From bf8eadbc85b05c78c99c0ae14fdc7f3058d960e4 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 10 Aug 2026 12:00:08 +0000
Subject: [PATCH 001/174] fix: portal cannot load last-mile confirmation
 request
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

LAST_MILE_REQUESTS URL constants were missing the /api prefix every other
endpoint in URLS.ts carries — all five calls (get, submit, contract
view/document/sign) 404'd against the deployed API, so the departure
notification's confirm link never loaded for the customer.

Also widen GET /last-mile-requests/:id from @BookingStaff to @MixedAudience
with the same ownership check submit()/sign() already use — the confirm
page calls this as its first request, before the customer has done
anything else, so it can't be staff-only.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../last-mile-requests.controller.ts             | 10 +++++++---
 .../last-mile-requests.service.ts                | 16 +++++++++++++++-
 .../edr-freight-web/portal/src/constants/URLS.ts | 10 +++++-----
 3 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.controller.ts b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.controller.ts
index c6910c7a7..3d9fa4254 100644
--- a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.controller.ts
+++ b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.controller.ts
@@ -91,11 +91,15 @@ export class LastMileRequestsController {
     return this.contractService.sign(id, dto, user?.id ?? null);
   }
 
+  // Customer-facing like :id/contract/view — the portal's confirm page opens
+  // this straight from the departure notification link before the customer
+  // has done anything else, so it can't be staff-only. Service ownership-
+  // checks against the resolved company; staff may also open it.
   @Get(':id')
-  @BookingStaff(FREIGHT_PERMS.lastMile.requestView)
+  @MixedAudience(FREIGHT_PERMS.lastMile.requestView)
   @ApiOperation({ summary: 'Get a last-mile confirmation request by ID' })
-  findOne(@Param('id', ParseUUIDPipe) id: string) {
-    return this.requestsService.findById(id);
+  findOne(@Param('id', ParseUUIDPipe) id: string, @CurrentUser() user: TCurrentUser) {
+    return this.requestsService.findById(id, user?.id ?? null);
   }
 
   // No @BookingStaff — the customer (portal) fills this, not backoffice staff.
diff --git a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.service.ts b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.service.ts
index b89f06479..ebdc93746 100644
--- a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.service.ts
+++ b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.service.ts
@@ -199,11 +199,25 @@ export class LastMileRequestsService {
     };
   }
 
-  async findById(id: string): Promise<LastMileRequest> {
+  /**
+   * `userId` is set only when a portal customer calls this directly (the
+   * confirm-page deep link from the departure notification, before they've
+   * submitted or signed anything) — staff and every internal caller pass
+   * nothing and skip the check, same convention as submit()/sign().
+   */
+  async findById(id: string, userId?: string | null): Promise<LastMileRequest> {
     const record = await this.requestsRepository.findById(id, {
       relations: { booking: { company: true } },
     });
     if (!record) throw new NotFoundException(`Last-mile request ${id} not found`);
+
+    if (userId) {
+      const companyId = await this.bookingsService.resolveCustomerCompanyId(userId);
+      if (companyId && record.booking?.companyId && companyId !== record.booking.companyId) {
+        throw new BadRequestException('This request does not belong to your company');
+      }
+    }
+
     return record;
   }
 
diff --git a/apps/edr-freight-web/portal/src/constants/URLS.ts b/apps/edr-freight-web/portal/src/constants/URLS.ts
index 153ed5e8b..a0d33f5ba 100644
--- a/apps/edr-freight-web/portal/src/constants/URLS.ts
+++ b/apps/edr-freight-web/portal/src/constants/URLS.ts
@@ -224,10 +224,10 @@ export const URL_CONSTANTS = {
   },
 
   LAST_MILE_REQUESTS: {
-    BY_ID: (id: string) => `/last-mile-requests/${id}`,
-    SUBMIT: (id: string) => `/last-mile-requests/${id}/submit`,
-    CONTRACT_VIEW: (id: string) => `/last-mile-requests/${id}/contract/view`,
-    CONTRACT_DOCUMENT: (id: string) => `/last-mile-requests/${id}/contract/document`,
-    CONTRACT_SIGN: (id: string) => `/last-mile-requests/${id}/contract/sign`,
+    BY_ID: (id: string) => `/api/last-mile-requests/${id}`,
+    SUBMIT: (id: string) => `/api/last-mile-requests/${id}/submit`,
+    CONTRACT_VIEW: (id: string) => `/api/last-mile-requests/${id}/contract/view`,
+    CONTRACT_DOCUMENT: (id: string) => `/api/last-mile-requests/${id}/contract/document`,
+    CONTRACT_SIGN: (id: string) => `/api/last-mile-requests/${id}/contract/sign`,
   },
 };

From 45715d68381fac5a6f841f40c110dba31a815461 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 10 Aug 2026 12:02:19 +0000
Subject: [PATCH 002/174] fix: default DataTable status to success so rows
 render

status was required with no default; omitting it left the body blank
while the footer (which renders regardless of status) still showed
"Showing 1-N of N". Rows to draw is the common case, so default to
success instead of requiring every caller to pass it explicitly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/ui-common/src/components/data-table/table.tsx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/ui-common/src/components/data-table/table.tsx b/packages/ui-common/src/components/data-table/table.tsx
index 957da3300..3dc2d5786 100644
--- a/packages/ui-common/src/components/data-table/table.tsx
+++ b/packages/ui-common/src/components/data-table/table.tsx
@@ -13,7 +13,10 @@ import { DataTableFooter } from "./footer";
 export function DataTable<TData, TValue>({
   columns,
   data,
-  status,
+  // The body only renders under "success", but the footer renders regardless —
+  // omitting status gave a blank table under a populated "Showing 1–N of N"
+  // footer. Having rows to draw is the default case, so default to success.
+  status = "success",
   onRowClick,
   rowStyle,
   rowClassName,

From 1b4a317d927aa6c01527560f9e2bb0f83f428b7c Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 10 Aug 2026 12:02:31 +0000
Subject: [PATCH 003/174] docs: trim eims.types.ts file header comment

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 apps/edr-freight-api/src/modules/eims/eims.types.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/eims/eims.types.ts b/apps/edr-freight-api/src/modules/eims/eims.types.ts
index 6e74604bd..8cea86619 100644
--- a/apps/edr-freight-api/src/modules/eims/eims.types.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims.types.ts
@@ -1,6 +1,5 @@
 /**
- * Wire types for the MoR EIMS gateway, taken from the supplied Postman collection.
- *
+ * Wire types for the MoR EIMS gateway,
  * Every protected payload is the same envelope: the business object under `request`, a base64
  * RSA-SHA512 signature over the *inner* object only, and the base64 certificate bundle.
  */

From b701ae3f470b669f149702e1175cf0e82378df85 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 10 Aug 2026 12:05:04 +0000
Subject: [PATCH 004/174] Revert "docs: trim eims.types.ts file header comment"

This reverts commit f4b8dab58d921791b4b3f69e3c9952b6802835cc.
---
 apps/edr-freight-api/src/modules/eims/eims.types.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/apps/edr-freight-api/src/modules/eims/eims.types.ts b/apps/edr-freight-api/src/modules/eims/eims.types.ts
index 8cea86619..6e74604bd 100644
--- a/apps/edr-freight-api/src/modules/eims/eims.types.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims.types.ts
@@ -1,5 +1,6 @@
 /**
- * Wire types for the MoR EIMS gateway,
+ * Wire types for the MoR EIMS gateway, taken from the supplied Postman collection.
+ *
  * Every protected payload is the same envelope: the business object under `request`, a base64
  * RSA-SHA512 signature over the *inner* object only, and the base64 certificate bundle.
  */

From c24c93bcf347ac2840ba396344ab7f4a1f5365af Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 10 Aug 2026 13:56:25 +0000
Subject: [PATCH 005/174] feat: add 11 digit vat

---
 .../modules/companies/dto/update-profile.dto.ts    | 10 +++++-----
 .../accounts/companyProfileForm/schema.test.ts     | 14 +++++++++++++-
 .../pages/accounts/companyProfileForm/schema.ts    |  2 +-
 .../companyProfileForm/steps/CompanyInfoStep.tsx   |  4 ++--
 .../src/pages/settings/TabCompanyProfile.tsx       |  4 ++--
 5 files changed, 23 insertions(+), 11 deletions(-)

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 214c3858a..c89326fa1 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
@@ -36,13 +36,13 @@ export class UpdateProfileDto {
   @IsTin({ message: "TIN must be exactly 10 digits" })
   tin?: string;
 
-  // Ethiopian VAT registration numbers are 10 digits, the same shape as the
-  // TIN. Both portal forms enforce that; without it here the API happily stored
-  // whatever a stale client sent, and the two layers disagreed about what the
-  // column may hold.
+  // Ethiopian VAT registration numbers are 10 digits (the same shape as the
+  // TIN), but some are issued with an 11th. Both portal forms enforce the same
+  // range; without it here the API happily stored whatever a stale client sent,
+  // and the two layers disagreed about what the column may hold.
   @IsOptional()
   @IsString()
-  @Matches(/^\d{10}$/, { message: "VAT number must be exactly 10 digits" })
+  @Matches(/^\d{10,11}$/, { message: "VAT number must be 10 or 11 digits" })
   vatNumber?: string;
 
   // `fanNumber` is deliberately absent: the FAN is the Fayda number of the
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
index f38d54432..0d357f691 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
@@ -59,10 +59,22 @@ describe("VAT number", () => {
     ).toBeUndefined();
   });
 
+  it("accepts eleven digits", () => {
+    expect(
+      errorFor(values({ vatNumber: "00123456789" }), "vatNumber"),
+    ).toBeUndefined();
+  });
+
+  it("rejects twelve digits", () => {
+    expect(errorFor(values({ vatNumber: "001234567890" }), "vatNumber")).toBe(
+      "VAT number must be 10 or 11 digits",
+    );
+  });
+
   // `.length(10)` used to pass this, so a ten-letter string reached the API.
   it("rejects ten non-digits", () => {
     expect(errorFor(values({ vatNumber: "ABCDEFGHIJ" }), "vatNumber")).toBe(
-      "VAT number must be exactly 10 digits",
+      "VAT number must be 10 or 11 digits",
     );
   });
 
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 37f92e05e..db48667db 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
@@ -25,7 +25,7 @@ export const onboardingSchema = z.object({
   vatNumber: z
     .string()
     .min(1, "VAT number is required")
-    .regex(/^\d{10}$/, "VAT number must be exactly 10 digits"),
+    .regex(/^\d{10,11}$/, "VAT number must be 10 or 11 digits"),
   // The owner's passport number — the foreign-company identity credential
   // (Fayda is an Ethiopian national ID). Required only for a foreign company;
   // enforced in buildOnboardingSchema since that depends on `nationality`.
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
index 3f37506a4..978377151 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
@@ -51,7 +51,7 @@ export default function CompanyInfoStep({
         index={1}
         title="VAT number"
         status={
-          watch("vatNumber")?.length === 10 && !errors.vatNumber
+          (watch("vatNumber")?.length ?? 0) >= 10 && !errors.vatNumber
             ? "done"
             : "todo"
         }
@@ -59,7 +59,7 @@ export default function CompanyInfoStep({
         <TextInput
           aria-label="VAT Number"
           placeholder="0012345678"
-          maxLength={10}
+          maxLength={11}
           error={errors.vatNumber?.message}
           {...register("vatNumber")}
         />
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 6a315392c..deaec110f 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabCompanyProfile.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabCompanyProfile.tsx
@@ -46,7 +46,7 @@ export const COMPANY_PROFILE_SCHEMA = z.object({
   vatNumber: z
     .string()
     .min(1, "VAT number is required")
-    .regex(/^\d{10}$/, "VAT number must be exactly 10 digits"),
+    .regex(/^\d{10,11}$/, "VAT number must be 10 or 11 digits"),
   ownerPassportNumber: z.string().optional(),
   // Registration/address fields are eTrade-sourced — locked once eTrade
   // supplies a value, editable only as an escape hatch when it doesn't
@@ -332,7 +332,7 @@ export default function TabCompanyProfile({
                 <TextInput
                   label="VAT Number"
                   placeholder="e.g. 0012345678"
-                  maxLength={10}
+                  maxLength={11}
                   error={errors.vatNumber?.message}
                   {...register("vatNumber")}
                 />

From e29e3ff8371b692f36e634702b7f0750c49b6c94 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 10 Aug 2026 14:02:13 +0000
Subject: [PATCH 006/174] fix(freight-backoffice): render wagon transfer reason
 as sanitized HTML in a modal

---
 .../modules/trains/train-builder.service.ts   | 16 ++++-
 .../src/pages/fleet/FleetResourcePage.tsx     | 18 +++++-
 .../src/pages/fleet/config/resources.ts       |  9 ++-
 .../src/pages/wagons/TransferHistoryPanel.tsx |  5 +-
 .../src/pages/wagons/WagonTransfersPage.tsx   | 61 +++++++++++++++++--
 .../src/pages/wagons/wagon-transfer-ui.tsx    | 10 +++
 6 files changed, 108 insertions(+), 11 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/trains/train-builder.service.ts b/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
index fbb5301fb..9da3cecf0 100644
--- a/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
+++ b/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
@@ -510,6 +510,8 @@ export class TrainBuilderService {
         trainId: null,
         sequenceNumber: null,
         status: WagonStatus.Available,
+        importTrainNumber: null,
+        exportTrainNumber: null,
       });
       await this.resequenceWagons(manager, train.id);
       await this.syncLiveScheduleAfterConsistChange(
@@ -544,6 +546,8 @@ export class TrainBuilderService {
         trainId: null,
         sequenceNumber: null,
         status: WagonStatus.Maintenance,
+        importTrainNumber: null,
+        exportTrainNumber: null,
       });
       // Audit row: which train it came off and when. The wagon does not change
       // yard here, so from/to are the same — the ledger is the wagon's history
@@ -761,7 +765,13 @@ export class TrainBuilderService {
         .getRepository(Wagon)
         .update(
           { trainId: train.id },
-          { trainId: null, sequenceNumber: null, status: WagonStatus.Available },
+          {
+            trainId: null,
+            sequenceNumber: null,
+            status: WagonStatus.Available,
+            importTrainNumber: null,
+            exportTrainNumber: null,
+          },
         );
       await manager.getRepository(TrainLocomotive).delete({ trainId: train.id });
       await manager.getRepository(Train).remove(train);
@@ -1021,6 +1031,10 @@ export class TrainBuilderService {
         trainId: train.id,
         sequenceNumber: sequence,
         status: WagonStatus.Assigned,
+        // Wagon inherits the train's run numbers on coupling — no per-wagon
+        // number entry, they ride whatever numbers the train was built with.
+        importTrainNumber: train.importTrainNumber,
+        exportTrainNumber: train.exportTrainNumber,
       });
     }
     return toAttach;
diff --git a/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx b/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
index 6bea10a8c..06d9a20ab 100644
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
@@ -102,6 +102,7 @@ const FleetResourcePage = () => {
     const currentYardId = listFilterValues.currentYardId;
     const availability = listFilterValues.availability;
     const trainNumber = listFilterValues.trainNumber;
+    const trainId = listFilterValues.trainId;
     if (status && status !== "ALL") {
       (filters as { status?: string }).status = status;
     }
@@ -114,6 +115,9 @@ const FleetResourcePage = () => {
     if (trainNumber && trainNumber !== "ALL") {
       (filters as { trainNumber?: string }).trainNumber = trainNumber;
     }
+    if (trainId && trainId !== "ALL") {
+      filters.trainId = trainId;
+    }
     // Wagons only: narrow the fleet to one wagon type (the API filters on it).
     const wagonTypeId = listFilterValues.wagonTypeId;
     if (wagonTypeId && wagonTypeId !== "ALL") {
@@ -191,6 +195,11 @@ const FleetResourcePage = () => {
   const { data: drivers = [] } = useQuery(
     api.fleet.list.queryOptions({ input: { slug: "drivers" } }),
   );
+  // Wagons-only: "Train" list filter needs every train's code to pick from.
+  const { data: trains = [], isLoading: trainsLoading } = useQuery({
+    ...api.trains.list.queryOptions(),
+    enabled: slug === "wagons",
+  });
 
   useEffect(() => {
     setPagination((prev) => ({ pageIndex: 0, pageSize: prev.pageSize }));
@@ -247,6 +256,9 @@ const FleetResourcePage = () => {
     const yardOpts = (yards as Array<{ id: string; label?: string; code?: string }>).map(
       (y) => ({ value: y.id, label: y.label ?? y.code ?? y.id }),
     );
+    const trainOpts = (trains as Array<{ id: string; code: string; trainName?: string | null }>).map(
+      (t) => ({ value: t.id, label: t.trainName ? `${t.code} - ${t.trainName}` : t.code }),
+    );
 
     // Carries capacity + trailer configuration so picking a truck type can
     // pre-fill the vehicle's capacity and drop the trailer plate on a rigid type.
@@ -274,8 +286,9 @@ const FleetResourcePage = () => {
       wagons: [{ label: "Unassigned", value: FLEET_SELECT_NONE }, ...wagonOpts],
       containers: containerOpts,
       yards: yardOpts,
+      trains: trainOpts,
     };
-  }, [wagonTypes, containerTypes, cargoTypes, truckTypes, wagons, containers, yards]);
+  }, [wagonTypes, containerTypes, cargoTypes, truckTypes, wagons, containers, yards, trains]);
 
   const listFilterSelects = useMemo(() => {
     if (!config?.listFilters?.length) return null;
@@ -327,7 +340,8 @@ const FleetResourcePage = () => {
     truckTypesLoading ||
     wagonsLoading ||
     containersLoading ||
-    yardsLoading;
+    yardsLoading ||
+    trainsLoading;
 
   const filteredRows = useMemo(() => {
     if (!config) return allRows;
diff --git a/apps/edr-freight-web/backoffice/src/pages/fleet/config/resources.ts b/apps/edr-freight-web/backoffice/src/pages/fleet/config/resources.ts
index 9ba826e6f..11ca236be 100644
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/config/resources.ts
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/config/resources.ts
@@ -33,7 +33,8 @@ export type FleetDynamicOptions =
   | "truckTypes"
   | "wagons"
   | "containers"
-  | "yards";
+  | "yards"
+  | "trains";
 
 /**
  * A dynamic select option that can carry the record it came from. Picking a
@@ -324,6 +325,12 @@ export const FLEET_RESOURCES: FleetResourceConfig[] = [
         allLabel: "All trains",
         options: TRAIN_RUN_FILTER_OPTIONS,
       },
+      {
+        key: "trainId",
+        label: "Train",
+        allLabel: "All trains",
+        dynamicOptions: "trains",
+      },
     ],
     cardTitleKey: "wagonNumber",
     cardSubtitleKey: "currentYard",
diff --git a/apps/edr-freight-web/backoffice/src/pages/wagons/TransferHistoryPanel.tsx b/apps/edr-freight-web/backoffice/src/pages/wagons/TransferHistoryPanel.tsx
index dff9cdaa3..807745b73 100644
--- a/apps/edr-freight-web/backoffice/src/pages/wagons/TransferHistoryPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/wagons/TransferHistoryPanel.tsx
@@ -35,6 +35,7 @@ import {
   STATUS_META,
   TransferProgress,
   TransferStatusBadge,
+  stripHtmlToText,
   wagonTypeLabel,
   yardLabel,
 } from "./wagon-transfer-ui";
@@ -119,9 +120,9 @@ function RequestItem({ request }: { request: WagonTransferRequest }) {
               {wagonTypeLabel(request.wagonType)}
             </Badge>
           </Group>
-          {request.reason ? (
+          {stripHtmlToText(request.reason) ? (
             <Text size="xs" c="dimmed" lineClamp={1}>
-              {request.reason}
+              {stripHtmlToText(request.reason)}
             </Text>
           ) : null}
         </Stack>
diff --git a/apps/edr-freight-web/backoffice/src/pages/wagons/WagonTransfersPage.tsx b/apps/edr-freight-web/backoffice/src/pages/wagons/WagonTransfersPage.tsx
index 95705e964..1a08b5c54 100644
--- a/apps/edr-freight-web/backoffice/src/pages/wagons/WagonTransfersPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/wagons/WagonTransfersPage.tsx
@@ -10,6 +10,7 @@ import {
   Tabs,
   Text,
   TextInput,
+  UnstyledButton,
 } from "@mantine/core";
 import { useDebouncedValue } from "@mantine/hooks";
 import { useQuery } from "@tanstack/react-query";
@@ -31,6 +32,7 @@ import { useMutation } from "@tanstack/react-query";
 import { useAuth } from "@/auth/useAuth";
 import { KpiStrip, PageContainer, PageHeader } from "@/components/page";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
+import { sanitizeHtml } from "@/shared/lib/sanitize";
 import { api } from "@/services/api";
 import type {
   TransferRequestListFilter,
@@ -55,6 +57,7 @@ import {
   fmtDateTime,
   isOpenRequest,
   outstandingOn,
+  stripHtmlToText,
   wagonTypeLabel,
   yardLabel,
 } from "./wagon-transfer-ui";
@@ -108,6 +111,9 @@ export default function WagonTransfersPage() {
   const [closingShort, setClosingShort] = useState<WagonTransferRequest | null>(
     null,
   );
+  const [viewingReason, setViewingReason] = useState<WagonTransferRequest | null>(
+    null,
+  );
 
   const filter: TransferRequestListFilter = useMemo(
     () => ({
@@ -197,11 +203,29 @@ export default function WagonTransfersPage() {
     {
       id: "reason",
       header: () => <span>Reason</span>,
-      cell: ({ row }) => (
-        <Text size="sm" c="dimmed" lineClamp={2} maw={260}>
-          {row.original.reason || "—"}
-        </Text>
-      ),
+      cell: ({ row }) => {
+        const text = stripHtmlToText(row.original.reason);
+        return text ? (
+          <UnstyledButton
+            onClick={() => setViewingReason(row.original)}
+            data-stop-row-click
+          >
+            <Text
+              size="sm"
+              c="dimmed"
+              lineClamp={2}
+              maw={260}
+              style={{ textAlign: "left", textDecoration: "underline dotted" }}
+            >
+              {text}
+            </Text>
+          </UnstyledButton>
+        ) : (
+          <Text size="sm" c="dimmed">
+            —
+          </Text>
+        );
+      },
     },
     {
       id: "filed",
@@ -522,6 +546,33 @@ export default function WagonTransfersPage() {
           </Stack>
         )}
       </Modal>
+      <Modal
+        opened={Boolean(viewingReason)}
+        onClose={() => setViewingReason(null)}
+        radius="md"
+        title="Reason"
+      >
+        {!viewingReason ? null : (
+          <Stack gap="sm">
+            <Text size="sm" fw={600}>
+              {yardLabel(viewingReason.fromYard)}{" "}
+              <ArrowRight
+                size={13}
+                className="inline-block opacity-60"
+              />{" "}
+              {yardLabel(viewingReason.toYard)} ·{" "}
+              {wagonTypeLabel(viewingReason.wagonType)} ·{" "}
+              {viewingReason.quantity} wagon(s)
+            </Text>
+            <Box
+              className="text-sm [&_p]:my-2 [&_ol]:list-decimal [&_ul]:list-disc [&_ol]:pl-5 [&_ul]:pl-5"
+              dangerouslySetInnerHTML={{
+                __html: sanitizeHtml(viewingReason.reason ?? ""),
+              }}
+            />
+          </Stack>
+        )}
+      </Modal>
     </PageContainer>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/wagons/wagon-transfer-ui.tsx b/apps/edr-freight-web/backoffice/src/pages/wagons/wagon-transfer-ui.tsx
index e60480590..ea73a95d2 100644
--- a/apps/edr-freight-web/backoffice/src/pages/wagons/wagon-transfer-ui.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/wagons/wagon-transfer-ui.tsx
@@ -3,6 +3,16 @@ import { Badge, Box, Group, Progress, Text, Tooltip } from "@mantine/core";
 
 import type { WagonTransferRequest } from "@/services/wagon.service";
 
+/** Reason/note fields come from a rich-text editor and store HTML — this
+ * gives a plain-text preview for list/table contexts (full formatting is
+ * shown via `sanitizeHtml` + `dangerouslySetInnerHTML` where there's room). */
+export const stripHtmlToText = (html?: string | null): string =>
+  (html ?? "")
+    .replace(/<[^>]*>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+
 export const yardLabel = (y?: { label?: string; code?: string } | null) =>
   y?.label || y?.code || "—";
 

From 615f7e679818d288c3a89208a1e81e61ea1d3f42 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 10 Aug 2026 14:49:17 +0000
Subject: [PATCH 007/174] feat: add choice to etrade fetcher

---
 .../modules/companies/companies.controller.ts |   1 +
 .../modules/companies/companies.service.ts    |  22 ++-
 .../companies/dto/etrade-response.dto.ts      |   4 +-
 .../modules/companies/dto/fetch-etrade.dto.ts |  12 +-
 .../etrade-business-selection.spec.ts         |  87 +++++++++
 .../companies/services/etrade.service.ts      |  29 ++-
 .../src/modules/payment/payments.dto.ts       |  11 +-
 .../src/components/onboarding/ETradeInfo.tsx  | 184 ++++++++++++++++--
 .../portal/src/hooks/useETradeData.ts         |  11 +-
 .../src/pages/accounts/CompanyProfileForm.tsx |   4 +-
 .../companyProfileForm/ETradeCompanyCard.tsx  | 126 ++----------
 .../accounts/companyProfileForm/helpers.ts    |   7 +-
 .../companyProfileForm/schema.test.ts         |  23 ++-
 .../accounts/companyProfileForm/schema.ts     |  46 ++---
 .../steps/CompanyInfoStep.tsx                 |  10 +-
 .../src/pages/settings/TabCompanyProfile.tsx  | 168 +++-------------
 .../portal/src/services/companies.service.ts  |   5 +-
 packages/types/src/freight/etrade.ts          |  23 ++-
 18 files changed, 443 insertions(+), 330 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/companies/services/etrade-business-selection.spec.ts

diff --git a/apps/edr-freight-api/src/modules/companies/companies.controller.ts b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
index 78f8db410..de7a01484 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.controller.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
@@ -210,6 +210,7 @@ export class CompaniesController {
     const data = await this.companiesService.fetchETradeData(
       dto.tin,
       companyId,
+      dto.licenceNumber,
     );
     return new ETradeResponseDto(data);
   }
diff --git a/apps/edr-freight-api/src/modules/companies/companies.service.ts b/apps/edr-freight-api/src/modules/companies/companies.service.ts
index 0ed91c9e3..5dd55e704 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.service.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.service.ts
@@ -3541,9 +3541,10 @@ export class CompaniesService {
   /** Resolve a TIN's live eTrade registration data. Throws when eTrade has no matching business licence. */
   private async resolveEtradeRegistration(
     tin: string,
+    licenceNumber?: string,
   ): Promise<CompanyRegistrationData> {
     const { businessInfo, companyInfo } =
-      await this.etradeService.resolveCompanyData(tin);
+      await this.etradeService.resolveCompanyData(tin, licenceNumber);
     if (!businessInfo) {
       throw new BadRequestException(
         "We couldn't find a business license for this TIN with eTrade. Please double-check the number and try again.",
@@ -3555,8 +3556,15 @@ export class CompaniesService {
     );
   }
 
-  async fetchETradeData(tin: string, excludeCompanyId?: string) {
-    const registrationData = await this.resolveEtradeRegistration(tin);
+  async fetchETradeData(
+    tin: string,
+    excludeCompanyId?: string,
+    licenceNumber?: string,
+  ) {
+    const registrationData = await this.resolveEtradeRegistration(
+      tin,
+      licenceNumber,
+    );
     const tinTaken = await this.companiesRepo.existsByTin(
       tin,
       excludeCompanyId,
@@ -3583,7 +3591,13 @@ export class CompaniesService {
     if (!touched) return;
 
     const tin = dto.tin ?? company.tin;
-    const registration = await this.resolveEtradeRegistration(tin);
+    // Re-verify the licence the customer actually chose. Without it a TIN
+    // holding several licences would silently snap back to eTrade's first one on
+    // every save, overwriting the selection with a different business's record.
+    const registration = await this.resolveEtradeRegistration(
+      tin,
+      dto.licenceNumber ?? company.licenceNumber ?? undefined,
+    );
     const fresh: Partial<
       Record<(typeof ETRADE_SOURCED_FIELDS)[number], string>
     > = {
diff --git a/apps/edr-freight-api/src/modules/companies/dto/etrade-response.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/etrade-response.dto.ts
index bfe1f9b72..40b1f308e 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/etrade-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/etrade-response.dto.ts
@@ -1,4 +1,4 @@
-import { CompanyRegistrationData } from "@edr/types";
+import { CompanyRegistrationData, ETradeBusinessOption } from "@edr/types";
 
 export class ETradeResponseDto implements CompanyRegistrationData {
   companyName!: string;
@@ -19,6 +19,7 @@ export class ETradeResponseDto implements CompanyRegistrationData {
   managerEmail?: string;
   managerPhone!: string;
   tinTaken?: boolean;
+  businesses?: ETradeBusinessOption[];
 
   constructor(data: CompanyRegistrationData) {
     this.companyName = data.companyName;
@@ -39,5 +40,6 @@ export class ETradeResponseDto implements CompanyRegistrationData {
     this.managerEmail = data.managerEmail;
     this.managerPhone = data.managerPhone;
     this.tinTaken = data.tinTaken;
+    this.businesses = data.businesses;
   }
 }
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 466c03ed6..9ca533835 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,4 +1,4 @@
-import { IsString, IsNotEmpty } from "class-validator";
+import { IsString, IsNotEmpty, IsOptional, MaxLength } from "class-validator";
 import { IsTin } from "../../../common/validators/is-tin.validator";
 
 export class FetchETradeDto {
@@ -6,4 +6,14 @@ export class FetchETradeDto {
   @IsNotEmpty()
   @IsTin({ message: "TIN must be exactly 10 digits" })
   tin!: string;
+
+  /**
+   * Which of the TIN's business licences to resolve. Omitted on the first
+   * lookup — the response lists them all so the customer can pick, and the pick
+   * comes back here.
+   */
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  licenceNumber?: string;
 }
diff --git a/apps/edr-freight-api/src/modules/companies/services/etrade-business-selection.spec.ts b/apps/edr-freight-api/src/modules/companies/services/etrade-business-selection.spec.ts
new file mode 100644
index 000000000..0719d7fe8
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/companies/services/etrade-business-selection.spec.ts
@@ -0,0 +1,87 @@
+import { ETradeService } from './etrade.service';
+import type { ETradeBusinessInfo, ETradeCompanyInfo } from '@edr/types';
+
+/**
+ * A TIN routinely holds several business licences (import of vehicles, export of
+ * coffee, freight forwarding…), all under the same trade name. The customer
+ * picks one, and every later lookup has to resolve that same licence — snapping
+ * back to eTrade's first would silently swap their company record.
+ */
+const companyInfo = (): ETradeCompanyInfo =>
+  ({
+    Tin: '0045014036',
+    BusinessName: 'PAVE LOGISTICS AND TRADING P L C',
+    Businesses: [
+      {
+        LicenceNumber: 'MT/AA/14/670/11551235/2017',
+        TradesName: 'PAVE LOGISTICS AND TRADING P L C',
+        RenewedTo: '7/7/2026',
+        SubGroups: [
+          { Code: 66331, Description: 'Export trade in minerals' },
+        ],
+      },
+      {
+        LicenceNumber: 'MT/AA/14/670/128936/2007',
+        TradesName: 'PAVE LOGISTICS AND TRADING P L C',
+        RenewedTo: '7/7/2026',
+        SubGroups: [{ Code: 72131, Description: '(72131)Freight Forwarders' }],
+      },
+    ],
+  }) as unknown as ETradeCompanyInfo;
+
+describe('ETradeService business selection', () => {
+  const build = () => {
+    const service = new ETradeService({} as never);
+    const fetched: string[] = [];
+    jest
+      .spyOn(service, 'getCompanyInfoByTin')
+      .mockResolvedValue(companyInfo());
+    jest
+      .spyOn(service, 'getBusinessByLicenseNo')
+      .mockImplementation(async (licenceNo: string) => {
+        fetched.push(licenceNo);
+        return { LicenceNumber: licenceNo } as ETradeBusinessInfo;
+      });
+    return { service, fetched };
+  };
+
+  it('defaults to the first licence when none is chosen', async () => {
+    const { service, fetched } = build();
+    await service.resolveCompanyData('0045014036');
+    expect(fetched).toEqual(['MT/AA/14/670/11551235/2017']);
+  });
+
+  it('resolves the chosen licence', async () => {
+    const { service, fetched } = build();
+    await service.resolveCompanyData('0045014036', 'MT/AA/14/670/128936/2007');
+    expect(fetched).toEqual(['MT/AA/14/670/128936/2007']);
+  });
+
+  it('falls back to the first licence when the chosen one is gone', async () => {
+    const { service, fetched } = build();
+    await service.resolveCompanyData('0045014036', 'NO/SUCH/LICENCE');
+    expect(fetched).toEqual(['MT/AA/14/670/11551235/2017']);
+  });
+
+  it('lists every licence for the picker, code prefixes stripped', () => {
+    const { service } = build();
+    const data = service.extractRegistrationData(
+      { LicenceNumber: 'x' } as ETradeBusinessInfo,
+      companyInfo(),
+    );
+    expect(data.businesses).toEqual([
+      {
+        licenceNumber: 'MT/AA/14/670/11551235/2017',
+        tradeName: 'PAVE LOGISTICS AND TRADING P L C',
+        activity: 'Export trade in minerals',
+        renewedTo: '7/7/2026',
+      },
+      {
+        licenceNumber: 'MT/AA/14/670/128936/2007',
+        tradeName: 'PAVE LOGISTICS AND TRADING P L C',
+        activity: 'Freight Forwarders',
+        renewedTo: '7/7/2026',
+      },
+    ]);
+  });
+});
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 3292ee2d3..45cc8e840 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
@@ -66,7 +66,15 @@ export class ETradeService {
     }
   }
 
-  async resolveCompanyData(tin: string): Promise<{
+  /**
+   * @param licenceNumber which of the TIN's licences to resolve. Defaults to the
+   * first one — a TIN with several licences is only unambiguous once the
+   * customer has picked one (see {@link ETradeBusinessOption}).
+   */
+  async resolveCompanyData(
+    tin: string,
+    licenceNumber?: string,
+  ): Promise<{
     companyInfo: ETradeCompanyInfo;
     businessInfo: ETradeBusinessInfo | null;
   }> {
@@ -76,10 +84,15 @@ export class ETradeService {
       return { companyInfo, businessInfo: null };
     }
 
-    const latestBusiness = companyInfo.Businesses[0];
+    // An unknown licence falls back to the first rather than 400-ing: eTrade can
+    // drop or renumber a licence between the customer picking it and the save
+    // that re-verifies it, and that must not lock them out of their own profile.
+    const selected =
+      companyInfo.Businesses.find((b) => b.LicenceNumber === licenceNumber) ??
+      companyInfo.Businesses[0];
     try {
       const businessInfo = await this.getBusinessByLicenseNo(
-        latestBusiness.LicenceNumber,
+        selected.LicenceNumber,
         tin,
       );
       return { companyInfo, businessInfo };
@@ -124,6 +137,16 @@ export class ETradeService {
       regularPhone: businessInfo.AddressInfo?.RegularPhone || "",
       managerName: primaryManager?.ManagerNameEng || "",
       managerPhone: primaryManager?.RegularPhone || "",
+      businesses: (companyInfo?.Businesses ?? []).map((b) => ({
+        licenceNumber: b.LicenceNumber,
+        tradeName: b.TradesName?.trim() || "",
+        activity: (b.SubGroups ?? [])
+          // Some descriptions repeat the code inline ("(65611)Import trade …").
+          .map((g) => g.Description?.replace(/^\(\d+\)\s*/, "").trim())
+          .filter(Boolean)
+          .join(", "),
+        renewedTo: b.RenewedTo || "",
+      })),
     };
   }
 }
diff --git a/apps/edr-freight-api/src/modules/payment/payments.dto.ts b/apps/edr-freight-api/src/modules/payment/payments.dto.ts
index ee7b703d2..92ff7dc38 100644
--- a/apps/edr-freight-api/src/modules/payment/payments.dto.ts
+++ b/apps/edr-freight-api/src/modules/payment/payments.dto.ts
@@ -69,6 +69,7 @@ export class ClientActionDto {
       "LAUNCH_APP",
       "INVOKE_BRIDGE",
       "COLLECT_OTP",
+      "AWAIT_PUSH",
       "SHOW_BILL_REFERENCE",
     ],
   })
@@ -77,6 +78,7 @@ export class ClientActionDto {
     | "LAUNCH_APP"
     | "INVOKE_BRIDGE"
     | "COLLECT_OTP"
+    | "AWAIT_PUSH"
     | "SHOW_BILL_REFERENCE";
 
   @ApiPropertyOptional({ description: "Set when type=REDIRECT (web flow)" })
@@ -104,9 +106,16 @@ export class ClientActionDto {
   @ApiPropertyOptional({ description: "Set when type=COLLECT_OTP (e.g. CAC Bank)" })
   providerOrderId?: string;
 
-  @ApiPropertyOptional({ description: "Set when type=COLLECT_OTP" })
+  @ApiPropertyOptional({
+    description: "Set when type=COLLECT_OTP or type=AWAIT_PUSH",
+  })
   message?: string;
 
+  @ApiPropertyOptional({
+    description: "Set when type=AWAIT_PUSH (masked MSISDN the push prompt went to)",
+  })
+  payerAccountMasked?: string;
+
   @ApiPropertyOptional({
     description: "Set when type=SHOW_BILL_REFERENCE (CBE bill payment)",
   })
diff --git a/apps/edr-freight-web/portal/src/components/onboarding/ETradeInfo.tsx b/apps/edr-freight-web/portal/src/components/onboarding/ETradeInfo.tsx
index 74e267a30..56273351d 100644
--- a/apps/edr-freight-web/portal/src/components/onboarding/ETradeInfo.tsx
+++ b/apps/edr-freight-web/portal/src/components/onboarding/ETradeInfo.tsx
@@ -1,7 +1,17 @@
-import { Alert, Button, Loader, Stack, TextInput } from "@mantine/core";
-import { useEffect, useRef } from "react";
+import {
+  Alert,
+  Button,
+  Card,
+  Group,
+  Loader,
+  Radio,
+  Stack,
+  Text,
+  TextInput,
+} from "@mantine/core";
+import { useEffect, useRef, useState } from "react";
 import type { UseFormRegisterReturn } from "react-hook-form";
-import { AlertCircle, Download } from "lucide-react";
+import { AlertCircle, Building2, Download } from "lucide-react";
 import { useETradeData } from "@/hooks/useETradeData";
 import { extractApiError } from "@/utils/result";
 import type { CompanyRegistrationData } from "@edr/types";
@@ -12,6 +22,8 @@ export type ETradeStatus =
   | "verified"
   | "not-found"
   | "taken"
+  /** eTrade returned several business licences; the customer must pick one. */
+  | "choose-business"
   | "error";
 
 interface ETradeInfoProps {
@@ -36,6 +48,12 @@ interface ETradeInfoProps {
    * stays available for a deliberate re-verify.
    */
   alreadyVerified?: boolean;
+  /**
+   * The licence this company already operates under, if any. Pre-selects it in
+   * the picker so a deliberate re-verify refreshes that same business rather
+   * than silently snapping to eTrade's first one.
+   */
+  selectedLicenceNumber?: string;
 }
 
 // Digits, not just length: a 10-character non-numeric TIN used to fire a lookup
@@ -51,6 +69,7 @@ export default function ETradeInfo({
   onStatusChange,
   onReset,
   alreadyVerified,
+  selectedLicenceNumber,
 }: ETradeInfoProps) {
   const mutation = useETradeData();
   const isLoading = mutation.isPending;
@@ -61,14 +80,39 @@ export default function ETradeInfo({
   // user has typed a different TIN and overwrite its fields with stale data.
   const requestIdRef = useRef(0);
 
-  const handleFetch = async () => {
+  // Which of the TIN's licences the customer operates as. A ref alongside the
+  // state because handleFetch is called from an effect that doesn't re-run on
+  // this value.
+  const [licence, setLicence] = useState<string | null>(
+    selectedLicenceNumber || null,
+  );
+  const licenceRef = useRef(licence);
+  licenceRef.current = licence;
+
+  const handleFetch = async (chosen = licenceRef.current) => {
     if (!isValidTin(tin)) return;
     const requestId = ++requestIdRef.current;
-    const result = await mutation.mutateAsync(tin);
+    const result = await mutation.mutateAsync({
+      tin,
+      licenceNumber: chosen ?? undefined,
+    });
     if (requestIdRef.current !== requestId) return;
-    if (result && !result.tinTaken) {
-      onDataLoaded(result);
-    }
+    if (!result || result.tinTaken) return;
+    // Several licences and no pick yet: the registration data describes only
+    // eTrade's first one, so it must not be adopted as this company's record
+    // until the customer says which business they're acting as.
+    if (!chosen && (result.businesses?.length ?? 0) > 1) return;
+    onDataLoaded(result);
+  };
+
+  // The picker collapses to a one-line summary + "Change" once a business is
+  // settled on; it only stays open while the choice is still outstanding.
+  const [pickerOpen, setPickerOpen] = useState(false);
+
+  const handleChooseBusiness = (value: string) => {
+    setLicence(value);
+    setPickerOpen(false);
+    handleFetch(value);
   };
 
   // Auto-fetch as soon as the TIN reaches its full 10-digit length — only
@@ -87,8 +131,12 @@ export default function ETradeInfo({
     if (tin !== lastFetchedTin.current) {
       // TIN moved away from whatever we last fetched — that result (verified
       // data, "taken", or an error) no longer describes this TIN. Drop it so
-      // the UI doesn't keep showing the previous TIN's outcome.
+      // the UI doesn't keep showing the previous TIN's outcome. The licence pick
+      // belongs to the old TIN too, so it goes with it (via the ref as well, so
+      // the fetch below doesn't reuse it before the state lands).
       requestIdRef.current++;
+      licenceRef.current = null;
+      setLicence(null);
       if (mutation.data || mutation.error) {
         mutation.reset();
         onReset?.();
@@ -116,17 +164,28 @@ export default function ETradeInfo({
         : apiError.message
       : null;
 
+  const businesses = mutation.data?.businesses ?? [];
+  const chosenBusiness = businesses.find((b) => b.licenceNumber === licence);
+  // More than one licence and none of them picked: the lookup succeeded but
+  // this company's record is still undecided, so it must not read as verified.
+  // Matched against the list rather than `licence` alone — a saved licence
+  // eTrade no longer lists is not a choice among what it offers today.
+  const needsChoice = businesses.length > 1 && !chosenBusiness;
+  const showPicker = needsChoice || pickerOpen;
+
   const status: ETradeStatus = isLoading
     ? "loading"
     : tinTaken
       ? "taken"
-      : mutation.isSuccess && mutation.data && !mutation.data.tinTaken
-        ? "verified"
-        : notFound
-          ? "not-found"
-          : errorMessage
-            ? "error"
-            : "idle";
+      : needsChoice
+        ? "choose-business"
+        : mutation.isSuccess && mutation.data && !mutation.data.tinTaken
+          ? "verified"
+          : notFound
+            ? "not-found"
+            : errorMessage
+              ? "error"
+              : "idle";
 
   const lastReportedStatus = useRef<ETradeStatus | null>(null);
   useEffect(() => {
@@ -142,7 +201,11 @@ export default function ETradeInfo({
   const willAutoFetch = isValidTin(tin) && lastFetchedTin.current !== tin;
   const showLoading = isLoading || willAutoFetch;
 
-  const showRetry = isValidTin(tin) && status !== "verified" && !showLoading;
+  const showRetry =
+    isValidTin(tin) &&
+    status !== "verified" &&
+    status !== "choose-business" &&
+    !showLoading;
 
   return (
     <Stack gap="md">
@@ -170,7 +233,7 @@ export default function ETradeInfo({
             className="max-w-none"
             variant="filled"
             color="edr-green"
-            onClick={handleFetch}
+            onClick={() => handleFetch()}
             disabled={!isValidTin(tin)}
             leftSection={<Download size={16} />}
           >
@@ -179,6 +242,91 @@ export default function ETradeInfo({
         )}
       </div>
 
+      {businesses.length > 1 && !showPicker && chosenBusiness && (
+        <Card padding="sm" radius="md" withBorder>
+          <Group justify="space-between" wrap="nowrap" gap="sm">
+            <Group gap="sm" wrap="nowrap">
+              <Building2 size={18} className="shrink-0 text-edr-muted" />
+              <Stack gap={2}>
+                <Text fw={600} size="sm">
+                  {chosenBusiness.activity ||
+                    chosenBusiness.tradeName ||
+                    chosenBusiness.licenceNumber}
+                </Text>
+                <Group gap="xs">
+                  <Text size="xs" c="edr-muted" ff="monospace">
+                    {chosenBusiness.licenceNumber}
+                  </Text>
+                  {chosenBusiness.renewedTo && (
+                    <Text size="xs" c="edr-muted">
+                      · valid to {chosenBusiness.renewedTo}
+                    </Text>
+                  )}
+                </Group>
+              </Stack>
+            </Group>
+            <Button
+              size="xs"
+              variant="subtle"
+              onClick={() => setPickerOpen(true)}
+              disabled={isLoading}
+            >
+              Change
+            </Button>
+          </Group>
+        </Card>
+      )}
+
+      {businesses.length > 1 && showPicker && (
+        <Stack gap="sm">
+          <Alert
+            icon={<Building2 size={16} />}
+            color={needsChoice ? "yellow" : "blue"}
+            title={
+              needsChoice
+                ? `This TIN holds ${businesses.length} business licences`
+                : "Change business"
+            }
+          >
+            Pick the business you're registering as — its licence and registered
+            address become this account's record.
+          </Alert>
+          <Radio.Group
+            value={licence}
+            onChange={handleChooseBusiness}
+            aria-label="Business licence"
+          >
+            <Stack gap="xs">
+              {businesses.map((b) => (
+                <Card key={b.licenceNumber} padding="sm" radius="md" withBorder>
+                  <Radio
+                    value={b.licenceNumber}
+                    disabled={isLoading}
+                    label={
+                      <Stack gap={2}>
+                        <Text fw={600} size="sm">
+                          {b.activity || b.tradeName || b.licenceNumber}
+                        </Text>
+                        <Group gap="xs">
+                          <Text size="xs" c="edr-muted" ff="monospace">
+                            {b.licenceNumber}
+                          </Text>
+                          {b.renewedTo && (
+                            <Text size="xs" c="edr-muted">
+                              · valid to {b.renewedTo}
+                            </Text>
+                          )}
+                        </Group>
+                      </Stack>
+                    }
+                  />
+                </Card>
+              ))}
+            </Stack>
+          </Radio.Group>
+        </Stack>
+      )}
+
       {notFound && (
         <Alert
           icon={<AlertCircle size={16} />}
diff --git a/apps/edr-freight-web/portal/src/hooks/useETradeData.ts b/apps/edr-freight-web/portal/src/hooks/useETradeData.ts
index 9fbce53d9..e764ecad5 100644
--- a/apps/edr-freight-web/portal/src/hooks/useETradeData.ts
+++ b/apps/edr-freight-web/portal/src/hooks/useETradeData.ts
@@ -3,10 +3,17 @@ import { companiesService } from "@/services/companies.service";
 import { extractApiError } from "@/utils/result";
 import type { CompanyRegistrationData } from "@edr/types";
 
+/**
+ * `licenceNumber` picks which of the TIN's business licences to resolve — a TIN
+ * routinely holds several, and the customer says which one they operate as.
+ */
 export function useETradeData() {
   return useMutation({
-    mutationFn: async (tin: string): Promise<CompanyRegistrationData> => {
-      return companiesService.fetchETradeInfo({ tin });
+    mutationFn: async (vars: {
+      tin: string;
+      licenceNumber?: string;
+    }): Promise<CompanyRegistrationData> => {
+      return companiesService.fetchETradeInfo(vars);
     },
     onError: (error) => {
       const { message } = extractApiError(error);
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 21956c9a1..92e1a7118 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
@@ -989,7 +989,9 @@ export default function CompanyProfileForm({
     }
     if (step === "company" && !tinVerified) {
       setSaveError(
-        "We need to confirm your TIN with eTrade before continuing.",
+        tinStatus === "choose-business"
+          ? "This TIN holds more than one business licence — pick the one you're registering as."
+          : "We need to confirm your TIN with eTrade before continuing.",
       );
       return;
     }
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/ETradeCompanyCard.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/ETradeCompanyCard.tsx
index 2634fed0d..4469009ed 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/ETradeCompanyCard.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/ETradeCompanyCard.tsx
@@ -1,70 +1,27 @@
-import { Badge, Card, Group, Select, SimpleGrid, Text, TextInput } from "@mantine/core";
+import { Badge, Card, Group, SimpleGrid, Text } from "@mantine/core";
 import { CheckCircle2 } from "lucide-react";
-import { Controller } from "react-hook-form";
-import type {
-  Control,
-  FieldErrors,
-  UseFormRegister,
-  UseFormWatch,
-} from "react-hook-form";
-import { ETHIOPIAN_REGIONS } from "@edr/types";
+import type { UseFormWatch } from "react-hook-form";
 
 import type { FormData } from "./schema";
 import { ReadOnlyField } from "./ReadOnlyField";
 
 /**
- * One field of the verified-registration card: locked read-only once eTrade
- * supplied a value, but falls back to an editable input when eTrade left it
- * blank — otherwise a gap in eTrade's own data would leave the field
- * permanently empty and the user stuck (zod requires all of these).
+ * The verified eTrade record, rendered strictly read-only.
  *
- * A value that fails validation unlocks the same way. eTrade (or a row saved
- * before the current rules) can supply something the schema rejects, and a
- * rejected value rendered read-only is a step that can never be completed and
- * never says why.
+ * Nothing here is typeable — not even a field eTrade left blank. These values
+ * are the government's record of the company, so a customer-typed substitute
+ * would be an unverified claim wearing the badge of a verified one. A gap stays
+ * a visible gap ("—"), and the schema no longer requires these fields, so it
+ * cannot block the step either.
  */
-function LockedField({
-  label,
-  name,
-  register,
-  watch,
-  errors,
-}: {
-  label: string;
-  name: keyof FormData;
-  register: UseFormRegister<FormData>;
-  watch: UseFormWatch<FormData>;
-  errors: FieldErrors<FormData>;
-}) {
-  const value = watch(name) as string | undefined;
-  if (value && value.trim() && !errors[name]) {
-    return <ReadOnlyField label={label} value={value} />;
-  }
-  return (
-    <TextInput
-      label={label}
-      description="eTrade didn't provide this — please confirm"
-      error={errors[name]?.message as string | undefined}
-      {...register(name)}
-    />
-  );
-}
-
 export default function ETradeCompanyCard({
   tin,
-  register,
   watch,
-  errors,
-  control,
 }: {
   tin: string;
-  register: UseFormRegister<FormData>;
   watch: UseFormWatch<FormData>;
-  errors: FieldErrors<FormData>;
-  control: Control<FormData>;
 }) {
   const companyName = watch("companyName");
-  const region = watch("region");
 
   return (
     <Card padding="md" radius="md" withBorder>
@@ -88,73 +45,18 @@ export default function ETradeCompanyCard({
       </Group>
 
       <SimpleGrid cols={2} spacing="sm">
-        <LockedField
-          label="Company Name"
-          name="companyName"
-          register={register}
-          watch={watch}
-          errors={errors}
-        />
+        <ReadOnlyField label="Company Name" value={watch("companyName")} />
         <ReadOnlyField label="License Number" value={watch("licenceNumber")} />
         <ReadOnlyField label="Status" value={watch("statusDescription")} />
         <ReadOnlyField label="Date Registered" value={watch("dateRegistered")} />
         <ReadOnlyField label="Renewal Date" value={watch("renewalDate")} />
         <ReadOnlyField label="Renewed From" value={watch("renewedFrom")} />
         <ReadOnlyField label="Renewed To" value={watch("renewedTo")} />
-        {/* Membership of the catalog, not mere presence: eTrade's normalizer
-            returns null for a region it doesn't recognise, and older rows can
-            hold a spelling that isn't in the list. Showing such a value
-            read-only left the customer with a required field they could not
-            correct. */}
-        {(ETHIOPIAN_REGIONS as readonly string[]).includes(region ?? "") ? (
-          <ReadOnlyField label="Region" value={region} />
-        ) : (
-          <Controller
-            name="region"
-            control={control}
-            render={({ field }) => (
-              <Select
-                label="Region"
-                description="eTrade didn't provide this — please confirm"
-                placeholder="Select region"
-                searchable
-                data={ETHIOPIAN_REGIONS.map((r) => ({ value: r, label: r }))}
-                error={errors.region?.message}
-                value={field.value || null}
-                onChange={(v) => field.onChange(v ?? "")}
-                onBlur={field.onBlur}
-              />
-            )}
-          />
-        )}
-        <LockedField
-          label="Zone"
-          name="zone"
-          register={register}
-          watch={watch}
-          errors={errors}
-        />
-        <LockedField
-          label="Woreda"
-          name="woreda"
-          register={register}
-          watch={watch}
-          errors={errors}
-        />
-        <LockedField
-          label="Kebele"
-          name="kebele"
-          register={register}
-          watch={watch}
-          errors={errors}
-        />
-        <LockedField
-          label="House No"
-          name="houseNo"
-          register={register}
-          watch={watch}
-          errors={errors}
-        />
+        <ReadOnlyField label="Region" value={watch("region")} />
+        <ReadOnlyField label="Zone" value={watch("zone")} />
+        <ReadOnlyField label="Woreda" value={watch("woreda")} />
+        <ReadOnlyField label="Kebele" value={watch("kebele")} />
+        <ReadOnlyField label="House No" value={watch("houseNo")} />
       </SimpleGrid>
     </Card>
   );
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/helpers.ts b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/helpers.ts
index 36c0072fb..20e889235 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/helpers.ts
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/helpers.ts
@@ -91,7 +91,7 @@ export function buildPayload(
   _user: AuthUser,
 ): CreateCompanyPayload {
   return {
-    companyName: data.companyName,
+    companyName: data.companyName ?? "",
     companyAddress: data.companyAddress,
     tin: data.tinNumber,
     vatNumber: data.vatNumber,
@@ -128,7 +128,10 @@ export function stepPayload(
     case "company": {
       const etrade: Partial<UpdateProfilePayload> = {};
       for (const key of ETRADE_BUNDLE_FIELDS) {
-        if (dirty[key]) (etrade as Record<string, unknown>)[key] = d[key];
+        // Empty is never sent: a field eTrade left blank has no input to fill
+        // it, and "" fails the API's own validation (region's @IsIn, say),
+        // which would 400 a save over data the customer cannot supply.
+        if (dirty[key] && d[key]) (etrade as Record<string, unknown>)[key] = d[key];
       }
       if (dirty.tinNumber) etrade.tin = d.tinNumber;
       return {
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
index 0d357f691..95755e777 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
@@ -85,11 +85,18 @@ describe("VAT number", () => {
   });
 });
 
-describe("region", () => {
-  it("rejects a spelling outside the catalog", () => {
-    expect(errorFor(values({ region: "Addis Abeba City" }), "region")).toBe(
-      "Region is required",
-    );
+describe("eTrade-sourced fields", () => {
+  // They are rendered read-only — there is no input to correct one in — so the
+  // schema must never reject what eTrade supplied (or failed to supply).
+  it.each([
+    "companyName",
+    "region",
+    "zone",
+    "woreda",
+    "kebele",
+    "houseNo",
+  ] as const)("accepts a blank %s", (field) => {
+    expect(errorFor(values({ [field]: "" }), field)).toBeUndefined();
   });
 });
 
@@ -100,12 +107,18 @@ describe("stepFields", () => {
   it("never gates the company step on a derived or read-only field", () => {
     const unreachable = [
       "etradePhone",
+      "companyName",
       "licenceNumber",
       "statusDescription",
       "dateRegistered",
       "renewedFrom",
       "renewalDate",
       "renewedTo",
+      "region",
+      "zone",
+      "woreda",
+      "kebele",
+      "houseNo",
     ];
     expect(stepFields.company.filter((f) => unreachable.includes(f))).toEqual(
       [],
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 db48667db..0017598e9 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,5 +1,5 @@
 import { z } from "zod";
-import { ETHIOPIAN_REGIONS } from "@edr/types";
+
 
 import { isValidPhone } from "@/components/PhoneField";
 
@@ -12,7 +12,8 @@ export type CompanyStep =
   | "additional";
 
 export const onboardingSchema = z.object({
-  companyName: z.string().min(1, "Company name is required"),
+  // eTrade-sourced, and never typeable — see the address block below.
+  companyName: z.string().optional(),
   // 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(),
@@ -36,24 +37,15 @@ export const onboardingSchema = z.object({
   renewedFrom: z.string().optional(),
   renewalDate: z.string().optional(),
   renewedTo: z.string().optional(),
-  // Address fields are user-entered and required (the registration/license
-  // 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.
-  //
-  // 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"),
-  houseNo: z.string().min(1, "House number is required"),
+  // The registered address comes from eTrade and nowhere else — the form
+  // renders these read-only, so requiring them would be a Continue button that
+  // fails on a field with no input to fix it. A gap in eTrade's own data stays
+  // a gap rather than becoming a customer-typed claim wearing eTrade's badge.
+  region: z.string().optional(),
+  zone: z.string().optional(),
+  woreda: z.string().optional(),
+  kebele: z.string().optional(),
+  houseNo: z.string().optional(),
   contactPersonName: z.string().min(1, "Contact person name is required"),
   contactPersonPosition: z.string().optional(),
   contactPersonEmail: z
@@ -192,17 +184,9 @@ export const ETRADE_BUNDLE_FIELDS = [
  * (`REQUIRED_COMPANY_INFO`), and reports it with a message.
  */
 export const stepFields: Record<CompanyStep, (keyof FormData)[]> = {
-  company: [
-    "companyName",
-    "tinNumber",
-    "vatNumber",
-    "ownerPassportNumber",
-    "region",
-    "zone",
-    "woreda",
-    "kebele",
-    "houseNo",
-  ],
+  // Only the three fields this step actually renders an input for. The company
+  // name and the registered address are eTrade's, shown read-only.
+  company: ["tinNumber", "vatNumber", "ownerPassportNumber"],
   personnel: [
     "generalManagerName",
     "generalManagerEmail",
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
index 978377151..0473b26d1 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
@@ -40,7 +40,6 @@ export default function CompanyInfoStep({
 }: CompanyInfoStepProps) {
   const {
     register,
-    control,
     watch,
     formState: { errors },
   } = form;
@@ -123,15 +122,10 @@ export default function CompanyInfoStep({
           onStatusChange={onETradeStatusChange}
           onReset={onETradeReset}
           alreadyVerified={hasRegistrationDetails}
+          selectedLicenceNumber={watch("licenceNumber")}
         />
         {tinVerified && (
-          <ETradeCompanyCard
-            tin={watch("tinNumber")}
-            register={register}
-            watch={watch}
-            errors={errors}
-            control={control}
-          />
+          <ETradeCompanyCard tin={watch("tinNumber")} watch={watch} />
         )}
       </StepSection>
     </Stack>
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 deaec110f..b11fecefc 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabCompanyProfile.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabCompanyProfile.tsx
@@ -11,7 +11,6 @@ import {
   Button,
   Card,
   Group,
-  Select,
   SimpleGrid,
   Stack,
   Text,
@@ -21,9 +20,9 @@ import {
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { Building2, CheckCircle2, Save, XCircle } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
-import { Controller, useForm } from "react-hook-form";
+import { useForm } from "react-hook-form";
 import { z } from "zod";
-import { ETHIOPIAN_REGIONS, type CompanyRegistrationData } from "@edr/types";
+import type { CompanyRegistrationData } from "@edr/types";
 import OnboardingRoleSelect from "./OnboardingRoleSelect";
 import FaydaVerifyPanel from "@/components/FaydaVerifyPanel";
 import ETradeInfo, {
@@ -35,7 +34,8 @@ import { ETRADE_BUNDLE_FIELDS as SHARED_ETRADE_FIELDS } from "@/pages/accounts/c
 import { normalizeIdentityPhones } from "@/pages/accounts/companyProfileForm/helpers";
 
 export const COMPANY_PROFILE_SCHEMA = z.object({
-  companyName: z.string().min(1, "Company name is required"),
+  // eTrade-sourced and read-only, like the registration block below.
+  companyName: z.string().optional(),
   companyLocation: z.string().min(1, "Location is required"),
   // Derived from the eTrade address parts (region/zone/woreda/kebele/houseNo);
   // no standalone input.
@@ -48,24 +48,20 @@ export const COMPANY_PROFILE_SCHEMA = z.object({
     .min(1, "VAT number is required")
     .regex(/^\d{10,11}$/, "VAT number must be 10 or 11 digits"),
   ownerPassportNumber: z.string().optional(),
-  // Registration/address fields are eTrade-sourced — locked once eTrade
-  // supplies a value, editable only as an escape hatch when it doesn't
-  // (see LockedField below). Not typed by hand in the normal case.
+  // Registration/address fields are eTrade-sourced and never typed by hand —
+  // not even when eTrade leaves one blank, so none of them may be required
+  // here (there is no input on screen to fix one with).
   licenceNumber: z.string().optional(),
   statusDescription: z.string().optional(),
   dateRegistered: z.string().optional(),
   renewedFrom: z.string().optional(),
   renewalDate: z.string().optional(),
   renewedTo: z.string().optional(),
-  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"),
-  houseNo: z.string().min(1, "House number is required"),
+  region: z.string().optional(),
+  zone: z.string().optional(),
+  woreda: z.string().optional(),
+  kebele: z.string().optional(),
+  houseNo: z.string().optional(),
 });
 
 export type CompanyProfileFormData = z.infer<typeof COMPANY_PROFILE_SCHEMA>;
@@ -140,7 +136,6 @@ export default function TabCompanyProfile({
 
   const {
     register,
-    control,
     handleSubmit,
     reset,
     watch,
@@ -219,7 +214,9 @@ export default function TabCompanyProfile({
       // authenticity re-check for no reason.
       const etradeBundle: Record<string, string | undefined> = {};
       for (const key of ETRADE_FIELDS) {
-        if (dirtyFields[key]) etradeBundle[key] = data[key];
+        // Never "": eTrade left it blank, no input exists to fill it, and the
+        // API rejects the empty value (region's @IsIn) — see stepPayload.
+        if (dirtyFields[key] && data[key]) etradeBundle[key] = data[key];
       }
       if (dirtyFields.tinNumber) etradeBundle.tin = data.tinNumber;
 
@@ -241,7 +238,7 @@ export default function TabCompanyProfile({
           : "customer";
         const payload: CreateCompanyPayload = {
           ...base,
-          companyName: data.companyName,
+          companyName: data.companyName ?? "",
           tin: data.tinNumber,
           companyType,
           companyProfiles: selectedRoles.map((type) => ({
@@ -400,15 +397,10 @@ export default function TabCompanyProfile({
                   onDataLoaded={handleETradeDataLoaded}
                   onStatusChange={setTinStatus}
                   alreadyVerified={hasRegistrationDetails}
+                  selectedLicenceNumber={watch("licenceNumber")}
                 />
                 {tinVerified && (
-                  <EtradeLockedCard
-                    tin={watch("tinNumber")}
-                    register={register}
-                    watch={watch}
-                    errors={errors}
-                    control={control}
-                  />
+                  <EtradeLockedCard tin={watch("tinNumber")} watch={watch} />
                 )}
               </StepSection>
 
@@ -474,27 +466,20 @@ export default function TabCompanyProfile({
 }
 
 /**
- * The verified eTrade record, locked read-only — same escape hatch as
- * onboarding's ETradeCompanyCard: a field eTrade left blank falls back to an
- * editable input rather than trapping the customer.
+ * The verified eTrade record, rendered strictly read-only — same rule as
+ * onboarding's ETradeCompanyCard: nothing here is typeable, not even a field
+ * eTrade left blank. These are the government's record of the company, so a
+ * customer-typed substitute would be an unverified claim wearing a verified
+ * badge. A gap stays a visible gap ("—").
  */
 function EtradeLockedCard({
   tin,
-  register,
   watch,
-  errors,
-  control,
 }: {
   tin: string;
-  register: ReturnType<typeof useForm<CompanyProfileFormData>>["register"];
   watch: ReturnType<typeof useForm<CompanyProfileFormData>>["watch"];
-  errors: ReturnType<
-    typeof useForm<CompanyProfileFormData>
-  >["formState"]["errors"];
-  control: ReturnType<typeof useForm<CompanyProfileFormData>>["control"];
 }) {
   const companyName = watch("companyName");
-  const region = watch("region");
 
   return (
     <Card padding="md" radius="md" withBorder>
@@ -507,13 +492,7 @@ function EtradeLockedCard({
         </Text>
       </Group>
       <SimpleGrid cols={2} spacing="sm">
-        <LockedField
-          label="Company Name"
-          name="companyName"
-          register={register}
-          watch={watch}
-          errors={errors}
-        />
+        <ReadOnlyField label="Company Name" value={watch("companyName")} />
         <ReadOnlyField label="License Number" value={watch("licenceNumber")} />
         <ReadOnlyField label="Status" value={watch("statusDescription")} />
         <ReadOnlyField
@@ -523,101 +502,12 @@ function EtradeLockedCard({
         <ReadOnlyField label="Renewal Date" value={watch("renewalDate")} />
         <ReadOnlyField label="Renewed From" value={watch("renewedFrom")} />
         <ReadOnlyField label="Renewed To" value={watch("renewedTo")} />
-        {/* Membership of the catalog, not mere presence — a stored spelling
-            outside the list is otherwise uncorrectable. */}
-        {(ETHIOPIAN_REGIONS as readonly string[]).includes(region ?? "") ? (
-          <ReadOnlyField label="Region" value={region} />
-        ) : (
-          <RegionSelect control={control} error={errors.region?.message} />
-        )}
-        <LockedField
-          label="Zone"
-          name="zone"
-          register={register}
-          watch={watch}
-          errors={errors}
-        />
-        <LockedField
-          label="Woreda"
-          name="woreda"
-          register={register}
-          watch={watch}
-          errors={errors}
-        />
-        <LockedField
-          label="Kebele"
-          name="kebele"
-          register={register}
-          watch={watch}
-          errors={errors}
-        />
-        <LockedField
-          label="House No"
-          name="houseNo"
-          register={register}
-          watch={watch}
-          errors={errors}
-        />
+        <ReadOnlyField label="Region" value={watch("region")} />
+        <ReadOnlyField label="Zone" value={watch("zone")} />
+        <ReadOnlyField label="Woreda" value={watch("woreda")} />
+        <ReadOnlyField label="Kebele" value={watch("kebele")} />
+        <ReadOnlyField label="House No" value={watch("houseNo")} />
       </SimpleGrid>
     </Card>
   );
 }
-
-function LockedField({
-  label,
-  name,
-  register,
-  watch,
-  errors,
-}: {
-  label: string;
-  name: keyof CompanyProfileFormData;
-  register: ReturnType<typeof useForm<CompanyProfileFormData>>["register"];
-  watch: ReturnType<typeof useForm<CompanyProfileFormData>>["watch"];
-  errors: ReturnType<
-    typeof useForm<CompanyProfileFormData>
-  >["formState"]["errors"];
-}) {
-  const value = watch(name) as string | undefined;
-  // A value that fails validation unlocks too — rendering a rejected value
-  // read-only is a save that can never succeed and never says why.
-  if (value?.trim() && !errors[name]) {
-    return <ReadOnlyField label={label} value={value} />;
-  }
-  return (
-    <TextInput
-      label={label}
-      description="eTrade didn't provide this — please confirm"
-      error={errors[name]?.message as string | undefined}
-      {...register(name)}
-    />
-  );
-}
-
-function RegionSelect({
-  control,
-  error,
-}: {
-  control: ReturnType<typeof useForm<CompanyProfileFormData>>["control"];
-  error?: string;
-}) {
-  return (
-    <Controller
-      name="region"
-      control={control}
-      render={({ field }) => (
-        <Select
-          label="Region"
-          description="eTrade didn't provide this — please confirm"
-          placeholder="Select region"
-          searchable
-          data={ETHIOPIAN_REGIONS.map((r) => ({ value: r, label: r }))}
-          error={error}
-          value={field.value || null}
-          onChange={(v) => field.onChange(v ?? "")}
-          onBlur={field.onBlur}
-        />
-      )}
-    />
-  );
-}
diff --git a/apps/edr-freight-web/portal/src/services/companies.service.ts b/apps/edr-freight-web/portal/src/services/companies.service.ts
index 58de2bd16..d6a78f1af 100644
--- a/apps/edr-freight-web/portal/src/services/companies.service.ts
+++ b/apps/edr-freight-web/portal/src/services/companies.service.ts
@@ -480,7 +480,10 @@ export const companiesService = {
   },
 
   /** Fetch company registration data from eTrade by TIN. */
-  fetchETradeInfo: async (payload: { tin: string }): Promise<any> => {
+  fetchETradeInfo: async (payload: {
+    tin: string;
+    licenceNumber?: string;
+  }): Promise<any> => {
     const response = await client.post<ApiResponse<any>>(
       URL_CONSTANTS.COMPANIES_API.FETCH_ETRADE_INFO,
       payload,
diff --git a/packages/types/src/freight/etrade.ts b/packages/types/src/freight/etrade.ts
index 67a7de28b..6f33567e4 100644
--- a/packages/types/src/freight/etrade.ts
+++ b/packages/types/src/freight/etrade.ts
@@ -55,10 +55,24 @@ export interface ETradeCompanyInfo {
     RenewedFrom: string;
     RenewedTo: string;
     BusinessLicensingGroupMain: string | null;
-    SubGroups: string | null;
+    SubGroups: Array<{ Code: number; Description: string }> | null;
   }>;
 }
 
+/**
+ * One business licence held under a TIN. A single owner routinely holds many
+ * (import of vehicles, export of coffee, freight forwarding…), all sharing the
+ * same trade name — the licensed activity is what tells them apart, so that is
+ * what the customer picks by.
+ */
+export interface ETradeBusinessOption {
+  licenceNumber: string;
+  tradeName: string;
+  /** The licensed activities ("Import trade in …"), joined. May be empty. */
+  activity: string;
+  renewedTo: string;
+}
+
 export interface CompanyRegistrationData {
   /**
    * The registered organization name — `ETradeCompanyInfo.BusinessName`, falling
@@ -84,4 +98,11 @@ export interface CompanyRegistrationData {
   managerPhone: string;
   /** True when this TIN is already registered to an existing company. */
   tinTaken?: boolean;
+  /**
+   * Every licence this TIN holds. More than one means the customer has to say
+   * which business they are acting as before the registration data above can be
+   * trusted — it describes whichever licence was selected (the first, by
+   * default).
+   */
+  businesses?: ETradeBusinessOption[];
 }

From 92371f17da48e4fdde7050a77444ae54e7c82bd2 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 10 Aug 2026 18:45:54 +0000
Subject: [PATCH 008/174] fix: the position based gl gate on sidbear

---
 .../components/layout/sidebar-sections.tsx    | 45 +------------------
 1 file changed, 2 insertions(+), 43 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index cfbc50528..83e80d11e 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -40,8 +40,6 @@ import type { SidebarItem, SidebarSection } from "./types";
 import {
   FREIGHT_PERMS,
   hasPermission as hasFreightPermission,
-  isDjiboutiGl,
-  isEthiopianGl,
   isSuperAdmin,
 } from "@/lib/permissions";
 import { getCategorySidebarChildren } from "@/pages/ruleEngine/config/resources";
@@ -554,38 +552,10 @@ export const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[]
   },
 ];
 
-/** Hrefs of the two document-clearance menu items (stable identifiers). */
-export const ET_CLEARANCE_HREF = "/dashboard/contracts/clearance";
-export const DJ_CLEARANCE_HREF = "/dashboard/gl-djibouti/clearance";
-
-// Routes a GL officer may reach beyond their clearance hub. Path B booking is
-// part of their job (create/rebook under a cleared contract, then view that
-// booking's clearance), but those routes live outside the clearance prefix —
-// without this allowlist the single-prefix lock bounces them out of their own
-// workflow. Matched against location.pathname (no query string).
-export const GL_WORKFLOW_PATH_PATTERNS: RegExp[] = [
-  /^\/dashboard\/contracts\/[^/]+\/create-booking(\/|$)/,
-  /^\/dashboard\/bookings\/[^/]+\/clearance(\/|$)/,
-  // The ET hub's rows open the shipment clearance detail at this URL.
-  /^\/dashboard\/clearance\/[^/]+(\/|$)/,
-];
-
-const isEtClearanceItem = (item: SidebarItem): boolean =>
-  item.href === ET_CLEARANCE_HREF;
-const isDjClearanceItem = (item: SidebarItem): boolean =>
-  item.href === DJ_CLEARANCE_HREF;
-const isClearanceItem = (item: SidebarItem): boolean =>
-  isEtClearanceItem(item) || isDjClearanceItem(item);
-
 /**
  * Keep only items the user is permitted to see; drop now-empty sections.
- *
- * Position-scoped visibility (super_admin sees everything):
- * - Super Admin → sees all items (all permissions pass, all tabs visible)
- * - Ethiopian GL  → sees ONLY the ET document-clearance page.
- * - Djibouti GL   → sees ONLY the DJ clearance page.
- * - Everyone else → sees everything they have permission for, EXCEPT the two
- *   clearance pages (those are GL-only).
+ * Super Admin sees everything; everyone else is filtered purely by each
+ * item's `permission` field (OR across the array when one is given).
  */
 export const filterSidebarByPermission = (
   sections: SidebarSection[],
@@ -594,9 +564,6 @@ export const filterSidebarByPermission = (
   // Superadmin sees every section and item — no permission filtering.
   if (isSuperAdmin(user)) return sections;
 
-  const etGl = isEthiopianGl(user);
-  const djGl = isDjiboutiGl(user);
-
   const permissionAllowed = (item: SidebarItem): boolean => {
     if (!item.permission) return true;
     const keys = Array.isArray(item.permission)
@@ -616,14 +583,6 @@ export const filterSidebarByPermission = (
           : item,
       )
       .filter((item) => {
-        if (etGl || djGl) {
-          // GL positions are locked to their single clearance page (parents
-          // survive only as the path to that page).
-          const isTarget = etGl ? isEtClearanceItem : isDjClearanceItem;
-          return isTarget(item) || (item.children?.length ?? 0) > 0;
-        }
-        // Everyone else: hide the GL-only clearance pages entirely.
-        if (isClearanceItem(item)) return false;
         if (!permissionAllowed(item)) return false;
         if (item.children) return item.children.length > 0;
         return true;

From 40672e9c41ab0b59013ac0bbb3c8140d13fc9b8e Mon Sep 17 00:00:00 2001
From: marshalyordanos <marshalyordanosseifu@gmail.com>
Date: Mon, 10 Aug 2026 21:47:28 +0300
Subject: [PATCH 009/174] feat(freight): surface scheduling clock and gate pay
 during drain

---
 .../src/modules/bookings/bookings.service.ts  |  58 +++++
 .../train-scheduling/booking-batch.service.ts |  35 +--
 .../detail/BookingSchedulingWindowCard.tsx    | 215 ++++++++++++++++++
 .../src/components/bookings/detail/index.ts   |   1 +
 .../bookings/BookingRequestDetailPage.tsx     |   2 +
 .../backoffice/src/types/booking.ts           |  25 ++
 .../MyPortalPage/components/BookingRow.tsx    |   8 +-
 .../src/pages/MyPortalPage/constants.ts       |   2 +-
 .../components/BookingPaymentPanel.tsx        |  23 +-
 .../src/pages/bookings/BookingsListPage.tsx   |  10 +-
 .../pages/bookings/payments/PayNowButton.tsx  |  20 ++
 .../payments/PaymentProcessingNotice.tsx      |  84 +++++++
 .../pages/bookings/payments/payment-drain.ts  |  60 +++++
 packages/types/src/freight/index.ts           |   6 +
 14 files changed, 524 insertions(+), 25 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingSchedulingWindowCard.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/bookings/payments/PaymentProcessingNotice.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/bookings/payments/payment-drain.ts

diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
index 2fb9b3032..e2a3d9b0c 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
@@ -34,6 +34,7 @@ import { ServiceType } from '../rule-engine/entities/service-type.entity';
 import { TrainSchedule } from '../train-schedules/entities/train-schedule.entity';
 import { Contract } from '../contracts/entities/contract.entity';
 import { BookingBatchService } from '../train-scheduling/booking-batch.service';
+import { paymentDrainEndsAtIso } from '../train-scheduling/booking-batch.constants';
 import { BookingContractService } from './booking-contract.service';
 import { BookingsRepository } from './bookings.repository';
 import { ConsolidationService } from './consolidation.service';
@@ -57,6 +58,24 @@ import { CustomerTruckAssignmentDto } from './dto/customer-truck-assignment.dto'
 import { PdfRenderService } from '../billing/documents/pdf-render.service';
 import { buildTabularFallbackPdf } from '../billing/documents/styled-pdf.util';
 
+/**
+ * The allocated train as the backoffice booking detail page needs it: which
+ * train, its window phase, and both the planned and actual clock. Attached by
+ * `findById` only when the booking is on a schedule.
+ */
+export interface TrainScheduleSummary {
+  id: string;
+  reference: string | null;
+  trainNumber: string | null;
+  status: string | null;
+  scheduledDepartureDate: string | null;
+  scheduledArrivalDate: string | null;
+  actualDepartureAt: string | null;
+  actualArrivalAt: string | null;
+  windowPhase: string | null;
+  paymentPhaseEndsAt: string | null;
+}
+
 /** Paginated booking list: flat `total` (backoffice) + `meta` block (portal). */
 export interface PaginatedBookings {
   items: Booking[];
@@ -1738,6 +1757,20 @@ export class BookingsService {
       (b as Booking & { handoverAwaitingSignature?: boolean }).handoverAwaitingSignature =
         pending.has(b.id);
     }
+    this.attachPaymentDrainEnds(bookings);
+  }
+
+  /**
+   * Derived, no query: end of the settlement drain tail after `paymentDeadline`.
+   * The portal hides "Pay now" between the deadline and this instant — a payment
+   * started just before the buzzer is still settling, so offering to pay again
+   * would invite a double payment.
+   */
+  private attachPaymentDrainEnds(bookings: Booking[]): void {
+    for (const b of bookings) {
+      (b as Booking & { paymentDrainEndsAt?: string | null }).paymentDrainEndsAt =
+        paymentDrainEndsAtIso(b.paymentDeadline);
+    }
   }
 
   async findAll(
@@ -2105,8 +2138,33 @@ export class BookingsService {
         .findOne({ where: { id: booking.trainScheduleId } });
       (booking as Booking & { trainScheduleStatus?: string | null }).trainScheduleStatus =
         schedule?.status ?? null;
+      // Backoffice staff view: the allocated train's identity and clock, so the
+      // detail page can state which train the booking rides and when it runs
+      // without a second round-trip to the schedules API.
+      (
+        booking as Booking & { trainScheduleSummary?: TrainScheduleSummary | null }
+      ).trainScheduleSummary = schedule
+        ? {
+            id: schedule.id,
+            reference: schedule.reference ?? null,
+            trainNumber: schedule.trainNumber ?? null,
+            status: schedule.status ?? null,
+            scheduledDepartureDate: schedule.scheduledDepartureDate?.toISOString() ?? null,
+            scheduledArrivalDate: schedule.scheduledArrivalDate?.toISOString() ?? null,
+            actualDepartureAt: schedule.actualDepartureAt?.toISOString() ?? null,
+            actualArrivalAt: schedule.actualArrivalAt?.toISOString() ?? null,
+            windowPhase: schedule.windowPhase ?? null,
+            paymentPhaseEndsAt: schedule.paymentPhaseEndsAt?.toISOString() ?? null,
+          }
+        : null;
     }
 
+    // End of this booking's own pay window including the settlement drain tail —
+    // the deadline staff should quote, since a payment landing inside the drain
+    // still counts (see paymentDrainEndsAtIso).
+    (booking as Booking & { paymentDrainEndsAt?: string | null }).paymentDrainEndsAt =
+      paymentDrainEndsAtIso(booking.paymentDeadline);
+
     // A generated-but-unsigned handover means the customer must approve delivery
     // from the portal. Self-haul: booking-based, one per booking. EDR last-mile:
     // per delivering truck (generated on truck exit), signed one by one.
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 23024bfdf..cb568171a 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
@@ -3680,23 +3680,24 @@ export class BookingBatchService implements OnModuleInit {
       // (provider query errored / payment still in flight) means we could not
       // confirm "not paid" — never expire on unknown; the next settle tick
       // asks again.
-      if (reason === "payment" && (fresh?.paymentDeadline ?? booking.paymentDeadline)) {
-        const reconcile = await this.billing.reconcilePayable(booking.id);
-        if (reconcile.paid) {
-          this.logger.log(
-            `[BATCH] expire skipped for ${booking.reference} — gateway ` +
-              `reconcile found a settled payment; payment.succeeded will allocate it`,
-          );
-          return;
-        }
-        if (reconcile.unverifiable) {
-          this.logger.warn(
-            `[BATCH] expire deferred for ${booking.reference} — settlement ` +
-              `unverifiable at the gateway; retrying next settle tick`,
-          );
-          return;
-        }
-      }
+      // TODO: CBE has no reconcile endpoint yet — re-enable once available.
+      // if (reason === "payment" && (fresh?.paymentDeadline ?? booking.paymentDeadline)) {
+      //   const reconcile = await this.billing.reconcilePayable(booking.id);
+      //   if (reconcile.paid) {
+      //     this.logger.log(
+      //       `[BATCH] expire skipped for ${booking.reference} — gateway ` +
+      //         `reconcile found a settled payment; payment.succeeded will allocate it`,
+      //     );
+      //     return;
+      //   }
+      //   if (reconcile.unverifiable) {
+      //     this.logger.warn(
+      //       `[BATCH] expire deferred for ${booking.reference} — settlement ` +
+      //         `unverifiable at the gateway; retrying next settle tick`,
+      //     );
+      //     return;
+      //   }
+      // }
     }
     const freedScheduleId = booking.trainScheduleId;
     await this.bookingsRepository.update(booking.id, {
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingSchedulingWindowCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingSchedulingWindowCard.tsx
new file mode 100644
index 000000000..84f0645a8
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingSchedulingWindowCard.tsx
@@ -0,0 +1,215 @@
+import { useEffect, useState } from "react";
+import { Badge, Box, Group, Stack, Text } from "@mantine/core";
+import { CalendarClock } from "lucide-react";
+
+import type { BookingDetail } from "@/types/booking";
+import { SchedulingStatusBadge } from "@/components/trainScheduling/ScheduleStatusBadge";
+
+import { SectionCard } from "./SectionCard";
+
+export interface BookingSchedulingWindowCardProps {
+  booking: BookingDetail;
+}
+
+/** Full date + time — staff read these against the operating clock, so no time is dropped. */
+function formatStamp(iso: string | null | undefined): string | null {
+  if (!iso) return null;
+  const ms = new Date(iso).getTime();
+  if (!Number.isFinite(ms)) return null;
+  return new Date(ms).toLocaleString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/** "in 2h 14m" / "12m ago" — the at-a-glance read next to an absolute stamp. */
+function formatRelative(iso: string, nowMs: number): string {
+  const diff = new Date(iso).getTime() - nowMs;
+  const past = diff < 0;
+  const totalMinutes = Math.floor(Math.abs(diff) / 60_000);
+  const days = Math.floor(totalMinutes / 1440);
+  const hours = Math.floor((totalMinutes % 1440) / 60);
+  const minutes = totalMinutes % 60;
+
+  const parts: string[] = [];
+  if (days) parts.push(`${days}d`);
+  if (hours) parts.push(`${hours}h`);
+  // Keep minutes when they're the only unit, so sub-hour gaps never read "0".
+  if (minutes || parts.length === 0) parts.push(`${minutes}m`);
+
+  const span = parts.slice(0, 2).join(" ");
+  return past ? `${span} ago` : `in ${span}`;
+}
+
+function Row({
+  label,
+  value,
+  hint,
+  tone,
+}: {
+  label: string;
+  value: string;
+  hint?: string | null;
+  tone?: "muted" | "warning" | "danger";
+}) {
+  const valueColor =
+    tone === "danger" ? "red.7" : tone === "warning" ? "orange.7" : "dark";
+  return (
+    <Group justify="space-between" align="flex-start" wrap="nowrap" gap="md">
+      <Text size="sm" c="dimmed" style={{ flexShrink: 0 }}>
+        {label}
+      </Text>
+      <Box style={{ textAlign: "right", minWidth: 0 }}>
+        <Text size="sm" fw={600} c={valueColor}>
+          {value}
+        </Text>
+        {hint ? (
+          <Text size="xs" c="dimmed">
+            {hint}
+          </Text>
+        ) : null}
+      </Box>
+    </Group>
+  );
+}
+
+/**
+ * Backoffice-only staff view of the scheduling clock: which batch/train the
+ * booking is scheduled for, when its pay window closes, and the train's
+ * planned vs actual departure/arrival (i.e. when the run actually ended).
+ */
+export function BookingSchedulingWindowCard({
+  booking,
+}: BookingSchedulingWindowCardProps) {
+  const schedule = booking.trainScheduleSummary ?? null;
+
+  // The pay-window end staff should quote is the drain end (a payment landing
+  // inside the drain still counts); fall back to the raw deadline if the API
+  // predates that field.
+  const payWindowEndsAt = booking.paymentDrainEndsAt ?? booking.paymentDeadline ?? null;
+
+  // One shared ticking clock so every relative label in the card stays in sync.
+  const [nowMs, setNowMs] = useState(() => Date.now());
+  useEffect(() => {
+    const interval = setInterval(() => setNowMs(Date.now()), 30_000);
+    return () => clearInterval(interval);
+  }, []);
+
+  const hasAnything =
+    Boolean(schedule) || Boolean(payWindowEndsAt) || Boolean(booking.holdExpiresAt);
+  if (!hasAnything) return null;
+
+  const payWindowClosed = payWindowEndsAt
+    ? new Date(payWindowEndsAt).getTime() <= nowMs
+    : false;
+
+  const trainLabel =
+    schedule?.trainNumber ??
+    schedule?.reference ??
+    (schedule ? "Assigned train" : null);
+
+  return (
+    <SectionCard
+      icon={CalendarClock}
+      title="Scheduling & payment window"
+      subtitle="Staff view — batch allocation and the operating clock"
+      accent="indigo"
+      extra={<SchedulingStatusBadge status={booking.schedulingStatus} />}
+    >
+      <Stack gap="sm">
+        {trainLabel ? (
+          <Row
+            label="Scheduled on train"
+            value={trainLabel}
+            hint={
+              schedule?.reference && schedule.reference !== trainLabel
+                ? schedule.reference
+                : null
+            }
+          />
+        ) : (
+          <Row
+            label="Scheduled on train"
+            value="Not yet allocated"
+            tone="muted"
+            hint="The booking has not been placed on a train schedule"
+          />
+        )}
+
+        {schedule?.status ? (
+          <Group justify="space-between" wrap="nowrap">
+            <Text size="sm" c="dimmed">
+              Train status
+            </Text>
+            <Group gap="xs">
+              {schedule.windowPhase ? (
+                <Badge variant="light" color="gray" size="sm">
+                  {schedule.windowPhase.replace(/_/g, " ")}
+                </Badge>
+              ) : null}
+              <Badge variant="light" color="indigo" size="sm">
+                {schedule.status}
+              </Badge>
+            </Group>
+          </Group>
+        ) : null}
+
+        {payWindowEndsAt ? (
+          <Row
+            label="Payment window ends"
+            value={formatStamp(payWindowEndsAt) ?? "—"}
+            tone={payWindowClosed ? "danger" : "warning"}
+            hint={
+              payWindowClosed
+                ? `Closed ${formatRelative(payWindowEndsAt, nowMs)}`
+                : `Closes ${formatRelative(payWindowEndsAt, nowMs)}`
+            }
+          />
+        ) : null}
+
+        {booking.holdExpiresAt && booking.schedulingStatus === "HOLDING" ? (
+          <Row
+            label="Wagon hold expires"
+            value={formatStamp(booking.holdExpiresAt) ?? "—"}
+            tone="warning"
+            hint={formatRelative(booking.holdExpiresAt, nowMs)}
+          />
+        ) : null}
+
+        {schedule ? (
+          <>
+            <Row
+              label="Departure"
+              value={
+                formatStamp(schedule.actualDepartureAt) ??
+                formatStamp(schedule.scheduledDepartureDate) ??
+                "—"
+              }
+              hint={
+                schedule.actualDepartureAt
+                  ? `Actual · planned ${formatStamp(schedule.scheduledDepartureDate) ?? "—"}`
+                  : "Planned"
+              }
+            />
+            <Row
+              label={schedule.actualArrivalAt ? "Arrived (trip ended)" : "Arrival"}
+              value={
+                formatStamp(schedule.actualArrivalAt) ??
+                formatStamp(schedule.scheduledArrivalDate) ??
+                "—"
+              }
+              hint={
+                schedule.actualArrivalAt
+                  ? `Actual · planned ${formatStamp(schedule.scheduledArrivalDate) ?? "—"}`
+                  : "Planned — the train has not arrived yet"
+              }
+            />
+          </>
+        ) : null}
+      </Stack>
+    </SectionCard>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/index.ts b/apps/edr-freight-web/backoffice/src/components/bookings/detail/index.ts
index ecbb0488e..b0b024977 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/index.ts
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/index.ts
@@ -22,3 +22,4 @@ export * from "./BookingMileServicesCard";
 export * from "./BookingCargoCard";
 export * from "./BookingContractSummaryCard";
 export * from "./BookingCompanyCard";
+export * from "./BookingSchedulingWindowCard";
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
index feee70b9d..4367fc708 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
@@ -40,6 +40,7 @@ import {
   BookingCompanyCard,
   BookingContractSummaryCard,
   BookingContainerUnitsCard,
+  BookingSchedulingWindowCard,
   BookingDocumentsPanel,
   BookingTrucksPanel,
   ContractOrdersPanel,
@@ -246,6 +247,7 @@ export default function BookingRequestDetailPage() {
             <Box style={{ position: "sticky", top: 24 }}>
               <Stack gap="lg">
                 <BookingCompanyCard booking={booking} />
+                <BookingSchedulingWindowCard booking={booking} />
                 <BookingPricingSummary booking={booking} />
                 <Box id="warehouse-payments">
                   <WarehouseInfoCard
diff --git a/apps/edr-freight-web/backoffice/src/types/booking.ts b/apps/edr-freight-web/backoffice/src/types/booking.ts
index 69312e428..e28ecbea1 100644
--- a/apps/edr-freight-web/backoffice/src/types/booking.ts
+++ b/apps/edr-freight-web/backoffice/src/types/booking.ts
@@ -131,6 +131,20 @@ export interface BookingFile {
   size?: number;
 }
 
+/** The allocated train's identity, window phase, and planned/actual clock. */
+export interface BookingTrainScheduleSummary {
+  id: string;
+  reference: string | null;
+  trainNumber: string | null;
+  status: string | null;
+  scheduledDepartureDate: string | null;
+  scheduledArrivalDate: string | null;
+  actualDepartureAt: string | null;
+  actualArrivalAt: string | null;
+  windowPhase: string | null;
+  paymentPhaseEndsAt: string | null;
+}
+
 export interface BookingDetail {
   id: string;
   reference: string;
@@ -188,6 +202,17 @@ export interface BookingDetail {
   wagonsRequired?: number | null;
   scheduledAt?: string | null;
   trainScheduleId?: string | null;
+  /** Operational status of the allocated train (null until scheduled). */
+  trainScheduleStatus?: string | null;
+  /** The allocated train's identity + clock, attached by the detail endpoint. */
+  trainScheduleSummary?: BookingTrainScheduleSummary | null;
+  /** End of this booking's pay window (batch/offer deadline). */
+  paymentDeadline?: string | null;
+  /**
+   * End of the pay window including the settlement drain tail — the deadline
+   * staff should quote, since a payment landing inside the drain still counts.
+   */
+  paymentDrainEndsAt?: string | null;
   pnrCode?: string | null;
   firstMilePickupAddress?: string | null;
   lastMileDeliveryAddress?: string | null;
diff --git a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/BookingRow.tsx b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/BookingRow.tsx
index 7abc16192..20f148f3d 100644
--- a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/BookingRow.tsx
+++ b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/BookingRow.tsx
@@ -3,6 +3,7 @@ import { memo } from "react";
 import { ACTION_PROPS, STATUS_CONFIG, cv } from "../constants";
 import { Stepper } from "./Stepper";
 import { PayNowButton } from "@/pages/bookings/payments/PayNowButton";
+import { payWindowState } from "@/pages/bookings/payments/payment-drain";
 import { BookingActionButton } from "@/pages/bookings/clearance/BookingActionButton";
 import { bookingHasInlineAction } from "@/pages/bookings/clearance/bookingNextAction";
 import {
@@ -35,8 +36,13 @@ export const BookingRow = memo(function BookingRow({
     booking.bookingType === "GENERAL_CONTRACT"
       ? "FULLY_EXECUTED"
       : "SELECTED_FOR_BATCH";
+  // A fully-closed pay window (deadline + drain both elapsed) has nothing to pay
+  // against, so the row falls back to its normal action instead of an empty slot.
+  // The drain itself still routes here — PayNowButton renders the wait notice.
   const canPay =
-    booking.status === payableStatus && booking.paymentStatus !== "PAID";
+    booking.status === payableStatus &&
+    booking.paymentStatus !== "PAID" &&
+    payWindowState(booking).phase !== "closed";
   // Clearance/operation steps + changes-requested resubmit can be done in place
   // via a modal on the row.
   const hasInlineAction = bookingHasInlineAction(booking);
diff --git a/apps/edr-freight-web/portal/src/pages/MyPortalPage/constants.ts b/apps/edr-freight-web/portal/src/pages/MyPortalPage/constants.ts
index 2ee9cd719..6c92403ce 100644
--- a/apps/edr-freight-web/portal/src/pages/MyPortalPage/constants.ts
+++ b/apps/edr-freight-web/portal/src/pages/MyPortalPage/constants.ts
@@ -302,7 +302,7 @@ export const STATUS_CONFIG: Record<string, StageConfig> = {
     icon: Wallet,
     iconColor: "edr-amber-text",
     tile: "edr-amber-soft",
-    hint: "Selected for batch · payment due within 1 hour",
+    hint: "Selected for batch · payment due before the deadline",
     step: "edr-accent",
     badgeLabel: "Pay Now",
     badgeBg: "edr-amber-soft",
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/BookingPaymentPanel.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/BookingPaymentPanel.tsx
index b94ea9fed..710c6b40f 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/BookingPaymentPanel.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/BookingPaymentPanel.tsx
@@ -18,6 +18,8 @@ import { invoicesService, type PortalInvoice } from "@/services/invoices.service
 import { InvoiceStatusBadge, titleCase } from "@/pages/billing/invoice-ui";
 import { paymentStatusLabel } from "@/pages/bookings/booking-display";
 import { isUsdOfflineBooking } from "@/pages/bookings/payments/offline-payment";
+import { payWindowState } from "@/pages/bookings/payments/payment-drain";
+import { PaymentProcessingNotice } from "@/pages/bookings/payments/PaymentProcessingNotice";
 import { saveBlob } from "@/utils/download";
 
 import {
@@ -216,6 +218,11 @@ export function BookingPaymentPanel({
     (booking.status === "SELECTED_FOR_BATCH" ||
       Boolean(booking.paymentDeadline));
 
+  // Pay deadline passed but the settlement drain tail hasn't: in-flight payments
+  // are still landing, so the pay action gives way to a processing countdown.
+  const payWindow = payWindowState(booking);
+  const draining = payWindow.phase === "draining" && Boolean(payWindow.drainEndsAt);
+
   const { data: invoices = [] } = useQuery({
     queryKey: ["booking-invoices", booking.id],
     queryFn: () => invoicesService.listForSource("booking", booking.id),
@@ -266,9 +273,11 @@ export function BookingPaymentPanel({
           {paid ? <CheckCircle2 size={13} /> : showCountdown ? <Timer size={13} /> : null}
           {paid
             ? "Paid"
-            : showCountdown
-              ? "Pay window open"
-              : paymentStatusLabel(booking.paymentStatus ?? "PENDING")}
+            : draining
+              ? "Payment processing"
+              : showCountdown
+                ? "Pay window open"
+                : paymentStatusLabel(booking.paymentStatus ?? "PENDING")}
         </Group>
       </Group>
 
@@ -279,7 +288,11 @@ export function BookingPaymentPanel({
       {/* USD: no online payment — bank transfer + slip to Finance, who confirm
           the payment (backoffice flow lands in a later phase). Shown for any
           unpaid USD booking, with or without an open pay window. */}
-      {!paid && offlineUsd && (
+      {!paid && draining && payWindow.drainEndsAt && (
+        <PaymentProcessingNotice drainEndsAt={payWindow.drainEndsAt} />
+      )}
+
+      {!paid && !draining && offlineUsd && (
         <Box
           mt={14}
           p={14}
@@ -301,7 +314,7 @@ export function BookingPaymentPanel({
         </Box>
       )}
 
-      {showCountdown && booking.paymentDeadline && (
+      {showCountdown && !draining && booking.paymentDeadline && (
         <Box mt={16}>
           <Countdown
             deadline={booking.paymentDeadline}
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
index 4a9ef757c..2f269bdab 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
@@ -35,6 +35,7 @@ import {
 
 import { ShipmentTrackingModal } from "./tracking/ShipmentTrackingModal";
 import { PayNowButton } from "./payments/PayNowButton";
+import { payWindowState } from "./payments/payment-drain";
 import { BookingActionButton } from "./clearance/BookingActionButton";
 import { bookingHasInlineAction } from "./clearance/bookingNextAction";
 import {
@@ -211,7 +212,14 @@ function PrimaryAction({
   const payableStatus = isGeneralContract
     ? "FULLY_EXECUTED"
     : "SELECTED_FOR_BATCH";
-  if (status === payableStatus && booking.paymentStatus !== "PAID") {
+  // A fully-closed pay window (deadline + drain both elapsed) falls through to
+  // the default action. The drain itself still routes here — PayNowButton
+  // renders the "payment processing" wait notice instead of a pay action.
+  if (
+    status === payableStatus &&
+    booking.paymentStatus !== "PAID" &&
+    payWindowState(booking).phase !== "closed"
+  ) {
     return <PayNowButton booking={booking} />;
   }
   // Contract ready for the customer's signature → full-page contract viewer.
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/payments/PayNowButton.tsx b/apps/edr-freight-web/portal/src/pages/bookings/payments/PayNowButton.tsx
index db50bd57f..63ca637b5 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/payments/PayNowButton.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/payments/PayNowButton.tsx
@@ -7,6 +7,8 @@ import { ModalSafeWrapper } from "@/components/customer-actions/ModalSafeWrapper
 import { PaymentMethodModal } from "../BookingDetailPage/components/PaymentMethodModal";
 import { priceTotal } from "../BookingDetailPage/utils";
 import { isUsdOfflineBooking } from "./offline-payment";
+import { payWindowState } from "./payment-drain";
+import { PaymentProcessingNotice } from "./PaymentProcessingNotice";
 import { useBookingPayment } from "./useBookingPayment";
 
 interface PayNowButtonProps {
@@ -29,6 +31,24 @@ export function PayNowButton({
 }: PayNowButtonProps) {
   const pay = useBookingPayment(booking.id);
   const pricing = booking.pricingBreakdown;
+  const payWindow = payWindowState(booking);
+
+  // Pay deadline passed but in-flight payments are still settling: show the
+  // drain countdown instead of any pay action, so nobody pays a second time.
+  // Checked before the USD branch — a bank transfer is just as double-payable.
+  if (payWindow.phase === "draining" && payWindow.drainEndsAt) {
+    return (
+      <PaymentProcessingNotice
+        drainEndsAt={payWindow.drainEndsAt}
+        variant="inline"
+      />
+    );
+  }
+
+  // Window fully over (drain included) — nothing to pay against anymore.
+  if (payWindow.phase === "closed") {
+    return null;
+  }
 
   // USD is paid by bank transfer and confirmed by Finance — no online payment.
   if (isUsdOfflineBooking(booking)) {
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/payments/PaymentProcessingNotice.tsx b/apps/edr-freight-web/portal/src/pages/bookings/payments/PaymentProcessingNotice.tsx
new file mode 100644
index 000000000..56b7897ee
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/bookings/payments/PaymentProcessingNotice.tsx
@@ -0,0 +1,84 @@
+import { useEffect, useState } from "react";
+import { Box, Group, Text } from "@mantine/core";
+import { Loader2 } from "lucide-react";
+
+/** mm:ss left until `target`; clamped at zero so it never shows a negative. */
+function secondsLeft(target: number, now: number): string {
+  const total = Math.max(0, Math.ceil((target - now) / 1000));
+  const minutes = Math.floor(total / 60);
+  const seconds = total % 60;
+  return `${minutes}:${String(seconds).padStart(2, "0")}`;
+}
+
+export interface PaymentProcessingNoticeProps {
+  /** ISO end of the drain tail — the countdown target. */
+  drainEndsAt: string;
+  /** Compact single-line form for list rows; full block for the detail page. */
+  variant?: "inline" | "block";
+  /** Called once the drain elapses, so the parent can refetch the new state. */
+  onElapsed?: () => void;
+}
+
+/**
+ * Shown in place of "Pay now" during the settlement drain tail: the pay deadline
+ * has passed but in-flight payments are still landing, so the customer waits
+ * rather than paying again.
+ */
+export function PaymentProcessingNotice({
+  drainEndsAt,
+  variant = "block",
+  onElapsed,
+}: PaymentProcessingNoticeProps) {
+  const targetMs = new Date(drainEndsAt).getTime();
+  const [now, setNow] = useState(() => Date.now());
+
+  useEffect(() => {
+    setNow(Date.now());
+    const interval = setInterval(() => {
+      const next = Date.now();
+      setNow(next);
+      if (next >= targetMs) {
+        clearInterval(interval);
+        onElapsed?.();
+      }
+    }, 1000);
+    return () => clearInterval(interval);
+  }, [targetMs, onElapsed]);
+
+  const remaining = secondsLeft(targetMs, now);
+
+  if (variant === "inline") {
+    return (
+      <Group gap={6} align="center" wrap="nowrap">
+        <Loader2 size={13} color="#B07D14" className="animate-spin" />
+        <Text fz={12} fw={700} c="#B07D14" style={{ whiteSpace: "nowrap" }}>
+          Processing · {remaining}
+        </Text>
+      </Group>
+    );
+  }
+
+  return (
+    <Box
+      mt={14}
+      p={14}
+      style={{
+        borderRadius: 10,
+        backgroundColor: "#FEF6E6",
+        border: "1px solid #F3E2B8",
+      }}
+    >
+      <Group gap={8} align="center" wrap="nowrap">
+        <Loader2 size={15} color="#9A5B00" className="animate-spin" />
+        <Text fz="13px" fw={800} c="#9A5B00">
+          Payment processing — {remaining} left
+        </Text>
+      </Group>
+      <Text mt={4} fz="12.5px" c="#7A5A1E" lh={1.55}>
+        The payment window has closed and we&apos;re confirming the payments that
+        came in. If you already paid, it can take a few minutes to appear —
+        please don&apos;t pay again. This page updates on its own.
+      </Text>
+    </Box>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/payments/payment-drain.ts b/apps/edr-freight-web/portal/src/pages/bookings/payments/payment-drain.ts
new file mode 100644
index 000000000..61d97864b
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/bookings/payments/payment-drain.ts
@@ -0,0 +1,60 @@
+import { Freight } from "@edr/types";
+
+/**
+ * Where a booking sits relative to its pay window.
+ *
+ * - `open`     — the window is live; the customer can pay.
+ * - `draining` — the deadline passed but the settlement drain tail has not. A
+ *                payment started just before the buzzer may still be settling,
+ *                so we show "processing" and hide every pay action rather than
+ *                invite a second payment for the same booking.
+ * - `closed`   — the drain tail elapsed too; the window is over.
+ * - `none`     — no deadline on the booking (nothing to gate).
+ */
+export type PayWindowPhase = "open" | "draining" | "closed" | "none";
+
+export interface PayWindowState {
+  phase: PayWindowPhase;
+  /** True only while the customer may actually start a payment. */
+  canPay: boolean;
+  /** End of the drain tail — the countdown target while `draining`. */
+  drainEndsAt: string | null;
+}
+
+type PayableBooking = Pick<
+  Freight.IBooking,
+  "paymentDeadline" | "paymentDrainEndsAt"
+>;
+
+/**
+ * Classify a booking's pay window against `now`.
+ *
+ * Falls back to the raw deadline when the server sent no `paymentDrainEndsAt`
+ * (older payload): with no known tail there is no drain to wait out, so the
+ * window goes straight from open to closed.
+ */
+export function payWindowState(
+  booking: PayableBooking | null | undefined,
+  now: number = Date.now(),
+): PayWindowState {
+  const deadline = booking?.paymentDeadline ?? null;
+  if (!deadline) {
+    return { phase: "none", canPay: true, drainEndsAt: null };
+  }
+
+  const deadlineMs = new Date(deadline).getTime();
+  if (!Number.isFinite(deadlineMs)) {
+    return { phase: "none", canPay: true, drainEndsAt: null };
+  }
+  if (now < deadlineMs) {
+    return { phase: "open", canPay: true, drainEndsAt: null };
+  }
+
+  const drainRaw = booking?.paymentDrainEndsAt ?? null;
+  const drainMs = drainRaw ? new Date(drainRaw).getTime() : NaN;
+  if (Number.isFinite(drainMs) && now < drainMs) {
+    return { phase: "draining", canPay: false, drainEndsAt: drainRaw };
+  }
+
+  return { phase: "closed", canPay: false, drainEndsAt: null };
+}
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index 7ff14721c..68f48e187 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -717,6 +717,12 @@ export interface IBooking extends BaseEntity {
   selectedForBatchAt?: string | null;
   /** End of the pay window once the booking is SELECTED_FOR_BATCH. */
   paymentDeadline?: string | null;
+  /**
+   * End of the settlement drain tail that follows `paymentDeadline`. Between the
+   * two, an in-flight payment can still land, so the customer is shown a
+   * "payment processing" state instead of a pay action.
+   */
+  paymentDrainEndsAt?: string | null;
 
   containers?: Array<{ type: string; qty: number; vgm: number }> | null;
 

From c743750ef6cd7bb37561d298792922cd84e79a1f Mon Sep 17 00:00:00 2001
From: marshalyordanos <marshalyordanosseifu@gmail.com>
Date: Mon, 10 Aug 2026 22:14:04 +0300
Subject: [PATCH 010/174] feat(freight): surface scheduling clock and gate pay
 during drain

---
 .../detail/BookingSchedulingWindowCard.tsx    | 45 ++++++++++++++++++-
 .../backoffice/src/types/booking.ts           |  5 +++
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingSchedulingWindowCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingSchedulingWindowCard.tsx
index 84f0645a8..9b5cf91f2 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingSchedulingWindowCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingSchedulingWindowCard.tsx
@@ -44,6 +44,27 @@ function formatRelative(iso: string, nowMs: number): string {
   return past ? `${span} ago` : `in ${span}`;
 }
 
+/**
+ * Length of a window as "1h 30m" / "45m". Null unless both ends are real and
+ * ordered — the pay window is configurable per schedule, so this is read off the
+ * actual stamps rather than assuming any fixed duration.
+ */
+function formatDuration(
+  from: string | null | undefined,
+  to: string | null | undefined,
+): string | null {
+  if (!from || !to) return null;
+  const fromMs = new Date(from).getTime();
+  const toMs = new Date(to).getTime();
+  if (!Number.isFinite(fromMs) || !Number.isFinite(toMs)) return null;
+  const minutes = Math.round((toMs - fromMs) / 60_000);
+  if (minutes <= 0) return null;
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  if (!hours) return `${rest}m`;
+  return rest ? `${hours}h ${rest}m` : `${hours}h`;
+}
+
 function Row({
   label,
   value,
@@ -98,8 +119,18 @@ export function BookingSchedulingWindowCard({
     return () => clearInterval(interval);
   }, []);
 
+  // How long the customer actually had to pay: start → the raw deadline, NOT the
+  // drain end (the drain is settlement grace, not payable time).
+  const windowDuration = formatDuration(
+    booking.selectedForBatchAt,
+    booking.paymentDeadline,
+  );
+
   const hasAnything =
-    Boolean(schedule) || Boolean(payWindowEndsAt) || Boolean(booking.holdExpiresAt);
+    Boolean(schedule) ||
+    Boolean(payWindowEndsAt) ||
+    Boolean(booking.selectedForBatchAt) ||
+    Boolean(booking.holdExpiresAt);
   if (!hasAnything) return null;
 
   const payWindowClosed = payWindowEndsAt
@@ -157,6 +188,18 @@ export function BookingSchedulingWindowCard({
           </Group>
         ) : null}
 
+        {booking.selectedForBatchAt ? (
+          <Row
+            label="Payment window started"
+            value={formatStamp(booking.selectedForBatchAt) ?? "—"}
+            hint={
+              windowDuration
+                ? `${windowDuration} window`
+                : formatRelative(booking.selectedForBatchAt, nowMs)
+            }
+          />
+        ) : null}
+
         {payWindowEndsAt ? (
           <Row
             label="Payment window ends"
diff --git a/apps/edr-freight-web/backoffice/src/types/booking.ts b/apps/edr-freight-web/backoffice/src/types/booking.ts
index e28ecbea1..7ae93a1b7 100644
--- a/apps/edr-freight-web/backoffice/src/types/booking.ts
+++ b/apps/edr-freight-web/backoffice/src/types/booking.ts
@@ -206,6 +206,11 @@ export interface BookingDetail {
   trainScheduleStatus?: string | null;
   /** The allocated train's identity + clock, attached by the detail endpoint. */
   trainScheduleSummary?: BookingTrainScheduleSummary | null;
+  /**
+   * When the batch engine picked this booking and opened its pay window — the
+   * start paired with `paymentDeadline` (both are set and cleared together).
+   */
+  selectedForBatchAt?: string | null;
   /** End of this booking's pay window (batch/offer deadline). */
   paymentDeadline?: string | null;
   /**

From 997998dcb2b7530f7ad4837afb51791b60c1d72b Mon Sep 17 00:00:00 2001
From: marshalyordanos <marshalyordanosseifu@gmail.com>
Date: Mon, 10 Aug 2026 23:30:18 +0300
Subject: [PATCH 011/174] feat(wagons): enforce wagon availability limits in
 transfer requests

---
 .../wagons/dto/create-transfer-request.dto.ts |  3 +-
 .../wagon-transfer-requests.service.spec.ts   | 42 ++++++++++++-
 .../wagons/wagon-transfer-requests.service.ts | 23 +++++--
 .../wagons/WagonYardWorkspaceModal.tsx        | 16 +++--
 .../pages/wagons/TransferRequestModals.tsx    | 61 +++++++++++++++++--
 5 files changed, 127 insertions(+), 18 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts b/apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts
index e747b69f2..85c879f70 100644
--- a/apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts
+++ b/apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts
@@ -14,7 +14,8 @@ import {
  * A count-only wagon-transfer request. The requester picks source yard, wagon
  * type, destination yard and HOW MANY — never the specific wagons; OCC hand-picks
  * those at fulfilment. The quantity may not exceed the AVAILABLE wagons of that
- * type currently in the source yard, and a reason is mandatory.
+ * type currently in the source yard (enforced in the service, which is the only
+ * layer that can count them), and a reason is mandatory.
  */
 export class CreateTransferRequestDto {
   @IsUUID()
diff --git a/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.spec.ts b/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.spec.ts
index 205d86450..8f7457b37 100644
--- a/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.spec.ts
@@ -199,7 +199,7 @@ describe('WagonTransferRequestsService — partial fulfilment', () => {
   });
 
   describe('createRequest', () => {
-    it('accepts a count larger than what the yard holds today', async () => {
+    it('accepts a count up to what the yard holds today', async () => {
       wagonRepo.count.mockResolvedValue(20);
 
       await service.createRequest(
@@ -207,14 +207,50 @@ describe('WagonTransferRequestsService — partial fulfilment', () => {
           fromYardId: 'yard-a',
           toYardId: 'yard-b',
           wagonTypeId: 'type-1',
-          quantity: 50,
+          quantity: 20,
           reason: 'Grain campaign',
         },
         'user-1',
       );
 
       expect(requestRepo.save).toHaveBeenCalled();
-      expect(stored.quantity).toBe(50);
+      expect(stored.quantity).toBe(20);
+    });
+
+    it('refuses a count larger than what the yard holds today', async () => {
+      wagonRepo.count.mockResolvedValue(20);
+
+      await expect(
+        service.createRequest(
+          {
+            fromYardId: 'yard-a',
+            toYardId: 'yard-b',
+            wagonTypeId: 'type-1',
+            quantity: 50,
+            reason: 'Grain campaign',
+          },
+          'user-1',
+        ),
+      ).rejects.toThrow(/only 20 wagon\(s\).*available/i);
+      expect(requestRepo.save).not.toHaveBeenCalled();
+    });
+
+    it('refuses when the yard has nothing of that type available', async () => {
+      wagonRepo.count.mockResolvedValue(0);
+
+      await expect(
+        service.createRequest(
+          {
+            fromYardId: 'yard-a',
+            toYardId: 'yard-b',
+            wagonTypeId: 'type-1',
+            quantity: 1,
+            reason: 'Grain campaign',
+          },
+          'user-1',
+        ),
+      ).rejects.toThrow(/no available wagons/i);
+      expect(requestRepo.save).not.toHaveBeenCalled();
     });
 
     it('still refuses a same-yard move', async () => {
diff --git a/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts b/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts
index 8d4159726..6b63460ad 100644
--- a/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts
+++ b/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts
@@ -75,10 +75,11 @@ export class WagonTransferRequestsService {
   ) {}
 
   /**
-   * Record a PENDING request. Count-only — no wagons are picked here, and the
-   * count is NOT capped by what the source yard holds today: OCC fulfils in
-   * instalments, so asking for 50 while only 20 sit there is a normal, useful
-   * request. A reason is mandatory and is shown on the OCC queue.
+   * Record a PENDING request. Count-only — no wagons are picked here, but the
+   * count IS capped by what the source yard can hand over right now: a request
+   * may not exceed the AVAILABLE, uncoupled wagons of that type in the source
+   * yard (the same number the yard desk shows). A reason is mandatory and is
+   * shown on the OCC queue.
    */
   async createRequest(
     dto: CreateTransferRequestDto,
@@ -89,6 +90,20 @@ export class WagonTransferRequestsService {
         'Source and destination yard must be different',
       );
     }
+    const available = await this.countAvailable(
+      dto.fromYardId,
+      dto.wagonTypeId,
+    );
+    if (available === 0) {
+      throw new BadRequestException(
+        'No available wagons of this type in the source yard',
+      );
+    }
+    if (dto.quantity > available) {
+      throw new BadRequestException(
+        `Only ${available} wagon(s) of this type are available in the source yard — cannot request ${dto.quantity}`,
+      );
+    }
     const request = this.requestRepo.create({
       fromYardId: dto.fromYardId,
       toYardId: dto.toYardId,
diff --git a/apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx b/apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx
index 4a92695ca..cb9fdf86b 100644
--- a/apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx
@@ -44,9 +44,8 @@ const clampInt = (v: number | string, max: number): number => {
 
 /**
  * NumberInput + Slider + All/Half presets, kept in sync. `max` bounds the field
- * for actions that move real wagons; omit it for a transfer REQUEST, which may
- * legitimately ask for more than the yard holds today (OCC fulfils it in
- * instalments) — the slider then just tracks the current value.
+ * to the wagons on hand; omitting it leaves the field unbounded and the slider
+ * simply tracks the current value.
  */
 const QuantityField = ({
   value,
@@ -434,9 +433,14 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
                           {availableCount} available
                         </Badge>
                       </Group>
-                      {/* No max: the request may exceed what the yard holds
-                          today — OCC fulfils it in instalments. */}
-                      <QuantityField value={transferQty} onChange={setTransferQty} />
+                      {/* Capped at the wagons actually available in this yard
+                          right now (uncoupled + Available) — a request may not
+                          ask for more than the yard can hand over. */}
+                      <QuantityField
+                        value={transferQty}
+                        onChange={setTransferQty}
+                        max={availableCount}
+                      />
                     </div>
                     <Select
                       label="Destination yard"
diff --git a/apps/edr-freight-web/backoffice/src/pages/wagons/TransferRequestModals.tsx b/apps/edr-freight-web/backoffice/src/pages/wagons/TransferRequestModals.tsx
index df90a7683..a58d49bf1 100644
--- a/apps/edr-freight-web/backoffice/src/pages/wagons/TransferRequestModals.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/wagons/TransferRequestModals.tsx
@@ -1,3 +1,4 @@
+import { Freight } from "@edr/types";
 import {
   Alert,
   Button,
@@ -41,6 +42,30 @@ function useTransferOptions(enabled: boolean) {
   };
 }
 
+/**
+ * Wagons the source yard can hand over right now — AVAILABLE and not coupled to
+ * a built train. Mirrors `countAvailable` on the API, which rejects any request
+ * asking for more than this, so the field must not let one be filed.
+ */
+function useAvailableCount(
+  enabled: boolean,
+  fromYardId: string | null,
+  wagonTypeId: string | null,
+) {
+  const { data: wagons = [] } = useQuery({
+    ...api.wagons.list.queryOptions({ input: {} }),
+    enabled: enabled && Boolean(fromYardId && wagonTypeId),
+  });
+  if (!fromYardId || !wagonTypeId) return null;
+  return wagons.filter(
+    (w) =>
+      w.currentYardId === fromYardId &&
+      w.wagonTypeId === wagonTypeId &&
+      w.status === Freight.WagonStatus.Available &&
+      !w.trainId,
+  ).length;
+}
+
 export interface TransferRequestFormModalProps {
   opened: boolean;
   onClose: () => void;
@@ -54,9 +79,9 @@ export interface TransferRequestFormModalProps {
 }
 
 /**
- * File a wagon-transfer request. The count is deliberately NOT capped by what
- * the source yard holds today — OCC fulfils in instalments, so asking for 50
- * where 20 sit is a normal request.
+ * File a wagon-transfer request. The count is capped by what the source yard
+ * has available right now; the API enforces the same ceiling, so a larger ask
+ * is rejected rather than queued.
  */
 export function TransferRequestFormModal({
   opened,
@@ -83,10 +108,23 @@ export function TransferRequestFormModal({
 
   const create = useMutation(api.wagonTransferRequests.create.mutationOptions());
 
+  const available = useAvailableCount(opened, fromYardId, wagonTypeId);
+
+  // A prefilled outstanding count (or a count typed before the yard was picked)
+  // can exceed what the chosen source yard actually has — pull it back down so
+  // the field never holds a value the API would reject.
+  useEffect(() => {
+    if (available == null) return;
+    setQuantity((q) => (Number(q) > available ? available : q));
+  }, [available]);
+
   const sameYard = Boolean(fromYardId && fromYardId === toYardId);
+  const overAvailable = available != null && Number(quantity) > available;
   const valid =
     Boolean(fromYardId && toYardId && wagonTypeId && reason.trim()) &&
     !sameYard &&
+    !overAvailable &&
+    available !== 0 &&
     Number(quantity) >= 1;
 
   const submit = async () => {
@@ -155,10 +193,25 @@ export function TransferRequestFormModal({
         />
         <NumberInput
           label="How many"
-          description="Can exceed what the yard holds today — OCC delivers in instalments"
+          description={
+            available == null
+              ? "Pick a source yard and wagon type to see what is available"
+              : `${available} wagon(s) available in the source yard`
+          }
           min={1}
+          max={available ?? undefined}
+          clampBehavior={available == null ? "none" : "strict"}
+          allowNegative={false}
           value={quantity}
           onChange={setQuantity}
+          disabled={available === 0}
+          error={
+            available === 0
+              ? "This yard has no wagons of that type available"
+              : overAvailable
+                ? `Only ${available} available`
+                : undefined
+          }
           required
         />
         <Textarea

From ea6eccbf098003d45907ea77f1c6c043d51407e8 Mon Sep 17 00:00:00 2001
From: marshalyordanos <marshalyordanosseifu@gmail.com>
Date: Tue, 11 Aug 2026 09:26:23 +0300
Subject: [PATCH 012/174] feat(upload): increase document upload size limits to
 50MB across the application

---
 .../src/common/document-upload.options.ts     | 30 +++++++
 apps/edr-freight-api/src/main.ts              | 12 ++-
 ...0000000000-RaiseDocumentUploadSizeLimit.ts | 44 ++++++++++
 .../modules/companies/companies.controller.ts |  3 +-
 .../entities/file-upload-field.entity.ts      |  2 +-
 .../poa-delegation.constants.ts               |  2 +-
 .../src/seed/file-upload-settings.seeder.ts   | 24 +++---
 docs/uploads.md                               | 86 +++++++++++++++++++
 infrastructure/nginx/spa.conf                 |  5 ++
 9 files changed, 190 insertions(+), 18 deletions(-)
 create mode 100644 apps/edr-freight-api/src/common/document-upload.options.ts
 create mode 100644 apps/edr-freight-api/src/migrations/3380000000000-RaiseDocumentUploadSizeLimit.ts
 create mode 100644 docs/uploads.md

diff --git a/apps/edr-freight-api/src/common/document-upload.options.ts b/apps/edr-freight-api/src/common/document-upload.options.ts
new file mode 100644
index 000000000..736d8099b
--- /dev/null
+++ b/apps/edr-freight-api/src/common/document-upload.options.ts
@@ -0,0 +1,30 @@
+import { MulterOptions } from "@nestjs/platform-express/multer/interfaces/multer-options.interface";
+
+/**
+ * Ceiling for a single uploaded document, in bytes.
+ *
+ * Mirrors the 50MB `max_size_mb` the file-upload settings hand the portal, so
+ * the client-side gate and the server-side cap agree. Raising this alone is not
+ * enough to accept a 50MB upload: the reverse proxy in front of the API applies
+ * its own `client_max_body_size`, and nginx's 1MB default rejects the request
+ * with a 413 before it ever reaches Nest (see docs/uploads.md).
+ */
+export const DOCUMENT_UPLOAD_MAX_BYTES = 50 * 1024 * 1024;
+
+/** Upper bound on parts in one multipart document post. */
+export const DOCUMENT_UPLOAD_MAX_FILES = 20;
+
+/**
+ * Multer caps for the document upload routes.
+ *
+ * Without an explicit `fileSize`, multer's default is unlimited and every byte
+ * is buffered in memory, so an oversized post is absorbed in full before
+ * anything can reject it. With the limit set, multer stops reading the socket
+ * at the ceiling instead.
+ */
+export const documentUploadMulterOptions: MulterOptions = {
+  limits: {
+    fileSize: DOCUMENT_UPLOAD_MAX_BYTES,
+    files: DOCUMENT_UPLOAD_MAX_FILES,
+  },
+};
diff --git a/apps/edr-freight-api/src/main.ts b/apps/edr-freight-api/src/main.ts
index c9a718f5d..f26cd19e7 100644
--- a/apps/edr-freight-api/src/main.ts
+++ b/apps/edr-freight-api/src/main.ts
@@ -16,11 +16,17 @@ import { AppModule } from "./app.module";
 
 /**
  * JSON body ceiling. Signing posts the signature AND the company stamp as
- * base64 in one JSON body, and base64 inflates bytes by ~4/3 — a 10MB stamp is
- * ~13.4MB on the wire. Express defaults to 100kb, which rejected any real stamp
+ * base64 in one JSON body, and base64 inflates bytes by ~4/3 — a 50MB asset is
+ * ~67MB on the wire. Express defaults to 100kb, which rejected any real stamp
  * image with a 413 "request entity too large".
+ *
+ * Sized to clear the 50MB per-document ceiling
+ * (`DOCUMENT_UPLOAD_MAX_BYTES`) after base64 inflation, with room for the
+ * surrounding JSON. Note that the reverse proxy applies its own
+ * `client_max_body_size` and rejects oversized bodies before Nest sees them —
+ * raising this alone does not lift the limit end to end (see docs/uploads.md).
  */
-const JSON_BODY_LIMIT = "20mb";
+const JSON_BODY_LIMIT = "100mb";
 
 /**
  * Static /etc/hosts-style overrides from `DNS_HOST_OVERRIDES`, formatted as
diff --git a/apps/edr-freight-api/src/migrations/3380000000000-RaiseDocumentUploadSizeLimit.ts b/apps/edr-freight-api/src/migrations/3380000000000-RaiseDocumentUploadSizeLimit.ts
new file mode 100644
index 000000000..99d949e2e
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3380000000000-RaiseDocumentUploadSizeLimit.ts
@@ -0,0 +1,44 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Raises the per-field document ceiling from 10MB to 50MB.
+ *
+ * `max_size_mb` is what the portal enforces client-side (SmartFileInput blocks
+ * the file and shows "File size exceeds the limit of NMB"), so the seeded 10
+ * was the visible limit for every existing form even after the server-side caps
+ * were lifted. The seeder only writes these rows on first insert, so deployed
+ * environments keep their old value until this runs.
+ *
+ * Only rows still sitting at the old default are touched — a field an admin has
+ * deliberately tuned to something else keeps that value.
+ */
+export class RaiseDocumentUploadSizeLimit3380000000000
+  implements MigrationInterface
+{
+  name = "RaiseDocumentUploadSizeLimit3380000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.file_upload_fields
+      ALTER COLUMN max_size_mb SET DEFAULT 50
+    `);
+    await queryRunner.query(`
+      UPDATE freight.file_upload_fields
+      SET max_size_mb = 50
+      WHERE max_size_mb = 10
+    `);
+  }
+
+  /**
+   * Restores the column default only. The old per-row values are not
+   * recoverable (10 and an admin-chosen 10 are indistinguishable after `up`),
+   * and shrinking a customer's limit back down would reject documents they have
+   * already uploaded, so the rows are deliberately left at 50.
+   */
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.file_upload_fields
+      ALTER COLUMN max_size_mb SET DEFAULT 10
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/companies/companies.controller.ts b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
index de7a01484..1b14845b2 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.controller.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
@@ -20,6 +20,7 @@ import { ApiOperation, ApiTags, ApiConsumes } from "@nestjs/swagger";
 import { CurrentUser } from "@edr/api-common";
 import type { TCurrentUser } from "@tria-plc/api-common/modules/auth/types/current-user.type";
 import { BookingStaff, MixedAudience, PortalCustomer } from "../../common/booking-guards";
+import { documentUploadMulterOptions } from "../../common/document-upload.options";
 import {
   assertFreightPermission,
   hasFreightPermission,
@@ -726,7 +727,7 @@ export class CompaniesController {
 
   @Post(":companyId/documents")
   @MixedAudience(FREIGHT_PERMS.customers.update)
-  @UseInterceptors(AnyFilesInterceptor())
+  @UseInterceptors(AnyFilesInterceptor(documentUploadMulterOptions))
   @ApiConsumes("multipart/form-data")
   @ApiOperation({ summary: "Upload documents for a company (onboarding)" })
   async uploadDocuments(
diff --git a/apps/edr-freight-api/src/modules/file-upload-settings/entities/file-upload-field.entity.ts b/apps/edr-freight-api/src/modules/file-upload-settings/entities/file-upload-field.entity.ts
index e76c5716b..097c1ec39 100644
--- a/apps/edr-freight-api/src/modules/file-upload-settings/entities/file-upload-field.entity.ts
+++ b/apps/edr-freight-api/src/modules/file-upload-settings/entities/file-upload-field.entity.ts
@@ -50,7 +50,7 @@ export class FileUploadField extends BaseEntity {
   })
   allowedExtensions!: string[];
 
-  @Column({ name: "max_size_mb", type: "integer", default: 10 })
+  @Column({ name: "max_size_mb", type: "integer", default: 50 })
   maxSizeMb!: number;
 
   @Column({ name: "display_order", type: "integer", default: 0 })
diff --git a/apps/edr-freight-api/src/modules/file-upload-settings/poa-delegation.constants.ts b/apps/edr-freight-api/src/modules/file-upload-settings/poa-delegation.constants.ts
index 9085cc018..7f8a34175 100644
--- a/apps/edr-freight-api/src/modules/file-upload-settings/poa-delegation.constants.ts
+++ b/apps/edr-freight-api/src/modules/file-upload-settings/poa-delegation.constants.ts
@@ -46,7 +46,7 @@ export function poaDelegationField(displayOrder: number): FileUploadField {
     isMultiple: false,
     maxFiles: 1,
     allowedExtensions: ["pdf", "jpg", "jpeg", "png"],
-    maxSizeMb: 10,
+    maxSizeMb: 50,
     displayOrder,
   } as FileUploadField;
 }
diff --git a/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts b/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
index 7bcae753b..512229706 100644
--- a/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
+++ b/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
@@ -37,7 +37,7 @@ const ETHIOPIAN_ONBOARDING_FIELDS: OnboardingField[] = [
     isMultiple: false,
     maxFiles: 1,
     allowedExtensions: DOC_EXTENSIONS,
-    maxSizeMb: 10,
+    maxSizeMb: 50,
     displayOrder: 1,
   },
   {
@@ -49,7 +49,7 @@ const ETHIOPIAN_ONBOARDING_FIELDS: OnboardingField[] = [
     isMultiple: false,
     maxFiles: 1,
     allowedExtensions: DOC_EXTENSIONS,
-    maxSizeMb: 10,
+    maxSizeMb: 50,
     displayOrder: 2,
   },
   {
@@ -60,7 +60,7 @@ const ETHIOPIAN_ONBOARDING_FIELDS: OnboardingField[] = [
     isMultiple: false,
     maxFiles: 1,
     allowedExtensions: DOC_EXTENSIONS,
-    maxSizeMb: 10,
+    maxSizeMb: 50,
     displayOrder: 3,
   },
   poaDelegationDefault(4),
@@ -76,7 +76,7 @@ const FOREIGN_ONBOARDING_FIELDS: OnboardingField[] = [
     isMultiple: false,
     maxFiles: 1,
     allowedExtensions: DOC_EXTENSIONS,
-    maxSizeMb: 10,
+    maxSizeMb: 50,
     displayOrder: 1,
   },
   {
@@ -87,7 +87,7 @@ const FOREIGN_ONBOARDING_FIELDS: OnboardingField[] = [
     isMultiple: false,
     maxFiles: 1,
     allowedExtensions: DOC_EXTENSIONS,
-    maxSizeMb: 10,
+    maxSizeMb: 50,
     displayOrder: 2,
   },
   {
@@ -98,7 +98,7 @@ const FOREIGN_ONBOARDING_FIELDS: OnboardingField[] = [
     isMultiple: false,
     maxFiles: 1,
     allowedExtensions: DOC_EXTENSIONS,
-    maxSizeMb: 10,
+    maxSizeMb: 50,
     displayOrder: 3,
   },
   {
@@ -109,7 +109,7 @@ const FOREIGN_ONBOARDING_FIELDS: OnboardingField[] = [
     isMultiple: false,
     maxFiles: 1,
     allowedExtensions: DOC_EXTENSIONS,
-    maxSizeMb: 10,
+    maxSizeMb: 50,
     displayOrder: 4,
   },
   poaDelegationDefault(5),
@@ -127,7 +127,7 @@ const FOREIGN_ONBOARDING_FIELDS: OnboardingField[] = [
 //     isMultiple: false,
 //     maxFiles: 1,
 //     allowedExtensions: DOC_EXTENSIONS,
-//     maxSizeMb: 10,
+//     maxSizeMb: 50,
 //     displayOrder: 1,
 //   },
 //   {
@@ -138,7 +138,7 @@ const FOREIGN_ONBOARDING_FIELDS: OnboardingField[] = [
 //     isMultiple: false,
 //     maxFiles: 1,
 //     allowedExtensions: DOC_EXTENSIONS,
-//     maxSizeMb: 10,
+//     maxSizeMb: 50,
 //     displayOrder: 2,
 //   },
 //   {
@@ -149,7 +149,7 @@ const FOREIGN_ONBOARDING_FIELDS: OnboardingField[] = [
 //     isMultiple: false,
 //     maxFiles: 1,
 //     allowedExtensions: DOC_EXTENSIONS,
-//     maxSizeMb: 10,
+//     maxSizeMb: 50,
 //     displayOrder: 3,
 //   },
 // ];
@@ -232,7 +232,7 @@ function clearanceField(
     isMultiple: false,
     maxFiles: 1,
     allowedExtensions: opts?.extensions ?? DOC_EXTENSIONS,
-    maxSizeMb: 10,
+    maxSizeMb: 50,
     displayOrder,
   };
 }
@@ -556,7 +556,7 @@ const DRIVER_DOCUMENT_FIELDS: OnboardingField[] = [
     isMultiple: true,
     maxFiles: 20,
     allowedExtensions: ["pdf", "jpg", "jpeg", "png", "doc", "docx"],
-    maxSizeMb: 10,
+    maxSizeMb: 50,
     displayOrder: 1,
   },
 ];
diff --git a/docs/uploads.md b/docs/uploads.md
new file mode 100644
index 000000000..a41763d89
--- /dev/null
+++ b/docs/uploads.md
@@ -0,0 +1,86 @@
+# Upload size limits
+
+A document upload passes through four independent ceilings. The **smallest one
+wins**, so raising a limit in application code changes nothing while a lower
+limit sits in front of it.
+
+| # | Layer | Limit | Where it lives |
+| - | ----- | ----- | -------------- |
+| 1 | Reverse proxy (`client_max_body_size`) | **50m** | nginx config on the API host — **not in this repo** for deployed environments |
+| 2 | Express JSON/urlencoded body | `JSON_BODY_LIMIT` = 80mb | `apps/edr-freight-api/src/main.ts` |
+| 3 | Multer multipart (`fileSize`) | `DOCUMENT_UPLOAD_MAX_BYTES` = 50MB | `apps/edr-freight-api/src/common/document-upload.options.ts` |
+| 4 | Per-field portal gate (`max_size_mb`) | 50 | `freight.file_upload_fields`, seeded by `file-upload-settings.seeder.ts` |
+
+Layer 4 is the only one the customer sees before uploading — `SmartFileInput`
+blocks the file client-side with "File size exceeds the limit of NMB". Layers
+1–3 produce a failed request after the fact.
+
+## The nginx layer is the one that bites
+
+nginx defaults `client_max_body_size` to **1m** and answers anything larger with
+its own HTML error page:
+
+```
+HTTP/1.1 413 Request Entity Too Large
+Server: nginx
+Content-Type: text/html
+```
+
+Two tells that a 413 came from the proxy rather than the API:
+
+- the body is nginx's HTML page, not the API's JSON envelope, and
+- `curl -w '%{size_upload}'` reports **0** — nginx rejects on the `Content-Length`
+  header, so the body is never transmitted.
+
+This is also why the failure looks like a CORS error in the browser: nginx's
+error response carries no `Access-Control-Allow-Origin` header.
+
+### Applying it
+
+Add to the `server` (or `location`) block fronting the API and reload:
+
+```nginx
+server {
+    server_name edrfreightapi-staging.edrsc.com;
+
+    client_max_body_size 50m;
+
+    location / {
+        proxy_pass http://freight-api:3001;
+        # Large uploads stream for a while; the default 60s read timeout can
+        # cut off a slow client mid-body.
+        proxy_read_timeout 300s;
+        proxy_request_buffering off;
+    }
+}
+```
+
+```bash
+nginx -t && nginx -s reload   # -t first: a bad config that reloads takes the site down
+```
+
+On Kubernetes ingress-nginx this is an annotation on the Ingress instead:
+
+```yaml
+nginx.ingress.kubernetes.io/proxy-body-size: 50m
+```
+
+Note that `client_max_body_size 0` disables the check entirely — do not use it.
+An unbounded body is a denial-of-service vector, and layer 3 buffers uploads in
+memory.
+
+## Verifying end to end
+
+512KB should pass the proxy and reach the API; 50MB should too. A `401` here is
+a *success* for this purpose — it means the request got past nginx to the API's
+auth layer.
+
+```bash
+head -c 52428800 /dev/urandom > big.bin
+curl -s -o /dev/null -w 'HTTP %{http_code}  uploaded %{size_upload}\n' \
+  -X POST "https://edrfreightapi-staging.edrsc.com/api/companies/<id>/documents" \
+  -F "test=@big.bin"
+```
+
+- `413` with `uploaded 0` → the proxy is still capped; layer 1 was not applied.
+- `401`/`200` with the full byte count → the body made it through.
diff --git a/infrastructure/nginx/spa.conf b/infrastructure/nginx/spa.conf
index 83629210c..0cc9b1de0 100644
--- a/infrastructure/nginx/spa.conf
+++ b/infrastructure/nginx/spa.conf
@@ -11,6 +11,11 @@ server {
     add_header Referrer-Policy "strict-origin-when-cross-origin" always;
     add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
 
+    # nginx defaults to 1m and answers anything larger with its own HTML 413
+    # before the request reaches an upstream. Kept in step with the 50MB
+    # per-document ceiling the API enforces (DOCUMENT_UPLOAD_MAX_BYTES).
+    client_max_body_size 50m;
+
     gzip on;
     gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/wasm;
     gzip_min_length 1024;

From 619b183a11327e462de96d01f9353623c9b3ea1b Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 11 Aug 2026 08:34:15 +0000
Subject: [PATCH 013/174] fix: redirect to booking issue fixed

---
 apps/edr-freight-web/backoffice/src/App.tsx | 22 +++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index 00d5e0ddb..ec63fa53c 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -117,6 +117,20 @@ import {
   findActiveSidebarLabel,
 } from "@/components/layout/sidebar-sections";
 
+/**
+ * The per-shipment clearance detail page is the shared destination of three
+ * hubs (Operations → Clearance, Clearance Documents, Self-Clearance Review),
+ * none of which are gated on `bookings:clearance_view`. Gating the detail on
+ * that key alone bounced reviewers back to their landing page (Bookings) the
+ * moment they opened a row, so accept any key that can reach a hub.
+ */
+const CLEARANCE_DETAIL_PERMS = [
+  FREIGHT_PERMS.bookings.clearanceView,
+  FREIGHT_PERMS.contracts.clearanceReview,
+  FREIGHT_PERMS.contracts.clearanceEtActions,
+  FREIGHT_PERMS.contracts.opsClearanceReview,
+];
+
 const DashboardShell = () => {
   const navigate = useNavigate();
   const location = useLocation();
@@ -285,9 +299,7 @@ const App = () => {
         <Route
           path="clearance/:id"
           element={
-            <RequirePermission
-              permission={FREIGHT_PERMS.bookings.clearanceView}
-            >
+            <RequirePermission permission={CLEARANCE_DETAIL_PERMS}>
               <DocumentClearanceDetailPage />
             </RequirePermission>
           }
@@ -321,9 +333,7 @@ const App = () => {
         <Route
           path="bookings/:bookingId/clearance"
           element={
-            <RequirePermission
-              permission={FREIGHT_PERMS.bookings.clearanceView}
-            >
+            <RequirePermission permission={CLEARANCE_DETAIL_PERMS}>
               <DocumentClearanceDetailPage />
             </RequirePermission>
           }

From 07a120af5ecba2772e6312706733df745b9f17c8 Mon Sep 17 00:00:00 2001
From: marshalyordanos <marshalyordanosseifu@gmail.com>
Date: Tue, 11 Aug 2026 11:48:16 +0300
Subject: [PATCH 014/174] feat(permissions): add granular permissions for train
 management actions feat(train-builder): update permissions checks for train
 actions in UI feat(contracts): enhance contract view and shipment request
 pages with new features test(shipment-preview): add tests for customs
 clearing logic in booking preview style(contract-sign-bar): create CSS for
 fixed sign bar layout

---
 .../contracts/contract-booking.service.ts     |   5 +
 .../contracts/shipment-preview-parity.spec.ts | 123 ++++++++++++++++++
 .../trains/train-builder.controller.ts        |  14 +-
 .../src/seed/freight-permissions.registry.ts  |  31 +++++
 .../backoffice/src/lib/permissions.ts         |   5 +
 .../trainBuilder/TrainBuilderDetailPage.tsx   |  94 ++++++-------
 .../src/pages/contracts/ContractViewPage.tsx  |  33 ++---
 .../contracts/NewShipmentRequestPage.tsx      |  24 ++--
 .../src/pages/contracts/contract-sign-bar.css |  11 ++
 9 files changed, 267 insertions(+), 73 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/contracts/shipment-preview-parity.spec.ts
 create mode 100644 apps/edr-freight-web/portal/src/pages/contracts/contract-sign-bar.css

diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
index 441544b39..d5989f2ac 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
@@ -1974,6 +1974,11 @@ export class ContractBookingService {
       isReefer: this.resolveShipmentHandlingFlag(contract, dto, 'reeferQuantity'),
       equipmentReturn: this.resolveShipmentEquipmentReturn(contract, dto),
       isGovernment: contract.isGovernment,
+      // The clearance fee is gated on this flag in BookingPricingService, and
+      // createUnderContract copies it off the contract. Omitting it here priced
+      // the preview WITHOUT the customs line the created booking is then billed
+      // — the customer confirmed one total and got invoiced a larger one.
+      customsClearingEnabled: contract.customsClearingEnabled,
       shippingLineId: null,
       contractRouteId: route?.id ?? null,
       originYardId: route?.originYardId ?? null,
diff --git a/apps/edr-freight-api/src/modules/contracts/shipment-preview-parity.spec.ts b/apps/edr-freight-api/src/modules/contracts/shipment-preview-parity.spec.ts
new file mode 100644
index 000000000..4152ffb30
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/contracts/shipment-preview-parity.spec.ts
@@ -0,0 +1,123 @@
+import { ContractBookingService } from './contract-booking.service';
+import type { Contract } from './entities/contract.entity';
+import type { Booking } from '../bookings/entities/booking.entity';
+import type { CreateBookingUnderContractDto } from './dto/create-booking-under-contract.dto';
+
+/**
+ * The price the customer confirms in the modal comes from validateShipment,
+ * which prices an UNSAVED twin of the booking createUnderContract will write.
+ * Any contract field that reaches the pricing service must be copied onto that
+ * twin — a field left off doesn't fail loudly, it silently drops whole charge
+ * lines from the quote while the created booking is still billed for them.
+ *
+ * The regression this locks: `customsClearingEnabled` was missing, so
+ * BookingPricingService's `if (booking.customsClearingEnabled)` gate never
+ * opened in the preview. Container bookings quoted rail freight alone, then
+ * invoiced rail + customs clearance.
+ */
+describe('shipment preview / created booking parity', () => {
+  const contract = (over: Partial<Contract> = {}): Contract =>
+    ({
+      id: 'c1',
+      freightType: 'CONTAINER',
+      tradeDirection: 'EXPORT',
+      paymentCurrency: 'ETB',
+      serviceTypeId: 'svc1',
+      customsClearingEnabled: true,
+      equipmentReturn: 'NO_RETURN',
+      isHazardous: false,
+      isReefer: false,
+      isGovernment: false,
+      cargoScope: [],
+      firstMilePickupAddress: null,
+      lastMileDeliveryAddress: null,
+      ...over,
+    }) as Contract;
+
+  /**
+   * Run validateShipment against stubbed collaborators and hand back the
+   * booking the pricing service was actually asked to price.
+   */
+  const previewBookingFor = async (c: Contract): Promise<Booking> => {
+    let priced: Booking | null = null;
+
+    const svc = {
+      contractsRepository: { findByIdWithRelations: async () => c },
+      bookingPricingService: {
+        computePriceForBooking: async (b: Booking) => {
+          priced = b;
+          return {
+            lineItems: [],
+            totalAmount: 0,
+            currency: 'ETB',
+            overweightLines: [],
+            hardBlocked: [],
+          };
+        },
+      },
+      ruleEngineService: { capacityViolations: async () => [] },
+      resolveRoute: async () => null,
+      resolveShipmentCurrency: () => 'ETB',
+      resolveCargoTypeId: () => null,
+      resolveShipmentHandlingFlag: () => false,
+      resolveShipmentEquipmentReturn: () => c.equipmentReturn,
+      resolveBulkTons: () => 0,
+      resolveBulkWeightTons: () => 0,
+      resolveContainerTypeForSize: async () => ({ id: 'ct40', sizeFt: 40 }),
+      handlingCounts: () => ({
+        hazardousQuantity: 0,
+        reeferQuantity: 0,
+        returnQuantity: 0,
+      }),
+      max20ftPairDiffTons: async () => 2,
+      findContainerClashesOnTrain: async () => [],
+    };
+
+    const dto = {
+      containers: [
+        {
+          containerSize: '40ft',
+          quantity: 2,
+          units: [{ vgmTons: 10 }, { vgmTons: 10 }],
+        },
+      ],
+    } as unknown as CreateBookingUnderContractDto;
+
+    await (
+      ContractBookingService.prototype as unknown as {
+        validateShipment: (
+          this: unknown,
+          id: string,
+          dto: CreateBookingUnderContractDto,
+        ) => Promise<unknown>;
+      }
+    ).validateShipment.call(svc, 'c1', dto);
+
+    if (!priced) throw new Error('pricing service was never called');
+    return priced;
+  };
+
+  it('prices the preview with customs clearing on when the contract clears', async () => {
+    // Without this the clearance fee is quoted as 0 and billed in full later.
+    const booking = await previewBookingFor(contract());
+    expect(booking.customsClearingEnabled).toBe(true);
+  });
+
+  it('leaves customs clearing off when the contract does not clear', async () => {
+    const booking = await previewBookingFor(
+      contract({ customsClearingEnabled: false }),
+    );
+    expect(booking.customsClearingEnabled).toBe(false);
+  });
+
+  it('carries the contract mile legs so trucking is quoted too', async () => {
+    const booking = await previewBookingFor(
+      contract({
+        firstMilePickupAddress: 'Modjo Dry Port',
+        lastMileDeliveryAddress: 'Djibouti Port',
+      }),
+    );
+    expect(booking.firstMilePickupAddress).toBe('Modjo Dry Port');
+    expect(booking.lastMileDeliveryAddress).toBe('Djibouti Port');
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/trains/train-builder.controller.ts b/apps/edr-freight-api/src/modules/trains/train-builder.controller.ts
index 834663170..c1b1459a3 100644
--- a/apps/edr-freight-api/src/modules/trains/train-builder.controller.ts
+++ b/apps/edr-freight-api/src/modules/trains/train-builder.controller.ts
@@ -39,6 +39,10 @@ import { TrainBuilderService } from './train-builder.service';
   FREIGHT_PERMS.trains.update,
   FREIGHT_PERMS.trains.assignWagons,
   FREIGHT_PERMS.trains.delete,
+  FREIGHT_PERMS.trains.changeLocomotives,
+  FREIGHT_PERMS.trains.changeYard,
+  FREIGHT_PERMS.trains.toggleActive,
+  FREIGHT_PERMS.trains.disband,
 ])
 export class TrainBuilderController {
   constructor(private readonly trainBuilderService: TrainBuilderService) {}
@@ -72,7 +76,7 @@ export class TrainBuilderController {
   }
 
   @Put(':id/locomotives')
-  @FleetManage(FREIGHT_PERMS.trains.update)
+  @FleetManage(FREIGHT_PERMS.trains.changeLocomotives)
   @ApiOperation({ summary: 'Replace the locomotive set (minimum 1, same yard)' })
   setLocomotives(
     @Param('id', ParseUUIDPipe) id: string,
@@ -94,7 +98,7 @@ export class TrainBuilderController {
   }
 
   @Patch(':id/yard')
-  @FleetManage(FREIGHT_PERMS.trains.update)
+  @FleetManage(FREIGHT_PERMS.trains.changeYard)
   @ApiOperation({
     summary: 'Relocate the train — its locomotives and wagons move to the new yard with it',
   })
@@ -143,7 +147,7 @@ export class TrainBuilderController {
   }
 
   @Post(':id/deactivate')
-  @FleetManage(FREIGHT_PERMS.trains.update)
+  @FleetManage(FREIGHT_PERMS.trains.toggleActive)
   @ApiOperation({
     summary: 'Deactivate the train (park it) — only allowed with no active schedule',
   })
@@ -152,14 +156,14 @@ export class TrainBuilderController {
   }
 
   @Post(':id/activate')
-  @FleetManage(FREIGHT_PERMS.trains.update)
+  @FleetManage(FREIGHT_PERMS.trains.toggleActive)
   @ApiOperation({ summary: 'Reactivate a deactivated train back to AVAILABLE' })
   activate(@Param('id', ParseUUIDPipe) id: string) {
     return this.trainBuilderService.activate(id);
   }
 
   @Delete(':id')
-  @FleetManage(FREIGHT_PERMS.trains.delete)
+  @FleetManage(FREIGHT_PERMS.trains.disband)
   @HttpCode(HttpStatus.NO_CONTENT)
   @ApiOperation({ summary: 'Disband the train (release wagons and locomotives)' })
   disband(@Param('id', ParseUUIDPipe) id: string) {
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 06511cb2b..47fde9fb4 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -707,6 +707,29 @@ export const FLEET_RAIL_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:trains:assign_wagons",
     "Assign wagons to train",
   ),
+  // Granular splits of trains:update / trains:delete for the train-builder
+  // detail page's Actions menu — each item gets its own grant instead of
+  // sharing the coarse update/delete keys.
+  perm(
+    "e1c00001-0001-4000-8000-000000000006",
+    "edr_freight_app:trains:change_locomotives",
+    "Change train locomotives",
+  ),
+  perm(
+    "e1c00001-0001-4000-8000-000000000007",
+    "edr_freight_app:trains:change_yard",
+    "Change train yard",
+  ),
+  perm(
+    "e1c00001-0001-4000-8000-000000000008",
+    "edr_freight_app:trains:toggle_active",
+    "Activate or deactivate train",
+  ),
+  perm(
+    "e1c00001-0001-4000-8000-000000000009",
+    "edr_freight_app:trains:disband",
+    "Disband train",
+  ),
   perm(
     "e1d00001-0001-4000-8000-000000000001",
     "edr_freight_app:routes:view",
@@ -1714,6 +1737,10 @@ export const FREIGHT_PERMS = {
     update: "edr_freight_app:trains:update",
     delete: "edr_freight_app:trains:delete",
     assignWagons: "edr_freight_app:trains:assign_wagons",
+    changeLocomotives: "edr_freight_app:trains:change_locomotives",
+    changeYard: "edr_freight_app:trains:change_yard",
+    toggleActive: "edr_freight_app:trains:toggle_active",
+    disband: "edr_freight_app:trains:disband",
   },
   routes: {
     view: "edr_freight_app:routes:view",
@@ -2021,6 +2048,10 @@ const FLEET_GRANULAR_KEYS: string[] = [
   FREIGHT_PERMS.trains.update,
   FREIGHT_PERMS.trains.delete,
   FREIGHT_PERMS.trains.assignWagons,
+  FREIGHT_PERMS.trains.changeLocomotives,
+  FREIGHT_PERMS.trains.changeYard,
+  FREIGHT_PERMS.trains.toggleActive,
+  FREIGHT_PERMS.trains.disband,
   FREIGHT_PERMS.routes.view,
   FREIGHT_PERMS.routes.create,
   FREIGHT_PERMS.routes.update,
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index 09790091d..b74c7bef9 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -188,6 +188,11 @@ export const FREIGHT_PERMS = {
     update: "edr_freight_app:trains:update",
     delete: "edr_freight_app:trains:delete",
     assignWagons: "edr_freight_app:trains:assign_wagons",
+    /** Train-builder detail Actions menu — each item its own grant. */
+    changeLocomotives: "edr_freight_app:trains:change_locomotives",
+    changeYard: "edr_freight_app:trains:change_yard",
+    toggleActive: "edr_freight_app:trains:toggle_active",
+    disband: "edr_freight_app:trains:disband",
   },
   routes: {
     view: "edr_freight_app:routes:view",
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
index 5291e26f1..400bfc1e5 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
@@ -47,7 +47,7 @@ import { TrainCompositionDiagram } from "@/components/trainScheduling/TrainCompo
 import { KpiStrip, PageContainer, PageHeader } from "@/components/page";
 import { api } from "@/services/api";
 import { useAuth } from "@/auth/useAuth";
-import { canFleetAction, FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
+import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import { useToast } from "@/hooks/use-toast";
 import type { TrainCompositionWagon } from "@/services/trainBuilder.service";
 
@@ -83,9 +83,11 @@ export default function TrainBuilderDetailPage() {
   const [maintenanceTarget, setMaintenanceTarget] =
     useState<TrainCompositionWagon | null>(null);
   const { user } = useAuth();
-  const canUpdate = canFleetAction(user, "trains", "update");
-  const canDelete = canFleetAction(user, "trains", "delete");
   const canAssign = hasPermission(user, FREIGHT_PERMS.trains.assignWagons);
+  const canChangeLocomotives = hasPermission(user, FREIGHT_PERMS.trains.changeLocomotives);
+  const canChangeYard = hasPermission(user, FREIGHT_PERMS.trains.changeYard);
+  const canToggleActive = hasPermission(user, FREIGHT_PERMS.trains.toggleActive);
+  const canDisband = hasPermission(user, FREIGHT_PERMS.trains.disband);
 
   const compositionQuery = useQuery(
     api.trainBuilder.composition.queryOptions({ input: { id }, enabled: Boolean(id) }),
@@ -172,7 +174,7 @@ export default function TrainBuilderDetailPage() {
           </Group>
         }
         action={
-          canUpdate || canDelete ? (
+          canChangeLocomotives || canChangeYard || canToggleActive || canDisband ? (
             <Menu position="bottom-end" withinPortal shadow="md" width={220}>
               <Menu.Target>
                 <Button variant="default" rightSection={<MoreHorizontal size={16} />}>
@@ -180,47 +182,49 @@ export default function TrainBuilderDetailPage() {
                 </Button>
               </Menu.Target>
               <Menu.Dropdown>
-                {canUpdate ? (
-                  <>
-                    <Menu.Item
-                      leftSection={<Replace size={15} />}
-                      disabled={!composition.editable}
-                      onClick={() => setLocoModalOpen(true)}
-                    >
-                      Change locomotives
-                    </Menu.Item>
-                    <Menu.Item
-                      leftSection={<MapPin size={15} />}
-                      disabled={!composition.editable}
-                      onClick={() => setYardModalOpen(true)}
-                    >
-                      Change yard
-                    </Menu.Item>
-                    {composition.status === "DEACTIVATED" ? (
-                      <Menu.Item
-                        leftSection={<Power size={15} />}
-                        disabled={blockingLocomotives.length > 0}
-                        onClick={() =>
-                          void withToast(async () => {
-                            await activate.mutateAsync(composition.id);
-                            toast({ title: `Train ${composition.code} reactivated` });
-                          }, "Could not reactivate train")
-                        }
-                      >
-                        Reactivate train
-                      </Menu.Item>
-                    ) : (
-                      <Menu.Item
-                        leftSection={<PowerOff size={15} />}
-                        disabled={composition.activeSchedules.length > 0}
-                        onClick={() => setDeactivateOpen(true)}
-                      >
-                        Deactivate train
-                      </Menu.Item>
-                    )}
-                  </>
+                {canChangeLocomotives ? (
+                  <Menu.Item
+                    leftSection={<Replace size={15} />}
+                    disabled={!composition.editable}
+                    onClick={() => setLocoModalOpen(true)}
+                  >
+                    Change locomotives
+                  </Menu.Item>
                 ) : null}
-                {canDelete ? (
+                {canChangeYard ? (
+                  <Menu.Item
+                    leftSection={<MapPin size={15} />}
+                    disabled={!composition.editable}
+                    onClick={() => setYardModalOpen(true)}
+                  >
+                    Change yard
+                  </Menu.Item>
+                ) : null}
+                {canToggleActive ? (
+                  composition.status === "DEACTIVATED" ? (
+                    <Menu.Item
+                      leftSection={<Power size={15} />}
+                      disabled={blockingLocomotives.length > 0}
+                      onClick={() =>
+                        void withToast(async () => {
+                          await activate.mutateAsync(composition.id);
+                          toast({ title: `Train ${composition.code} reactivated` });
+                        }, "Could not reactivate train")
+                      }
+                    >
+                      Reactivate train
+                    </Menu.Item>
+                  ) : (
+                    <Menu.Item
+                      leftSection={<PowerOff size={15} />}
+                      disabled={composition.activeSchedules.length > 0}
+                      onClick={() => setDeactivateOpen(true)}
+                    >
+                      Deactivate train
+                    </Menu.Item>
+                  )
+                ) : null}
+                {canDisband ? (
                   <Menu.Item
                     color="red"
                     leftSection={<Trash2 size={15} />}
@@ -277,7 +281,7 @@ export default function TrainBuilderDetailPage() {
               .
             </Text>
             <Group gap="xs">
-              {canUpdate ? (
+              {canChangeLocomotives ? (
                 <Button
                   size="compact-sm"
                   variant="light"
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx b/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
index 8f13e1466..92b9ed640 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
@@ -33,6 +33,8 @@ import { contractsService } from "@/services/contracts.service";
 import { api } from "@/services/api";
 import { extractApiError } from "@/utils/result";
 
+import "./contract-sign-bar.css";
+
 const CONSENT_TEXT = "I have read the entire contract and agree to its terms.";
 
 /**
@@ -225,7 +227,7 @@ export default function ContractViewPage() {
   return (
     <Box
       p={{ base: "md", md: "xl" }}
-      pb={data.canSignCustomer ? 120 : undefined}
+      pb={data.canSignCustomer ? { base: 220, sm: 160, md: 120 } : undefined}
     >
       <Box maw={920} mx="auto">
         <Group justify="space-between" wrap="wrap" gap="sm" mb="md">
@@ -294,16 +296,19 @@ export default function ContractViewPage() {
           style={{
             position: "fixed",
             bottom: 0,
-            left: 0,
+            left: "var(--sign-bar-left, 0px)",
             right: 0,
             zIndex: 100,
             borderTop: "1px solid var(--mantine-color-gray-3)",
             background: "var(--mantine-color-body)",
-            paddingBottom: 32,
+            paddingBottom: "max(env(safe-area-inset-bottom, 0px), 16px)",
+            maxHeight: "80vh",
+            overflowY: "auto",
           }}
+          className="contract-sign-bar"
         >
           <Box maw={920} mx="auto">
-            <Stack gap="sm">
+            <Group justify="flex-start" align="flex-start" wrap="wrap" gap="sm">
               <Checkbox
                 checked={agreedToTerms}
                 onChange={(e) => setAgreedToTerms(e.currentTarget.checked)}
@@ -315,17 +320,15 @@ export default function ContractViewPage() {
                     : "Read the full contract above before you can agree and sign."
                 }
               />
-              <Group justify="flex-end">
-                <Button
-                  color="edr-green"
-                  leftSection={<FileSignature size={16} />}
-                  disabled={!canProceedToSign}
-                  onClick={openSign}
-                >
-                  {usingSaved ? "Approve & sign" : "Sign contract"}
-                </Button>
-              </Group>
-            </Stack>
+              <Button
+                color="edr-green"
+                leftSection={<FileSignature size={16} />}
+                disabled={!canProceedToSign}
+                onClick={openSign}
+              >
+                {usingSaved ? "Approve & sign" : "Sign contract"}
+              </Button>
+            </Group>
           </Box>
         </Paper>
       )}
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentRequestPage.tsx b/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentRequestPage.tsx
index f5be74416..9c6974641 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentRequestPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentRequestPage.tsx
@@ -87,6 +87,8 @@ export default function NewShipmentRequestPage() {
     contract.contractKind === "GENERAL" &&
     (contract.serviceType?.includesCustoms ?? contract.customsClearingEnabled);
   const isIntercity = contract.tradeDirection === "DOMESTIC";
+  // Export shipments are invoiced in ETB only — USD is not offered.
+  const isExport = contract.tradeDirection === "EXPORT";
 
   // Only the container sizes the contract was scoped for (20ft, 40ft, or both).
   const SIZE_ORDER = ["20ft", "40ft"];
@@ -115,7 +117,7 @@ export default function NewShipmentRequestPage() {
     const dto: Freight.CreateBookingRequestDto = {
       contractRouteId: route?.id,
       scheduledDate: hasCustoms ? undefined : scheduledDate || undefined,
-      paymentCurrency: isIntercity ? "ETB" : paymentCurrency,
+      paymentCurrency: isIntercity || isExport ? "ETB" : paymentCurrency,
       notes: notes.trim() || undefined,
     };
 
@@ -246,16 +248,22 @@ export default function NewShipmentRequestPage() {
               <Text size="xs" c="dimmed" mb={8}>
                 {isIntercity
                   ? "Intercity shipments are invoiced in ETB."
-                  : "Your contract is quoted in USD. Global Logistics will book this shipment and invoice you in the currency you pick here."}
+                  : isExport
+                    ? "Export shipments are invoiced in ETB."
+                    : "Your contract is quoted in USD. Global Logistics will book this shipment and invoice you in the currency you pick here."}
               </Text>
               <SegmentedControl
-                value={isIntercity ? "ETB" : paymentCurrency}
+                value={isIntercity || isExport ? "ETB" : paymentCurrency}
                 onChange={(v) => setPaymentCurrency(v as "USD" | "ETB")}
-                disabled={isIntercity}
-                data={[
-                  { label: "USD", value: "USD" },
-                  { label: "ETB", value: "ETB" },
-                ]}
+                disabled={isIntercity || isExport}
+                data={
+                  isExport
+                    ? [{ label: "ETB", value: "ETB" }]
+                    : [
+                        { label: "USD", value: "USD" },
+                        { label: "ETB", value: "ETB" },
+                      ]
+                }
                 color="teal"
                 radius={10}
               />
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/contract-sign-bar.css b/apps/edr-freight-web/portal/src/pages/contracts/contract-sign-bar.css
new file mode 100644
index 000000000..270b91e16
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/contracts/contract-sign-bar.css
@@ -0,0 +1,11 @@
+/* Keeps the fixed sign bar confined to the content area (right of the
+   navbar) instead of spanning the full viewport and drifting off-center. */
+.contract-sign-bar {
+  --sign-bar-left: 0px;
+}
+
+@media (min-width: 48em) {
+  .contract-sign-bar {
+    --sign-bar-left: 260px;
+  }
+}

From dac2186c020712526050ce4698c113a2a9802755 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Tue, 11 Aug 2026 08:31:27 +0000
Subject: [PATCH 015/174] feat(permissions): grant the director full warehouse
 authority

The director position held no warehouse permissions at all. It now
carries the same warehouse set as the chief tier: dashboard, warehouse
/yard/zone CRUD, allocation and fee rule CRUD, the inventory operation
set, inspection reports, interchange documents and fee invoices.
Unlike the dispatcher, the director owns the allocation and fee rules
themselves. The positions seeder backfills existing environments on
boot.
---
 .../src/seed/freight-permissions.registry.ts      | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 06511cb2b..227158db3 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -2256,7 +2256,8 @@ export const POSITION_PERMISSION_PRESETS = {
     FREIGHT_PERMS.payments.view,
   ]),
   // Director additionally manages train scheduling + rail fleet (same block the
-  // operation officer/chief hold), on top of the approval-chain role preset.
+  // operation officer/chief hold), on top of the approval-chain role preset,
+  // and carries the same full warehouse authority the chief tier holds.
   director: dedupe([
     ...ROLE_PERMISSION_PRESETS.director,
     FREIGHT_PERMS.trainScheduling.view,
@@ -2268,6 +2269,18 @@ export const POSITION_PERMISSION_PRESETS = {
     FREIGHT_PERMS.fleet.view,
     FREIGHT_PERMS.fleet.manage,
     ...FLEET_GRANULAR_KEYS,
+    // Warehouse — full CRUD, matching the chief tier. Unlike the dispatcher,
+    // the director also owns the allocation and fee rules themselves.
+    FREIGHT_PERMS.warehouseDashboard.view,
+    ...Object.values(FREIGHT_PERMS.warehouses),
+    ...Object.values(FREIGHT_PERMS.warehouseYards),
+    ...Object.values(FREIGHT_PERMS.warehouseZones),
+    ...Object.values(FREIGHT_PERMS.warehouseAllocationRules),
+    ...Object.values(FREIGHT_PERMS.warehouseFeeRules),
+    ...Object.values(FREIGHT_PERMS.warehouseInventory),
+    ...Object.values(FREIGHT_PERMS.warehouseInspectionReports),
+    ...Object.values(FREIGHT_PERMS.interchangeDocuments),
+    ...Object.values(FREIGHT_PERMS.warehouseFeeInvoices),
   ]),
   ceo: dedupe([...ROLE_PERMISSION_PRESETS.ceo]),
   ethiopianGl: dedupe([...ROLE_PERMISSION_PRESETS.glEthiopia]),

From a1bcdfb692adf9be9880519a2ec2a49da7df23fd Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 11 Aug 2026 11:53:26 +0000
Subject: [PATCH 016/174] refactor(companies): one verified identity per
 company, no general manager

Replaces the owner/general-manager/PoA trio with a single identity whose
subject is the PoA when the company declares one and the owner otherwise.

- Drop the general manager everywhere: entity columns, DTOs, required-field
  list, self-service attributes, gm* identity handling.
- New explicit poaDeclared answer ("yes"/"no") replaces poaSameAsOwner. A
  DARS delegation letter is required iff it is "yes"; a freight forwarder is
  forced to "yes" server-side and gets no waiver.
- Owner name/email/phone become typeable and required, prefilled from the
  eTrade lookup, never falling back to the authenticated account.
- Store eTrade's manager separately (etradeManagerName/Phone) and expose
  ownerMatchesEtrade so backoffice compares the asserted owner against the
  licence instead of against itself.
- Foreign companies satisfy the identity with Fayda or a passport number, on
  whichever subject is verifying (poaPassportNumber added).
- Write companies.email/phone from the owner unconditionally, so a company
  without a Fayda-verified owner still has a notification address.
---
 .../modules/companies/companies.controller.ts |  80 +-
 .../modules/companies/companies.service.ts    | 913 +++++++-----------
 .../companies/company-revision-diff.util.ts   |  15 +-
 .../dto/complete-identity-verification.dto.ts | 283 +++---
 .../onboarding-requirements-response.dto.ts   |  23 +-
 .../companies/dto/profile-response.dto.ts     |  26 +-
 .../companies/dto/response-company.dto.ts     |  11 +-
 .../companies/dto/set-poa-declared.dto.ts     |  17 +
 .../companies/dto/update-profile.dto.ts       |  44 +-
 .../companies/entities/company.entity.ts      |  28 +-
 .../resolve-company-phone.util.ts             |  34 +-
 .../seed-negad-indode-arrived-train.ts        |   3 -
 ...ved-first-lastmile-demo-bookings.seeder.ts |   3 -
 .../src/seed/demo-bookings.seeder.ts          |   3 -
 .../paid-import-export-mile-demo.seeder.ts    |   3 -
 15 files changed, 659 insertions(+), 827 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/companies/dto/set-poa-declared.dto.ts

diff --git a/apps/edr-freight-api/src/modules/companies/companies.controller.ts b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
index 1b14845b2..a0c609f67 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.controller.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
@@ -39,6 +39,7 @@ import {
   CompleteIdentityVerificationDto,
 } from "./dto/complete-identity-verification.dto";
 import { SetOnboardingStepDto } from "./dto/set-onboarding-step.dto";
+import { SetPoaDeclaredDto } from "./dto/set-poa-declared.dto";
 import { StartOnboardingDto } from "./dto/start-onboarding.dto";
 import { DashboardQueryDto } from "./dto/dashboard-query.dto";
 import {
@@ -415,90 +416,31 @@ export class CompaniesController {
   @PortalCustomer()
   @ApiOperation({
     summary:
-      "Bind a completed Fayda verification to the company's owner or Power of Attorney. " +
+      "Bind a completed Fayda verification to the company's single identity. " +
       "Start the flow with POST /fayda/verification/start (platform=PORTAL), then post the returned code+state here. " +
+      "`subject` must match the company's PoA declaration — the representative when one is named, otherwise the owner. " +
       "The verified name, phone, email and address are written from the Fayda payload; on an approved company the change is staged for backoffice review.",
   })
   async completeIdentityVerification(
     @CurrentUser() user: CurrentIamUser,
     @Body() dto: CompleteIdentityVerificationDto,
   ): Promise<CompanyIdentityStateDto> {
-    return this.companiesService.completeIdentityVerification(user.id, dto, {
-      email: user.email,
-      phoneNumber: user.phoneNumber,
-    });
+    return this.companiesService.completeIdentityVerification(user.id, dto);
   }
 
-  @Post("identity/gm/same-as-owner")
+  @Patch("identity/poa-declared")
   @PortalCustomer()
   @ApiOperation({
     summary:
-      "Declare the General Manager is the company's owner, copying the owner's verified identity across. " +
-      "Refused until the owner is Fayda-verified — there would be nothing proven to copy.",
+      "Answer whether anyone holds power of attorney for this company — the question that decides whose identity is verified. " +
+      'Answering "no" removes the representative entirely: their details, their verification, their passport number and the DARS delegation paper. ' +
+      'Refused for a freight forwarder, which cannot operate without a representative (its answer is always "yes").',
   })
-  async setGmSameAsOwner(
+  async setPoaDeclared(
     @CurrentUser() user: CurrentIamUser,
+    @Body() dto: SetPoaDeclaredDto,
   ): Promise<CompanyIdentityStateDto> {
-    return this.companiesService.setGmSameAsOwner(user.id, {
-      email: user.email,
-      phoneNumber: user.phoneNumber,
-    });
-  }
-
-  @Delete("identity/gm")
-  @PortalCustomer()
-  @ApiOperation({
-    summary:
-      "Clear the General Manager's identity — the \"same as owner\" declaration or a verification, and the details either wrote. " +
-      "Leaves the GM open to be verified in their own right, or typed where Fayda is optional.",
-  })
-  async clearGmIdentity(
-    @CurrentUser() user: CurrentIamUser,
-  ): Promise<CompanyIdentityStateDto> {
-    return this.companiesService.clearGmIdentity(user.id);
-  }
-
-  @Post("identity/poa/same-as-owner")
-  @PortalCustomer()
-  @ApiOperation({
-    summary:
-      "Declare the Power of Attorney is the company's owner, copying the owner's identity across. " +
-      "Waives the DARS delegation paper — nobody delegates to themselves. " +
-      "Refused for an Ethiopian company whose owner is not Fayda-verified yet: its representative must be verified, and there would be nothing proven to copy.",
-  })
-  async setPoaSameAsOwner(
-    @CurrentUser() user: CurrentIamUser,
-  ): Promise<CompanyIdentityStateDto> {
-    return this.companiesService.setPoaSameAsOwner(user.id, {
-      email: user.email,
-      phoneNumber: user.phoneNumber,
-    });
-  }
-
-  @Delete("identity/poa/same-as-owner")
-  @PortalCustomer()
-  @ApiOperation({
-    summary:
-      "Undo the Power of Attorney \"same as owner\" declaration and the identity it copied, leaving the representative open to be verified in their own right. " +
-      "Unlike DELETE identity/fayda/poa this is allowed for a freight forwarder — it is how they change who represents them — and leaves the delegation paper on file.",
-  })
-  async clearPoaSameAsOwner(
-    @CurrentUser() user: CurrentIamUser,
-  ): Promise<CompanyIdentityStateDto> {
-    return this.companiesService.clearPoaSameAsOwner(user.id);
-  }
-
-  @Delete("identity/fayda/poa")
-  @PortalCustomer()
-  @ApiOperation({
-    summary:
-      "Remove the company's Power of Attorney — the verified identity, its details and the delegation paper together. " +
-      "Refused while the company holds a freight forwarder role, which cannot operate without a representative.",
-  })
-  async removePoaIdentity(
-    @CurrentUser() user: CurrentIamUser,
-  ): Promise<CompanyIdentityStateDto> {
-    return this.companiesService.removePoaIdentity(user.id);
+    return this.companiesService.setPoaDeclared(user.id, dto.declared);
   }
 
   @Patch("onboarding-step")
diff --git a/apps/edr-freight-api/src/modules/companies/companies.service.ts b/apps/edr-freight-api/src/modules/companies/companies.service.ts
index 5dd55e704..4362c4285 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.service.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.service.ts
@@ -33,8 +33,13 @@ import {
   buildCompanyIdentityState,
   CompanyIdentityStateDto,
   CompleteIdentityVerificationDto,
+  ETRADE_MANAGER_NAME_KEY,
+  ETRADE_MANAGER_PHONE_KEY,
   IDENTITY_SUBJECTS,
   IdentitySubject,
+  POA_DECLARED_KEY,
+  PoaDeclaration,
+  readPoaDeclaration,
 } from "./dto/complete-identity-verification.dto";
 import { ETradeService } from "./services/etrade.service";
 import { CompanyNotifierService } from "./company-notifier.service";
@@ -93,15 +98,16 @@ const POA_ATTRIBUTES = [
   "poaAddress",
 ] as const;
 /**
- * Personnel an approved company maintains itself: its contact person, its
- * general manager and its Power of Attorney. These name who to talk to, not
- * what the company is allowed to do, so freezing the settings page until a
- * reviewer gets to a new phone number costs more than it protects. They write
- * straight to the live row even for an active company.
+ * The one person an approved company maintains itself: its contact person.
+ * That names who to talk to, not what the company is allowed to do, so freezing
+ * the settings page until a reviewer gets to a new phone number costs more than
+ * it protects. It writes straight to the live row even for an active company.
  *
- * The PoA's *delegation letter* is deliberately not here — the paper is the
- * thing that actually evidences the delegation, so it still goes through
- * review (see `uploadPoaDelegationLetter`), as does the owner's own identity.
+ * The owner and the Power of Attorney are deliberately NOT here. Between them
+ * they carry the company's only identity verification — the owner is who the
+ * eTrade licence names, the PoA is who may act for the company — so an edit to
+ * either is exactly the kind of change a reviewer exists to see. Their
+ * delegation letter has always gone through review (`uploadPoaDelegationLetter`).
  */
 const SELF_SERVICE_ATTRIBUTES: readonly string[] = [
   "contactPersonName",
@@ -109,12 +115,8 @@ const SELF_SERVICE_ATTRIBUTES: readonly string[] = [
   "contactPersonEmail",
   "contactPersonPhone",
   "contactVerifiedPhone",
-  "generalManagerName",
-  "generalManagerEmail",
-  "generalManagerPhone",
-  ...POA_ATTRIBUTES,
 ];
-/** Mandatory once the company operates as a freight forwarder. */
+/** Mandatory once the company names a Power of Attorney. */
 const REQUIRED_POA_FIELDS: { key: string; label: string }[] = [
   { key: "poaName", label: "PoA name" },
   { key: "poaEmail", label: "PoA email" },
@@ -122,42 +124,25 @@ const REQUIRED_POA_FIELDS: { key: string; label: string }[] = [
 ];
 
 /**
- * `attributes` key prefix per verifiable person. The owner is NOT the general
- * manager: the owner is who the verification proves the company through, the
- * GM is personnel it names. They're very often the same human, which is what
- * the portal's "same as owner" copy is for.
+ * `attributes` key prefix per person. The owner is whoever the eTrade licence
+ * names as the business's manager; the PoA is whoever the company delegates to.
+ * Exactly one of them carries the company's identity verification — which one
+ * is the company's own declaration (`poaDeclared`).
  */
 const IDENTITY_PREFIX: Record<IdentitySubject, string> = {
   owner: "owner",
   poa: "poa",
-  gm: "gm",
 };
 
-/**
- * Typed GM columns a GM verification also writes. Three notifier services mail
- * `company.generalManagerEmail` directly, so leaving these behind would mean a
- * verified GM whose address the system never actually uses.
- */
-const GM_TYPED_FIELDS = [
-  "generalManagerName",
-  "generalManagerEmail",
-  "generalManagerPhone",
-] as const;
-
 /**
  * Identity fields a Fayda verification owns outright, per person. Once verified
  * these can no longer be typed — the government IdP is the source, so an edit
  * that disagrees with it is either a mistake or an attempt to launder the
  * guarantee away.
- *
- * The GM's entries are its typed columns: a verified GM is locked the same way
- * the others are, while an unverified one (a foreign company's, or a record
- * that predates this) stays freely editable.
  */
 const IDENTITY_OWNED_FIELDS: Record<IdentitySubject, string[]> = {
   owner: ["ownerName", "ownerEmail", "ownerPhone", "ownerAddress"],
   poa: ["poaName", "poaEmail", "poaPhone", "poaAddress"],
-  gm: [...GM_TYPED_FIELDS],
 };
 
 /**
@@ -242,23 +227,29 @@ export class CompaniesService {
         label: "Contact person phone",
         get: (c) => c.attributes?.contactPersonPhone,
       },
+      // The owner — whoever the eTrade licence names as the business's manager.
+      // All three are required whatever their source: the eTrade lookup fills
+      // the name and phone, a Fayda verification can fill all three, and the
+      // portal renders an input for whatever neither supplied. eTrade never
+      // returns an email and Fayda's email claim is optional, so in practice
+      // that field is usually typed — which is fine, because there IS an input
+      // for it. What there is no longer is a fallback to the signed-in account:
+      // the person onboarding is not necessarily the person on the licence, and
+      // silently stamping their address onto the owner made the record a guess.
       {
-        key: "generalManagerName",
-        label: "General manager name",
-        get: (c) => c.attributes?.generalManagerName,
+        key: "ownerName",
+        label: "Owner name",
+        get: (c) => c.attributes?.ownerName,
       },
-      // The manager's EMAIL is deliberately absent. It was demanded because the
-      // notifiers were believed to mail it, and Fayda's email claim is optional
-      // — so a manager the government proved without one blocked the whole
-      // submission over an address nothing could produce. `companyNotifyEmailExpr`
-      // now resolves the address itself and falls through to the contact
-      // person's, then to the registering account's (which signup guarantees),
-      // so nothing depends on this being filled. It is still collected and still
-      // preferred when present; it just no longer holds the company hostage.
       {
-        key: "generalManagerPhone",
-        label: "General manager phone",
-        get: (c) => c.attributes?.generalManagerPhone,
+        key: "ownerEmail",
+        label: "Owner email",
+        get: (c) => c.attributes?.ownerEmail,
+      },
+      {
+        key: "ownerPhone",
+        label: "Owner phone",
+        get: (c) => c.attributes?.ownerPhone,
       },
     ];
 
@@ -768,6 +759,7 @@ export class CompaniesService {
     company: Company,
     dto: Partial<UpdateProfileDto> & {
       faydaIdentity?: VerifiedIdentityAttributes;
+      etradeManager?: { name: string; phone: string };
     },
   ): Record<string, any> {
     const companyUpdates: Record<string, any> = {};
@@ -796,12 +788,10 @@ export class CompaniesService {
       attrUpdates.contactVerifiedPhone = normalizeE164(
         dto.contactVerifiedPhone,
       );
-    if (dto.generalManagerName !== undefined)
-      attrUpdates.generalManagerName = dto.generalManagerName;
-    if (dto.generalManagerEmail !== undefined)
-      attrUpdates.generalManagerEmail = dto.generalManagerEmail;
-    if (dto.generalManagerPhone !== undefined)
-      attrUpdates.generalManagerPhone = normalizeE164(dto.generalManagerPhone);
+    if (dto.ownerName !== undefined) attrUpdates.ownerName = dto.ownerName;
+    if (dto.ownerEmail !== undefined) attrUpdates.ownerEmail = dto.ownerEmail;
+    if (dto.ownerPhone !== undefined)
+      attrUpdates.ownerPhone = normalizeE164(dto.ownerPhone);
     if (dto.poaName !== undefined) attrUpdates.poaName = dto.poaName;
     if (dto.poaPhone !== undefined)
       attrUpdates.poaPhone = normalizeE164(dto.poaPhone);
@@ -829,11 +819,29 @@ export class CompaniesService {
     if (dto.etradePhone !== undefined)
       companyUpdates.etradePhone = normalizeE164(dto.etradePhone);
 
-    // A plain typed field — never Fayda-verified, so no lock ever applies to
-    // it. Independent of the owner's verification: still required for a
-    // foreign company even if the owner also verifies with Fayda.
+    // Plain typed fields — never Fayda-verified, so no lock ever applies. For a
+    // foreign company a passport number proves the person just as a Fayda
+    // verification does, so it is collected for whichever of the two carries
+    // the company's identity.
     if (dto.ownerPassportNumber !== undefined)
       attrUpdates.ownerPassportNumber = dto.ownerPassportNumber;
+    if (dto.poaPassportNumber !== undefined)
+      attrUpdates.poaPassportNumber = dto.poaPassportNumber;
+
+    // eTrade's own manager, captured at lookup by `applyEtradeSourcedFields`.
+    // Never off the wire — the global pipe runs `forbidNonWhitelisted`, so this
+    // reaches us only from that method, the same guarantee `faydaIdentity` has.
+    // Stored apart from `ownerName`/`ownerPhone` so the two can be COMPARED:
+    // the company asserts an owner, eTrade states a manager, and the backoffice
+    // check is whether they are the same person (`ownerMatchesEtrade`).
+    if (dto.etradeManager) {
+      if (dto.etradeManager.name)
+        attrUpdates[ETRADE_MANAGER_NAME_KEY] = dto.etradeManager.name;
+      if (dto.etradeManager.phone)
+        attrUpdates[ETRADE_MANAGER_PHONE_KEY] = normalizeE164(
+          dto.etradeManager.phone,
+        );
+    }
 
     // A verified identity overwrites the person's details. `faydaIdentity`
     // never comes off the wire — the global validation pipe runs with
@@ -844,19 +852,17 @@ export class CompaniesService {
       Object.assign(attrUpdates, dto.faydaIdentity);
     }
 
-    // Keyed on the verified VALUE, not on `ownerFaydaSub`: Fayda's email and
-    // phone claims are optional, so a verification can prove the person while
-    // supplying neither (see completeIdentityVerification's conditional
-    // spreads). The portal falls back to the account email / eTrade's
-    // registered phone in exactly that case and submits it on every save of
-    // the company step — locking against an absent value would 400 that
-    // forever, and re-verifying could never clear it because Fayda still has
-    // nothing to return.
-    if (attrUpdates.ownerFaydaSub) {
-      if (attrUpdates.ownerEmail) companyUpdates.email = attrUpdates.ownerEmail;
-      if (attrUpdates.ownerPhone)
-        companyUpdates.phone = normalizeE164(String(attrUpdates.ownerPhone));
-    }
+    // The company's own contact columns follow the owner, verified or not.
+    //
+    // This used to be gated on `ownerFaydaSub`, which meant `companies.email`
+    // was only ever written for a Fayda-verified owner — so every foreign
+    // company (passport instead of Fayda) had none, and the notification
+    // resolver papered over it by falling through to the general manager's
+    // address. The GM is gone and the owner's email is now required outright,
+    // so this is simply where it lands.
+    if (attrUpdates.ownerEmail) companyUpdates.email = attrUpdates.ownerEmail;
+    if (attrUpdates.ownerPhone)
+      companyUpdates.phone = normalizeE164(String(attrUpdates.ownerPhone));
 
     // Renaming a Fayda-verified person by hand would launder the guarantee
     // away, so the verification keeps these fields: a submission that disagrees
@@ -874,12 +880,10 @@ export class CompaniesService {
         if (dto.faydaIdentity && field in dto.faydaIdentity) continue;
         const stored = company.attributes?.[field];
         // A verification that supplied nothing for this field left no guarantee
-        // to protect, so it stays typeable. Matters most for the GM —
-        // `setGmSameAsOwner` copies `ownerEmail ?? null` onto
-        // `generalManagerEmail` while setting `gmFaydaSub`, and
-        // REQUIRED_COMPANY_INFO still demands that email, so holding a null
-        // here makes it required, hidden by the portal's "same as owner" card,
-        // and unwritable all at once.
+        // to protect, so it stays typeable. This is what makes the required
+        // owner email reachable: Fayda's email claim is optional, so a verified
+        // owner routinely has none stored — locking against that absence would
+        // make `REQUIRED_COMPANY_INFO` demand a field nobody could ever fill.
         if (stored === null || stored === undefined || stored === "") continue;
         attrUpdates[field] = stored;
       }
@@ -965,9 +969,7 @@ export class CompaniesService {
     if (POA_ATTRIBUTES.some((k) => dto[k] !== undefined)) {
       const attributes = this.mapProfileDtoToCompanyUpdates(company, dto)
         .attributes as Record<string, unknown>;
-      await this.assertPoaDelegationSatisfied(company.id, attributes, {
-        requirePoa: await this.isFreightForwarder(company.id),
-      });
+      await this.assertPoaDelegationSatisfied(company, attributes);
     }
 
     if (company.status !== CompanyStatus.Active) {
@@ -1615,12 +1617,13 @@ export class CompaniesService {
       // the last place it has to be checked — the role may have been applied
       // for before the paper was withdrawn.
       if (company && existing.type === ProfileType.freightForwarder) {
-        this.assertIdentityVerified(company, { requirePoa: true });
-        await this.assertPoaDelegationSatisfied(
-          company.id,
-          company.attributes,
-          { requirePoa: true },
-        );
+        // The row was loaded FOR UPDATE, so its relations are not populated —
+        // and `readPoaDeclaration` reads `companyProfiles` to force "yes" for a
+        // forwarder. This IS the forwarder profile being approved, so naming it
+        // is enough (and truthful) for both assertions below.
+        company.companyProfiles = company.companyProfiles ?? [existing];
+        this.assertIdentityVerified(company);
+        await this.assertPoaDelegationSatisfied(company, company.attributes);
       }
 
       const [companyDocs, profileDocs] = await Promise.all([
@@ -1884,11 +1887,11 @@ export class CompaniesService {
       // without a Power of Attorney and its DARS paper — checked here so the
       // customer is told at the point of asking, not at review.
       if (type === ProfileType.freightForwarder) {
-        this.assertIdentityVerified(company, { requirePoa: true });
+        const asForwarder = this.withProfileType(company, type);
+        this.assertIdentityVerified(asForwarder);
         await this.assertPoaDelegationSatisfied(
-          companyId,
+          asForwarder,
           await this.effectivePoaAttributes(company),
-          { requirePoa: true },
         );
       }
 
@@ -1930,11 +1933,11 @@ export class CompaniesService {
 
     let created = await this.companyProfilesRepo.findByType(companyId, type);
     if (!created && type === ProfileType.freightForwarder) {
-      this.assertIdentityVerified(company, { requirePoa: true });
+      const asForwarder = this.withProfileType(company, type);
+      this.assertIdentityVerified(asForwarder);
       await this.assertPoaDelegationSatisfied(
-        companyId,
+        asForwarder,
         await this.effectivePoaAttributes(company),
-        { requirePoa: true },
       );
     }
     if (!created) {
@@ -2028,33 +2031,26 @@ export class CompaniesService {
     );
     const missingLicenses = licenseProfiles.filter((p) => !p.uploaded);
 
-    // 4. Power of Attorney. Optional in general, but a freight forwarder acts on
-    // other companies' behalf so its PoA is mandatory. Either way, a PoA that
-    // has been entered must be evidenced by the DARS delegation paper — a legal
-    // requirement, so unlike the documents above it does not depend on the
-    // upload set carrying a field for it (see poa-delegation.constants.ts).
-    const poaRequired = (company.companyProfiles ?? []).some(
-      (p) => p.type === ProfileType.freightForwarder,
-    );
-    const poaProvided = POA_ATTRIBUTES.some((k) =>
-      (company.attributes?.[k] as string | undefined)?.trim(),
-    );
+    // 4. Power of Attorney. Whether there is one at all is the company's own
+    // declaration — the question the wizard asks outright — and that answer is
+    // what decides whose identity gets verified, so an unanswered one is itself
+    // outstanding. A freight forwarder never gets to answer: it signs on other
+    // companies' behalf, so `readPoaDeclaration` forces "yes".
+    //
+    // Once there IS a representative, their details and the DARS delegation
+    // paper are both due. The paper is a legal requirement, so unlike the
+    // documents above it does not depend on the upload set carrying a field for
+    // it (see poa-delegation.constants.ts).
+    const poaDue = identity.poaDeclared === "yes";
     const delegation = await this.getPoaDelegationState(company.id);
-    // "There is a representative" and "a paper is owed for them" used to be the
-    // same condition. They part company once the owner represents the company
-    // themselves: the representative's details are still required, but nobody
-    // delegates to themselves, so no DARS paper is due (`assertPoaDelegationSatisfied`
-    // returns on the same flag — the two must agree).
-    const poaDue = poaRequired || poaProvided;
-    const delegationDue = poaDue && !identity.poaSameAsOwner;
+    const delegationDue = poaDue;
     // The representative's details normally arrive from their Fayda
     // verification — but Fayda's email and phone claims are optional and
     // routinely come back empty, and the PoA step renders an input for whatever
     // the verification did not supply. So these are askable after all, and are
-    // reported outstanding once a PoA is required or provided; reporting
-    // nothing here let a freight forwarder finish onboarding with a
-    // representative the API's own `REQUIRED_POA_FIELDS` calls incomplete, then
-    // 400'd their next PoA edit for it.
+    // reported outstanding once a PoA is declared; reporting nothing here let a
+    // freight forwarder finish onboarding with a representative the API's own
+    // `REQUIRED_POA_FIELDS` calls incomplete, then 400'd their next PoA edit.
     const missingPoaFields = poaDue
       ? REQUIRED_POA_FIELDS.filter(
         (f) => !(company.attributes?.[f.key] as string | undefined)?.trim(),
@@ -2065,10 +2061,15 @@ export class CompaniesService {
     // replace it before the application counts as complete.
     const flaggedDelegation = delegationDue && delegation.flagged;
 
-    // Mirrors `poaProven` in buildCompanyIdentityState — see the note there.
-    const poaProven = identity.faydaRequired
-      ? identity.poa.verified
-      : identity.poa.verified || Boolean(identity.poa.name?.trim());
+    // 5. The single identity. Who proves it is `identity.subject`; how they may
+    // prove it is nationality-dependent (Fayda always, a passport number as an
+    // alternative for a foreign company). Both are derived once in
+    // buildCompanyIdentityState so this list can never disagree with the gate
+    // `assertIdentityVerified` actually enforces.
+    const identitySubjectLabel =
+      identity.subject === "poa"
+        ? "your Power of Attorney"
+        : "the person named on your eTrade licence";
 
     const outstanding = [
       ...missingInfo.map((f) => `Add your ${f.label.toLowerCase()}`),
@@ -2086,58 +2087,38 @@ export class CompaniesService {
           `Re-upload your ${POA_DELEGATION_LABEL} — EDR asked for a correction`,
         ]
         : []),
-      ...(identity.faydaRequired && !identity.owner.verified
-        ? ["Verify the company owner's identity with Fayda"]
+      ...(identity.poaDeclared === null
+        ? ["Tell us whether anyone holds power of attorney for your company"]
         : []),
-      // Nationality-aware, exactly like `poaProven` in
-      // buildCompanyIdentityState and the check in `assertIdentityVerified`:
-      // Fayda is an Ethiopian national ID, so a foreign company's typed
-      // representative has to count. Demanding a verification here regardless
-      // made this list disagree with the rule actually enforced, and left a
-      // foreign freight forwarder unable to submit — asked for a Fayda
-      // verification its representative may have no way to obtain.
-      ...((poaRequired || poaProvided) && !poaProven
+      ...(identity.poaDeclared !== null && !identity.identityProven
         ? [
-          identity.faydaRequired
-            ? "Verify your Power of Attorney's identity with Fayda"
-            : "Name your Power of Attorney, or verify them with Fayda",
+          identity.passportAccepted
+            ? `Verify ${identitySubjectLabel} with Fayda, or add their passport number`
+            : `Verify ${identitySubjectLabel} with Fayda`,
         ]
         : []),
-      ...(identity.passportRequired && !identity.owner.passportNumber
-        ? ["Add the company owner's passport number"]
-        : []),
     ];
 
     // Progress spans every required item the user has to satisfy: company-info
-    // fields, required documents, one license per operational profile, and the
-    // PoA details/paper whenever those are mandatory.
+    // fields, required documents, one license per operational profile, the PoA
+    // details/paper once declared, and the two identity items — answering the
+    // declaration, and proving the person it points at.
     const requiredDocCount = documents.filter((d) => d.isRequired).length;
     // The delegation paper plus the representative's own required details —
     // `completed` below subtracts every one of those it is still missing, so
     // leaving them out of the total would make the bar understate progress.
     const poaItemCount =
       (poaDue ? REQUIRED_POA_FIELDS.length : 0) + (delegationDue ? 1 : 0);
-    // One item per identity credential the company has to prove: the owner
-    // always (Fayda for Ethiopian, passport for foreign), plus the PoA once
-    // there is one — Fayda for an Ethiopian company, a named representative
-    // for a foreign one, same rule as `poaProven` above. Counting a foreign
-    // company's typed PoA as unproven here left the progress bar permanently
-    // short of 100% on an item it had already satisfied.
-    const ownerCredentialDue =
-      identity.faydaRequired || identity.passportRequired;
-    const ownerCredentialProven = identity.faydaRequired
-      ? identity.owner.verified
-      : Boolean(identity.owner.passportNumber);
-    const identityItemCount = (ownerCredentialDue ? 1 : 0) + (poaDue ? 1 : 0);
     const missingIdentityCount =
-      (ownerCredentialDue && !ownerCredentialProven ? 1 : 0) +
-      (poaDue && !poaProven ? 1 : 0);
+      (identity.poaDeclared === null ? 1 : 0) +
+      (identity.identityProven ? 0 : 1);
     const total =
       requiredInfo.length +
       requiredDocCount +
       licenseProfiles.length +
       poaItemCount +
-      identityItemCount;
+      // The declaration and the verification it selects.
+      2;
     const completed =
       total -
       (missingInfo.length +
@@ -2157,8 +2138,12 @@ export class CompaniesService {
       documents,
       licenseProfiles,
       poa: {
-        required: poaRequired,
-        provided: poaProvided,
+        // "Locked" rather than "required": a freight forwarder is not asked the
+        // question at all, everyone else answers it themselves.
+        locked: identity.poaDeclared === "yes" && (company.companyProfiles ?? []).some(
+          (p) => p.type === ProfileType.freightForwarder,
+        ),
+        declared: identity.poaDeclared,
         delegationLetterRequired: delegationDue,
         delegationLetterUploaded: delegation.onFile,
         delegationLetterFlagged: delegation.flagged,
@@ -2689,39 +2674,44 @@ export class CompaniesService {
    * judged against the files that would survive it (`ignoreFileIds`).
    */
   private async assertPoaDelegationSatisfied(
-    companyId: string,
+    company: Company,
     attributes: Record<string, unknown> | null | undefined,
-    opts: { requirePoa: boolean; ignoreFileIds?: string[] },
+    opts: { ignoreFileIds?: string[] } = {},
   ): Promise<void> {
+    // The declaration is the whole gate. A company that says it has no
+    // representative owes nothing here; one that says it has owes the details
+    // AND the paper, with no exceptions — including a freight forwarder, for
+    // whom `readPoaDeclaration` forces "yes" regardless of what is stored.
+    const declared = readPoaDeclaration({
+      attributes: attributes as Company["attributes"],
+      companyProfiles: company.companyProfiles,
+    });
+    if (declared !== "yes") return;
+
+    const isForwarder = (company.companyProfiles ?? []).some(
+      (p) => p.type === ProfileType.freightForwarder,
+    );
     const read = (key: string) =>
       (attributes?.[key] as string | undefined)?.trim();
-    const poaProvided = POA_ATTRIBUTES.some((k) => read(k));
-    if (!opts.requirePoa && !poaProvided) return;
 
-    if (opts.requirePoa) {
-      const missing = REQUIRED_POA_FIELDS.filter((f) => !read(f.key));
-      if (missing.length > 0) {
-        throw new BadRequestException(
-          `A freight forwarder acts on other companies' behalf, so a Power of Attorney is required. ` +
-          `Add the ${missing.map((f) => f.label.toLowerCase()).join(", ")} first.`,
-        );
-      }
+    const missing = REQUIRED_POA_FIELDS.filter((f) => !read(f.key));
+    if (missing.length > 0) {
+      throw new BadRequestException(
+        (isForwarder
+          ? "A freight forwarder acts on other companies' behalf, so a Power of Attorney is required. "
+          : "You told us someone holds power of attorney for this company. ") +
+        `Add the ${missing.map((f) => f.label.toLowerCase()).join(", ")} first.`,
+      );
     }
 
-    // Nobody delegates to themselves: an owner representing their own company
-    // has no delegation to evidence, so the DARS paper is not owed. The
-    // representative's own details are still required above — a forwarder's
-    // counterparties need someone to contact either way.
-    if (attributes?.poaSameAsOwner) return;
-
     const { onFile, flagged } = await this.getPoaDelegationState(
-      companyId,
+      company.id,
       opts.ignoreFileIds,
     );
     if (!onFile) {
       throw new BadRequestException(
         `Upload the ${POA_DELEGATION_LABEL} for the Power of Attorney` +
-        (opts.requirePoa ? " — it is required for freight forwarders." : "."),
+        (isForwarder ? " — it is required for freight forwarders." : "."),
       );
     }
     if (flagged) {
@@ -2732,54 +2722,145 @@ export class CompaniesService {
     }
   }
 
-  /** Does this company operate as a freight forwarder? */
-  private async isFreightForwarder(companyId: string): Promise<boolean> {
-    const profiles = await this.companyProfilesRepo.findByCompanyId(companyId);
-    return profiles.some((p) => p.type === ProfileType.freightForwarder);
-  }
-
   // ---------------------------------------------------------------------------
-  // Fayda identity verification (owner / PoA)
+  // Identity verification (one per company)
   //
-  // A completed VeriFayda verification proves a person's name, phone, email
-  // and address — Fayda's userinfo carries no national ID number, so none of
-  // that is collected here. For an Ethiopian company both the owner and its
-  // PoA (once named) must be verified before the company can trade. Fayda is
-  // an Ethiopian national ID system, so a foreign company's owner proves
-  // identity with a typed passport number instead — required on its own
-  // terms, not waived by an owner who happens to verify with Fayda too.
+  // A company proves itself through exactly ONE person. Which one is its own
+  // declaration: the Power of Attorney when it names a representative,
+  // otherwise the owner — whoever the eTrade licence names as the business's
+  // manager. There is no general manager and no "same as owner" copy: an owner
+  // who represents their own company simply answers "no, nobody holds power of
+  // attorney", and verifies as the owner.
+  //
+  // A completed VeriFayda verification proves that person's name, phone, email
+  // and address (Fayda's userinfo carries no national ID number, so none is
+  // collected). Fayda is an Ethiopian national ID, so a foreign company may
+  // instead type a passport number for the same person — an alternative, not an
+  // addition.
   // ---------------------------------------------------------------------------
 
   /**
-   * Verification state for both people, plus whether it is mandatory here.
-   * `complete` answers the gate question directly so the portal, the onboarding
-   * requirements and the assertions below all read the same verdict — the
-   * derivation itself is shared with ProfileResponseDto.
+   * The company's identity state: both people, who currently carries the
+   * verification, whether it is proven, and whether the owner the company put
+   * forward matches the eTrade licence. `complete` answers the gate question
+   * directly so the portal, the onboarding requirements and the assertions
+   * above all read the same verdict — the derivation itself is shared with
+   * ProfileResponseDto and the backoffice company DTO.
    */
   getCompanyIdentityState(company: Company): CompanyIdentityStateDto {
     return buildCompanyIdentityState(company);
   }
 
   /**
-   * Complete a Fayda verification and bind the identity to one of the company's
-   * people. The portal starts the flow through the shared
+   * Record whether anyone holds power of attorney for this company.
+   *
+   * This is the question that decides whose identity gets verified, so it is
+   * stored rather than inferred from "are any `poa*` keys set" — absence means
+   * "not asked yet", which is an outstanding onboarding item in its own right.
+   *
+   * Answering "no" tears the representative down: their details, their
+   * verification, their passport number and the DARS paper evidencing them all
+   * go. Leaving any of it behind would keep the company on the hook for a
+   * delegation it has just said does not exist.
+   *
+   * Refused for a freight forwarder — it signs on other companies' behalf, so a
+   * representative is non-negotiable. (`readPoaDeclaration` forces "yes" for
+   * them anyway; this is the honest error rather than a silently ignored write.)
+   */
+  async setPoaDeclared(
+    userId: string,
+    declared: PoaDeclaration,
+  ): Promise<CompanyIdentityStateDto> {
+    const { company } = await this.getCompanyInfoByUserId(userId);
+
+    if (
+      declared === "no" &&
+      (company.companyProfiles ?? []).some(
+        (p) => p.type === ProfileType.freightForwarder,
+      )
+    ) {
+      throw new BadRequestException(
+        "A freight forwarder acts on other companies' behalf, so it must have a Power of Attorney. Remove the freight forwarder role first.",
+      );
+    }
+
+    const attributes: Record<string, unknown> = {
+      ...(company.attributes ?? {}),
+      [POA_DECLARED_KEY]: declared,
+    };
+
+    if (declared === "no") {
+      for (const key of [
+        ...POA_ATTRIBUTES,
+        "poaFaydaSub",
+        "poaFaydaVerifiedAt",
+        "poaBirthdate",
+        "poaGender",
+        "poaPassportNumber",
+      ]) {
+        attributes[key] = null;
+      }
+      await this.deletePoaDelegationFiles(company.id);
+    }
+
+    const updated = await this.companiesRepo.update(company.id, { attributes });
+    if (!updated)
+      throw new NotFoundException(`Company ${company.id} not found`);
+    updated.companyProfiles = company.companyProfiles;
+    return this.getCompanyIdentityState(updated);
+  }
+
+  /** Drop every DARS paper on file — the delegation it evidenced is gone. */
+  private async deletePoaDelegationFiles(companyId: string): Promise<void> {
+    const records = await this.filesService.findByResource(
+      companyId,
+      COMPANY_RESOURCE,
+    );
+    for (const r of records) {
+      if (
+        r.code === POA_DELEGATION_FILE_KEY ||
+        r.code === POA_DELEGATION_PENDING_CODE
+      ) {
+        await this.filesService.remove(r.id);
+        await this.withdrawDocumentIntent(companyId, r.id);
+      }
+    }
+  }
+
+  /**
+   * Complete a Fayda verification and bind the identity to the company.
+   *
+   * The portal starts the flow through the shared
    * `POST /fayda/verification/start` and only tells us which person it was for
    * here, at completion — so the verifayda module stays generic and its session
    * table needs no company-specific column.
+   *
+   * The subject has to be the one the company's declaration calls for. A
+   * verification bound to the other person would sit on the record looking
+   * proven while the gate — which reads only the declared subject — stayed
+   * unsatisfied, and nothing in the portal would explain why.
    */
   async completeIdentityVerification(
     userId: string,
     dto: CompleteIdentityVerificationDto,
-    /**
-     * The signed-in account, used as the owner's fallback contact details.
-     * Optional so the callers that only have a user id keep compiling — they
-     * simply get no fallback.
-     */
-    account?: { email?: string; phoneNumber?: string },
   ): Promise<CompanyIdentityStateDto> {
     const { company } = await this.getCompanyInfoByUserId(userId);
+    const state = buildCompanyIdentityState(company);
     const prefix = IDENTITY_PREFIX[dto.subject];
 
+    if (state.subject === null) {
+      throw new BadRequestException(
+        "Tell us whether anyone holds power of attorney for this company first — the answer decides whose identity we verify.",
+      );
+    }
+    if (state.subject !== dto.subject) {
+      throw new BadRequestException(
+        state.subject === "poa"
+          ? "This company is represented by a Power of Attorney, so it is their identity we need — not the owner's."
+          : "This company has no Power of Attorney, so it is the owner's identity we need.",
+      );
+    }
+
     const result = await this.verifaydaService.completeVerification({
       code: dto.code,
       state: dto.state,
@@ -2790,71 +2871,38 @@ export class CompaniesService {
       );
     }
 
-    // An owner who is also the company's representative is a supported answer,
-    // not a conflict — the same way the GM is very often the owner. Small
-    // companies routinely have one human in all three roles, and the portal's
-    // "same as owner" cards exist precisely so they can say so. No identity
-    // here is refused for colliding with another.
-
-    const now = new Date().toISOString();
-
-    // Fayda's email and phone claims are optional and routinely come back empty.
-    // For the owner that leaves the company with no contact details at all: the
-    // step renders no input for them (they are the verification's output), and
-    // "same as owner" then copies those blanks onto `generalManagerEmail` /
-    // `generalManagerPhone`, which `REQUIRED_COMPANY_INFO` demands at submit —
-    // an unfixable dead end. The account doing the onboarding is the one contact
-    // we always have, and it is already OTP-proven, so it stands in.
+    // Only what Fayda actually returned is written. Its email and phone claims
+    // are optional and routinely come back empty — the portal renders an input
+    // for whatever is missing and the customer fills it in.
     //
-    // Owner only: the PoA and the GM are other people, and the registering
-    // account's address is not theirs to wear.
-    const isOwner = dto.subject === "owner";
-    const email = result.email || (isOwner ? account?.email : undefined);
-    const phone =
-      result.phoneNumber || (isOwner ? account?.phoneNumber : undefined);
-
+    // There is deliberately NO fallback to the signed-in account. The person
+    // onboarding is not necessarily the person on the licence, so stamping
+    // their address onto the owner turned a required field into a guess that
+    // looked verified.
     const identity: VerifiedIdentityAttributes = {
       [`${prefix}FaydaSub`]: result.sub,
-      [`${prefix}FaydaVerifiedAt`]: now,
+      [`${prefix}FaydaVerifiedAt`]: new Date().toISOString(),
       [`${prefix}Birthdate`]: result.birthdate ?? null,
       [`${prefix}Gender`]: result.gender ?? null,
       // The verified payload owns the person's details from here on.
       ...(result.fullName ? { [`${prefix}Name`]: result.fullName } : {}),
-      ...(email ? { [`${prefix}Email`]: email } : {}),
+      ...(result.email ? { [`${prefix}Email`]: result.email } : {}),
       // Fayda returns whatever the national registry holds, which is routinely a
       // local number ("0911223344"). Every typed phone in this service is stored
       // E.164, and `@IsValidPhone()` rejects anything else — so a raw claim here
       // becomes a value the portal reads back and cannot resubmit.
-      ...(phone ? { [`${prefix}Phone`]: normalizeE164(phone) } : {}),
+      ...(result.phoneNumber
+        ? { [`${prefix}Phone`]: normalizeE164(result.phoneNumber) }
+        : {}),
       ...(result.address ? { [`${prefix}Address`]: result.address } : {}),
     };
 
-    // A GM verification also lands on the typed columns the rest of the system
-    // already reads (the booking, train-scheduling and contract notifiers all
-    // mail `generalManagerEmail`), and clears any earlier "same as owner"
-    // declaration — verifying in their own right is the GM answering for
-    // themselves.
-    // Verifying the representative in their own right answers the question the
-    // "same as owner" declaration answered, so the declaration goes.
-    if (dto.subject === "poa") {
-      identity.poaSameAsOwner = false;
-    }
-
-    if (dto.subject === "gm") {
-      identity.gmSameAsOwner = false;
-      if (result.fullName) identity.generalManagerName = result.fullName;
-      if (result.email) identity.generalManagerEmail = result.email;
-      if (result.phoneNumber)
-        identity.generalManagerPhone = normalizeE164(result.phoneNumber);
-    }
-
-    // An approved company's *owner* is its identity proof, so re-verifying one
-    // is staged for backoffice review rather than quietly rewriting a live
-    // record. The PoA and GM are personnel — the company names its own
-    // representative and manager, and the delegation letter backing the PoA is
-    // what the reviewer sees — so those land live, matching their typed
-    // counterparts in `SELF_SERVICE_ATTRIBUTES`.
-    if (company.status === CompanyStatus.Active && dto.subject === "owner") {
+    // An approved company's identity is what its approval rested on, so
+    // re-verifying is staged for backoffice review rather than quietly
+    // rewriting a live record. Both subjects go through review now: whichever
+    // one the declaration points at IS the company's proof, and the owner is
+    // additionally the person the reviewer checks against the eTrade licence.
+    if (company.status === CompanyStatus.Active) {
       await this.stageIdentityChange(company, userId, identity);
       return this.getCompanyIdentityState(company);
     }
@@ -2868,261 +2916,6 @@ export class CompaniesService {
     return this.getCompanyIdentityState(updated);
   }
 
-  /**
-   * Declare that the General Manager is the company's owner.
-   *
-   * The GM is very often the owner, and making that human verify twice buys
-   * nothing — the owner's verification already proves them. So this copies the
-   * owner's verified identity across rather than starting a second flow, and
-   * records `gmSameAsOwner` so the portal can show it as a declaration rather
-   * than as a verification the GM passed in their own right.
-   *
-   * Refused until the owner is actually verified: without that there is no
-   * proven identity to copy, only typed text that would arrive wearing a
-   * verified badge.
-   */
-  async setGmSameAsOwner(
-    userId: string,
-    /** Same fallback as {@link completeIdentityVerification}, for owners
-     * verified before that fallback existed — their stored contact details are
-     * blank, and copying blanks here would block the submit. */
-    account?: { email?: string; phoneNumber?: string },
-  ): Promise<CompanyIdentityStateDto> {
-    const { company } = await this.getCompanyInfoByUserId(userId);
-    const attrs = company.attributes ?? {};
-    const ownerSub = attrs.ownerFaydaSub as string | undefined;
-    if (!ownerSub) {
-      throw new BadRequestException(
-        "Verify the company owner with Fayda first — there is no proven identity to reuse yet.",
-      );
-    }
-
-    const ownerEmail = (attrs.ownerEmail as string | undefined) || account?.email || null;
-    const ownerPhone = (attrs.ownerPhone as string | undefined) || account?.phoneNumber || null;
-
-    const copied: Record<string, unknown> = {
-      gmSameAsOwner: true,
-      gmFaydaSub: ownerSub,
-      gmFaydaVerifiedAt: attrs.ownerFaydaVerifiedAt ?? new Date().toISOString(),
-      gmName: attrs.ownerName ?? null,
-      gmEmail: ownerEmail,
-      gmPhone: ownerPhone ? normalizeE164(ownerPhone) : null,
-      gmAddress: attrs.ownerAddress ?? null,
-      gmBirthdate: attrs.ownerBirthdate ?? null,
-      gmGender: attrs.ownerGender ?? null,
-      // Kept in step for the notifiers, same as a GM verification does.
-      generalManagerName: attrs.ownerName ?? null,
-      generalManagerEmail: ownerEmail,
-      generalManagerPhone: ownerPhone ? normalizeE164(ownerPhone) : null,
-    };
-
-    const updated = await this.companiesRepo.update(company.id, {
-      attributes: { ...attrs, ...copied },
-    });
-    if (!updated)
-      throw new NotFoundException(`Company ${company.id} not found`);
-    updated.companyProfiles = company.companyProfiles;
-    return this.getCompanyIdentityState(updated);
-  }
-
-  /**
-   * Undo the "same as owner" declaration, clearing the copied identity so the
-   * GM can be verified in their own right (or typed, where Fayda is optional).
-   */
-  async clearGmIdentity(userId: string): Promise<CompanyIdentityStateDto> {
-    const { company } = await this.getCompanyInfoByUserId(userId);
-    const attrs = { ...(company.attributes ?? {}) };
-    for (const key of [
-      "gmSameAsOwner",
-      "gmFaydaSub",
-      "gmFaydaVerifiedAt",
-      "gmName",
-      "gmEmail",
-      "gmPhone",
-      "gmAddress",
-      "gmBirthdate",
-      "gmGender",
-      ...GM_TYPED_FIELDS,
-    ]) {
-      attrs[key] = null;
-    }
-
-    const updated = await this.companiesRepo.update(company.id, {
-      attributes: attrs,
-    });
-    if (!updated)
-      throw new NotFoundException(`Company ${company.id} not found`);
-    updated.companyProfiles = company.companyProfiles;
-    return this.getCompanyIdentityState(updated);
-  }
-
-  /**
-   * Declare that the company's Power of Attorney is its owner.
-   *
-   * An owner representing their own company is the ordinary case for a small
-   * business, so this is a supported answer rather than the conflict it used to
-   * be refused as. Two shapes, matching {@link setGmSameAsOwner}:
-   *
-   * - A Fayda-verified owner is a proven identity, so it is copied outright —
-   *   the representative inherits the verification instead of the same human
-   *   being sent through Fayda a second time.
-   * - A foreign company's owner is backed by a typed passport, so there is
-   *   nothing proven to copy. The declaration is still recorded (it is what
-   *   waives the DARS paper) and whatever owner details exist come across; the
-   *   portal types the rest, which `poaProven` accepts for a foreign company.
-   *
-   * Refused for an Ethiopian company whose owner is not verified yet: Fayda is
-   * mandatory for its representative, so a declaration there would record a
-   * representative that could never satisfy the gate.
-   */
-  async setPoaSameAsOwner(
-    userId: string,
-    /** Same fallback as {@link completeIdentityVerification} — an owner whose
-     * Fayda claims carried no email/phone has none stored, and copying blanks
-     * onto a freight forwarder's PoA would block the submit on
-     * `REQUIRED_POA_FIELDS`. */
-    account?: { email?: string; phoneNumber?: string },
-  ): Promise<CompanyIdentityStateDto> {
-    const { company } = await this.getCompanyInfoByUserId(userId);
-    const attrs = company.attributes ?? {};
-    const state = buildCompanyIdentityState(company);
-    const ownerSub = attrs.ownerFaydaSub as string | undefined;
-
-    if (state.faydaRequired && !ownerSub) {
-      throw new BadRequestException(
-        "Verify the company owner with Fayda first — there is no proven identity to reuse yet.",
-      );
-    }
-
-    const ownerEmail = (attrs.ownerEmail as string | undefined) || account?.email;
-    const ownerPhone =
-      (attrs.ownerPhone as string | undefined) || account?.phoneNumber;
-
-    // Only non-blank values are copied: a blank here would overwrite something
-    // the portal typed for a foreign company, whose owner has no verified
-    // claims to draw on.
-    const copied: Record<string, unknown> = { poaSameAsOwner: true };
-    const copy = (key: string, value: unknown) => {
-      if (value !== null && value !== undefined && value !== "")
-        copied[key] = value;
-    };
-    copy("poaName", attrs.ownerName);
-    copy("poaEmail", ownerEmail);
-    copy("poaPhone", ownerPhone ? normalizeE164(ownerPhone) : undefined);
-    copy("poaAddress", attrs.ownerAddress);
-
-    if (ownerSub) {
-      copied.poaFaydaSub = ownerSub;
-      copied.poaFaydaVerifiedAt =
-        attrs.ownerFaydaVerifiedAt ?? new Date().toISOString();
-      copy("poaBirthdate", attrs.ownerBirthdate);
-      copy("poaGender", attrs.ownerGender);
-    }
-
-    const updated = await this.companiesRepo.update(company.id, {
-      attributes: { ...attrs, ...copied },
-    });
-    if (!updated)
-      throw new NotFoundException(`Company ${company.id} not found`);
-    updated.companyProfiles = company.companyProfiles;
-    return this.getCompanyIdentityState(updated);
-  }
-
-  /**
-   * Undo the PoA "same as owner" declaration, clearing the identity it copied
-   * so a different representative can be verified (or typed, for a foreign
-   * company).
-   *
-   * Separate from {@link removePoaIdentity}, which drops the representative and
-   * their paper and is refused to a freight forwarder. Undoing a declaration is
-   * how a forwarder changes its mind about who represents it, so it must stay
-   * open to them — the submit gate still refuses a forwarder that never names a
-   * replacement. The delegation paper is left alone for the same reason: the
-   * company still owes one, now for whoever comes next.
-   *
-   * A no-op when no declaration is in place: a stray call must not wipe a
-   * representative who verified in their own right.
-   */
-  async clearPoaSameAsOwner(userId: string): Promise<CompanyIdentityStateDto> {
-    const { company } = await this.getCompanyInfoByUserId(userId);
-    const attrs = { ...(company.attributes ?? {}) };
-    if (!attrs.poaSameAsOwner) return this.getCompanyIdentityState(company);
-
-    attrs.poaSameAsOwner = false;
-    for (const key of [
-      ...POA_ATTRIBUTES,
-      "poaFaydaSub",
-      "poaFaydaVerifiedAt",
-      "poaBirthdate",
-      "poaGender",
-    ]) {
-      attrs[key] = null;
-    }
-
-    const updated = await this.companiesRepo.update(company.id, {
-      attributes: attrs,
-    });
-    if (!updated)
-      throw new NotFoundException(`Company ${company.id} not found`);
-    updated.companyProfiles = company.companyProfiles;
-    return this.getCompanyIdentityState(updated);
-  }
-
-  /**
-   * Drop the Power of Attorney entirely — the verified identity, the details it
-   * wrote and the delegation paper together.
-   *
-   * Only the PoA can go: a company always has an owner, and a freight forwarder
-   * always has a representative. Once a PoA is Fayda-verified its
-   * fields are locked, so blanking the form is no longer a way out — without
-   * this the customer would be stuck with a representative they cannot remove.
-   */
-  async removePoaIdentity(userId: string): Promise<CompanyIdentityStateDto> {
-    const { company } = await this.getCompanyInfoByUserId(userId);
-    if (
-      (company.companyProfiles ?? []).some(
-        (p) => p.type === ProfileType.freightForwarder,
-      )
-    ) {
-      throw new BadRequestException(
-        "A freight forwarder must have a Power of Attorney. Remove the freight forwarder role first.",
-      );
-    }
-
-    const cleared: Record<string, unknown> = { poaSameAsOwner: false };
-    for (const key of [
-      ...POA_ATTRIBUTES,
-      "poaFaydaSub",
-      "poaFaydaVerifiedAt",
-      "poaBirthdate",
-      "poaGender",
-    ]) {
-      cleared[key] = null;
-    }
-    const attributes = { ...(company.attributes ?? {}), ...cleared };
-
-    // The paper evidences a representative who no longer exists.
-    const records = await this.filesService.findByResource(
-      company.id,
-      COMPANY_RESOURCE,
-    );
-    for (const r of records) {
-      if (
-        r.code === POA_DELEGATION_FILE_KEY ||
-        r.code === POA_DELEGATION_PENDING_CODE
-      ) {
-        await this.filesService.remove(r.id);
-        await this.withdrawDocumentIntent(company.id, r.id);
-      }
-    }
-
-    const updated = await this.companiesRepo.update(company.id, { attributes });
-    if (!updated)
-      throw new NotFoundException(`Company ${company.id} not found`);
-    updated.companyProfiles = company.companyProfiles;
-    return this.getCompanyIdentityState(updated);
-  }
-
   /** Stage a verified identity onto the company's pending change request. */
   private async stageIdentityChange(
     company: Company,
@@ -3171,62 +2964,56 @@ export class CompaniesService {
   }
 
   /**
-   * The gate: an Ethiopian company's owner must be Fayda-verified, and so must
-   * its Power of Attorney once it has one; a foreign company's owner must carry
-   * a passport number instead. Called from the same places as
-   * `assertPoaDelegationSatisfied` — the two rules describe the same moment
-   * (who may act for this company, and on what evidence) and drifting them
-   * apart is how one of them ends up unenforced.
+   * The company as it will be once `type` is one of its roles.
+   *
+   * Taking on the freight-forwarder role is checked BEFORE the profile row
+   * exists, and both assertions below read `companyProfiles` — a forwarder is
+   * what forces the PoA declaration to "yes". Judging the company as it stands
+   * would let one that answered "no" pick up the role and skip the very
+   * requirement the role exists to impose. Read-only; never persisted.
    */
-  private assertIdentityVerified(
-    company: Company,
-    opts: { requirePoa: boolean },
-  ): void {
+  private withProfileType(company: Company, type: ProfileType): Company {
+    const profiles = company.companyProfiles ?? [];
+    if (profiles.some((p) => p.type === type)) return company;
+    return {
+      ...company,
+      companyProfiles: [...profiles, { type } as CompanyProfile],
+    } as Company;
+  }
+
+  /**
+   * The gate: the company's ONE identity must be proven.
+   *
+   * Which person that is comes from the company's own declaration — the
+   * representative when it names one, otherwise the owner (whoever the eTrade
+   * licence names as manager). How they prove it depends on nationality: Fayda
+   * for an Ethiopian company, Fayda *or* a typed passport number for a foreign
+   * one, whose people may hold no Fayda ID at all.
+   *
+   * Called from the same places as `assertPoaDelegationSatisfied` — the two
+   * rules describe the same moment (who may act for this company, and on what
+   * evidence) and drifting them apart is how one of them ends up unenforced.
+   */
+  private assertIdentityVerified(company: Company): void {
     const state = buildCompanyIdentityState(company);
 
-    // Only the owner's credential is nationality-specific: Fayda for an
-    // Ethiopian company, a typed passport number for a foreign one.
-    if (state.passportRequired) {
-      if (!state.owner.passportNumber) {
-        throw new BadRequestException(
-          "Add the company owner's passport number before continuing.",
-        );
-      }
-    } else if (!state.owner.verified) {
+    if (state.poaDeclared === null) {
       throw new BadRequestException(
-        "Verify the company owner's identity with Fayda before continuing.",
+        "Tell us whether anyone holds power of attorney for this company — the answer decides whose identity we verify.",
       );
     }
 
-    const poaNamed = POA_ATTRIBUTES.some((k) =>
-      (company.attributes?.[k] as string | undefined)?.trim(),
+    if (state.identityProven) return;
+
+    const who =
+      state.subject === "poa"
+        ? "your Power of Attorney"
+        : "the person named on your eTrade licence";
+    throw new BadRequestException(
+      state.passportAccepted
+        ? `Verify ${who} with Fayda, or add their passport number.`
+        : `Verify ${who} with Fayda before continuing.`,
     );
-    if (!opts.requirePoa && !poaNamed) return;
-
-    // Fayda is an Ethiopian national ID, so only an Ethiopian company's
-    // representative can be held to it. A foreign company is offered the
-    // verification and nominates a Fayda-holding representative where it can,
-    // but a typed name has to remain sufficient — otherwise a foreign company
-    // whose representative holds no Fayda ID could never trade at all. Mirrors
-    // `poaProven` in buildCompanyIdentityState; the two must agree.
-    if (state.passportRequired) {
-      if (!state.poa.verified && !state.poa.name?.trim()) {
-        throw new BadRequestException(
-          opts.requirePoa
-            ? "Name your Power of Attorney — a freight forwarder cannot operate without one."
-            : "Complete the Power of Attorney you named, or remove the representative.",
-        );
-      }
-      return;
-    }
-
-    if (!state.poa.verified) {
-      throw new BadRequestException(
-        opts.requirePoa
-          ? "Verify your Power of Attorney with Fayda — a freight forwarder cannot operate without one."
-          : "Verify the Power of Attorney you named with Fayda, or remove the representative.",
-      );
-    }
   }
 
   /**
@@ -3350,12 +3137,9 @@ export class CompaniesService {
     // the representative it evidences is gone too (which, for an Active
     // company, means the clearing edit is already staged).
     await this.assertPoaDelegationSatisfied(
-      company.id,
+      company,
       await this.effectivePoaAttributes(company),
-      {
-        requirePoa: await this.isFreightForwarder(company.id),
-        ignoreFileIds: [fileId],
-      },
+      { ignoreFileIds: [fileId] },
     );
 
     if (record.code === POA_DELEGATION_PENDING_CODE) {
@@ -3583,7 +3367,7 @@ export class CompaniesService {
    */
   private async applyEtradeSourcedFields(
     company: Company,
-    dto: UpdateProfileDto,
+    dto: UpdateProfileDto & { etradeManager?: { name: string; phone: string } },
   ): Promise<void> {
     const touched = ETRADE_SOURCED_FIELDS.some(
       (key) => key !== "tin" && dto[key] !== undefined,
@@ -3626,5 +3410,18 @@ export class CompaniesService {
       // (the onboarding/settings card lets the customer type it directly then).
       if (value) (dto as Record<string, unknown>)[key] = value;
     }
+
+    // Capture the licence's own manager alongside the registration it belongs
+    // to. NOT written onto `ownerName`/`ownerPhone`: those are what the company
+    // asserts (and what a Fayda verification owns), and overwriting them here
+    // would destroy the very difference the backoffice is asked to check. The
+    // portal prefills the owner from these, so they agree unless someone made
+    // them disagree — which is exactly the case worth surfacing.
+    if (registration.managerName || registration.managerPhone) {
+      dto.etradeManager = {
+        name: registration.managerName,
+        phone: registration.managerPhone,
+      };
+    }
   }
 }
diff --git a/apps/edr-freight-api/src/modules/companies/company-revision-diff.util.ts b/apps/edr-freight-api/src/modules/companies/company-revision-diff.util.ts
index 83fa539e3..71b60a268 100644
--- a/apps/edr-freight-api/src/modules/companies/company-revision-diff.util.ts
+++ b/apps/edr-freight-api/src/modules/companies/company-revision-diff.util.ts
@@ -23,9 +23,18 @@ export const COMPANY_FIELD_LABELS: Record<string, string> = {
   contactPersonPhone: "Contact person phone",
   contactPersonEmail: "Contact person email",
   contactPersonPosition: "Contact person position",
-  generalManagerName: "General manager name",
-  generalManagerPhone: "General manager phone",
-  generalManagerEmail: "General manager email",
+  ownerName: "Owner name",
+  ownerPhone: "Owner phone",
+  ownerEmail: "Owner email",
+  ownerPassportNumber: "Owner passport number",
+  poaPassportNumber: "PoA passport number",
+  poaDeclared: "Has a Power of Attorney",
+  // Nothing writes these any more (the general manager was removed), but
+  // revisions and change requests filed before that still carry them — without
+  // the labels those rows render raw attribute keys to a reviewer.
+  generalManagerName: "General manager name (retired)",
+  generalManagerPhone: "General manager phone (retired)",
+  generalManagerEmail: "General manager email (retired)",
   poaName: "PoA name",
   poaPhone: "PoA phone",
   poaEmail: "PoA email",
diff --git a/apps/edr-freight-api/src/modules/companies/dto/complete-identity-verification.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/complete-identity-verification.dto.ts
index df39949d4..6fe1ecc74 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/complete-identity-verification.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/complete-identity-verification.dto.ts
@@ -5,21 +5,61 @@ import { Company, CompanyNationality } from "../entities/company.entity";
 import { ProfileType } from "../entities/company-profile.entity";
 
 /**
- * The three people a company is verified through — its owner, its Power of
- * Attorney and its General Manager. The owner is the person the company's
- * existence is proven by; the other two are personnel it names.
+ * The two people a company can be described through.
  *
- * The GM is very often the owner, which is what the portal's "same as owner"
- * copy is for: that path reuses the owner's verified identity outright rather
- * than asking the same human to verify twice.
+ * The **owner** is whoever the eTrade TIN record names as the business's
+ * manager. Not necessarily the legal owner — eTrade's `ManagerNameEng` is
+ * simply the person on the licence — but that is the point: whoever the company
+ * puts forward here has to match the eTrade record, and the backoffice check is
+ * exactly that comparison (see `ownerMatchesEtrade`).
+ *
+ * The **Power of Attorney** is who the company delegates to act for it, when it
+ * delegates at all.
+ *
+ * Exactly ONE of them is identity-verified, and which one is decided by the
+ * company's own answer (see {@link PoaDeclaration}): the representative if
+ * there is one, otherwise the owner. There is no general manager — the concept
+ * was removed; it named who to talk to and gated nothing.
  */
-export const IDENTITY_SUBJECTS = ["owner", "poa", "gm"] as const;
+export const IDENTITY_SUBJECTS = ["owner", "poa"] as const;
 export type IdentitySubject = (typeof IDENTITY_SUBJECTS)[number];
 
+/**
+ * The company's answer to "does anyone hold power of attorney for you?".
+ *
+ * Explicit rather than derived from "are any `poa*` keys set", because "no" is
+ * an answer that moves the verification onto the owner, while *absent* is a
+ * question the customer has not reached yet. Stored on `company.attributes`
+ * under {@link POA_DECLARED_KEY}.
+ *
+ * A freight forwarder never gets to answer: it signs on other companies'
+ * behalf, so a Power of Attorney (and the DARS paper evidencing it) is
+ * non-negotiable. {@link readPoaDeclaration} forces "yes" for them, which is
+ * why the declaration is read through that helper rather than off the blob.
+ */
+export const POA_DECLARATIONS = ["yes", "no"] as const;
+export type PoaDeclaration = (typeof POA_DECLARATIONS)[number];
+
+/** `company.attributes` key holding the {@link PoaDeclaration}. */
+export const POA_DECLARED_KEY = "poaDeclared";
+
+/**
+ * `company.attributes` keys holding the eTrade record's own manager, captured
+ * at lookup time.
+ *
+ * Kept apart from `ownerName`/`ownerPhone` — which are what the *company*
+ * asserts, and what a Fayda verification overwrites — precisely so the two can
+ * be compared. Storing only one value would leave the reviewer comparing the
+ * owner field against itself.
+ */
+export const ETRADE_MANAGER_NAME_KEY = "etradeManagerName";
+export const ETRADE_MANAGER_PHONE_KEY = "etradeManagerPhone";
+
 export class CompleteIdentityVerificationDto {
   @ApiProperty({
     enum: IDENTITY_SUBJECTS,
-    description: "Which of the company's people this verification is for.",
+    description:
+      "Which of the company's people this verification is for. Must match the company's PoA declaration — the representative when one is named, the owner when not.",
   })
   @IsIn(IDENTITY_SUBJECTS)
   subject!: IdentitySubject;
@@ -35,9 +75,11 @@ export class CompleteIdentityVerificationDto {
   state!: string;
 }
 
-/** One person's verification state, as reported back to the portal. */
+/** One person's identity state, as reported back to the portal. */
 export class IdentityVerificationStateDto {
-  @ApiProperty() verified!: boolean;
+  @ApiProperty({ description: "True once a Fayda verification is bound." })
+  verified!: boolean;
+
   @ApiProperty({ nullable: true }) name!: string | null;
   @ApiProperty({ nullable: true }) phone!: string | null;
   @ApiProperty({ nullable: true }) email!: string | null;
@@ -45,13 +87,11 @@ export class IdentityVerificationStateDto {
   @ApiProperty({ nullable: true }) verifiedAt!: string | null;
   @ApiProperty({ nullable: true }) birthdate!: string | null;
   @ApiProperty({ nullable: true }) gender!: string | null;
-}
 
-export class OwnerIdentityStateDto extends IdentityVerificationStateDto {
   @ApiProperty({
     nullable: true,
     description:
-      "Typed passport number — the foreign-company identity credential. Independent of Fayda: never written by a verification, and still required even if the owner also verifies.",
+      "Typed passport number. Fayda is an Ethiopian national ID, so a foreign company proves the identity with either — this is the alternative, not an addition.",
   })
   passportNumber!: string | null;
 }
@@ -59,44 +99,55 @@ export class OwnerIdentityStateDto extends IdentityVerificationStateDto {
 export class CompanyIdentityStateDto {
   @ApiProperty({
     description:
-      "True when Fayda verification of the owner (and PoA, once named) is mandatory — Ethiopian companies only.",
+      "True for a foreign company: a typed passport number proves the identity just as a Fayda verification does. An Ethiopian company must use Fayda.",
   })
-  faydaRequired!: boolean;
+  passportAccepted!: boolean;
 
   @ApiProperty({
+    enum: POA_DECLARATIONS,
+    nullable: true,
     description:
-      "True when the owner's passport number is mandatory — foreign companies only. Independent of faydaRequired: a foreign owner may verify with Fayda too, but the passport is still required.",
+      'Whether the company named a Power of Attorney. Null until the customer answers — which is itself an outstanding onboarding item, since the answer decides who verifies.',
   })
-  passportRequired!: boolean;
+  poaDeclared!: PoaDeclaration | null;
 
-  @ApiProperty({ type: OwnerIdentityStateDto })
-  owner!: OwnerIdentityStateDto;
+  @ApiProperty({
+    enum: IDENTITY_SUBJECTS,
+    nullable: true,
+    description:
+      "Who the company's single identity verification belongs to: the PoA when one is named, the owner when not. Null while the declaration is unanswered.",
+  })
+  subject!: IdentitySubject | null;
+
+  @ApiProperty({ type: IdentityVerificationStateDto })
+  owner!: IdentityVerificationStateDto;
 
   @ApiProperty({ type: IdentityVerificationStateDto })
   poa!: IdentityVerificationStateDto;
 
   @ApiProperty({
     description:
-      "True when the Power of Attorney is the company's owner, declared through the portal's \"same as owner\" copy. Waives the DARS delegation paper — nobody delegates to themselves.",
+      "True once the subject is proven — Fayda-verified, or carrying a passport number where that is accepted.",
   })
-  poaSameAsOwner!: boolean;
+  identityProven!: boolean;
 
   @ApiProperty({
-    type: IdentityVerificationStateDto,
+    nullable: true,
     description:
-      "General manager. `verified` is true both when the GM verified with Fayda in their own right and when the company declared the GM is the owner — in the latter case the owner's Fayda sub backs it.",
+      "The manager named on the eTrade licence, captured at lookup. Null when eTrade returned none (ManagerNameEng is frequently blank).",
   })
-  gm!: IdentityVerificationStateDto;
+  etradeManagerName!: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    description:
+      "Does the owner the company put forward match the person on the eTrade licence? This is the backoffice's check. Null when there is nothing to compare — no eTrade manager on file, or no owner name yet. Advisory, not a gate: eTrade's Latin transliteration and Fayda's rarely agree character-for-character, so a reviewer decides.",
+  })
+  ownerMatchesEtrade!: boolean | null;
 
   @ApiProperty({
     description:
-      "True when the GM's identity is the owner's, declared through the portal's \"same as owner\" copy rather than a separate verification.",
-  })
-  gmSameAsOwner!: boolean;
-
-  @ApiProperty({
-    description:
-      "False while a mandatory requirement (Fayda for Ethiopian, passport for foreign) is still outstanding.",
+      "False while the declaration is unanswered or the subject is unproven. Field-level completeness (owner/PoA details, documents) is reported separately by the onboarding requirements.",
   })
   complete!: boolean;
 }
@@ -105,26 +156,9 @@ export class CompanyIdentityStateDto {
 const PREFIX: Record<IdentitySubject, string> = {
   owner: "owner",
   poa: "poa",
-  gm: "gm",
 };
 
-/**
- * Typed GM fields, kept in step with the Fayda-written ones.
- *
- * The GM predates this verification: its details are plain company columns
- * that three notifier services mail (booking-lifecycle, train-scheduling and
- * contract notifiers all read `company.generalManagerEmail`). A verification
- * therefore writes BOTH — the `gm*` attributes carry the proof, these carry
- * the value everything else already reads — and an unverified company keeps
- * showing whatever was typed before this existed.
- */
-const GM_TYPED_KEYS = {
-  name: "generalManagerName",
-  email: "generalManagerEmail",
-  phone: "generalManagerPhone",
-} as const;
-
-/** company.attributes keys that together mean "a PoA was entered". */
+/** `company.attributes` keys that together mean "a representative was entered". */
 const POA_KEYS = [
   "poaName",
   "poaPhone",
@@ -139,7 +173,7 @@ function stateFor(
 ): IdentityVerificationStateDto {
   const p = PREFIX[subject];
   const read = (key: string) => (attrs[key] as string | undefined) ?? null;
-  const state: IdentityVerificationStateDto = {
+  return {
     verified: Boolean(read(`${p}FaydaSub`)),
     name: read(`${p}Name`),
     phone: read(`${p}Phone`),
@@ -148,88 +182,111 @@ function stateFor(
     verifiedAt: read(`${p}FaydaVerifiedAt`),
     birthdate: read(`${p}Birthdate`),
     gender: read(`${p}Gender`),
-  };
-  if (subject !== "gm" || state.verified) return state;
-
-  // Companies onboarded before the GM was verifiable have typed details and no
-  // `gm*` attributes at all. Report those rather than a blank card — they are
-  // still what the notifiers mail — leaving `verified` false so the portal
-  // offers the upgrade instead of pretending the identity is proven.
-  //
-  // Only for such an unverified GM, which is the whole population this exists
-  // for. Merging the typed columns into a *verified* manager's state would read
-  // back the email the portal asked them to type when Fayda supplied none, and
-  // the input offering it — keyed on that value being absent — would vanish the
-  // moment it was saved, leaving a typo uncorrectable.
-  return {
-    ...state,
-    name: state.name ?? read(GM_TYPED_KEYS.name),
-    email: state.email ?? read(GM_TYPED_KEYS.email),
-    phone: state.phone ?? read(GM_TYPED_KEYS.phone),
+    passportNumber: read(`${p}PassportNumber`),
   };
 }
 
 /**
- * Derive both people's verification state from the company row.
+ * The company's PoA declaration, or null when it hasn't answered yet.
  *
- * Pure and shared: `CompaniesService` gates on it and `ProfileResponseDto`
- * renders from it, so the settings page and the onboarding wizard can never
- * disagree with the rule the API actually enforces.
+ * A freight forwarder is never asked: it acts on other companies' behalf, so a
+ * representative and the DARS paper behind them are mandatory. Forcing it here
+ * — rather than only disabling the radio in the portal — is what stops a
+ * forwarder role added *after* onboarding from inheriting an old "no".
+ */
+export function readPoaDeclaration(
+  company: Pick<Company, "attributes" | "companyProfiles">,
+): PoaDeclaration | null {
+  if (
+    (company.companyProfiles ?? []).some(
+      (p) => p.type === ProfileType.freightForwarder,
+    )
+  ) {
+    return "yes";
+  }
+  const value = company.attributes?.[POA_DECLARED_KEY];
+  if (value === "yes" || value === "no") return value;
+
+  // No explicit answer, but the company holds a representative's details —
+  // so it has one, and owes everything a representative brings with them.
+  //
+  // Covers rows that predate the question (the migration derives the same way)
+  // and any write that reaches the attributes without going through
+  // `setPoaDeclared`. Without this, PoA details could be saved with the
+  // delegation paper silently unowed. Safe against a genuine "no": answering
+  // it clears these keys, so they cannot outlive the answer.
+  return POA_KEYS.some((k) => (company.attributes?.[k] as string | undefined)?.trim())
+    ? "yes"
+    : null;
+}
+
+/**
+ * Do two people's names refer to the same person, as far as a string can tell?
+ *
+ * Deliberately loose: eTrade returns uppercase Latin transliterations of
+ * Amharic names and Fayda returns its own, so exact equality would flag almost
+ * every company. Case, punctuation, extra whitespace and word ORDER are all
+ * ignored — "ABEBE KEBEDE TESFA" and "Tesfa, Abebe Kebede" match. Anything
+ * beyond that is the reviewer's call, which is why the verdict is advisory.
+ */
+export function ownerNameMatchesEtrade(
+  ownerName: string | null | undefined,
+  etradeName: string | null | undefined,
+): boolean | null {
+  const words = (v: string | null | undefined) =>
+    (v ?? "")
+      .toLowerCase()
+      .replace(/[^a-z0-9ሀ-፿\s]/g, " ")
+      .split(/\s+/)
+      .filter(Boolean)
+      .sort();
+  const a = words(ownerName);
+  const b = words(etradeName);
+  if (a.length === 0 || b.length === 0) return null;
+  return a.length === b.length && a.every((w, i) => w === b[i]);
+}
+
+/**
+ * Derive the company's identity state from its row.
+ *
+ * Pure and shared: `CompaniesService` gates on it, `ProfileResponseDto` and the
+ * backoffice's company DTO render from it, so the settings page, the onboarding
+ * wizard and the reviewer can never disagree with the rule the API enforces.
  */
 export function buildCompanyIdentityState(
   company: Company,
 ): CompanyIdentityStateDto {
   const attrs = company.attributes ?? {};
-  const read = (key: string) => (attrs[key] as string | undefined) ?? null;
 
-  // Fayda is an Ethiopian national ID — a foreign company's owner may not hold
-  // one, so a typed passport number is the mandatory credential there instead.
-  // The two are mutually exclusive by nationality but independently tracked,
-  // since a foreign owner verifying with Fayda doesn't waive the passport.
-  const foreign = company.nationality === CompanyNationality.Foreign;
-  const faydaRequired = !foreign;
-  const passportRequired = foreign;
+  // Fayda is an Ethiopian national ID. A foreign company's people may hold
+  // none, so a typed passport number stands in — either one proves the person,
+  // and holding both is fine.
+  const passportAccepted = company.nationality === CompanyNationality.Foreign;
 
-  const owner: OwnerIdentityStateDto = {
-    ...stateFor(attrs, "owner"),
-    passportNumber: read("ownerPassportNumber"),
-  };
+  const owner = stateFor(attrs, "owner");
   const poa = stateFor(attrs, "poa");
-  const poaDue =
-    (company.companyProfiles ?? []).some(
-      (p) => p.type === ProfileType.freightForwarder,
-    ) || POA_KEYS.some((k) => (attrs[k] as string | undefined)?.trim());
+  const poaDeclared = readPoaDeclaration(company);
+  const subject: IdentitySubject | null =
+    poaDeclared === "yes" ? "poa" : poaDeclared === "no" ? "owner" : null;
 
-  const gm = stateFor(attrs, "gm");
-  const gmSameAsOwner = Boolean(attrs.gmSameAsOwner);
-  const poaSameAsOwner = Boolean(attrs.poaSameAsOwner);
+  const proven = (s: IdentityVerificationStateDto) =>
+    s.verified || (passportAccepted && Boolean(s.passportNumber?.trim()));
 
-  const ownerProven = faydaRequired
-    ? owner.verified
-    : !passportRequired || Boolean(owner.passportNumber);
+  const identityProven =
+    subject === null ? false : proven(subject === "poa" ? poa : owner);
 
-  // Fayda is an Ethiopian national ID, so only an Ethiopian company's
-  // personnel can be held to it. A foreign company may nominate a
-  // representative who holds one — and is offered the verification — but a
-  // typed name has to remain sufficient, or a foreign company whose PoA has no
-  // Fayda ID could never finish onboarding.
-  const poaProven = faydaRequired
-    ? poa.verified
-    : poa.verified || Boolean(poa.name?.trim());
-
-  // The GM is deliberately absent from this verdict: it names who to talk to,
-  // not what the company may do, and it has never gated trading. Capturing it
-  // through Fayda changes how it is collected, not whether it is required.
-  const complete = ownerProven && (!poaDue || poaProven);
+  const etradeManagerName =
+    (attrs[ETRADE_MANAGER_NAME_KEY] as string | undefined) ?? null;
 
   return {
-    faydaRequired,
-    passportRequired,
+    passportAccepted,
+    poaDeclared,
+    subject,
     owner,
     poa,
-    poaSameAsOwner,
-    gm,
-    gmSameAsOwner,
-    complete,
+    identityProven,
+    etradeManagerName,
+    ownerMatchesEtrade: ownerNameMatchesEtrade(owner.name, etradeManagerName),
+    complete: subject !== null && identityProven,
   };
 }
diff --git a/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts
index 9b69bb15d..b1baa2553 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts
@@ -8,7 +8,10 @@
  * truth the wizard uses to auto-finish.
  */
 
-import { CompanyIdentityStateDto } from "./complete-identity-verification.dto";
+import {
+  CompanyIdentityStateDto,
+  PoaDeclaration,
+} from "./complete-identity-verification.dto";
 
 export interface OnboardingInfoField {
   key: string;
@@ -38,15 +41,19 @@ export interface OnboardingLicenseProfile {
 }
 
 export interface OnboardingPoaState {
-  /** True when the company operates as a freight forwarder — PoA is mandatory. */
-  required: boolean;
-  /** True once any PoA detail has been entered. */
-  provided: boolean;
   /**
-   * True when the DARS delegation paper is owed — a PoA exists (or is
-   * mandatory) and is not the owner themselves. An owner representing their own
-   * company delegates to nobody, so there is no delegation to evidence.
+   * True when the company operates as a freight forwarder: it signs on other
+   * companies' behalf, so a Power of Attorney is non-negotiable and the portal
+   * renders the question answered and locked rather than asking it.
    */
+  locked: boolean;
+  /**
+   * The company's answer to "does anyone hold power of attorney for you?".
+   * Null until it answers — which is itself outstanding, since the answer
+   * decides whose identity is verified.
+   */
+  declared: PoaDeclaration | null;
+  /** True when the DARS delegation paper is owed — i.e. `declared === "yes"`. */
   delegationLetterRequired: boolean;
   /** True when the DARS delegation paper is stored for the company. */
   delegationLetterUploaded: boolean;
diff --git a/apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts
index a70c52b5d..dc2ddc4c3 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts
@@ -42,9 +42,10 @@ export class ProfileResponseDto {
   contactPersonPhone: string | null;
   /** Phone that passed SMS OTP verification (drives the verify-step resume). */
   contactVerifiedPhone: string | null;
-  generalManagerName: string | null;
-  generalManagerEmail: string | null;
-  generalManagerPhone: string | null;
+  /** The owner — whoever the eTrade licence names as the business's manager. */
+  ownerName: string | null;
+  ownerEmail: string | null;
+  ownerPhone: string | null;
 
   poaName: string | null;
   poaPhone: string | null;
@@ -55,12 +56,13 @@ export class ProfileResponseDto {
   profileId: string;
 
   /**
-   * Fayda verification state for the company's owner and PoA — not the general
-   * manager, which is a separate typed role. The settings tabs and the
-   * onboarding wizard render from `identity.faydaRequired` /
-   * `identity.passportRequired`: an Ethiopian company verifies the owner (and
-   * PoA) instead of typing their details; a foreign one requires a typed
-   * passport number instead.
+   * The company's single identity verification, plus who it belongs to.
+   *
+   * `identity.subject` follows the company's PoA declaration — the
+   * representative when one is named, otherwise the owner. The settings tabs
+   * and the onboarding wizard render from it: `passportAccepted` says whether a
+   * typed passport number is an alternative to Fayda (foreign companies only),
+   * and `ownerMatchesEtrade` is the check the backoffice makes.
    */
   identity: CompanyIdentityStateDto;
 
@@ -113,9 +115,9 @@ export class ProfileResponseDto {
     this.contactPersonEmail = attrs.contactPersonEmail ?? null;
     this.contactPersonPhone = attrs.contactPersonPhone ?? null;
     this.contactVerifiedPhone = attrs.contactVerifiedPhone ?? null;
-    this.generalManagerName = attrs.generalManagerName ?? null;
-    this.generalManagerEmail = attrs.generalManagerEmail ?? null;
-    this.generalManagerPhone = attrs.generalManagerPhone ?? null;
+    this.ownerName = attrs.ownerName ?? null;
+    this.ownerEmail = attrs.ownerEmail ?? null;
+    this.ownerPhone = attrs.ownerPhone ?? null;
     this.poaName = attrs.poaName ?? null;
     this.poaPhone = attrs.poaPhone ?? null;
     this.poaEmail = attrs.poaEmail ?? null;
diff --git a/apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts
index d705e7323..b78925285 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts
@@ -89,9 +89,14 @@ export class ResponseCompanyDto {
   houseNo?: string | null;
 
   /**
-   * Owner/PoA Fayda verification state, shared with the portal
-   * (`buildCompanyIdentityState`) so backoffice never re-derives — or
-   * disagrees with — the rule the API actually enforces.
+   * The company's single identity verification, shared with the portal
+   * (`buildCompanyIdentityState`) so backoffice never re-derives — or disagrees
+   * with — the rule the API actually enforces.
+   *
+   * `subject` names whose verification it is (the PoA when one is declared,
+   * otherwise the owner), and `ownerMatchesEtrade` is the reviewer's check:
+   * does the owner the company put forward match the manager on the eTrade
+   * licence? Advisory — see the note on that field.
    */
   identity: CompanyIdentityStateDto;
 
diff --git a/apps/edr-freight-api/src/modules/companies/dto/set-poa-declared.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/set-poa-declared.dto.ts
new file mode 100644
index 000000000..37c54b254
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/companies/dto/set-poa-declared.dto.ts
@@ -0,0 +1,17 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsIn } from "class-validator";
+
+import {
+  POA_DECLARATIONS,
+  PoaDeclaration,
+} from "./complete-identity-verification.dto";
+
+export class SetPoaDeclaredDto {
+  @ApiProperty({
+    enum: POA_DECLARATIONS,
+    description:
+      'Whether anyone holds power of attorney for this company. "no" tears down any representative already recorded.',
+  })
+  @IsIn(POA_DECLARATIONS)
+  declared!: PoaDeclaration;
+}
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 c89326fa1..b7b814da1 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
@@ -45,11 +45,11 @@ export class UpdateProfileDto {
   @Matches(/^\d{10,11}$/, { message: "VAT number must be 10 or 11 digits" })
   vatNumber?: string;
 
-  // `fanNumber` is deliberately absent: the FAN is the Fayda number of the
-  // company's PoA (or its general manager), so it is derived from a completed
-  // Fayda verification rather than typed. The global validation pipe runs with
-  // forbidNonWhitelisted, so a client that still sends it gets a 400 telling it
-  // so — see CompaniesService.completeIdentityVerification.
+  // `fanNumber` is deliberately absent: the FAN is a Fayda number, so it would
+  // have to come from a completed verification rather than be typed — and
+  // Fayda's userinfo carries no national ID number, so nothing produces one.
+  // The global validation pipe runs with forbidNonWhitelisted, so a client that
+  // still sends it gets a 400 telling it so.
 
   @IsOptional()
   @IsString()
@@ -78,18 +78,31 @@ export class UpdateProfileDto {
   @IsValidPhone()
   contactVerifiedPhone?: string;
 
+  /**
+   * The owner — whoever the eTrade licence names as the business's manager.
+   *
+   * All three are required before onboarding can be submitted, whatever their
+   * source: the eTrade lookup prefills the name and phone, a Fayda
+   * verification can supply all three, and the portal renders an input for
+   * whatever neither did (eTrade returns no email at all, and Fayda's email
+   * claim is optional, so that one is usually typed).
+   *
+   * Locked once a Fayda verification supplied them — see
+   * `IDENTITY_OWNED_FIELDS` — but only field by field: a claim that came back
+   * empty owns nothing and stays typeable.
+   */
   @IsOptional()
   @IsString()
-  generalManagerName?: string;
+  ownerName?: string;
 
   @IsOptional()
   @IsEmail()
-  generalManagerEmail?: string;
+  ownerEmail?: string;
 
   @IsOptional()
   @IsString()
   @IsValidPhone()
-  generalManagerPhone?: string;
+  ownerPhone?: string;
 
   @IsOptional()
   @IsString()
@@ -113,15 +126,22 @@ export class UpdateProfileDto {
   poaAddress?: string;
 
   /**
-   * The owner's passport number — the identity credential for a foreign
-   * company, since Fayda is an Ethiopian national ID. Plain typed field, never
-   * written or locked by a Fayda verification: still required even if the
-   * owner also verifies.
+   * Passport numbers — the alternative identity credential for a foreign
+   * company, since Fayda is an Ethiopian national ID. Plain typed fields, never
+   * written or locked by a Fayda verification.
+   *
+   * Only the one belonging to the company's declared identity subject matters:
+   * the PoA's when a representative is named, the owner's otherwise. An
+   * Ethiopian company is not offered either — it must use Fayda.
    */
   @IsOptional()
   @IsString()
   ownerPassportNumber?: string;
 
+  @IsOptional()
+  @IsString()
+  poaPassportNumber?: string;
+
   @IsOptional()
   @IsString()
   @MaxLength(100)
diff --git a/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts b/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts
index f254e0121..2ecfa3deb 100644
--- a/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts
+++ b/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts
@@ -112,29 +112,11 @@ export class Company extends BaseEntity {
   })
   contactPersonPhone?: string | null;
 
-  @Column({
-    name: "general_manager_name",
-    type: "varchar",
-    length: 100,
-    nullable: true,
-  })
-  generalManagerName?: string | null;
-
-  @Column({
-    name: "general_manager_email",
-    type: "varchar",
-    length: 150,
-    nullable: true,
-  })
-  generalManagerEmail?: string | null;
-
-  @Column({
-    name: "general_manager_phone",
-    type: "varchar",
-    length: 20,
-    nullable: true,
-  })
-  generalManagerPhone?: string | null;
+  // The general manager used to live here as three columns. It named who to
+  // talk to, gated nothing, and nothing ever populated the columns — the write
+  // path put the values in `attributes`. Removed in RemoveGeneralManager; the
+  // company's people are now its owner (whoever the eTrade licence names) and
+  // its Power of Attorney, both in `attributes`.
 
   @Column({ name: "website", type: "varchar", length: 200, nullable: true })
   website?: string | null;
diff --git a/apps/edr-freight-api/src/modules/notifications/resolve-company-phone.util.ts b/apps/edr-freight-api/src/modules/notifications/resolve-company-phone.util.ts
index 886aa8b85..104456384 100644
--- a/apps/edr-freight-api/src/modules/notifications/resolve-company-phone.util.ts
+++ b/apps/edr-freight-api/src/modules/notifications/resolve-company-phone.util.ts
@@ -12,8 +12,8 @@ import { DataSource, EntityManager } from "typeorm";
  * `companies.contact_person_phone` is deliberately NOT consulted: the live write
  * path stores that value in the `attributes` jsonb and has never populated the
  * column, so every reader of it was silently falling through to `phone` anyway.
- * `companies.general_manager_email` is the same trap on the email side — see
- * {@link companyNotifyEmailExpr}.
+ * The retired `general_manager_email` column was the same trap on the email
+ * side — see {@link companyNotifyEmailExpr}.
  */
 
 /**
@@ -50,24 +50,30 @@ export function companyNotifyPhoneExpr(alias: string): string {
  * SQL expression for the company's notification address, given the joined `pc`
  * alias.
  *
- * `companies.email` alone is not enough: it is written from ONE place — a
- * Fayda-verified owner's email claim — so a foreign company, whose owner proves
- * identity by passport instead, never gets one. Readers papered over that with
- * `COALESCE(email, general_manager_email)`, but that column has the same problem
- * `contact_person_phone` has above: onboarding writes the value into the
- * `attributes` jsonb and nothing has ever populated the column, so the fallback
- * could not fire and the mail was dropped in silence.
+ * `companies.email` is now the owner's email, written on every profile save
+ * whether or not the owner verified with Fayda — and the owner's email is a
+ * required onboarding field, so a company that finished onboarding has one.
+ * (It used to be written ONLY for a Fayda-verified owner, which meant every
+ * foreign company had none; the gap was papered over with a
+ * `general_manager_email` leg that could never fire, because onboarding wrote
+ * that value into `attributes` and nothing ever populated the column.)
  *
- * So: the company address, then the two the customer actually filled in during
- * onboarding, then the account that registered them — which always has one,
- * signup requires it. `NULLIF` because a blank jsonb key is not an address and
- * `COALESCE` would happily stop on it.
+ * The `generalManagerEmail` attribute is still consulted, after the contact
+ * person: the general manager was removed, but companies onboarded before that
+ * may carry an address there and nowhere else. RemoveGeneralManager backfills
+ * `companies.email` from it, so this is belt-and-braces for rows that migration
+ * could not resolve.
+ *
+ * `NULLIF` because a blank jsonb key is not an address and `COALESCE` would
+ * happily stop on it. The account that registered the company is the last
+ * resort — signup guarantees it has one.
  */
 export function companyNotifyEmailExpr(alias: string): string {
   return `COALESCE(
     NULLIF(${alias}.email, ''),
-    NULLIF(${alias}.attributes->>'generalManagerEmail', ''),
+    NULLIF(${alias}.attributes->>'ownerEmail', ''),
     NULLIF(${alias}.attributes->>'contactPersonEmail', ''),
+    NULLIF(${alias}.attributes->>'generalManagerEmail', ''),
     NULLIF(pc.email, '')
   )`;
 }
diff --git a/apps/edr-freight-api/src/scripts/seed-negad-indode-arrived-train.ts b/apps/edr-freight-api/src/scripts/seed-negad-indode-arrived-train.ts
index 9cf1ef0cd..174a32341 100644
--- a/apps/edr-freight-api/src/scripts/seed-negad-indode-arrived-train.ts
+++ b/apps/edr-freight-api/src/scripts/seed-negad-indode-arrived-train.ts
@@ -157,9 +157,6 @@ async function main() {
             email: 'negad-indode-demo@edr.local',
             contactPersonName: 'Marshalling Demo',
             contactPersonPhone: '251900000202',
-            generalManagerName: 'Demo Manager',
-            generalManagerEmail: 'negad-indode-demo@edr.local',
-            generalManagerPhone: '251900000202',
           }),
         ));
 
diff --git a/apps/edr-freight-api/src/seed/approved-first-lastmile-demo-bookings.seeder.ts b/apps/edr-freight-api/src/seed/approved-first-lastmile-demo-bookings.seeder.ts
index 2e234bcf0..91848dff4 100644
--- a/apps/edr-freight-api/src/seed/approved-first-lastmile-demo-bookings.seeder.ts
+++ b/apps/edr-freight-api/src/seed/approved-first-lastmile-demo-bookings.seeder.ts
@@ -247,9 +247,6 @@ export class ApprovedFirstLastMileDemoBookingsSeeder {
           website: null,
           contactPersonName: 'First Last Mile Demo',
           contactPersonPhone: '251900000101',
-          generalManagerName: 'Demo Manager',
-          generalManagerEmail: COMPANY_EMAIL,
-          generalManagerPhone: '251900000101',
         },
         { conflictPaths: { tin: true } },
       );
diff --git a/apps/edr-freight-api/src/seed/demo-bookings.seeder.ts b/apps/edr-freight-api/src/seed/demo-bookings.seeder.ts
index 20d2a3f8b..4f259c28c 100644
--- a/apps/edr-freight-api/src/seed/demo-bookings.seeder.ts
+++ b/apps/edr-freight-api/src/seed/demo-bookings.seeder.ts
@@ -324,9 +324,6 @@ export class DemoBookingsSeeder {
           website: null,
           contactPersonName: "Train Scheduling",
           contactPersonPhone: "251900000001",
-          generalManagerName: "Demo Manager",
-          generalManagerEmail: COMPANY_EMAIL,
-          generalManagerPhone: "251900000001",
         },
         { conflictPaths: { tin: true } },
       );
diff --git a/apps/edr-freight-api/src/seed/paid-import-export-mile-demo.seeder.ts b/apps/edr-freight-api/src/seed/paid-import-export-mile-demo.seeder.ts
index 654f4f77f..a658ec13d 100644
--- a/apps/edr-freight-api/src/seed/paid-import-export-mile-demo.seeder.ts
+++ b/apps/edr-freight-api/src/seed/paid-import-export-mile-demo.seeder.ts
@@ -175,9 +175,6 @@ export class PaidImportExportMileDemoSeeder {
           website: null,
           contactPersonName: 'Paid Mile Demo',
           contactPersonPhone: '251900000202',
-          generalManagerName: 'Demo Manager',
-          generalManagerEmail: COMPANY_EMAIL,
-          generalManagerPhone: '251900000202',
         },
         { conflictPaths: { tin: true } },
       );

From f611c337223ad36a2f491017a85933f90e65bc66 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 11 Aug 2026 11:53:36 +0000
Subject: [PATCH 017/174] feat(companies): migrate existing companies off the
 general manager
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Data rescue, not just schema tidying — the order matters:

1. Backfill companies.email from generalManagerEmail before the key is
   stripped, or companies whose only address lived there stop receiving mail.
2. Backfill ownerName/Email/Phone (now required) from owner, GM, contact
   person, then the columns; seed etradeManagerName so existing rows read as
   matching rather than as a false mismatch.
3. Convert poaSameAsOwner: non-forwarders become poaDeclared='no' with their
   poa* details cleared; forwarders become 'yes' and keep them, so they now
   owe a DARS letter they were previously waived.
4. Derive poaDeclared for everyone else.
5. Move drafts off the deleted 'personnel' wizard step.
6. Drop the general_manager_* columns and strip gm*/poaSameAsOwner.

down() restores the column shape only; the stripped values are gone by design.
---
 .../3390000000000-RemoveGeneralManager.ts     | 210 ++++++++++++++++++
 1 file changed, 210 insertions(+)
 create mode 100644 apps/edr-freight-api/src/migrations/3390000000000-RemoveGeneralManager.ts

diff --git a/apps/edr-freight-api/src/migrations/3390000000000-RemoveGeneralManager.ts b/apps/edr-freight-api/src/migrations/3390000000000-RemoveGeneralManager.ts
new file mode 100644
index 000000000..055c3771b
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3390000000000-RemoveGeneralManager.ts
@@ -0,0 +1,210 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Onboarding revamp: one company, one verified identity.
+ *
+ * The general manager is removed outright — it named who to talk to and gated
+ * nothing — and the company's people become its **owner** (whoever the eTrade
+ * licence names as the business's manager) and its **Power of Attorney**.
+ * Exactly one of them is identity-verified, chosen by the company's own answer
+ * to "does anyone hold power of attorney for you?", stored as
+ * `attributes.poaDeclared`.
+ *
+ * The order below matters — each step depends on data a later step destroys:
+ *
+ * 1. Rescue notification addresses. `companyNotifyEmailExpr` used to fall
+ *    through to `attributes->>'generalManagerEmail'`, and `companies.email` was
+ *    only ever written for a Fayda-verified owner — so every foreign company
+ *    had none and was reached solely through that fallback. Promote it to the
+ *    column before the key is stripped, or those companies stop receiving mail
+ *    in silence.
+ * 2. Backfill the owner. `ownerName`/`ownerEmail`/`ownerPhone` are now required
+ *    onboarding fields; without this every already-onboarded company would
+ *    report three missing fields the moment it opened its settings page.
+ * 3. Resolve `poaSameAsOwner`. That flag waived the DARS delegation paper. It
+ *    is gone, so the companies holding it must be re-expressed:
+ *      - NOT a freight forwarder → "no PoA" (the owner represents themselves,
+ *        nothing to delegate). Their PoA details are cleared.
+ *      - A freight forwarder → "yes" and details KEPT. A forwarder signs on
+ *        other companies' behalf, so a representative is non-negotiable and the
+ *        waiver no longer exists. These companies will be asked for a
+ *        delegation paper they were previously excused — an intentional,
+ *        visible consequence, not an oversight. Count them before deploying.
+ * 4. Derive the declaration for everyone else, from whether PoA details exist.
+ * 5. Move drafts off the deleted "personnel" wizard step.
+ * 6. Only now drop the columns and strip the retired attribute keys.
+ *
+ * Irreversible by design: `down()` restores the columns' shape but cannot
+ * recover the values, and re-deriving `poaSameAsOwner` from `poaDeclared` would
+ * be a guess.
+ */
+export class RemoveGeneralManager3390000000000 implements MigrationInterface {
+  name = "RemoveGeneralManager3390000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // 1. Rescue the notification address before the key it lives under is gone.
+    await queryRunner.query(`
+      UPDATE freight.companies
+      SET email = COALESCE(
+        NULLIF(email, ''),
+        NULLIF(attributes->>'ownerEmail', ''),
+        NULLIF(attributes->>'generalManagerEmail', ''),
+        NULLIF(attributes->>'contactPersonEmail', '')
+      )
+      WHERE COALESCE(email, '') = ''
+    `);
+
+    // 2. Backfill the owner from the best source each company actually has:
+    // its Fayda-verified owner claims (already under owner*), then the general
+    // manager it named, then its contact person. A company with none of these
+    // never finished onboarding, and will be asked on its next visit.
+    await queryRunner.query(`
+      UPDATE freight.companies
+      SET attributes = attributes
+        || jsonb_strip_nulls(jsonb_build_object(
+             'ownerName', COALESCE(
+               NULLIF(attributes->>'ownerName', ''),
+               NULLIF(attributes->>'generalManagerName', ''),
+               NULLIF(attributes->>'contactPersonName', '')
+             ),
+             'ownerEmail', COALESCE(
+               NULLIF(attributes->>'ownerEmail', ''),
+               NULLIF(attributes->>'generalManagerEmail', ''),
+               NULLIF(attributes->>'contactPersonEmail', ''),
+               NULLIF(email, '')
+             ),
+             'ownerPhone', COALESCE(
+               NULLIF(attributes->>'ownerPhone', ''),
+               NULLIF(attributes->>'generalManagerPhone', ''),
+               NULLIF(attributes->>'contactPersonPhone', ''),
+               NULLIF(phone, '')
+             )
+           ))
+      WHERE attributes IS NOT NULL
+    `);
+
+    // 2b. Capture eTrade's manager for the owner-vs-licence check the
+    // backoffice now makes. Nothing stored it before, so the best we have is
+    // the owner name itself — which makes existing companies read as "matches"
+    // rather than as a false mismatch on data nobody ever compared. The value
+    // is refreshed for real on the company's next eTrade lookup.
+    await queryRunner.query(`
+      UPDATE freight.companies
+      SET attributes = jsonb_set(
+            attributes, '{etradeManagerName}', to_jsonb(attributes->>'ownerName')
+          )
+      WHERE COALESCE(attributes->>'ownerName', '') <> ''
+        AND attributes->>'etradeManagerName' IS NULL
+        AND COALESCE(licence_number, '') <> ''
+    `);
+
+    // 3a. Owner-represents-themselves, and NOT a forwarder → "no PoA".
+    await queryRunner.query(`
+      UPDATE freight.companies c
+      SET attributes = (c.attributes - 'poaName' - 'poaPhone' - 'poaEmail'
+                        - 'poaLocation' - 'poaAddress' - 'poaFaydaSub'
+                        - 'poaFaydaVerifiedAt' - 'poaBirthdate' - 'poaGender')
+                       || jsonb_build_object('poaDeclared', 'no')
+      WHERE (c.attributes->>'poaSameAsOwner')::boolean IS TRUE
+        AND NOT EXISTS (
+          SELECT 1 FROM freight.company_profiles cp
+          WHERE cp.company_id = c.id
+            AND cp.type = 'freight_forwarder'
+            AND cp.deleted_at IS NULL
+        )
+    `);
+
+    // 3b. Forwarders keep their representative and lose the waiver.
+    await queryRunner.query(`
+      UPDATE freight.companies c
+      SET attributes = c.attributes || jsonb_build_object('poaDeclared', 'yes')
+      WHERE (c.attributes->>'poaSameAsOwner')::boolean IS TRUE
+        AND EXISTS (
+          SELECT 1 FROM freight.company_profiles cp
+          WHERE cp.company_id = c.id
+            AND cp.type = 'freight_forwarder'
+            AND cp.deleted_at IS NULL
+        )
+    `);
+
+    // 4. Everyone else: "yes" if a representative was named or the company is a
+    // forwarder, "no" if it finished onboarding without one. A company still
+    // mid-onboarding is left unanswered — it will be asked, which is the point.
+    await queryRunner.query(`
+      UPDATE freight.companies c
+      SET attributes = COALESCE(c.attributes, '{}'::jsonb)
+                       || jsonb_build_object('poaDeclared', 'yes')
+      WHERE c.attributes->>'poaDeclared' IS NULL
+        AND (
+          COALESCE(c.attributes->>'poaName', '') <> ''
+          OR COALESCE(c.attributes->>'poaPhone', '') <> ''
+          OR COALESCE(c.attributes->>'poaEmail', '') <> ''
+          OR COALESCE(c.attributes->>'poaLocation', '') <> ''
+          OR COALESCE(c.attributes->>'poaAddress', '') <> ''
+          OR EXISTS (
+            SELECT 1 FROM freight.company_profiles cp
+            WHERE cp.company_id = c.id
+              AND cp.type = 'freight_forwarder'
+              AND cp.deleted_at IS NULL
+          )
+        )
+    `);
+    await queryRunner.query(`
+      UPDATE freight.companies c
+      SET attributes = COALESCE(c.attributes, '{}'::jsonb)
+                       || jsonb_build_object('poaDeclared', 'no')
+      WHERE c.attributes->>'poaDeclared' IS NULL
+        AND EXISTS (
+          SELECT 1 FROM freight.external_profiles ep
+          WHERE ep.company_id = c.id
+            AND ep.onboarding_completed = true
+            AND ep.deleted_at IS NULL
+        )
+    `);
+
+    // 5. The "personnel" (general manager) wizard step no longer exists; a
+    // draft resting on it would fall back to the very first step and make the
+    // customer walk the whole wizard again.
+    await queryRunner.query(`
+      UPDATE freight.external_profiles
+      SET onboarding_step = 'owner'
+      WHERE onboarding_step = 'personnel'
+    `);
+
+    // 6. Retire the general manager and the flag it shared the model with.
+    await queryRunner.query(`
+      UPDATE freight.companies
+      SET attributes = attributes - 'generalManagerName' - 'generalManagerEmail'
+                       - 'generalManagerPhone' - 'gmSameAsOwner' - 'gmFaydaSub'
+                       - 'gmFaydaVerifiedAt' - 'gmName' - 'gmEmail' - 'gmPhone'
+                       - 'gmAddress' - 'gmBirthdate' - 'gmGender'
+                       - 'poaSameAsOwner'
+      WHERE attributes IS NOT NULL
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.companies
+        DROP COLUMN IF EXISTS general_manager_name,
+        DROP COLUMN IF EXISTS general_manager_email,
+        DROP COLUMN IF EXISTS general_manager_phone
+    `);
+  }
+
+  /**
+   * Restores the columns' shape only. The values, the `gm*` attributes and the
+   * `poaSameAsOwner` flag are not recoverable — this migration folded them into
+   * `ownerEmail` / `poaDeclared`, and there is no way back that isn't a guess.
+   */
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.companies
+        ADD COLUMN IF NOT EXISTS general_manager_name varchar(100),
+        ADD COLUMN IF NOT EXISTS general_manager_email varchar(150),
+        ADD COLUMN IF NOT EXISTS general_manager_phone varchar(20)
+    `);
+    await queryRunner.query(`
+      UPDATE freight.external_profiles
+      SET onboarding_step = 'personnel'
+      WHERE onboarding_step = 'owner'
+    `);
+  }
+}

From 8cf041f494843dc69f46df94c7e610d0990b1869 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 11 Aug 2026 11:53:42 +0000
Subject: [PATCH 018/174] test(companies): rewrite identity specs around the
 single subject

fayda-identity covers the two subjects, the passport alternative and the
eTrade owner comparison in place of ~40 general-manager assertions.
poa-delegation drops the poaSameAsOwner waiver case and asserts the opposite:
a forwarder is refused without a delegation letter however it represents
itself.
---
 .../companies.fayda-identity.spec.ts          | 1063 ++++++-----------
 .../companies.poa-delegation.spec.ts          |   21 +-
 2 files changed, 379 insertions(+), 705 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/companies/companies.fayda-identity.spec.ts b/apps/edr-freight-api/src/modules/companies/companies.fayda-identity.spec.ts
index fe40cf08f..30c323ac3 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.fayda-identity.spec.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.fayda-identity.spec.ts
@@ -177,782 +177,451 @@ function makeService(overrides: Partial<Ctx> = {}) {
 
   return { service, ctx, deps, company };
 }
+describe("one company, one verified identity", () => {
+  it("refuses a verification before the company says who represents it", async () => {
+    const { service } = makeService();
+    await expect(
+      service.completeIdentityVerification("user-1", {
+        subject: "owner",
+        code: "c",
+        state: "s",
+      }),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
 
-describe("Fayda identity verification binds a person to the company", () => {
-  it("writes the verified identity", async () => {
-    const { service, ctx } = makeService();
-
+  it("writes the verified identity onto the declared subject", async () => {
+    const { service, ctx } = makeService({ attributes: { poaDeclared: "no" } });
     const state = await service.completeIdentityVerification("user-1", {
       subject: "owner",
       code: "c",
       state: "s",
     });
 
+    expect(state.owner.verified).toBe(true);
+    expect(state.owner.name).toBe("Haile Gebrselassie");
+    expect(state.owner.email).toBe("haile@example.com");
+    expect(state.owner.address).toBe("Addis Ababa");
     expect(ctx.attributes.ownerFaydaSub).toBe("new-sub");
-    expect(ctx.attributes.ownerName).toBe("Haile Gebrselassie");
-    expect(state.owner.verified).toBe(true);
+    expect(state.identityProven).toBe(true);
+    expect(state.complete).toBe(true);
   });
 
-  it("fills every PoA detail from the payload, address included", async () => {
-    const { service, ctx } = makeService();
-
-    await service.completeIdentityVerification("user-1", {
-      subject: "poa",
-      code: "c",
-      state: "s",
-    });
-
-    expect(ctx.attributes.poaName).toBe("Haile Gebrselassie");
-    expect(ctx.attributes.poaEmail).toBe("haile@example.com");
-    expect(ctx.attributes.poaPhone).toBe("+251922000000");
-    expect(ctx.attributes.poaAddress).toBe("Addis Ababa");
+  it("refuses a verification for the person the declaration does not point at", async () => {
+    // A PoA-declared company gates on the PoA. An owner verification here would
+    // sit on the record looking proven while the gate stayed unsatisfied.
+    const { service } = makeService({ attributes: { poaDeclared: "yes" } });
+    await expect(
+      service.completeIdentityVerification("user-1", {
+        subject: "owner",
+        code: "c",
+        state: "s",
+      }),
+    ).rejects.toBeInstanceOf(BadRequestException);
   });
 
-  it("verifies successfully even though Fayda returns no national ID number", async () => {
-    // Fayda's userinfo carries no FAN/FIN claim at all — this must be the
-    // normal, successful path, not an error.
-    const { service } = makeService({
-      verification: {
-        purpose: "VERIFY",
-        verified: true,
-        sub: "x",
-        fullName: "No Fan Here",
-      },
-    });
-
-    const state = await service.completeIdentityVerification("user-1", {
-      subject: "owner",
-      code: "c",
-      state: "s",
-    });
-
-    expect(state.owner.verified).toBe(true);
-  });
-
-  it("lets one identity be both owner and PoA", async () => {
-    // An owner who represents their own company is the ordinary small-business
-    // case, not a conflict — the same answer the GM has always been allowed.
-    const { service, ctx } = makeService({
-      attributes: { ownerFaydaSub: "same-person" },
-      verification: {
-        purpose: "VERIFY",
-        verified: true,
-        sub: "same-person",
-        fullName: "Abebe Bikila",
-      },
-    });
-
+  it("verifies the representative when one is declared", async () => {
+    const { service, ctx } = makeService({ attributes: { poaDeclared: "yes" } });
     const state = await service.completeIdentityVerification("user-1", {
       subject: "poa",
       code: "c",
       state: "s",
     });
-
+    expect(state.subject).toBe("poa");
     expect(state.poa.verified).toBe(true);
-    expect(ctx.attributes.poaFaydaSub).toBe("same-person");
-  });
-
-  it("stages an owner re-verification for review on an approved company", async () => {
-    // The owner is the live company's identity proof, so re-verifying one is
-    // exactly what the backoffice review exists for: it must not rewrite the
-    // row directly.
-    const { service, ctx, deps } = makeService({
-      status: CompanyStatus.Active,
-    });
-
-    await service.completeIdentityVerification("user-1", {
-      subject: "owner",
-      code: "c",
-      state: "s",
-    });
-
-    expect(deps.changeRequestRepo.create).toHaveBeenCalled();
-    expect(ctx.attributes.ownerFaydaSub).toBeUndefined();
-  });
-
-  it("applies a PoA verification live on an approved company", async () => {
-    // The PoA is personnel the company names for itself — the delegation paper
-    // is what a reviewer actually judges — so it does not go to review.
-    const { service, ctx, deps } = makeService({
-      status: CompanyStatus.Active,
-    });
-
-    await service.completeIdentityVerification("user-1", {
-      subject: "poa",
-      code: "c",
-      state: "s",
-    });
-
-    expect(deps.changeRequestRepo.create).not.toHaveBeenCalled();
+    expect(state.poa.address).toBe("Addis Ababa");
+    expect(state.identityProven).toBe(true);
     expect(ctx.attributes.poaFaydaSub).toBe("new-sub");
   });
 
-  it("stages nothing for a verified field an approved company resubmits", async () => {
-    // Approving it could not move the live row — the verified value is written
-    // back over it — so it must never reach a reviewer as a pending change.
-    const { service, deps } = makeService({
-      status: CompanyStatus.Active,
-      attributes: { ...OWNER_VERIFIED, ownerEmail: "abebe@example.com" },
-    });
-
-    await expect(
-      service.updateProfile("user-1", {
-        companyEmail: "someone-else@example.com",
-      } as never),
-    ).resolves.toBeDefined();
-    expect(deps.changeRequestRepo.create).not.toHaveBeenCalled();
-    expect(deps.changeRequestRepo.update).not.toHaveBeenCalled();
-    expect(deps.companiesRepo.update).not.toHaveBeenCalled();
-  });
-
-  // The verified value wins, and it wins by overwriting rather than by
-  // rejecting: nobody types these fields, so a submission that disagrees is a
-  // stale form echoing itself back, not an edit. Failing it would block a save
-  // the customer never made — and leave them no way through, since re-verifying
-  // returns the same value they are being 400'd for.
-  it("overwrites a hand-renamed verified person with the verified name", async () => {
+  it("verifies successfully even though Fayda returns no national ID number", async () => {
     const { service, ctx } = makeService({
-      attributes: { ...OWNER_VERIFIED, ...POA_VERIFIED },
-      files: [paper()],
-    });
-
-    await expect(
-      service.updateProfile("user-1", { poaName: "Someone Else" } as never),
-    ).resolves.toBeDefined();
-    expect(ctx.attributes.poaName).toBe(POA_VERIFIED.poaName);
-  });
-
-  // Fayda's email and phone claims are optional — a verification can prove the
-  // person and return neither. Holding the company mirrors to "the owner is
-  // verified" rather than to "the verification supplied this value" would
-  // clobber the fallbacks the portal is built to send (account email, eTrade's
-  // registered phone) with nothing at all. OWNER_VERIFIED is exactly that
-  // shape: a sub, no contact details.
-  it("keeps company contact details a Fayda verification never supplied", async () => {
-    const { deps } = makeService({
-      attributes: { ...OWNER_VERIFIED },
-    });
-
-    const [, patch] = deps.companiesRepo.update.mock.calls.at(-1)!;
-    expect(patch.email).toBe("account@example.com");
-    expect(patch.phone).toBe("+251911777777");
-  });
-
-  // "Same as owner" copies `ownerEmail ?? null` onto the GM while setting
-  // `gmFaydaSub`. Locking that null made generalManagerEmail required by
-  // onboarding, hidden by the portal's link card and unwritable at once.
-  it("lets the GM's details be typed when the copied owner identity carried none", async () => {
-    const { service } = makeService({
-      attributes: {
-        ...OWNER_VERIFIED,
-        gmSameAsOwner: true,
-        gmFaydaSub: "owner-sub",
-        generalManagerName: "Abebe Bikila",
-        generalManagerEmail: null,
-        generalManagerPhone: null,
+      attributes: { poaDeclared: "no" },
+      verification: {
+        purpose: "VERIFY",
+        verified: true,
+        sub: "new-sub",
+        fullName: "Haile Gebrselassie",
       },
     });
-
-    await expect(
-      service.updateProfile("user-1", {
-        generalManagerEmail: "gm@example.com",
-        generalManagerPhone: "+251911888888",
-      } as never),
-    ).resolves.toBeDefined();
-  });
-
-  // Fayda's email and phone claims are optional and routinely absent. The owner
-  // is who the company is reached through and the step renders no input for
-  // their contact details, so the onboarding account — already OTP-proven —
-  // stands in rather than leaving the company unreachable.
-  describe("account contact details stand in for absent Fayda claims", () => {
-    const noContactClaims = {
-      purpose: "VERIFY",
-      verified: true,
-      sub: "new-sub",
-      fullName: "Haile Gebrselassie",
-      address: "Addis Ababa",
-    };
-    const account = {
-      email: "account@example.com",
-      phoneNumber: "+251911777777",
-    };
-
-    it("falls back to the account for an owner Fayda gave no email or phone", async () => {
-      const { service, ctx } = makeService({ verification: noContactClaims });
-
-      await service.completeIdentityVerification(
-        "user-1",
-        { subject: "owner", code: "c", state: "s" },
-        account,
-      );
-
-      expect(ctx.attributes.ownerEmail).toBe("account@example.com");
-      expect(ctx.attributes.ownerPhone).toBe("+251911777777");
-    });
-
-    it("prefers the Fayda claim over the account when there is one", async () => {
-      const { service, ctx } = makeService();
-
-      await service.completeIdentityVerification(
-        "user-1",
-        { subject: "owner", code: "c", state: "s" },
-        account,
-      );
-
-      expect(ctx.attributes.ownerEmail).toBe("haile@example.com");
-      expect(ctx.attributes.ownerPhone).toBe("+251922000000");
-    });
-
-    it("leaves the PoA alone — the account is not that person", async () => {
-      const { service, ctx } = makeService({ verification: noContactClaims });
-
-      await service.completeIdentityVerification(
-        "user-1",
-        { subject: "poa", code: "c", state: "s" },
-        account,
-      );
-
-      expect(ctx.attributes.poaEmail).toBeUndefined();
-      expect(ctx.attributes.poaPhone).toBeUndefined();
-    });
-
-    // Owners verified before the fallback existed hold blank contacts. Copying
-    // those blanks onto the GM makes generalManagerEmail required by onboarding
-    // with no field anywhere to satisfy it.
-    it("fills the GM copy from the account when the stored owner has no contacts", async () => {
-      const { service, ctx } = makeService({
-        attributes: { ...OWNER_VERIFIED },
-      });
-
-      await service.setGmSameAsOwner("user-1", account);
-
-      expect(ctx.attributes.gmEmail).toBe("account@example.com");
-      expect(ctx.attributes.generalManagerEmail).toBe("account@example.com");
-      expect(ctx.attributes.generalManagerPhone).toBe("+251911777777");
-    });
-
-    it("keeps the stored owner contacts when the GM copy has them", async () => {
-      const { service, ctx } = makeService({
-        attributes: {
-          ...OWNER_VERIFIED,
-          ownerEmail: "abebe@example.com",
-          ownerPhone: "+251911000111",
-        },
-      });
-
-      await service.setGmSameAsOwner("user-1", account);
-
-      expect(ctx.attributes.generalManagerEmail).toBe("abebe@example.com");
-      expect(ctx.attributes.generalManagerPhone).toBe("+251911000111");
-    });
-  });
-
-  it("never locks or gates the general manager — it is not the verified subject", async () => {
-    // GM is a plain typed role; the portal offers a "same as owner" copy, but
-    // the backend must not treat it as identity-owned or require it verified.
-    const { service } = makeService({
-      attributes: { ...OWNER_VERIFIED },
-    });
-
-    await expect(
-      service.updateProfile("user-1", {
-        generalManagerName: "Someone Else",
-        generalManagerEmail: "someone@example.com",
-        generalManagerPhone: "+251911223344",
-      } as never),
-    ).resolves.toBeDefined();
-  });
-});
-
-describe("Ethiopian companies verify with Fayda; foreign companies verify identity by passport", () => {
-  // The company is applying for the forwarder role, so it must not already
-  // hold it — createCompanyProfileForUser short-circuits on an existing profile
-  // and would never reach the gate.
-  const applyingForFf = {
-    profileTypes: [ProfileType.importer],
-    attributes: { ...POA_VERIFIED },
-    files: [paper()],
-  };
-
-  it("blocks the forwarder role while the owner is unverified", async () => {
-    const { service } = makeService(applyingForFf);
-
-    await expect(
-      service.createCompanyProfileForUser(
-        "user-1",
-        ProfileType.freightForwarder,
-      ),
-    ).rejects.toBeInstanceOf(BadRequestException);
-  });
-
-  it("blocks the forwarder role while the PoA is unverified", async () => {
-    const { service } = makeService({
-      profileTypes: [ProfileType.importer],
-      attributes: {
-        ...OWNER_VERIFIED,
-        poaName: "Tirunesh Dibaba",
-        poaEmail: "t@example.com",
-        poaPhone: "+251911000000",
-      },
-      files: [paper()],
-    });
-
-    await expect(
-      service.createCompanyProfileForUser(
-        "user-1",
-        ProfileType.freightForwarder,
-      ),
-    ).rejects.toBeInstanceOf(BadRequestException);
-  });
-
-  it("grants the forwarder role once owner and PoA are both verified", async () => {
-    const { service } = makeService({
-      profileTypes: [ProfileType.importer],
-      attributes: { ...OWNER_VERIFIED, ...POA_VERIFIED },
-      files: [paper()],
-    });
-
-    await expect(
-      service.createCompanyProfileForUser(
-        "user-1",
-        ProfileType.freightForwarder,
-      ),
-    ).resolves.toBeDefined();
-  });
-
-  it("never asks a foreign company for Fayda, verified or not", async () => {
-    const { service } = makeService({
-      nationality: CompanyNationality.Foreign,
-    });
-
     const state = await service.completeIdentityVerification("user-1", {
       subject: "owner",
       code: "c",
       state: "s",
     });
-
-    // Still lets the owner verify — a foreign owner verifying is allowed, just
-    // never required — but the passport is the thing that actually gates it.
     expect(state.owner.verified).toBe(true);
-    expect(state.faydaRequired).toBe(false);
-    expect(state.passportRequired).toBe(true);
+    expect(ctx.attributes.fanNumber).toBeUndefined();
   });
 
-  it("blocks the forwarder role for a foreign company with no owner passport", async () => {
-    const { service } = makeService({
-      profileTypes: [ProfileType.importer],
-      nationality: CompanyNationality.Foreign,
-      attributes: {
-        poaName: "Jean Dupont",
-        poaEmail: "jean@example.com",
-        poaPhone: "+33100000000",
-      },
-    });
-
-    await expect(
-      service.createCompanyProfileForUser(
-        "user-1",
-        ProfileType.freightForwarder,
-      ),
-    ).rejects.toBeInstanceOf(BadRequestException);
-  });
-
-  it("grants the forwarder role to a foreign company whose owner has a passport and whose PoA is Fayda-verified", async () => {
-    const { service } = makeService({
-      profileTypes: [ProfileType.importer],
-      nationality: CompanyNationality.Foreign,
-      attributes: {
-        ownerPassportNumber: "P1234567",
-        ...POA_VERIFIED,
-      },
-      files: [paper()],
-    });
-
-    await expect(
-      service.createCompanyProfileForUser(
-        "user-1",
-        ProfileType.freightForwarder,
-      ),
-    ).resolves.toBeDefined();
-  });
-
-  it("accepts a typed PoA from a foreign company, whose representative may hold no Fayda ID", async () => {
-    // Fayda is an Ethiopian national ID, so only an Ethiopian company's
-    // representative can be held to it. A foreign company is offered the
-    // verification and uses it where its representative holds one, but a typed
-    // name stays sufficient — holding it to Fayda would leave a foreign
-    // company whose representative has no Fayda ID unable to trade at all.
-    const { service } = makeService({
-      profileTypes: [ProfileType.importer],
-      nationality: CompanyNationality.Foreign,
-      attributes: {
-        ownerPassportNumber: "P1234567",
-        poaName: "Jean Dupont",
-        poaEmail: "jean@example.com",
-        poaPhone: "+33100000000",
-      },
-      files: [paper()],
-    });
-
-    await expect(
-      service.createCompanyProfileForUser(
-        "user-1",
-        ProfileType.freightForwarder,
-      ),
-    ).resolves.toBeDefined();
-  });
-
-  it("still refuses a foreign company that named no PoA at all", async () => {
-    // The typed fallback is a different credential, not a waiver: a freight
-    // forwarder acts on other companies' behalf and needs a representative
-    // whatever its nationality.
-    const { service } = makeService({
-      profileTypes: [ProfileType.importer],
-      nationality: CompanyNationality.Foreign,
-      attributes: { ownerPassportNumber: "P1234567" },
-      files: [paper()],
-    });
-
-    await expect(
-      service.createCompanyProfileForUser(
-        "user-1",
-        ProfileType.freightForwarder,
-      ),
-    ).rejects.toBeInstanceOf(BadRequestException);
-  });
-
-  it("holds an Ethiopian company to a Fayda-verified PoA, typed details notwithstanding", async () => {
-    // The relaxation above is scoped to foreign companies only — an Ethiopian
-    // representative holds a Fayda ID, so typing a name must not substitute.
-    const { service } = makeService({
-      profileTypes: [ProfileType.importer],
-      nationality: CompanyNationality.Ethiopian,
-      attributes: {
-        ...OWNER_VERIFIED,
-        poaName: "Abebe Bekele",
-        poaEmail: "abebe@example.com",
-        poaPhone: "+251911000000",
-      },
-      files: [paper()],
-    });
-
-    await expect(
-      service.createCompanyProfileForUser(
-        "user-1",
-        ProfileType.freightForwarder,
-      ),
-    ).rejects.toBeInstanceOf(BadRequestException);
-  });
-
-  it("still requires the passport for a foreign owner who chose to verify with Fayda too", async () => {
-    // Verifying is optional for a foreign owner, but it does not waive the
-    // passport requirement — the two are independent credentials.
-    const { service } = makeService({
-      profileTypes: [ProfileType.importer],
-      nationality: CompanyNationality.Foreign,
-      attributes: {
-        ...OWNER_VERIFIED,
-        poaName: "Jean Dupont",
-        poaEmail: "jean@example.com",
-        poaPhone: "+33100000000",
-      },
-    });
-
-    await expect(
-      service.createCompanyProfileForUser(
-        "user-1",
-        ProfileType.freightForwarder,
-      ),
-    ).rejects.toBeInstanceOf(BadRequestException);
-  });
-
-  // -------------------------------------------------------------------------
-  // General manager
-  // -------------------------------------------------------------------------
-
-  it("reuses the owner's verified identity when the GM is declared the same person", async () => {
-    // The GM is very often the owner. Copying the proven identity is the whole
-    // point — asking one human to complete two verifications proves nothing
-    // extra, and typing the details instead would forge a verified badge.
+  it("never stands the signed-in account in for an absent Fayda claim", async () => {
+    // The person onboarding is not necessarily the person on the licence.
+    // Stamping their address onto the owner made a required field a guess.
     const { service, ctx } = makeService({
-      attributes: {
-        ...OWNER_VERIFIED,
-        ownerEmail: "abebe@example.com",
-        ownerPhone: "+251911222333",
-      },
-    });
-
-    const state = await service.setGmSameAsOwner("user-1");
-
-    expect(state.gm.verified).toBe(true);
-    expect(state.gmSameAsOwner).toBe(true);
-    expect(state.gm.name).toBe("Abebe Bikila");
-    expect(ctx.attributes.gmFaydaSub).toBe("owner-sub");
-    // The notifiers mail the flat column, so a linked GM has to land there too.
-    expect(ctx.attributes.generalManagerEmail).toBe("abebe@example.com");
-  });
-
-  it("refuses to declare the GM is the owner while the owner is unverified", async () => {
-    // Without a verification there is no proven identity to copy — only typed
-    // text, which would arrive wearing a badge it had not earned.
-    const { service } = makeService({ attributes: {} });
-
-    await expect(service.setGmSameAsOwner("user-1")).rejects.toBeInstanceOf(
-      BadRequestException,
-    );
-  });
-
-  it("lets the GM verify as the same human as the owner", async () => {
-    // One human in every role is the ordinary small-business shape, so
-    // verifying with the owner's own Fayda sub has to succeed.
-    const { service, ctx } = makeService({
-      attributes: { ...OWNER_VERIFIED },
+      attributes: { poaDeclared: "no" },
       verification: {
         purpose: "VERIFY",
         verified: true,
-        sub: "owner-sub",
-        fullName: "Abebe Bikila",
-        email: "abebe@example.com",
-        phoneNumber: "+251911222333",
+        sub: "new-sub",
+        fullName: "Haile Gebrselassie",
       },
     });
-
     const state = await service.completeIdentityVerification("user-1", {
-      subject: "gm",
+      subject: "owner",
       code: "c",
       state: "s",
     });
-
-    expect(state.gm.verified).toBe(true);
-    expect(ctx.attributes.gmFaydaSub).toBe("owner-sub");
-    expect(ctx.attributes.generalManagerName).toBe("Abebe Bikila");
+    expect(state.owner.email).toBeNull();
+    expect(state.owner.phone).toBeNull();
+    expect(ctx.attributes.ownerEmail).toBeUndefined();
   });
 
-  it("declares the PoA is the owner, copying the verified identity across", async () => {
-    const { service, ctx } = makeService({ attributes: { ...OWNER_VERIFIED } });
-
-    const state = await service.setPoaSameAsOwner("user-1");
-
-    expect(state.poaSameAsOwner).toBe(true);
-    expect(state.poa.verified).toBe(true);
-    expect(ctx.attributes.poaFaydaSub).toBe(OWNER_VERIFIED.ownerFaydaSub);
-    expect(ctx.attributes.poaName).toBe(OWNER_VERIFIED.ownerName);
+  it("stages a verification for review on an approved company", async () => {
+    const { service, deps, ctx } = makeService({
+      status: CompanyStatus.Active,
+      attributes: { poaDeclared: "no", ...OWNER_VERIFIED },
+    });
+    await service.completeIdentityVerification("user-1", {
+      subject: "owner",
+      code: "c",
+      state: "s",
+    });
+    expect(deps.changeRequestRepo.create).toHaveBeenCalled();
+    // The live row is untouched until a reviewer approves.
+    expect(ctx.attributes.ownerFaydaSub).toBe("owner-sub");
   });
 
-  it("refuses to declare the PoA is the owner while an Ethiopian owner is unverified", async () => {
-    // Its representative must be Fayda-verified, so a declaration here would
-    // record one that could never satisfy the gate.
-    const { service } = makeService({ attributes: {} });
+  it("overwrites a hand-renamed verified person with the verified name", async () => {
+    const { service } = makeService({
+      attributes: { poaDeclared: "no", ...OWNER_VERIFIED },
+    });
+    const profile = await service.updateProfile("user-1", {
+      ownerName: "Someone Else",
+    } as never);
+    expect(profile.ownerName).toBe("Abebe Bikila");
+  });
 
-    await expect(service.setPoaSameAsOwner("user-1")).rejects.toBeInstanceOf(
+  it("keeps a field the verification never supplied typeable", async () => {
+    // Fayda's email claim is optional and `REQUIRED_COMPANY_INFO` demands one,
+    // so locking against an absent value would make it unfillable forever.
+    const { service, ctx } = makeService({
+      attributes: { poaDeclared: "no", ...OWNER_VERIFIED },
+    });
+    await service.updateProfile("user-1", {
+      ownerEmail: "typed@example.com",
+    } as never);
+    expect(ctx.attributes.ownerEmail).toBe("typed@example.com");
+  });
+
+  it("writes the owner's email onto the company, verified or not", async () => {
+    // `companies.email` is what the notification resolver reads first. Gating
+    // this on a Fayda verification left every foreign company without one.
+    const { service, deps } = makeService({ attributes: { poaDeclared: "no" } });
+    await service.updateProfile("user-1", {
+      ownerEmail: "owner@example.com",
+      ownerPhone: "+251911223344",
+    } as never);
+    const patch = deps.companiesRepo.update.mock.calls.at(-1)?.[1] as Record<
+      string,
+      unknown
+    >;
+    expect(patch.email).toBe("owner@example.com");
+    expect(patch.phone).toBe("+251911223344");
+  });
+});
+
+describe("the declaration decides who verifies", () => {
+  it("points at the owner when the company says it has no representative", async () => {
+    const { service, company } = makeService({
+      attributes: { poaDeclared: "no" },
+    });
+    expect(service.getCompanyIdentityState(company() as never).subject).toBe(
+      "owner",
+    );
+  });
+
+  it("points at the representative when it says it has one", async () => {
+    const { service, company } = makeService({
+      attributes: { poaDeclared: "yes" },
+    });
+    expect(service.getCompanyIdentityState(company() as never).subject).toBe(
+      "poa",
+    );
+  });
+
+  it("is null until the company answers, and nothing is proven yet", async () => {
+    const { service, company } = makeService({ attributes: OWNER_VERIFIED });
+    const state = service.getCompanyIdentityState(company() as never);
+    expect(state.poaDeclared).toBeNull();
+    expect(state.subject).toBeNull();
+    expect(state.identityProven).toBe(false);
+    expect(state.complete).toBe(false);
+  });
+
+  it('forces "yes" for a freight forwarder whatever is stored', async () => {
+    // A forwarder signs on other companies' behalf, so a representative is
+    // non-negotiable — including one that answered "no" before taking the role.
+    const { service, company } = makeService({
+      attributes: { poaDeclared: "no" },
+      profileTypes: [ProfileType.freightForwarder],
+    });
+    const state = service.getCompanyIdentityState(company() as never);
+    expect(state.poaDeclared).toBe("yes");
+    expect(state.subject).toBe("poa");
+  });
+
+  it('refuses to set "no" for a freight forwarder', async () => {
+    const { service } = makeService({
+      profileTypes: [ProfileType.freightForwarder],
+    });
+    await expect(service.setPoaDeclared("user-1", "no")).rejects.toBeInstanceOf(
       BadRequestException,
     );
   });
 
-  it("undoes the PoA \"same as owner\" declaration without touching a real verification", async () => {
-    const { service, ctx } = makeService({
-      attributes: { ...OWNER_VERIFIED, ...POA_VERIFIED },
+  it('tears the representative down when answered "no"', async () => {
+    const { service, ctx, deps } = makeService({
+      attributes: { poaDeclared: "yes", ...POA_VERIFIED },
+      files: [paper()],
     });
-
-    // No declaration in place: the verified representative must survive.
-    await service.clearPoaSameAsOwner("user-1");
-    expect(ctx.attributes.poaFaydaSub).toBe(POA_VERIFIED.poaFaydaSub);
-
-    await service.setPoaSameAsOwner("user-1");
-    const state = await service.clearPoaSameAsOwner("user-1");
-
-    expect(state.poaSameAsOwner).toBe(false);
+    const state = await service.setPoaDeclared("user-1", "no");
+    expect(state.poaDeclared).toBe("no");
     expect(state.poa.verified).toBe(false);
+    expect(ctx.attributes.poaName).toBeNull();
     expect(ctx.attributes.poaFaydaSub).toBeNull();
-  });
-
-  it("reports a pre-existing typed GM as unverified rather than blank", async () => {
-    // Companies onboarded before the GM was verifiable have typed details and
-    // no gm* attributes. Those details are still what the notifiers mail, so
-    // they must survive — flagged unverified so the portal offers the upgrade.
-    const { service, company } = makeService({
-      attributes: {
-        ...OWNER_VERIFIED,
-        generalManagerName: "Legacy Manager",
-        generalManagerEmail: "legacy@example.com",
-      },
-    });
-
-    const state = service.getCompanyIdentityState(company() as never);
-
-    expect(state.gm.verified).toBe(false);
-    expect(state.gm.name).toBe("Legacy Manager");
-    expect(state.gm.email).toBe("legacy@example.com");
-  });
-
-  // The mirror image, and the reason the fallback above is gated on the GM
-  // being unverified: a manager Fayda proved but supplied no email for types
-  // one instead, and the portal decides whether to render that input by asking
-  // whether the identity holds one. Reading the typed column back as part of
-  // the verified identity would answer "yes" the moment it was saved — the
-  // input would vanish and a typo could never be corrected.
-  it("keeps a verified GM's typed email out of the verified identity", async () => {
-    const { service, company } = makeService({
-      attributes: {
-        ...OWNER_VERIFIED,
-        gmFaydaSub: "gm-sub",
-        gmFaydaVerifiedAt: "2026-07-03T00:00:00.000Z",
-        gmName: "Derartu Tulu",
-        generalManagerName: "Derartu Tulu",
-        generalManagerEmail: "typed@example.com",
-      },
-    });
-
-    const state = service.getCompanyIdentityState(company() as never);
-
-    expect(state.gm.verified).toBe(true);
-    expect(state.gm.name).toBe("Derartu Tulu");
-    expect(state.gm.email).toBeNull();
-  });
-
-  it("never stands the account in for a GM Fayda gave no email", async () => {
-    // Deliberate: the account is the person onboarding, not necessarily the
-    // manager. The portal asks for the email instead.
-    const { service, ctx } = makeService({
-      attributes: { ...OWNER_VERIFIED },
-      verification: {
-        purpose: "VERIFY",
-        verified: true,
-        sub: "gm-sub",
-        fullName: "Derartu Tulu",
-        phoneNumber: "+251911222333",
-      },
-    });
-
-    const state = await service.completeIdentityVerification(
-      "user-1",
-      { subject: "gm", code: "c", state: "s" },
-      { email: "account@example.com", phoneNumber: "+251911777777" },
-    );
-
-    expect(ctx.attributes.gmEmail).toBeUndefined();
-    expect(state.gm.verified).toBe(true);
-    expect(state.gm.email).toBeNull();
-  });
-
-  it("accepts the email typed for a GM whose verification carried none", async () => {
-    const { service, ctx } = makeService({
-      attributes: {
-        ...OWNER_VERIFIED,
-        gmFaydaSub: "gm-sub",
-        gmName: "Derartu Tulu",
-        generalManagerName: "Derartu Tulu",
-      },
-    });
-
-    await service.updateProfile("user-1", {
-      generalManagerEmail: "gm@example.com",
-    } as never);
-
-    expect(ctx.attributes.generalManagerEmail).toBe("gm@example.com");
-  });
-
-  it("does not let an unproven GM block the company from trading", async () => {
-    // The GM names who to talk to, not what the company may do. Capturing it
-    // through Fayda changed how it is collected, not whether it gates.
-    const { service } = makeService({
-      attributes: { ...OWNER_VERIFIED },
-    });
-
-    await expect(
-      service.createCompanyProfileForUser("user-1", ProfileType.importer),
-    ).resolves.toBeDefined();
+    // The paper evidenced a delegation that no longer exists.
+    expect(deps.filesService.remove).toHaveBeenCalledWith("file-1");
   });
 });
 
-/**
- * Fayda's email and phone claims are optional, so a *verified* representative
- * can still be missing the details `REQUIRED_POA_FIELDS` demands. The PoA step
- * renders an input for whatever the verification did not supply — so onboarding
- * has to report them outstanding, rather than letting a freight forwarder
- * submit an incomplete representative and be refused its next PoA edit for it.
- */
-describe("onboarding requirements name the PoA details Fayda did not supply", () => {
-  const POA_VERIFIED_NO_CONTACTS = {
-    poaFaydaSub: "poa-sub",
-    poaFaydaVerifiedAt: "2026-07-02T00:00:00.000Z",
-    poaName: "Tirunesh Dibaba",
-  };
+describe("foreign companies prove the same person by Fayda OR passport", () => {
+  const foreign = (attributes: Record<string, unknown>) =>
+    makeService({ nationality: CompanyNationality.Foreign, attributes });
 
-  it("reports the missing email and phone for a freight forwarder", async () => {
+  it("accepts a passport number in place of Fayda", async () => {
+    const { service, company } = foreign({
+      poaDeclared: "no",
+      ownerPassportNumber: "P1234567",
+    });
+    const state = service.getCompanyIdentityState(company() as never);
+    expect(state.passportAccepted).toBe(true);
+    expect(state.identityProven).toBe(true);
+  });
+
+  it("accepts a Fayda verification instead — the passport is not additional", async () => {
+    const { service, company } = foreign({ poaDeclared: "no", ...OWNER_VERIFIED });
+    expect(
+      service.getCompanyIdentityState(company() as never).identityProven,
+    ).toBe(true);
+  });
+
+  it("collects the passport of whichever person carries the identity", async () => {
+    const { service, company } = foreign({
+      poaDeclared: "yes",
+      poaPassportNumber: "P7654321",
+    });
+    const state = service.getCompanyIdentityState(company() as never);
+    expect(state.subject).toBe("poa");
+    expect(state.identityProven).toBe(true);
+  });
+
+  it("is not satisfied by the OTHER person's passport", async () => {
+    // A PoA-represented company gates on the PoA; the owner's passport proves
+    // nobody relevant.
+    const { service, company } = foreign({
+      poaDeclared: "yes",
+      ownerPassportNumber: "P1234567",
+    });
+    expect(
+      service.getCompanyIdentityState(company() as never).identityProven,
+    ).toBe(false);
+  });
+
+  it("offers an Ethiopian company no passport alternative", async () => {
+    const { service, company } = makeService({
+      attributes: { poaDeclared: "no", ownerPassportNumber: "P1234567" },
+    });
+    const state = service.getCompanyIdentityState(company() as never);
+    expect(state.passportAccepted).toBe(false);
+    expect(state.identityProven).toBe(false);
+  });
+});
+
+describe("the owner is checked against the eTrade licence", () => {
+  it("matches ignoring case, punctuation and word order", async () => {
+    const { service, company } = makeService({
+      attributes: {
+        poaDeclared: "no",
+        ownerName: "abebe  bikila",
+        etradeManagerName: "BIKILA, Abebe",
+      },
+    });
+    expect(
+      service.getCompanyIdentityState(company() as never).ownerMatchesEtrade,
+    ).toBe(true);
+  });
+
+  it("flags a different person", async () => {
+    const { service, company } = makeService({
+      attributes: {
+        poaDeclared: "no",
+        ownerName: "Haile Gebrselassie",
+        etradeManagerName: "Abebe Bikila",
+      },
+    });
+    expect(
+      service.getCompanyIdentityState(company() as never).ownerMatchesEtrade,
+    ).toBe(false);
+  });
+
+  it("reports null when there is nothing to compare", async () => {
+    // eTrade's ManagerNameEng is frequently blank; a null must not read as a
+    // mismatch, which would flag half the customer base.
+    const { service, company } = makeService({
+      attributes: { poaDeclared: "no", ownerName: "Abebe Bikila" },
+    });
+    expect(
+      service.getCompanyIdentityState(company() as never).ownerMatchesEtrade,
+    ).toBeNull();
+  });
+
+  it("never blocks on a mismatch — it is the reviewer's call", async () => {
     const { service } = makeService({
-      attributes: { ...OWNER_VERIFIED, ...POA_VERIFIED_NO_CONTACTS },
-      profileTypes: [ProfileType.freightForwarder],
+      attributes: {
+        poaDeclared: "no",
+        ...OWNER_VERIFIED,
+        // The verified owner is a different human from the one on the licence.
+        ownerName: "Haile Gebrselassie",
+        etradeManagerName: "Abebe Bikila",
+      },
+    });
+    const reqs = await service.getOnboardingRequirements("user-1");
+    expect(reqs.outstanding).not.toContain(
+      expect.stringContaining("eTrade"),
+    );
+  });
+});
+
+describe("the freight-forwarder gate", () => {
+  const addForwarder = (service: CompaniesService) =>
+    service.addCompanyProfilesForUser("user-1", [ProfileType.freightForwarder]);
+
+  it("blocks the role while the representative is unverified", async () => {
+    const { service } = makeService({ attributes: { poaDeclared: "yes" } });
+    await expect(addForwarder(service)).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+  });
+
+  it("blocks the role on a company that answered no — it becomes yes", async () => {
+    // Taking the role forces the declaration, so a company that had answered
+    // "no" cannot inherit that answer past the gate.
+    const { service } = makeService({
+      attributes: { poaDeclared: "no", ...OWNER_VERIFIED },
+    });
+    await expect(addForwarder(service)).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+  });
+
+  it("blocks the role without the DARS delegation paper", async () => {
+    const { service } = makeService({
+      attributes: { poaDeclared: "yes", ...POA_VERIFIED },
+      files: [],
+    });
+    await expect(addForwarder(service)).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+  });
+
+  it("grants the role once the representative is proven and the paper is on file", async () => {
+    const { service } = makeService({
+      attributes: { poaDeclared: "yes", ...POA_VERIFIED },
       files: [paper()],
     });
+    await expect(addForwarder(service)).resolves.toBeDefined();
+  });
 
-    const req = await service.getOnboardingRequirements("user-1");
+  it("grants it to a foreign forwarder whose representative has a passport", async () => {
+    const { service } = makeService({
+      nationality: CompanyNationality.Foreign,
+      attributes: {
+        poaDeclared: "yes",
+        ...POA_VERIFIED,
+        poaFaydaSub: undefined,
+        poaPassportNumber: "P7654321",
+      },
+      files: [paper()],
+    });
+    await expect(addForwarder(service)).resolves.toBeDefined();
+  });
+});
 
-    expect(req.poa.missingFields.map((f) => f.key)).toEqual([
+describe("onboarding requirements report exactly what is outstanding", () => {
+  it("asks the power-of-attorney question before anything else about identity", async () => {
+    const { service } = makeService();
+    const reqs = await service.getOnboardingRequirements("user-1");
+    expect(reqs.poa.declared).toBeNull();
+    expect(reqs.outstanding).toContain(
+      "Tell us whether anyone holds power of attorney for your company",
+    );
+  });
+
+  it("names the representative's missing details once one is declared", async () => {
+    const { service } = makeService({
+      attributes: { poaDeclared: "yes", poaName: "Tirunesh Dibaba" },
+    });
+    const reqs = await service.getOnboardingRequirements("user-1");
+    expect(reqs.poa.missingFields.map((f) => f.key)).toEqual([
       "poaEmail",
       "poaPhone",
     ]);
-    expect(req.poa.complete).toBe(false);
-    expect(req.outstanding).toEqual(
-      expect.arrayContaining(["Add your poa email", "Add your poa phone"]),
-    );
   });
 
-  it("clears once they are typed", async () => {
+  it("asks nothing about a representative from a company that has none", async () => {
     const { service } = makeService({
-      attributes: { ...OWNER_VERIFIED, ...POA_VERIFIED },
-      profileTypes: [ProfileType.freightForwarder],
-      files: [paper()],
+      attributes: { poaDeclared: "no", ...OWNER_VERIFIED },
     });
-
-    const req = await service.getOnboardingRequirements("user-1");
-
-    expect(req.poa.missingFields).toEqual([]);
-    expect(req.poa.complete).toBe(true);
-    expect(req.outstanding).not.toContain("Add your poa email");
+    const reqs = await service.getOnboardingRequirements("user-1");
+    expect(reqs.poa.missingFields).toEqual([]);
+    expect(reqs.poa.delegationLetterRequired).toBe(false);
   });
 
-  // Fayda's email claim is optional and the GM's verification has no account to
-  // fall back on, so demanding one blocked a manager the government had already
-  // proved. `companyNotifyEmailExpr` resolves the address from the contact
-  // person or the registering account instead, so nothing needs this filled.
-  it("does not hold a company back for a general manager with no email", async () => {
+  it("demands the delegation paper from every declared representative", async () => {
+    // No waiver: the owner representing the company IS the "no" answer, so a
+    // "yes" always means a delegation that has to be evidenced.
     const { service } = makeService({
-      attributes: {
-        ...OWNER_VERIFIED,
-        gmFaydaSub: "gm-sub",
-        generalManagerName: "Derartu Tulu",
-        generalManagerPhone: "+251911222333",
-      },
+      attributes: { poaDeclared: "yes", ...POA_VERIFIED },
+      files: [],
     });
-
-    const req = await service.getOnboardingRequirements("user-1");
-
-    expect(req.companyInfo.missingFields.map((f) => f.key)).not.toContain(
-      "generalManagerEmail",
-    );
-    expect(req.outstanding).not.toContain("Add your general manager email");
+    const reqs = await service.getOnboardingRequirements("user-1");
+    expect(reqs.poa.delegationLetterRequired).toBe(true);
+    expect(reqs.isComplete).toBe(false);
   });
 
-  it("still holds it back for the manager's name and phone", async () => {
-    const { service } = makeService({ attributes: { ...OWNER_VERIFIED } });
-
-    const req = await service.getOnboardingRequirements("user-1");
-
-    expect(req.companyInfo.missingFields.map((f) => f.key)).toEqual(
-      expect.arrayContaining(["generalManagerName", "generalManagerPhone"]),
+  it("names the owner's missing details", async () => {
+    const { service } = makeService({ attributes: { poaDeclared: "no" } });
+    const reqs = await service.getOnboardingRequirements("user-1");
+    const missing = reqs.companyInfo.missingFields.map((f) => f.key);
+    expect(missing).toEqual(
+      expect.arrayContaining(["ownerName", "ownerEmail", "ownerPhone"]),
     );
   });
 
-  // An importer that never named a representative owes nothing here — the step
-  // is one it may walk straight past.
-  it("asks nothing of a company with no PoA at all", async () => {
-    const { service } = makeService({ attributes: { ...OWNER_VERIFIED } });
+  it("reports the verification against the person it actually gates on", async () => {
+    const { service } = makeService({ attributes: { poaDeclared: "yes" } });
+    const reqs = await service.getOnboardingRequirements("user-1");
+    expect(reqs.outstanding).toContain(
+      "Verify your Power of Attorney with Fayda",
+    );
+  });
 
-    const req = await service.getOnboardingRequirements("user-1");
-
-    expect(req.poa.missingFields).toEqual([]);
-    expect(req.poa.complete).toBe(true);
+  it("offers the passport alternative to a foreign company", async () => {
+    const { service } = makeService({
+      nationality: CompanyNationality.Foreign,
+      attributes: { poaDeclared: "no" },
+    });
+    const reqs = await service.getOnboardingRequirements("user-1");
+    expect(reqs.outstanding).toContain(
+      "Verify the person named on your eTrade licence with Fayda, or add their passport number",
+    );
   });
 });
diff --git a/apps/edr-freight-api/src/modules/companies/companies.poa-delegation.spec.ts b/apps/edr-freight-api/src/modules/companies/companies.poa-delegation.spec.ts
index b85344e8e..96dc3ff53 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.poa-delegation.spec.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.poa-delegation.spec.ts
@@ -174,21 +174,26 @@ describe("PoA delegation paper is enforced wherever PoA state changes", () => {
     ).resolves.toBeDefined();
   });
 
-  it("waives the paper when the owner represents the company themselves", async () => {
-    // Nobody delegates to themselves, so a self-declared PoA owes no DARS
-    // paper — the representative's own details are still required.
+  it('owes nothing when the company answered "no representative"', async () => {
+    // "The owner represents the company themselves" is now expressed as the
+    // declaration being "no" — there is no delegation, so no paper is due. The
+    // representative's details are cleared with the answer, so there is nothing
+    // left to evidence either.
     const { service } = makeService({
-      attributes: { ...VERIFIED_IDENTITIES, poaSameAsOwner: true },
+      attributes: { ...VERIFIED_IDENTITIES, poaDeclared: "no" },
     });
 
     await expect(
-      service.updateProfile("user-1", POA as never),
+      service.updateProfile("user-1", {} as never),
     ).resolves.toBeDefined();
   });
 
-  it("grants the forwarder role to a self-represented company with no paper", async () => {
+  it("refuses the forwarder role without a paper, however it represents itself", async () => {
+    // The self-representation waiver is gone: a freight forwarder signs on
+    // other companies' behalf, so the delegation and the paper evidencing it
+    // are non-negotiable.
     const { service } = makeService({
-      attributes: { ...VERIFIED_IDENTITIES, ...POA, poaSameAsOwner: true },
+      attributes: { ...VERIFIED_IDENTITIES, ...POA, poaDeclared: "yes" },
     });
 
     await expect(
@@ -196,7 +201,7 @@ describe("PoA delegation paper is enforced wherever PoA state changes", () => {
         "user-1",
         ProfileType.freightForwarder,
       ),
-    ).resolves.toBeDefined();
+    ).rejects.toBeInstanceOf(BadRequestException);
   });
 
   it("rejects a paper the reviewer sent back for correction", async () => {

From 293f255daa2beb6ce3a676c159521c51c7869934 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 11 Aug 2026 11:53:56 +0000
Subject: [PATCH 019/174] refactor(freight-portal): rebuild the onboarding
 wizard around owner and representation

Steps are now company -> owner -> representation -> contact -> documents;
PersonnelStep and PoaStep are gone.

- OwnerStep shows whoever the eTrade licence names, read-only with a
  provenance badge (SourcedField), and renders an input for every gap eTrade
  and Fayda left. It warns when the stored owner does not match eTrade.
- RepresentationStep asks outright whether anyone holds power of attorney,
  then branches: "no" verifies the owner, "yes" collects the representative
  and the DARS delegation letter. Freight forwarders cannot answer "no".
- Passport input appears only for a foreign company whose subject has not
  verified with Fayda.
- Drop every same-as-owner copy-across and the auth-user fallbacks for the
  owner's email and phone. Re-picking a business licence now clears the
  eTrade owner prefill, since licences under one TIN can name different
  managers.
- Settings: TabGeneralManager replaced by TabOwner; TabPowerOfAttorney
  reworked around poaDeclared.
---
 .../onboarding/OnboardingWizardDialog.tsx     |  55 +-
 .../portal/src/pages/SettingsPage.tsx         |  51 +-
 .../src/pages/accounts/CompanyProfileForm.tsx | 699 +++++-------------
 .../companyProfileForm/SourcedField.tsx       |  61 ++
 .../accounts/companyProfileForm/helpers.ts    |  37 +-
 .../companyProfileForm/schema.test.ts         | 103 ++-
 .../accounts/companyProfileForm/schema.ts     | 103 +--
 .../steps/CompanyInfoStep.tsx                 |  50 --
 .../companyProfileForm/steps/ContactStep.tsx  |  32 +-
 .../companyProfileForm/steps/OwnerStep.tsx    | 132 ++++
 .../steps/PersonnelStep.tsx                   | 150 ----
 .../companyProfileForm/steps/PoaStep.tsx      | 217 ------
 .../steps/RepresentationStep.tsx              | 273 +++++++
 .../src/pages/settings/TabCompanyProfile.tsx  |  58 +-
 .../src/pages/settings/TabGeneralManager.tsx  | 333 ---------
 .../portal/src/pages/settings/TabOwner.tsx    | 198 +++++
 .../src/pages/settings/TabPowerOfAttorney.tsx | 132 ++--
 .../portal/src/services/companies.service.ts  |  15 +-
 .../portal/src/services/verifayda.service.ts  | 138 ++--
 .../portal/src/types/profile.ts               |  32 +-
 20 files changed, 1187 insertions(+), 1682 deletions(-)
 create mode 100644 apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/SourcedField.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx
 delete mode 100644 apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/PersonnelStep.tsx
 delete mode 100644 apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/PoaStep.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx
 delete mode 100644 apps/edr-freight-web/portal/src/pages/settings/TabGeneralManager.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx

diff --git a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
index fa9c5919b..b9fdca622 100644
--- a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
+++ b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
@@ -41,12 +41,17 @@ import type { UpdateProfilePayload } from "@/types/profile";
 import { extractApiError } from "@/utils/result";
 
 /** Form steps rendered by CompanyProfileForm. */
-type FormStep = "company" | "personnel" | "contact" | "poa" | "documents";
+type FormStep =
+  | "company"
+  | "owner"
+  | "representation"
+  | "contact"
+  | "documents";
 const FORM_STEPS: FormStep[] = [
   "company",
-  "personnel",
+  "owner",
+  "representation",
   "contact",
-  "poa",
   "documents",
 ];
 
@@ -68,23 +73,25 @@ const STEP_META: Record<
     icon: <Building2 size={20} />,
     title: "Company Information",
     description:
-      "Confirm your VAT number, verify the owner's identity, and we'll pull your registration from eTrade.",
+      "Confirm your VAT number and we'll pull your registration straight from eTrade.",
   },
-  personnel: {
+  owner: {
     icon: <User size={20} />,
-    title: "General Manager",
-    description: "Who is the general manager of the company?",
+    title: "Company Owner",
+    description:
+      "The person registered on your eTrade licence. We fill in what eTrade and Fayda gave us.",
+  },
+  representation: {
+    icon: <FileText size={20} />,
+    title: "Who Acts For You",
+    description:
+      "Tell us whether anyone holds power of attorney — your answer decides whose identity we verify.",
   },
   contact: {
     icon: <UserCheck size={20} />,
     title: "Contact Person",
     description: "Who should we reach out to about this account?",
   },
-  poa: {
-    icon: <FileText size={20} />,
-    title: "Power of Attorney",
-    description: "Optionally add a representative with power of attorney.",
-  },
   documents: {
     icon: <UploadCloud size={20} />,
     title: "Upload Documents",
@@ -210,7 +217,7 @@ export default function OnboardingWizardDialog({
     }) => api.companies.startOnboarding.call(vars),
     onSuccess: async () => {
       // Nationality drives the server-resolved identity requirements (Fayda vs
-      // passport), the document set and the GM/PoA copy — all read from
+      // passport), the document set and the PoA copy — all read from
       // onboardingRequirements/profile. Re-entering role selection can change
       // it, so both must be refetched alongside getInfo or the form step would
       // keep rendering the previous nationality's requirements.
@@ -414,15 +421,21 @@ export default function OnboardingWizardDialog({
   const requiredDocsMissing = requirementDocuments.some(
     (d) => d.isRequired && !d.uploaded,
   );
-  // The PoA gets the same treatment: a resumed draft that predates the
-  // delegation-letter requirement (or a forwarder whose PoA is blank) must land
-  // back on the PoA step, where both the details and the letter are entered.
-  const poaIncomplete = requirementsQuery.data?.poa?.complete === false;
+  // The representation step gets the same treatment. An unanswered
+  // power-of-attorney question, or a declared representative still missing
+  // details or the DARS paper, must land the customer back on the step where
+  // all of that is entered — including a draft that predates the question
+  // existing at all, whose `declared` comes back null.
+  const representationIncomplete =
+    requirementsQuery.data?.poa?.declared == null ||
+    requirementsQuery.data?.poa?.complete === false ||
+    requirementsQuery.data?.identity?.identityProven === false;
   // Each unmet requirement lowers the ceiling; resume never moves forward.
   let ceiling = FORM_STEPS.length - 1;
   if (requiredDocsMissing)
     ceiling = Math.min(ceiling, FORM_STEPS.indexOf("documents"));
-  if (poaIncomplete) ceiling = Math.min(ceiling, FORM_STEPS.indexOf("poa"));
+  if (representationIncomplete)
+    ceiling = Math.min(ceiling, FORM_STEPS.indexOf("representation"));
   const effectiveResumeStep: FormStep =
     FORM_STEPS[
     Math.min(Math.max(FORM_STEPS.indexOf(resumeFormStep), 0), ceiling)
@@ -446,9 +459,9 @@ export default function OnboardingWizardDialog({
     onLicenseChange: setLicenseFiles,
     uploadedDocumentKeys,
     onUploadDocuments: handleUploadDocuments,
-    // Fayda verification state for the owner and the PoA — the general manager
-    // stays a plain typed role. Mandatory (Fayda) for an Ethiopian company;
-    // a foreign one requires a typed passport number for the owner instead.
+    // The company's single identity verification, and whose it is. Fayda is
+    // mandatory for an Ethiopian company; a foreign one may instead type a
+    // passport number for the same person.
     identity: requirementsQuery.data?.identity,
     onIdentityChange: () => {
       void profileQuery.refetch();
diff --git a/apps/edr-freight-web/portal/src/pages/SettingsPage.tsx b/apps/edr-freight-web/portal/src/pages/SettingsPage.tsx
index 8a2f1d12f..13b0d4025 100644
--- a/apps/edr-freight-web/portal/src/pages/SettingsPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/SettingsPage.tsx
@@ -49,49 +49,46 @@ import TabAccount from "./settings/TabAccount";
 import TabCompanyProfile from "./settings/TabCompanyProfile";
 import TabContactPerson from "./settings/TabContactPerson";
 import TabDocuments from "./settings/TabDocuments";
-import TabGeneralManager from "./settings/TabGeneralManager";
+import TabOwner from "./settings/TabOwner";
 import TabPowerOfAttorney from "./settings/TabPowerOfAttorney";
 
 type SettingsTab =
   | "account"
   | "company"
   | "contact"
-  | "gm"
+  | "owner"
   | "poa"
   | "documents";
 
 /** A section is "incomplete" when its required fields aren't filled in yet. */
 function tabIncomplete(tabId: SettingsTab, profile: ProfileResponse): boolean {
   switch (tabId) {
-    case "company": {
-      // Identity proof lives here: the owner's Fayda verification for an
-      // Ethiopian company, or the owner's typed passport number for a foreign
-      // one.
-      const identity = profile.identity;
-      const identityIncomplete = identity
-        ? (identity.faydaRequired && !identity.owner.verified) ||
-        (identity.passportRequired && !identity.owner.passportNumber)
-        : false;
-      return !profile.companyAddress || identityIncomplete;
-    }
+    case "company":
+      return !profile.companyAddress;
     case "contact":
       return !profile.contactPersonName || !profile.contactPersonPhone;
-    case "gm":
-      // The GM is established through Fayda — verified in their own right or
-      // declared the same person as the owner — so the identity answers this,
-      // not the typed columns. A company that may still type them (foreign,
-      // whose manager may hold no Fayda ID) is judged on those instead.
-      if (profile.identity?.gm.verified) return false;
-      if (profile.identity?.faydaRequired) return true;
+    case "owner":
+      // The owner is whoever the eTrade licence names. All three details are
+      // required whatever supplied them, and the identity verification lives
+      // on whichever person the PoA declaration points at — flagged here when
+      // it is the owner and still unproven.
       return (
-        !profile.generalManagerName ||
-        !profile.generalManagerEmail ||
-        !profile.generalManagerPhone
+        !profile.ownerName ||
+        !profile.ownerEmail ||
+        !profile.ownerPhone ||
+        (profile.identity?.subject === "owner" &&
+          !profile.identity.identityProven)
+      );
+    case "poa":
+      // Unanswered is itself incomplete — the answer decides whose identity is
+      // verified — as is a declared representative who has not proved theirs.
+      if (profile.identity?.poaDeclared == null) return true;
+      return (
+        profile.identity.subject === "poa" && !profile.identity.identityProven
       );
     case "account":
     // Account fields live on the IAM user, not the company profile, and are
     // always populated (signup requires them) — nothing to nag about here.
-    case "poa":
     case "documents":
       return false;
   }
@@ -101,7 +98,7 @@ const TABS: { id: SettingsTab; label: string; icon: React.ReactNode }[] = [
   { id: "account", label: "Account", icon: <UserCog size={16} /> },
   { id: "company", label: "Company", icon: <Building2 size={16} /> },
   { id: "contact", label: "Contact Person", icon: <User size={16} /> },
-  { id: "gm", label: "General Manager", icon: <Briefcase size={16} /> },
+  { id: "owner", label: "Owner", icon: <Briefcase size={16} /> },
   { id: "poa", label: "Power of Attorney", icon: <UserCheck size={16} /> },
   { id: "documents", label: "Documents", icon: <FileCheck size={16} /> },
 ];
@@ -405,8 +402,8 @@ export default function SettingsPage() {
           <Tabs.Panel value="contact">
             <TabContactPerson profile={profile} mode="edit" />
           </Tabs.Panel>
-          <Tabs.Panel value="gm">
-            <TabGeneralManager profile={profile} mode="edit" />
+          <Tabs.Panel value="owner">
+            <TabOwner profile={profile} mode="edit" />
           </Tabs.Panel>
           <Tabs.Panel value="poa">
             <TabPowerOfAttorney profile={profile} mode="edit" />
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 92e1a7118..93ab3cfc2 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
@@ -24,18 +24,19 @@ import {
 import {
   buildPayload,
   firstPresent,
-  firstValidEmail,
-  firstValidPhone,
   normalizeIdentityPhones,
   stepPayload,
   toFormValues,
 } from "./companyProfileForm/helpers";
 import { verifaydaService } from "@/services/verifayda.service";
-import type { CompanyIdentityState } from "@/services/verifayda.service";
+import type {
+  CompanyIdentityState,
+  PoaDeclaration,
+} from "@/services/verifayda.service";
 import CompanyInfoStep from "./companyProfileForm/steps/CompanyInfoStep";
-import PersonnelStep from "./companyProfileForm/steps/PersonnelStep";
+import OwnerStep from "./companyProfileForm/steps/OwnerStep";
 import ContactStep from "./companyProfileForm/steps/ContactStep";
-import PoaStep from "./companyProfileForm/steps/PoaStep";
+import RepresentationStep from "./companyProfileForm/steps/RepresentationStep";
 import DocumentsStep from "./companyProfileForm/steps/DocumentsStep";
 
 export default function CompanyProfileForm({
@@ -96,7 +97,7 @@ export default function CompanyProfileForm({
   onUploadDocuments?: () => Promise<
     { ok: true } | { ok: false; error: string }
   >;
-  /** Fayda verification state for the owner and the PoA (undefined until loaded). */
+  /** The company's single identity verification (undefined until loaded). */
   identity?: CompanyIdentityState;
   /**
    * Refetch the profile + requirements. Only the in-page identity actions need
@@ -148,7 +149,7 @@ export default function CompanyProfileForm({
 
   // Follow a parent-driven resume correction: if initialStep changes (the wizard
   // re-clamps it back once onboarding requirements load — e.g. a required
-  // document is still missing, so it must not skip ahead to Business License),
+  // document is still missing, so it must not skip ahead to the documents step),
   // adopt it, but only while the user hasn't started navigating themselves.
   const lastInitialStep = useRef(initialStep);
   useEffect(() => {
@@ -174,16 +175,6 @@ export default function CompanyProfileForm({
     }),
   );
 
-  // A freight forwarder signs on other companies' behalf, so its Power of
-  // Attorney (details + DARS delegation paper) is mandatory rather than optional.
-  const requirePoa = (roleProfiles ?? []).some(
-    (p) => p.type === "freight_forwarder",
-  );
-  // Fayda is an Ethiopian national ID: an Ethiopian company verifies its owner
-  // and PoA instead of typing their details, a foreign one keeps the typed
-  // forms (plus a mandatory owner passport number).
-  const verifiedIdentity = identity?.faydaRequired === true;
-
   // Which fields the current step renders an input for and therefore requires.
   // Filled in further down (it depends on values this form owns), and read at
   // validation time rather than at render time — the resolver below runs on
@@ -192,16 +183,15 @@ export default function CompanyProfileForm({
 
   const form = useForm<FormData>({
     resolver: (values, context, options) =>
-      zodResolver(
-        buildOnboardingSchema(
-          identity?.passportRequired === true,
-          requiredKeysRef.current,
-        ),
-      )(values, context, options),
+      zodResolver(buildOnboardingSchema(requiredKeysRef.current))(
+        values,
+        context,
+        options,
+      ),
     // `values` below re-seeds the form whenever the profile is refetched — and
-    // an in-page identity action (ticking "same as owner") refetches it. Without
-    // this, that reset silently throws away whatever the customer was part-way
-    // through typing on the current step.
+    // an in-page identity action (answering the PoA question) refetches it.
+    // Without this, that reset silently throws away whatever the customer was
+    // part-way through typing on the current step.
     resetOptions: { keepDirtyValues: true, keepErrors: true },
     defaultValues: {
       companyName: "",
@@ -210,6 +200,7 @@ export default function CompanyProfileForm({
       tinNumber: "",
       vatNumber: "",
       ownerPassportNumber: "",
+      poaPassportNumber: "",
       licenceNumber: "",
       statusDescription: "",
       dateRegistered: "",
@@ -225,9 +216,9 @@ export default function CompanyProfileForm({
       contactPersonPosition: "",
       contactPersonEmail: "",
       contactPersonPhone: "",
-      generalManagerName: "",
-      generalManagerEmail: "",
-      generalManagerPhone: "",
+      ownerName: "",
+      ownerEmail: "",
+      ownerPhone: "",
       poaName: "",
       poaPhone: "",
       poaAddress: "",
@@ -273,8 +264,9 @@ export default function CompanyProfileForm({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [region, zone, woreda, kebele, houseNo]);
 
-  // The business owner/manager pulled from eTrade — powers "Use owner as
-  // manager" on the General Manager step. Null until a TIN lookup succeeds.
+  // The manager eTrade lists for this licence. This is the person the owner
+  // step is about — "owner" here means whoever the licence names, and the
+  // backoffice checks the stored owner against exactly this.
   const [etradeOwner, setEtradeOwner] = useState<{
     name: string;
     phone: string;
@@ -302,31 +294,45 @@ export default function CompanyProfileForm({
     setValue("woreda", data.woreda, dirty);
     setValue("kebele", data.kebele, dirty);
     setValue("houseNo", data.houseNo, dirty);
-    // companyAddress is composed reactively from the address fields below, so
-    // setting region/zone/woreda/kebele/houseNo above is enough — no need to
-    // compose it here. companyPhone is derived below (identity → eTrade →
-    // account), not set directly here.
+    // companyAddress is composed reactively from the address fields above.
     // etradePhone is the raw number eTrade returned for this TIN — kept as its
-    // own field (distinct from companyPhone, which prefers the Fayda-verified
-    // owner's phone) so the backend's "matches eTrade's current record" check
-    // always compares against what eTrade actually said, not the owner's phone.
+    // own field (distinct from the owner's phone) so the backend's "matches
+    // eTrade's current record" check always compares against what eTrade
+    // actually said.
     setValue(
       "etradePhone",
       data.managerPhone || data.regularPhone || data.mobilePhone,
       dirty,
     );
 
-    setEtradeOwner({
+    const owner = {
       name: data.managerName,
       phone: toEthiopianE164(
         data.managerPhone || data.regularPhone || data.mobilePhone,
       ),
-    });
+    };
+    setEtradeOwner(owner);
+
+    // Prefill the owner inputs rather than replacing them. The customer can
+    // still correct a name eTrade transliterated oddly — and if they change it
+    // to a different person, `identity.ownerMatchesEtrade` says so to both them
+    // and the reviewer. Only fills what is empty: a value the customer already
+    // typed (or a Fayda claim already stored) is not overwritten by a lookup.
+    if (owner.name && !getValues("ownerName")?.trim()) {
+      setValue("ownerName", owner.name, { shouldValidate: true, ...dirty });
+    }
+    if (owner.phone && !getValues("ownerPhone")?.trim()) {
+      setValue("ownerPhone", owner.phone, { shouldValidate: true, ...dirty });
+    }
   };
 
   // TIN changed since the last successful lookup — the registration/address
   // fields it filled in describe the OLD TIN, not this one, so clear them
   // rather than leaving them stale on screen.
+  //
+  // The owner goes too: different licences under one TIN can list different
+  // managers, so a prefill from the previous pick is someone else's name.
+  // Only the prefill is cleared — a Fayda-verified owner is the API's to own.
   const handleETradeReset = () => {
     setValue("licenceNumber", "");
     setValue("statusDescription", "");
@@ -340,273 +346,91 @@ export default function CompanyProfileForm({
     setValue("kebele", "");
     setValue("houseNo", "");
     setValue("etradePhone", "");
+    if (!identity?.owner.verified) {
+      if (getValues("ownerName") === etradeOwner?.name) setValue("ownerName", "");
+      if (getValues("ownerPhone") === etradeOwner?.phone)
+        setValue("ownerPhone", "");
+    }
     setEtradeOwner(null);
   };
 
-  // "Same as …" links. A checked card prefills the target step's fields from the
-  // source step and disables them (kept mirrored while linked); unchecking clears
-  // them and re-enables editing.
-  // Seeded from the server so a resumed draft reopens with the declaration the
-  // company already made, rather than an unticked box over a linked GM.
-  const [gmSameAsOwner, setGmSameAsOwner] = useState(
-    identity?.gmSameAsOwner ?? false,
-  );
-  // `identity` is undefined on the first render (the requirements query is still
-  // in flight), so the initial state above freezes at `false` — adopt the
-  // server's declaration the moment it lands, or a resumed draft shows an
-  // unticked box over a GM that is linked server-side.
-  const [poaSameAsOwner, setPoaSameAsOwner] = useState(
-    identity?.poaSameAsOwner ?? false,
-  );
-  const identityLoaded = useRef(false);
-  useEffect(() => {
-    if (!identity || identityLoaded.current) return;
-    identityLoaded.current = true;
-    setGmSameAsOwner(identity.gmSameAsOwner);
-    setPoaSameAsOwner(identity.poaSameAsOwner);
-  }, [identity]);
-  const [contactSameAsGm, setContactSameAsGm] = useState(false);
-
-  // Where the owner's details come from when they are copied onto someone else
-  // — the GM, or the representative. A Fayda-verified owner outranks eTrade's
-  // registered owner: it's the higher-trust source, and the whole point of
-  // proving identity is to stop trusting typed/looked-up data for this.
-  const ownerSourceName = firstPresent(
-    identity?.owner.name,
-    etradeOwner?.name,
-    user.name?.en,
-  );
-
-  const ownerSourceEmail = firstValidEmail(identity?.owner.email, user.email);
-  // Same reason as `derivedPhone`: this value is written into
-  // `generalManagerPhone` / `poaPhone`, which the API validates with
-  // `@IsValidPhone()`, so an unusable eTrade number here 400s the step instead.
-  const ownerSourcePhone = firstValidPhone(
-    identity?.owner.phone,
-    etradeOwner?.phone,
-    user.phoneNumber,
-  );
-
-  useEffect(() => {
-    if (!gmSameAsOwner) return;
-    // A verified owner's identity is copied server-side and read back from
-    // `identity.gm`; mirroring it into form fields here would send typed
-    // values for something the API already owns.
-    if (identity?.owner.verified) return;
-    setValue("generalManagerName", ownerSourceName, { shouldValidate: true });
-    setValue("generalManagerEmail", ownerSourceEmail, { shouldValidate: true });
-    setValue("generalManagerPhone", ownerSourcePhone, {
-      shouldValidate: true,
-    });
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [gmSameAsOwner, ownerSourceName, ownerSourceEmail, ownerSourcePhone]);
-
-  // The representative's half of the same copy. A verified owner's identity is
-  // copied server-side and read back from `identity.poa`, so only an owner
-  // backed by a typed passport is mirrored into form fields here — the same
-  // split the GM makes above, for the same reason.
-  //
-  // Only non-empty sources are written. A source the owner does not have is a
-  // gap the step renders an input for (see `poaGaps`), and this effect re-runs
-  // whenever any *other* source changes — so blanking here would wipe what the
-  // customer is typing into that input the moment an eTrade lookup lands.
-  useEffect(() => {
-    if (!poaSameAsOwner || identity?.owner.verified) return;
-    if (ownerSourceName) setValue("poaName", ownerSourceName, { shouldValidate: true });
-    if (ownerSourceEmail) setValue("poaEmail", ownerSourceEmail, { shouldValidate: true });
-    if (ownerSourcePhone) setValue("poaPhone", ownerSourcePhone, { shouldValidate: true });
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [poaSameAsOwner, ownerSourceName, ownerSourceEmail, ownerSourcePhone]);
-
   /**
-   * "Same as owner" has two meanings depending on what backs the owner.
+   * Answer the power-of-attorney question.
    *
-   * A Fayda-verified owner is a proven identity, so the declaration is made
-   * server-side: the API copies that identity onto the GM and records what it
-   * did. Anything typed here would arrive wearing a verified badge it hadn't
-   * earned, which is exactly what the verification exists to prevent.
-   *
-   * A foreign company's owner is backed by a typed passport instead, so there
-   * is nothing proven to copy — that stays the local field-mirroring it has
-   * always been.
+   * Persisted server-side rather than held in form state: the answer decides
+   * whose identity the API gates on, and answering "no" tears down any
+   * representative already recorded (details, verification and DARS paper
+   * together) — none of which the form could do on its own.
    */
-  const [gmLinkPending, setGmLinkPending] = useState(false);
-  const toggleGmSameAsOwner = async (checked: boolean) => {
-    setGmSameAsOwner(checked);
-    if (!identity?.owner.verified) {
-      if (!checked) {
-        setValue("generalManagerName", "");
-        setValue("generalManagerEmail", "");
-        setValue("generalManagerPhone", "");
-      }
-      return;
-    }
-
-    setGmLinkPending(true);
-    try {
-      if (checked) await verifaydaService.setGmSameAsOwner();
-      else await verifaydaService.clearGmIdentity();
-      onIdentityChange?.();
-    } catch (err) {
-      setGmSameAsOwner(!checked);
-      setSaveError(
-        (err as { response?: { data?: { message?: string } } })?.response?.data
-          ?.message ??
-        (err instanceof Error
-          ? err.message
-          : "Could not update the general manager"),
-      );
-    } finally {
-      setGmLinkPending(false);
-    }
-  };
-
-  /**
-   * The representative is the owner. Unlike the GM's card this always goes to
-   * the API, whichever backs the owner: the declaration itself is what waives
-   * the DARS delegation paper, so it has to be recorded server-side even when
-   * there is no proven identity to copy and the details are mirrored locally.
-   */
-  const [poaLinkPending, setPoaLinkPending] = useState(false);
-  const togglePoaSameAsOwner = async (checked: boolean) => {
+  const [declarePending, setDeclarePending] = useState(false);
+  const handleDeclare = async (declared: PoaDeclaration) => {
     setSaveError(null);
-    setPoaSameAsOwner(checked);
-    setPoaLinkPending(true);
+    setDeclarePending(true);
     try {
-      if (checked) await verifaydaService.setPoaSameAsOwner();
-      else {
-        await verifaydaService.clearPoaSameAsOwner();
-        // Only the locally mirrored values are ours to clear; a copied identity
-        // is cleared by the call above.
-        if (!identity?.owner.verified) {
-          setValue("poaName", "");
-          setValue("poaEmail", "");
-          setValue("poaPhone", "");
-        }
+      await verifaydaService.setPoaDeclared(declared);
+      if (declared === "no") {
+        // The paper is deleted server-side with the representative; a copy
+        // still sitting in the picker would be re-uploaded on the next step.
+        setDocumentFiles({ ...documentFiles, [POA_DELEGATION_FILE_KEY]: null });
       }
       onIdentityChange?.();
-    } catch (err) {
-      setPoaSameAsOwner(!checked);
-      setSaveError(
-        (err as { response?: { data?: { message?: string } } })?.response?.data
-          ?.message ??
-        (err instanceof Error
-          ? err.message
-          : "Could not update the Power of Attorney"),
-      );
-    } finally {
-      setPoaLinkPending(false);
-    }
-  };
-
-  // Where the GM's details come from depends on how they were established: a
-  // Fayda verification (or a "same as owner" declaration) owns them outright,
-  // and only a company that may still type them falls back to form state.
-  // A verified GM's identity wins, but Fayda's email and phone claims are
-  // optional: what the verification did not supply is typed on this step, and
-  // the API deliberately does not read those back onto the identity (they are
-  // not proven), so the form value is the only place they exist.
-  const gmVerified = identity?.gm.verified ?? false;
-  const gmName = gmVerified
-    ? firstPresent(identity?.gm.name, watch("generalManagerName"))
-    : watch("generalManagerName");
-  const gmEmail = gmVerified
-    ? firstPresent(identity?.gm.email, watch("generalManagerEmail"))
-    : watch("generalManagerEmail");
-  const gmPhone = gmVerified
-    ? firstPresent(identity?.gm.phone, watch("generalManagerPhone"))
-    : watch("generalManagerPhone");
-
-  /**
-   * Whether the GM has been established at all — by verification, by the
-   * "same as owner" declaration, or (only where Fayda is optional) by typing.
-   * Fayda is an Ethiopian national ID, so a foreign company's GM may hold none.
-   */
-  // Matches what the API actually demands (`REQUIRED_COMPANY_INFO`): a name and
-  // a phone. The email is collected but optional — a manager proved through
-  // Fayda may have no email claim, and the notify resolver no longer needs one.
-  const gmTyped = Boolean(
-    watch("generalManagerName")?.trim() &&
-    watch("generalManagerPhone")?.trim(),
-  );
-  const gmEstablished =
-    gmVerified || (identity ? !identity.faydaRequired && gmTyped : gmTyped);
-
-  /**
-   * Same rule for the representative: verified, or entered where Fayda is
-   * optional.
-   *
-   * Matches the API's own rule (`REQUIRED_POA_FIELDS`): a typed representative
-   * counts once they have a name, an email and a phone. The step now renders
-   * inputs for all three, so this is something the customer can actually
-   * satisfy — previously it gated on `poaName`, for which no input existed
-   * anywhere, leaving a foreign freight forwarder permanently stuck.
-   */
-  const poaTyped = Boolean(
-    watch("poaName")?.trim() &&
-    watch("poaEmail")?.trim() &&
-    watch("poaPhone")?.trim(),
-  );
-  const poaEstablished =
-    (identity?.poa.verified ?? false) ||
-    (identity ? !identity.faydaRequired && poaTyped : false);
-
-  /**
-   * Drop an optional representative the company no longer wants.
-   *
-   * Verifying a PoA is one click on a step that calls itself optional, and it
-   * is not reversible from the form: the verification owns the fields (so
-   * blanking them is refused), and its mere existence makes the DARS paper due
-   * — which then blocks the submit AND clamps the resume back to this step. The
-   * settings page has the same escape hatch, but `/settings` is off-limits
-   * until onboarding finishes, so without this the customer is stuck.
-   *
-   * Not offered to a freight forwarder: the API refuses (they must have one).
-   */
-  const [poaRemovePending, setPoaRemovePending] = useState(false);
-  const removePoa = async () => {
-    setSaveError(null);
-    setPoaRemovePending(true);
-    try {
-      await verifaydaService.removePoa();
-      for (const key of [
-        "poaName",
-        "poaEmail",
-        "poaPhone",
-        "poaAddress",
-        "poaLocation",
-      ] as const) {
-        setValue(key, "", { shouldDirty: false });
-      }
-      // The paper is deleted server-side with the identity; a copy still
-      // sitting in the picker would be re-uploaded on the documents step.
-      setDocumentFiles({ ...documentFiles, [POA_DELEGATION_FILE_KEY]: null });
-      onIdentityChange?.();
     } catch (err) {
       setSaveError(
         (err as { response?: { data?: { message?: string } } })?.response?.data
           ?.message ??
         (err instanceof Error
           ? err.message
-          : "Could not remove the Power of Attorney"),
+          : "Could not save your answer"),
       );
     } finally {
-      setPoaRemovePending(false);
+      setDeclarePending(false);
     }
   };
 
+  /**
+   * What no source supplied, per person.
+   *
+   * A Fayda verification owns the fields its claims filled — the API refuses to
+   * let those be overwritten — but its email, phone and address claims are
+   * optional and routinely come back empty. eTrade fills the owner's name and
+   * phone, and nothing at all fills an email.
+   *
+   * So "what still has to be asked" varies per company. Computed here, once,
+   * and handed to both the step (which renders an input per gap) and the schema
+   * (which requires exactly those): **a field is required if and only if there
+   * is an input on screen to fix it in.**
+   */
+  const ownerGaps = {
+    name: !identity?.owner.name?.trim(),
+    email: !identity?.owner.email?.trim(),
+    phone: !identity?.owner.phone?.trim(),
+  };
+  const poaGaps = {
+    name: !identity?.poa.name?.trim(),
+    email: !identity?.poa.email?.trim(),
+    phone: !identity?.poa.phone?.trim(),
+    address: !identity?.poa.address?.trim(),
+  };
+
+  // The owner's name from whichever source established them — powers the
+  // contact step's "same as owner" card.
+  const ownerName = firstPresent(identity?.owner.name, watch("ownerName"));
+  const ownerEmail = firstPresent(identity?.owner.email, watch("ownerEmail"));
+  const ownerPhone = firstPresent(identity?.owner.phone, watch("ownerPhone"));
+
+  const [contactSameAsOwner, setContactSameAsOwner] = useState(false);
   // While linked, mirror the source values into the (disabled) target fields so
   // the copy stays current even if the user goes back and edits the source.
   useEffect(() => {
-    if (!contactSameAsGm) return;
-    setValue("contactPersonName", gmName ?? "", { shouldValidate: true });
-    setValue("contactPersonEmail", gmEmail ?? "");
-    setValue("contactPersonPhone", gmPhone ?? "", { shouldValidate: true });
+    if (!contactSameAsOwner) return;
+    setValue("contactPersonName", ownerName, { shouldValidate: true });
+    setValue("contactPersonEmail", ownerEmail);
+    setValue("contactPersonPhone", ownerPhone, { shouldValidate: true });
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [contactSameAsGm, gmName, gmEmail, gmPhone]);
+  }, [contactSameAsOwner, ownerName, ownerEmail, ownerPhone]);
 
-  const toggleContactSameAsGm = (checked: boolean) => {
-    setContactSameAsGm(checked);
+  const toggleContactSameAsOwner = (checked: boolean) => {
+    setContactSameAsOwner(checked);
     // Checked → the mirror effect fills the fields; unchecked → reset them.
     if (!checked) {
       setValue("contactPersonName", "");
@@ -616,10 +440,10 @@ export default function CompanyProfileForm({
   };
 
   // The DARS delegation paper ships in the same nationality document set as the
-  // rest (the API guarantees it is there), but belongs on the PoA step next to
-  // the details it evidences — so it's split out here and the Documents step
-  // renders the remainder. Both halves share `documentFiles`, so the existing
-  // bulk upload still carries it.
+  // rest (the API guarantees it is there), but belongs on the representation
+  // step next to the details it evidences — so it's split out here and the
+  // Documents step renders the remainder. Both halves share `documentFiles`, so
+  // the existing bulk upload still carries it.
   const poaDocumentField = uploadSetting?.fields?.find(
     (f) => f.fileKey === POA_DELEGATION_FILE_KEY,
   );
@@ -713,8 +537,7 @@ export default function CompanyProfileForm({
 
   // The registration/license details come straight from the eTrade lookup and
   // are not user-editable — shown as a read-only confirmation once a TIN lookup
-  // (or rehydration) has filled them in. The address fields below are separate:
-  // user-entered and required. We watch the values so the display stays current.
+  // (or rehydration) has filled them in.
   const registration = watch([
     "licenceNumber",
     "statusDescription",
@@ -732,51 +555,17 @@ export default function CompanyProfileForm({
   // progress bar all derive from this so adding/removing a step is one edit.
   const stepOrder: CompanyStep[] = [
     "company",
-    "personnel",
+    "owner",
+    "representation",
     "contact",
-    "poa",
     "documents",
   ];
   const currentIdx = stepOrder.indexOf(step);
 
-  // The DARS delegation paper is what proves the representative was actually
-  // delegated, so it's required the moment a PoA exists. The API enforces the
-  // same rule on save, so skipping it here only costs the customer a
-  // round-trip.
-  //
-  // "Exists" is the API's own test (`POA_ATTRIBUTES.some(...)`): ANY detail,
-  // verified or typed. Requiring a complete typed representative here instead
-  // hid the upload from a customer who had entered only a name — for whom the
-  // API still demands the paper, and whose resume would then be clamped back to
-  // this step with nothing on it to fill.
-  const poaAnyDetail = [
-    identity?.poa.name,
-    identity?.poa.email,
-    identity?.poa.phone,
-    identity?.poa.address,
-    watch("poaName"),
-    watch("poaEmail"),
-    watch("poaPhone"),
-    watch("poaLocation"),
-  ].some((v) => v?.trim());
-  const poaProvided = (identity?.poa.verified ?? false) || poaAnyDetail;
-  // A freight forwarder owes the paper whether or not its representative could
-  // verify with Fayda — the API demands it at completion either way. Keying
-  // this on the verification alone hid the upload from a foreign forwarder and
-  // then failed them on submit for a file they were never shown.
-  //
-  // Unless the owner represents the company themselves: nobody delegates to
-  // themselves, so there is no delegation to evidence. Mirrors the API's own
-  // waiver in `assertPoaDelegationSatisfied` — the two must agree, or this
-  // demands a file the server would accept the submission without.
-  //
-  // Split from `poaDue` — "there is a representative, so their details are
-  // owed" — because a self-PoA keeps the second while dropping the first. The
-  // API draws the same line (`poaDue` / `delegationDue` in
-  // getOnboardingRequirements); anything that is about the *details* must key
-  // on `poaDue`, only the paper keys on this.
-  const poaDue = poaProvided || requirePoa;
-  const delegationRequired = poaDue && !poaSameAsOwner;
+  // The DARS delegation paper is owed exactly when the company says it has a
+  // representative. The API enforces the same rule on save, so skipping it here
+  // only costs the customer a round-trip.
+  const delegationRequired = identity?.poaDeclared === "yes";
   const delegationPresent =
     (uploadedDocumentKeys ?? []).includes(POA_DELEGATION_FILE_KEY) ||
     (() => {
@@ -785,90 +574,30 @@ export default function CompanyProfileForm({
     })();
 
   /**
-   * What a Fayda verification did NOT supply, per person.
+   * Is the company's one identity proven?
    *
-   * Fayda's email, phone and address claims are optional and routinely come
-   * back empty, so a *verified* person can still be missing details the API
-   * demands (`REQUIRED_POA_FIELDS`, `REQUIRED_COMPANY_INFO`). Those gaps are
-   * typed instead — the API keeps exactly the keys a claim left empty typeable,
-   * since a claim that returned nothing owns no value to protect.
-   *
-   * Computed here, once, and handed to both the step (which renders an input
-   * per gap) and the schema (which requires exactly those) — a field is
-   * required if and only if there is an input on screen to fix it in.
+   * `identity.identityProven` is the server's verdict, but it is a step behind
+   * a passport number the customer has just typed and not yet saved — so the
+   * live form value counts too. Blocking on the stale server value would refuse
+   * to advance past a field the customer has visibly filled in.
    */
-  // Where Fayda is mandatory an unverified representative must verify rather
-  // than be typed, so nothing is offered until the verification lands.
-  const poaTypedAllowed =
-    !identity || identity.poa.verified || !identity.faydaRequired;
-  // A representative the verification never proved holds only typed details —
-  // the API leaves those unlocked, so the inputs stay on screen and stay
-  // editable. Only a *verified* PoA hides the fields their claim did fill,
-  // which is also the only case the API refuses to let anyone overwrite.
-  const poaGap = (v?: string | null) =>
-    poaTypedAllowed && (!identity?.poa.verified || !v?.trim());
-  /**
-   * "Same as owner" answers each field only as far as the owner actually has
-   * one. Fayda's name, email and phone claims are all optional, the account and
-   * eTrade fallbacks can be empty or unusable, and `REQUIRED_POA_FIELDS` still
-   * demands a name, an email and a phone — so anything the copy could not
-   * supply stays askable. Assuming the copy filled everything is what dead-ends
-   * the submit on "Add your poa phone" with no input anywhere to satisfy it.
-   *
-   * Keyed on the *source*, never on the field's current value: an input that
-   * disappears the moment the first character is typed into it is unusable.
-   * A verified owner's identity is copied server-side, so `identity.poa` is the
-   * source there; otherwise it is the same owner-derived values the mirror
-   * effect writes.
-   */
-  const poaCopyGap = (copied?: string | null, mirrored?: string | null) =>
-    identity?.owner.verified ? !copied?.trim() : !mirrored?.trim();
-  const poaGaps = poaSameAsOwner
-    ? {
-      name: poaCopyGap(identity?.poa.name, ownerSourceName),
-      email: poaCopyGap(identity?.poa.email, ownerSourceEmail),
-      phone: poaCopyGap(identity?.poa.phone, ownerSourcePhone),
-      // The location is the one detail the API never demands, so a blank one
-      // dead-ends nothing — and asking for the owner's city under a card that
-      // says "same as owner" reads as a contradiction.
-      address: false,
-    }
-    : {
-      name: poaGap(identity?.poa.name),
-      email: poaGap(identity?.poa.email),
-      phone: poaGap(identity?.poa.phone),
-      address: poaGap(identity?.poa.address),
-    };
-  // The GM's own verification never falls back to the signed-in account — that
-  // account is the person onboarding, not necessarily the manager — so a GM
-  // verified with no email claim has nowhere else for one to come from. The
-  // name claim is optional too, and `REQUIRED_COMPANY_INFO` demands it, so it
-  // gets the same treatment rather than dead-ending the submit.
-  // "Same as owner" is exempt: the API copies the owner's (account-backed)
-  // contact details across, so there is no gap and no input.
-  const gmGaps = {
-    name: !gmSameAsOwner && gmVerified && !identity?.gm.name?.trim(),
-    email: !gmSameAsOwner && gmVerified && !identity?.gm.email?.trim(),
-    phone: !gmSameAsOwner && gmVerified && !identity?.gm.phone?.trim(),
-  };
+  const passportField =
+    identity?.subject === "poa" ? "poaPassportNumber" : "ownerPassportNumber";
+  const identityProven =
+    (identity?.identityProven ?? false) ||
+    ((identity?.passportAccepted ?? false) &&
+      Boolean(watch(passportField)?.trim()));
 
   const requiredKeys: (keyof FormData)[] = [];
-  if (step === "personnel") {
-    // The manager's email is offered but not demanded: the API dropped it from
-    // `REQUIRED_COMPANY_INFO` once the notify resolver stopped depending on it.
-    // The name and phone are still required there, so they are still required
-    // here.
-    if (gmGaps.name) requiredKeys.push("generalManagerName");
-    if (gmGaps.phone) requiredKeys.push("generalManagerPhone");
-  } else if (step === "poa" && poaDue) {
-    // Only once a PoA is required or provided: an untouched optional PoA is
-    // still a step the customer may walk straight past.
-    //
-    // `poaDue`, NOT `delegationRequired`: the paper is waived for a self-PoA
-    // but `REQUIRED_POA_FIELDS` is not, and the API reports every one of them
-    // missing (`missingPoaFields` keys on its own `poaDue`) — which fails the
-    // submit and clamps the resume back here. Keying this on the paper let the
-    // customer walk past an input this step had already put on screen.
+  if (step === "owner") {
+    // All three are required by the API (`REQUIRED_COMPANY_INFO`), and an input
+    // is rendered for each one a Fayda claim did not already own.
+    if (ownerGaps.name) requiredKeys.push("ownerName");
+    if (ownerGaps.email) requiredKeys.push("ownerEmail");
+    if (ownerGaps.phone) requiredKeys.push("ownerPhone");
+  } else if (step === "representation" && identity?.poaDeclared === "yes") {
+    // Only once a representative is actually declared: a company that answered
+    // "no" has no representative to describe.
     if (poaGaps.name) requiredKeys.push("poaName");
     if (poaGaps.email) requiredKeys.push("poaEmail");
     if (poaGaps.phone) requiredKeys.push("poaPhone");
@@ -879,19 +608,15 @@ export default function CompanyProfileForm({
    * Collect the messages for a set of fields into one sentence.
    *
    * A failed `trigger()` used to return silently, so Continue simply did
-   * nothing — and every field whose input is conditionally rendered (or derived
-   * and never rendered at all) turned into an invisible dead end. Naming the
-   * failures is the whole point: the ones worth reporting are exactly the ones
-   * with no error text on screen to read.
+   * nothing — and every field whose input is conditionally rendered turned into
+   * an invisible dead end. Naming the failures is the whole point: the ones
+   * worth reporting are exactly the ones with no error text on screen to read.
    */
   const describeErrors = (fields: (keyof FormData)[]): string => {
     // Re-parse rather than read `errors`: that's the render-time snapshot, and
     // this runs immediately after an `await trigger()` that has not re-rendered
     // yet, so the closure would still be holding the previous attempt's state.
-    const parsed = buildOnboardingSchema(
-      identity?.passportRequired === true,
-      requiredKeys,
-    ).safeParse(getValues());
+    const parsed = buildOnboardingSchema(requiredKeys).safeParse(getValues());
     const wanted = new Set<string>(fields as string[]);
     const messages = parsed.success
       ? []
@@ -903,21 +628,10 @@ export default function CompanyProfileForm({
       : "Some details on this step are incomplete. Please review the fields above.";
   };
 
-  /**
-   * The fields this step actually validates. `stepFields` covers what the step
-   * always renders; the company step additionally exposes company email/phone
-   * as inputs when nothing could be derived for them, and a field is validated
-   * exactly when the customer can see and fix it.
-   */
-  const fieldsForStep = (s: CompanyStep): (keyof FormData)[] => {
-    if (s !== "company" || !identity) return stepFields[s];
-    return [...stepFields.company];
-  };
-
   /** Validate + persist the current step, returning whether we may advance. */
   const saveCurrentStep = async (): Promise<boolean> => {
     setSaveError(null);
-    const fields = fieldsForStep(step);
+    const fields = stepFields[step];
     const isValid = await trigger(fields);
     if (!isValid) {
       setSaveError(describeErrors(fields));
@@ -969,13 +683,13 @@ export default function CompanyProfileForm({
       }
 
       setSaveError(null);
-      // Deliberately NOT `handleSubmit`: that re-validated all 34 schema fields
-      // — including every field belonging to a step that isn't on screen — and
-      // on failure did nothing at all, no alert and no navigation, which is the
+      // Deliberately NOT `handleSubmit`: that re-validated every schema field —
+      // including every field belonging to a step that isn't on screen — and on
+      // failure did nothing at all, no alert and no navigation, which is the
       // "Submit for review" button that appears dead. Each step has already
-      // validated and saved its own fields, and the API's `markOnboardingComplete`
-      // is the authority on what is still outstanding; its message reaches the
-      // customer through `submitError`.
+      // validated and saved its own fields, and the API's
+      // `markOnboardingComplete` is the authority on what is still outstanding;
+      // its message reaches the customer through `submitError`.
       onSubmit(buildPayload(getValues(), user));
       return;
     }
@@ -995,66 +709,50 @@ export default function CompanyProfileForm({
       );
       return;
     }
-    // Fayda verification is proved outside the form state, so it gates here
-    // rather than through zod. The passport number is a plain typed field —
-    // buildOnboardingSchema already requires it when passportRequired, so
-    // saveCurrentStep()'s trigger() below catches that; checking the stale
-    // server-side identity.owner.passportNumber here would block a value the
-    // user just typed but hasn't saved yet.
-    if (
-      step === "company" &&
-      identity?.faydaRequired &&
-      !identity.owner.verified
-    ) {
+    // The declaration decides whose identity is verified, so it has to be
+    // answered before the verification below can mean anything.
+    if (step === "representation" && !identity?.poaDeclared) {
       setSaveError(
-        "Verify the company owner's identity with Fayda before continuing.",
+        "Tell us whether anyone holds power of attorney for this company.",
       );
       return;
     }
-    // The GM is established through Fayda now, so the step gates on the
-    // identity rather than on typed text — same strength as the old required
-    // fields, different evidence. A foreign company's GM may hold no Fayda ID,
-    // so typed details still satisfy it there.
-    if (step === "personnel" && !gmEstablished) {
+    // The verification itself is proved outside the form state, so it gates
+    // here rather than through zod.
+    if (step === "representation" && !identityProven) {
+      const who =
+        identity?.subject === "poa"
+          ? "your Power of Attorney"
+          : "the company owner";
       setSaveError(
-        identity?.faydaRequired
-          ? "Verify the general manager with Fayda, or tick “same as owner” if they are the company's owner."
-          : "Add the general manager's details, or verify them with Fayda.",
+        identity?.passportAccepted
+          ? `Verify ${who} with Fayda, or enter their passport number.`
+          : `Verify ${who} with Fayda before continuing.`,
       );
       return;
     }
-    if (step === "poa" && requirePoa && !poaEstablished) {
-      setSaveError(
-        identity?.faydaRequired
-          ? "Freight forwarders act on other companies' behalf, so the Power of Attorney's identity must be verified with Fayda."
-          : "Freight forwarders act on other companies' behalf, so a Power of Attorney is required.",
-      );
-      return;
-    }
-    // The PoA step also gates on a file, which lives outside the form state.
-    if (step === "poa" && delegationRequired && !delegationPresent) {
+    // The step also gates on a file, which lives outside the form state.
+    if (step === "representation" && delegationRequired && !delegationPresent) {
       setDocumentFieldErrors({
         [POA_DELEGATION_FILE_KEY]: "DARS delegation paper is required",
       });
       // Validate the text fields too, so every problem shows at once.
-      const fieldsOk = await trigger(stepFields.poa);
+      const fieldsOk = await trigger(stepFields.representation);
       setSaveError(
         [
-          requirePoa
-            ? "Freight forwarders must provide Power of Attorney details and the DARS delegation paper."
-            : "Upload the DARS delegation paper for the Power of Attorney you entered, or clear the PoA details to skip.",
-          fieldsOk ? null : describeErrors(stepFields.poa),
+          "Upload the DARS delegation paper for the representative you named.",
+          fieldsOk ? null : describeErrors(stepFields.representation),
         ]
           .filter(Boolean)
           .join(" "),
       );
       return;
     }
-    // The API will not accept the PoA's details until the paper evidencing the
-    // delegation is actually on file, so the selection made on this step has to
-    // be uploaded before the save — not held back until the documents step,
-    // which is unreachable while this save keeps failing.
-    if (step === "poa" && delegationRequired && onUploadDocuments) {
+    // The API will not accept the representative's details until the paper
+    // evidencing the delegation is actually on file, so the selection made on
+    // this step has to be uploaded before the save — not held back until the
+    // documents step, which is unreachable while this save keeps failing.
+    if (step === "representation" && delegationRequired && onUploadDocuments) {
       const pending = documentFiles[POA_DELEGATION_FILE_KEY];
       const hasPending = Array.isArray(pending)
         ? pending.length > 0
@@ -1092,8 +790,6 @@ export default function CompanyProfileForm({
           {step === "company" && (
             <CompanyInfoStep
               form={form}
-              identity={identity}
-              verifiedIdentity={verifiedIdentity}
               tinStatus={tinStatus}
               tinVerified={tinVerified}
               hasRegistrationDetails={hasRegistrationDetails}
@@ -1103,46 +799,36 @@ export default function CompanyProfileForm({
             />
           )}
 
-          {step === "personnel" && (
-            <PersonnelStep
+          {step === "owner" && (
+            <OwnerStep
               form={form}
               identity={identity}
               etradeOwner={etradeOwner}
-              gmSameAsOwner={gmSameAsOwner}
-              onToggleGmSameAsOwner={toggleGmSameAsOwner}
-              gmLinkPending={gmLinkPending}
-              gmVerified={gmVerified}
-              gaps={gmGaps}
+              gaps={ownerGaps}
+            />
+          )}
+
+          {step === "representation" && (
+            <RepresentationStep
+              form={form}
+              identity={identity}
+              onDeclare={handleDeclare}
+              declarePending={declarePending}
+              gaps={poaGaps}
+              poaDocumentSetting={poaDocumentSetting}
+              documentFiles={documentFiles}
+              uploadedDocumentKeys={uploadedDocumentKeys}
+              documentFieldErrors={documentFieldErrors}
+              onDocumentFilesChange={handleDocumentFilesChange}
             />
           )}
 
           {step === "contact" && (
             <ContactStep
               form={form}
-              gmName={gmName}
-              contactSameAsGm={contactSameAsGm}
-              onToggleContactSameAsGm={toggleContactSameAsGm}
-            />
-          )}
-
-          {step === "poa" && (
-            <PoaStep
-              form={form}
-              identity={identity}
-              requirePoa={requirePoa}
-              poaSameAsOwner={poaSameAsOwner}
-              onTogglePoaSameAsOwner={togglePoaSameAsOwner}
-              poaLinkPending={poaLinkPending}
-              etradeOwner={etradeOwner}
-              gaps={poaGaps}
-              onRemovePoa={removePoa}
-              removePending={poaRemovePending}
-              delegationRequired={delegationRequired}
-              poaDocumentSetting={poaDocumentSetting}
-              documentFiles={documentFiles}
-              uploadedDocumentKeys={uploadedDocumentKeys}
-              documentFieldErrors={documentFieldErrors}
-              onDocumentFilesChange={handleDocumentFilesChange}
+              ownerName={ownerName}
+              contactSameAsOwner={contactSameAsOwner}
+              onToggleContactSameAsOwner={toggleContactSameAsOwner}
             />
           )}
 
@@ -1197,6 +883,7 @@ export default function CompanyProfileForm({
               disabled={
                 isPending ||
                 saving ||
+                declarePending ||
                 (step === "documents" && !hasDocuments && loadingDocuments)
               }
               loading={isPending || saving}
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/SourcedField.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/SourcedField.tsx
new file mode 100644
index 000000000..480606db8
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/SourcedField.tsx
@@ -0,0 +1,61 @@
+import { Badge, Group, Stack, Text } from "@mantine/core";
+import type { ReactNode } from "react";
+
+/** Where a prefilled value came from, shown as a badge next to it. */
+export type FieldSource = "eTrade" | "Fayda";
+
+const SOURCE_NOTE: Record<FieldSource, string> = {
+  eTrade: "From your eTrade licence",
+  Fayda: "From the Fayda verification",
+};
+
+/**
+ * One person-detail field that may already be answered for us.
+ *
+ * The onboarding wizard fills what it can from the eTrade lookup and the Fayda
+ * verification, and asks the customer only for what neither supplied. Both
+ * sources are patchy in practice — eTrade returns no email at all and often no
+ * manager name; Fayda's email and phone claims are optional and routinely come
+ * back empty — so "what is missing" varies per company and cannot be decided
+ * once at build time.
+ *
+ * This is the single place that decision is rendered: a supplied value shows
+ * read-only with its provenance, a gap shows the input. It pairs with
+ * `requiredKeys` in CompanyProfileForm, which requires exactly the fields that
+ * fall through to `children` — the invariant being that **a field is required
+ * if and only if there is an input on screen to satisfy it**.
+ */
+export default function SourcedField({
+  label,
+  value,
+  source,
+  children,
+}: {
+  label: string;
+  /** The value a source supplied. Blank/absent means "ask the customer". */
+  value?: string | null;
+  source: FieldSource;
+  /** The input rendered when no source supplied a value. */
+  children: ReactNode;
+}) {
+  if (!value?.trim()) return <>{children}</>;
+
+  return (
+    <Stack gap={2}>
+      <Group gap="xs" align="center">
+        <Text size="xs" c="dimmed">
+          {label}
+        </Text>
+        <Badge size="xs" variant="light" color="edr-green">
+          {source}
+        </Badge>
+      </Group>
+      <Text className="wrap-break-word" size="sm" c="edr-text" fw={500}>
+        {value}
+      </Text>
+      <Text size="xs" c="edr-muted">
+        {SOURCE_NOTE[source]}
+      </Text>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/helpers.ts b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/helpers.ts
index 20e889235..ca745a953 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/helpers.ts
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/helpers.ts
@@ -69,7 +69,6 @@ export function normalizeIdentityPhones(
     ...identity,
     owner: fix(identity.owner),
     poa: fix(identity.poa),
-    gm: fix(identity.gm),
   };
 }
 
@@ -97,15 +96,14 @@ export function buildPayload(
     vatNumber: data.vatNumber,
     attributes: {
       ownerPassportNumber: data.ownerPassportNumber || undefined,
+      poaPassportNumber: data.poaPassportNumber || undefined,
       contactPersonName: data.contactPersonName,
       contactPersonPosition: data.contactPersonPosition || undefined,
       contactPersonEmail: data.contactPersonEmail || undefined,
       contactPersonPhone: data.contactPersonPhone,
-      generalManagerName: data.generalManagerName,
-      generalManagerEmail: data.generalManagerEmail,
-      generalManagerPhone: data.generalManagerPhone,
-      // The representative's own details are written by their Fayda
-      // verification, so the city is all the form has to send.
+      ownerName: data.ownerName,
+      ownerEmail: data.ownerEmail,
+      ownerPhone: data.ownerPhone,
       poaLocation: data.poaLocation || undefined,
     },
   };
@@ -137,21 +135,20 @@ export function stepPayload(
       return {
         companyAddress: d.companyAddress,
         vatNumber: d.vatNumber,
-        ownerPassportNumber: d.ownerPassportNumber || undefined,
         ...etrade,
       };
     }
-    case "personnel":
+    case "owner":
       // `|| undefined`, never "": the DTO's `@IsOptional()` only skips null and
       // undefined, so an empty string is validated and 400s with
-      // "generalManagerEmail must be an email". An Ethiopian company never types
-      // these — the GM comes from the Fayda verification (or the "same as owner"
-      // declaration), so the form fields are legitimately blank and would fail a
-      // step that has no input to fix.
+      // "ownerEmail must be an email". A field the eTrade lookup or the Fayda
+      // claim already filled is legitimately blank in the form — it has no
+      // input — so sending "" would fail a step with nothing on screen to fix.
       return {
-        generalManagerName: d.generalManagerName || undefined,
-        generalManagerEmail: d.generalManagerEmail || undefined,
-        generalManagerPhone: d.generalManagerPhone || undefined,
+        ownerName: d.ownerName || undefined,
+        ownerEmail: d.ownerEmail || undefined,
+        ownerPhone: d.ownerPhone || undefined,
+        ownerPassportNumber: d.ownerPassportNumber || undefined,
       };
     case "contact":
       return {
@@ -160,12 +157,13 @@ export function stepPayload(
         contactPersonEmail: d.contactPersonEmail || undefined,
         contactPersonPhone: d.contactPersonPhone,
       };
-    case "poa":
+    case "representation":
       return {
         poaName: d.poaName || undefined,
         poaEmail: d.poaEmail || undefined,
         poaPhone: d.poaPhone || undefined,
         poaLocation: d.poaLocation || undefined,
+        poaPassportNumber: d.poaPassportNumber || undefined,
       };
     default:
       return {};
@@ -183,6 +181,7 @@ export function toFormValues(p: ProfileResponse): FormData {
     tinNumber: tin,
     vatNumber: p.vatNumber ?? "",
     ownerPassportNumber: p.identity?.owner.passportNumber ?? "",
+    poaPassportNumber: p.identity?.poa.passportNumber ?? "",
     licenceNumber: p.licenceNumber ?? "",
     statusDescription: p.statusDescription ?? "",
     dateRegistered: p.dateRegistered ?? "",
@@ -198,9 +197,9 @@ export function toFormValues(p: ProfileResponse): FormData {
     contactPersonPosition: p.contactPersonPosition ?? "",
     contactPersonEmail: p.contactPersonEmail ?? "",
     contactPersonPhone: p.contactPersonPhone ?? "",
-    generalManagerName: p.generalManagerName ?? "",
-    generalManagerEmail: p.generalManagerEmail ?? "",
-    generalManagerPhone: p.generalManagerPhone ?? "",
+    ownerName: p.ownerName ?? "",
+    ownerEmail: p.ownerEmail ?? "",
+    ownerPhone: p.ownerPhone ?? "",
     poaName: p.poaName ?? "",
     poaPhone: p.poaPhone ?? "",
     poaAddress: p.poaAddress ?? "",
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
index 95755e777..ebff24687 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
@@ -35,9 +35,9 @@ const values = (over: Partial<FormData> = {}): FormData =>
     contactPersonPosition: "",
     contactPersonEmail: "",
     contactPersonPhone: "+251911223344",
-    generalManagerName: "",
-    generalManagerEmail: "",
-    generalManagerPhone: "",
+    ownerName: "",
+    ownerEmail: "",
+    ownerPhone: "",
     poaName: "",
     poaPhone: "",
     poaAddress: "",
@@ -131,31 +131,29 @@ describe("buildOnboardingSchema (conditionally required fields)", () => {
     data: FormData,
     required: (keyof FormData)[],
   ): (keyof FormData)[] => {
-    const parsed = buildOnboardingSchema(false, required).safeParse(data);
+    const parsed = buildOnboardingSchema(required).safeParse(data);
     return parsed.success
       ? []
       : (parsed.error.issues.map((i) => i.path[0]) as (keyof FormData)[]);
   };
 
-  // Fayda's email/phone claims are optional: the step renders an input for what
-  // the verification did not supply, and requires exactly those. Nothing else —
-  // a field with no input on screen must never fail Continue.
+  // eTrade returns no email and Fayda's email/phone claims are optional: the
+  // step renders an input for what no source supplied, and requires exactly
+  // those. Nothing else — a field with no input on screen must never fail
+  // Continue.
   it("requires only the keys it is handed", () => {
-    const issues = issuesFor(values(), [
-      "generalManagerEmail",
-      "generalManagerPhone",
-    ]);
-    expect(issues).toEqual(["generalManagerEmail", "generalManagerPhone"]);
+    const issues = issuesFor(values(), ["ownerEmail", "ownerPhone"]);
+    expect(issues).toEqual(["ownerEmail", "ownerPhone"]);
   });
 
   it("passes once those keys are filled", () => {
     expect(
       issuesFor(
         values({
-          generalManagerEmail: "gm@example.com",
-          generalManagerPhone: "+251911223344",
+          ownerEmail: "owner@example.com",
+          ownerPhone: "+251911223344",
         }),
-        ["generalManagerEmail", "generalManagerPhone"],
+        ["ownerEmail", "ownerPhone"],
       ),
     ).toEqual([]);
   });
@@ -165,9 +163,7 @@ describe("buildOnboardingSchema (conditionally required fields)", () => {
   });
 
   it("names the field in the message, so it reads under its own input", () => {
-    const parsed = buildOnboardingSchema(false, ["poaEmail"]).safeParse(
-      values(),
-    );
+    const parsed = buildOnboardingSchema(["poaEmail"]).safeParse(values());
     expect(parsed.success).toBe(false);
     if (parsed.success) return;
     expect(parsed.error.issues[0]?.message).toBe(
@@ -198,37 +194,33 @@ describe("stepPayload (company)", () => {
   });
 });
 
-describe("stepPayload (personnel)", () => {
-  // An Ethiopian company never types the GM — Fayda (or "same as owner") owns
-  // those fields — so the form holds "". `@IsOptional()` on the DTO skips only
-  // null/undefined, so an empty string is validated and comes back as
-  // "generalManagerEmail must be an email", on a step that renders no input.
-  it("omits blank GM fields instead of sending empty strings", () => {
+describe("stepPayload (owner)", () => {
+  // A Fayda claim owns whatever it supplied, so the form holds "" for those.
+  // `@IsOptional()` on the DTO skips only null/undefined, so an empty string is
+  // validated and comes back as "ownerEmail must be an email" — on a step that
+  // renders no input for it.
+  it("omits blank owner fields instead of sending empty strings", () => {
     const payload = stepPayload(
-      "personnel",
-      values({
-        generalManagerName: "",
-        generalManagerEmail: "",
-        generalManagerPhone: "",
-      }),
+      "owner",
+      values({ ownerName: "", ownerEmail: "", ownerPhone: "" }),
     );
-    expect(payload.generalManagerName).toBeUndefined();
-    expect(payload.generalManagerEmail).toBeUndefined();
-    expect(payload.generalManagerPhone).toBeUndefined();
+    expect(payload.ownerName).toBeUndefined();
+    expect(payload.ownerEmail).toBeUndefined();
+    expect(payload.ownerPhone).toBeUndefined();
   });
 
-  it("still sends typed GM details (foreign company)", () => {
+  it("sends the owner details the customer typed or eTrade prefilled", () => {
     const payload = stepPayload(
-      "personnel",
+      "owner",
       values({
-        generalManagerName: "Abebe Bikila",
-        generalManagerEmail: "gm@example.com",
-        generalManagerPhone: "+251911223344",
+        ownerName: "Abebe Bikila",
+        ownerEmail: "owner@example.com",
+        ownerPhone: "+251911223344",
       }),
     );
-    expect(payload.generalManagerName).toBe("Abebe Bikila");
-    expect(payload.generalManagerEmail).toBe("gm@example.com");
-    expect(payload.generalManagerPhone).toBe("+251911223344");
+    expect(payload.ownerName).toBe("Abebe Bikila");
+    expect(payload.ownerEmail).toBe("owner@example.com");
+    expect(payload.ownerPhone).toBe("+251911223344");
   });
 });
 
@@ -271,10 +263,11 @@ describe("firstValidEmail", () => {
 describe("normalizeIdentityPhones", () => {
   it("converts a local Fayda phone claim to E.164", () => {
     const identity = {
-      faydaRequired: true,
-      passportRequired: false,
+      passportAccepted: false,
+      poaDeclared: "yes",
+      subject: "poa",
       owner: {
-        verified: true,
+        verified: false,
         name: "A",
         phone: "0911223344",
         email: null,
@@ -283,28 +276,22 @@ describe("normalizeIdentityPhones", () => {
         passportNumber: null,
       },
       poa: {
-        verified: false,
-        name: null,
-        phone: null,
-        email: null,
-        address: null,
-        verifiedAt: null,
-      },
-      gm: {
-        verified: false,
-        name: null,
+        verified: true,
+        name: "B",
         phone: "251911223344",
         email: null,
         address: null,
         verifiedAt: null,
+        passportNumber: null,
       },
-      gmSameAsOwner: false,
-      complete: false,
+      identityProven: true,
+      etradeManagerName: null,
+      ownerMatchesEtrade: null,
+      complete: true,
     } as CompanyIdentityState;
 
     const fixed = normalizeIdentityPhones(identity)!;
     expect(fixed.owner.phone).toBe("+251911223344");
-    expect(fixed.gm.phone).toBe("+251911223344");
-    expect(fixed.poa.phone).toBeNull();
+    expect(fixed.poa.phone).toBe("+251911223344");
   });
 });
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 0017598e9..770e565b8 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
@@ -5,9 +5,9 @@ import { isValidPhone } from "@/components/PhoneField";
 
 export type CompanyStep =
   | "company"
-  | "personnel"
+  | "owner"
+  | "representation"
   | "contact"
-  | "poa"
   | "documents"
   | "additional";
 
@@ -27,10 +27,13 @@ export const onboardingSchema = z.object({
     .string()
     .min(1, "VAT number is required")
     .regex(/^\d{10,11}$/, "VAT number must be 10 or 11 digits"),
-  // The owner's passport number — the foreign-company identity credential
-  // (Fayda is an Ethiopian national ID). Required only for a foreign company;
-  // enforced in buildOnboardingSchema since that depends on `nationality`.
+  // Passport numbers — the alternative identity credential for a foreign
+  // company (Fayda is an Ethiopian national ID). Only the one belonging to the
+  // declared identity subject is ever asked for, and only when that person has
+  // not verified with Fayda — so requiredness is decided per render and lives
+  // in `requiredKeys`, not here.
   ownerPassportNumber: z.string().optional(),
+  poaPassportNumber: z.string().optional(),
   licenceNumber: z.string().optional(),
   statusDescription: z.string().optional(),
   dateRegistered: z.string().optional(),
@@ -57,21 +60,23 @@ export const onboardingSchema = z.object({
     .string()
     .min(1, "Contact person phone is required")
     .refine(isValidPhone, "Enter a valid phone number"),
-  // Optional here, not unrequired: the GM is now established by Fayda — either
-  // verified in their own right or declared the same person as the owner — so
-  // for an Ethiopian company these fields are never typed and would fail a
-  // blanket `min(1)`. Presence is gated per nationality in the step's own
-  // check, where the identity state is available; zod only polices format for
-  // the foreign companies that still type them.
-  generalManagerName: z.string().optional(),
-  generalManagerEmail: z
+  // The owner — whoever the eTrade licence names as the business's manager.
+  //
+  // Optional here, not unrequired: the eTrade lookup fills the name and phone,
+  // and a Fayda verification can fill all three, so on a well-supplied company
+  // none of them is typed and a blanket `min(1)` would fail a step with no
+  // input on screen. What IS required is decided per render — a field is
+  // required exactly when the step renders an input for it (`requiredKeys`).
+  // zod only polices format here.
+  ownerName: z.string().optional(),
+  ownerEmail: z
     .string()
     .optional()
     .refine(
       (v) => !v || z.string().email().safeParse(v).success,
-      "Invalid Manager email",
+      "Invalid owner email",
     ),
-  generalManagerPhone: z
+  ownerPhone: z
     .string()
     .optional()
     .refine((v) => !v || isValidPhone(v), "Enter a valid phone number"),
@@ -105,42 +110,36 @@ const CONDITIONAL_LABELS: Partial<Record<keyof FormData, string>> = {
   poaName: "Representative's name",
   poaEmail: "Representative's email",
   poaPhone: "Representative's phone",
-  generalManagerName: "General manager's name",
-  generalManagerEmail: "General manager's email",
-  generalManagerPhone: "General manager's phone",
+  poaPassportNumber: "Representative's passport number",
+  ownerName: "Owner's name",
+  ownerEmail: "Owner's email",
+  ownerPhone: "Owner's phone",
+  ownerPassportNumber: "Owner's passport number",
 };
 
 /**
- * The PoA's and GM's identifying fields normally come from their Fayda
- * verification, so nothing in the base schema requires them. But Fayda's email
- * and phone claims are optional and routinely come back empty, and the steps
- * render an input for whatever the verification did not supply — so those
- * fields become mandatory exactly then.
+ * The owner's and the representative's identifying fields arrive from three
+ * places — the eTrade lookup, a Fayda verification, or the customer typing them
+ * — and which one supplies what varies per company. eTrade returns no email at
+ * all; Fayda's email and phone claims are optional and routinely come back
+ * empty. So nothing in the base schema requires them, and the steps render an
+ * input for whatever no source supplied.
  *
  * `requiredKeys` is that decision, made by CompanyProfileForm from the same
- * state that drives the rendering: a field is required iff an input exists for
- * it. Passing it in (rather than deriving it here) is what keeps the two from
- * drifting into a Continue button that fails on a field nobody can see.
+ * state that drives the rendering: **a field is required iff an input exists
+ * for it**. Passing it in (rather than deriving it here) is what keeps the two
+ * from drifting into a Continue button that fails on a field nobody can see.
  */
 export function buildOnboardingSchema(
-  /** True for a foreign company: the owner's passport number is mandatory. */
-  passportRequired = false,
   /** Fields the current step renders an input for and must not leave blank. */
   requiredKeys: readonly (keyof FormData)[] = [],
 ) {
-  if (!passportRequired && requiredKeys.length === 0) return onboardingSchema;
+  if (requiredKeys.length === 0) return onboardingSchema;
   return onboardingSchema.superRefine((d, ctx) => {
-    if (passportRequired && !d.ownerPassportNumber?.trim()) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        path: ["ownerPassportNumber"],
-        message: "The owner's passport number is required",
-      });
-    }
     for (const key of requiredKeys) {
       if (d[key]?.trim()) continue;
       ctx.addIssue({
-        code: z.ZodIssueCode.custom,
+        code: "custom",
         path: [key],
         message: `${CONDITIONAL_LABELS[key] ?? key} is required`,
       });
@@ -184,25 +183,29 @@ export const ETRADE_BUNDLE_FIELDS = [
  * (`REQUIRED_COMPANY_INFO`), and reports it with a message.
  */
 export const stepFields: Record<CompanyStep, (keyof FormData)[]> = {
-  // Only the three fields this step actually renders an input for. The company
-  // name and the registered address are eTrade's, shown read-only.
-  company: ["tinNumber", "vatNumber", "ownerPassportNumber"],
-  personnel: [
-    "generalManagerName",
-    "generalManagerEmail",
-    "generalManagerPhone",
-  ],
+  // Only what this step actually renders an input for. The company name and the
+  // registered address are eTrade's, shown read-only.
+  company: ["tinNumber", "vatNumber"],
+  // `REQUIRED_COMPANY_INFO` demands all three server-side, so the step offers
+  // an input wherever eTrade and Fayda between them left a gap.
+  owner: ["ownerName", "ownerEmail", "ownerPhone", "ownerPassportNumber"],
   contact: [
     "contactPersonName",
     "contactPersonPosition",
     "contactPersonEmail",
     "contactPersonPhone",
   ],
-  // The API requires poaName/poaEmail/poaPhone from a freight forwarder
-  // (`REQUIRED_POA_FIELDS`), so the step has to offer them wherever the
-  // representative isn't proven by Fayda — otherwise the save is rejected
-  // naming fields the form never rendered.
-  poa: ["poaName", "poaEmail", "poaPhone", "poaLocation"],
+  // The API requires poaName/poaEmail/poaPhone once a representative is
+  // declared (`REQUIRED_POA_FIELDS`), so the step has to offer them wherever
+  // Fayda didn't supply them — otherwise the save is rejected naming fields the
+  // form never rendered.
+  representation: [
+    "poaName",
+    "poaEmail",
+    "poaPhone",
+    "poaLocation",
+    "poaPassportNumber",
+  ],
   documents: [],
   additional: [],
 };
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
index 0473b26d1..f57d7c433 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
@@ -2,11 +2,9 @@ import { Stack, TextInput } from "@mantine/core";
 import type { UseFormReturn } from "react-hook-form";
 
 import type { CompanyRegistrationData } from "@edr/types";
-import FaydaVerifyPanel from "@/components/FaydaVerifyPanel";
 import ETradeInfo, {
   type ETradeStatus,
 } from "@/components/onboarding/ETradeInfo";
-import type { CompanyIdentityState } from "@/services/verifayda.service";
 
 import type { FormData } from "../schema";
 import ETradeCompanyCard from "../ETradeCompanyCard";
@@ -14,10 +12,6 @@ import StepSection from "../StepSection";
 
 export interface CompanyInfoStepProps {
   form: UseFormReturn<FormData>;
-  /** Fayda verification state, phone-normalized by the parent. */
-  identity?: CompanyIdentityState;
-  /** True when Fayda (not a passport) is what this company must prove with. */
-  verifiedIdentity: boolean;
   tinStatus: ETradeStatus;
   tinVerified: boolean;
   /** Registration fields are already populated (a lookup passed, now or earlier). */
@@ -29,8 +23,6 @@ export interface CompanyInfoStepProps {
 
 export default function CompanyInfoStep({
   form,
-  identity,
-  verifiedIdentity,
   tinStatus,
   tinVerified,
   hasRegistrationDetails,
@@ -66,48 +58,6 @@ export default function CompanyInfoStep({
 
       <StepSection
         index={2}
-        title="Owner identity"
-        subtitle={
-          !identity?.owner.verified && !verifiedIdentity
-            ? "Provide the company owner's passport number."
-            : undefined
-        }
-        status={
-          verifiedIdentity
-            ? identity?.owner.verified
-              ? "done"
-              : identity?.faydaRequired
-                ? "blocked"
-                : "todo"
-            : (watch("ownerPassportNumber")?.trim()?.length ?? 0) > 0
-              ? "done"
-              : identity?.passportRequired
-                ? "blocked"
-                : "todo"
-        }
-      >
-        {identity && (
-          <>
-            <FaydaVerifyPanel
-              subject="owner"
-              title="Owner"
-              state={identity.owner}
-              required={identity.faydaRequired}
-            />
-            {identity.passportRequired && (
-              <TextInput
-                label="Owner Passport Number"
-                placeholder="P1234567"
-                error={errors.ownerPassportNumber?.message}
-                {...register("ownerPassportNumber")}
-              />
-            )}
-          </>
-        )}
-      </StepSection>
-
-      <StepSection
-        index={3}
         title="Company TIN"
         subtitle="We'll pull your registration straight from eTrade — nothing to type by hand once it's found."
         status={
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/ContactStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/ContactStep.tsx
index e5d16ea5f..b03e879f1 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/ContactStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/ContactStep.tsx
@@ -9,19 +9,19 @@ import { LinkCheckboxCard } from "../LinkCheckboxCard";
 export interface ContactStepProps {
   form: UseFormReturn<FormData>;
   /**
-   * The GM's name from whichever source established them (verification or form)
-   * — the "same as GM" card only makes sense once there is a GM.
+   * The owner's name from whichever source established them (eTrade, Fayda or
+   * typed) — the "same as owner" card only makes sense once there is one.
    */
-  gmName?: string;
-  contactSameAsGm: boolean;
-  onToggleContactSameAsGm: (checked: boolean) => void;
+  ownerName?: string;
+  contactSameAsOwner: boolean;
+  onToggleContactSameAsOwner: (checked: boolean) => void;
 }
 
 export default function ContactStep({
   form,
-  gmName,
-  contactSameAsGm,
-  onToggleContactSameAsGm,
+  ownerName,
+  contactSameAsOwner,
+  onToggleContactSameAsOwner,
 }: ContactStepProps) {
   const {
     register,
@@ -34,15 +34,15 @@ export default function ContactStep({
       <Text fw={600} size="sm" c="edr-text">
         Contact Person
       </Text>
-      {/* `gmName`, not the raw form field: a Fayda-verified GM never
-          fills `generalManagerName`, so gating on it hid this card from
-          every Ethiopian company — the majority case. */}
-      {gmName && (
+      {/* `ownerName`, not the raw form field: the owner's name usually comes
+          from the eTrade lookup or a Fayda claim rather than being typed, so
+          gating on the form value would hide this card from most companies. */}
+      {ownerName && (
         <LinkCheckboxCard
-          checked={contactSameAsGm}
-          onToggle={onToggleContactSameAsGm}
-          title="Same as General Manager"
-          description="Reuse the general manager's name, email and phone. Uncheck to enter different details."
+          checked={contactSameAsOwner}
+          onToggle={onToggleContactSameAsOwner}
+          title="Same as company owner"
+          description="Reuse the owner's name, email and phone. Uncheck to enter different details."
         />
       )}
       <SimpleGrid cols={2} spacing="md">
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx
new file mode 100644
index 000000000..7c7c05fec
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx
@@ -0,0 +1,132 @@
+import { Alert, SimpleGrid, Stack, Text, TextInput } from "@mantine/core";
+import { AlertTriangle, Info } from "lucide-react";
+import type { UseFormReturn } from "react-hook-form";
+
+import { ControlledPhoneField } from "@/components/PhoneField";
+import type { CompanyIdentityState } from "@/services/verifayda.service";
+
+import type { FormData } from "../schema";
+import SourcedField from "../SourcedField";
+
+export interface OwnerStepProps {
+  form: UseFormReturn<FormData>;
+  identity?: CompanyIdentityState;
+  /** eTrade's registered manager, once a TIN lookup has succeeded. */
+  etradeOwner: { name: string; phone: string } | null;
+  /**
+   * Which of the owner's details neither eTrade nor Fayda supplied, and are
+   * therefore typed here. Computed by CompanyProfileForm, which requires
+   * exactly these in the schema — so every input below is one the customer is
+   * actually asked to fill, and nothing is required that has no input.
+   */
+  gaps: { name: boolean; email: boolean; phone: boolean };
+}
+
+/**
+ * Who the company's owner is — meaning whoever the eTrade licence names as the
+ * business's manager. Not necessarily the legal owner, but the person the
+ * record has to match: the backoffice's check is precisely "is this the person
+ * on the licence".
+ *
+ * Nothing here falls back to the signed-in account. The person doing the
+ * onboarding is often not the person on the licence, and stamping their name,
+ * email and phone onto the owner turned three required fields into a guess
+ * wearing the licence's authority.
+ */
+export default function OwnerStep({
+  form,
+  identity,
+  etradeOwner,
+  gaps,
+}: OwnerStepProps) {
+  const {
+    register,
+    control,
+    formState: { errors },
+  } = form;
+
+  // A verified owner's own claims outrank eTrade's record for display: the
+  // government IdP is the higher-trust source, and the API locks those fields
+  // to it. eTrade still supplies the name and phone when there is no
+  // verification — which is the case for every company represented by a PoA.
+  const ownerVerified = identity?.owner.verified ?? false;
+  const nameValue = identity?.owner.name || etradeOwner?.name || "";
+  const phoneValue = identity?.owner.phone || etradeOwner?.phone || "";
+  const emailValue = identity?.owner.email || "";
+  const nameSource = identity?.owner.name ? "Fayda" : "eTrade";
+  const phoneSource = identity?.owner.phone ? "Fayda" : "eTrade";
+
+  // A Fayda verification that names someone other than the person on the
+  // licence is the one thing this step exists to catch. Advisory here — the two
+  // sources transliterate Amharic names differently, so the reviewer decides —
+  // but the customer should see it now rather than be rejected later.
+  const mismatch = identity?.ownerMatchesEtrade === false;
+
+  return (
+    <Stack gap="md">
+      <Text size="sm" c="edr-muted">
+        These are the details of the person registered on your eTrade licence.
+        We fill in whatever eTrade and Fayda gave us; anything they left blank
+        we need from you.
+      </Text>
+
+      {!etradeOwner && !ownerVerified && (
+        <Alert color="blue" variant="light" icon={<Info size={18} />}>
+          Your eTrade licence didn't list a manager, so there's nothing for us
+          to prefill. Enter the details of the person registered on it.
+        </Alert>
+      )}
+
+      {mismatch && (
+        <Alert
+          color="amber"
+          variant="light"
+          icon={<AlertTriangle size={18} />}
+          title="This doesn't match your eTrade licence"
+        >
+          Your licence lists{" "}
+          <strong>{identity?.etradeManagerName}</strong>, but the name here is{" "}
+          <strong>{nameValue}</strong>. You can continue, but our team will
+          check this before approving your account — so make sure it's the
+          person the licence actually names.
+        </Alert>
+      )}
+
+      <SourcedField label="Owner's Name" value={nameValue} source={nameSource}>
+        <TextInput
+          label="Owner's Name"
+          placeholder="Abebe Bikila"
+          error={errors.ownerName?.message}
+          {...register("ownerName")}
+        />
+      </SourcedField>
+
+      <SimpleGrid cols={{ base: 1, sm: gaps.email && gaps.phone ? 2 : 1 }} spacing="md">
+        {/* eTrade never returns an email for the manager and Fayda's email
+            claim is optional, so this is the field most companies actually
+            type — it is required either way (`REQUIRED_COMPANY_INFO`). */}
+        <SourcedField label="Owner's Email" value={emailValue} source="Fayda">
+          <TextInput
+            label="Owner's Email"
+            type="email"
+            placeholder="owner@company.com"
+            error={errors.ownerEmail?.message}
+            {...register("ownerEmail")}
+          />
+        </SourcedField>
+
+        <SourcedField
+          label="Owner's Phone"
+          value={phoneValue}
+          source={phoneSource}
+        >
+          <ControlledPhoneField
+            control={control}
+            name="ownerPhone"
+            label="Owner's Phone"
+          />
+        </SourcedField>
+      </SimpleGrid>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/PersonnelStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/PersonnelStep.tsx
deleted file mode 100644
index d3324e0a7..000000000
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/PersonnelStep.tsx
+++ /dev/null
@@ -1,150 +0,0 @@
-import { SimpleGrid, Text, TextInput } from "@mantine/core";
-import type { UseFormReturn } from "react-hook-form";
-
-import { ControlledPhoneField } from "@/components/PhoneField";
-import FaydaVerifyPanel from "@/components/FaydaVerifyPanel";
-import type { CompanyIdentityState } from "@/services/verifayda.service";
-
-import type { FormData } from "../schema";
-import { LinkCheckboxCard } from "../LinkCheckboxCard";
-
-export interface PersonnelStepProps {
-  form: UseFormReturn<FormData>;
-  identity?: CompanyIdentityState;
-  /** eTrade-registered owner, once a TIN lookup has succeeded. */
-  etradeOwner: { name: string; phone: string } | null;
-  gmSameAsOwner: boolean;
-  onToggleGmSameAsOwner: (checked: boolean) => void;
-  /** A server-side "same as owner" declaration is in flight. */
-  gmLinkPending: boolean;
-  gmVerified: boolean;
-  /**
-   * Which of the manager's contact details their Fayda verification did not
-   * supply, and are therefore typed here. Computed by CompanyProfileForm, which
-   * requires exactly these in the schema.
-   */
-  gaps: { name: boolean; email: boolean; phone: boolean };
-}
-
-export default function PersonnelStep({
-  form,
-  identity,
-  etradeOwner,
-  gmSameAsOwner,
-  onToggleGmSameAsOwner,
-  gmLinkPending,
-  gmVerified,
-  gaps,
-}: PersonnelStepProps) {
-  const {
-    register,
-    control,
-    formState: { errors },
-  } = form;
-
-  return (
-    <>
-      <Text fw={600} size="sm" c="edr-text">
-        General Manager
-      </Text>
-      {/* The GM is very often the owner. Where the owner is
-          Fayda-verified this reuses that proven identity outright
-          rather than making the same human verify twice; where the
-          owner is backed by a typed passport there is nothing proven
-          to copy, so it stays a local prefill. */}
-      <LinkCheckboxCard
-        checked={gmSameAsOwner}
-        onToggle={onToggleGmSameAsOwner}
-        title={
-          identity?.owner.verified
-            ? "Same as verified owner"
-            : "Same as business owner"
-        }
-        description={
-          identity?.owner.verified
-            ? "Reuse the Fayda-verified owner's identity for the general manager. Uncheck to verify a different person."
-            : etradeOwner
-              ? "Reuse the eTrade-registered owner's name, plus the company email and phone as you entered them. Uncheck to enter different details."
-              : "Reuse your account's name and the company email and phone as you entered them. Uncheck to enter different details."
-        }
-      />
-
-      {/* Verifying a second person is only meaningful when the GM is
-          someone other than the owner. */}
-      {!gmSameAsOwner && identity && (
-        <FaydaVerifyPanel
-          subject="gm"
-          title="General Manager"
-          state={identity.gm}
-          required={identity.faydaRequired}
-          disabled={gmLinkPending}
-        />
-      )}
-
-      {/* Fayda's name, email and phone claims are all optional, and the
-          manager's own verification has no account to fall back on the way the
-          owner's does — the person onboarding is not necessarily the manager.
-          Whatever the verification left empty is typed here, and required:
-          without it the submit fails on "Add your general manager name" with no
-          field anywhere to satisfy it. */}
-      {gaps.name && (
-        <TextInput
-          label="Name"
-          placeholder="Abebe Bikila"
-          error={errors.generalManagerName?.message}
-          {...register("generalManagerName")}
-        />
-      )}
-      {(gaps.email || gaps.phone) && (
-        <SimpleGrid cols={gaps.email && gaps.phone ? 2 : 1} spacing="md">
-          {gaps.email && (
-            <TextInput
-              label="Email"
-              type="email"
-              placeholder="gm@company.com"
-              error={errors.generalManagerEmail?.message}
-              {...register("generalManagerEmail")}
-            />
-          )}
-          {gaps.phone && (
-            <ControlledPhoneField
-              control={control}
-              name="generalManagerPhone"
-              label="Phone"
-              required
-            />
-          )}
-        </SimpleGrid>
-      )}
-
-      {/* Typed details survive only where Fayda cannot be required —
-          a foreign company's manager may hold no Fayda ID. Once
-          verified the API owns these fields, so they go away. */}
-      {!gmSameAsOwner && !gmVerified && !identity?.faydaRequired && (
-        <>
-          <TextInput
-            label="Name"
-            placeholder="Abebe Bikila"
-            error={errors.generalManagerName?.message}
-            {...register("generalManagerName")}
-          />
-          <SimpleGrid cols={2} spacing="md">
-            <TextInput
-              label="Email"
-              type="email"
-              placeholder="gm@company.com"
-              error={errors.generalManagerEmail?.message}
-              {...register("generalManagerEmail")}
-            />
-            <ControlledPhoneField
-              control={control}
-              name="generalManagerPhone"
-              label="Phone"
-              required
-            />
-          </SimpleGrid>
-        </>
-      )}
-    </>
-  );
-}
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/PoaStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/PoaStep.tsx
deleted file mode 100644
index efece363b..000000000
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/PoaStep.tsx
+++ /dev/null
@@ -1,217 +0,0 @@
-import { Button, Divider, Group, SimpleGrid, Text, TextInput } from "@mantine/core";
-import { Trash2 } from "lucide-react";
-import type { UseFormReturn } from "react-hook-form";
-
-import { SmartFileInput } from "@edr/ui-common";
-import { ControlledPhoneField } from "@/components/PhoneField";
-import FaydaVerifyPanel from "@/components/FaydaVerifyPanel";
-import type { FileUploadSetting } from "@/types/fileUploadSettings";
-import type { CompanyIdentityState } from "@/services/verifayda.service";
-
-import type { FormData } from "../schema";
-import { LinkCheckboxCard } from "../LinkCheckboxCard";
-
-export interface PoaStepProps {
-  form: UseFormReturn<FormData>;
-  identity?: CompanyIdentityState;
-  /** This company holds a freight-forwarder profile, so the PoA is mandatory. */
-  requirePoa: boolean;
-  /** The owner represents the company themselves. */
-  poaSameAsOwner: boolean;
-  onTogglePoaSameAsOwner: (checked: boolean) => void;
-  /** A server-side "same as owner" declaration is in flight. */
-  poaLinkPending: boolean;
-  /** eTrade-registered owner, once a TIN lookup has succeeded. */
-  etradeOwner: { name: string; phone: string } | null;
-  /**
-   * Which of the representative's details the Fayda verification did not
-   * supply, and are therefore typed here. Computed by CompanyProfileForm, which
-   * requires exactly these in the schema — so every input rendered below is one
-   * the customer is actually asked to fill.
-   */
-  gaps: { name: boolean; email: boolean; phone: boolean; address: boolean };
-  /** Drop a verified representative the company decided against. */
-  onRemovePoa: () => void;
-  removePending: boolean;
-  /** The DARS delegation paper is owed (a PoA exists, or the company forwards). */
-  delegationRequired: boolean;
-  /** Single-field upload setting carrying just the delegation letter. */
-  poaDocumentSetting?: FileUploadSetting;
-  documentFiles: Record<string, File | File[] | null>;
-  uploadedDocumentKeys?: string[];
-  documentFieldErrors: Record<string, string>;
-  onDocumentFilesChange: (next: Record<string, File | File[] | null>) => void;
-}
-
-export default function PoaStep({
-  form,
-  identity,
-  requirePoa,
-  poaSameAsOwner,
-  onTogglePoaSameAsOwner,
-  poaLinkPending,
-  etradeOwner,
-  gaps,
-  onRemovePoa,
-  removePending,
-  delegationRequired,
-  poaDocumentSetting,
-  documentFiles,
-  uploadedDocumentKeys,
-  documentFieldErrors,
-  onDocumentFilesChange,
-}: PoaStepProps) {
-  const {
-    register,
-    control,
-    formState: { errors },
-  } = form;
-
-  // Fayda's email/phone/address claims are optional and routinely come back
-  // empty, so a *verified* representative can still be missing the email and
-  // phone the API demands from a freight forwarder (`REQUIRED_POA_FIELDS`) —
-  // and the panel above renders no input for them, which dead-ends the step on
-  // "Add the poa email first". `gaps` is exactly what the verification did not
-  // supply: the API keeps those keys typeable, since a claim that returned
-  // nothing owns no value to protect (`faydaOwnedKeys`).
-  const needsEmail = gaps.email;
-  const needsPhone = gaps.phone;
-
-  // Fayda is mandatory for an Ethiopian company's representative, so there the
-  // link can only reuse a proven owner — with none there would be nothing to
-  // copy and the declaration could never satisfy the gate. A foreign company's
-  // owner is backed by a typed passport, so it prefills instead.
-  const linkNeedsVerifiedOwner =
-    (identity?.faydaRequired ?? false) && !identity?.owner.verified;
-
-  return (
-    <>
-      <Text size="sm" c="edr-muted">
-        {requirePoa
-          ? "As a freight forwarder you act on other companies' behalf, so Power of Attorney details are required."
-          : "Power of Attorney details are optional. Fill them in if you have them, or skip to continue."}{" "}
-        {poaSameAsOwner
-          ? "You represent the company yourself, so no delegation paper is needed."
-          : "If the representative is someone other than the owner, upload the delegation paper authenticated by DARS."}
-      </Text>
-
-      {/* An owner who represents their own company is the ordinary
-          small-business case. Where the owner is Fayda-verified this reuses
-          that proven identity outright rather than sending the same human
-          through Fayda twice; where they are backed by a typed passport there
-          is nothing proven to copy, so it stays a local prefill. Either way it
-          is the declaration that waives the DARS paper. */}
-      {identity && (
-        <LinkCheckboxCard
-          checked={poaSameAsOwner}
-          onToggle={onTogglePoaSameAsOwner}
-          disabled={poaLinkPending || (linkNeedsVerifiedOwner && !poaSameAsOwner)}
-          title={
-            identity.owner.verified
-              ? "Same as verified owner"
-              : "Same as business owner"
-          }
-          description={
-            linkNeedsVerifiedOwner
-              ? "Verify the company owner with Fayda first — then you can reuse that identity here."
-              : identity.owner.verified
-                ? "You represent the company yourself. Reuses the Fayda-verified owner's identity, and no DARS delegation paper is needed. Uncheck to name someone else."
-                : etradeOwner
-                  ? "You represent the company yourself. Reuses the eTrade-registered owner's name plus the company email and phone as you entered them, and no DARS delegation paper is needed. Uncheck to name someone else."
-                  : "You represent the company yourself. Reuses your account's name, email and phone, and no DARS delegation paper is needed. Uncheck to name someone else."
-          }
-        />
-      )}
-
-      {/* A representative acts for the company inside Ethiopia
-          whoever owns it, so the PoA is proven with Fayda regardless of
-          nationality — their name, email, phone and address all come
-          from the verification and are never typed here. Verifying a second
-          person is only meaningful when the representative is not the owner. */}
-      {identity && !poaSameAsOwner && (
-        <FaydaVerifyPanel
-          subject="poa"
-          title="Power of Attorney"
-          state={identity.poa}
-          required={requirePoa}
-          disabled={poaLinkPending}
-        />
-      )}
-      {/* A verification cannot be undone by clearing the form — it owns those
-          fields — and its mere existence makes the delegation paper due, which
-          then blocks the submit. So an optional representative needs a way
-          back out, here rather than only in settings (unreachable until
-          onboarding finishes). */}
-      {identity?.poa.verified && !requirePoa && !poaSameAsOwner && (
-        <Group justify="flex-end">
-          <Button
-            type="button"
-            variant="subtle"
-            color="red"
-            size="xs"
-            loading={removePending}
-            leftSection={<Trash2 size={14} />}
-            onClick={onRemovePoa}
-          >
-            Remove this representative
-          </Button>
-        </Group>
-      )}
-      {/* Whatever the Fayda claim did carry is shown on the panel above and
-          is never typed here — the verification owns it. */}
-      {gaps.name && (
-        <TextInput
-          label="Representative's Name"
-          placeholder="Abebe Bikila"
-          error={errors.poaName?.message}
-          {...register("poaName")}
-        />
-      )}
-      {(needsEmail || needsPhone) && (
-        <SimpleGrid cols={needsEmail && needsPhone ? 2 : 1} spacing="md">
-          {needsEmail && (
-            <TextInput
-              label="Representative's Email"
-              type="email"
-              placeholder="poa@company.com"
-              error={errors.poaEmail?.message}
-              {...register("poaEmail")}
-            />
-          )}
-          {needsPhone && (
-            <ControlledPhoneField
-              control={control}
-              name="poaPhone"
-              label="Representative's Phone"
-            />
-          )}
-        </SimpleGrid>
-      )}
-      {gaps.address && (
-        <TextInput
-          label="PoA Location"
-          placeholder="City, Country"
-          error={errors.poaLocation?.message}
-          {...register("poaLocation")}
-        />
-      )}
-
-      {/* The paper authorises the representative, so it shows once one
-          exists — or straight away for a freight forwarder, who owes it
-          either way and must not be failed on submit for a file the
-          step never offered. */}
-      {delegationRequired && poaDocumentSetting && (
-        <>
-          <Divider my="sm" />
-          <SmartFileInput
-            file={poaDocumentSetting}
-            value={documentFiles}
-            uploadedKeys={uploadedDocumentKeys}
-            errors={documentFieldErrors}
-            onChange={onDocumentFilesChange}
-          />
-        </>
-      )}
-    </>
-  );
-}
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx
new file mode 100644
index 000000000..52fd8c56d
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx
@@ -0,0 +1,273 @@
+import {
+  Alert,
+  Divider,
+  Group,
+  Loader,
+  SimpleGrid,
+  Stack,
+  Text,
+  TextInput,
+} from "@mantine/core";
+import { Info, UserCheck, UserX } from "lucide-react";
+import type { UseFormReturn } from "react-hook-form";
+
+import { SmartFileInput } from "@edr/ui-common";
+import { ControlledPhoneField } from "@/components/PhoneField";
+import FaydaVerifyPanel from "@/components/FaydaVerifyPanel";
+import RoleCard from "@/pages/settings/RoleCard";
+import type { FileUploadSetting } from "@/types/fileUploadSettings";
+import type {
+  CompanyIdentityState,
+  PoaDeclaration,
+} from "@/services/verifayda.service";
+
+import type { FormData } from "../schema";
+import SourcedField from "../SourcedField";
+
+export interface RepresentationStepProps {
+  form: UseFormReturn<FormData>;
+  identity?: CompanyIdentityState;
+  /** Answer the power-of-attorney question (persisted server-side). */
+  onDeclare: (declared: PoaDeclaration) => void;
+  /** A declaration change is in flight. */
+  declarePending: boolean;
+  /**
+   * Which of the representative's details the Fayda verification did not
+   * supply. Same contract as OwnerStep's `gaps`: an input is rendered for
+   * exactly these, and the schema requires exactly these.
+   */
+  gaps: { name: boolean; email: boolean; phone: boolean; address: boolean };
+  /** Single-field upload setting carrying just the DARS delegation letter. */
+  poaDocumentSetting?: FileUploadSetting;
+  documentFiles: Record<string, File | File[] | null>;
+  uploadedDocumentKeys?: string[];
+  documentFieldErrors: Record<string, string>;
+  onDocumentFilesChange: (next: Record<string, File | File[] | null>) => void;
+}
+
+/**
+ * Who acts for this company — and, as a direct consequence, whose identity gets
+ * verified.
+ *
+ * A company proves itself through exactly one person. This step asks which:
+ * name a Power of Attorney and it is the representative who verifies (plus the
+ * DARS paper evidencing the delegation); say there is none and the owner
+ * verifies here instead. There is no third answer — "the owner represents the
+ * company themselves" IS "no".
+ *
+ * A freight forwarder is never asked. It signs on other companies' behalf, so a
+ * representative and the paper behind them are non-negotiable; the API forces
+ * the answer regardless of what the portal sends.
+ */
+export default function RepresentationStep({
+  form,
+  identity,
+  onDeclare,
+  declarePending,
+  gaps,
+  poaDocumentSetting,
+  documentFiles,
+  uploadedDocumentKeys,
+  documentFieldErrors,
+  onDocumentFilesChange,
+}: RepresentationStepProps) {
+  const {
+    register,
+    control,
+    formState: { errors },
+  } = form;
+
+  if (!identity) {
+    return (
+      <Group justify="center" py="xl">
+        <Loader size="sm" />
+      </Group>
+    );
+  }
+
+  const declared = identity.poaDeclared;
+  const locked = identity.poaDeclared === "yes" && identity.subject === "poa";
+  // Only the API knows whether the lock is the freight-forwarder rule; it
+  // reports the answer as "yes" for them no matter what is stored, so a company
+  // that cannot switch to "no" is one the API will refuse. Rather than
+  // duplicating the role check here, the "no" card simply reports the refusal.
+  const passportAccepted = identity.passportAccepted;
+
+  return (
+    <Stack gap="lg">
+      <Stack gap="xs">
+        <Text fw={600} size="lg" c="edr-text">
+          Does anyone hold power of attorney for this company?
+        </Text>
+        <Text size="sm" c="edr-muted">
+          Your answer decides whose identity we verify — the representative's,
+          or the owner's.
+        </Text>
+      </Stack>
+
+      <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+        <RoleCard
+          label="Yes, we have a representative"
+          description="Someone other than the owner is authorised to act for the company. We'll verify their identity and ask for the DARS delegation paper."
+          icon={<UserCheck size={20} />}
+          selected={declared === "yes"}
+          onClick={
+            declarePending || declared === "yes"
+              ? undefined
+              : () => onDeclare("yes")
+          }
+        />
+        <RoleCard
+          label="No, the owner acts for us"
+          description="Nobody holds power of attorney. We'll verify the owner instead, and no delegation paper is needed."
+          icon={<UserX size={20} />}
+          selected={declared === "no"}
+          onClick={
+            declarePending || declared === "no"
+              ? undefined
+              : () => onDeclare("no")
+          }
+        />
+      </SimpleGrid>
+
+      {locked && (
+        <Alert color="blue" variant="light" icon={<Info size={18} />}>
+          As a freight forwarder you act on other companies' behalf, so a Power
+          of Attorney is required — this can't be set to "no" while you hold the
+          freight forwarder role.
+        </Alert>
+      )}
+
+      {declared === null && (
+        <Text size="sm" c="edr-muted">
+          Pick one to continue.
+        </Text>
+      )}
+
+      {/* ---------------------------------------------------------------- */}
+      {/* No representative → the owner is the one who verifies.            */}
+      {/* ---------------------------------------------------------------- */}
+      {declared === "no" && (
+        <>
+          <Divider />
+          <FaydaVerifyPanel
+            subject="owner"
+            title="Company owner"
+            state={identity.owner}
+            required={!passportAccepted}
+          />
+          {/* Fayda is an Ethiopian national ID, so a foreign company's owner
+              may hold none — a passport number proves them instead. Offered
+              alongside, not after: either one satisfies the gate. */}
+          {passportAccepted && !identity.owner.verified && (
+            <TextInput
+              label="Owner's Passport Number"
+              description="If the owner has no Fayda ID, their passport number proves their identity instead."
+              placeholder="P1234567"
+              error={errors.ownerPassportNumber?.message}
+              {...register("ownerPassportNumber")}
+            />
+          )}
+        </>
+      )}
+
+      {/* ---------------------------------------------------------------- */}
+      {/* A representative → they verify, and the delegation is evidenced.  */}
+      {/* ---------------------------------------------------------------- */}
+      {declared === "yes" && (
+        <>
+          <Divider />
+          <FaydaVerifyPanel
+            subject="poa"
+            title="Power of Attorney"
+            state={identity.poa}
+            required={!passportAccepted}
+          />
+          {passportAccepted && !identity.poa.verified && (
+            <TextInput
+              label="Representative's Passport Number"
+              description="If your representative has no Fayda ID, their passport number proves their identity instead."
+              placeholder="P1234567"
+              error={errors.poaPassportNumber?.message}
+              {...register("poaPassportNumber")}
+            />
+          )}
+
+          {/* Whatever the Fayda claim carried is shown on the panel above and
+              never typed here — the verification owns it. The rest is asked
+              for outright, because the API demands name/email/phone from any
+              declared representative (`REQUIRED_POA_FIELDS`). */}
+          <SourcedField
+            label="Representative's Name"
+            value={gaps.name ? "" : identity.poa.name}
+            source="Fayda"
+          >
+            <TextInput
+              label="Representative's Name"
+              placeholder="Abebe Bikila"
+              error={errors.poaName?.message}
+              {...register("poaName")}
+            />
+          </SourcedField>
+
+          <SimpleGrid
+            cols={{ base: 1, sm: gaps.email && gaps.phone ? 2 : 1 }}
+            spacing="md"
+          >
+            <SourcedField
+              label="Representative's Email"
+              value={gaps.email ? "" : identity.poa.email}
+              source="Fayda"
+            >
+              <TextInput
+                label="Representative's Email"
+                type="email"
+                placeholder="representative@company.com"
+                error={errors.poaEmail?.message}
+                {...register("poaEmail")}
+              />
+            </SourcedField>
+
+            <SourcedField
+              label="Representative's Phone"
+              value={gaps.phone ? "" : identity.poa.phone}
+              source="Fayda"
+            >
+              <ControlledPhoneField
+                control={control}
+                name="poaPhone"
+                label="Representative's Phone"
+              />
+            </SourcedField>
+          </SimpleGrid>
+
+          {gaps.address && (
+            <TextInput
+              label="Representative's Location"
+              placeholder="City, Country"
+              error={errors.poaLocation?.message}
+              {...register("poaLocation")}
+            />
+          )}
+
+          {poaDocumentSetting && (
+            <>
+              <Divider my="sm" />
+              <Text size="sm" c="edr-muted">
+                Upload the delegation paper authenticated by DARS. It is what
+                evidences that this person was actually delegated.
+              </Text>
+              <SmartFileInput
+                file={poaDocumentSetting}
+                value={documentFiles}
+                uploadedKeys={uploadedDocumentKeys}
+                errors={documentFieldErrors}
+                onChange={onDocumentFilesChange}
+              />
+            </>
+          )}
+        </>
+      )}
+    </Stack>
+  );
+}
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 b11fecefc..a359a3ff0 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabCompanyProfile.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabCompanyProfile.tsx
@@ -24,14 +24,12 @@ import { useForm } from "react-hook-form";
 import { z } from "zod";
 import type { CompanyRegistrationData } from "@edr/types";
 import OnboardingRoleSelect from "./OnboardingRoleSelect";
-import FaydaVerifyPanel from "@/components/FaydaVerifyPanel";
 import ETradeInfo, {
   type ETradeStatus,
 } from "@/components/onboarding/ETradeInfo";
 import { ReadOnlyField } from "@/pages/accounts/companyProfileForm/ReadOnlyField";
 import StepSection from "@/pages/accounts/companyProfileForm/StepSection";
 import { ETRADE_BUNDLE_FIELDS as SHARED_ETRADE_FIELDS } from "@/pages/accounts/companyProfileForm/schema";
-import { normalizeIdentityPhones } from "@/pages/accounts/companyProfileForm/helpers";
 
 export const COMPANY_PROFILE_SCHEMA = z.object({
   // eTrade-sourced and read-only, like the registration block below.
@@ -149,11 +147,6 @@ export default function TabCompanyProfile({
   // Fayda stores the phone as the national registry holds it (often a local
   // number), which neither this form's E.164 validation nor the API's
   // `@IsValidPhone()` accepts. Normalize on read — same as the wizard.
-  const identity = useMemo(
-    () => normalizeIdentityPhones(profile?.identity),
-    [profile?.identity],
-  );
-  const verifiedIdentity = identity?.faydaRequired === true;
 
   // companyAddress is composed from the (locked) eTrade address parts, not
   // typed directly.
@@ -287,13 +280,6 @@ export default function TabCompanyProfile({
     validationError ??
     (mutation.isError ? extractApiError(mutation.error).message : null);
 
-  const pendingOwnerReview = Boolean(
-    (
-      profile?.pendingChanges as {
-        faydaIdentity?: Record<string, unknown>;
-      } | null
-    )?.faydaIdentity?.ownerFaydaSub,
-  );
 
   // During onboarding the role selection gates the form: nothing else shows
   // until the user picks Importer/Exporter or Freight Forwarder.
@@ -335,51 +321,9 @@ export default function TabCompanyProfile({
                 />
               </StepSection>
 
-              {identity && (
-                <StepSection
-                  index={2}
-                  title="Owner identity"
-                  subtitle={
-                    verifiedIdentity
-                      ? "Re-verify the company owner with Fayda — their name, phone, email and address are refreshed from the verification."
-                      : "The company owner's passport number."
-                  }
-                  status={
-                    verifiedIdentity
-                      ? identity.owner.verified
-                        ? "done"
-                        : identity.faydaRequired
-                          ? "blocked"
-                          : "todo"
-                      : (watch("ownerPassportNumber")?.trim()?.length ?? 0) > 0
-                        ? "done"
-                        : identity.passportRequired
-                          ? "blocked"
-                          : "todo"
-                  }
-                >
-                  <FaydaVerifyPanel
-                    subject="owner"
-                    title="Company owner"
-                    state={identity.owner}
-                    required={identity.faydaRequired}
-                    disabled={mutation.isPending}
-                    pendingReview={pendingOwnerReview}
-                  />
-                  {identity.passportRequired && (
-                    <TextInput
-                      label="Owner Passport Number"
-                      placeholder="P1234567"
-                      description="The owner's identity credential — Fayda is an Ethiopian national ID, so a foreign company's owner is identified by passport instead."
-                      error={errors.ownerPassportNumber?.message}
-                      {...register("ownerPassportNumber")}
-                    />
-                  )}
-                </StepSection>
-              )}
 
               <StepSection
-                index={3}
+                index={2}
                 title="Company TIN"
                 subtitle="Re-verify with eTrade to refresh your registration record — nothing here is typed by hand."
                 status={
diff --git a/apps/edr-freight-web/portal/src/pages/settings/TabGeneralManager.tsx b/apps/edr-freight-web/portal/src/pages/settings/TabGeneralManager.tsx
deleted file mode 100644
index ad680b010..000000000
--- a/apps/edr-freight-web/portal/src/pages/settings/TabGeneralManager.tsx
+++ /dev/null
@@ -1,333 +0,0 @@
-import { useMemo, useState } from "react";
-import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { useForm } from "react-hook-form";
-import { zodResolver } from "@hookform/resolvers/zod";
-import { z } from "zod";
-import { Briefcase, CheckCircle2, Save, XCircle } from "lucide-react";
-import {
-  Alert,
-  Card,
-  Group,
-  Stack,
-  Title,
-  Text,
-  TextInput,
-  Button,
-  Grid,
-} from "@mantine/core";
-import { api } from "@/services/api";
-import { verifaydaService } from "@/services/verifayda.service";
-import { ControlledPhoneField, isValidPhone } from "@/components/PhoneField";
-import { LinkCheckboxCard } from "@/pages/accounts/companyProfileForm/LinkCheckboxCard";
-import FaydaVerifyPanel from "@/components/FaydaVerifyPanel";
-import type { ProfileResponse } from "@/types/profile";
-
-// Optional, not unrequired: an Ethiopian company's GM is established through
-// Fayda and never types these, so a blanket `min(1)` would fail a form that is
-// correct. Presence is gated below, where the identity state says which route
-// applies; zod only polices format for the companies that still type them.
-const schema = z.object({
-  generalManagerName: z.string().optional(),
-  generalManagerEmail: z
-    .string()
-    .optional()
-    .refine(
-      (v) => !v || z.string().email().safeParse(v).success,
-      "Invalid GM email",
-    ),
-  generalManagerPhone: z
-    .string()
-    .optional()
-    .refine((v) => !v || isValidPhone(v), "Enter a valid phone number"),
-});
-
-type FormData = z.infer<typeof schema>;
-
-interface TabGeneralManagerProps {
-  profile: ProfileResponse;
-  mode?: "edit" | "onboarding";
-  onContinue?: () => void;
-}
-
-/**
- * The general manager's identity comes from Fayda: either verified in their
- * own right, or declared to be the owner — very often the same human, which is
- * what "Same as owner" is for. Typed details survive only for a foreign
- * company, whose manager may hold no Fayda ID at all.
- */
-export default function TabGeneralManager({ profile, mode = "edit", onContinue }: TabGeneralManagerProps) {
-  const queryClient = useQueryClient();
-  const owner = profile.identity?.owner;
-  const identity = profile.identity;
-  const gm = identity?.gm;
-  const faydaRequired = identity?.faydaRequired ?? false;
-  const [gmSameAsOwner, setGmSameAsOwner] = useState(
-    identity?.gmSameAsOwner ?? false,
-  );
-
-  const defaultValues = useMemo((): FormData => {
-    return {
-      generalManagerName: profile.generalManagerName ?? "",
-      generalManagerEmail: profile.generalManagerEmail ?? "",
-      generalManagerPhone: profile.generalManagerPhone ?? "",
-    };
-  }, [profile]);
-
-  const {
-    register,
-    control,
-    handleSubmit,
-    reset,
-    setValue,
-    formState: { errors, isDirty },
-  } = useForm<FormData>({
-    resolver: zodResolver(schema),
-    values: defaultValues,
-  });
-
-  /**
-   * With a Fayda-verified owner the declaration is made server-side — the API
-   * copies the proven identity onto the GM — so nothing is typed here. Without
-   * one (a foreign company, whose owner is backed by a passport) there is
-   * nothing proven to copy and this stays a local prefill.
-   */
-  const [linkPending, setLinkPending] = useState(false);
-  const [linkError, setLinkError] = useState<string | null>(null);
-  const toggleGmSameAsOwner = async (checked: boolean) => {
-    setGmSameAsOwner(checked);
-    setLinkError(null);
-    if (!owner?.verified) {
-      if (checked && owner) {
-        setValue("generalManagerName", owner.name ?? "", { shouldValidate: true });
-        setValue("generalManagerEmail", owner.email ?? "", { shouldValidate: true });
-        setValue("generalManagerPhone", owner.phone ?? "", { shouldValidate: true });
-      }
-      return;
-    }
-
-    setLinkPending(true);
-    try {
-      if (checked) await verifaydaService.setGmSameAsOwner();
-      else await verifaydaService.clearGmIdentity();
-      queryClient.invalidateQueries({
-        queryKey: api.companies.getProfile.queryKey(),
-      });
-    } catch (err) {
-      setGmSameAsOwner(!checked);
-      setLinkError(
-        (err as { response?: { data?: { message?: string } } })?.response?.data
-          ?.message ??
-          (err instanceof Error ? err.message : "Could not update the general manager"),
-      );
-    } finally {
-      setLinkPending(false);
-    }
-  };
-
-  const mutation = useMutation({
-    mutationFn: (data: FormData) =>
-      api.companies.updateProfile.call({
-        // `|| undefined`, never "": the DTO's `@IsOptional()` only skips null
-        // and undefined, so an empty string is validated and 400s with
-        // "generalManagerEmail must be an email". A verified manager legitimately
-        // leaves the fields Fayda did supply blank here.
-        generalManagerName: data.generalManagerName || undefined,
-        generalManagerEmail: data.generalManagerEmail || undefined,
-        generalManagerPhone: data.generalManagerPhone || undefined,
-      }),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: api.companies.getProfile.queryKey() });
-      if (mode === "onboarding") onContinue?.();
-    },
-  });
-
-  const onSubmit = (data: FormData) => mutation.mutate(data);
-
-  // Nothing to save when Fayda owns the details: the verification and the
-  // "same as owner" declaration both write server-side, so the form would be
-  // posting empty strings over a proven identity.
-  const typedFieldsInUse = !gmSameAsOwner && !gm?.verified && !faydaRequired;
-
-  // Except for what the verification never supplied. Fayda's name, email and
-  // phone claims are all optional, and a manager verified without them has no
-  // account to fall back on the way the owner does — so those stay typed, here
-  // as well as in onboarding, or a wrong value could never be corrected.
-  const gmGaps = {
-    name: !gmSameAsOwner && Boolean(gm?.verified) && !gm?.name?.trim(),
-    email: !gmSameAsOwner && Boolean(gm?.verified) && !gm?.email?.trim(),
-    phone: !gmSameAsOwner && Boolean(gm?.verified) && !gm?.phone?.trim(),
-  };
-  const savable =
-    typedFieldsInUse || gmGaps.name || gmGaps.email || gmGaps.phone;
-
-  return (
-    <Card padding="lg">
-      <Group gap="sm" mb="xs">
-        <Briefcase size={20} />
-        <Title order={3}>General Manager</Title>
-      </Group>
-      <Text c="edr-muted" size="sm" mb="lg">
-        Manage the general manager information
-      </Text>
-
-      <form onSubmit={handleSubmit(onSubmit)}>
-        <Stack gap="md">
-          <LinkCheckboxCard
-            checked={gmSameAsOwner}
-            onToggle={toggleGmSameAsOwner}
-            title={
-              owner?.verified ? "Same as verified owner" : "Same as business owner"
-            }
-            description={
-              owner?.verified
-                ? "Reuse the Fayda-verified owner's identity for the general manager. Uncheck to verify a different person."
-                : "Reuse the owner's name, email and phone. Uncheck to enter different details."
-            }
-          />
-
-          {linkError && (
-            <Alert color="red" variant="light" icon={<XCircle size={18} />}>
-              {linkError}
-            </Alert>
-          )}
-
-          {/* Verifying a second person only means something when the manager
-              is someone other than the owner. */}
-          {!gmSameAsOwner && gm && (
-            <FaydaVerifyPanel
-              subject="gm"
-              title="General Manager"
-              state={gm}
-              required={faydaRequired}
-              disabled={linkPending || mutation.isPending}
-            />
-          )}
-
-          {/* Whatever the verification did not supply is typed instead — the
-              API keeps exactly those keys writable. */}
-          {gmGaps.name && (
-            <TextInput
-              label="Full Name"
-              placeholder="Abebe Bikila"
-              error={errors.generalManagerName?.message}
-              {...register("generalManagerName")}
-            />
-          )}
-          {(gmGaps.email || gmGaps.phone) && (
-            <Grid>
-              {gmGaps.email && (
-                <Grid.Col span={gmGaps.phone ? 6 : 12}>
-                  <TextInput
-                    label="Email Address"
-                    type="email"
-                    placeholder="gm@company.com"
-                    error={errors.generalManagerEmail?.message}
-                    {...register("generalManagerEmail")}
-                  />
-                </Grid.Col>
-              )}
-              {gmGaps.phone && (
-                <Grid.Col span={gmGaps.email ? 6 : 12}>
-                  <ControlledPhoneField
-                    control={control}
-                    name="generalManagerPhone"
-                    label="Phone Number"
-                    required
-                  />
-                </Grid.Col>
-              )}
-            </Grid>
-          )}
-
-          {/* Typed details survive only where Fayda cannot be required — a
-              foreign company's manager may hold no Fayda ID. Once verified the
-              API owns these fields and refuses edits, so they go away. */}
-          {!gmSameAsOwner && !gm?.verified && !faydaRequired && (
-            <>
-              <TextInput
-                label="Full Name"
-                placeholder="Abebe Bikila"
-                error={errors.generalManagerName?.message}
-                {...register("generalManagerName")}
-              />
-
-              <Grid>
-                <Grid.Col span={6}>
-                  <TextInput
-                    label="Email Address"
-                    type="email"
-                    placeholder="gm@company.com"
-                    error={errors.generalManagerEmail?.message}
-                    {...register("generalManagerEmail")}
-                  />
-                </Grid.Col>
-                <Grid.Col span={6}>
-                  <ControlledPhoneField
-                    control={control}
-                    name="generalManagerPhone"
-                    label="Phone Number"
-                    required
-                  />
-                </Grid.Col>
-              </Grid>
-            </>
-          )}
-        </Stack>
-
-        <Group
-          justify="space-between"
-          mt="xl"
-          pt="md"
-          style={{ borderTop: "1px solid var(--mantine-color-edr-border-0)" }}
-        >
-          <Group gap="xs">
-            {mutation.isSuccess && (
-              <Group gap={6} c="green">
-                <CheckCircle2 size={16} />
-                <Text size="sm" fw={500}>Saved successfully</Text>
-              </Group>
-            )}
-            {mutation.isError && (
-              <Group gap={6} c="red">
-                <XCircle size={16} />
-                <Text size="sm" fw={500}>Save failed</Text>
-              </Group>
-            )}
-          </Group>
-          <Group gap="md">
-            {mode === "edit" && typedFieldsInUse && (
-              <Button
-                type="button"
-                variant="outline"
-                disabled={mutation.isPending || !isDirty}
-                onClick={() => reset()}
-              >
-                Reset
-              </Button>
-            )}
-            {/* Saving only means something while the details are typed: under
-                Fayda both routes write server-side, so a submit would post
-                empty strings at an identity the API owns and refuses to
-                overwrite. Onboarding still needs a way forward, so the button
-                becomes a plain Continue rather than disappearing. */}
-            {savable ? (
-              <Button
-                type="submit"
-                leftSection={<Save size={16} />}
-                loading={mutation.isPending}
-              >
-                {mode === "onboarding" ? "Continue" : "Save Changes"}
-              </Button>
-            ) : (
-              mode === "onboarding" && (
-                <Button type="button" onClick={() => onContinue?.()}>
-                  Continue
-                </Button>
-              )
-            )}
-          </Group>
-        </Group>
-      </form>
-    </Card>
-  );
-}
diff --git a/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx b/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx
new file mode 100644
index 000000000..2c03aaed3
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx
@@ -0,0 +1,198 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+import { AlertTriangle, Briefcase, Save } from "lucide-react";
+import {
+  Alert,
+  Button,
+  Card,
+  Grid,
+  Group,
+  Stack,
+  Text,
+  TextInput,
+  Title,
+} from "@mantine/core";
+
+import { api } from "@/services/api";
+import { ControlledPhoneField, isValidPhone } from "@/components/PhoneField";
+import FaydaVerifyPanel from "@/components/FaydaVerifyPanel";
+import SourcedField from "@/pages/accounts/companyProfileForm/SourcedField";
+import type { ProfileResponse } from "@/types/profile";
+
+// Optional, not unrequired: whatever a Fayda verification supplied is owned by
+// the API and never typed here, so a blanket `min(1)` would fail a form that is
+// correct. Presence is gated below, where the identity state says which fields
+// are actually on screen; zod only polices format.
+const schema = z.object({
+  ownerName: z.string().optional(),
+  ownerEmail: z
+    .string()
+    .optional()
+    .refine(
+      (v) => !v || z.string().email().safeParse(v).success,
+      "Invalid owner email",
+    ),
+  ownerPhone: z
+    .string()
+    .optional()
+    .refine((v) => !v || isValidPhone(v), "Enter a valid phone number"),
+});
+
+type FormData = z.infer<typeof schema>;
+
+interface TabOwnerProps {
+  profile: ProfileResponse;
+  mode?: "edit" | "onboarding";
+  onContinue?: () => void;
+}
+
+/**
+ * The company's owner — meaning whoever the eTrade licence names as the
+ * business's manager. Not necessarily the legal owner, but the person the
+ * record has to match: the backoffice's check is that comparison.
+ *
+ * Their identity is Fayda-verified only when the company has NO Power of
+ * Attorney; when it names a representative it is the representative who
+ * verifies, and the owner's details are simply recorded (from eTrade, or typed
+ * here). Either way all three are required.
+ */
+export default function TabOwner({
+  profile,
+  mode = "edit",
+  onContinue,
+}: TabOwnerProps) {
+  const queryClient = useQueryClient();
+  const identity = profile.identity;
+  const owner = identity?.owner;
+  // Only the person the declaration points at carries the verification, so the
+  // panel is offered here only when that person is the owner.
+  const ownerIsSubject = identity?.subject === "owner";
+
+  const {
+    register,
+    control,
+    handleSubmit,
+    formState: { errors },
+  } = useForm<FormData>({
+    resolver: zodResolver(schema),
+    defaultValues: {
+      ownerName: profile.ownerName ?? "",
+      ownerEmail: profile.ownerEmail ?? "",
+      ownerPhone: profile.ownerPhone ?? "",
+    },
+  });
+
+  const mutation = useMutation({
+    mutationFn: (data: FormData) =>
+      api.companies.updateProfile.call({
+        // `|| undefined`, never "": the DTO's `@IsOptional()` only skips null
+        // and undefined, so an empty string is validated and 400s with
+        // "ownerEmail must be an email". A verified owner legitimately leaves
+        // the fields Fayda did supply blank here.
+        ownerName: data.ownerName || undefined,
+        ownerEmail: data.ownerEmail || undefined,
+        ownerPhone: data.ownerPhone || undefined,
+      }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: api.companies.getProfile.queryKey(),
+      });
+      if (mode === "onboarding") onContinue?.();
+    },
+  });
+
+  // What the verification did NOT supply. Fayda's email and phone claims are
+  // optional, so a verified owner can still be missing details the API demands
+  // — the API leaves exactly those keys typeable, and so does this form.
+  const gaps = {
+    name: !owner?.name?.trim(),
+    email: !owner?.email?.trim(),
+    phone: !owner?.phone?.trim(),
+  };
+  const savable = gaps.name || gaps.email || gaps.phone;
+
+  return (
+    <Card padding="lg">
+      <Group gap="sm" mb="xs">
+        <Briefcase size={20} />
+        <Title order={3}>Company Owner</Title>
+      </Group>
+      <Text c="edr-muted" size="sm" mb="lg">
+        The person registered on your eTrade licence.
+      </Text>
+
+      <form onSubmit={handleSubmit((data) => mutation.mutate(data))}>
+        <Stack gap="md">
+          {identity?.ownerMatchesEtrade === false && (
+            <Alert
+              color="amber"
+              variant="light"
+              icon={<AlertTriangle size={18} />}
+              title="This doesn't match your eTrade licence"
+            >
+              Your licence lists <strong>{identity.etradeManagerName}</strong>.
+              Our team checks this before approving changes.
+            </Alert>
+          )}
+
+          {ownerIsSubject && owner && (
+            <FaydaVerifyPanel
+              subject="owner"
+              title="Owner identity"
+              state={owner}
+              required={!identity?.passportAccepted}
+              pendingReview={profile.reviewStatus === "pending"}
+            />
+          )}
+
+          <SourcedField label="Name" value={owner?.name} source="Fayda">
+            <TextInput
+              label="Name"
+              placeholder="Abebe Bikila"
+              error={errors.ownerName?.message}
+              {...register("ownerName")}
+            />
+          </SourcedField>
+
+          <Grid>
+            <Grid.Col span={{ base: 12, sm: 6 }}>
+              <SourcedField label="Email" value={owner?.email} source="Fayda">
+                <TextInput
+                  label="Email"
+                  type="email"
+                  placeholder="owner@company.com"
+                  error={errors.ownerEmail?.message}
+                  {...register("ownerEmail")}
+                />
+              </SourcedField>
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, sm: 6 }}>
+              <SourcedField label="Phone" value={owner?.phone} source="Fayda">
+                <ControlledPhoneField
+                  control={control}
+                  name="ownerPhone"
+                  label="Phone"
+                />
+              </SourcedField>
+            </Grid.Col>
+          </Grid>
+
+          {savable && (
+            <Group justify="flex-end">
+              <Button
+                type="submit"
+                color="edr-green"
+                loading={mutation.isPending}
+                leftSection={<Save size={16} />}
+              >
+                {mode === "onboarding" ? "Save & continue" : "Save changes"}
+              </Button>
+            </Group>
+          )}
+        </Stack>
+      </form>
+    </Card>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/settings/TabPowerOfAttorney.tsx b/apps/edr-freight-web/portal/src/pages/settings/TabPowerOfAttorney.tsx
index 40f118580..a3118ad28 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabPowerOfAttorney.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabPowerOfAttorney.tsx
@@ -13,6 +13,7 @@ import {
   Undo2,
   UploadCloud,
   UserCheck,
+  UserX,
   XCircle,
 } from "lucide-react";
 import {
@@ -24,6 +25,7 @@ import {
   Card,
   Group,
   Loader,
+  SimpleGrid,
   Stack,
   Title,
   Text,
@@ -41,7 +43,7 @@ import {
 } from "@/services/companies.service";
 import FaydaVerifyPanel from "@/components/FaydaVerifyPanel";
 import { verifaydaService } from "@/services/verifayda.service";
-import { LinkCheckboxCard } from "@/pages/accounts/companyProfileForm/LinkCheckboxCard";
+import RoleCard from "@/pages/settings/RoleCard";
 import type { ProfileResponse } from "@/types/profile";
 
 // The representative's name, email, phone and address all come from their
@@ -136,21 +138,17 @@ export default function TabPowerOfAttorney({
   // company inside Ethiopia either way. A PoA therefore exists exactly when one
   // has been verified.
   const identity = profile.identity;
-  const owner = identity?.owner;
   const poaProvided = identity?.poa.verified ?? false;
-  const [poaSameAsOwner, setPoaSameAsOwner] = useState(
-    identity?.poaSameAsOwner ?? false,
-  );
-  // The paper authorises the representative named above, so there is nothing
-  // for it to authorise until one has been verified — the upload is hidden
-  // until then, and requiring it while hidden would block the save on a
-  // control the customer cannot see. A freight forwarder is still held to
-  // having a PoA at all, by the verification gate on the panel and by the API.
-  //
-  // And nobody delegates to themselves: an owner representing their own company
-  // has no delegation to evidence, which is the same waiver the API applies in
-  // `assertPoaDelegationSatisfied`.
-  const letterRequired = poaProvided && !poaSameAsOwner;
+  // Whether there is a representative at all is the company's own declaration,
+  // held server-side — it decides whose identity the API gates on, so it is
+  // never local state here.
+  const declared = identity?.poaDeclared ?? null;
+  // The paper is owed exactly when the company says it has a representative —
+  // the same single rule `assertPoaDelegationSatisfied` enforces. Keying it on
+  // the verification instead would hide the upload from a foreign company whose
+  // representative proves themselves by passport, then fail the save for a file
+  // that was never offered.
+  const letterRequired = declared === "yes";
   const letterMissing = letterRequired && !hasLetterAfterSave;
 
   const fileDirty = Boolean(pickedFile) || removeIds.length > 0;
@@ -191,11 +189,12 @@ export default function TabPowerOfAttorney({
 
   /**
    * A verified representative cannot be removed by blanking the form — their
-   * fields are owned by the verification — so removal is its own action that
-   * clears the identity and the delegation paper together.
+   * fields are owned by the verification — so removal is answering the
+   * declaration "no", which clears the identity, the details and the
+   * delegation paper together. Refused by the API for a freight forwarder.
    */
   const removeMutation = useMutation({
-    mutationFn: () => verifaydaService.removePoa(),
+    mutationFn: () => verifaydaService.setPoaDeclared("no"),
     onSuccess: () => {
       resetAll();
       queryClient.invalidateQueries({
@@ -208,25 +207,20 @@ export default function TabPowerOfAttorney({
   });
 
   /**
-   * "Same as owner": the owner represents the company themselves. Always goes
-   * to the API, whichever credential backs the owner — the declaration is what
-   * waives the DARS paper, so it has to be recorded server-side even when there
-   * is no proven identity to copy.
+   * Answer the power-of-attorney question.
    *
-   * Unchecking undoes the declaration only. It leaves the paper on file and is
-   * allowed for a freight forwarder, which is how one changes who represents
-   * it; "Remove representative" below is the harder action that takes the paper
-   * with it and is refused to a forwarder.
+   * "No" means the owner acts for the company themselves — there is no
+   * delegation, so no DARS paper is owed and it is the OWNER whose identity is
+   * verified. The API tears the representative down when this is answered, and
+   * refuses "no" outright for a freight forwarder.
    */
   const [linkPending, setLinkPending] = useState(false);
   const [linkError, setLinkError] = useState<string | null>(null);
-  const togglePoaSameAsOwner = async (checked: boolean) => {
-    setPoaSameAsOwner(checked);
+  const declare = async (next: "yes" | "no") => {
     setLinkError(null);
     setLinkPending(true);
     try {
-      if (checked) await verifaydaService.setPoaSameAsOwner();
-      else await verifaydaService.clearPoaSameAsOwner();
+      await verifaydaService.setPoaDeclared(next);
       queryClient.invalidateQueries({
         queryKey: api.companies.getProfile.queryKey(),
       });
@@ -234,7 +228,6 @@ export default function TabPowerOfAttorney({
         queryKey: api.companies.poaDelegation.queryKey(),
       });
     } catch (err) {
-      setPoaSameAsOwner(!checked);
       setLinkError(
         (err as { response?: { data?: { message?: string } } })?.response?.data
           ?.message ??
@@ -297,10 +290,10 @@ export default function TabPowerOfAttorney({
         <Text c="edr-muted" size="sm" mb="lg">
           {requirePoa
             ? "As a freight forwarder you act on other companies' behalf, so a Power of Attorney is required."
-            : "Power of Attorney details are optional."}{" "}
-          {poaSameAsOwner
-            ? "You represent the company yourself, so no delegation paper is needed."
-            : "If you name a representative, upload the DARS delegation paper authorising them."}
+            : "Tell us whether anyone is authorised to act for the company — your answer decides whose identity we verify."}{" "}
+          {declared === "no"
+            ? "The owner acts for the company, so no delegation paper is needed."
+            : "A representative must be identified, and the DARS delegation paper authorising them uploaded."}
         </Text>
 
         {/* The owner representing their own company is the ordinary
@@ -309,30 +302,35 @@ export default function TabPowerOfAttorney({
             mandatory it needs a verified owner first — there would be nothing
             proven to copy, and a representative who could never satisfy the
             gate. */}
+        {/* The declaration itself. "No" is not a lesser answer — it means the
+            owner acts for the company, so it is the OWNER who verifies and no
+            delegation paper is owed. A freight forwarder cannot choose it; the
+            API refuses and the error lands in `linkError`. */}
         {identity && (
-          <LinkCheckboxCard
-            checked={poaSameAsOwner}
-            onToggle={togglePoaSameAsOwner}
-            disabled={
-              linkPending ||
-              mutation.isPending ||
-              (!poaSameAsOwner &&
-                (identity.faydaRequired ?? false) &&
-                !owner?.verified)
-            }
-            title={
-              owner?.verified
-                ? "Same as verified owner"
-                : "Same as business owner"
-            }
-            description={
-              (identity.faydaRequired ?? false) && !owner?.verified
-                ? "Verify the company owner with Fayda first — then you can reuse that identity here."
-                : owner?.verified
-                  ? "You represent the company yourself. Reuses the Fayda-verified owner's identity, and no DARS delegation paper is needed. Uncheck to name someone else."
-                  : "You represent the company yourself. Reuses the owner's name, email and phone, and no DARS delegation paper is needed. Uncheck to name someone else."
-            }
-          />
+          <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md" mb="md">
+            <RoleCard
+              label="Yes, we have a representative"
+              description="Someone other than the owner is authorised to act for the company. Their identity is verified and the DARS delegation paper is required."
+              icon={<UserCheck size={20} />}
+              selected={declared === "yes"}
+              onClick={
+                linkPending || declared === "yes"
+                  ? undefined
+                  : () => void declare("yes")
+              }
+            />
+            <RoleCard
+              label="No, the owner acts for us"
+              description="Nobody holds power of attorney. The owner's identity is verified instead, and no delegation paper is needed."
+              icon={<UserX size={20} />}
+              selected={declared === "no"}
+              onClick={
+                linkPending || declared === "no"
+                  ? undefined
+                  : () => void declare("no")
+              }
+            />
+          </SimpleGrid>
         )}
 
         {linkError && (
@@ -343,12 +341,12 @@ export default function TabPowerOfAttorney({
 
         {/* Verifying a second person only means something when the
             representative is someone other than the owner. */}
-        {identity && !poaSameAsOwner && (
+        {identity && declared === "yes" && (
           <FaydaVerifyPanel
             subject="poa"
             title="Power of Attorney"
             state={identity.poa}
-            required={requirePoa}
+            required={!identity.passportAccepted}
             disabled={mutation.isPending || linkPending}
           />
         )}
@@ -359,7 +357,7 @@ export default function TabPowerOfAttorney({
                 verification and are shown on the panel above. Only a company
                 whose representative may hold no Fayda ID still types a
                 location. */}
-            {!poaProvided && !(identity?.faydaRequired ?? false) && (
+            {declared === "yes" && !poaProvided && (
               <Grid>
                 <Grid.Col span={6}>
                   <TextInput
@@ -376,7 +374,7 @@ export default function TabPowerOfAttorney({
           {/* ------------------------ Delegation letter ------------------------ */}
           {/* The paper authorises the representative the verification named,
               so it only has meaning once one exists. */}
-          {poaProvided && !poaSameAsOwner && (
+          {declared === "yes" && (
           <Stack gap="sm" mt="xl">
             <Group justify="space-between" align="center">
               <Group gap="sm">
@@ -418,7 +416,7 @@ export default function TabPowerOfAttorney({
               >
                 {requirePoa
                   ? "Upload the DARS delegation paper before saving — it is required for freight forwarders."
-                  : "Upload the DARS delegation paper for the representative you named, or clear the PoA details."}
+                  : "Upload the DARS delegation paper for the representative you named, or answer \u201cthe owner acts for us\u201d instead."}
               </Alert>
             )}
 
@@ -551,12 +549,12 @@ export default function TabPowerOfAttorney({
               )}
             </Group>
             <Group gap="md">
-              {/* Not offered against a "same as owner" declaration: unchecking
-                  the card above is the way out of that one, and it leaves the
-                  paper alone. */}
+              {/* Answering "the owner acts for us" is the same teardown, so
+                  this is only a shortcut — and it is refused to a forwarder,
+                  which cannot be without a representative. */}
               {mode === "edit" &&
                 identity?.poa.verified &&
-                !poaSameAsOwner &&
+                declared === "yes" &&
                 !requirePoa && (
                   <Button
                     type="button"
diff --git a/apps/edr-freight-web/portal/src/services/companies.service.ts b/apps/edr-freight-web/portal/src/services/companies.service.ts
index d6a78f1af..55eb52c9a 100644
--- a/apps/edr-freight-web/portal/src/services/companies.service.ts
+++ b/apps/edr-freight-web/portal/src/services/companies.service.ts
@@ -158,14 +158,17 @@ export interface OnboardingLicenseProfile {
   uploaded: boolean;
 }
 
-/** Power of Attorney state — mandatory for freight forwarders, optional otherwise. */
+/** Power of Attorney state, driven by the company's own declaration. */
 export interface OnboardingPoaState {
-  required: boolean;
-  provided: boolean;
   /**
-   * True when the DARS delegation paper is owed. False when the owner
-   * represents the company themselves — nobody delegates to themselves.
+   * True for a freight forwarder: it signs on other companies' behalf, so a
+   * representative is non-negotiable and the question is shown answered rather
+   * than asked.
    */
+  locked: boolean;
+  /** The company's answer. Null until it answers — itself an outstanding item. */
+  declared: "yes" | "no" | null;
+  /** True when the DARS delegation paper is owed — i.e. `declared === "yes"`. */
   delegationLetterRequired: boolean;
   delegationLetterUploaded: boolean;
   /** True when a reviewer sent the DARS delegation paper back for correction. */
@@ -189,7 +192,7 @@ export interface OnboardingRequirements {
   documents: OnboardingDocumentField[];
   licenseProfiles: OnboardingLicenseProfile[];
   poa: OnboardingPoaState;
-  /** Fayda verification state; `required` is false for a foreign company. */
+  /** The company's single identity verification, and whose it is. */
   identity: CompanyIdentityState;
   progress: { completed: number; total: number };
   isComplete: boolean;
diff --git a/apps/edr-freight-web/portal/src/services/verifayda.service.ts b/apps/edr-freight-web/portal/src/services/verifayda.service.ts
index 7dd96c571..50afaaec6 100644
--- a/apps/edr-freight-web/portal/src/services/verifayda.service.ts
+++ b/apps/edr-freight-web/portal/src/services/verifayda.service.ts
@@ -3,14 +3,21 @@ import { unwrap } from "@/utils/endpoint";
 import type { ApiResponse } from "@/types/apiResponse";
 
 /**
- * Which of the company's people a verification is for. The owner is who the
- * company is proven through; the PoA and GM are personnel it names. The GM is
- * very often the owner — "same as owner" reuses that verification rather than
- * making the same human prove themselves twice.
+ * Which of the company's two people a verification is for.
+ *
+ * The **owner** is whoever the eTrade licence names as the business's manager
+ * — not necessarily the legal owner, but the person the record has to match.
+ * The **PoA** is who the company delegates to act for it.
+ *
+ * Exactly one of them is verified, chosen by the company's own answer to "does
+ * anyone hold power of attorney for you?" — see `poaDeclared`.
  */
-export type IdentitySubject = "owner" | "poa" | "gm";
+export type IdentitySubject = "owner" | "poa";
 
-/** One person's Fayda verification state, as the API reports it. */
+/** Whether the company named a representative. Null until it answers. */
+export type PoaDeclaration = "yes" | "no";
+
+/** One person's identity state, as the API reports it. */
 export interface IdentityVerificationState {
   verified: boolean;
   name: string | null;
@@ -18,43 +25,42 @@ export interface IdentityVerificationState {
   email: string | null;
   address: string | null;
   verifiedAt: string | null;
-}
-
-export interface OwnerIdentityState extends IdentityVerificationState {
   /**
-   * Typed passport number — the foreign-company identity credential.
-   * Independent of Fayda: never written by a verification, and still required
-   * even if the owner also verifies.
+   * Typed passport number — the ALTERNATIVE to Fayda for a foreign company,
+   * never written by a verification. Only asked of whichever person carries
+   * the company's identity, and only when `passportAccepted`.
    */
   passportNumber: string | null;
 }
 
 export interface CompanyIdentityState {
   /**
-   * True when Fayda verification is mandatory — Ethiopian companies only.
-   * Doubles as "may this person be typed instead": Fayda is an Ethiopian
-   * national ID, so a foreign company's GM and PoA are offered the
-   * verification but fall back to typed details when they hold none.
+   * True for a foreign company: a typed passport number proves the identity
+   * just as a Fayda verification does. Fayda is an Ethiopian national ID, so an
+   * Ethiopian company has no alternative to it.
    */
-  faydaRequired: boolean;
-  /** True when the owner's passport number is mandatory — foreign companies only. */
-  passportRequired: boolean;
-  owner: OwnerIdentityState;
+  passportAccepted: boolean;
+  /**
+   * The company's answer to the power-of-attorney question. Null until it
+   * answers — which is itself outstanding, since the answer decides who
+   * verifies. Always "yes" for a freight forwarder, which cannot operate
+   * without a representative and is never asked.
+   */
+  poaDeclared: PoaDeclaration | null;
+  /** Whose verification the company is gated on. Null while undeclared. */
+  subject: IdentitySubject | null;
+  owner: IdentityVerificationState;
   poa: IdentityVerificationState;
+  /** True once `subject` is proven — Fayda-verified, or passport where accepted. */
+  identityProven: boolean;
+  /** The manager named on the eTrade licence, captured at lookup. */
+  etradeManagerName: string | null;
   /**
-   * True when the representative is the owner themselves, declared through
-   * "same as owner". Waives the DARS delegation paper — nobody delegates to
-   * themselves — and, where the owner is Fayda-verified, backs `poa.verified`
-   * with the owner's sub.
+   * Does the owner the company put forward match the eTrade licence? This is
+   * the backoffice's check. Null when there is nothing to compare. Advisory:
+   * eTrade's and Fayda's transliterations rarely agree exactly.
    */
-  poaSameAsOwner: boolean;
-  /**
-   * General manager. `verified` covers both routes: the GM verifying in their
-   * own right, and the company declaring the GM is the owner (in which case
-   * `gmSameAsOwner` is set and the owner's Fayda sub backs it).
-   */
-  gm: IdentityVerificationState;
-  gmSameAsOwner: boolean;
+  ownerMatchesEtrade: boolean | null;
   complete: boolean;
 }
 
@@ -127,65 +133,19 @@ export const verifaydaService = {
   },
 
   /**
-   * Declare the General Manager is the company's owner, reusing the owner's
-   * verified identity rather than making the same human verify twice. The copy
-   * happens server-side from the stored owner identity — the portal never
-   * supplies the values — and is refused until the owner is verified.
-   */
-  setGmSameAsOwner: async (): Promise<CompanyIdentityState> => {
-    const response = await client.post<ApiResponse<CompanyIdentityState>>(
-      "/api/companies/identity/gm/same-as-owner",
-    );
-    return unwrap(response.data);
-  },
-
-  /**
-   * Clear the GM's identity — the "same as owner" declaration or a verification
-   * of their own — leaving them open to be re-established either way.
-   */
-  clearGmIdentity: async (): Promise<CompanyIdentityState> => {
-    const response = await client.delete<ApiResponse<CompanyIdentityState>>(
-      "/api/companies/identity/gm",
-    );
-    return unwrap(response.data);
-  },
-
-  /**
-   * Declare the Power of Attorney is the company's owner. A Fayda-verified
-   * owner's identity is copied server-side (the portal never supplies it); a
-   * foreign company's owner has nothing proven to copy, so the API records the
-   * declaration and the form types the representative's details as usual.
+   * Answer whether anyone holds power of attorney for this company — the
+   * question that decides whose identity is verified.
    *
-   * Either way the declaration is what waives the DARS delegation paper.
+   * Answering "no" tears the representative down server-side: their details,
+   * their verification, their passport number and the DARS delegation paper.
+   * Refused for a freight forwarder, which cannot operate without one.
    */
-  setPoaSameAsOwner: async (): Promise<CompanyIdentityState> => {
-    const response = await client.post<ApiResponse<CompanyIdentityState>>(
-      "/api/companies/identity/poa/same-as-owner",
-    );
-    return unwrap(response.data);
-  },
-
-  /**
-   * Undo that declaration and the identity it copied, leaving the
-   * representative open to be verified in their own right. Unlike
-   * {@link removePoa} this is allowed for a freight forwarder — it is how they
-   * change who represents them — and leaves the delegation paper on file.
-   */
-  clearPoaSameAsOwner: async (): Promise<CompanyIdentityState> => {
-    const response = await client.delete<ApiResponse<CompanyIdentityState>>(
-      "/api/companies/identity/poa/same-as-owner",
-    );
-    return unwrap(response.data);
-  },
-
-  /**
-   * Drop the Power of Attorney — verified identity, details and delegation
-   * paper together. A verified person's fields are locked, so blanking the form
-   * is no longer a way to remove them. Refused for a freight forwarder.
-   */
-  removePoa: async (): Promise<CompanyIdentityState> => {
-    const response = await client.delete<ApiResponse<CompanyIdentityState>>(
-      "/api/companies/identity/fayda/poa",
+  setPoaDeclared: async (
+    declared: PoaDeclaration,
+  ): Promise<CompanyIdentityState> => {
+    const response = await client.patch<ApiResponse<CompanyIdentityState>>(
+      "/api/companies/identity/poa-declared",
+      { declared },
     );
     return unwrap(response.data);
   },
diff --git a/apps/edr-freight-web/portal/src/types/profile.ts b/apps/edr-freight-web/portal/src/types/profile.ts
index 732dd13cf..aa62ed4ca 100644
--- a/apps/edr-freight-web/portal/src/types/profile.ts
+++ b/apps/edr-freight-web/portal/src/types/profile.ts
@@ -30,19 +30,15 @@ export interface ProfileResponse {
   contactPersonPhone: string | null;
   /** Phone that passed SMS OTP verification (resumes the verify step's state). */
   contactVerifiedPhone: string | null;
-  generalManagerName: string | null;
-  generalManagerEmail: string | null;
-  generalManagerPhone: string | null;
+  /** The owner — whoever the eTrade licence names as the business's manager. */
+  ownerName: string | null;
+  ownerEmail: string | null;
+  ownerPhone: string | null;
   /**
-   * Fayda verification state for the owner, the PoA and the general manager.
-   * `identity.faydaRequired` / `identity.passportRequired` is the
-   * Ethiopian/foreign switch: an Ethiopian company verifies all three with
-   * Fayda, while a foreign one proves its owner with a typed passport number
-   * and may type its GM and PoA, whose holders may have no Fayda ID.
-   *
-   * The `generalManager*` fields above are the same person's details written
-   * flat — a verification keeps them in step, since the booking, contract and
-   * train-scheduling notifiers mail `generalManagerEmail` directly.
+   * The company's single identity verification. `identity.subject` says whose
+   * it is (the PoA when one is declared, otherwise the owner);
+   * `identity.passportAccepted` is the Ethiopian/foreign switch — a foreign
+   * company may prove the same person with a typed passport number instead.
    */
   identity: CompanyIdentityState;
   poaName: string | null;
@@ -88,14 +84,18 @@ export interface UpdateProfilePayload {
   contactPersonEmail?: string;
   contactPersonPhone?: string;
   contactVerifiedPhone?: string;
-  generalManagerName?: string;
-  generalManagerEmail?: string;
-  generalManagerPhone?: string;
+  ownerName?: string;
+  ownerEmail?: string;
+  ownerPhone?: string;
   poaName?: string;
   poaPhone?: string;
   poaEmail?: string;
   poaLocation?: string;
   poaAddress?: string;
-  /** The owner's passport number — the foreign-company identity credential. */
+  /**
+   * Passport numbers — the ALTERNATIVE to Fayda for a foreign company. Only the
+   * one belonging to the declared identity subject is ever collected.
+   */
   ownerPassportNumber?: string;
+  poaPassportNumber?: string;
 }

From 02d9debe1daec51d309916668d952b9e8ece5c29 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 11 Aug 2026 11:54:05 +0000
Subject: [PATCH 020/174] refactor(freight-backoffice): review one identity and
 the eTrade owner match

- Replace the general-manager rows with owner rows across the customer
  detail, contract cards, types and service mappings.
- The identity card names its subject ("Verifies for this company") and shows
  whether the asserted owner matches the manager on the eTrade licence:
  amber when it does not, green when it does, dimmed when eTrade named
  nobody. Advisory only, since the comparison is a fuzzy transliteration
  match.
- A missing delegation letter now keys on poaDeclared === "yes".
- Keep the three general-manager labels in the change-request label map so
  historical requests still render readable field names.
---
 .../detail/ContractDetailTabCards.tsx         |  9 +--
 .../customers/ChangeRequestReview.tsx         | 20 +++++--
 .../pages/customers/CustomerDetailPage.tsx    | 58 ++++++++++++++-----
 .../src/services/customers.service.ts         |  8 +--
 .../backoffice/src/types/booking.ts           |  6 +-
 .../backoffice/src/types/customer.ts          | 34 +++++++----
 6 files changed, 92 insertions(+), 43 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/detail/ContractDetailTabCards.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/detail/ContractDetailTabCards.tsx
index de8ff1953..d29e045c4 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/detail/ContractDetailTabCards.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/detail/ContractDetailTabCards.tsx
@@ -170,12 +170,13 @@ export function ContractCustomerCard({
         />
       </SectionCard>
 
-      <SectionCard icon={User} title="General manager" accent="grape">
+      {/* Whoever the eTrade licence names as the business's manager. */}
+      <SectionCard icon={User} title="Owner" accent="grape">
         <InfoRows
           rows={[
-            { icon: User, label: "Name", value: company.generalManagerName },
-            { icon: Mail, label: "Email", value: company.generalManagerEmail },
-            { icon: Phone, label: "Phone", value: company.generalManagerPhone },
+            { icon: User, label: "Name", value: company.ownerName },
+            { icon: Mail, label: "Email", value: company.ownerEmail },
+            { icon: Phone, label: "Phone", value: company.ownerPhone },
           ]}
         />
       </SectionCard>
diff --git a/apps/edr-freight-web/backoffice/src/components/customers/ChangeRequestReview.tsx b/apps/edr-freight-web/backoffice/src/components/customers/ChangeRequestReview.tsx
index d86e0079c..65c4f25e3 100644
--- a/apps/edr-freight-web/backoffice/src/components/customers/ChangeRequestReview.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/customers/ChangeRequestReview.tsx
@@ -43,9 +43,17 @@ export const FIELD_LABELS: Record<string, string> = {
   contactPersonPosition: "Contact position",
   contactPersonEmail: "Contact email",
   contactPersonPhone: "Contact phone",
-  generalManagerName: "General manager",
-  generalManagerEmail: "GM email",
-  generalManagerPhone: "GM phone",
+  ownerName: "Owner name",
+  ownerEmail: "Owner email",
+  ownerPhone: "Owner phone",
+  poaDeclared: "Has a Power of Attorney",
+  poaPassportNumber: "PoA passport number",
+  // Nothing writes these any more — the general manager was removed — but
+  // change requests filed before that still carry them, and without a label
+  // the reviewer sees a raw attribute key.
+  generalManagerName: "General manager (retired)",
+  generalManagerEmail: "GM email (retired)",
+  generalManagerPhone: "GM phone (retired)",
   poaName: "PoA name",
   poaPhone: "PoA phone",
   poaEmail: "PoA email",
@@ -79,9 +87,9 @@ export function currentValue(company: Company, key: string): string {
     nationality: c.nationality,
     contactPersonName: c.contactPersonName ?? attrs.contactPersonName,
     contactPersonPhone: c.contactPersonPhone ?? attrs.contactPersonPhone,
-    generalManagerName: c.generalManagerName ?? attrs.generalManagerName,
-    generalManagerEmail: c.generalManagerEmail ?? attrs.generalManagerEmail,
-    generalManagerPhone: c.generalManagerPhone ?? attrs.generalManagerPhone,
+    ownerName: c.ownerName ?? attrs.ownerName,
+    ownerEmail: c.ownerEmail ?? attrs.ownerEmail,
+    ownerPhone: c.ownerPhone ?? attrs.ownerPhone,
   };
   const v = key in map ? map[key] : (c[key] ?? attrs[key]);
   return v === null || v === undefined || v === "" ? "—" : String(v);
diff --git a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
index f31ce02e9..f197e1952 100644
--- a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
@@ -17,6 +17,7 @@ import {
   Text,
 } from "@mantine/core";
 import {
+  AlertTriangle,
   ArrowLeft,
   ArrowRight,
   Banknote,
@@ -638,8 +639,9 @@ export default function CustomerDetailPage() {
   const hasPoaDetails = poaFields.some((f) => f.value?.trim());
   // Shared with the portal (buildCompanyIdentityState) — same derivation, so
   // this page can never disagree with the rule the API actually enforces.
-  const ownerIdentity = company?.identity?.owner;
-  const poaIdentity = company?.identity?.poa;
+  const identityState = company?.identity;
+  const ownerIdentity = identityState?.owner;
+  const poaIdentity = identityState?.poa;
   const hasEtradeRecord = Boolean(company?.licenceNumber?.trim());
   // A freight forwarder acts on other companies' behalf, so its PoA — details
   // and DARS delegation paper both — is mandatory rather than optional.
@@ -647,7 +649,7 @@ export default function CustomerDetailPage() {
     (p) => p.type === "freight_forwarder",
   );
   const delegationMissing =
-    (hasPoaDetails || poaMandatory) && poaLive.length === 0;
+    company?.identity?.poaDeclared === "yes" && poaLive.length === 0;
 
   if (isLoading) {
     return (
@@ -834,18 +836,9 @@ export default function CustomerDetailPage() {
                     value={company.contactPersonPhone}
                   />
                   <Box />
-                  <InfoField
-                    label="General manager"
-                    value={company.generalManagerName}
-                  />
-                  <InfoField
-                    label="GM email"
-                    value={company.generalManagerEmail}
-                  />
-                  <InfoField
-                    label="GM phone"
-                    value={company.generalManagerPhone}
-                  />
+                  <InfoField label="Owner" value={company.ownerName} />
+                  <InfoField label="Owner email" value={company.ownerEmail} />
+                  <InfoField label="Owner phone" value={company.ownerPhone} />
                 </SimpleGrid>
               </Stack>
             </Card>
@@ -912,6 +905,11 @@ export default function CustomerDetailPage() {
                   <Text fw={600} c="edr-text">
                     Owner identity
                   </Text>
+                  {identityState?.subject === "owner" && (
+                    <Badge size="sm" color="blue" variant="light">
+                      Verifies for this company
+                    </Badge>
+                  )}
                   {ownerIdentity?.verified ? (
                     <Badge size="sm" color="edr-green" variant="light">
                       Fayda verified
@@ -922,6 +920,36 @@ export default function CustomerDetailPage() {
                     </Badge>
                   )}
                 </Group>
+
+                {/* THE check: is the owner the company put forward the person
+                    the eTrade licence actually names? Advisory — eTrade and
+                    Fayda transliterate Amharic names differently, so this is a
+                    prompt to look, not a verdict. */}
+                {identityState?.ownerMatchesEtrade === false ? (
+                  <Alert
+                    color="amber"
+                    variant="light"
+                    icon={<AlertTriangle size={16} />}
+                    title="Does not match the eTrade licence"
+                  >
+                    The licence names{" "}
+                    <strong>{identityState.etradeManagerName}</strong>, but this
+                    company recorded <strong>{company.ownerName}</strong>.
+                  </Alert>
+                ) : identityState?.ownerMatchesEtrade === true ? (
+                  <Badge
+                    size="sm"
+                    color="edr-green"
+                    variant="light"
+                    style={{ alignSelf: "flex-start" }}
+                  >
+                    Matches the eTrade licence
+                  </Badge>
+                ) : (
+                  <Text size="xs" c="dimmed">
+                    No eTrade manager name on file to compare against.
+                  </Text>
+                )}
                 {ownerIdentity?.verified ? (
                   <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="lg">
                     <InfoField label="Name" value={ownerIdentity.name} />
diff --git a/apps/edr-freight-web/backoffice/src/services/customers.service.ts b/apps/edr-freight-web/backoffice/src/services/customers.service.ts
index eb86dd752..5b3cc4527 100644
--- a/apps/edr-freight-web/backoffice/src/services/customers.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/customers.service.ts
@@ -24,7 +24,7 @@ const cleanParams = (params: object) =>
     ),
   );
 
-/** Lift attributes JSONB into the flat contact/manager fields the UI reads. */
+/** Lift attributes JSONB into the flat contact/owner fields the UI reads. */
 function mapCompany(dto: Record<string, unknown>): Company {
   const attrs = (dto.attributes as Record<string, unknown> | null) ?? {};
   return {
@@ -32,9 +32,9 @@ function mapCompany(dto: Record<string, unknown>): Company {
     companyProfiles: (dto.companyProfiles as Company["companyProfiles"]) ?? [],
     contactPersonName: (attrs.contactPersonName as string | null) ?? null,
     contactPersonPhone: (attrs.contactPersonPhone as string | null) ?? null,
-    generalManagerName: (attrs.generalManagerName as string | null) ?? null,
-    generalManagerEmail: (attrs.generalManagerEmail as string | null) ?? null,
-    generalManagerPhone: (attrs.generalManagerPhone as string | null) ?? null,
+    ownerName: (attrs.ownerName as string | null) ?? null,
+    ownerEmail: (attrs.ownerEmail as string | null) ?? null,
+    ownerPhone: (attrs.ownerPhone as string | null) ?? null,
     poaName: (attrs.poaName as string | null) ?? null,
     poaEmail: (attrs.poaEmail as string | null) ?? null,
     poaPhone: (attrs.poaPhone as string | null) ?? null,
diff --git a/apps/edr-freight-web/backoffice/src/types/booking.ts b/apps/edr-freight-web/backoffice/src/types/booking.ts
index 7ae93a1b7..dd1734ad6 100644
--- a/apps/edr-freight-web/backoffice/src/types/booking.ts
+++ b/apps/edr-freight-web/backoffice/src/types/booking.ts
@@ -64,9 +64,9 @@ export interface BookingCompany {
   email?: string | null;
   contactPersonName?: string | null;
   contactPersonPhone?: string | null;
-  generalManagerName?: string | null;
-  generalManagerEmail?: string | null;
-  generalManagerPhone?: string | null;
+  ownerName?: string | null;
+  ownerEmail?: string | null;
+  ownerPhone?: string | null;
   website?: string | null;
 }
 
diff --git a/apps/edr-freight-web/backoffice/src/types/customer.ts b/apps/edr-freight-web/backoffice/src/types/customer.ts
index cd2d67842..4fd920916 100644
--- a/apps/edr-freight-web/backoffice/src/types/customer.ts
+++ b/apps/edr-freight-web/backoffice/src/types/customer.ts
@@ -179,23 +179,34 @@ export interface IdentityVerificationState {
   verifiedAt: string | null;
   birthdate: string | null;
   gender: string | null;
-}
-
-/** Mirrors `OwnerIdentityStateDto`. */
-export interface OwnerIdentityState extends IdentityVerificationState {
+  /** Typed passport number — the foreign-company alternative to Fayda. */
   passportNumber: string | null;
 }
 
 /**
- * Owner/PoA Fayda verification, shared with the portal's derivation
+ * The company's single identity verification, shared with the portal's derivation
  * (`buildCompanyIdentityState`) so backoffice never re-derives — or
  * disagrees with — the rule the API actually enforces.
  */
 export interface CompanyIdentityState {
-  faydaRequired: boolean;
-  passportRequired: boolean;
-  owner: OwnerIdentityState;
+  /** Foreign company: a passport number proves the person as Fayda would. */
+  passportAccepted: boolean;
+  /** Whether the company named a representative. Null = never answered. */
+  poaDeclared: "yes" | "no" | null;
+  /** Whose verification the company is gated on — PoA if declared, else owner. */
+  subject: "owner" | "poa" | null;
+  owner: IdentityVerificationState;
   poa: IdentityVerificationState;
+  identityProven: boolean;
+  /** The manager named on the eTrade licence, captured at lookup. */
+  etradeManagerName: string | null;
+  /**
+   * Does the owner the company put forward match the eTrade licence?
+   * THE reviewer check. Null when there is nothing to compare. Advisory —
+   * eTrade and Fayda transliterate Amharic names differently, so a `false` is
+   * "look at this", not "reject this".
+   */
+  ownerMatchesEtrade: boolean | null;
   complete: boolean;
 }
 
@@ -216,9 +227,10 @@ export interface Company {
   email?: string | null;
   contactPersonName?: string | null;
   contactPersonPhone?: string | null;
-  generalManagerName?: string | null;
-  generalManagerEmail?: string | null;
-  generalManagerPhone?: string | null;
+  /** The owner — whoever the eTrade licence names as the business's manager. */
+  ownerName?: string | null;
+  ownerEmail?: string | null;
+  ownerPhone?: string | null;
   poaName?: string | null;
   poaEmail?: string | null;
   poaPhone?: string | null;

From 1be72799f4bbf8938b3c4579b4ac663c01665c7b Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Tue, 11 Aug 2026 12:13:34 +0000
Subject: [PATCH 021/174] fix(train-scheduling): exempt direct-to-train export
 bookings from GRN gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

confirmScheduleLoading's assertExportBookingsReceived checked every
wagon-assigned export booking for a warehouse GRN, with no exception for
DIRECT_TO_TRAIN (manual truck-straight-to-wagon) bookings — the one
call site that lacked the carve-out already applied everywhere else GRN
is checked (export-received-gate, booking-journey, carriage acceptance).
Warehouse-routed export cargo still requires GRN; direct handovers rely
on the carriage acceptance sheet instead.
---
 .../train-scheduling/services/train-scheduling.service.ts  | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index 657703ada..1cd900d66 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -3262,6 +3262,12 @@ export class TrainSchedulingService {
    * Every export booking being confirmed loaded must already be received at the
    * warehouse with a GRN. An allocation puts a booking on a wagon on paper; this
    * is the check that the cargo is physically in the yard before we call it loaded.
+   *
+   * Direct truck-to-train (exportHandoverMode = DIRECT_TO_TRAIN) is excluded —
+   * that cargo is manually loaded from the customer's truck straight onto the
+   * wagon, never sees the warehouse, and is never GRN'd. Its custody is attested
+   * by the carriage acceptance sheet instead (same carve-out as the shared
+   * assertExportReceivedWithGrn gate — see common/export-received-gate.ts).
    */
   private async assertExportBookingsReceived(bookingIds: string[]): Promise<void> {
     if (!bookingIds.length) return;
@@ -3270,6 +3276,7 @@ export class TrainSchedulingService {
          FROM freight.bookings b
         WHERE b.id = ANY($1)
           AND b.deleted_at IS NULL
+          AND b.export_handover_mode IS DISTINCT FROM 'DIRECT_TO_TRAIN'
           AND NOT EXISTS (
             SELECT 1 FROM freight.warehouse_inventory inv
              WHERE inv.booking_id = b.id

From 72164b0b8e55851d85867849a60e531f130bf0ff Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 11 Aug 2026 12:54:38 +0000
Subject: [PATCH 022/174] fix(freight-portal): stop owner details vanishing
 between wizard steps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SourcedField rendered read-only whenever a value existed, so the input a
customer had just typed into turned into a badge as soon as the step saved and
they navigated back — and dropped out of requiredKeys at the same time. It now
locks on ownership instead: a Fayda verification owns what its claims filled,
everything else stays an editable, prefilled input.

The representation step follows the same rule and asks in the right order:

- The power-of-attorney question collapses to its answer once given, with a
  button back to it (none for a freight forwarder, whose answer is forced).
- A foreign company picks how to prove the person outright — Fayda or a
  passport — rather than being shown both at once.
- The representative's own fields appear only once the person is established,
  and only for what the verification did not supply; what it did supply is
  already on the panel above and is no longer repeated beneath it.
- Dropped the freight-forwarder lecture and the DARS blurb; the badge and the
  upload field's own help text already say both.

VAT numbers accept any non-blank value. A foreign tax authority's carries
letters and dashes and a co-operative's follows neither pattern, so the 10-11
digit rule only ever rejected numbers we had no business judging.
---
 .../companies/dto/update-profile.dto.ts       |  12 +-
 .../companyProfileForm/SourcedField.tsx       |  34 +-
 .../companyProfileForm/steps/OwnerStep.tsx    |  67 +--
 .../steps/RepresentationStep.tsx              | 442 +++++++++++-------
 .../portal/src/pages/settings/TabOwner.tsx    |  30 +-
 .../src/pages/settings/TabPowerOfAttorney.tsx |   8 +-
 6 files changed, 363 insertions(+), 230 deletions(-)

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 b7b814da1..2273bf79a 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
@@ -5,7 +5,6 @@ import {
   MaxLength,
   IsEnum,
   IsIn,
-  Matches,
 } from "class-validator";
 import { ETHIOPIAN_REGIONS, type EthiopianRegion } from "@edr/types";
 import { CompanyNationality } from "../entities/company.entity";
@@ -36,13 +35,14 @@ export class UpdateProfileDto {
   @IsTin({ message: "TIN must be exactly 10 digits" })
   tin?: string;
 
-  // Ethiopian VAT registration numbers are 10 digits (the same shape as the
-  // TIN), but some are issued with an 11th. Both portal forms enforce the same
-  // range; without it here the API happily stored whatever a stale client sent,
-  // and the two layers disagreed about what the column may hold.
+  // No shape check. Ethiopian VAT numbers are usually 10 or 11 digits, but a
+  // foreign company's is whatever its own tax authority issues — letters,
+  // dashes and any length — and a co-operative's registration numbering does
+  // not follow the trade-licence pattern either. The field is required (the
+  // portal enforces non-blank) but its content is not ours to police.
   @IsOptional()
   @IsString()
-  @Matches(/^\d{10,11}$/, { message: "VAT number must be 10 or 11 digits" })
+  @MaxLength(64)
   vatNumber?: string;
 
   // `fanNumber` is deliberately absent: the FAN is a Fayda number, so it would
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/SourcedField.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/SourcedField.tsx
index 480606db8..3b3601711 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/SourcedField.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/SourcedField.tsx
@@ -1,7 +1,7 @@
 import { Badge, Group, Stack, Text } from "@mantine/core";
 import type { ReactNode } from "react";
 
-/** Where a prefilled value came from, shown as a badge next to it. */
+/** Where a locked value came from, shown as a badge next to it. */
 export type FieldSource = "eTrade" | "Fayda";
 
 const SOURCE_NOTE: Record<FieldSource, string> = {
@@ -10,35 +10,37 @@ const SOURCE_NOTE: Record<FieldSource, string> = {
 };
 
 /**
- * One person-detail field that may already be answered for us.
+ * One person-detail field that a verification may have taken ownership of.
  *
- * The onboarding wizard fills what it can from the eTrade lookup and the Fayda
- * verification, and asks the customer only for what neither supplied. Both
- * sources are patchy in practice — eTrade returns no email at all and often no
- * manager name; Fayda's email and phone claims are optional and routinely come
- * back empty — so "what is missing" varies per company and cannot be decided
- * once at build time.
+ * `locked` — not "does a value exist" — decides which side renders. That
+ * distinction is the whole point: `ownerName` holds a value the moment the
+ * eTrade lookup prefills it or the customer types it and the step saves, and
+ * keying off presence meant the input a customer had just filled in turned into
+ * a read-only badge as soon as they navigated away and back, with no way to
+ * correct it. Only a Fayda verification actually owns a field — the API refuses
+ * to overwrite those — so only those lock.
  *
- * This is the single place that decision is rendered: a supplied value shows
- * read-only with its provenance, a gap shows the input. It pairs with
- * `requiredKeys` in CompanyProfileForm, which requires exactly the fields that
- * fall through to `children` — the invariant being that **a field is required
- * if and only if there is an input on screen to satisfy it**.
+ * It pairs with `requiredKeys` in CompanyProfileForm, which requires exactly
+ * the fields that fall through to `children`: **a field is required if and only
+ * if there is an input on screen to satisfy it.**
  */
 export default function SourcedField({
   label,
   value,
   source,
+  locked,
   children,
 }: {
   label: string;
-  /** The value a source supplied. Blank/absent means "ask the customer". */
+  /** The value to display when locked. */
   value?: string | null;
   source: FieldSource;
-  /** The input rendered when no source supplied a value. */
+  /** A verification owns this field: show it read-only instead of an input. */
+  locked: boolean;
+  /** The input rendered whenever the field is still the customer's to fill. */
   children: ReactNode;
 }) {
-  if (!value?.trim()) return <>{children}</>;
+  if (!locked || !value?.trim()) return <>{children}</>;
 
   return (
     <Stack gap={2}>
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx
index 7c7c05fec..7861f4818 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx
@@ -14,12 +14,15 @@ export interface OwnerStepProps {
   /** eTrade's registered manager, once a TIN lookup has succeeded. */
   etradeOwner: { name: string; phone: string } | null;
   /**
-   * Which of the owner's details neither eTrade nor Fayda supplied, and are
-   * therefore typed here. Computed by CompanyProfileForm, which requires
-   * exactly these in the schema — so every input below is one the customer is
-   * actually asked to fill, and nothing is required that has no input.
+   * Which of the owner's details a Fayda verification owns. A locked field is
+   * shown read-only; every other one is an editable input, prefilled from
+   * eTrade or from what was saved earlier. CompanyProfileForm computes this and
+   * requires exactly the unlocked fields, so every input on screen is one the
+   * customer is actually asked to fill and nothing is required that has none.
    */
-  gaps: { name: boolean; email: boolean; phone: boolean };
+  locked: { name: boolean; email: boolean; phone: boolean };
+  /** A co-operative union or farm: no licence, so no eTrade record to match. */
+  cooperative?: boolean;
 }
 
 /**
@@ -32,12 +35,17 @@ export interface OwnerStepProps {
  * onboarding is often not the person on the licence, and stamping their name,
  * email and phone onto the owner turned three required fields into a guess
  * wearing the licence's authority.
+ *
+ * A co-operative union or farm has no licence, so there is nobody named on one
+ * — the owner is simply the person who runs it, typed in full and compared
+ * against nothing.
  */
 export default function OwnerStep({
   form,
   identity,
   etradeOwner,
-  gaps,
+  locked,
+  cooperative = false,
 }: OwnerStepProps) {
   const {
     register,
@@ -45,16 +53,7 @@ export default function OwnerStep({
     formState: { errors },
   } = form;
 
-  // A verified owner's own claims outrank eTrade's record for display: the
-  // government IdP is the higher-trust source, and the API locks those fields
-  // to it. eTrade still supplies the name and phone when there is no
-  // verification — which is the case for every company represented by a PoA.
   const ownerVerified = identity?.owner.verified ?? false;
-  const nameValue = identity?.owner.name || etradeOwner?.name || "";
-  const phoneValue = identity?.owner.phone || etradeOwner?.phone || "";
-  const emailValue = identity?.owner.email || "";
-  const nameSource = identity?.owner.name ? "Fayda" : "eTrade";
-  const phoneSource = identity?.owner.phone ? "Fayda" : "eTrade";
 
   // A Fayda verification that names someone other than the person on the
   // licence is the one thing this step exists to catch. Advisory here — the two
@@ -65,12 +64,12 @@ export default function OwnerStep({
   return (
     <Stack gap="md">
       <Text size="sm" c="edr-muted">
-        These are the details of the person registered on your eTrade licence.
-        We fill in whatever eTrade and Fayda gave us; anything they left blank
-        we need from you.
+        {cooperative
+          ? "The person who runs the co-operative union or farm. We have no licence record to fill these in from, so we need all of them from you."
+          : "These are the details of the person registered on your eTrade licence. We fill in whatever eTrade and Fayda gave us; anything they left blank we need from you."}
       </Text>
 
-      {!etradeOwner && !ownerVerified && (
+      {!cooperative && !etradeOwner && !ownerVerified && (
         <Alert color="blue" variant="light" icon={<Info size={18} />}>
           Your eTrade licence didn't list a manager, so there's nothing for us
           to prefill. Enter the details of the person registered on it.
@@ -84,15 +83,19 @@ export default function OwnerStep({
           icon={<AlertTriangle size={18} />}
           title="This doesn't match your eTrade licence"
         >
-          Your licence lists{" "}
-          <strong>{identity?.etradeManagerName}</strong>, but the name here is{" "}
-          <strong>{nameValue}</strong>. You can continue, but our team will
-          check this before approving your account — so make sure it's the
-          person the licence actually names.
+          Your licence lists <strong>{identity?.etradeManagerName}</strong>, but
+          the name here is <strong>{identity?.owner.name}</strong>. You can
+          continue, but our team will check this before approving your account —
+          so make sure it's the person the licence actually names.
         </Alert>
       )}
 
-      <SourcedField label="Owner's Name" value={nameValue} source={nameSource}>
+      <SourcedField
+        label="Owner's Name"
+        value={identity?.owner.name}
+        source="Fayda"
+        locked={locked.name}
+      >
         <TextInput
           label="Owner's Name"
           placeholder="Abebe Bikila"
@@ -101,11 +104,16 @@ export default function OwnerStep({
         />
       </SourcedField>
 
-      <SimpleGrid cols={{ base: 1, sm: gaps.email && gaps.phone ? 2 : 1 }} spacing="md">
+      <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
         {/* eTrade never returns an email for the manager and Fayda's email
             claim is optional, so this is the field most companies actually
             type — it is required either way (`REQUIRED_COMPANY_INFO`). */}
-        <SourcedField label="Owner's Email" value={emailValue} source="Fayda">
+        <SourcedField
+          label="Owner's Email"
+          value={identity?.owner.email}
+          source="Fayda"
+          locked={locked.email}
+        >
           <TextInput
             label="Owner's Email"
             type="email"
@@ -117,8 +125,9 @@ export default function OwnerStep({
 
         <SourcedField
           label="Owner's Phone"
-          value={phoneValue}
-          source={phoneSource}
+          value={identity?.owner.phone}
+          source="Fayda"
+          locked={locked.phone}
         >
           <ControlledPhoneField
             control={control}
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx
index 52fd8c56d..9acf9f1fb 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx
@@ -1,5 +1,6 @@
 import {
-  Alert,
+  Button,
+  Card,
   Divider,
   Group,
   Loader,
@@ -8,7 +9,7 @@ import {
   Text,
   TextInput,
 } from "@mantine/core";
-import { Info, UserCheck, UserX } from "lucide-react";
+import { IdCard, ShieldCheck, UserCheck, UserX } from "lucide-react";
 import type { UseFormReturn } from "react-hook-form";
 
 import { SmartFileInput } from "@edr/ui-common";
@@ -24,6 +25,9 @@ import type {
 import type { FormData } from "../schema";
 import SourcedField from "../SourcedField";
 
+/** How a foreign company chose to prove the person: Fayda, or a passport. */
+export type IdentityMethod = "fayda" | "passport";
+
 export interface RepresentationStepProps {
   form: UseFormReturn<FormData>;
   identity?: CompanyIdentityState;
@@ -32,11 +36,26 @@ export interface RepresentationStepProps {
   /** A declaration change is in flight. */
   declarePending: boolean;
   /**
-   * Which of the representative's details the Fayda verification did not
-   * supply. Same contract as OwnerStep's `gaps`: an input is rendered for
-   * exactly these, and the schema requires exactly these.
+   * The answer is not the company's to change — it operates as a freight
+   * forwarder, which the API forces to "yes". No alert says so: the summary
+   * simply offers no way back, which is the same information without the
+   * lecture.
    */
-  gaps: { name: boolean; email: boolean; phone: boolean; address: boolean };
+  declarationLocked: boolean;
+  /**
+   * Which of the representative's details the Fayda verification owns. Same
+   * contract as OwnerStep's `locked`: a locked field is read-only, every other
+   * one is an input, and the schema requires exactly the unlocked ones.
+   */
+  locked: { name: boolean; email: boolean; phone: boolean; address: boolean };
+  /**
+   * How a foreign company is proving the subject. Null until it picks — the
+   * either/or is a fork, not a fallback, so nothing below it renders until one
+   * side is chosen. Always "fayda" for an Ethiopian company, which has no
+   * choice to make.
+   */
+  method: IdentityMethod | null;
+  onMethodChange: (method: IdentityMethod) => void;
   /** Single-field upload setting carrying just the DARS delegation letter. */
   poaDocumentSetting?: FileUploadSetting;
   documentFiles: Record<string, File | File[] | null>;
@@ -64,7 +83,10 @@ export default function RepresentationStep({
   identity,
   onDeclare,
   declarePending,
-  gaps,
+  declarationLocked,
+  locked,
+  method,
+  onMethodChange,
   poaDocumentSetting,
   documentFiles,
   uploadedDocumentKeys,
@@ -86,184 +108,220 @@ export default function RepresentationStep({
   }
 
   const declared = identity.poaDeclared;
-  const locked = identity.poaDeclared === "yes" && identity.subject === "poa";
-  // Only the API knows whether the lock is the freight-forwarder rule; it
-  // reports the answer as "yes" for them no matter what is stored, so a company
-  // that cannot switch to "no" is one the API will refuse. Rather than
-  // duplicating the role check here, the "no" card simply reports the refusal.
   const passportAccepted = identity.passportAccepted;
+  const subject = declared === "yes" ? identity.poa : identity.owner;
+  const verified = subject.verified;
+
+  // Nothing below the fork renders until the person is actually established:
+  // a Fayda claim that came back, or the passport path deliberately chosen.
+  // Asking for a name before the verification runs is asking for a value the
+  // verification is about to overwrite.
+  const established = verified || method === "passport";
+
+  const who = declared === "yes" ? "Representative" : "Owner";
+  const passportField =
+    declared === "yes" ? "poaPassportNumber" : "ownerPassportNumber";
 
   return (
     <Stack gap="lg">
-      <Stack gap="xs">
-        <Text fw={600} size="lg" c="edr-text">
-          Does anyone hold power of attorney for this company?
-        </Text>
-        <Text size="sm" c="edr-muted">
-          Your answer decides whose identity we verify — the representative's,
-          or the owner's.
-        </Text>
-      </Stack>
-
-      <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
-        <RoleCard
-          label="Yes, we have a representative"
-          description="Someone other than the owner is authorised to act for the company. We'll verify their identity and ask for the DARS delegation paper."
-          icon={<UserCheck size={20} />}
-          selected={declared === "yes"}
-          onClick={
-            declarePending || declared === "yes"
-              ? undefined
-              : () => onDeclare("yes")
-          }
-        />
-        <RoleCard
-          label="No, the owner acts for us"
-          description="Nobody holds power of attorney. We'll verify the owner instead, and no delegation paper is needed."
-          icon={<UserX size={20} />}
-          selected={declared === "no"}
-          onClick={
-            declarePending || declared === "no"
-              ? undefined
-              : () => onDeclare("no")
-          }
-        />
-      </SimpleGrid>
-
-      {locked && (
-        <Alert color="blue" variant="light" icon={<Info size={18} />}>
-          As a freight forwarder you act on other companies' behalf, so a Power
-          of Attorney is required — this can't be set to "no" while you hold the
-          freight forwarder role.
-        </Alert>
-      )}
-
-      {declared === null && (
-        <Text size="sm" c="edr-muted">
-          Pick one to continue.
-        </Text>
-      )}
-
-      {/* ---------------------------------------------------------------- */}
-      {/* No representative → the owner is the one who verifies.            */}
-      {/* ---------------------------------------------------------------- */}
-      {declared === "no" && (
+      {/* ------------------------------------------------------------------ */}
+      {/* The question. Once answered it collapses to its answer, so the step */}
+      {/* is about the person rather than re-presenting a settled choice.    */}
+      {/* ------------------------------------------------------------------ */}
+      {declared === null ? (
         <>
-          <Divider />
-          <FaydaVerifyPanel
-            subject="owner"
-            title="Company owner"
-            state={identity.owner}
-            required={!passportAccepted}
-          />
-          {/* Fayda is an Ethiopian national ID, so a foreign company's owner
-              may hold none — a passport number proves them instead. Offered
-              alongside, not after: either one satisfies the gate. */}
-          {passportAccepted && !identity.owner.verified && (
-            <TextInput
-              label="Owner's Passport Number"
-              description="If the owner has no Fayda ID, their passport number proves their identity instead."
-              placeholder="P1234567"
-              error={errors.ownerPassportNumber?.message}
-              {...register("ownerPassportNumber")}
+          <Stack gap="xs">
+            <Text fw={600} size="lg" c="edr-text">
+              Does anyone hold power of attorney for this company?
+            </Text>
+            <Text size="sm" c="edr-muted">
+              Your answer decides whose identity we verify — the
+              representative's, or the owner's.
+            </Text>
+          </Stack>
+
+          <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+            <RoleCard
+              label="Yes, we have a representative"
+              description="Someone other than the owner is authorised to act for the company. We'll verify their identity and ask for the DARS delegation paper."
+              icon={<UserCheck size={20} />}
+              selected={false}
+              onClick={declarePending ? undefined : () => onDeclare("yes")}
             />
-          )}
-        </>
-      )}
-
-      {/* ---------------------------------------------------------------- */}
-      {/* A representative → they verify, and the delegation is evidenced.  */}
-      {/* ---------------------------------------------------------------- */}
-      {declared === "yes" && (
-        <>
-          <Divider />
-          <FaydaVerifyPanel
-            subject="poa"
-            title="Power of Attorney"
-            state={identity.poa}
-            required={!passportAccepted}
-          />
-          {passportAccepted && !identity.poa.verified && (
-            <TextInput
-              label="Representative's Passport Number"
-              description="If your representative has no Fayda ID, their passport number proves their identity instead."
-              placeholder="P1234567"
-              error={errors.poaPassportNumber?.message}
-              {...register("poaPassportNumber")}
+            <RoleCard
+              label="No, the owner acts for us"
+              description="Nobody holds power of attorney. We'll verify the owner instead, and no delegation paper is needed."
+              icon={<UserX size={20} />}
+              selected={false}
+              onClick={declarePending ? undefined : () => onDeclare("no")}
             />
-          )}
-
-          {/* Whatever the Fayda claim carried is shown on the panel above and
-              never typed here — the verification owns it. The rest is asked
-              for outright, because the API demands name/email/phone from any
-              declared representative (`REQUIRED_POA_FIELDS`). */}
-          <SourcedField
-            label="Representative's Name"
-            value={gaps.name ? "" : identity.poa.name}
-            source="Fayda"
-          >
-            <TextInput
-              label="Representative's Name"
-              placeholder="Abebe Bikila"
-              error={errors.poaName?.message}
-              {...register("poaName")}
-            />
-          </SourcedField>
-
-          <SimpleGrid
-            cols={{ base: 1, sm: gaps.email && gaps.phone ? 2 : 1 }}
-            spacing="md"
-          >
-            <SourcedField
-              label="Representative's Email"
-              value={gaps.email ? "" : identity.poa.email}
-              source="Fayda"
-            >
-              <TextInput
-                label="Representative's Email"
-                type="email"
-                placeholder="representative@company.com"
-                error={errors.poaEmail?.message}
-                {...register("poaEmail")}
-              />
-            </SourcedField>
-
-            <SourcedField
-              label="Representative's Phone"
-              value={gaps.phone ? "" : identity.poa.phone}
-              source="Fayda"
-            >
-              <ControlledPhoneField
-                control={control}
-                name="poaPhone"
-                label="Representative's Phone"
-              />
-            </SourcedField>
           </SimpleGrid>
+        </>
+      ) : (
+        <ChoiceSummary
+          icon={declared === "yes" ? <UserCheck size={18} /> : <UserX size={18} />}
+          label={
+            declared === "yes"
+              ? "A representative holds power of attorney"
+              : "The owner acts for the company"
+          }
+          detail={
+            declared === "yes"
+              ? "We'll verify their identity and ask for the DARS delegation paper."
+              : "Nobody holds power of attorney, so we verify the owner."
+          }
+          onChange={
+            declarePending || declarationLocked
+              ? undefined
+              : () => onDeclare(declared === "yes" ? "no" : "yes")
+          }
+          changeLabel={declared === "yes" ? "We have no representative" : "We have a representative"}
+        />
+      )}
 
-          {gaps.address && (
-            <TextInput
-              label="Representative's Location"
-              placeholder="City, Country"
-              error={errors.poaLocation?.message}
-              {...register("poaLocation")}
-            />
+      {declared !== null && (
+        <>
+          <Divider />
+
+          {/* -------------------------------------------------------------- */}
+          {/* How the person is proved. Ethiopian: Fayda, no choice. Foreign: */}
+          {/* Fayda or a passport — one or the other, picked outright.        */}
+          {/* -------------------------------------------------------------- */}
+          {passportAccepted && !verified && method === null ? (
+            <Stack gap="xs">
+              <Text fw={600} c="edr-text">
+                How would you like to prove {who.toLowerCase()}'s identity?
+              </Text>
+              <Text size="sm" c="edr-muted">
+                Either one is enough — you don't need both.
+              </Text>
+              <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md" mt="xs">
+                <RoleCard
+                  label="Verify with Fayda"
+                  description="Their name, phone and address come straight from the national ID — nothing to type."
+                  icon={<ShieldCheck size={20} />}
+                  selected={false}
+                  onClick={() => onMethodChange("fayda")}
+                />
+                <RoleCard
+                  label="Use a passport instead"
+                  description="For someone who holds no Fayda ID. You'll enter their passport number and details yourself."
+                  icon={<IdCard size={20} />}
+                  selected={false}
+                  onClick={() => onMethodChange("passport")}
+                />
+              </SimpleGrid>
+            </Stack>
+          ) : (
+            <>
+              {(method === "fayda" || !passportAccepted || verified) && (
+                <FaydaVerifyPanel
+                  subject={declared === "yes" ? "poa" : "owner"}
+                  title={declared === "yes" ? "Power of Attorney" : "Company owner"}
+                  state={subject}
+                  required={!passportAccepted}
+                />
+              )}
+
+              {passportAccepted && !verified && method === "passport" && (
+                <TextInput
+                  label={`${who}'s Passport Number`}
+                  description="Fayda is an Ethiopian national ID, so a passport number proves this person instead."
+                  placeholder="P1234567"
+                  error={errors[passportField]?.message}
+                  {...register(passportField)}
+                />
+              )}
+
+              {passportAccepted && !verified && method !== null && (
+                <Button
+                  variant="subtle"
+                  size="compact-xs"
+                  style={{ alignSelf: "flex-start" }}
+                  onClick={() =>
+                    onMethodChange(method === "fayda" ? "passport" : "fayda")
+                  }
+                >
+                  {method === "fayda"
+                    ? "Use a passport instead"
+                    : "Verify with Fayda instead"}
+                </Button>
+              )}
+            </>
           )}
 
-          {poaDocumentSetting && (
+          {/* -------------------------------------------------------------- */}
+          {/* The representative's own details — only once the person exists, */}
+          {/* and only the parts the verification did not already carry. What */}
+          {/* Fayda supplied is shown on the panel above and never repeated.  */}
+          {/* -------------------------------------------------------------- */}
+          {declared === "yes" && established && (
             <>
-              <Divider my="sm" />
-              <Text size="sm" c="edr-muted">
-                Upload the delegation paper authenticated by DARS. It is what
-                evidences that this person was actually delegated.
-              </Text>
-              <SmartFileInput
-                file={poaDocumentSetting}
-                value={documentFiles}
-                uploadedKeys={uploadedDocumentKeys}
-                errors={documentFieldErrors}
-                onChange={onDocumentFilesChange}
-              />
+              <SourcedField
+                label="Representative's Name"
+                value={identity.poa.name}
+                source="Fayda"
+                locked={locked.name}
+              >
+                <TextInput
+                  label="Representative's Name"
+                  placeholder="Abebe Bikila"
+                  error={errors.poaName?.message}
+                  {...register("poaName")}
+                />
+              </SourcedField>
+
+              <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+                <SourcedField
+                  label="Representative's Email"
+                  value={identity.poa.email}
+                  source="Fayda"
+                  locked={locked.email}
+                >
+                  <TextInput
+                    label="Representative's Email"
+                    type="email"
+                    placeholder="representative@company.com"
+                    error={errors.poaEmail?.message}
+                    {...register("poaEmail")}
+                  />
+                </SourcedField>
+
+                <SourcedField
+                  label="Representative's Phone"
+                  value={identity.poa.phone}
+                  source="Fayda"
+                  locked={locked.phone}
+                >
+                  <ControlledPhoneField
+                    control={control}
+                    name="poaPhone"
+                    label="Representative's Phone"
+                  />
+                </SourcedField>
+              </SimpleGrid>
+
+              {!locked.address && (
+                <TextInput
+                  label="Representative's Location"
+                  placeholder="City, Country"
+                  error={errors.poaLocation?.message}
+                  {...register("poaLocation")}
+                />
+              )}
+
+              {poaDocumentSetting && (
+                <>
+                  <Divider my="sm" />
+                  <SmartFileInput
+                    file={poaDocumentSetting}
+                    value={documentFiles}
+                    uploadedKeys={uploadedDocumentKeys}
+                    errors={documentFieldErrors}
+                    onChange={onDocumentFilesChange}
+                  />
+                </>
+              )}
             </>
           )}
         </>
@@ -271,3 +329,41 @@ export default function RepresentationStep({
     </Stack>
   );
 }
+
+/** A settled choice, shown as its answer with a way back to the question. */
+function ChoiceSummary({
+  icon,
+  label,
+  detail,
+  onChange,
+  changeLabel,
+}: {
+  icon: React.ReactNode;
+  label: string;
+  detail: string;
+  onChange?: () => void;
+  changeLabel: string;
+}) {
+  return (
+    <Card padding="md" radius="md" withBorder>
+      <Group justify="space-between" align="flex-start" wrap="nowrap">
+        <Group gap="sm" align="flex-start" wrap="nowrap">
+          <span style={{ display: "flex", marginTop: 2 }}>{icon}</span>
+          <Stack gap={2}>
+            <Text fw={600} size="sm" c="edr-text">
+              {label}
+            </Text>
+            <Text size="xs" c="edr-muted">
+              {detail}
+            </Text>
+          </Stack>
+        </Group>
+        {onChange && (
+          <Button variant="subtle" size="compact-xs" onClick={onChange}>
+            {changeLabel}
+          </Button>
+        )}
+      </Group>
+    </Card>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx b/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx
index 2c03aaed3..9399c5efc 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx
@@ -69,6 +69,15 @@ export default function TabOwner({
   // Only the person the declaration points at carries the verification, so the
   // panel is offered here only when that person is the owner.
   const ownerIsSubject = identity?.subject === "owner";
+  // A Fayda verification owns what its claims filled — the API refuses to
+  // overwrite those, so they show read-only. Anything it left blank stays
+  // editable here, whatever value is currently stored.
+  const ownerVerified = owner?.verified ?? false;
+  const ownerLocked = {
+    name: ownerVerified && Boolean(owner?.name?.trim()),
+    email: ownerVerified && Boolean(owner?.email?.trim()),
+    phone: ownerVerified && Boolean(owner?.phone?.trim()),
+  };
 
   const {
     register,
@@ -147,7 +156,12 @@ export default function TabOwner({
             />
           )}
 
-          <SourcedField label="Name" value={owner?.name} source="Fayda">
+          <SourcedField
+            label="Name"
+            value={owner?.name}
+            source="Fayda"
+            locked={ownerLocked.name}
+          >
             <TextInput
               label="Name"
               placeholder="Abebe Bikila"
@@ -158,7 +172,12 @@ export default function TabOwner({
 
           <Grid>
             <Grid.Col span={{ base: 12, sm: 6 }}>
-              <SourcedField label="Email" value={owner?.email} source="Fayda">
+              <SourcedField
+                label="Email"
+                value={owner?.email}
+                source="Fayda"
+                locked={ownerLocked.email}
+              >
                 <TextInput
                   label="Email"
                   type="email"
@@ -169,7 +188,12 @@ export default function TabOwner({
               </SourcedField>
             </Grid.Col>
             <Grid.Col span={{ base: 12, sm: 6 }}>
-              <SourcedField label="Phone" value={owner?.phone} source="Fayda">
+              <SourcedField
+                label="Phone"
+                value={owner?.phone}
+                source="Fayda"
+                locked={ownerLocked.phone}
+              >
                 <ControlledPhoneField
                   control={control}
                   name="ownerPhone"
diff --git a/apps/edr-freight-web/portal/src/pages/settings/TabPowerOfAttorney.tsx b/apps/edr-freight-web/portal/src/pages/settings/TabPowerOfAttorney.tsx
index a3118ad28..63dc3b777 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabPowerOfAttorney.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabPowerOfAttorney.tsx
@@ -288,9 +288,11 @@ export default function TabPowerOfAttorney({
           )}
         </Group>
         <Text c="edr-muted" size="sm" mb="lg">
-          {requirePoa
-            ? "As a freight forwarder you act on other companies' behalf, so a Power of Attorney is required."
-            : "Tell us whether anyone is authorised to act for the company — your answer decides whose identity we verify."}{" "}
+          {/* The "Required for freight forwarder" badge above already says why
+              a forwarder has no choice here; repeating it in prose was a
+              lecture, not information. */}
+          {!requirePoa &&
+            "Tell us whether anyone is authorised to act for the company — your answer decides whose identity we verify. "}
           {declared === "no"
             ? "The owner acts for the company, so no delegation paper is needed."
             : "A representative must be identified, and the DARS delegation paper authorising them uploaded."}

From d6e349f32961e26b010f5115bc435c03415b4fde Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 11 Aug 2026 12:54:51 +0000
Subject: [PATCH 023/174] feat(companies): onboard co-operative unions and
 farms
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

They hold a TIN but no business licence, so there is no eTrade record to look
their registration up in. A checkbox on the first wizard step marks them, and
everything that assumed a trade licence bends around it:

- The company step replaces the eTrade lookup with typed registration details
  — name, region, zone, woreda, kebele, house number — required exactly because
  they are now on screen. applyEtradeSourcedFields skips the lookup rather than
  failing it, so what the customer sends is what is stored.
- No freight-forwarder role. Forwarding is licensed work, so the option is not
  offered, and the API refuses it at start-onboarding and at every later
  role-add rather than letting approval fail on a document they cannot produce.
- No per-role business-licence upload, client-side or in the completion gate.
- Their own document set (company_onboarding_documents_cooperative) merges on
  top of the nationality one, admin-managed like every other set. Nationality
  wins a fileKey collision so no slot renders twice, and the DARS paper is not
  injected into it — the set it merges onto already carries one.
- The owner is typed in full; with no eTrade manager on file the licence
  comparison reports "nothing to compare against", which backoffice now
  explains rather than leaving as a bare dash.

Stored as an attributes flag, not a column: everything it changes is
behavioural, and nothing queries or joins on it.
---
 apps/edr-freight-api/src/app.module.ts        |   2 +
 .../migrations/3400000000000-StampSettings.ts |  28 +++
 .../billing/documents/documents.module.ts     |   4 +-
 .../documents/invoice-document.service.ts     |  35 +++-
 .../modules/companies/companies.controller.ts |   1 +
 .../companies/companies.role-deselect.spec.ts |   8 +-
 .../modules/companies/companies.service.ts    |  98 ++++++++++-
 .../onboarding-requirements-response.dto.ts   |  14 ++
 .../companies/dto/profile-response.dto.ts     |   9 +-
 .../companies/dto/response-company.dto.ts     |   8 +
 .../companies/dto/start-onboarding.dto.ts     |  19 +-
 .../companies/entities/company.entity.ts      |  19 ++
 .../file-upload-settings.service.ts           |   5 +
 .../poa-delegation.constants.ts               |   8 +
 .../dto/update-stamp-setting.dto.ts           |   9 +
 .../entities/stamp-setting.entity.ts          |  24 +++
 .../stamp-settings.controller.ts              |  39 ++++
 .../stamp-settings/stamp-settings.module.ts   |  23 +++
 .../stamp-settings.repository.ts              |  21 +++
 .../stamp-settings/stamp-settings.service.ts  | 154 ++++++++++++++++
 .../src/seed/file-upload-settings.seeder.ts   |  33 ++++
 .../src/seed/freight-permissions.registry.ts  |  30 ++++
 apps/edr-freight-web/backoffice/src/App.tsx   |  20 +++
 .../components/layout/sidebar-sections.tsx    |  12 ++
 .../backoffice/src/hooks/useStampSettings.ts  |  45 +++++
 .../backoffice/src/lib/permissions.ts         |  10 ++
 .../pages/customers/CustomerDetailPage.tsx    |  15 ++
 .../settings/InvoiceStampSettingsPage.tsx     |  88 ++++++++++
 .../Settings/uploadTeeterandSingature.tsx     |  12 +-
 .../src/services/stampSettings.service.ts     |  31 ++++
 .../backoffice/src/types/customer.ts          |   6 +
 .../onboarding/OnboardingWizardDialog.tsx     |  37 +++-
 .../src/pages/accounts/CompanyProfileForm.tsx | 166 ++++++++++++++----
 .../companyProfileForm/schema.test.ts         |  68 ++++---
 .../accounts/companyProfileForm/schema.ts     |  43 +++--
 .../steps/CompanyInfoStep.tsx                 | 137 +++++++++++----
 .../pages/settings/OnboardingRoleSelect.tsx   |  11 +-
 .../portal/src/services/api.ts                |   2 +
 .../portal/src/services/companies.service.ts  |  10 ++
 .../portal/src/types/profile.ts               |   2 +
 40 files changed, 1188 insertions(+), 118 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3400000000000-StampSettings.ts
 create mode 100644 apps/edr-freight-api/src/modules/stamp-settings/dto/update-stamp-setting.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/stamp-settings/entities/stamp-setting.entity.ts
 create mode 100644 apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.controller.ts
 create mode 100644 apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.module.ts
 create mode 100644 apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.repository.ts
 create mode 100644 apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/hooks/useStampSettings.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/settings/InvoiceStampSettingsPage.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/services/stampSettings.service.ts

diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index c1b890719..029f2040b 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -49,6 +49,7 @@ import { SupportChatModule } from "./modules/support-chat/support-chat.module";
 import { FileUploadSettingsModule } from "./modules/file-upload-settings/file-upload-settings.module";
 import { DropdownSettingsModule } from "./modules/dropdown-settings/dropdown-settings.module";
 import { ExchangeSettingsModule } from "./modules/exchange-settings/exchange-settings.module";
+import { StampSettingsModule } from "./modules/stamp-settings/stamp-settings.module";
 import { ContractTemplatesModule } from "./modules/contract-templates/contract-templates.module";
 import { SupportContentModule } from "./modules/support-content/support-content.module";
 import { OtpModule } from "./modules/otp/otp.module";
@@ -221,6 +222,7 @@ if (!process.env.APPLICATION_NAME) {
     FileUploadSettingsModule,
     DropdownSettingsModule,
     ExchangeSettingsModule,
+    StampSettingsModule,
     ContractTemplatesModule,
     SupportContentModule,
     OtpModule,
diff --git a/apps/edr-freight-api/src/migrations/3400000000000-StampSettings.ts b/apps/edr-freight-api/src/migrations/3400000000000-StampSettings.ts
new file mode 100644
index 000000000..9556318f9
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3400000000000-StampSettings.ts
@@ -0,0 +1,28 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Single-row table holding the one company stamp/seal image stamped onto
+ * generated invoice/receipt PDFs (see StampSettingsService /
+ * InvoiceDocumentService). Same single-row shape as exchange_settings; the
+ * app never inserts more than one row.
+ */
+export class StampSettings3400000000000 implements MigrationInterface {
+  name = "StampSettings3400000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.stamp_settings (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        stamp_file_id uuid REFERENCES freight.files(id),
+        updated_by_id uuid,
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz
+      );
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.stamp_settings;`);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/documents/documents.module.ts b/apps/edr-freight-api/src/modules/billing/documents/documents.module.ts
index c320a5d44..363cda3f0 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/documents.module.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/documents.module.ts
@@ -7,7 +7,9 @@ import { PdfRenderService } from "./pdf-render.service";
  * Standalone document infrastructure — generic HTML→PDF plus the shared
  * invoice/receipt renderer. Has no domain dependencies, so any module (billing,
  * warehouses, …) can import it to print invoices without coupling to the
- * billing payment graph.
+ * billing payment graph. StampSettingsService is @Global (see
+ * StampSettingsModule) so InvoiceDocumentService can inject it without this
+ * module declaring an explicit import.
  */
 @Module({
   providers: [PdfRenderService, InvoiceDocumentService],
diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
index 06d164bbd..72146491d 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
@@ -1,5 +1,6 @@
 import { Injectable } from "@nestjs/common";
 
+import { StampSettingsService } from "../../stamp-settings/stamp-settings.service";
 import { PdfRenderService } from "./pdf-render.service";
 import {
   PdfColor,
@@ -53,6 +54,13 @@ export interface InvoiceDocumentModel {
   totals: InvoiceDocumentTotal[];
   /** Override the round seal text; defaults from kind/status. */
   sealText?: string;
+  /**
+   * Company stamp image (data URL) to render instead of the plain text seal.
+   * Callers normally leave this unset — `InvoiceDocumentService.render()`
+   * fills it in from the single global stamp in StampSettingsService; set it
+   * explicitly only to override that default for one document.
+   */
+  stampImageUrl?: string | null;
 }
 
 /**
@@ -63,12 +71,21 @@ export interface InvoiceDocumentModel {
  */
 @Injectable()
 export class InvoiceDocumentService {
-  constructor(private readonly pdf: PdfRenderService) {}
+  constructor(
+    private readonly pdf: PdfRenderService,
+    private readonly stampSettings: StampSettingsService,
+  ) {}
 
   async render(
     model: InvoiceDocumentModel,
   ): Promise<{ filename: string; buffer: Buffer }> {
-    const html = this.buildHtml(model);
+    const stampImageUrl =
+      model.stampImageUrl !== undefined
+        ? model.stampImageUrl
+        : await this.stampSettings.getStampImageUrl();
+    const resolvedModel: InvoiceDocumentModel = { ...model, stampImageUrl };
+
+    const html = this.buildHtml(resolvedModel);
     const kindLabel = model.kind === "RECEIPT" ? "receipt" : "invoice";
     return {
       filename: `${this.safeFilename(model.documentNumber)}-${kindLabel}.pdf`,
@@ -77,7 +94,11 @@ export class InvoiceDocumentService {
         // Chromium-less fallback: draw a genuine styled invoice (header, seal,
         // summary grid, line-item table, totals) from the model — not a flat
         // plain-text dump — so it still reads as a proper invoice document.
-        fallback: () => this.buildFallbackPdf(model),
+        // ponytail: still draws the plain vector seal, not the uploaded stamp
+        // image — embedding a raster image needs a new PDF XObject primitive
+        // in styled-pdf.util.ts. Upgrade when the Chromium-less path needs to
+        // carry the real stamp too; today it's a rare degraded fallback.
+        fallback: () => this.buildFallbackPdf(resolvedModel),
       }),
     };
   }
@@ -218,6 +239,10 @@ export class InvoiceDocumentService {
     const showCategory = Boolean(model.categoryHeader);
     const sealText =
       model.sealText ?? (model.kind === "RECEIPT" || model.status === "PAID" ? "EDR PAID" : "EDR");
+    const sealMarkup = model.stampImageUrl
+      ? `<img src="${esc(model.stampImageUrl)}" alt="Company stamp" />`
+      : esc(sealText);
+    const sealClass = model.stampImageUrl ? "seal seal-image" : "seal";
 
     const summaryRows = model.summary
       .map((row) => `<div><span>${esc(row.label)}</span>${esc(row.value)}</div>`)
@@ -256,6 +281,8 @@ export class InvoiceDocumentService {
     .meta { text-align: right; font-size: 12px; color: #475569; }
     .meta strong { display: block; color: #0f172a; font-size: 17px; margin-top: 5px; }
     .seal { position: absolute; right: 28px; top: 118px; width: 116px; height: 116px; border: 4px double #0f766e; border-radius: 999px; color: #0f766e; display: flex; align-items: center; justify-content: center; text-align: center; font-weight: 800; font-size: 18px; transform: rotate(-14deg); opacity: .82; }
+    .seal.seal-image { border: none; border-radius: 0; opacity: 1; transform: none; }
+    .seal img { max-width: 100%; max-height: 100%; object-fit: contain; }
     .summary { display: grid; grid-template-columns: 1fr 1fr; gap: 12px 28px; margin: 24px 150px 16px 0; font-size: 13px; }
     .summary div { border-bottom: 1px solid #e2e8f0; padding: 7px 0; }
     .summary span { color: #64748b; display: block; font-size: 11px; margin-bottom: 3px; }
@@ -283,7 +310,7 @@ export class InvoiceDocumentService {
         Issued: ${esc(date(model.issuedAt))}
       </div>
     </div>
-    <div class="seal">${esc(sealText)}</div>
+    <div class="${sealClass}">${sealMarkup}</div>
     <div class="summary">${summaryRows}</div>
     <table>
       <thead>
diff --git a/apps/edr-freight-api/src/modules/companies/companies.controller.ts b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
index a0c609f67..d35400f1a 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.controller.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
@@ -266,6 +266,7 @@ export class CompaniesController {
       dto.companyType,
       dto.roles,
       dto.nationality,
+      dto.cooperative,
     );
     return new CompanyInfoResponseDto(profile, company);
   }
diff --git a/apps/edr-freight-api/src/modules/companies/companies.role-deselect.spec.ts b/apps/edr-freight-api/src/modules/companies/companies.role-deselect.spec.ts
index 5961be90f..ea81e4dbe 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.role-deselect.spec.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.role-deselect.spec.ts
@@ -26,7 +26,13 @@ function makeService(existing: ExistingProfile[]) {
     })),
     softDelete: jest.fn(async () => undefined),
   };
-  const companiesRepo = { update: jest.fn(async () => null) };
+  // `findById` is only consulted when the co-operative flag is in play (adding
+  // a forwarder role, or setting the flag itself) — a plain company row is the
+  // right answer for every case here.
+  const companiesRepo = {
+    update: jest.fn(async () => null),
+    findById: jest.fn(async () => ({ id: "company-1", attributes: {} })),
+  };
   const profilesRepo = {
     findByUserId: jest.fn(async () => ({
       id: "external-1",
diff --git a/apps/edr-freight-api/src/modules/companies/companies.service.ts b/apps/edr-freight-api/src/modules/companies/companies.service.ts
index 4362c4285..cf2f2e84d 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.service.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.service.ts
@@ -24,6 +24,7 @@ import { FilesService } from "../files/files.service";
 import { FileRecord } from "../files/entities/file.entity";
 import { FileUploadSettingsService } from "../file-upload-settings/file-upload-settings.service";
 import {
+  COOPERATIVE_ONBOARDING_CODE,
   POA_DELEGATION_FILE_KEY,
   POA_DELEGATION_LABEL,
   POA_DELEGATION_PENDING_CODE,
@@ -60,6 +61,8 @@ import {
   CompanyNationality,
   CompanyStatus,
   CompanyType,
+  COOPERATIVE_KEY,
+  isCooperative,
 } from "./entities/company.entity";
 import { ExternalProfile } from "./entities/external-profile.entity";
 import {
@@ -262,6 +265,7 @@ export class CompaniesService {
       : "company_onboarding_documents_ethiopian";
   }
 
+
   async createCompany(dto: CreateCompanyDto): Promise<Company> {
     const exists = await this.companiesRepo.existsByTin(dto.tin);
     if (exists) {
@@ -368,19 +372,41 @@ export class CompaniesService {
     companyType: CompanyType,
     roles: ProfileType[],
     nationality?: CompanyNationality,
+    cooperative?: boolean,
   ): Promise<{ profile: ExternalProfile; company: Company }> {
     // Already started — reuse the existing draft, just ensure roles exist and
     // keep the nationality up to date if it was (re)selected.
     const existing = await this.profilesRepo.findByUserId(identity.userId);
     if (existing) {
       const companyId = existing.company?.id ?? existing.companyId;
+      // Only load the row when the answer actually depends on it: to merge the
+      // flag into `attributes`, or to read a stored one the caller didn't send.
+      const needsCompany =
+        cooperative !== undefined ||
+        roles.includes(ProfileType.freightForwarder);
+      const current = needsCompany
+        ? await this.companiesRepo.findById(companyId)
+        : null;
+      this.assertRolesAllowedForCooperative(
+        cooperative ?? isCooperative(current),
+        roles,
+      );
       await this.syncCompanyProfiles(companyId, companyType, roles);
-      if (nationality) {
-        await this.companiesRepo.update(companyId, { nationality });
+      const updates: Partial<Company> = {};
+      if (nationality) updates.nationality = nationality;
+      if (cooperative !== undefined) {
+        updates.attributes = {
+          ...(current?.attributes ?? {}),
+          [COOPERATIVE_KEY]: cooperative,
+        };
+      }
+      if (Object.keys(updates).length > 0) {
+        await this.companiesRepo.update(companyId, updates);
       }
       return this.getCompanyInfoByUserId(identity.userId);
     }
 
+    this.assertRolesAllowedForCooperative(cooperative === true, roles);
     const allowedTypes = this.getProfileTypeForCompanyType(companyType);
     const chosenTypes = roles.filter((t) => allowedTypes.includes(t));
 
@@ -393,6 +419,7 @@ export class CompaniesService {
       country: "Ethiopia",
       nationality: nationality ?? CompanyNationality.Ethiopian,
       status: CompanyStatus.Pending,
+      ...(cooperative ? { attributes: { [COOPERATIVE_KEY]: true } } : {}),
     });
 
     await this.profilesRepo.create({
@@ -410,6 +437,27 @@ export class CompaniesService {
     return this.getCompanyInfoByUserId(identity.userId);
   }
 
+  /**
+   * A co-operative union or farm cannot hold the freight-forwarder role.
+   *
+   * Forwarding is licensed work — the forwarder signs on other companies'
+   * behalf, which is why the role carries a mandatory Power of Attorney and a
+   * DARS delegation paper. A co-op is here precisely because it has no business
+   * licence, so the role is refused at the door rather than left to fail later
+   * at approval with a document it can never produce.
+   */
+  private assertRolesAllowedForCooperative(
+    cooperative: boolean,
+    roles: ProfileType[],
+  ): void {
+    if (!cooperative) return;
+    if (roles.includes(ProfileType.freightForwarder)) {
+      throw new BadRequestException(
+        "A co-operative union or farm cannot register as a freight forwarder — that role requires a business licence.",
+      );
+    }
+  }
+
   /**
    * Reconcile the company's operational profiles with the roles the user has
    * selected: create the missing ones, drop the ones they deselected.
@@ -1887,6 +1935,7 @@ export class CompaniesService {
       // without a Power of Attorney and its DARS paper — checked here so the
       // customer is told at the point of asking, not at review.
       if (type === ProfileType.freightForwarder) {
+        this.assertRolesAllowedForCooperative(isCooperative(company), [type]);
         const asForwarder = this.withProfileType(company, type);
         this.assertIdentityVerified(asForwarder);
         await this.assertPoaDelegationSatisfied(
@@ -1933,6 +1982,7 @@ export class CompaniesService {
 
     let created = await this.companyProfilesRepo.findByType(companyId, type);
     if (!created && type === ProfileType.freightForwarder) {
+      this.assertRolesAllowedForCooperative(isCooperative(company), [type]);
       const asForwarder = this.withProfileType(company, type);
       this.assertIdentityVerified(asForwarder);
       await this.assertPoaDelegationSatisfied(
@@ -1986,18 +2036,35 @@ export class CompaniesService {
       .filter((f) => !f.get(company))
       .map((f) => ({ key: f.key, label: f.label }));
 
-    // 2. Nationality-based company documents + which are already uploaded.
+    // 2. Nationality-based company documents + which are already uploaded. A
+    // co-operative adds its own set on top: it provides everything its
+    // nationality demands, plus the papers standing in for the business licence
+    // it does not hold.
+    const cooperative = isCooperative(company);
     const documentSettingCode = this.documentSettingCodeFor(
       company.nationality,
     );
-    const [setting, uploadedFiles] = await Promise.all([
+    const [setting, coopSetting, uploadedFiles] = await Promise.all([
       this.fileUploadSettingsService
         .getByCode(documentSettingCode)
         .catch(() => null),
+      cooperative
+        ? this.fileUploadSettingsService
+          .getByCode(COOPERATIVE_ONBOARDING_CODE)
+          .catch(() => null)
+        : Promise.resolve(null),
       this.filesService.findByResource(company.id, "companies"),
     ]);
     const uploadedCodes = new Set(uploadedFiles.map((f) => f.code));
-    const documents = (setting?.fields ?? [])
+    // The co-op set is admin-managed and could name a fileKey the nationality
+    // set already carries; the nationality field wins so the same slot is never
+    // rendered (or required) twice.
+    const baseFields = setting?.fields ?? [];
+    const baseKeys = new Set(baseFields.map((f) => f.fileKey));
+    const documents = [
+      ...baseFields,
+      ...(coopSetting?.fields ?? []).filter((f) => !baseKeys.has(f.fileKey)),
+    ]
       .slice()
       .sort((a, b) => a.displayOrder - b.displayOrder)
       .map((f) => ({
@@ -2029,7 +2096,13 @@ export class CompaniesService {
         };
       }),
     );
-    const missingLicenses = licenseProfiles.filter((p) => !p.uploaded);
+    // A co-operative holds no business licence — that is the whole reason it
+    // skips the eTrade lookup — so the per-role licence is not owed. Its own
+    // document set (merged above) is what stands in for it. The profiles are
+    // still reported so the portal can show them; only the requirement lifts.
+    const missingLicenses = cooperative
+      ? []
+      : licenseProfiles.filter((p) => !p.uploaded);
 
     // 4. Power of Attorney. Whether there is one at all is the company's own
     // declaration — the question the wizard asks outright — and that answer is
@@ -2115,7 +2188,7 @@ export class CompaniesService {
     const total =
       requiredInfo.length +
       requiredDocCount +
-      licenseProfiles.length +
+      (cooperative ? 0 : licenseProfiles.length) +
       poaItemCount +
       // The declaration and the verification it selects.
       2;
@@ -2130,7 +2203,11 @@ export class CompaniesService {
 
     return new OnboardingRequirementsResponseDto({
       documentSettingCode,
+      cooperativeDocumentSettingCode: cooperative
+        ? COOPERATIVE_ONBOARDING_CODE
+        : null,
       nationality: company.nationality ?? CompanyNationality.Ethiopian,
+      cooperative,
       companyInfo: {
         complete: missingInfo.length === 0,
         missingFields: missingInfo,
@@ -3369,6 +3446,13 @@ export class CompaniesService {
     company: Company,
     dto: UpdateProfileDto & { etradeManager?: { name: string; phone: string } },
   ): Promise<void> {
+    // A co-operative union or farm has a TIN but no business licence, so eTrade holds no
+    // record to check these against — the customer types the company name and
+    // the registered address themselves, and what they send IS the data. The
+    // check is skipped rather than failed: running the lookup would 400 every
+    // save with "no registration found for this TIN".
+    if (isCooperative(company)) return;
+
     const touched = ETRADE_SOURCED_FIELDS.some(
       (key) => key !== "tin" && dto[key] !== undefined,
     );
diff --git a/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts
index b1baa2553..8d47dbb4e 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts
@@ -68,7 +68,19 @@ export interface OnboardingPoaState {
 export class OnboardingRequirementsResponseDto {
   /** Resolved document setting code (by nationality) the docs were drawn from. */
   documentSettingCode: string;
+  /**
+   * The co-operative document set, merged on top of the nationality one — null
+   * for every other company. `documents` below already carries the merged
+   * result; this is only so the portal can fetch the same extra fields when it
+   * renders the pickers from the file-settings endpoint.
+   */
+  cooperativeDocumentSettingCode: string | null;
   nationality: string;
+  /**
+   * The company trades as a co-operative: no business licence, so no eTrade
+   * lookup, no per-role licence upload, and no freight-forwarder role.
+   */
+  cooperative: boolean;
 
   /** Required company-information fields and whether each is filled. */
   companyInfo: {
@@ -106,7 +118,9 @@ export class OnboardingRequirementsResponseDto {
 
   constructor(init: Omit<OnboardingRequirementsResponseDto, never>) {
     this.documentSettingCode = init.documentSettingCode;
+    this.cooperativeDocumentSettingCode = init.cooperativeDocumentSettingCode;
     this.nationality = init.nationality;
+    this.cooperative = init.cooperative;
     this.companyInfo = init.companyInfo;
     this.documents = init.documents;
     this.licenseProfiles = init.licenseProfiles;
diff --git a/apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts
index dc2ddc4c3..0d7293ab0 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts
@@ -2,7 +2,7 @@ import {
   buildCompanyIdentityState,
   CompanyIdentityStateDto,
 } from "./complete-identity-verification.dto";
-import { Company } from "../entities/company.entity";
+import { Company, isCooperative } from "../entities/company.entity";
 import { ExternalProfile } from "../entities/external-profile.entity";
 import {
   ChangeRequestStatus,
@@ -15,6 +15,12 @@ export class ProfileResponseDto {
   companyName: string;
   companyType: string;
   nationality: string | null;
+  /**
+   * The company trades as a co-operative: it has a TIN but no business licence,
+   * so the company step collects the registration by hand instead of fetching
+   * it from eTrade.
+   */
+  cooperative: boolean;
   companyLocation: string;
   companyAddress: string | null;
   tinNumber: string;
@@ -86,6 +92,7 @@ export class ProfileResponseDto {
     this.companyName = company.name;
     this.companyType = company.type;
     this.nationality = company.nationality ?? null;
+    this.cooperative = isCooperative(company);
     this.companyProfiles =
       company.companyProfiles?.map((p) => new ResponseCompanyProfileDto(p)) ??
       [];
diff --git a/apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts
index b78925285..e75182889 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts
@@ -3,6 +3,7 @@ import {
   CompanyType,
   CompanyStatus,
   CompanyNationality,
+  isCooperative,
 } from '../entities/company.entity';
 import {
   CompanyProfile,
@@ -55,6 +56,12 @@ export class ResponseCompanyDto {
   type: CompanyType;
   status: CompanyStatus;
   nationality?: CompanyNationality | null;
+  /**
+   * The company trades as a co-operative: no business licence, so its
+   * registration was typed rather than fetched from eTrade and there is no
+   * eTrade manager to check the owner against.
+   */
+  cooperative: boolean;
   tin: string;
   vatNumber?: string | null;
   fanNumber?: string | null;
@@ -110,6 +117,7 @@ export class ResponseCompanyDto {
     this.type = company.type;
     this.status = company.status;
     this.nationality = company.nationality ?? null;
+    this.cooperative = isCooperative(company);
     this.tin = company.tin;
     this.vatNumber = company.vatNumber;
     this.fanNumber = company.fanNumber;
diff --git a/apps/edr-freight-api/src/modules/companies/dto/start-onboarding.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/start-onboarding.dto.ts
index 7687faab1..91fcb44a1 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/start-onboarding.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/start-onboarding.dto.ts
@@ -1,4 +1,10 @@
-import { ArrayMinSize, IsArray, IsEnum, IsOptional } from "class-validator";
+import {
+  ArrayMinSize,
+  IsArray,
+  IsBoolean,
+  IsEnum,
+  IsOptional,
+} from "class-validator";
 import { CompanyNationality, CompanyType } from "../entities/company.entity";
 import { ProfileType } from "../entities/company-profile.entity";
 
@@ -14,4 +20,15 @@ export class StartOnboardingDto {
   @IsOptional()
   @IsEnum(CompanyNationality)
   nationality?: CompanyNationality;
+
+  /**
+   * The company trades as a co-operative: it holds a TIN but no business
+   * licence, so there is no eTrade record to fetch its registration from.
+   * Chosen on the same step as the nationality and the roles, because it
+   * decides all three of what the next step asks for, which documents apply,
+   * and which roles are even available (a co-op cannot freight-forward).
+   */
+  @IsOptional()
+  @IsBoolean()
+  cooperative?: boolean;
 }
diff --git a/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts b/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts
index 2ecfa3deb..54c36bf41 100644
--- a/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts
+++ b/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts
@@ -32,6 +32,25 @@ export enum CompanyNationality {
   Foreign = "foreign",
 }
 
+/**
+ * `attributes` key marking a co-operative union or farm.
+ *
+ * Such a company has a TIN but no business licence, so there is no eTrade record to
+ * look its registration up in — the company name, registered address and the
+ * owner are all typed instead of fetched, and the eTrade authenticity check is
+ * skipped rather than failed. It is a flag rather than a column because
+ * everything it changes is behavioural (which lookup runs, which documents
+ * apply, which roles are offered); nothing queries or joins on it.
+ */
+export const COOPERATIVE_KEY = "cooperative";
+
+/** Is this a co-operative union or farm (a TIN, but no business licence)? */
+export function isCooperative(
+  company: Pick<Company, "attributes"> | null | undefined,
+): boolean {
+  return company?.attributes?.[COOPERATIVE_KEY] === true;
+}
+
 @Entity({ schema: "freight", name: "companies" })
 @Index(["tin"])
 @Index(["type"])
diff --git a/apps/edr-freight-api/src/modules/file-upload-settings/file-upload-settings.service.ts b/apps/edr-freight-api/src/modules/file-upload-settings/file-upload-settings.service.ts
index 9651d4f37..21ddc4c91 100644
--- a/apps/edr-freight-api/src/modules/file-upload-settings/file-upload-settings.service.ts
+++ b/apps/edr-freight-api/src/modules/file-upload-settings/file-upload-settings.service.ts
@@ -17,6 +17,7 @@ import {
 } from "./interfaces/file-upload-settings.repository.interface";
 import {
   COMPANY_ONBOARDING_CODE_PREFIX,
+  COOPERATIVE_ONBOARDING_CODE,
   POA_DELEGATION_FILE_KEY,
   poaDelegationField,
 } from "./poa-delegation.constants";
@@ -56,6 +57,10 @@ export class FileUploadSettingsService {
    */
   private withPoaDelegationField(setting: FileUploadSetting): FileUploadSetting {
     if (!setting.code.startsWith(COMPANY_ONBOARDING_CODE_PREFIX)) return setting;
+    // The co-operative set is merged ON TOP of a nationality set that already
+    // carries the paper; injecting it here too would hand the portal the same
+    // slot twice.
+    if (setting.code === COOPERATIVE_ONBOARDING_CODE) return setting;
     const fields = setting.fields ?? [];
     if (fields.some((f) => f.fileKey === POA_DELEGATION_FILE_KEY)) return setting;
 
diff --git a/apps/edr-freight-api/src/modules/file-upload-settings/poa-delegation.constants.ts b/apps/edr-freight-api/src/modules/file-upload-settings/poa-delegation.constants.ts
index 7f8a34175..e8d593ded 100644
--- a/apps/edr-freight-api/src/modules/file-upload-settings/poa-delegation.constants.ts
+++ b/apps/edr-freight-api/src/modules/file-upload-settings/poa-delegation.constants.ts
@@ -26,6 +26,14 @@ export const POA_DELEGATION_LABEL = "DARS Delegation Paper";
 /** Prefix of the setting codes the field is injected into. */
 export const COMPANY_ONBOARDING_CODE_PREFIX = "company_onboarding_documents_";
 
+/**
+ * The co-operative onboarding set. Unlike the nationality sets it is ADDITIVE —
+ * merged on top of the company's `_ethiopian`/`_foreign` set rather than
+ * replacing it — which is why the delegation paper is not injected into it: the
+ * set it is merged onto already carries one.
+ */
+export const COOPERATIVE_ONBOARDING_CODE = `${COMPANY_ONBOARDING_CODE_PREFIX}cooperative`;
+
 const POA_DELEGATION_HELP =
   "Delegation paper issued by the Documents Authentication and Registration " +
   "Service (DARS) delegating the representative named above. Upload the " +
diff --git a/apps/edr-freight-api/src/modules/stamp-settings/dto/update-stamp-setting.dto.ts b/apps/edr-freight-api/src/modules/stamp-settings/dto/update-stamp-setting.dto.ts
new file mode 100644
index 000000000..96f86bf61
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/stamp-settings/dto/update-stamp-setting.dto.ts
@@ -0,0 +1,9 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsString, MinLength } from "class-validator";
+
+export class UpdateStampSettingDto {
+  @ApiProperty({ description: "Stamp image as a base64 data URL (PNG/JPG)." })
+  @IsString()
+  @MinLength(1)
+  stampImageBase64!: string;
+}
diff --git a/apps/edr-freight-api/src/modules/stamp-settings/entities/stamp-setting.entity.ts b/apps/edr-freight-api/src/modules/stamp-settings/entities/stamp-setting.entity.ts
new file mode 100644
index 000000000..7ab7a0e2c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/stamp-settings/entities/stamp-setting.entity.ts
@@ -0,0 +1,24 @@
+import { BaseEntity } from "@edr/api-common";
+import { Column, Entity, JoinColumn, ManyToOne } from "typeorm";
+
+import { FileRecord } from "../../files/entities/file.entity";
+
+/**
+ * Single-row table holding the one company stamp/seal image stamped onto
+ * generated invoice/receipt PDFs (see InvoiceDocumentService). Mirrors the
+ * exchange_settings single-row pattern — `get()` lazily creates the row, and
+ * there is never more than one.
+ */
+@Entity({ schema: "freight", name: "stamp_settings" })
+export class StampSetting extends BaseEntity {
+  @Column({ name: "stamp_file_id", type: "uuid", nullable: true })
+  stampFileId?: string | null;
+
+  @ManyToOne(() => FileRecord, { nullable: true })
+  @JoinColumn({ name: "stamp_file_id" })
+  stampFile?: FileRecord | null;
+
+  /** IAM user id of the last operator to set/clear the stamp. */
+  @Column({ name: "updated_by_id", type: "uuid", nullable: true })
+  updatedById?: string | null;
+}
diff --git a/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.controller.ts b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.controller.ts
new file mode 100644
index 000000000..f03d55058
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.controller.ts
@@ -0,0 +1,39 @@
+import { Body, Controller, Delete, Get, Put } from "@nestjs/common";
+import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
+import { CurrentUser } from "@edr/api-common";
+import type { TCurrentUser } from "@tria-plc/api-common/modules/auth/types/current-user.type";
+
+import { BookingStaff } from "../../common/booking-guards";
+import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
+import { UpdateStampSettingDto } from "./dto/update-stamp-setting.dto";
+import { StampSettingsService } from "./stamp-settings.service";
+
+@ApiTags("stamp-settings")
+@ApiBearerAuth()
+@Controller("stamp-settings")
+export class StampSettingsController {
+  constructor(private readonly service: StampSettingsService) {}
+
+  @Get()
+  @BookingStaff([FREIGHT_PERMS.settings.invoiceStamp.view, FREIGHT_PERMS.admin])
+  @ApiOperation({ summary: "Current company stamp used on invoice/receipt PDFs" })
+  get() {
+    return this.service.getView();
+  }
+
+  @Put()
+  @BookingStaff([FREIGHT_PERMS.settings.invoiceStamp.manage, FREIGHT_PERMS.admin])
+  @ApiOperation({ summary: "Replace the company stamp" })
+  update(@Body() dto: UpdateStampSettingDto, @CurrentUser() user: TCurrentUser) {
+    return this.service.setStamp(dto.stampImageBase64, user?.id ?? null);
+  }
+
+  @Delete()
+  @BookingStaff([FREIGHT_PERMS.settings.invoiceStamp.manage, FREIGHT_PERMS.admin])
+  @ApiOperation({
+    summary: "Clear the company stamp (invoices fall back to the plain seal)",
+  })
+  clear(@CurrentUser() user: TCurrentUser) {
+    return this.service.clearStamp(user?.id ?? null);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.module.ts b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.module.ts
new file mode 100644
index 000000000..6c9fc3a36
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.module.ts
@@ -0,0 +1,23 @@
+import { Global, Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+
+import { FilesModule } from "../files/files.module";
+import { MinioModule } from "../minio/minio.module";
+import { StampSetting } from "./entities/stamp-setting.entity";
+import { StampSettingsController } from "./stamp-settings.controller";
+import { StampSettingsRepository } from "./stamp-settings.repository";
+import { StampSettingsService } from "./stamp-settings.service";
+
+/**
+ * Global so DocumentsModule (invoice PDF rendering) can inject
+ * {@link StampSettingsService} without pulling in a circular billing/warehouse
+ * dependency — same reasoning as ExchangeSettingsModule.
+ */
+@Global()
+@Module({
+  imports: [TypeOrmModule.forFeature([StampSetting]), FilesModule, MinioModule],
+  controllers: [StampSettingsController],
+  providers: [StampSettingsRepository, StampSettingsService],
+  exports: [StampSettingsService],
+})
+export class StampSettingsModule {}
diff --git a/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.repository.ts b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.repository.ts
new file mode 100644
index 000000000..0ca4cfb68
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.repository.ts
@@ -0,0 +1,21 @@
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+import { BaseRepository } from "@edr/api-common";
+
+import { StampSetting } from "./entities/stamp-setting.entity";
+
+@Injectable()
+export class StampSettingsRepository extends BaseRepository<StampSetting> {
+  constructor(
+    @InjectRepository(StampSetting)
+    repo: Repository<StampSetting>,
+  ) {
+    super(repo);
+  }
+
+  /** The single settings row, with its stamp file joined, or null before first upload. */
+  findSingleton(): Promise<StampSetting | null> {
+    return this.repository.findOne({ where: {}, relations: ["stampFile"] });
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.ts b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.ts
new file mode 100644
index 000000000..01352e133
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.ts
@@ -0,0 +1,154 @@
+import { Injectable, Logger } from "@nestjs/common";
+import { Readable } from "stream";
+import { DataSource } from "typeorm";
+
+import { FilesService } from "../files/files.service";
+import { FileRecord } from "../files/entities/file.entity";
+import { MinioService } from "../minio/minio.service";
+import { StampSettingsRepository } from "./stamp-settings.repository";
+import { StampSetting } from "./entities/stamp-setting.entity";
+
+export interface StampSettingView {
+  stampImageUrl: string | null;
+  updatedById: string | null;
+  updatedAt: Date | null;
+}
+
+/**
+ * Owns the single `stamp_settings` row: the one company stamp/seal image used
+ * on generated invoice/receipt PDFs (see InvoiceDocumentService). Same
+ * single-row shape as ExchangeSettingsService, but the value is an uploaded
+ * image (via FilesService) rather than a scalar.
+ */
+@Injectable()
+export class StampSettingsService {
+  private readonly logger = new Logger(StampSettingsService.name);
+
+  constructor(
+    private readonly repository: StampSettingsRepository,
+    private readonly filesService: FilesService,
+    private readonly minioService: MinioService,
+    private readonly dataSource: DataSource,
+  ) {}
+
+  /** The settings row, created empty on first access. */
+  async get(): Promise<StampSetting> {
+    const existing = await this.repository.findSingleton();
+    if (existing) return existing;
+    return this.repository.create({ stampFileId: null, updatedById: null });
+  }
+
+  /** Current stamp, with the image inlined as a data URL (or null if unset). */
+  async getView(): Promise<StampSettingView> {
+    const setting = await this.get();
+    return {
+      stampImageUrl: await this.inlineImageUrl(setting.stampFile?.url),
+      updatedById: setting.updatedById ?? null,
+      updatedAt: setting.updatedAt ?? null,
+    };
+  }
+
+  /**
+   * The stamp image for embedding into invoice PDFs. Never throws — invoice
+   * generation must succeed even if the stamp lookup fails; callers fall back
+   * to the programmatic seal when this returns null.
+   */
+  async getStampImageUrl(): Promise<string | null> {
+    try {
+      const setting = await this.get();
+      return await this.inlineImageUrl(setting.stampFile?.url);
+    } catch (err) {
+      this.logger.warn(
+        `Could not load company stamp for PDF rendering: ${(err as Error).message}`,
+      );
+      return null;
+    }
+  }
+
+  /** Replace the stamp image, storing it in MinIO via FilesService. */
+  async setStamp(
+    stampImageBase64: string,
+    updatedById?: string | null,
+  ): Promise<StampSettingView> {
+    const current = await this.get();
+    const previousFileId = current.stampFileId ?? null;
+
+    const fileRecord = await this.filesService.upload({
+      resourceId: current.id,
+      resource: "stamp_settings",
+      code: "stamp",
+      file: this.toUploadFile(stampImageBase64),
+      uploadedByUserId: updatedById ?? null,
+    });
+
+    await this.repository.update(current.id, {
+      stampFileId: fileRecord.id,
+      updatedById: updatedById ?? null,
+    });
+
+    if (previousFileId && previousFileId !== fileRecord.id) {
+      await this.dataSource.getRepository(FileRecord).delete(previousFileId);
+    }
+
+    this.logger.log(`Company stamp updated by ${updatedById ?? "unknown user"}`);
+    return this.getView();
+  }
+
+  /** Clear the stamp (invoices fall back to the programmatic seal). */
+  async clearStamp(updatedById?: string | null): Promise<StampSettingView> {
+    const current = await this.get();
+    const previousFileId = current.stampFileId ?? null;
+
+    await this.repository.update(current.id, {
+      stampFileId: null,
+      updatedById: updatedById ?? null,
+    });
+
+    if (previousFileId) {
+      await this.dataSource.getRepository(FileRecord).delete(previousFileId);
+    }
+
+    return this.getView();
+  }
+
+  private toUploadFile(base64: string): Express.Multer.File {
+    const raw = base64.includes(",") ? base64.split(",")[1]! : base64;
+    const buffer = Buffer.from(raw, "base64");
+    return {
+      fieldname: "stamp",
+      originalname: "company-stamp.png",
+      encoding: "7bit",
+      mimetype: "image/png",
+      size: buffer.length,
+      buffer,
+      stream: Readable.from(buffer),
+      destination: "",
+      filename: "",
+      path: "",
+    };
+  }
+
+  private async inlineImageUrl(url?: string | null): Promise<string | null> {
+    if (!url) return null;
+    if (url.startsWith("data:")) return url;
+    try {
+      const objectName = this.minioService.getObjectNameFromUrl(url);
+      const stream = await this.minioService.getFileStream(objectName);
+      const buffer = await this.streamToBuffer(stream);
+      return `data:image/png;base64,${buffer.toString("base64")}`;
+    } catch {
+      return url;
+    }
+  }
+
+  private streamToBuffer(stream: Readable): Promise<Buffer> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      stream.on("data", (chunk: Buffer | string) => {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+      stream.on("error", reject);
+      stream.on("end", () => resolve(Buffer.concat(chunks)));
+    });
+  }
+}
diff --git a/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts b/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
index 512229706..abc4e613c 100644
--- a/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
+++ b/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
@@ -154,6 +154,31 @@ const FOREIGN_ONBOARDING_FIELDS: OnboardingField[] = [
 //   },
 // ];
 
+/**
+ * Extra documents a co-operative union or farm provides, merged on top of its
+ * nationality set. It has a TIN but no business licence, so the papers that
+ * evidence the co-operative itself stand in for the trade licence every other
+ * company uploads.
+ *
+ * Only the registration certificate is seeded, and the set is admin-managed
+ * like every other onboarding set — what these members must actually produce
+ * is a backoffice decision, edited in the file-settings editor.
+ */
+const COOPERATIVE_ONBOARDING_FIELDS: OnboardingField[] = [
+  {
+    fileKey: "cooperative_registration_certificate",
+    fileLabel: "Co-operative Union / Farm Registration Certificate",
+    helpText:
+      "Certificate issued by the co-operative promotion agency that registered the union or farm.",
+    isRequired: true,
+    isMultiple: false,
+    maxFiles: 1,
+    allowedExtensions: DOC_EXTENSIONS,
+    maxSizeMb: 50,
+    displayOrder: 1,
+  },
+];
+
 interface OnboardingDocumentSetting {
   code: string;
   label: string;
@@ -176,6 +201,14 @@ const COMPANY_ONBOARDING_DOCUMENTS: OnboardingDocumentSetting[] = [
     entity: "customer",
     fields: FOREIGN_ONBOARDING_FIELDS,
   },
+  // Additive, not a nationality of its own: a union or farm still uploads
+  // everything its nationality set demands, and these on top.
+  {
+    code: "company_onboarding_documents_cooperative",
+    label: "Co-operative union / farm onboarding documents (additional)",
+    entity: "customer",
+    fields: COOPERATIVE_ONBOARDING_FIELDS,
+  },
   // Legacy per-company-type codes — removed, unused by any resolver or portal
   // lookup (only `company_onboarding_documents_ethiopian`/`_foreign` are live).
   // {
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 06511cb2b..fb9afb5e1 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -1164,6 +1164,26 @@ export const CONFIG_SETTINGS_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:settings:dropdown:manage",
     "Manage dropdown settings",
   ),
+  perm(
+    "b4b00002-0001-4000-8000-000000000001",
+    "edr_freight_app:settings:stamp:view",
+    "View stamp settings",
+  ),
+  perm(
+    "b4b00002-0001-4000-8000-000000000002",
+    "edr_freight_app:settings:stamp:manage",
+    "Manage stamp settings",
+  ),
+  perm(
+    "b4b00003-0001-4000-8000-000000000001",
+    "edr_freight_app:settings:invoice_stamp:view",
+    "View invoice stamp settings",
+  ),
+  perm(
+    "b4b00003-0001-4000-8000-000000000002",
+    "edr_freight_app:settings:invoice_stamp:manage",
+    "Manage invoice stamp settings",
+  ),
   perm(
     "b4c00001-0001-4000-8000-000000000001",
     "edr_freight_app:audit:view",
@@ -1849,6 +1869,16 @@ export const FREIGHT_PERMS = {
       view: "edr_freight_app:settings:dropdown:view",
       manage: "edr_freight_app:settings:dropdown:manage",
     },
+    stamp: {
+      view: "edr_freight_app:settings:stamp:view",
+      manage: "edr_freight_app:settings:stamp:manage",
+    },
+    // Company stamp/seal image stamped onto invoice/receipt PDFs — separate
+    // from `stamp` above, which is the per-employee approval-record teeter.
+    invoiceStamp: {
+      view: "edr_freight_app:settings:invoice_stamp:view",
+      manage: "edr_freight_app:settings:invoice_stamp:manage",
+    },
     exchangeRate: {
       view: "edr_freight_app:settings:exchange_rate:view",
       manage: "edr_freight_app:settings:exchange_rate:manage",
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index ec63fa53c..58b8286f0 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -51,6 +51,8 @@ import { NO_ACCESS_PATH, resolveLandingPath } from "./lib/landing";
 import NoAccessPage from "./pages/NoAccessPage";
 import FileUploadSettingsPage from "./pages/documents/FileUploadSettingsPage";
 import DropdownSettingsPage from "./pages/dropdown_settings/DropdownSettingsPage";
+import StampSettings from "./record-management/components/Settings/uploadTeeterandSingature";
+import InvoiceStampSettingsPage from "./pages/settings/InvoiceStampSettingsPage";
 import ContractTemplatesPage from "./pages/contract_templates/ContractTemplatesPage";
 import PortalContentPage from "./pages/portal_content/PortalContentPage";
 import ContractTemplateEditorPage from "./pages/contract_templates/ContractTemplateEditorPage";
@@ -783,6 +785,24 @@ const App = () => {
             </RequirePermission>
           }
         />
+        <Route
+          path="stamp-settings"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.settings.stamp.view}>
+              <StampSettings />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="invoice-stamp-settings"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.settings.invoiceStamp.view}
+            >
+              <InvoiceStampSettingsPage />
+            </RequirePermission>
+          }
+        />
         <Route
           path="audit-logs"
           element={
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 83e80d11e..1b523c8c3 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -485,6 +485,18 @@ export const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[]
         icon: <Settings />,
         permission: FREIGHT_PERMS.settings.dropdown.view,
       },
+      {
+        label: "Stamp settings",
+        href: "/dashboard/stamp-settings",
+        icon: <FileSignature />,
+        permission: FREIGHT_PERMS.settings.stamp.view,
+      },
+      {
+        label: "Invoice stamp",
+        href: "/dashboard/invoice-stamp-settings",
+        icon: <Receipt />,
+        permission: FREIGHT_PERMS.settings.invoiceStamp.view,
+      },
       {
         label: "Contract templates",
         href: "/dashboard/contract-templates",
diff --git a/apps/edr-freight-web/backoffice/src/hooks/useStampSettings.ts b/apps/edr-freight-web/backoffice/src/hooks/useStampSettings.ts
new file mode 100644
index 000000000..9d1594602
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/hooks/useStampSettings.ts
@@ -0,0 +1,45 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useTranslation } from "react-i18next";
+import { toast } from "sonner";
+
+import { stampSettingsService } from "@/services/stampSettings.service";
+import { useErrorHandler } from "@/shared/hooks/useErrorHandler";
+
+const QUERY_KEY = ["stampSettings"];
+
+export const useStampSettingsQuery = () =>
+  useQuery({
+    queryKey: QUERY_KEY,
+    queryFn: () => stampSettingsService.get(),
+  });
+
+export const useSetStamp = () => {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+  const { handleError } = useErrorHandler(t);
+
+  return useMutation({
+    mutationFn: (stampImageBase64: string) =>
+      stampSettingsService.set(stampImageBase64),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: QUERY_KEY });
+      toast.success(t("stampSettings.updated", "Company stamp updated"));
+    },
+    onError: handleError,
+  });
+};
+
+export const useClearStamp = () => {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+  const { handleError } = useErrorHandler(t);
+
+  return useMutation({
+    mutationFn: () => stampSettingsService.clear(),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: QUERY_KEY });
+      toast.success(t("stampSettings.cleared", "Company stamp removed"));
+    },
+    onError: handleError,
+  });
+};
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index 09790091d..932604ce3 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -315,6 +315,16 @@ export const FREIGHT_PERMS = {
       view: "edr_freight_app:settings:dropdown:view",
       manage: "edr_freight_app:settings:dropdown:manage",
     },
+    stamp: {
+      view: "edr_freight_app:settings:stamp:view",
+      manage: "edr_freight_app:settings:stamp:manage",
+    },
+    // Company stamp/seal image stamped onto invoice/receipt PDFs — separate
+    // from `stamp` above, which is the per-employee approval-record teeter.
+    invoiceStamp: {
+      view: "edr_freight_app:settings:invoice_stamp:view",
+      manage: "edr_freight_app:settings:invoice_stamp:manage",
+    },
     exchangeRate: {
       view: "edr_freight_app:settings:exchange_rate:view",
       manage: "edr_freight_app:settings:exchange_rate:manage",
diff --git a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
index f197e1952..a6367786a 100644
--- a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
@@ -822,6 +822,16 @@ export default function CustomerDetailPage() {
                         : undefined
                     }
                   />
+                  {/* Why this company's registration was typed rather than
+                      fetched, and why it carries no business licence. */}
+                  <InfoField
+                    label="Registration"
+                    value={
+                      company.cooperative
+                        ? "Co-operative union / farm (no trade licence)"
+                        : "eTrade trade licence"
+                    }
+                  />
                   <InfoField label="Address" value={company.address} />
                   <InfoField label="Website" value={company.website} />
                   <InfoField label="Email" value={company.email} />
@@ -945,6 +955,11 @@ export default function CustomerDetailPage() {
                   >
                     Matches the eTrade licence
                   </Badge>
+                ) : company.cooperative ? (
+                  <Text size="xs" c="dimmed">
+                    A co-operative union or farm holds no trade licence, so
+                    there is no eTrade record to check the owner against.
+                  </Text>
                 ) : (
                   <Text size="xs" c="dimmed">
                     No eTrade manager name on file to compare against.
diff --git a/apps/edr-freight-web/backoffice/src/pages/settings/InvoiceStampSettingsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/settings/InvoiceStampSettingsPage.tsx
new file mode 100644
index 000000000..407218d70
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/settings/InvoiceStampSettingsPage.tsx
@@ -0,0 +1,88 @@
+import { useEffect, useState } from "react";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/shared/common/ui/card";
+import { Button } from "@/shared/common/ui/button";
+import { Save, Trash2 } from "lucide-react";
+
+import { StampUpload } from "@/components/contracts/StampUpload";
+import {
+  useClearStamp,
+  useSetStamp,
+  useStampSettingsQuery,
+} from "@/hooks/useStampSettings";
+
+/**
+ * The one company stamp/seal stamped onto every generated invoice/receipt
+ * PDF (InvoiceDocumentService). Single global image — no per-employee choice.
+ */
+export default function InvoiceStampSettingsPage() {
+  const { data, isLoading } = useStampSettingsQuery();
+  const setStamp = useSetStamp();
+  const clearStamp = useClearStamp();
+  const [draft, setDraft] = useState<string | null>(null);
+
+  useEffect(() => {
+    setDraft(null);
+  }, [data?.stampImageUrl]);
+
+  const value = draft !== null ? draft : (data?.stampImageUrl ?? null);
+  const dirty = draft !== null && draft !== data?.stampImageUrl;
+
+  const handleSave = async () => {
+    if (!draft) return;
+    await setStamp.mutateAsync(draft);
+  };
+
+  const handleClear = async () => {
+    if (!data?.stampImageUrl) return;
+    await clearStamp.mutateAsync();
+  };
+
+  return (
+    <div className="p-4 w-full max-w-screen-sm mx-auto">
+      <Card className="shadow-lg border-gray-200 dark:border-gray-700">
+        <CardHeader>
+          <CardTitle>Invoice stamp</CardTitle>
+          <CardDescription>
+            Stamped onto every generated invoice and receipt PDF. Replacing it
+            here changes it everywhere at once — there is no per-invoice or
+            per-user choice.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <StampUpload
+            value={isLoading ? null : value}
+            onChange={setDraft}
+            label="Company stamp"
+            description="Shown on every invoice/receipt PDF in place of the plain seal."
+          />
+
+          <div className="flex items-center gap-2">
+            <Button
+              onClick={handleSave}
+              disabled={!dirty || setStamp.isPending}
+            >
+              <Save className="mr-2 h-4 w-4" />
+              Save
+            </Button>
+            {data?.stampImageUrl && !dirty && (
+              <Button
+                variant="outline"
+                onClick={handleClear}
+                disabled={clearStamp.isPending}
+              >
+                <Trash2 className="mr-2 h-4 w-4" />
+                Remove
+              </Button>
+            )}
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/record-management/components/Settings/uploadTeeterandSingature.tsx b/apps/edr-freight-web/backoffice/src/record-management/components/Settings/uploadTeeterandSingature.tsx
index 3035d58c7..a6855f540 100644
--- a/apps/edr-freight-web/backoffice/src/record-management/components/Settings/uploadTeeterandSingature.tsx
+++ b/apps/edr-freight-web/backoffice/src/record-management/components/Settings/uploadTeeterandSingature.tsx
@@ -609,10 +609,18 @@ const UploadTeeterAndSignature = () => {
           )}
         </TabsContent>
 
-        {/* Teeter Tab */}
+        {/* Teeter Tab — single active stamp only: remove the current one to upload a replacement. */}
         <TabsContent value="teeter" className="p-4 space-y-6">
           {teeters.length > 0 && (
             <div className="space-y-6">
+              {teeters.length > 1 && (
+                <p className="rounded border border-amber-200 bg-amber-50 p-2 text-sm text-amber-700 dark:border-amber-900 dark:bg-amber-950 dark:text-amber-300">
+                  {t(
+                    "signatureUpload.multipleStampsWarning",
+                    "Only one stamp is allowed. Remove the extras below to keep a single active stamp.",
+                  )}
+                </p>
+              )}
               {teeters.map(({ id, url }) => (
                 <div key={id} className="space-y-3">
                   <p className="text-sm text-gray-600 dark:text-gray-300">
@@ -635,6 +643,7 @@ const UploadTeeterAndSignature = () => {
             </div>
           )}
 
+          {teeters.length === 0 && (
           <div className="border-2 border-dashed border-primary-300 dark:border-primary-600 rounded-lg p-6 text-center space-y-4">
             {!stampBlocks && !showLanguagePicker && (
               <Button
@@ -792,6 +801,7 @@ const UploadTeeterAndSignature = () => {
               </>
             )}
           </div>
+          )}
         </TabsContent>
       </Tabs>
 
diff --git a/apps/edr-freight-web/backoffice/src/services/stampSettings.service.ts b/apps/edr-freight-web/backoffice/src/services/stampSettings.service.ts
new file mode 100644
index 000000000..c88d4e08b
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/services/stampSettings.service.ts
@@ -0,0 +1,31 @@
+import { api as client } from "../auth/http";
+import { unwrap } from "@/utils/endpoint";
+import type { ApiResponse } from "@/types/apiResponse";
+
+const BASE = "/stamp-settings";
+
+/** Company stamp/seal used on generated invoice/receipt PDFs. */
+export interface StampSettings {
+  stampImageUrl: string | null;
+  updatedById: string | null;
+  updatedAt: string | null;
+}
+
+export const stampSettingsService = {
+  get: async (): Promise<StampSettings> => {
+    const response = await client.get<ApiResponse<StampSettings>>(BASE);
+    return unwrap(response.data);
+  },
+
+  set: async (stampImageBase64: string): Promise<StampSettings> => {
+    const response = await client.put<ApiResponse<StampSettings>>(BASE, {
+      stampImageBase64,
+    });
+    return unwrap(response.data);
+  },
+
+  clear: async (): Promise<StampSettings> => {
+    const response = await client.delete<ApiResponse<StampSettings>>(BASE);
+    return unwrap(response.data);
+  },
+};
diff --git a/apps/edr-freight-web/backoffice/src/types/customer.ts b/apps/edr-freight-web/backoffice/src/types/customer.ts
index 4fd920916..87a71bf6e 100644
--- a/apps/edr-freight-web/backoffice/src/types/customer.ts
+++ b/apps/edr-freight-web/backoffice/src/types/customer.ts
@@ -222,6 +222,12 @@ export interface Company {
   fanNumber?: string | null;
   country: string;
   nationality?: CompanyNationality | null;
+  /**
+   * A co-operative union or farm: a TIN but no trade licence, so its
+   * registration was typed rather than fetched from eTrade, there is no eTrade
+   * manager to check the owner against, and it holds no freight-forwarder role.
+   */
+  cooperative?: boolean;
   address?: string | null;
   phone?: string | null;
   email?: string | null;
diff --git a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
index b9fdca622..6d75e502f 100644
--- a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
+++ b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
@@ -1,6 +1,7 @@
 import {
   Box,
   Button,
+  Checkbox,
   Group,
   Modal,
   ScrollArea,
@@ -164,6 +165,15 @@ export default function OnboardingWizardDialog({
   const [roles, setRoles] = useState<string[]>(
     existingProfiles.map((p) => p.type),
   );
+  const [cooperative, setCooperative] = useState<boolean>(
+    company?.company?.attributes?.cooperative === true,
+  );
+  // Ticking the box drops a role the company can no longer hold, rather than
+  // letting Continue fail on a selection the API refuses.
+  const handleCooperativeChange = useCallback((checked: boolean) => {
+    setCooperative(checked);
+    if (checked) setRoles((prev) => prev.filter((r) => r !== "freight_forwarder"));
+  }, []);
   const [documentFiles, setDocumentFiles] = useState<
     Record<string, File | File[] | null>
   >({});
@@ -214,6 +224,7 @@ export default function OnboardingWizardDialog({
       companyType: string;
       roles: ProfileTypeValue[];
       nationality?: CompanyNationality;
+      cooperative?: boolean;
     }) => api.companies.startOnboarding.call(vars),
     onSuccess: async () => {
       // Nationality drives the server-resolved identity requirements (Fayda vs
@@ -296,6 +307,7 @@ export default function OnboardingWizardDialog({
     resumedRef.current = true;
     setRoles(existingProfiles.map((p) => p.type));
     setNationality(savedNationality);
+    setCooperative(company?.company?.attributes?.cooperative === true);
     // Resume into the form only when profiles exist; otherwise send the user to
     // role selection so the missing operational profiles get created.
     setPhase(hasOperationalProfiles ? "form" : "nationality-role");
@@ -310,8 +322,9 @@ export default function OnboardingWizardDialog({
       companyType: companyTypeForRoles(roles),
       roles: roles as ProfileTypeValue[],
       nationality: nationality ?? undefined,
+      cooperative,
     });
-  }, [roles, nationality, startMutation]);
+  }, [roles, nationality, cooperative, startMutation]);
 
   // Back from the form's first step returns to nationality/role selection.
   // Safe to re-enter: startOnboarding is idempotent — it reuses the existing
@@ -463,6 +476,15 @@ export default function OnboardingWizardDialog({
     // mandatory for an Ethiopian company; a foreign one may instead type a
     // passport number for the same person.
     identity: requirementsQuery.data?.identity,
+    // Server-confirmed, not the local checkbox: the flag is only real once
+    // startOnboarding has persisted it, and the form's whole company step
+    // branches on it.
+    cooperative: requirementsQuery.data?.cooperative ?? cooperative,
+    extraDocumentSettingCode:
+      requirementsQuery.data?.cooperativeDocumentSettingCode ?? null,
+    // A freight forwarder cannot answer the power-of-attorney question — the
+    // API forces "yes" — so the step offers no way to change it.
+    declarationLocked: requirementsQuery.data?.poa?.locked ?? false,
     onIdentityChange: () => {
       void profileQuery.refetch();
       void requirementsQuery.refetch();
@@ -530,6 +552,16 @@ export default function OnboardingWizardDialog({
                 onChange={setNationality}
                 embedded
               />
+              {/* A co-operative union or farm registers on a TIN alone. It
+                  changes what the next step asks for (typed registration, no
+                  eTrade lookup), which documents apply, and which roles are on
+                  offer — so it is answered here, alongside the other two. */}
+              <Checkbox
+                checked={cooperative}
+                onChange={(e) => handleCooperativeChange(e.currentTarget.checked)}
+                label="We're a co-operative union or farm"
+                description="For members with a TIN but no business licence. You'll type your registration details instead of us pulling them from eTrade, and upload your co-operative papers in place of a trade licence."
+              />
               <Text fw={600} size="lg" c="edr-text">
                 What does your company do?(multiple)
               </Text>
@@ -537,6 +569,9 @@ export default function OnboardingWizardDialog({
                 value={roles}
                 onChange={setRoles}
                 embedded
+                // Forwarding is licensed work — a co-op holds no licence, so
+                // the role is not offered rather than refused later.
+                excludeTypes={cooperative ? ["freight_forwarder"] : undefined}
               />
               {startError && (
                 <Text size="sm" c="red">
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 93ab3cfc2..f4a788437 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
@@ -36,7 +36,9 @@ import type {
 import CompanyInfoStep from "./companyProfileForm/steps/CompanyInfoStep";
 import OwnerStep from "./companyProfileForm/steps/OwnerStep";
 import ContactStep from "./companyProfileForm/steps/ContactStep";
-import RepresentationStep from "./companyProfileForm/steps/RepresentationStep";
+import RepresentationStep, {
+  type IdentityMethod,
+} from "./companyProfileForm/steps/RepresentationStep";
 import DocumentsStep from "./companyProfileForm/steps/DocumentsStep";
 
 export default function CompanyProfileForm({
@@ -60,6 +62,9 @@ export default function CompanyProfileForm({
   onUploadDocuments,
   identity: rawIdentity,
   onIdentityChange,
+  cooperative = false,
+  declarationLocked = false,
+  extraDocumentSettingCode,
 }: {
   documentSettingCode: string;
   documentFiles?: Record<string, File | File[] | null>;
@@ -105,6 +110,20 @@ export default function CompanyProfileForm({
    * a freshly booted app, so it has nothing to notify.
    */
   onIdentityChange?: () => void;
+  /**
+   * The company trades as a co-operative: a TIN but no business licence, so the
+   * eTrade lookup is replaced by typed registration details, the per-role
+   * licence upload is not owed, and its own document set applies on top of the
+   * nationality one.
+   */
+  cooperative?: boolean;
+  /**
+   * The company operates as a freight forwarder, so the power-of-attorney
+   * answer is forced to "yes" and cannot be changed here.
+   */
+  declarationLocked?: boolean;
+  /** Additional document set merged in (the co-operative one), if any. */
+  extraDocumentSettingCode?: string | null;
 }) {
   // A Fayda claim carries the phone as the national registry holds it, which is
   // often a local number the form's E.164 validation (and the API's
@@ -168,12 +187,36 @@ export default function CompanyProfileForm({
   const documentFiles = controlledFiles ?? internalFiles;
   const setDocumentFiles = onDocumentFilesChange ?? setInternalFiles;
 
-  const { data: uploadSetting, isLoading: loadingDocuments } = useQuery(
+  const { data: nationalitySetting, isLoading: loadingDocuments } = useQuery(
     api.fileUploadSettings.getByCode.queryOptions({
       input: { code: documentSettingCode },
       refetchOnMount: false,
     }),
   );
+  // A co-operative's own documents come as a second, additive set — it uploads
+  // everything its nationality demands, plus the papers standing in for the
+  // business licence it does not hold. The API merges the same two sets when it
+  // decides what is outstanding.
+  const { data: extraSetting } = useQuery(
+    api.fileUploadSettings.getByCode.queryOptions({
+      input: { code: extraDocumentSettingCode ?? "" },
+      enabled: Boolean(extraDocumentSettingCode),
+      refetchOnMount: false,
+    }),
+  );
+  const uploadSetting = useMemo(() => {
+    if (!nationalitySetting) return nationalitySetting;
+    if (!extraSetting?.fields?.length) return nationalitySetting;
+    // Nationality wins a fileKey collision, so a slot is never rendered twice.
+    const seen = new Set(nationalitySetting.fields.map((f) => f.fileKey));
+    return {
+      ...nationalitySetting,
+      fields: [
+        ...nationalitySetting.fields,
+        ...extraSetting.fields.filter((f) => !seen.has(f.fileKey)),
+      ],
+    };
+  }, [nationalitySetting, extraSetting]);
 
   // Which fields the current step renders an input for and therefore requires.
   // Filled in further down (it depends on values this form owns), and read at
@@ -388,30 +431,58 @@ export default function CompanyProfileForm({
   };
 
   /**
-   * What no source supplied, per person.
+   * Which fields a verification owns, per person.
    *
    * A Fayda verification owns the fields its claims filled — the API refuses to
    * let those be overwritten — but its email, phone and address claims are
-   * optional and routinely come back empty. eTrade fills the owner's name and
-   * phone, and nothing at all fills an email.
+   * optional and routinely come back empty. Everything it did NOT fill stays
+   * the customer's: an editable input, prefilled from eTrade or from what was
+   * saved earlier, and required precisely because there is an input for it.
    *
-   * So "what still has to be asked" varies per company. Computed here, once,
-   * and handed to both the step (which renders an input per gap) and the schema
-   * (which requires exactly those): **a field is required if and only if there
-   * is an input on screen to fix it in.**
+   * Keyed off `verified`, deliberately, not off "does a value exist". A value
+   * exists the moment eTrade prefills the owner or the customer types one and
+   * the step saves — so a presence test turned the input they had just filled
+   * into a read-only badge on the way back through the wizard, and dropped the
+   * field out of `requiredKeys` at the same time. Only a verification locks.
    */
-  const ownerGaps = {
-    name: !identity?.owner.name?.trim(),
-    email: !identity?.owner.email?.trim(),
-    phone: !identity?.owner.phone?.trim(),
+  const ownerVerified = identity?.owner.verified ?? false;
+  const poaVerified = identity?.poa.verified ?? false;
+  const ownerLocked = {
+    name: ownerVerified && Boolean(identity?.owner.name?.trim()),
+    email: ownerVerified && Boolean(identity?.owner.email?.trim()),
+    phone: ownerVerified && Boolean(identity?.owner.phone?.trim()),
   };
-  const poaGaps = {
-    name: !identity?.poa.name?.trim(),
-    email: !identity?.poa.email?.trim(),
-    phone: !identity?.poa.phone?.trim(),
-    address: !identity?.poa.address?.trim(),
+  const poaLocked = {
+    name: poaVerified && Boolean(identity?.poa.name?.trim()),
+    email: poaVerified && Boolean(identity?.poa.email?.trim()),
+    phone: poaVerified && Boolean(identity?.poa.phone?.trim()),
+    address: poaVerified && Boolean(identity?.poa.address?.trim()),
   };
 
+  /**
+   * How a foreign company chose to prove its subject: Fayda, or a passport.
+   *
+   * An either/or rather than a fallback, so nothing is asked until one side is
+   * picked. Seeded from what already happened — a completed verification or a
+   * saved passport number is itself the answer — and only then held locally,
+   * because the choice is a UI fork with nothing to persist: what the API
+   * stores is the proof, not the route taken to it.
+   */
+  const [identityMethod, setIdentityMethod] = useState<IdentityMethod | null>(
+    null,
+  );
+  const passportSaved = Boolean(
+    identity?.subject === "poa"
+      ? identity?.poa.passportNumber?.trim()
+      : identity?.owner.passportNumber?.trim(),
+  );
+  const subjectVerified = identity?.subject === "poa" ? poaVerified : ownerVerified;
+  const effectiveMethod: IdentityMethod | null = !identity?.passportAccepted
+    ? "fayda" // An Ethiopian company has no choice to make.
+    : subjectVerified
+      ? "fayda"
+      : (identityMethod ?? (passportSaved ? "passport" : null));
+
   // The owner's name from whichever source established them — powers the
   // contact step's "same as owner" card.
   const ownerName = firstPresent(identity?.owner.name, watch("ownerName"));
@@ -494,9 +565,12 @@ export default function CompanyProfileForm({
     return errs;
   };
 
-  // Every role needs at least one license file (existing or newly selected).
+  // Every role needs at least one license file (existing or newly selected) —
+  // except a co-operative's, which holds no business licence at all. Its own
+  // document set is what stands in, and the API lifts the same requirement.
   const validateLicenses = (): Record<string, string> => {
     const errs: Record<string, string> = {};
+    if (cooperative) return errs;
     for (const p of roleProfiles ?? []) {
       const hasNew = (licenseFiles?.[p.id]?.length ?? 0) > 0;
       const hasExisting = p.existingFiles.length > 0;
@@ -549,7 +623,10 @@ export default function CompanyProfileForm({
   const hasRegistrationDetails = registration.some((v) => v && v.trim());
   // A previously-saved (rehydrated) TIN counts as verified without a refetch —
   // the registration fields being populated at all is proof it passed before.
-  const tinVerified = tinStatus === "verified" || hasRegistrationDetails;
+  // A co-operative never runs the lookup, so there is nothing to be verified
+  // against; its TIN is validated by the schema like any other typed field.
+  const tinVerified =
+    cooperative || tinStatus === "verified" || hasRegistrationDetails;
 
   // Single source of truth for step sequence — navigation, labels and the
   // progress bar all derive from this so adding/removing a step is one edit.
@@ -589,18 +666,29 @@ export default function CompanyProfileForm({
       Boolean(watch(passportField)?.trim()));
 
   const requiredKeys: (keyof FormData)[] = [];
-  if (step === "owner") {
+  if (step === "company" && cooperative) {
+    // A co-operative has no eTrade record, so the fields every other company
+    // gets read-only from the licence are typed here — and are therefore
+    // required here. House number stays optional: plenty of addresses have none.
+    requiredKeys.push("companyName", "region", "zone", "woreda", "kebele");
+  } else if (step === "owner") {
     // All three are required by the API (`REQUIRED_COMPANY_INFO`), and an input
-    // is rendered for each one a Fayda claim did not already own.
-    if (ownerGaps.name) requiredKeys.push("ownerName");
-    if (ownerGaps.email) requiredKeys.push("ownerEmail");
-    if (ownerGaps.phone) requiredKeys.push("ownerPhone");
-  } else if (step === "representation" && identity?.poaDeclared === "yes") {
-    // Only once a representative is actually declared: a company that answered
-    // "no" has no representative to describe.
-    if (poaGaps.name) requiredKeys.push("poaName");
-    if (poaGaps.email) requiredKeys.push("poaEmail");
-    if (poaGaps.phone) requiredKeys.push("poaPhone");
+    // is rendered for each one a Fayda verification does not own.
+    if (!ownerLocked.name) requiredKeys.push("ownerName");
+    if (!ownerLocked.email) requiredKeys.push("ownerEmail");
+    if (!ownerLocked.phone) requiredKeys.push("ownerPhone");
+  } else if (
+    step === "representation" &&
+    identity?.poaDeclared === "yes" &&
+    // The details are only on screen once the person is established — before
+    // that the step is still asking how to prove them, and requiring a name
+    // with no input rendered is the dead Continue button this rule exists to
+    // prevent.
+    (poaVerified || effectiveMethod === "passport")
+  ) {
+    if (!poaLocked.name) requiredKeys.push("poaName");
+    if (!poaLocked.email) requiredKeys.push("poaEmail");
+    if (!poaLocked.phone) requiredKeys.push("poaPhone");
   }
   requiredKeysRef.current = requiredKeys;
 
@@ -695,6 +783,8 @@ export default function CompanyProfileForm({
     }
     // The TIN must resolve to a real eTrade record before anything else on
     // this step is even worth validating — gates here rather than through zod.
+    // A co-operative is exempt: it has no licence for eTrade to hold, so
+    // `tinVerified` is true for it and only the duplicate-TIN check applies.
     if (step === "company" && tinStatus === "taken") {
       setSaveError(
         "This TIN is already registered to another company account.",
@@ -793,6 +883,7 @@ export default function CompanyProfileForm({
               tinStatus={tinStatus}
               tinVerified={tinVerified}
               hasRegistrationDetails={hasRegistrationDetails}
+              cooperative={cooperative}
               onETradeDataLoaded={handleETradeDataLoaded}
               onETradeStatusChange={setTinStatus}
               onETradeReset={handleETradeReset}
@@ -804,7 +895,8 @@ export default function CompanyProfileForm({
               form={form}
               identity={identity}
               etradeOwner={etradeOwner}
-              gaps={ownerGaps}
+              locked={ownerLocked}
+              cooperative={cooperative}
             />
           )}
 
@@ -814,7 +906,10 @@ export default function CompanyProfileForm({
               identity={identity}
               onDeclare={handleDeclare}
               declarePending={declarePending}
-              gaps={poaGaps}
+              declarationLocked={declarationLocked}
+              locked={poaLocked}
+              method={effectiveMethod}
+              onMethodChange={setIdentityMethod}
               poaDocumentSetting={poaDocumentSetting}
               documentFiles={documentFiles}
               uploadedDocumentKeys={uploadedDocumentKeys}
@@ -840,7 +935,10 @@ export default function CompanyProfileForm({
               uploadedDocumentKeys={uploadedDocumentKeys}
               documentFieldErrors={documentFieldErrors}
               onDocumentFilesChange={handleDocumentFilesChange}
-              roleProfiles={roleProfiles}
+              // A co-operative union or farm holds no business licence, so the
+              // per-role upload cards are not shown at all — offering a slot
+              // nothing can fill reads as an unfinishable step.
+              roleProfiles={cooperative ? [] : roleProfiles}
               licenseFiles={licenseFiles}
               licenseFieldErrors={licenseFieldErrors}
               onLicenseFilesChange={handleLicenseFilesChange}
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
index ebff24687..4b5b7cdb7 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
@@ -65,18 +65,16 @@ describe("VAT number", () => {
     ).toBeUndefined();
   });
 
-  it("rejects twelve digits", () => {
-    expect(errorFor(values({ vatNumber: "001234567890" }), "vatNumber")).toBe(
-      "VAT number must be 10 or 11 digits",
-    );
-  });
-
-  // `.length(10)` used to pass this, so a ten-letter string reached the API.
-  it("rejects ten non-digits", () => {
-    expect(errorFor(values({ vatNumber: "ABCDEFGHIJ" }), "vatNumber")).toBe(
-      "VAT number must be 10 or 11 digits",
-    );
-  });
+  // No shape rule any more: a foreign tax authority's VAT number carries
+  // letters and dashes, and a co-operative union's registration numbering
+  // follows the trade-licence pattern not at all. Length and alphabet are not
+  // ours to police — only presence is.
+  it.each(["001234567890", "GB123456789", "ET-2024/0091"])(
+    "accepts %s",
+    (vat) => {
+      expect(errorFor(values({ vatNumber: vat }), "vatNumber")).toBeUndefined();
+    },
+  );
 
   it("rejects blank", () => {
     expect(errorFor(values({ vatNumber: "" }), "vatNumber")).toBe(
@@ -104,24 +102,44 @@ describe("stepFields", () => {
   // The regression this whole change exists to prevent: a step must not gate on
   // a field it renders no input for, or Continue fails with the error attached
   // to nothing on screen.
-  it("never gates the company step on a derived or read-only field", () => {
-    const unreachable = [
-      "etradePhone",
+  //
+  // Listing a field on a step is no longer the gate — `requiredKeys` is. The
+  // registration fields appear on the company step because a co-operative union
+  // or farm types them, and a licensed company gets them read-only from eTrade;
+  // the base schema must accept them blank either way.
+  it("never gates the company step on a field with no input", () => {
+    const derived = ["etradePhone", "licenceNumber", "statusDescription"];
+    expect(stepFields.company.filter((f) => derived.includes(f))).toEqual([]);
+  });
+
+  it("leaves the registration fields optional in the base schema", () => {
+    for (const field of ["companyName", "region", "zone", "woreda", "kebele"] as const) {
+      expect(errorFor(values({ [field]: "" }), field)).toBeUndefined();
+    }
+  });
+
+  it("requires the registration fields once a co-operative types them", () => {
+    const parsed = buildOnboardingSchema([
       "companyName",
-      "licenceNumber",
-      "statusDescription",
-      "dateRegistered",
-      "renewedFrom",
-      "renewalDate",
-      "renewedTo",
       "region",
       "zone",
       "woreda",
       "kebele",
-      "houseNo",
-    ];
-    expect(stepFields.company.filter((f) => unreachable.includes(f))).toEqual(
-      [],
+    ]).safeParse(
+      values({ companyName: "", region: "", zone: "", woreda: "", kebele: "" }),
+    );
+    expect(parsed.success).toBe(false);
+    const paths = parsed.success
+      ? []
+      : parsed.error.issues.map((i) => String(i.path[0]));
+    expect(paths).toEqual(
+      expect.arrayContaining([
+        "companyName",
+        "region",
+        "zone",
+        "woreda",
+        "kebele",
+      ]),
     );
   });
 });
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 770e565b8..d642e48c7 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
@@ -22,11 +22,11 @@ export const onboardingSchema = z.object({
   // can diverge without the backend's eTrade-authenticity check misfiring.
   etradePhone: z.string().optional(),
   tinNumber: z.string().regex(/^\d{10}$/, "TIN must be exactly 10 digits"),
-  // `.length(10)` alone accepted "ABCDEFGHIJ" — the check has to be on digits.
-  vatNumber: z
-    .string()
-    .min(1, "VAT number is required")
-    .regex(/^\d{10,11}$/, "VAT number must be 10 or 11 digits"),
+  // Required, but no shape check. Ethiopian VAT numbers are usually 10 or 11
+  // digits; a foreign company's is whatever its own tax authority issues, and a
+  // co-operative's registration numbering follows neither. A format rule here
+  // only ever rejected valid numbers we had no business judging.
+  vatNumber: z.string().min(1, "VAT number is required"),
   // Passport numbers — the alternative identity credential for a foreign
   // company (Fayda is an Ethiopian national ID). Only the one belonging to the
   // declared identity subject is ever asked for, and only when that person has
@@ -40,10 +40,15 @@ export const onboardingSchema = z.object({
   renewedFrom: z.string().optional(),
   renewalDate: z.string().optional(),
   renewedTo: z.string().optional(),
-  // The registered address comes from eTrade and nowhere else — the form
-  // renders these read-only, so requiring them would be a Continue button that
-  // fails on a field with no input to fix it. A gap in eTrade's own data stays
-  // a gap rather than becoming a customer-typed claim wearing eTrade's badge.
+  // The registered address normally comes from eTrade and nowhere else — the
+  // form renders these read-only, so requiring them would be a Continue button
+  // that fails on a field with no input to fix it. A gap in eTrade's own data
+  // stays a gap rather than becoming a customer-typed claim wearing eTrade's
+  // badge.
+  //
+  // A co-operative is the exception: it has no business licence, so there is no
+  // eTrade record at all and these ARE typed. Requiredness follows the same
+  // invariant as everywhere else — it is decided per render, in `requiredKeys`.
   region: z.string().optional(),
   zone: z.string().optional(),
   woreda: z.string().optional(),
@@ -107,6 +112,12 @@ export const POA_DELEGATION_FILE_KEY = "poa_delegation_letter";
  * message has to be built here rather than attached to the base schema.
  */
 const CONDITIONAL_LABELS: Partial<Record<keyof FormData, string>> = {
+  // Typed only by a co-operative — every other company gets these from eTrade.
+  companyName: "Company name",
+  region: "Region",
+  zone: "Zone",
+  woreda: "Woreda",
+  kebele: "Kebele",
   poaName: "Representative's name",
   poaEmail: "Representative's email",
   poaPhone: "Representative's phone",
@@ -184,8 +195,18 @@ export const ETRADE_BUNDLE_FIELDS = [
  */
 export const stepFields: Record<CompanyStep, (keyof FormData)[]> = {
   // Only what this step actually renders an input for. The company name and the
-  // registered address are eTrade's, shown read-only.
-  company: ["tinNumber", "vatNumber"],
+  // registered address are eTrade's, shown read-only — except for a
+  // co-operative, which types them (added per render via `requiredKeys`).
+  company: [
+    "tinNumber",
+    "vatNumber",
+    "companyName",
+    "region",
+    "zone",
+    "woreda",
+    "kebele",
+    "houseNo",
+  ],
   // `REQUIRED_COMPANY_INFO` demands all three server-side, so the step offers
   // an input wherever eTrade and Fayda between them left a gap.
   owner: ["ownerName", "ownerEmail", "ownerPhone", "ownerPassportNumber"],
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
index f57d7c433..5e4ad7f85 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
@@ -1,7 +1,7 @@
-import { Stack, TextInput } from "@mantine/core";
+import { Select, SimpleGrid, Stack, Text, TextInput } from "@mantine/core";
 import type { UseFormReturn } from "react-hook-form";
 
-import type { CompanyRegistrationData } from "@edr/types";
+import { ETHIOPIAN_REGIONS, type CompanyRegistrationData } from "@edr/types";
 import ETradeInfo, {
   type ETradeStatus,
 } from "@/components/onboarding/ETradeInfo";
@@ -16,6 +16,12 @@ export interface CompanyInfoStepProps {
   tinVerified: boolean;
   /** Registration fields are already populated (a lookup passed, now or earlier). */
   hasRegistrationDetails: boolean;
+  /**
+   * The company is a co-operative union or farm: it has a TIN but no business
+   * licence, so eTrade holds no record to look up and the registration is typed
+   * here instead.
+   */
+  cooperative?: boolean;
   onETradeDataLoaded: (data: CompanyRegistrationData) => void;
   onETradeStatusChange: (status: ETradeStatus) => void;
   onETradeReset: () => void;
@@ -26,6 +32,7 @@ export default function CompanyInfoStep({
   tinStatus,
   tinVerified,
   hasRegistrationDetails,
+  cooperative = false,
   onETradeDataLoaded,
   onETradeStatusChange,
   onETradeReset,
@@ -33,6 +40,7 @@ export default function CompanyInfoStep({
   const {
     register,
     watch,
+    setValue,
     formState: { errors },
   } = form;
 
@@ -41,43 +49,112 @@ export default function CompanyInfoStep({
       <StepSection
         index={1}
         title="VAT number"
-        status={
-          (watch("vatNumber")?.length ?? 0) >= 10 && !errors.vatNumber
-            ? "done"
-            : "todo"
-        }
+        status={watch("vatNumber")?.trim() && !errors.vatNumber ? "done" : "todo"}
       >
         <TextInput
           aria-label="VAT Number"
           placeholder="0012345678"
-          maxLength={11}
           error={errors.vatNumber?.message}
           {...register("vatNumber")}
         />
       </StepSection>
 
-      <StepSection
-        index={2}
-        title="Company TIN"
-        subtitle="We'll pull your registration straight from eTrade — nothing to type by hand once it's found."
-        status={
-          tinVerified ? "done" : tinStatus === "taken" ? "blocked" : "todo"
-        }
-      >
-        <ETradeInfo
-          tin={watch("tinNumber")}
-          register={register("tinNumber")}
-          error={errors.tinNumber?.message}
-          onDataLoaded={onETradeDataLoaded}
-          onStatusChange={onETradeStatusChange}
-          onReset={onETradeReset}
-          alreadyVerified={hasRegistrationDetails}
-          selectedLicenceNumber={watch("licenceNumber")}
-        />
-        {tinVerified && (
-          <ETradeCompanyCard tin={watch("tinNumber")} watch={watch} />
-        )}
-      </StepSection>
+      {cooperative ? (
+        <>
+          <StepSection
+            index={2}
+            title="Company TIN"
+            subtitle="A co-operative union or farm has no trade licence for us to look up, so we take the TIN as you give it."
+            status={watch("tinNumber")?.trim() && !errors.tinNumber ? "done" : "todo"}
+          >
+            <TextInput
+              aria-label="Company TIN"
+              placeholder="0012345678"
+              error={errors.tinNumber?.message}
+              {...register("tinNumber")}
+            />
+          </StepSection>
+
+          <StepSection
+            index={3}
+            title="Registration details"
+            subtitle="Everything we'd normally read off an eTrade licence. We need it from you instead."
+            status={
+              watch("companyName")?.trim() && watch("region")?.trim()
+                ? "done"
+                : "todo"
+            }
+          >
+            <Stack gap="md">
+              <TextInput
+                label="Company Name"
+                placeholder="Registered name of the union or farm"
+                error={errors.companyName?.message}
+                {...register("companyName")}
+              />
+              <Text size="sm" c="edr-muted">
+                Registered address
+              </Text>
+              <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+                <Select
+                  label="Region"
+                  placeholder="Select region"
+                  data={[...ETHIOPIAN_REGIONS]}
+                  searchable
+                  value={watch("region") || null}
+                  onChange={(v) =>
+                    setValue("region", v ?? "", { shouldValidate: true })
+                  }
+                  error={errors.region?.message}
+                />
+                <TextInput
+                  label="Zone"
+                  error={errors.zone?.message}
+                  {...register("zone")}
+                />
+                <TextInput
+                  label="Woreda"
+                  error={errors.woreda?.message}
+                  {...register("woreda")}
+                />
+                <TextInput
+                  label="Kebele"
+                  error={errors.kebele?.message}
+                  {...register("kebele")}
+                />
+                <TextInput
+                  label="House No."
+                  error={errors.houseNo?.message}
+                  {...register("houseNo")}
+                />
+              </SimpleGrid>
+            </Stack>
+          </StepSection>
+        </>
+      ) : (
+        <StepSection
+          index={2}
+          title="Company TIN"
+          subtitle="We'll pull your registration straight from eTrade — nothing to type by hand once it's found."
+          status={
+            tinVerified ? "done" : tinStatus === "taken" ? "blocked" : "todo"
+          }
+        >
+          <ETradeInfo
+            tin={watch("tinNumber")}
+            register={register("tinNumber")}
+            error={errors.tinNumber?.message}
+            onDataLoaded={onETradeDataLoaded}
+            onStatusChange={onETradeStatusChange}
+            onReset={onETradeReset}
+            alreadyVerified={hasRegistrationDetails}
+            selectedLicenceNumber={watch("licenceNumber")}
+          />
+          {tinVerified && (
+            <ETradeCompanyCard tin={watch("tinNumber")} watch={watch} />
+          )}
+        </StepSection>
+      )}
     </Stack>
   );
 }
diff --git a/apps/edr-freight-web/portal/src/pages/settings/OnboardingRoleSelect.tsx b/apps/edr-freight-web/portal/src/pages/settings/OnboardingRoleSelect.tsx
index ca4afb9b9..c6e46a507 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/OnboardingRoleSelect.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/OnboardingRoleSelect.tsx
@@ -9,6 +9,11 @@ interface OnboardingRoleSelectProps {
   onChange: (next: string[]) => void;
   /** Render only the option grid — the wizard supplies its own header/card. */
   embedded?: boolean;
+  /**
+   * Roles this company cannot hold, hidden rather than shown-and-refused. A
+   * co-operative has no business licence, so it cannot freight-forward.
+   */
+  excludeTypes?: readonly string[];
 }
 
 /**
@@ -22,8 +27,12 @@ export default function OnboardingRoleSelect({
   value,
   onChange,
   embedded = false,
+  excludeTypes,
 }: OnboardingRoleSelectProps) {
   const selected = new Set(value);
+  const roles = excludeTypes?.length
+    ? CUSTOMER_ROLES.filter((r) => !excludeTypes.includes(r.type))
+    : CUSTOMER_ROLES;
 
   const toggleRole = (type: string) => {
     const next = new Set(value);
@@ -34,7 +43,7 @@ export default function OnboardingRoleSelect({
 
   const grid = (
     <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
-      {CUSTOMER_ROLES.map((role) => (
+      {roles.map((role) => (
         <RoleCard
           key={role.type}
           label={role.label}
diff --git a/apps/edr-freight-web/portal/src/services/api.ts b/apps/edr-freight-web/portal/src/services/api.ts
index 0d0035b87..0cec830c9 100644
--- a/apps/edr-freight-web/portal/src/services/api.ts
+++ b/apps/edr-freight-web/portal/src/services/api.ts
@@ -238,6 +238,8 @@ export const api = {
         companyType: string;
         roles: ProfileTypeValue[];
         nationality?: CompanyNationality;
+        /** No business licence: registration typed, no eTrade lookup, no forwarding. */
+        cooperative?: boolean;
       },
       CompanyInfoResponse
     >("companies", "startOnboarding", companiesService.startOnboarding),
diff --git a/apps/edr-freight-web/portal/src/services/companies.service.ts b/apps/edr-freight-web/portal/src/services/companies.service.ts
index 55eb52c9a..e9cf478c3 100644
--- a/apps/edr-freight-web/portal/src/services/companies.service.ts
+++ b/apps/edr-freight-web/portal/src/services/companies.service.ts
@@ -184,7 +184,16 @@ export interface OnboardingPoaState {
  */
 export interface OnboardingRequirements {
   documentSettingCode: string;
+  /**
+   * Extra document set merged on top of the nationality one for a co-operative,
+   * null otherwise. `documents` already carries the merged list; this is only
+   * so the pickers, which render from the file-settings endpoint, can fetch the
+   * same extra fields.
+   */
+  cooperativeDocumentSettingCode: string | null;
   nationality: string;
+  /** No business licence: registration typed by hand, no eTrade lookup. */
+  cooperative: boolean;
   companyInfo: {
     complete: boolean;
     missingFields: { key: string; label: string }[];
@@ -324,6 +333,7 @@ export const companiesService = {
     companyType: string;
     roles: ProfileTypeValue[];
     nationality?: CompanyNationality;
+    cooperative?: boolean;
   }): Promise<CompanyInfoResponse> => {
     const response = await client.post<ApiResponse<CompanyInfoResponse>>(
       URL_CONSTANTS.COMPANIES_API.ONBOARDING_START,
diff --git a/apps/edr-freight-web/portal/src/types/profile.ts b/apps/edr-freight-web/portal/src/types/profile.ts
index aa62ed4ca..3839e3141 100644
--- a/apps/edr-freight-web/portal/src/types/profile.ts
+++ b/apps/edr-freight-web/portal/src/types/profile.ts
@@ -6,6 +6,8 @@ export interface ProfileResponse {
   companyName: string;
   companyType: string;
   nationality: string | null;
+  /** No business licence: the registration is typed, not fetched from eTrade. */
+  cooperative: boolean;
   companyProfiles: CompanyProfileResponse[];
   companyLocation: string;
   companyAddress: string | null;

From 637a76611856c6e4f6f8ea9c8a7bf95d9cae54ea Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 11 Aug 2026 13:13:11 +0000
Subject: [PATCH 024/174] WIP(represtation step)

---
 .../steps/RepresentationStep.tsx              | 66 ++++++++-----------
 1 file changed, 28 insertions(+), 38 deletions(-)

diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx
index 9acf9f1fb..7228c447c 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx
@@ -23,7 +23,6 @@ import type {
 } from "@/services/verifayda.service";
 
 import type { FormData } from "../schema";
-import SourcedField from "../SourcedField";
 
 /** How a foreign company chose to prove the person: Fayda, or a passport. */
 export type IdentityMethod = "fayda" | "passport";
@@ -251,55 +250,46 @@ export default function RepresentationStep({
           )}
 
           {/* -------------------------------------------------------------- */}
-          {/* The representative's own details — only once the person exists, */}
-          {/* and only the parts the verification did not already carry. What */}
-          {/* Fayda supplied is shown on the panel above and never repeated.  */}
+          {/* The representative's own details — only once the person exists,  */}
+          {/* and only the parts the verification did not carry. What Fayda    */}
+          {/* supplied is on the card above; echoing it back here as read-only */}
+          {/* rows was the same data twice with nothing to do about either.    */}
           {/* -------------------------------------------------------------- */}
           {declared === "yes" && established && (
             <>
-              <SourcedField
-                label="Representative's Name"
-                value={identity.poa.name}
-                source="Fayda"
-                locked={locked.name}
-              >
+              {!locked.name && (
                 <TextInput
                   label="Representative's Name"
                   placeholder="Abebe Bikila"
                   error={errors.poaName?.message}
                   {...register("poaName")}
                 />
-              </SourcedField>
+              )}
 
-              <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
-                <SourcedField
-                  label="Representative's Email"
-                  value={identity.poa.email}
-                  source="Fayda"
-                  locked={locked.email}
+              {(!locked.email || !locked.phone) && (
+                <SimpleGrid
+                  cols={{ base: 1, sm: !locked.email && !locked.phone ? 2 : 1 }}
+                  spacing="md"
                 >
-                  <TextInput
-                    label="Representative's Email"
-                    type="email"
-                    placeholder="representative@company.com"
-                    error={errors.poaEmail?.message}
-                    {...register("poaEmail")}
-                  />
-                </SourcedField>
+                  {!locked.email && (
+                    <TextInput
+                      label="Representative's Email"
+                      type="email"
+                      placeholder="representative@company.com"
+                      error={errors.poaEmail?.message}
+                      {...register("poaEmail")}
+                    />
+                  )}
 
-                <SourcedField
-                  label="Representative's Phone"
-                  value={identity.poa.phone}
-                  source="Fayda"
-                  locked={locked.phone}
-                >
-                  <ControlledPhoneField
-                    control={control}
-                    name="poaPhone"
-                    label="Representative's Phone"
-                  />
-                </SourcedField>
-              </SimpleGrid>
+                  {!locked.phone && (
+                    <ControlledPhoneField
+                      control={control}
+                      name="poaPhone"
+                      label="Representative's Phone"
+                    />
+                  )}
+                </SimpleGrid>
+              )}
 
               {!locked.address && (
                 <TextInput

From e52d66664763ad0160ccb5b16a981c576a08d47c Mon Sep 17 00:00:00 2001
From: ghost2023 <nathnaelwonisha@gmail.com>
Date: Tue, 11 Aug 2026 17:41:06 +0300
Subject: [PATCH 025/174] feat(freight-api): persist eTrade manager phone in
 identity

---
 .../src/components/onboarding/ETradeInfo.tsx  |  41 ++-
 .../src/pages/accounts/CompanyProfileForm.tsx | 269 +++++++++++++-----
 .../companyProfileForm/SourcedField.tsx       |  24 +-
 .../accounts/companyProfileForm/helpers.ts    |  81 +++++-
 .../companyProfileForm/schema.test.ts         | 155 ++++++++++
 .../accounts/companyProfileForm/schema.ts     |  12 +-
 .../steps/CompanyInfoStep.tsx                 | 198 +++++++------
 .../companyProfileForm/steps/ContactStep.tsx  |   7 +
 .../companyProfileForm/steps/OwnerStep.tsx    |  50 ++--
 .../steps/RepresentationStep.tsx              |  22 +-
 .../portal/src/pages/settings/TabOwner.tsx    |   9 +-
 .../portal/src/services/verifayda.service.ts  |   7 +
 12 files changed, 659 insertions(+), 216 deletions(-)

diff --git a/apps/edr-freight-web/portal/src/components/onboarding/ETradeInfo.tsx b/apps/edr-freight-web/portal/src/components/onboarding/ETradeInfo.tsx
index 56273351d..acedc57f5 100644
--- a/apps/edr-freight-web/portal/src/components/onboarding/ETradeInfo.tsx
+++ b/apps/edr-freight-web/portal/src/components/onboarding/ETradeInfo.tsx
@@ -11,7 +11,7 @@ import {
 } from "@mantine/core";
 import { useEffect, useRef, useState } from "react";
 import type { UseFormRegisterReturn } from "react-hook-form";
-import { AlertCircle, Building2, Download } from "lucide-react";
+import { AlertCircle, Building2, Download, Info } from "lucide-react";
 import { useETradeData } from "@/hooks/useETradeData";
 import { extractApiError } from "@/utils/result";
 import type { CompanyRegistrationData } from "@edr/types";
@@ -54,6 +54,14 @@ interface ETradeInfoProps {
    * than silently snapping to eTrade's first one.
    */
   selectedLicenceNumber?: string;
+  /**
+   * A record is worth having but not required — a co-operative union or farm
+   * registers on a TIN alone, so eTrade may legitimately hold nothing for it.
+   * The lookup still runs (plenty of co-operatives DO have a record, and it
+   * beats typing), but "not found" stops being a red dead end and becomes the
+   * expected outcome, with the form below to fill in by hand.
+   */
+  registrationOptional?: boolean;
 }
 
 // Digits, not just length: a 10-character non-numeric TIN used to fire a lookup
@@ -70,6 +78,7 @@ export default function ETradeInfo({
   onReset,
   alreadyVerified,
   selectedLicenceNumber,
+  registrationOptional = false,
 }: ETradeInfoProps) {
   const mutation = useETradeData();
   const isLoading = mutation.isPending;
@@ -327,16 +336,26 @@ export default function ETradeInfo({
         </Stack>
       )}
 
-      {notFound && (
-        <Alert
-          icon={<AlertCircle size={16} />}
-          color="red"
-          title="No matching business record"
-        >
-          This TIN isn't registered with eTrade. Check the number — we can't
-          continue without a matching business record.
-        </Alert>
-      )}
+      {notFound &&
+        (registrationOptional ? (
+          <Alert
+            icon={<Info size={16} />}
+            color="blue"
+            title="Nothing on file at eTrade for this TIN"
+          >
+            That's expected without a trade licence. Fill in your registration
+            details below and we'll take them as you give them.
+          </Alert>
+        ) : (
+          <Alert
+            icon={<AlertCircle size={16} />}
+            color="red"
+            title="No matching business record"
+          >
+            This TIN isn't registered with eTrade. Check the number — we can't
+            continue without a matching business record.
+          </Alert>
+        ))}
 
       {errorMessage && (
         <Alert
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 f4a788437..59fcc2223 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
@@ -9,7 +9,6 @@ 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 { toEthiopianE164 } from "@/components/PhoneField";
 import { getMinFiles } from "@/types/fileUploadSettings";
 import { api } from "@/services/api";
 import type { RoleLicenseProfile } from "@/components/onboarding/RoleLicenseStep";
@@ -24,7 +23,10 @@ import {
 import {
   buildPayload,
   firstPresent,
+  firstValidEmail,
+  firstValidPhone,
   normalizeIdentityPhones,
+  resolveOwnerSources,
   stepPayload,
   toFormValues,
 } from "./companyProfileForm/helpers";
@@ -136,7 +138,24 @@ export default function CompanyProfileForm({
 
   const [step, setStep] = useState<CompanyStep>(initialStep ?? "company");
   const [saving, setSaving] = useState(false);
-  const [saveError, setSaveError] = useState<string | null>(null);
+  /**
+   * What is holding this step back.
+   *
+   * `kind` only picks the title. Most of these never reach the API at all —
+   * they are the step's own gates (a TIN eTrade hasn't confirmed, an
+   * unanswered declaration, a missing paper) — and heading every one of them
+   * "Couldn't save this step" told the customer a request failed when none was
+   * made, which reads as a bug on our side rather than a field to go fix.
+   */
+  const [saveError, setSaveError] = useState<{
+    kind: "check" | "save";
+    message: string;
+  } | null>(null);
+  /** A step gate or a validation failure: something on screen to correct. */
+  const failCheck = (message: string) =>
+    setSaveError({ kind: "check", message });
+  /** The API refused the save; the message is the server's, shown verbatim. */
+  const failSave = (message: string) => setSaveError({ kind: "save", message });
   // Live eTrade lookup status, reported up by ETradeInfo — drives the Continue
   // gate on the company step.
   const [tinStatus, setTinStatus] = useState<ETradeStatus>("idle");
@@ -264,7 +283,6 @@ export default function CompanyProfileForm({
       ownerPhone: "",
       poaName: "",
       poaPhone: "",
-      poaAddress: "",
       poaEmail: "",
       poaLocation: "",
     },
@@ -282,14 +300,23 @@ export default function CompanyProfileForm({
     formState: { dirtyFields },
   } = form;
 
-  // The contact person's email still just seeds from the account and stays editable.
+  // Retire the alert the moment the customer starts acting on it. It was only
+  // ever cleared on navigation, so a red "fix these fields" banner sat above a
+  // form they had already fixed, right until they pressed Continue again —
+  // which reads as an error the page is refusing to let go of.
   useEffect(() => {
-    if (!user?.email) return;
-    if (!watch("contactPersonEmail")) {
-      setValue("contactPersonEmail", user.email);
-    }
+    const sub = watch(() => setSaveError(null));
+    return () => sub.unsubscribe();
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [user?.email, rehydrate]);
+  }, []);
+
+  // Nothing seeds the contact person's email. It used to be prefilled from the
+  // signed-in account, on the same assumption the owner fields were cleared of:
+  // the person doing the onboarding is routinely not the person the company
+  // wants contacted. Prefilled and editable is still prefilled — it is accepted
+  // as-is far more often than it is corrected, so the account address ends up on
+  // file as the company's contact by default rather than by anyone's decision.
+  // The field is optional, so an empty one costs nothing.
 
   // Keep the (hidden, derived) company address in sync with the editable address
   // fields — so it reflects both the eTrade auto-fill and any later user edits,
@@ -303,23 +330,63 @@ export default function CompanyProfileForm({
     const composed = [houseNo, kebele, woreda, zone, region]
       .filter((part) => part && part.trim())
       .join(", ");
+    // No parts means nothing to compose from — the lookup hasn't landed yet, or
+    // this is the render before rehydration. Writing "" here would replace a
+    // saved address with a blank on the next company-step save.
+    if (!composed) return;
     setValue("companyAddress", composed);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [region, zone, woreda, kebele, houseNo]);
 
-  // The manager eTrade lists for this licence. This is the person the owner
-  // step is about — "owner" here means whoever the licence names, and the
-  // backoffice checks the stored owner against exactly this.
-  const [etradeOwner, setEtradeOwner] = useState<{
+  // The manager eTrade lists for this licence, as returned by a lookup made in
+  // THIS session. This is the person the owner step is about — "owner" here
+  // means whoever the licence names, and the backoffice checks the stored owner
+  // against exactly this.
+  const [liveEtradeOwner, setLiveEtradeOwner] = useState<{
     name: string;
     phone: string;
   } | null>(null);
+  // The TIN moved off the last verified lookup, so the persisted manager below
+  // describes a licence this company is no longer claiming. Without this, a
+  // reset would re-lock the owner fields against stale data the moment the
+  // memo below fell back to the server's copy.
+  const [etradeCleared, setEtradeCleared] = useState(false);
+
+  /**
+   * The eTrade manager, live lookup or not.
+   *
+   * The lookup result dies with the page, but the fact that the owner came from
+   * eTrade must not — a resumed wizard that has forgotten it renders the
+   * licence's own name and phone as empty, typeable inputs, which is both a
+   * regression of the read-only rule and an invitation to overwrite the record
+   * the backoffice checks against. The API captured the manager at lookup time
+   * for exactly this, so a resume reads it back from the identity state.
+   */
+  const etradeOwner = useMemo(() => {
+    if (liveEtradeOwner) return liveEtradeOwner;
+    if (etradeCleared) return null;
+    const name = identity?.etradeManagerName?.trim() ?? "";
+    // Normalized on the way out of storage, and dropped if it cannot be — the
+    // stored value is eTrade's free text, and a resume must reach the same
+    // conclusion about it as the lookup did.
+    const phone = firstValidPhone(identity?.etradeManagerPhone);
+    return name || phone ? { name, phone } : null;
+  }, [
+    liveEtradeOwner,
+    etradeCleared,
+    identity?.etradeManagerName,
+    identity?.etradeManagerPhone,
+  ]);
+
+  /** A lookup has actually filled the registration fields this session. */
+  const etradeFilledRef = useRef(false);
 
   // `shouldDirty` is what marks the eTrade bundle as "re-verified this session";
   // `stepPayload` sends those keys only when dirty, so an unchanged record is
   // never echoed back to the API (which would make it re-query eTrade).
   const handleETradeDataLoaded = (data: CompanyRegistrationData) => {
     const dirty = { shouldDirty: true } as const;
+    etradeFilledRef.current = true;
     if (data.companyName) {
       setValue("companyName", data.companyName, {
         shouldValidate: true,
@@ -348,23 +415,32 @@ export default function CompanyProfileForm({
       dirty,
     );
 
+    // The owner's phone is only eTrade's to own if eTrade gave a usable one.
+    // The licence desk's field is free text, so it may hold "09        " — which
+    // normalizes to something non-empty and invalid. Dropping it here leaves the
+    // owner step with an empty, required, editable phone input, which is the
+    // honest state: eTrade has nothing we can use.
     const owner = {
       name: data.managerName,
-      phone: toEthiopianE164(
+      phone: firstValidPhone(
         data.managerPhone || data.regularPhone || data.mobilePhone,
       ),
     };
-    setEtradeOwner(owner);
+    setEtradeCleared(false);
+    setLiveEtradeOwner(owner);
 
-    // Prefill the owner inputs rather than replacing them. The customer can
-    // still correct a name eTrade transliterated oddly — and if they change it
-    // to a different person, `identity.ownerMatchesEtrade` says so to both them
-    // and the reviewer. Only fills what is empty: a value the customer already
-    // typed (or a Fayda claim already stored) is not overwritten by a lookup.
-    if (owner.name && !getValues("ownerName")?.trim()) {
+    // What eTrade said, verbatim — this replaces whatever is in the field
+    // rather than only filling a gap. The owner step shows an eTrade-sourced
+    // name and phone read-only, so leaving an older value in place would send
+    // the API something the customer is no longer shown and cannot correct.
+    //
+    // A Fayda verification still outranks the licence: it owns those fields
+    // server-side, so overwriting them here would only produce a value the API
+    // discards on the way in.
+    if (owner.name && !identity?.owner.name?.trim()) {
       setValue("ownerName", owner.name, { shouldValidate: true, ...dirty });
     }
-    if (owner.phone && !getValues("ownerPhone")?.trim()) {
+    if (owner.phone && !identity?.owner.phone?.trim()) {
       setValue("ownerPhone", owner.phone, { shouldValidate: true, ...dirty });
     }
   };
@@ -377,6 +453,17 @@ export default function CompanyProfileForm({
   // managers, so a prefill from the previous pick is someone else's name.
   // Only the prefill is cleared — a Fayda-verified owner is the API's to own.
   const handleETradeReset = () => {
+    // ...unless there was no prefill to clear. A co-operative now runs the same
+    // lookup as everyone else, but it types these fields itself when eTrade
+    // holds nothing — and wiping them because the customer went back to fix a
+    // digit of their TIN would throw away an address they had just typed by
+    // hand, over a lookup that never filled anything in the first place.
+    if (cooperative && !etradeFilledRef.current) {
+      setLiveEtradeOwner(null);
+      setEtradeCleared(true);
+      return;
+    }
+    etradeFilledRef.current = false;
     setValue("licenceNumber", "");
     setValue("statusDescription", "");
     setValue("dateRegistered", "");
@@ -394,7 +481,8 @@ export default function CompanyProfileForm({
       if (getValues("ownerPhone") === etradeOwner?.phone)
         setValue("ownerPhone", "");
     }
-    setEtradeOwner(null);
+    setLiveEtradeOwner(null);
+    setEtradeCleared(true);
   };
 
   /**
@@ -415,10 +503,27 @@ export default function CompanyProfileForm({
         // The paper is deleted server-side with the representative; a copy
         // still sitting in the picker would be re-uploaded on the next step.
         setDocumentFiles({ ...documentFiles, [POA_DELEGATION_FILE_KEY]: null });
+        // The representative's details go the same way. Answering "no" nulls
+        // every PoA attribute server-side, but the refetch below cannot undo
+        // what is still in the form: `keepDirtyValues` protects exactly the
+        // values the customer typed, so the next step save would send them
+        // straight back — and the API accepts them without complaint, because
+        // its PoA rules only run when the declaration is "yes". The company
+        // ended up on file with no representative and a full set of their
+        // details.
+        for (const field of [
+          "poaName",
+          "poaEmail",
+          "poaPhone",
+          "poaLocation",
+          "poaPassportNumber",
+        ] as const) {
+          setValue(field, "", { shouldDirty: false, shouldValidate: false });
+        }
       }
       onIdentityChange?.();
     } catch (err) {
-      setSaveError(
+      failSave(
         (err as { response?: { data?: { message?: string } } })?.response?.data
           ?.message ??
         (err instanceof Error
@@ -431,32 +536,48 @@ export default function CompanyProfileForm({
   };
 
   /**
-   * Which fields a verification owns, per person.
-   *
-   * A Fayda verification owns the fields its claims filled — the API refuses to
-   * let those be overwritten — but its email, phone and address claims are
-   * optional and routinely come back empty. Everything it did NOT fill stays
-   * the customer's: an editable input, prefilled from eTrade or from what was
-   * saved earlier, and required precisely because there is an input for it.
-   *
-   * Keyed off `verified`, deliberately, not off "does a value exist". A value
-   * exists the moment eTrade prefills the owner or the customer types one and
-   * the step saves — so a presence test turned the input they had just filled
-   * into a read-only badge on the way back through the wizard, and dropped the
-   * field out of `requiredKeys` at the same time. Only a verification locks.
+   * Who owns each of the owner's fields — and therefore which of them are shown
+   * read-only rather than as inputs. See `resolveOwnerSources`; the rule it
+   * encodes pairs with `requiredKeys` below, which requires exactly the fields
+   * no source owns.
    */
   const ownerVerified = identity?.owner.verified ?? false;
   const poaVerified = identity?.poa.verified ?? false;
-  const ownerLocked = {
-    name: ownerVerified && Boolean(identity?.owner.name?.trim()),
-    email: ownerVerified && Boolean(identity?.owner.email?.trim()),
-    phone: ownerVerified && Boolean(identity?.owner.phone?.trim()),
-  };
+  const usableEmail = (value?: string | null) => Boolean(firstValidEmail(value));
+  const usablePhone = (value?: string | null) => Boolean(firstValidPhone(value));
+  const { source: ownerSource, sourced: ownerSourced } = resolveOwnerSources(
+    identity,
+    etradeOwner,
+  );
+
+  // Keep the form holding exactly what the read-only rows show. The two are
+  // filled from different places — the rows from the licence, the fields from
+  // the lookup that ran or from the rehydrated profile — and only the fields
+  // are submitted, so a divergence would send the API something the customer
+  // was never shown and had no input to correct. eTrade wins it, which is what
+  // "not editable" has to mean for a value already on file.
+  useEffect(() => {
+    if (ownerSource.name === "eTrade" && getValues("ownerName") !== ownerSourced.name) {
+      setValue("ownerName", ownerSourced.name, { shouldValidate: true });
+    }
+    if (
+      ownerSource.phone === "eTrade" &&
+      getValues("ownerPhone") !== ownerSourced.phone
+    ) {
+      setValue("ownerPhone", ownerSourced.phone, { shouldValidate: true });
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ownerSource.name, ownerSource.phone, ownerSourced.name, ownerSourced.phone]);
+  // No `address`: Fayda's address claim is `poaAddress`, which the portal never
+  // sends — the step's only address-shaped input writes `poaLocation`, which is
+  // the company's own statement and stays typeable however well Fayda knows
+  // where the person lives.
+  // Same validity test as the owner's: a Fayda claim the schema would reject is
+  // not a claim this step can hide the input behind.
   const poaLocked = {
     name: poaVerified && Boolean(identity?.poa.name?.trim()),
-    email: poaVerified && Boolean(identity?.poa.email?.trim()),
-    phone: poaVerified && Boolean(identity?.poa.phone?.trim()),
-    address: poaVerified && Boolean(identity?.poa.address?.trim()),
+    email: poaVerified && usableEmail(identity?.poa.email),
+    phone: poaVerified && usablePhone(identity?.poa.phone),
   };
 
   /**
@@ -485,9 +606,15 @@ export default function CompanyProfileForm({
 
   // The owner's name from whichever source established them — powers the
   // contact step's "same as owner" card.
+  //
+  // Email and phone are picked by validity, not mere presence. Both are copied
+  // into contact fields the schema requires to be well-formed, and a Fayda
+  // claim or an eTrade record routinely carries something that is neither empty
+  // nor usable ("09        "). Taking it would fail the contact step on a value
+  // the customer never typed and — while the copy is linked — cannot edit.
   const ownerName = firstPresent(identity?.owner.name, watch("ownerName"));
-  const ownerEmail = firstPresent(identity?.owner.email, watch("ownerEmail"));
-  const ownerPhone = firstPresent(identity?.owner.phone, watch("ownerPhone"));
+  const ownerEmail = firstValidEmail(identity?.owner.email, watch("ownerEmail"));
+  const ownerPhone = firstValidPhone(identity?.owner.phone, watch("ownerPhone"));
 
   const [contactSameAsOwner, setContactSameAsOwner] = useState(false);
   // While linked, mirror the source values into the (disabled) target fields so
@@ -538,8 +665,6 @@ export default function CompanyProfileForm({
     [uploadSetting, poaDocumentField],
   );
 
-  const hasDocuments = Boolean(documentsSetting?.fields?.length);
-
   // Hard verification for the documents step: required company-level
   // documents and a business license per operational profile must both be
   // present before the user can continue.
@@ -585,6 +710,9 @@ export default function CompanyProfileForm({
     next: Record<string, File | File[] | null>,
   ) => {
     setDocumentFiles(next);
+    // Files live outside the form, so the watch subscription above never sees
+    // them — the "upload the required documents" alert has to be retired here.
+    setSaveError(null);
     setDocumentFieldErrors((prev) => {
       if (Object.keys(prev).length === 0) return prev;
       const updated = { ...prev };
@@ -674,9 +802,9 @@ export default function CompanyProfileForm({
   } else if (step === "owner") {
     // All three are required by the API (`REQUIRED_COMPANY_INFO`), and an input
     // is rendered for each one a Fayda verification does not own.
-    if (!ownerLocked.name) requiredKeys.push("ownerName");
-    if (!ownerLocked.email) requiredKeys.push("ownerEmail");
-    if (!ownerLocked.phone) requiredKeys.push("ownerPhone");
+    if (!ownerSource.name) requiredKeys.push("ownerName");
+    if (!ownerSource.email) requiredKeys.push("ownerEmail");
+    if (!ownerSource.phone) requiredKeys.push("ownerPhone");
   } else if (
     step === "representation" &&
     identity?.poaDeclared === "yes" &&
@@ -722,7 +850,7 @@ export default function CompanyProfileForm({
     const fields = stepFields[step];
     const isValid = await trigger(fields);
     if (!isValid) {
-      setSaveError(describeErrors(fields));
+      failCheck(describeErrors(fields));
       return false;
     }
     if (!onSaveStep) return true;
@@ -730,7 +858,7 @@ export default function CompanyProfileForm({
     try {
       const res = await onSaveStep(stepPayload(step, getValues(), dirtyFields));
       if (!res.ok) {
-        setSaveError(res.error);
+        failSave(res.error);
         return false;
       }
       return true;
@@ -753,7 +881,7 @@ export default function CompanyProfileForm({
       ) {
         setDocumentFieldErrors(docErrors);
         setLicenseFieldErrors(licenseErrors);
-        setSaveError("Please upload all required documents before continuing.");
+        failCheck("Please upload all required documents before continuing.");
         return;
       }
 
@@ -762,7 +890,7 @@ export default function CompanyProfileForm({
         try {
           const res = await onUploadDocuments();
           if (!res.ok) {
-            setSaveError(res.error);
+            failSave(res.error);
             return;
           }
         } finally {
@@ -786,13 +914,13 @@ export default function CompanyProfileForm({
     // A co-operative is exempt: it has no licence for eTrade to hold, so
     // `tinVerified` is true for it and only the duplicate-TIN check applies.
     if (step === "company" && tinStatus === "taken") {
-      setSaveError(
+      failCheck(
         "This TIN is already registered to another company account.",
       );
       return;
     }
     if (step === "company" && !tinVerified) {
-      setSaveError(
+      failCheck(
         tinStatus === "choose-business"
           ? "This TIN holds more than one business licence — pick the one you're registering as."
           : "We need to confirm your TIN with eTrade before continuing.",
@@ -802,7 +930,7 @@ export default function CompanyProfileForm({
     // The declaration decides whose identity is verified, so it has to be
     // answered before the verification below can mean anything.
     if (step === "representation" && !identity?.poaDeclared) {
-      setSaveError(
+      failCheck(
         "Tell us whether anyone holds power of attorney for this company.",
       );
       return;
@@ -814,7 +942,7 @@ export default function CompanyProfileForm({
         identity?.subject === "poa"
           ? "your Power of Attorney"
           : "the company owner";
-      setSaveError(
+      failCheck(
         identity?.passportAccepted
           ? `Verify ${who} with Fayda, or enter their passport number.`
           : `Verify ${who} with Fayda before continuing.`,
@@ -828,7 +956,7 @@ export default function CompanyProfileForm({
       });
       // Validate the text fields too, so every problem shows at once.
       const fieldsOk = await trigger(stepFields.representation);
-      setSaveError(
+      failCheck(
         [
           "Upload the DARS delegation paper for the representative you named.",
           fieldsOk ? null : describeErrors(stepFields.representation),
@@ -852,7 +980,7 @@ export default function CompanyProfileForm({
         try {
           const res = await onUploadDocuments();
           if (!res.ok) {
-            setSaveError(res.error);
+            failSave(res.error);
             return;
           }
         } finally {
@@ -895,7 +1023,8 @@ export default function CompanyProfileForm({
               form={form}
               identity={identity}
               etradeOwner={etradeOwner}
-              locked={ownerLocked}
+              source={ownerSource}
+              sourced={ownerSourced}
               cooperative={cooperative}
             />
           )}
@@ -950,9 +1079,13 @@ export default function CompanyProfileForm({
               color="red"
               variant="light"
               icon={<AlertCircle size={18} />}
-              title={"Couldn't save this step"}
+              title={
+                saveError.kind === "save"
+                  ? "Couldn't save this step"
+                  : "Please check this step"
+              }
             >
-              {saveError}
+              {saveError.message}
             </Alert>
           )}
 
@@ -982,7 +1115,11 @@ export default function CompanyProfileForm({
                 isPending ||
                 saving ||
                 declarePending ||
-                (step === "documents" && !hasDocuments && loadingDocuments)
+                // Nothing to validate against until the document set lands, so
+                // pressing Continue now would report every required upload as
+                // satisfied. `hasDocuments` used to be in here too, which let
+                // the button go live mid-load the moment the set resolved.
+                (step === "documents" && loadingDocuments)
               }
               loading={isPending || saving}
               rightSection={
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/SourcedField.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/SourcedField.tsx
index 3b3601711..2a42c424a 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/SourcedField.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/SourcedField.tsx
@@ -10,15 +10,15 @@ const SOURCE_NOTE: Record<FieldSource, string> = {
 };
 
 /**
- * One person-detail field that a verification may have taken ownership of.
+ * One person-detail field that an outside source may have taken ownership of.
  *
- * `locked` — not "does a value exist" — decides which side renders. That
+ * `source` — not "does a value exist" — decides which side renders. That
  * distinction is the whole point: `ownerName` holds a value the moment the
- * eTrade lookup prefills it or the customer types it and the step saves, and
- * keying off presence meant the input a customer had just filled in turned into
- * a read-only badge as soon as they navigated away and back, with no way to
- * correct it. Only a Fayda verification actually owns a field — the API refuses
- * to overwrite those — so only those lock.
+ * customer types it and the step saves, and keying off presence meant the input
+ * they had just filled in turned into a read-only badge as soon as they
+ * navigated away and back, with no way to correct it. Only a real source owns a
+ * field: a Fayda verification (the API refuses to overwrite those) or the
+ * eTrade licence (the record the backoffice checks the company against).
  *
  * It pairs with `requiredKeys` in CompanyProfileForm, which requires exactly
  * the fields that fall through to `children`: **a field is required if and only
@@ -28,19 +28,17 @@ export default function SourcedField({
   label,
   value,
   source,
-  locked,
   children,
 }: {
   label: string;
-  /** The value to display when locked. */
+  /** The value to display when a source owns this field. */
   value?: string | null;
-  source: FieldSource;
-  /** A verification owns this field: show it read-only instead of an input. */
-  locked: boolean;
+  /** The owning source, or null while the field is still the customer's. */
+  source: FieldSource | null;
   /** The input rendered whenever the field is still the customer's to fill. */
   children: ReactNode;
 }) {
-  if (!locked || !value?.trim()) return <>{children}</>;
+  if (!source || !value?.trim()) return <>{children}</>;
 
   return (
     <Stack gap={2}>
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/helpers.ts b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/helpers.ts
index ca745a953..623f75e1a 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/helpers.ts
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/helpers.ts
@@ -4,6 +4,8 @@ import type { ProfileResponse, UpdateProfilePayload } from "@/types/profile";
 import type { CompanyIdentityState } from "@/services/verifayda.service";
 import { isValidPhone, toEthiopianE164 } from "@/components/PhoneField";
 
+import type { FieldSource } from "./SourcedField";
+
 import {
   ETRADE_BUNDLE_FIELDS,
   type CompanyStep,
@@ -81,6 +83,73 @@ export const samePhone = (a?: string | null, b?: string | null) => {
   return da.length === 9 && da === phoneDigits(b);
 };
 
+/** The owner details an outside source can take ownership of. */
+export type OwnerField = "name" | "email" | "phone";
+
+export interface OwnerSources {
+  /** Which source owns each field, or null where it is still the customer's. */
+  source: Record<OwnerField, FieldSource | null>;
+  /** What to display for an owned field — normalized as the payload will be. */
+  sourced: Record<OwnerField, string>;
+}
+
+/**
+ * Who owns each of the owner's fields, and with what value.
+ *
+ * Two sources can own a field, and they rank. A Fayda verification owns
+ * whatever its claims filled (the API refuses to overwrite those), and the
+ * eTrade licence owns the manager's name and phone: that record is the thing
+ * the backoffice checks the company against, so it is reported, not proposed.
+ * Neither is typeable. Everything left over is the customer's — an editable
+ * input, required precisely because there is an input for it. Fayda outranks
+ * eTrade on the same person: the stronger claim, and the one the API keeps.
+ *
+ * Two things deliberately do NOT take ownership.
+ *
+ * A value merely being present. It exists the moment the customer types one and
+ * the step saves — so a presence test turned the input they had just filled
+ * into a read-only badge on the way back through the wizard, and dropped the
+ * field out of `requiredKeys` at the same time.
+ *
+ * And a value that isn't usable. Both sources hold contact details as free
+ * text: Fayda's phone is whatever the national registry recorded, eTrade's is
+ * whatever was typed at the licence desk ("09        " is a real answer, and it
+ * normalizes to a non-empty, invalid `+2519`). Locking one of those behind a
+ * read-only row leaves the customer told to fix a field with no input, or the
+ * step saved with a value the API rejects. So a source owns an email or a phone
+ * only if what it supplies holds up as one; otherwise the field falls through
+ * to an input and is required like any other. Names have no format to fail, so
+ * presence is the whole test there.
+ */
+export function resolveOwnerSources(
+  identity: CompanyIdentityState | undefined,
+  etradeOwner: { name: string; phone: string } | null,
+): OwnerSources {
+  const verified = identity?.owner.verified ?? false;
+  const faydaName = verified && Boolean(identity?.owner.name?.trim());
+  const faydaEmail = verified ? firstValidEmail(identity?.owner.email) : "";
+  const faydaPhone = verified ? firstValidPhone(identity?.owner.phone) : "";
+  const etradeName = etradeOwner?.name?.trim() ?? "";
+  const etradePhone = firstValidPhone(etradeOwner?.phone);
+
+  const source: Record<OwnerField, FieldSource | null> = {
+    name: faydaName ? "Fayda" : etradeName ? "eTrade" : null,
+    // eTrade never returns an email for the manager, so this one is Fayda's or
+    // it is the customer's to type.
+    email: faydaEmail ? "Fayda" : null,
+    phone: faydaPhone ? "Fayda" : etradePhone ? "eTrade" : null,
+  };
+
+  return {
+    source,
+    sourced: {
+      name: source.name === "Fayda" ? (identity?.owner.name?.trim() ?? "") : etradeName,
+      email: faydaEmail,
+      phone: source.phone === "Fayda" ? faydaPhone : etradePhone,
+    },
+  };
+}
+
 /** 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;
@@ -133,7 +202,13 @@ export function stepPayload(
       }
       if (dirty.tinNumber) etrade.tin = d.tinNumber;
       return {
-        companyAddress: d.companyAddress,
+        // Composed from the address parts, so it is only as complete as they
+        // are. Sending it while they are still empty (the lookup hasn't landed,
+        // or eTrade left them blank) would overwrite a stored address with a
+        // degraded version of itself — an absent key means "untouched".
+        ...(d.companyAddress?.trim()
+          ? { companyAddress: d.companyAddress }
+          : {}),
         vatNumber: d.vatNumber,
         ...etrade,
       };
@@ -164,6 +239,9 @@ export function stepPayload(
         poaPhone: d.poaPhone || undefined,
         poaLocation: d.poaLocation || undefined,
         poaPassportNumber: d.poaPassportNumber || undefined,
+        // The step renders one passport input, for whichever person the
+        // declaration made the identity subject — so it has to save both.
+        ownerPassportNumber: d.ownerPassportNumber || undefined,
       };
     default:
       return {};
@@ -202,7 +280,6 @@ export function toFormValues(p: ProfileResponse): FormData {
     ownerPhone: p.ownerPhone ?? "",
     poaName: p.poaName ?? "",
     poaPhone: p.poaPhone ?? "",
-    poaAddress: p.poaAddress ?? "",
     poaEmail: p.poaEmail ?? "",
     poaLocation: p.poaLocation ?? "",
   };
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
index 4b5b7cdb7..cd957eec7 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.test.ts
@@ -6,6 +6,7 @@ import {
   firstValidEmail,
   firstValidPhone,
   normalizeIdentityPhones,
+  resolveOwnerSources,
   stepPayload,
 } from "./helpers";
 import type { FormData } from "./schema";
@@ -144,6 +145,49 @@ describe("stepFields", () => {
   });
 });
 
+describe("the identity subject's passport", () => {
+  // The representation step renders ONE passport input, for whoever the
+  // power-of-attorney answer made the identity subject. When the answer is "no
+  // PoA" that is the owner — so the owner's passport number is typed on the
+  // representation step and has to be carried by it. It used to belong to the
+  // owner step alone, which is already behind the customer by then: the number
+  // was typed, dropped, and the final submit failed `assertIdentityVerified`
+  // naming a field they could see was filled in.
+  it("is carried by the step that renders the input", () => {
+    expect(stepFields.representation).toContain("ownerPassportNumber");
+    expect(stepFields.representation).toContain("poaPassportNumber");
+  });
+
+  it("saves the owner's passport from the representation step", () => {
+    const payload = stepPayload(
+      "representation",
+      values({ ownerPassportNumber: "P1234567" }),
+    );
+    expect(payload.ownerPassportNumber).toBe("P1234567");
+  });
+
+  it("still omits it when there is none, rather than sending an empty string", () => {
+    const payload = stepPayload(
+      "representation",
+      values({ ownerPassportNumber: "" }),
+    );
+    expect(payload.ownerPassportNumber).toBeUndefined();
+  });
+});
+
+describe("stepPayload (representation)", () => {
+  // `poaAddress` is a Fayda-owned claim (`IDENTITY_OWNED_FIELDS` server-side).
+  // The portal states `poaLocation` instead and must never send the other.
+  it("sends the company's stated location, never the Fayda address", () => {
+    const payload = stepPayload(
+      "representation",
+      values({ poaLocation: "Dire Dawa, Ethiopia" }),
+    );
+    expect(payload.poaLocation).toBe("Dire Dawa, Ethiopia");
+    expect("poaAddress" in payload).toBe(false);
+  });
+});
+
 describe("buildOnboardingSchema (conditionally required fields)", () => {
   const issuesFor = (
     data: FormData,
@@ -210,6 +254,14 @@ describe("stepPayload (company)", () => {
     // Still only the dirty ones.
     expect(payload.licenceNumber).toBeUndefined();
   });
+
+  // The address is composed from the parts, so it is only ever as complete as
+  // they are. An absent key means "untouched" to the API; sending a blank one
+  // would replace a stored address with nothing.
+  it("omits a blank composed address rather than clearing the stored one", () => {
+    const payload = stepPayload("company", values({ companyAddress: "" }), {});
+    expect("companyAddress" in payload).toBe(false);
+  });
 });
 
 describe("stepPayload (owner)", () => {
@@ -278,6 +330,109 @@ describe("firstValidEmail", () => {
   });
 });
 
+describe("resolveOwnerSources", () => {
+  const identity = (over: {
+    verified?: boolean;
+    name?: string | null;
+    email?: string | null;
+    phone?: string | null;
+  }): CompanyIdentityState =>
+    ({
+      passportAccepted: false,
+      poaDeclared: "no",
+      subject: "owner",
+      owner: {
+        verified: over.verified ?? true,
+        name: over.name ?? null,
+        email: over.email ?? null,
+        phone: over.phone ?? null,
+        address: null,
+        verifiedAt: null,
+        passportNumber: null,
+      },
+      poa: {
+        verified: false,
+        name: null,
+        email: null,
+        phone: null,
+        address: null,
+        verifiedAt: null,
+        passportNumber: null,
+      },
+      identityProven: false,
+      etradeManagerName: null,
+      etradeManagerPhone: null,
+      ownerMatchesEtrade: null,
+      complete: false,
+    }) as CompanyIdentityState;
+
+  it("locks what each source supplied, Fayda outranking eTrade", () => {
+    const { source, sourced } = resolveOwnerSources(
+      identity({
+        name: "Abebe Bikila",
+        email: "owner@example.com",
+        phone: "+251911223344",
+      }),
+      { name: "A. Bikila", phone: "+251911999888" },
+    );
+    expect(source).toEqual({ name: "Fayda", email: "Fayda", phone: "Fayda" });
+    expect(sourced.phone).toBe("+251911223344");
+  });
+
+  // The point of the whole exercise: a field is read-only only if what the
+  // source gave can actually be submitted. Otherwise the customer is shown a
+  // badge holding a value the API will reject, with no input to fix it.
+  it("falls back to an input when Fayda's phone claim is unusable", () => {
+    const { source, sourced } = resolveOwnerSources(
+      identity({ name: "Abebe Bikila", phone: "09        " }),
+      null,
+    );
+    expect(source.phone).toBeNull();
+    expect(sourced.phone).toBe("");
+  });
+
+  it("falls back to an input when Fayda's email claim is malformed", () => {
+    const { source } = resolveOwnerSources(
+      identity({ name: "Abebe Bikila", email: "not-an-email" }),
+      null,
+    );
+    expect(source.email).toBeNull();
+  });
+
+  it("falls back to an input when eTrade's manager phone is unusable", () => {
+    const { source, sourced } = resolveOwnerSources(undefined, {
+      name: "Abebe Bikila",
+      phone: "09        ",
+    });
+    // The name is still eTrade's — names have no format to fail.
+    expect(source.name).toBe("eTrade");
+    expect(source.phone).toBeNull();
+    expect(sourced.phone).toBe("");
+  });
+
+  it("takes eTrade's phone where Fayda has none, normalized", () => {
+    const { source, sourced } = resolveOwnerSources(
+      identity({ verified: false }),
+      { name: "Abebe Bikila", phone: "0911223344" },
+    );
+    expect(source.phone).toBe("eTrade");
+    expect(sourced.phone).toBe("+251911223344");
+  });
+
+  it("owns nothing when the verification never happened", () => {
+    const { source } = resolveOwnerSources(
+      identity({
+        verified: false,
+        name: "Abebe Bikila",
+        email: "owner@example.com",
+        phone: "+251911223344",
+      }),
+      null,
+    );
+    expect(source).toEqual({ name: null, email: null, phone: null });
+  });
+});
+
 describe("normalizeIdentityPhones", () => {
   it("converts a local Fayda phone claim to E.164", () => {
     const identity = {
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 d642e48c7..b274761b0 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
@@ -90,7 +90,6 @@ export const onboardingSchema = z.object({
     .string()
     .optional()
     .refine((v) => !v || isValidPhone(v), "Enter a valid phone number"),
-  poaAddress: z.string().optional(),
   poaEmail: z
     .string()
     .optional()
@@ -98,6 +97,10 @@ export const onboardingSchema = z.object({
       (v) => !v || z.string().email().safeParse(v).success,
       "Invalid email address",
     ),
+  // Where the representative is based, as the company states it. Deliberately
+  // NOT `poaAddress`: that one is a Fayda-owned claim (`IDENTITY_OWNED_FIELDS`)
+  // the verification writes and the portal must never send — the two used to
+  // sit side by side here, with the Fayda address silently hiding this input.
   poaLocation: z.string().optional(),
 });
 
@@ -220,12 +223,19 @@ export const stepFields: Record<CompanyStep, (keyof FormData)[]> = {
   // declared (`REQUIRED_POA_FIELDS`), so the step has to offer them wherever
   // Fayda didn't supply them — otherwise the save is rejected naming fields the
   // form never rendered.
+  // `ownerPassportNumber` belongs here as much as the PoA's: the step renders
+  // whichever passport input the declaration calls for, and when the answer is
+  // "no PoA" that is the owner's. Leaving it out meant the number was typed on
+  // this step, validated by nothing, and dropped by `stepPayload` — so the
+  // final submit failed `assertIdentityVerified` over a field two steps back
+  // that the customer could see was filled in.
   representation: [
     "poaName",
     "poaEmail",
     "poaPhone",
     "poaLocation",
     "poaPassportNumber",
+    "ownerPassportNumber",
   ],
   documents: [],
   additional: [],
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
index 5e4ad7f85..b89e0e920 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
@@ -44,6 +44,8 @@ export default function CompanyInfoStep({
     formState: { errors },
   } = form;
 
+  const region = watch("region") ?? "";
+
   return (
     <Stack gap="xl">
       <StepSection
@@ -59,100 +61,120 @@ export default function CompanyInfoStep({
         />
       </StepSection>
 
-      {cooperative ? (
-        <>
-          <StepSection
-            index={2}
-            title="Company TIN"
-            subtitle="A co-operative union or farm has no trade licence for us to look up, so we take the TIN as you give it."
-            status={watch("tinNumber")?.trim() && !errors.tinNumber ? "done" : "todo"}
-          >
-            <TextInput
-              aria-label="Company TIN"
-              placeholder="0012345678"
-              error={errors.tinNumber?.message}
-              {...register("tinNumber")}
-            />
-          </StepSection>
-
-          <StepSection
-            index={3}
-            title="Registration details"
-            subtitle="Everything we'd normally read off an eTrade licence. We need it from you instead."
-            status={
-              watch("companyName")?.trim() && watch("region")?.trim()
+      {/* The TIN lookup runs for everyone, co-operative included. A co-op has
+          no trade licence, but plenty of them are on eTrade all the same — and
+          when the record is there it is better data than anything typed, so we
+          ask for it first and fall back to the form below rather than deciding
+          in advance that nothing will be found. What differs for a co-op is
+          only the consequence of finding nothing: expected, not an error. */}
+      <StepSection
+        index={2}
+        title="Company TIN"
+        subtitle={
+          cooperative
+            ? "We'll check eTrade for your TIN. Co-operatives often aren't listed — if yours isn't, you'll fill the details in below."
+            : "We'll pull your registration straight from eTrade — nothing to type by hand once it's found."
+        }
+        status={
+          tinStatus === "taken"
+            ? "blocked"
+            : cooperative
+              ? watch("tinNumber")?.trim() && !errors.tinNumber
                 ? "done"
                 : "todo"
-            }
-          >
-            <Stack gap="md">
-              <TextInput
-                label="Company Name"
-                placeholder="Registered name of the union or farm"
-                error={errors.companyName?.message}
-                {...register("companyName")}
-              />
-              <Text size="sm" c="edr-muted">
-                Registered address
-              </Text>
-              <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
-                <Select
-                  label="Region"
-                  placeholder="Select region"
-                  data={[...ETHIOPIAN_REGIONS]}
-                  searchable
-                  value={watch("region") || null}
-                  onChange={(v) =>
-                    setValue("region", v ?? "", { shouldValidate: true })
-                  }
-                  error={errors.region?.message}
-                />
-                <TextInput
-                  label="Zone"
-                  error={errors.zone?.message}
-                  {...register("zone")}
-                />
-                <TextInput
-                  label="Woreda"
-                  error={errors.woreda?.message}
-                  {...register("woreda")}
-                />
-                <TextInput
-                  label="Kebele"
-                  error={errors.kebele?.message}
-                  {...register("kebele")}
-                />
-                <TextInput
-                  label="House No."
-                  error={errors.houseNo?.message}
-                  {...register("houseNo")}
-                />
-              </SimpleGrid>
-            </Stack>
-          </StepSection>
-        </>
-      ) : (
+              : tinVerified
+                ? "done"
+                : "todo"
+        }
+      >
+        <ETradeInfo
+          tin={watch("tinNumber")}
+          register={register("tinNumber")}
+          error={errors.tinNumber?.message}
+          onDataLoaded={onETradeDataLoaded}
+          onStatusChange={onETradeStatusChange}
+          onReset={onETradeReset}
+          alreadyVerified={hasRegistrationDetails}
+          selectedLicenceNumber={watch("licenceNumber")}
+          registrationOptional={cooperative}
+        />
+        {!cooperative && tinVerified && (
+          <ETradeCompanyCard tin={watch("tinNumber")} watch={watch} />
+        )}
+      </StepSection>
+
+      {/* A co-operative keeps its typed registration section either way. When
+          the lookup found something these arrive prefilled — still editable,
+          because for a co-op they are the customer's own statement rather than
+          the licence's, and the API takes them as given (`applyEtradeSourcedFields`
+          skips co-operatives entirely). */}
+      {cooperative && (
         <StepSection
-          index={2}
-          title="Company TIN"
-          subtitle="We'll pull your registration straight from eTrade — nothing to type by hand once it's found."
+          index={3}
+          title="Registration details"
+          subtitle={
+            hasRegistrationDetails
+              ? "From eTrade. Correct anything that doesn't look right — for a co-operative these are yours to state."
+              : "Everything we'd normally read off an eTrade licence. We need it from you instead."
+          }
           status={
-            tinVerified ? "done" : tinStatus === "taken" ? "blocked" : "todo"
+            watch("companyName")?.trim() && watch("region")?.trim()
+              ? "done"
+              : "todo"
           }
         >
-          <ETradeInfo
-            tin={watch("tinNumber")}
-            register={register("tinNumber")}
-            error={errors.tinNumber?.message}
-            onDataLoaded={onETradeDataLoaded}
-            onStatusChange={onETradeStatusChange}
-            onReset={onETradeReset}
-            alreadyVerified={hasRegistrationDetails}
-            selectedLicenceNumber={watch("licenceNumber")}
-          />
-          {tinVerified && (
-            <ETradeCompanyCard tin={watch("tinNumber")} watch={watch} />
-          )}
+          <Stack gap="md">
+            <TextInput
+              label="Company Name"
+              placeholder="Registered name of the union or farm"
+              error={errors.companyName?.message}
+              {...register("companyName")}
+            />
+            <Text size="sm" c="edr-muted">
+              Registered address
+            </Text>
+            <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+              <Select
+                label="Region"
+                placeholder="Select region"
+                // eTrade's own spelling may not be one of ours. Carrying it in
+                // as an option keeps the lookup's answer visible instead of
+                // silently blanking the field it just filled.
+                data={
+                  region &&
+                    !(ETHIOPIAN_REGIONS as readonly string[]).includes(region)
+                    ? [...ETHIOPIAN_REGIONS, region]
+                    : [...ETHIOPIAN_REGIONS]
+                }
+                searchable
+                value={region || null}
+                onChange={(v) =>
+                  setValue("region", v ?? "", { shouldValidate: true })
+                }
+                error={errors.region?.message}
+              />
+              <TextInput
+                label="Zone"
+                error={errors.zone?.message}
+                {...register("zone")}
+              />
+              <TextInput
+                label="Woreda"
+                error={errors.woreda?.message}
+                {...register("woreda")}
+              />
+              <TextInput
+                label="Kebele"
+                error={errors.kebele?.message}
+                {...register("kebele")}
+              />
+              <TextInput
+                label="House No."
+                error={errors.houseNo?.message}
+                {...register("houseNo")}
+              />
+            </SimpleGrid>
+          </Stack>
         </StepSection>
       )}
     </Stack>
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/ContactStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/ContactStep.tsx
index b03e879f1..6c28161b8 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/ContactStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/ContactStep.tsx
@@ -46,9 +46,14 @@ export default function ContactStep({
         />
       )}
       <SimpleGrid cols={2} spacing="md">
+        {/* Disabled while linked, not merely prefilled: the mirror effect
+            rewrites these from the owner whenever the owner changes, so an edit
+            made here would be silently thrown away the next time it fires.
+            Position is the customer's either way — the owner has no equivalent. */}
         <TextInput
           label="Name"
           placeholder="Jane Smith"
+          disabled={contactSameAsOwner}
           error={errors.contactPersonName?.message}
           {...register("contactPersonName")}
         />
@@ -64,6 +69,7 @@ export default function ContactStep({
           label="Email (Optional)"
           type="email"
           placeholder="contact@company.com"
+          disabled={contactSameAsOwner}
           error={errors.contactPersonEmail?.message}
           {...register("contactPersonEmail")}
         />
@@ -71,6 +77,7 @@ export default function ContactStep({
           control={control}
           name="contactPersonPhone"
           label="Phone"
+          disabled={contactSameAsOwner}
           required
         />
       </SimpleGrid>
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx
index 7861f4818..4035b8aaf 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx
@@ -6,7 +6,10 @@ import { ControlledPhoneField } from "@/components/PhoneField";
 import type { CompanyIdentityState } from "@/services/verifayda.service";
 
 import type { FormData } from "../schema";
-import SourcedField from "../SourcedField";
+import SourcedField, { type FieldSource } from "../SourcedField";
+
+/** The owner details this step is responsible for. */
+type OwnerField = "name" | "email" | "phone";
 
 export interface OwnerStepProps {
   form: UseFormReturn<FormData>;
@@ -14,13 +17,19 @@ export interface OwnerStepProps {
   /** eTrade's registered manager, once a TIN lookup has succeeded. */
   etradeOwner: { name: string; phone: string } | null;
   /**
-   * Which of the owner's details a Fayda verification owns. A locked field is
-   * shown read-only; every other one is an editable input, prefilled from
-   * eTrade or from what was saved earlier. CompanyProfileForm computes this and
-   * requires exactly the unlocked fields, so every input on screen is one the
-   * customer is actually asked to fill and nothing is required that has none.
+   * Which source owns each of the owner's details, or null where none does.
+   *
+   * A sourced field is shown read-only with its provenance; every other one is
+   * an editable input. Neither the eTrade licence nor a Fayda verification is
+   * the customer's to retype — the first is the record the backoffice checks
+   * this company against, the second is the government's. CompanyProfileForm
+   * computes this and requires exactly the unsourced fields, so every input on
+   * screen is one the customer is actually asked to fill and nothing is
+   * required that has none.
    */
-  locked: { name: boolean; email: boolean; phone: boolean };
+  source: Record<OwnerField, FieldSource | null>;
+  /** The value to display for a field its source owns. */
+  sourced: Record<OwnerField, string>;
   /** A co-operative union or farm: no licence, so no eTrade record to match. */
   cooperative?: boolean;
 }
@@ -44,7 +53,8 @@ export default function OwnerStep({
   form,
   identity,
   etradeOwner,
-  locked,
+  source,
+  sourced,
   cooperative = false,
 }: OwnerStepProps) {
   const {
@@ -64,11 +74,14 @@ export default function OwnerStep({
   return (
     <Stack gap="md">
       <Text size="sm" c="edr-muted">
-        {cooperative
-          ? "The person who runs the co-operative union or farm. We have no licence record to fill these in from, so we need all of them from you."
-          : "These are the details of the person registered on your eTrade licence. We fill in whatever eTrade and Fayda gave us; anything they left blank we need from you."}
+        {cooperative && !etradeOwner
+          ? "The person who runs the co-operative union or farm. eTrade held no record for your TIN, so we need all of these from you."
+          : "These are the details of the person registered on your eTrade licence. What eTrade and Fayda gave us is shown as they gave it; anything they left blank we need from you."}
       </Text>
 
+      {/* A co-operative is not told its licence listed no manager — it has no
+          licence. Its own "nothing came back" case is covered by the line
+          above. */}
       {!cooperative && !etradeOwner && !ownerVerified && (
         <Alert color="blue" variant="light" icon={<Info size={18} />}>
           Your eTrade licence didn't list a manager, so there's nothing for us
@@ -92,9 +105,8 @@ export default function OwnerStep({
 
       <SourcedField
         label="Owner's Name"
-        value={identity?.owner.name}
-        source="Fayda"
-        locked={locked.name}
+        value={sourced.name}
+        source={source.name}
       >
         <TextInput
           label="Owner's Name"
@@ -110,9 +122,8 @@ export default function OwnerStep({
             type — it is required either way (`REQUIRED_COMPANY_INFO`). */}
         <SourcedField
           label="Owner's Email"
-          value={identity?.owner.email}
-          source="Fayda"
-          locked={locked.email}
+          value={sourced.email}
+          source={source.email}
         >
           <TextInput
             label="Owner's Email"
@@ -125,9 +136,8 @@ export default function OwnerStep({
 
         <SourcedField
           label="Owner's Phone"
-          value={identity?.owner.phone}
-          source="Fayda"
-          locked={locked.phone}
+          value={sourced.phone}
+          source={source.phone}
         >
           <ControlledPhoneField
             control={control}
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx
index 7228c447c..24391391a 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/RepresentationStep.tsx
@@ -45,8 +45,14 @@ export interface RepresentationStepProps {
    * Which of the representative's details the Fayda verification owns. Same
    * contract as OwnerStep's `locked`: a locked field is read-only, every other
    * one is an input, and the schema requires exactly the unlocked ones.
+   *
+   * There is deliberately no `address` here. Fayda's address claim is stored as
+   * `poaAddress`, which the portal never sends; the input below writes
+   * `poaLocation`, a different field the company states itself. Gating one on
+   * the other hid the only input for `poaLocation` from every verified
+   * representative whose Fayda record happened to carry an address.
    */
-  locked: { name: boolean; email: boolean; phone: boolean; address: boolean };
+  locked: { name: boolean; email: boolean; phone: boolean };
   /**
    * How a foreign company is proving the subject. Null until it picks — the
    * either/or is a fork, not a fallback, so nothing below it renders until one
@@ -291,14 +297,12 @@ export default function RepresentationStep({
                 </SimpleGrid>
               )}
 
-              {!locked.address && (
-                <TextInput
-                  label="Representative's Location"
-                  placeholder="City, Country"
-                  error={errors.poaLocation?.message}
-                  {...register("poaLocation")}
-                />
-              )}
+              <TextInput
+                label="Representative's Location"
+                placeholder="City, Country"
+                error={errors.poaLocation?.message}
+                {...register("poaLocation")}
+              />
 
               {poaDocumentSetting && (
                 <>
diff --git a/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx b/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx
index 9399c5efc..def3126f1 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx
@@ -159,8 +159,7 @@ export default function TabOwner({
           <SourcedField
             label="Name"
             value={owner?.name}
-            source="Fayda"
-            locked={ownerLocked.name}
+            source={ownerLocked.name ? "Fayda" : null}
           >
             <TextInput
               label="Name"
@@ -175,8 +174,7 @@ export default function TabOwner({
               <SourcedField
                 label="Email"
                 value={owner?.email}
-                source="Fayda"
-                locked={ownerLocked.email}
+                source={ownerLocked.email ? "Fayda" : null}
               >
                 <TextInput
                   label="Email"
@@ -191,8 +189,7 @@ export default function TabOwner({
               <SourcedField
                 label="Phone"
                 value={owner?.phone}
-                source="Fayda"
-                locked={ownerLocked.phone}
+                source={ownerLocked.phone ? "Fayda" : null}
               >
                 <ControlledPhoneField
                   control={control}
diff --git a/apps/edr-freight-web/portal/src/services/verifayda.service.ts b/apps/edr-freight-web/portal/src/services/verifayda.service.ts
index 50afaaec6..79dc14f40 100644
--- a/apps/edr-freight-web/portal/src/services/verifayda.service.ts
+++ b/apps/edr-freight-web/portal/src/services/verifayda.service.ts
@@ -55,6 +55,13 @@ export interface CompanyIdentityState {
   identityProven: boolean;
   /** The manager named on the eTrade licence, captured at lookup. */
   etradeManagerName: string | null;
+  /**
+   * That manager's phone (E.164), from the same lookup. Together with the name
+   * this is what survives a refresh: the live lookup result does not, so
+   * without these two a resumed wizard cannot tell an eTrade-sourced owner from
+   * a typed one, and offers the licence's own data back as editable inputs.
+   */
+  etradeManagerPhone: string | null;
   /**
    * Does the owner the company put forward match the eTrade licence? This is
    * the backoffice's check. Null when there is nothing to compare. Advisory:

From 35e5404b4143fafa0036ff12556c44349aca4c9a Mon Sep 17 00:00:00 2001
From: marshalyordanos <marshalyordanosseifu@gmail.com>
Date: Tue, 11 Aug 2026 19:36:00 +0300
Subject: [PATCH 026/174] Refactor code structure for improved readability and
 maintainability

---
 apps/edr-freight-api/docs/audit-endpoints.md  |  922 +++++++
 apps/edr-freight-api/package.json             |    1 -
 apps/edr-freight-api/src/app.module.ts        |   16 -
 .../src/config/database.config.ts             |    6 -
 apps/edr-freight-api/src/main.ts              |    6 -
 .../src/modules/audit/audit.controller.ts     |   32 -
 .../src/modules/audit/audit.module.ts         |   13 -
 .../src/modules/audit/audit.service.ts        |   70 -
 .../payment/payment-events.consumer.ts        |    7 +-
 .../repositories/cargo-types.repository.ts    |    5 +-
 .../src/seed/freight-permissions.registry.ts  |    8 -
 apps/edr-freight-web/backoffice/src/App.tsx   |    9 -
 .../src/components/layout/route-meta.ts       |    7 -
 .../components/layout/sidebar-sections.tsx    |    7 -
 .../backoffice/src/constants/URLS.ts          |    4 -
 .../backoffice/src/lib/permissions.ts         |    3 -
 .../src/pages/audit/AuditLogsPage.tsx         |  190 --
 .../backoffice/src/services/api.ts            |   14 -
 .../backoffice/src/services/audit.service.ts  |   70 -
 pnpm-lock.yaml                                | 2227 ++++++-----------
 20 files changed, 1684 insertions(+), 1933 deletions(-)
 create mode 100644 apps/edr-freight-api/docs/audit-endpoints.md
 delete mode 100644 apps/edr-freight-api/src/modules/audit/audit.controller.ts
 delete mode 100644 apps/edr-freight-api/src/modules/audit/audit.module.ts
 delete mode 100644 apps/edr-freight-api/src/modules/audit/audit.service.ts
 delete mode 100644 apps/edr-freight-web/backoffice/src/pages/audit/AuditLogsPage.tsx
 delete mode 100644 apps/edr-freight-web/backoffice/src/services/audit.service.ts

diff --git a/apps/edr-freight-api/docs/audit-endpoints.md b/apps/edr-freight-api/docs/audit-endpoints.md
new file mode 100644
index 000000000..38e89e367
--- /dev/null
+++ b/apps/edr-freight-api/docs/audit-endpoints.md
@@ -0,0 +1,922 @@
+# Freight API — Mutating Endpoints (Audit Surface)
+
+Every state-changing route in `apps/edr-freight-api` — `POST`, `PUT`, `PATCH`, `DELETE`.
+This is the candidate surface for audit logging: each row is an action a user can take
+that changes persisted state and therefore needs a who / what / when trail.
+
+All paths include the global prefix `api` (`app.setGlobalPrefix("api")` in `src/main.ts`).
+Titles come from each route's `@ApiOperation({ summary })`; where a route has none,
+the title is derived from its handler name.
+
+> Generated by reading the `@Post` / `@Put` / `@Patch` / `@Delete` decorators in
+> `src/**/*.controller.ts`. Re-generate after adding routes so this stays complete.
+
+## Summary
+
+| Method | Count |
+| --- | ---: |
+| `POST` | 351 |
+| `PUT` | 8 |
+| `PATCH` | 72 |
+| `DELETE` | 61 |
+| **Total** | **492** |
+
+Across **66** entities.
+
+## Entity index
+
+| Entity | Endpoints |
+| --- | ---: |
+| [Account](#account) | 3 |
+| [AI Assist](#ai-assist) | 1 |
+| [Approval Rule](#approval-rule) | 5 |
+| [Booking](#booking) | 57 |
+| [Cargo](#cargo) | 6 |
+| [Cargo Type](#cargo-type) | 5 |
+| [Company](#company) | 30 |
+| [Compliance](#compliance) | 3 |
+| [Consignment](#consignment) | 1 |
+| [Container](#container) | 5 |
+| [Container Type](#container-type) | 5 |
+| [Contract](#contract) | 68 |
+| [Contract Template](#contract-template) | 8 |
+| [Driver](#driver) | 5 |
+| [Dropdown Setting](#dropdown-setting) | 7 |
+| [EIMS Invoice](#eims-invoice) | 3 |
+| [Exchange Setting](#exchange-setting) | 1 |
+| [Facility](#facility) | 3 |
+| [Fayda Verification](#fayda-verification) | 1 |
+| [File Upload Setting](#file-upload-setting) | 7 |
+| [First Mile](#first-mile) | 7 |
+| [Fuel](#fuel) | 1 |
+| [GPS Tracking](#gps-tracking) | 3 |
+| [Import Operation](#import-operation) | 9 |
+| [Incident](#incident) | 3 |
+| [Interchange Document](#interchange-document) | 3 |
+| [Last Mile](#last-mile) | 10 |
+| [Last Mile Request](#last-mile-request) | 4 |
+| [Locomotive](#locomotive) | 4 |
+| [Maintenance](#maintenance) | 13 |
+| [Notification Inbox](#notification-inbox) | 2 |
+| [Organization User](#organization-user) | 2 |
+| [OTP](#otp) | 2 |
+| [Password Reset](#password-reset) | 4 |
+| [Payment](#payment) | 7 |
+| [Priority Config](#priority-config) | 5 |
+| [Priority Rule Change Request](#priority-rule-change-request) | 3 |
+| [Procurement](#procurement) | 8 |
+| [Rate](#rate) | 5 |
+| [Rate Change Request](#rate-change-request) | 3 |
+| [Route](#route) | 4 |
+| [Schedule](#schedule) | 3 |
+| [Service Type](#service-type) | 5 |
+| [Shipping Line](#shipping-line) | 3 |
+| [Signature](#signature) | 1 |
+| [Support Chat](#support-chat) | 5 |
+| [Support Content](#support-content) | 3 |
+| [Train](#train) | 3 |
+| [Train Build](#train-build) | 11 |
+| [Train Schedule](#train-schedule) | 48 |
+| [Transit Agent](#transit-agent) | 3 |
+| [Truck Type](#truck-type) | 3 |
+| [User Trade Access](#user-trade-access) | 1 |
+| [Vehicle](#vehicle) | 3 |
+| [Wagon](#wagon) | 8 |
+| [Wagon Transfer Request](#wagon-transfer-request) | 5 |
+| [Wagon Type](#wagon-type) | 3 |
+| [Warehouse](#warehouse) | 12 |
+| [Warehouse Fee Invoice](#warehouse-fee-invoice) | 5 |
+| [Warehouse Inspection Report](#warehouse-inspection-report) | 3 |
+| [Warehouse Inventory](#warehouse-inventory) | 24 |
+| [Warehouse Yard](#warehouse-yard) | 2 |
+| [Warehouse Zone](#warehouse-zone) | 1 |
+| [Weight Limit Rule](#weight-limit-rule) | 3 |
+| [Yard](#yard) | 5 |
+| [Yard Distance](#yard-distance) | 3 |
+
+---
+
+## Endpoints by entity
+
+### Account
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Send a verification code to a new email/phone before changing it | `POST` | `/api/me/contact/otp` | `modules/auth/account.controller.ts:26` |
+| Change the account's email or phone, gated by a verification code | `PATCH` | `/api/me/contact` | `modules/auth/account.controller.ts:40` |
+| Change the account's display name | `PATCH` | `/api/me/name` | `modules/auth/account.controller.ts:54` |
+
+### AI Assist
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Mock AI: extract structured booking fields from free-text request | `POST` | `/api/ai/booking/extract` | `modules/ai/ai.controller.ts:16` |
+
+### Approval Rule
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create an approval rule step | `POST` | `/api/approval-rules` | `modules/rule-engine/controllers/approval-rules.controller.ts:66` |
+| Move an approval step up or down within its chain | `POST` | `/api/approval-rules/:id/move-order` | `modules/rule-engine/controllers/approval-rules.controller.ts:51` |
+| Bulk reorder approval steps within a chain | `POST` | `/api/approval-rules/reorder` | `modules/rule-engine/controllers/approval-rules.controller.ts:43` |
+| Update an approval rule | `PATCH` | `/api/approval-rules/:id` | `modules/rule-engine/controllers/approval-rules.controller.ts:73` |
+| Soft-delete an approval rule | `DELETE` | `/api/approval-rules/:id` | `modules/rule-engine/controllers/approval-rules.controller.ts:80` |
+
+### Booking
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a new freight booking (DRAFT) | `POST` | `/api/bookings` | `modules/bookings/bookings.controller.ts:170` |
+| Allocate containers to vehicles | `POST` | `/api/bookings/:bookingId/allocate-containers` | `modules/bookings/booking-allocation.controller.ts:13` |
+| Cancel booking | `POST` | `/api/bookings/:id/cancel` | `modules/bookings/bookings.controller.ts:1544` |
+| Customer cancels an unpaid hold (SELECTED_FOR_BATCH → CANCELLED); | `POST` | `/api/bookings/:id/cancel-hold` | `modules/bookings/bookings.controller.ts:1568` |
+| GL ET uploads customs declaration on booking (GENERAL customs) | `POST` | `/api/bookings/:id/clearance/declaration` | `modules/bookings/bookings.controller.ts:1126` |
+| Upload Booking Delivery Order | `POST` | `/api/bookings/:id/clearance/delivery-order` | `modules/bookings/bookings.controller.ts:1268` |
+| Customer uploads clearance documents (fieldname = document key) | `POST` | `/api/bookings/:id/clearance/documents` | `modules/bookings/bookings.controller.ts:959` |
+| GL ET sends a draft customs declaration (multi-file) with an estimated price for the customer to review | `POST` | `/api/bookings/:id/clearance/draft-declaration` | `modules/bookings/bookings.controller.ts:1175` |
+| Customer accepts the draft customs declaration — unlocks the real customs declaration step for GL Ethiopia | `POST` | `/api/bookings/:id/clearance/draft-declaration/accept` | `modules/bookings/bookings.controller.ts:1200` |
+| Customer requests a change to the draft customs declaration with a reason — GL Ethiopia sends a corrected draft (repeatable) | `POST` | `/api/bookings/:id/clearance/draft-declaration/change` | `modules/bookings/bookings.controller.ts:1211` |
+| GL ET sets duty/tax on booking with notice attachment | `POST` | `/api/bookings/:id/clearance/duty` | `modules/bookings/bookings.controller.ts:1144` |
+| Customer uploads duty/tax payment slip on booking | `POST` | `/api/bookings/:id/clearance/duty-slip` | `modules/bookings/bookings.controller.ts:1238` |
+| Confirm Booking Export Release | `POST` | `/api/bookings/:id/clearance/export-release` | `modules/bookings/bookings.controller.ts:1326` |
+| GL finalizes clearance (requires 100% approved) → CLEARANCE_READY | `POST` | `/api/bookings/:id/clearance/finalize` | `modules/bookings/bookings.controller.ts:1087` |
+| GL ET finalizes import pre-clearance on booking | `POST` | `/api/bookings/:id/clearance/finalize-pre-clearance` | `modules/bookings/bookings.controller.ts:1230` |
+| GL uploads customs output documents (IM4/EX3/…) | `POST` | `/api/bookings/:id/clearance/output-documents` | `modules/bookings/bookings.controller.ts:1071` |
+| Customer requests operation with a schedule day | `POST` | `/api/bookings/:id/clearance/proceed` | `modules/bookings/bookings.controller.ts:979` |
+| Upload Booking Release Order | `POST` | `/api/bookings/:id/clearance/release-order` | `modules/bookings/bookings.controller.ts:1288` |
+| GL reviews a clearance document (Approve | Query) | `POST` | `/api/bookings/:id/clearance/review` | `modules/bookings/bookings.controller.ts:1051` |
+| Request Booking RO Amendment | `POST` | `/api/bookings/:id/clearance/ro-amendment` | `modules/bookings/bookings.controller.ts:1311` |
+| GL Djibouti picks the transit officer from the roster — unblocks the customs declaration; calling again reassigns | `POST` | `/api/bookings/:id/clearance/transit-assignee/assign` | `modules/bookings/bookings.controller.ts:1112` |
+| GL ET asks GL Djibouti to name the transit officer — required before the import customs declaration | `POST` | `/api/bookings/:id/clearance/transit-assignee/request` | `modules/bookings/bookings.controller.ts:1098` |
+| Upload Booking Transit Permit | `POST` | `/api/bookings/:id/clearance/transit-permit` | `modules/bookings/bookings.controller.ts:1251` |
+| Confirm submit after price change | `POST` | `/api/bookings/:id/confirm-submit` | `modules/bookings/bookings.controller.ts:906` |
+| Request freight consolidation | `POST` | `/api/bookings/:id/consolidation` | `modules/bookings/bookings.controller.ts:1583` |
+| Generate contract PDF from template | `POST` | `/api/bookings/:id/contract/generate` | `modules/bookings/bookings.controller.ts:1406` |
+| Apply digital signature (customer or staff) | `POST` | `/api/bookings/:id/contract/sign` | `modules/bookings/bookings.controller.ts:1452` |
+| Customer cancels their own booking before payment — no cancellation fee | `POST` | `/api/bookings/:id/customer-cancel` | `modules/bookings/bookings.controller.ts:1555` |
+| Customer assigns external truck and driver for terminal pickup | `POST` | `/api/bookings/:id/customer-truck-assignment` | `modules/bookings/bookings.controller.ts:460` |
+| Add a customer self-haul truck carrying 1–2 of the booking containers | `POST` | `/api/bookings/:id/customer-trucks` | `modules/bookings/bookings.controller.ts:686` |
+| Register an import truck leaving: containers loaded + weighed gross (staff) | `POST` | `/api/bookings/:id/customer-trucks/:assignmentId/depart` | `modules/bookings/bookings.controller.ts:788` |
+| Truck_dispatch: load selected containers onto a truck (staff) | `POST` | `/api/bookings/:id/customer-trucks/:assignmentId/load` | `modules/bookings/bookings.controller.ts:773` |
+| Bulk add customer trucks from array payload (Excel parsed) | `POST` | `/api/bookings/:id/customer-trucks/bulk` | `modules/bookings/bookings.controller.ts:701` |
+| Customer digital signature (deprecated — use POST contract/sign) | `POST` | `/api/bookings/:id/customer/sign` | `modules/bookings/bookings.controller.ts:1487` |
+| Upload documents for a booking (DRAFT only) | `POST` | `/api/bookings/:id/documents` | `modules/bookings/bookings.controller.ts:869` |
+| Generate a GRN over the received containers (all received, or a subset) — one GRN per batch | `POST` | `/api/bookings/:id/generate-grn` | `modules/bookings/bookings.controller.ts:820` |
+| Generate price preview (DRAFT or CHANGES_REQUESTED) | `POST` | `/api/bookings/:id/generate-price` | `modules/bookings/bookings.controller.ts:882` |
+| Expedite government booking to PAID / ELIGIBLE for scheduling | `POST` | `/api/bookings/:id/government-expedite` | `modules/bookings/bookings.controller.ts:1390` |
+| Staff contract signature and fully execute (use contract/sign STAFF preferred) | `POST` | `/api/bookings/:id/marketing/approve` | `modules/bookings/bookings.controller.ts:1505` |
+| Operations reviews an operation request: ACCEPT (→ batch pool), | `POST` | `/api/bookings/:id/operation/review` | `modules/bookings/bookings.controller.ts:1030` |
+| Mark completed | `POST` | `/api/bookings/:id/operations/complete` | `modules/bookings/bookings.controller.ts:1536` |
+| Mark in transit | `POST` | `/api/bookings/:id/operations/start-transit` | `modules/bookings/bookings.controller.ts:1528` |
+| Customer reject price estimate | `POST` | `/api/bookings/:id/reject` | `modules/bookings/bookings.controller.ts:918` |
+| Staff accept intake → set contract validity window + start approval chain | `POST` | `/api/bookings/:id/staff/accept` | `modules/bookings/bookings.controller.ts:1355` |
+| Staff final reject | `POST` | `/api/bookings/:id/staff/reject` | `modules/bookings/bookings.controller.ts:1374` |
+| Staff return booking for customer updates | `POST` | `/api/bookings/:id/staff/request-changes` | `modules/bookings/bookings.controller.ts:1339` |
+| Customer submit booking | `POST` | `/api/bookings/:id/submit` | `modules/bookings/bookings.controller.ts:894` |
+| Request a partial wagon cancellation on a PAID booking — opens the cancellation-fee invoice; wagons are released only once the fee settles | `POST` | `/api/bookings/:id/wagon-cancellations` | `modules/bookings/bookings.controller.ts:558` |
+| Preview the fee/credit of a partial wagon cancellation (no writes) | `POST` | `/api/bookings/:id/wagon-cancellations/preview` | `modules/bookings/bookings.controller.ts:544` |
+| Rebook a wagon-cancellation credit: pick a shipment day only — the new booking is created under the contract and marked PAID (freight already paid; contract must still be valid) | `POST` | `/api/bookings/wagon-cancellations/:cancellationId/rebook` | `modules/bookings/bookings.controller.ts:638` |
+| Withdraw a fee-pending wagon cancellation (owner, or staff with the void permission) | `POST` | `/api/bookings/wagon-cancellations/:cancellationId/withdraw` | `modules/bookings/bookings.controller.ts:624` |
+| Update booking | `PATCH` | `/api/bookings/:id` | `modules/bookings/bookings.controller.ts:211` |
+| Edit a not-yet-arrived customer truck (plate/driver/type + containers) | `PATCH` | `/api/bookings/:id/customer-trucks/:assignmentId` | `modules/bookings/bookings.controller.ts:716` |
+| Export only: choose direct truck-to-train (no warehouse, no GRN) or warehouse first | `PATCH` | `/api/bookings/:id/export-handover-mode` | `modules/bookings/bookings.controller.ts:761` |
+| Soft-delete DRAFT booking | `DELETE` | `/api/bookings/:id` | `modules/bookings/bookings.controller.ts:861` |
+| Remove consolidation pairing | `DELETE` | `/api/bookings/:id/consolidation` | `modules/bookings/bookings.controller.ts:1590` |
+| Remove a not-yet-arrived customer truck from a booking | `DELETE` | `/api/bookings/:id/customer-trucks/:assignmentId` | `modules/bookings/bookings.controller.ts:732` |
+
+### Cargo
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a new cargo | `POST` | `/api/cargoes` | `modules/cargoes/cargoes.controller.ts:34` |
+| Mark cargo as delivered | `POST` | `/api/cargoes/:id/deliver` | `modules/cargoes/cargoes.controller.ts:81` |
+| Load cargo into a container | `POST` | `/api/cargoes/:id/load` | `modules/cargoes/cargoes.controller.ts:67` |
+| Unload cargo from container | `POST` | `/api/cargoes/:id/unload` | `modules/cargoes/cargoes.controller.ts:74` |
+| Update a cargo | `PATCH` | `/api/cargoes/:id` | `modules/cargoes/cargoes.controller.ts:53` |
+| Delete a cargo | `DELETE` | `/api/cargoes/:id` | `modules/cargoes/cargoes.controller.ts:60` |
+
+### Cargo Type
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a cargo type | `POST` | `/api/cargo-types` | `modules/rule-engine/controllers/cargo-types.controller.ts:51` |
+| Move a cargo type up or down in display order | `POST` | `/api/cargo-types/:id/move-order` | `modules/rule-engine/controllers/cargo-types.controller.ts:36` |
+| Bulk reorder cargo types by ID list | `POST` | `/api/cargo-types/reorder` | `modules/rule-engine/controllers/cargo-types.controller.ts:28` |
+| Update a cargo type | `PATCH` | `/api/cargo-types/:id` | `modules/rule-engine/controllers/cargo-types.controller.ts:58` |
+| Soft-delete a cargo type | `DELETE` | `/api/cargo-types/:id` | `modules/rule-engine/controllers/cargo-types.controller.ts:65` |
+
+### Company
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a new company (customer, freight_forwarder, dj_freight_forwarder, transporter) | `POST` | `/api/companies` | `modules/companies/companies.controller.ts:565` |
+| Upload documents for a company (onboarding) | `POST` | `/api/companies/:companyId/documents` | `modules/companies/companies.controller.ts:728` |
+| Add a profile (employee) to a company | `POST` | `/api/companies/:companyId/profiles` | `modules/companies/companies.controller.ts:843` |
+| Approve a pending profile change request (applies the changes) | `POST` | `/api/companies/change-requests/:id/approve` | `modules/companies/companies.controller.ts:790` |
+| Reject a pending profile change request with a note | `POST` | `/api/companies/change-requests/:id/reject` | `modules/companies/companies.controller.ts:806` |
+| Ask for specific changes on a pending request without rejecting it (row stays open, next edit appends to it) | `POST` | `/api/companies/change-requests/:id/request-changes` | `modules/companies/companies.controller.ts:824` |
+| Create a single operational profile for the current user's company. The role starts pending and does not become the active mode | `POST` | `/api/companies/company-profile` | `modules/companies/companies.controller.ts:272` |
+| Add operational profile(s) (importer/exporter/forwarder) to the current user's company | `POST` | `/api/companies/company-profiles` | `modules/companies/companies.controller.ts:229` |
+| Add business-license document(s) to a profile. For an approved company | `POST` | `/api/companies/company-profiles/:profileId/license` | `modules/companies/companies.controller.ts:290` |
+| Replace a business-license file with a newly uploaded one (staged for | `POST` | `/api/companies/company-profiles/:profileId/license/:fileId/replace` | `modules/companies/companies.controller.ts:311` |
+| Resubmit a rejected operational role for approval (→ pending) | `POST` | `/api/companies/company-profiles/:profileId/reapply` | `modules/companies/companies.controller.ts:165` |
+| Create a company with its associated external profile (onboarding) | `POST` | `/api/companies/create` | `modules/companies/companies.controller.ts:539` |
+| Ask the customer to correct one uploaded document | `POST` | `/api/companies/documents/:fileId/request-change` | `modules/companies/companies.controller.ts:699` |
+| Fetch company info from eTrade by TIN | `POST` | `/api/companies/fetch-etrade-info` | `modules/companies/companies.controller.ts:197` |
+| Bind a completed Fayda verification to the company's owner or Power of Attorney | `POST` | `/api/companies/identity/fayda/complete` | `modules/companies/companies.controller.ts:414` |
+| Declare the General Manager is the company's owner, copying the owner's verified identity across | `POST` | `/api/companies/identity/gm/same-as-owner` | `modules/companies/companies.controller.ts:432` |
+| Declare the Power of Attorney is the company's owner, copying the owner's identity across | `POST` | `/api/companies/identity/poa/same-as-owner` | `modules/companies/companies.controller.ts:461` |
+| Mark the current user's onboarding as complete | `POST` | `/api/companies/onboarding/complete` | `modules/companies/companies.controller.ts:527` |
+| Begin onboarding: create a draft company + profile + role(s) so later steps can save incrementally | `POST` | `/api/companies/onboarding/start` | `modules/companies/companies.controller.ts:246` |
+| Upload the Power of Attorney delegation letter, replacing any existing one | `POST` | `/api/companies/poa-delegation` | `modules/companies/companies.controller.ts:380` |
+| Update a company | `PATCH` | `/api/companies/:id` | `modules/companies/companies.controller.ts:613` |
+| Update a company profile's approval status | `PATCH` | `/api/companies/company-profiles/:profileId/status` | `modules/companies/companies.controller.ts:748` |
+| Persist the user's current onboarding wizard step | `PATCH` | `/api/companies/onboarding-step` | `modules/companies/companies.controller.ts:504` |
+| Update profile (flattened settings page) | `PATCH` | `/api/companies/profile` | `modules/companies/companies.controller.ts:219` |
+| Soft-delete a company | `DELETE` | `/api/companies/:id` | `modules/companies/companies.controller.ts:634` |
+| Remove a business-license file (staged for review on an approved company) | `DELETE` | `/api/companies/company-profiles/:profileId/license/:fileId` | `modules/companies/companies.controller.ts:338` |
+| Remove the company's Power of Attorney — the verified identity, its details and the delegation paper together | `DELETE` | `/api/companies/identity/fayda/poa` | `modules/companies/companies.controller.ts:491` |
+| Clear the General Manager's identity — the \"same as owner\" declaration or a verification, and the details either wrote | `DELETE` | `/api/companies/identity/gm` | `modules/companies/companies.controller.ts:448` |
+| Undo the Power of Attorney \"same as owner\" declaration and the identity it copied, leaving the representative open to be verified in their own right | `DELETE` | `/api/companies/identity/poa/same-as-owner` | `modules/companies/companies.controller.ts:478` |
+| Remove the Power of Attorney delegation letter (staged for review on an approved company) | `DELETE` | `/api/companies/poa-delegation/:fileId` | `modules/companies/companies.controller.ts:401` |
+
+### Compliance
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a compliance record | `POST` | `/api/compliance` | `modules/compliance/compliance.controller.ts:23` |
+| Update a compliance record | `PATCH` | `/api/compliance/:id` | `modules/compliance/compliance.controller.ts:51` |
+| Soft-delete a compliance record | `DELETE` | `/api/compliance/:id` | `modules/compliance/compliance.controller.ts:58` |
+
+### Consignment
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a new consignment | `POST` | `/api/consignments` | `modules/consignments/consignments.controller.ts:29` |
+
+### Container
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a new container | `POST` | `/api/containers` | `modules/container-management/containers.controller.ts:33` |
+| Assign container to a wagon | `POST` | `/api/containers/:id/assign-wagon` | `modules/container-management/containers.controller.ts:66` |
+| Unassign container from wagon | `POST` | `/api/containers/:id/unassign-wagon` | `modules/container-management/containers.controller.ts:73` |
+| Update a container | `PATCH` | `/api/containers/:id` | `modules/container-management/containers.controller.ts:52` |
+| Delete a container | `DELETE` | `/api/containers/:id` | `modules/container-management/containers.controller.ts:59` |
+
+### Container Type
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a container type | `POST` | `/api/container-types` | `modules/rule-engine/controllers/container-types.controller.ts:51` |
+| Move a container type up or down in display order | `POST` | `/api/container-types/:id/move-order` | `modules/rule-engine/controllers/container-types.controller.ts:36` |
+| Bulk reorder container types by ID list | `POST` | `/api/container-types/reorder` | `modules/rule-engine/controllers/container-types.controller.ts:28` |
+| Update a container type | `PATCH` | `/api/container-types/:id` | `modules/rule-engine/controllers/container-types.controller.ts:58` |
+| Soft-delete a container type | `DELETE` | `/api/container-types/:id` | `modules/rule-engine/controllers/container-types.controller.ts:65` |
+
+### Contract
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a new contract (DRAFT) with routes + cargo scope | `POST` | `/api/contracts` | `modules/contracts/contracts.controller.ts:188` |
+| Approve one approval step in sequence | `POST` | `/api/contracts/:id/approval-steps/:stepId/approve` | `modules/contracts/contracts.controller.ts:552` |
+| Reject one approval step — to the customer (terminal → REJECTED) or, via returnToStepId, back to an earlier approver (chain re-runs from there) | `POST` | `/api/contracts/:id/approval-steps/:stepId/reject` | `modules/contracts/contracts.controller.ts:571` |
+| Customer submits a shipment request on a GENERAL customs contract | `POST` | `/api/contracts/:id/booking-requests` | `modules/contracts/contracts.controller.ts:170` |
+| Create a shipment booking under a contract — Path A (customer) or Path B (GL Ethiopia) | `POST` | `/api/contracts/:id/bookings` | `modules/contracts/contracts.controller.ts:1076` |
+| Complete an initiated booking after Operations finalized its clearance — cargo + binding day, window and departure checks, pricing and invoicing | `POST` | `/api/contracts/:id/bookings/:bookingId/complete` | `modules/contracts/contracts.controller.ts:1133` |
+| Initiate a bare booking instance under an import/export contract (ONE_TIME or GENERAL) — no cargo, no date; enters per-booking clearance (AWAITING_DOCUMENTS). ONE_TIME customs instances are opened by the customer (or GL); GENERAL customs comes from a shipment request | `POST` | `/api/contracts/:id/bookings/initiate` | `modules/contracts/contracts.controller.ts:1105` |
+| Customer cancels their own contract (blocked while a booking is live) | `POST` | `/api/contracts/:id/cancel` | `modules/contracts/contracts.controller.ts:526` |
+| GL ET uploads customs declaration documents (multi-file) | `POST` | `/api/contracts/:id/clearance/declaration` | `modules/contracts/contracts.controller.ts:795` |
+| GL DJ uploads Delivery Order (import) with vessel arrival + DO collected dates | `POST` | `/api/contracts/:id/clearance/delivery-order` | `modules/contracts/contracts.controller.ts:957` |
+| Customer uploads clearance documents (fieldname = document key) | `POST` | `/api/contracts/:id/clearance/documents` | `modules/contracts/contracts.controller.ts:734` |
+| GL replaces a clearance document in place (reason required) — the previous version is kept in the file history and the new one needs approving | `POST` | `/api/contracts/:id/clearance/documents/:fileKey/replace` | `modules/contracts/contracts.controller.ts:894` |
+| GL ET sets duty/tax requirement and advises amount with notice attachment | `POST` | `/api/contracts/:id/clearance/duty` | `modules/contracts/contracts.controller.ts:808` |
+| Customer uploads duty/tax payment slip on contract | `POST` | `/api/contracts/:id/clearance/duty-slip` | `modules/contracts/contracts.controller.ts:932` |
+| Customer disputes the advised duty/tax with a reason — reopens the step so GL Ethiopia can re-advise (repeatable) | `POST` | `/api/contracts/:id/clearance/duty/dispute` | `modules/contracts/contracts.controller.ts:918` |
+| GL ET confirms export release after declaration | `POST` | `/api/contracts/:id/clearance/export-release` | `modules/contracts/contracts.controller.ts:1008` |
+| GL ET finalizes clearance → CLEARANCE_READY_FOR_BOOKING (legacy) | `POST` | `/api/contracts/:id/clearance/finalize` | `modules/contracts/contracts.controller.ts:788` |
+| GL ET finalizes export clearance after post-booking transit permit upload | `POST` | `/api/contracts/:id/clearance/finalize-export-clearance` | `modules/contracts/contracts.controller.ts:1018` |
+| GL ET finalizes import pre-clearance — unlocks Djibouti DO upload | `POST` | `/api/contracts/:id/clearance/finalize-pre-clearance` | `modules/contracts/contracts.controller.ts:838` |
+| Operations finalizes self-clearance → customer may create the booking | `POST` | `/api/contracts/:id/clearance/ops-finalize` | `modules/contracts/contracts.controller.ts:1051` |
+| Operations reviews a customer self-clearance document (Approve | Query) | `POST` | `/api/contracts/:id/clearance/ops-review` | `modules/contracts/contracts.controller.ts:1032` |
+| GL uploads customs output documents (IM4/EX3/…) pre-booking | `POST` | `/api/contracts/:id/clearance/output-documents` | `modules/contracts/contracts.controller.ts:776` |
+| GL DJ uploads Release Order + vessel departure date (export) | `POST` | `/api/contracts/:id/clearance/release-order` | `modules/contracts/contracts.controller.ts:978` |
+| GL ET reviews a clearance document (Approve | Query) | `POST` | `/api/contracts/:id/clearance/review` | `modules/contracts/contracts.controller.ts:756` |
+| GL DJ requests port amendment when RO vessel window is too short | `POST` | `/api/contracts/:id/clearance/ro-amendment` | `modules/contracts/contracts.controller.ts:997` |
+| GL Djibouti picks the transit officer from the roster — unblocks the customs declaration; calling again reassigns | `POST` | `/api/contracts/:id/clearance/transit-assignee/assign` | `modules/contracts/contracts.controller.ts:863` |
+| GL ET asks GL Djibouti to name the transit officer — required before the customs declaration | `POST` | `/api/contracts/:id/clearance/transit-assignee/request` | `modules/contracts/contracts.controller.ts:845` |
+| GL ET uploads import transit permit documents (multi-file) | `POST` | `/api/contracts/:id/clearance/transit-permit` | `modules/contracts/contracts.controller.ts:944` |
+| Confirm submit after a price change | `POST` | `/api/contracts/:id/confirm-submit` | `modules/contracts/contracts.controller.ts:380` |
+| Generate contract document → CONTRACT_READY | `POST` | `/api/contracts/:id/contract/generate` | `modules/contracts/contracts.controller.ts:596` |
+| Send the sudo-mode signing OTP to the contract company's registered phone (server picks the number) | `POST` | `/api/contracts/:id/contract/send-signing-otp` | `modules/contracts/contracts.controller.ts:667` |
+| Apply digital signature (customer or staff/director/ceo) | `POST` | `/api/contracts/:id/contract/sign` | `modules/contracts/contracts.controller.ts:680` |
+| Upload intake documents for a contract (DRAFT only) | `POST` | `/api/contracts/:id/documents` | `modules/contracts/contracts.controller.ts:354` |
+| Generate unit-rate breakdown (no totals at contract phase) | `POST` | `/api/contracts/:id/generate-price` | `modules/contracts/contracts.controller.ts:366` |
+| GL marks a pre-booking (contract) milestone complete | `POST` | `/api/contracts/:id/milestones/:code/complete` | `modules/contracts/contracts.controller.ts:1222` |
+| Create a renewal draft linked via renewalOfId | `POST` | `/api/contracts/:id/renew` | `modules/contracts/contracts.controller.ts:705` |
+| Staff lift a suspension — contract returns to its prior status | `POST` | `/api/contracts/:id/resume` | `modules/contracts/contracts.controller.ts:510` |
+| Staff accept → set validity window + start approval chain | `POST` | `/api/contracts/:id/staff/accept` | `modules/contracts/contracts.controller.ts:387` |
+| Staff reject contract | `POST` | `/api/contracts/:id/staff/reject` | `modules/contracts/contracts.controller.ts:476` |
+| Staff return contract for customer updates | `POST` | `/api/contracts/:id/staff/request-changes` | `modules/contracts/contracts.controller.ts:460` |
+| Customer submit contract (freezes contract_rate_snapshots) | `POST` | `/api/contracts/:id/submit` | `modules/contracts/contracts.controller.ts:373` |
+| Staff freeze a signed contract (reversible, any post-signature step) | `POST` | `/api/contracts/:id/suspend` | `modules/contracts/contracts.controller.ts:492` |
+| Pre-create validation + authoritative price preview: full booking price breakdown (rail, first/last mile, surcharges), overweight lines and 20ft weight-pairing errors for a shipment payload (no booking created) | `POST` | `/api/contracts/:id/validate-shipment` | `modules/contracts/contracts.controller.ts:1162` |
+| GL marks a shipment request accepted + links the created booking | `POST` | `/api/contracts/booking-requests/:reqId/accept` | `modules/contracts/contracts.controller.ts:134` |
+| Customer cancels their own pending shipment request | `POST` | `/api/contracts/booking-requests/:reqId/cancel` | `modules/contracts/contracts.controller.ts:160` |
+| GL rejects a shipment request | `POST` | `/api/contracts/booking-requests/:reqId/reject` | `modules/contracts/contracts.controller.ts:149` |
+| GL uploads post-booking operational documents (DO/RO/T1/…) | `POST` | `/api/contracts/bookings/:bookingId/documents` | `modules/contracts/contracts.controller.ts:1441` |
+| GL ET advises duty & tax amount + declaration serial | `POST` | `/api/contracts/bookings/:bookingId/duty` | `modules/contracts/contracts.controller.ts:1260` |
+| Customer uploads the duty/tax payment slip | `POST` | `/api/contracts/bookings/:bookingId/duty-slip` | `modules/contracts/contracts.controller.ts:1455` |
+| GL DJ raises the post-offload final invoice (amount + invoice document) | `POST` | `/api/contracts/bookings/:bookingId/final-invoice` | `modules/contracts/contracts.controller.ts:1332` |
+| Customer attaches the payment slip for the final invoice | `POST` | `/api/contracts/bookings/:bookingId/final-invoice-slip` | `modules/contracts/contracts.controller.ts:1374` |
+| Customer approves the drafted final invoice — unlocks the payment slip | `POST` | `/api/contracts/bookings/:bookingId/final-invoice/approve` | `modules/contracts/contracts.controller.ts:1359` |
+| GL (ET or DJ) confirms the payment slip — settles the final invoice | `POST` | `/api/contracts/bookings/:bookingId/final-invoice/confirm` | `modules/contracts/contracts.controller.ts:1386` |
+| GL DJ logs a cargo exception with photo evidence | `POST` | `/api/contracts/bookings/:bookingId/incidents` | `modules/contracts/contracts.controller.ts:1479` |
+| GL / Ops / Terminal marks a post-booking milestone complete | `POST` | `/api/contracts/bookings/:bookingId/milestones/:code/complete` | `modules/contracts/contracts.controller.ts:1205` |
+| GL ET assigns a customs risk level (GREEN/YELLOW/RED) | `POST` | `/api/contracts/bookings/:bookingId/risk` | `modules/contracts/contracts.controller.ts:1241` |
+| GL ET advises (or skips) the post-arrival additional duty/tax round (import) | `POST` | `/api/contracts/bookings/:bookingId/second-duty` | `modules/contracts/contracts.controller.ts:1399` |
+| Customer attaches the additional duty/tax payment slip | `POST` | `/api/contracts/bookings/:bookingId/second-duty-slip` | `modules/contracts/contracts.controller.ts:1429` |
+| GL station manager routes the shipment + binds staff | `POST` | `/api/contracts/bookings/:bookingId/station-assign` | `modules/contracts/contracts.controller.ts:1276` |
+| Close (accept) the T1 set — GL ET after arrival (import) / GL DJ after gate pass (export) | `POST` | `/api/contracts/bookings/:bookingId/t1-close` | `modules/contracts/contracts.controller.ts:1316` |
+| GL Djibouti uploads T1 transit documents (multi-file) after wagon allocation; locked once the train departs | `POST` | `/api/contracts/bookings/:bookingId/t1-documents` | `modules/contracts/contracts.controller.ts:1301` |
+| GL ET uploads export transit permit documents (multi-file) | `POST` | `/api/contracts/bookings/:bookingId/transport-document` | `modules/contracts/contracts.controller.ts:1289` |
+| Share a document with the other GL desk | `POST` | `/api/gl-exchange/:entityId` | `modules/contracts/gl-exchange.controller.ts:59` |
+| Edit this contract\'s document articles only (per-contract; never touches the six shared templates) | `PUT` | `/api/contracts/:id/document/articles` | `modules/contracts/contracts.controller.ts:441` |
+| Update contract | `PATCH` | `/api/contracts/:id` | `modules/contracts/contracts.controller.ts:327` |
+| Uploader edits a shared document (title, visibility, file) | `PATCH` | `/api/gl-exchange/documents/:documentId` | `modules/contracts/gl-exchange.controller.ts:79` |
+| Soft-delete DRAFT contract | `DELETE` | `/api/contracts/:id` | `modules/contracts/contracts.controller.ts:346` |
+| Uploader removes a shared document | `DELETE` | `/api/gl-exchange/documents/:documentId` | `modules/contracts/gl-exchange.controller.ts:105` |
+
+### Contract Template
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a bulk contract template for a (cargo type, customs option) pair | `POST` | `/api/contract-templates` | `modules/contract-templates/contract-templates.controller.ts:56` |
+| Add an article to the template | `POST` | `/api/contract-templates/:code/articles` | `modules/contract-templates/contract-templates.controller.ts:118` |
+| Render an HTML preview of the template against mock contract data | `POST` | `/api/contract-templates/:code/preview` | `modules/contract-templates/contract-templates.controller.ts:97` |
+| Replace the full ordered article list (used for reorder) | `PUT` | `/api/contract-templates/:code/articles` | `modules/contract-templates/contract-templates.controller.ts:111` |
+| Update template metadata (name, title, recitals, active flag) | `PATCH` | `/api/contract-templates/:code` | `modules/contract-templates/contract-templates.controller.ts:77` |
+| Update an article's title or body | `PATCH` | `/api/contract-templates/:code/articles/:articleId` | `modules/contract-templates/contract-templates.controller.ts:125` |
+| Delete a staff-created bulk template (system templates refuse) | `DELETE` | `/api/contract-templates/:code` | `modules/contract-templates/contract-templates.controller.ts:84` |
+| Remove an article from the template | `DELETE` | `/api/contract-templates/:code/articles/:articleId` | `modules/contract-templates/contract-templates.controller.ts:136` |
+
+### Driver
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a new driver | `POST` | `/api/drivers` | `modules/drivers/drivers.controller.ts:41` |
+| Upload driver documents (code driver_docs) | `POST` | `/api/drivers/:id/documents` | `modules/drivers/drivers.controller.ts:80` |
+| Update a driver | `PATCH` | `/api/drivers/:id` | `modules/drivers/drivers.controller.ts:128` |
+| Delete a driver | `DELETE` | `/api/drivers/:id` | `modules/drivers/drivers.controller.ts:138` |
+| Delete a driver document | `DELETE` | `/api/drivers/:id/documents/:fileId` | `modules/drivers/drivers.controller.ts:121` |
+
+### Dropdown Setting
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a new dropdown setting | `POST` | `/api/dropdown-settings` | `modules/dropdown-settings/dropdown-settings.controller.ts:61` |
+| Append a single option to a setting | `POST` | `/api/dropdown-settings/:id/options` | `modules/dropdown-settings/dropdown-settings.controller.ts:98` |
+| Replace the full option list for a setting | `PUT` | `/api/dropdown-settings/:id/options` | `modules/dropdown-settings/dropdown-settings.controller.ts:88` |
+| Update a dropdown setting's metadata | `PATCH` | `/api/dropdown-settings/:id` | `modules/dropdown-settings/dropdown-settings.controller.ts:68` |
+| Update a single option | `PATCH` | `/api/dropdown-settings/options/:optionId` | `modules/dropdown-settings/dropdown-settings.controller.ts:108` |
+| Soft-delete a dropdown setting | `DELETE` | `/api/dropdown-settings/:id` | `modules/dropdown-settings/dropdown-settings.controller.ts:78` |
+| Soft-delete a single option | `DELETE` | `/api/dropdown-settings/options/:optionId` | `modules/dropdown-settings/dropdown-settings.controller.ts:118` |
+
+### EIMS Invoice
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Register the invoice with MoR EIMS. Idempotent — an invoice that already has an IRN is returned unchanged | `POST` | `/api/invoices/:id/eims/register` | `modules/eims/eims-invoice.controller.ts:32` |
+| Resolve an unacknowledged submission: record the IRN confirmed with MoR, or discard it. Clears the system-wide block | `POST` | `/api/invoices/:id/eims/resolve` | `modules/eims/eims-invoice.controller.ts:49` |
+| Verify the invoice's stored IRN against EIMS | `POST` | `/api/invoices/:id/eims/verify` | `modules/eims/eims-invoice.controller.ts:42` |
+
+### Exchange Setting
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Set the USD→ETB fallback by hand (used only while CBE is unreachable) | `PATCH` | `/api/exchange-settings` | `modules/exchange-settings/exchange-settings.controller.ts:35` |
+
+### Facility
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a new facility | `POST` | `/api/facilities` | `modules/facilities/facilities.controller.ts:22` |
+| Update a facility | `PATCH` | `/api/facilities/:id` | `modules/facilities/facilities.controller.ts:41` |
+| Delete a facility (soft delete) | `DELETE` | `/api/facilities/:id` | `modules/facilities/facilities.controller.ts:48` |
+
+### Fayda Verification
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Start a VeriFayda 2.0 verification session | `POST` | `/api/fayda/verification/start` | `modules/verifayda/verifayda.controller.ts:44` |
+
+### File Upload Setting
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a new file upload setting | `POST` | `/api/file-upload-settings` | `modules/file-upload-settings/file-upload-settings.controller.ts:56` |
+| Append a single field to a setting | `POST` | `/api/file-upload-settings/:id/fields` | `modules/file-upload-settings/file-upload-settings.controller.ts:93` |
+| Replace the full field list for a setting | `PUT` | `/api/file-upload-settings/:id/fields` | `modules/file-upload-settings/file-upload-settings.controller.ts:83` |
+| Update a file upload setting's metadata | `PATCH` | `/api/file-upload-settings/:id` | `modules/file-upload-settings/file-upload-settings.controller.ts:63` |
+| Update a single field | `PATCH` | `/api/file-upload-settings/fields/:fieldId` | `modules/file-upload-settings/file-upload-settings.controller.ts:103` |
+| Soft-delete a file upload setting | `DELETE` | `/api/file-upload-settings/:id` | `modules/file-upload-settings/file-upload-settings.controller.ts:73` |
+| Soft-delete a single field | `DELETE` | `/api/file-upload-settings/fields/:fieldId` | `modules/file-upload-settings/file-upload-settings.controller.ts:113` |
+
+### First Mile
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a first-mile leg | `POST` | `/api/first-mile` | `modules/first-mile/first-mile.controller.ts:84` |
+| Set per-vehicle actual distances (does not generate an invoice) | `POST` | `/api/first-mile/:id/distances` | `modules/first-mile/first-mile.controller.ts:124` |
+| Generate the first-mile delivery-fee invoice | `POST` | `/api/first-mile/:id/invoice` | `modules/first-mile/first-mile.controller.ts:100` |
+| Set the vehicles assigned to a first-mile pickup (multi-truck) | `POST` | `/api/first-mile/:id/vehicles` | `modules/first-mile/first-mile.controller.ts:114` |
+| Accept a paid booking and create a first-mile leg | `POST` | `/api/first-mile/accept/:reference` | `modules/first-mile/first-mile.controller.ts:77` |
+| Update a first-mile leg | `PATCH` | `/api/first-mile/:id` | `modules/first-mile/first-mile.controller.ts:91` |
+| Soft-delete a first-mile leg | `DELETE` | `/api/first-mile/:id` | `modules/first-mile/first-mile.controller.ts:134` |
+
+### Fuel
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Record fuel purchase | `POST` | `/api/fuel/purchases` | `modules/fuel/fuel.controller.ts:22` |
+
+### GPS Tracking
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Register a GPS tracker | `POST` | `/api/gps/devices` | `modules/gps-tracking/gps-tracking.controller.ts:52` |
+| Update a GPS tracker (name / assigned vehicle) | `PATCH` | `/api/gps/devices/:id` | `modules/gps-tracking/gps-tracking.controller.ts:59` |
+| Delete a GPS tracker | `DELETE` | `/api/gps/devices/:id` | `modules/gps-tracking/gps-tracking.controller.ts:66` |
+
+### Import Operation
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Batch 12: record declaration serial number | `POST` | `/api/import-operations/customs/:bookingId/declaration` | `modules/import-operations/import-operations.controller.ts:53` |
+| Batch 12: upload IM4/IM5/T1/permit/payment-slip documents | `POST` | `/api/import-operations/customs/:bookingId/documents` | `modules/import-operations/import-operations.controller.ts:44` |
+| Batch 12: mark duties and taxes paid | `POST` | `/api/import-operations/customs/:bookingId/duties-taxes-paid` | `modules/import-operations/import-operations.controller.ts:71` |
+| Batch 12: notify duties and taxes | `POST` | `/api/import-operations/customs/:bookingId/notify-duties-taxes` | `modules/import-operations/import-operations.controller.ts:62` |
+| Batch 12: mark import release permitted | `POST` | `/api/import-operations/customs/:bookingId/release-permitted` | `modules/import-operations/import-operations.controller.ts:86` |
+| Batch 12: assign customs risk | `POST` | `/api/import-operations/customs/:bookingId/risk` | `modules/import-operations/import-operations.controller.ts:80` |
+| Batch 8: report a Djibouti import incident / exception | `POST` | `/api/import-operations/djibouti-incidents` | `modules/import-operations/import-operations.controller.ts:32` |
+| Batch 16: create an empty container return record | `POST` | `/api/import-operations/empty-container-returns` | `modules/import-operations/import-operations.controller.ts:101` |
+| Batch 16: advance empty container return workflow | `POST` | `/api/import-operations/empty-container-returns/:id/status` | `modules/import-operations/import-operations.controller.ts:107` |
+
+### Incident
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Report an incident | `POST` | `/api/incidents` | `modules/incidents/incidents.controller.ts:36` |
+| Update an incident | `PATCH` | `/api/incidents/:id` | `modules/incidents/incidents.controller.ts:72` |
+| Delete an incident | `DELETE` | `/api/incidents/:id` | `modules/incidents/incidents.controller.ts:79` |
+
+### Interchange Document
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Generate interchange document from a train schedule handover | `POST` | `/api/interchange-documents/generate-from-schedule` | `modules/interchange-documents/interchange-documents.controller.ts:41` |
+| Acknowledge an interchange document | `PATCH` | `/api/interchange-documents/:id/acknowledge` | `modules/interchange-documents/interchange-documents.controller.ts:48` |
+| Dispute an interchange document | `PATCH` | `/api/interchange-documents/:id/dispute` | `modules/interchange-documents/interchange-documents.controller.ts:58` |
+
+### Last Mile
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a last-mile leg | `POST` | `/api/last-mile` | `modules/last-mile/last-mile.controller.ts:97` |
+| Set each truck\'s own detention window (arrived at destination / returned) | `POST` | `/api/last-mile/:id/detention-times` | `modules/last-mile/last-mile.controller.ts:142` |
+| Set per-vehicle actual distances (does not generate an invoice) | `POST` | `/api/last-mile/:id/distances` | `modules/last-mile/last-mile.controller.ts:132` |
+| Generate the delivery-fee invoice for a last-mile leg | `POST` | `/api/last-mile/:id/invoice` | `modules/last-mile/last-mile.controller.ts:179` |
+| Record proof of delivery (signature + photos) and complete the leg | `POST` | `/api/last-mile/:id/proof-of-delivery` | `modules/last-mile/last-mile.controller.ts:166` |
+| Set the vehicles assigned to a last-mile delivery (multi-truck) | `POST` | `/api/last-mile/:id/vehicles` | `modules/last-mile/last-mile.controller.ts:122` |
+| Set each truck\'s warehouse gate arrival/departure times | `POST` | `/api/last-mile/:id/warehouse-gate-times` | `modules/last-mile/last-mile.controller.ts:154` |
+| Accept a paid booking and create a last-mile leg | `POST` | `/api/last-mile/accept/:reference` | `modules/last-mile/last-mile.controller.ts:90` |
+| Update a last-mile leg | `PATCH` | `/api/last-mile/:id` | `modules/last-mile/last-mile.controller.ts:104` |
+| Soft-delete a last-mile leg | `DELETE` | `/api/last-mile/:id` | `modules/last-mile/last-mile.controller.ts:113` |
+
+### Last Mile Request
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Truck & Machinery chief approves the request — the advance defaults to the live last-mile rate; LM contract becomes signable and the advance invoice follows the customer signature | `POST` | `/api/last-mile-requests/:id/approve` | `modules/last-mile-requests/last-mile-requests.controller.ts:119` |
+| Customer agrees and signs the LM contract — then the advance invoice is issued | `POST` | `/api/last-mile-requests/:id/contract/sign` | `modules/last-mile-requests/last-mile-requests.controller.ts:83` |
+| Truck & Machinery chief rejects the request with a reason | `POST` | `/api/last-mile-requests/:id/reject` | `modules/last-mile-requests/last-mile-requests.controller.ts:130` |
+| Customer confirms which containers go via EDR last-mile | `POST` | `/api/last-mile-requests/:id/submit` | `modules/last-mile-requests/last-mile-requests.controller.ts:108` |
+
+### Locomotive
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a locomotive | `POST` | `/api/locomotives` | `modules/locomotives/locomotives.controller.ts:58` |
+| Decommission a locomotive | `POST` | `/api/locomotives/:id/decommission` | `modules/locomotives/locomotives.controller.ts:72` |
+| Update a locomotive | `PATCH` | `/api/locomotives/:id` | `modules/locomotives/locomotives.controller.ts:65` |
+| Permanently delete a locomotive (irreversible; refused if any train references it) | `DELETE` | `/api/locomotives/:id/permanent` | `modules/locomotives/locomotives.controller.ts:82` |
+
+### Maintenance
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Record maintenance cost | `POST` | `/api/maintenance/costs` | `modules/maintenance/maintenance.controller.ts:38` |
+| Define/adjust a service interval (e.g. oil change every 10,000 km) | `POST` | `/api/maintenance/intervals` | `modules/maintenance/maintenance.controller.ts:59` |
+| Create part | `POST` | `/api/maintenance/parts` | `modules/maintenance/maintenance.controller.ts:150` |
+| Schedule maintenance | `POST` | `/api/maintenance/schedules` | `modules/maintenance/maintenance.controller.ts:31` |
+| Create warranty | `POST` | `/api/maintenance/warranties` | `modules/maintenance/maintenance.controller.ts:186` |
+| Create work order | `POST` | `/api/maintenance/work-orders` | `modules/maintenance/maintenance.controller.ts:110` |
+| Update part | `PATCH` | `/api/maintenance/parts/:id` | `modules/maintenance/maintenance.controller.ts:170` |
+| Update maintenance schedule | `PATCH` | `/api/maintenance/schedules/:id` | `modules/maintenance/maintenance.controller.ts:45` |
+| Update work order | `PATCH` | `/api/maintenance/work-orders/:id` | `modules/maintenance/maintenance.controller.ts:134` |
+| Deactivate a service interval (stops auto-scheduling) | `DELETE` | `/api/maintenance/intervals/:id` | `modules/maintenance/maintenance.controller.ts:73` |
+| Delete part | `DELETE` | `/api/maintenance/parts/:id` | `modules/maintenance/maintenance.controller.ts:177` |
+| Delete warranty | `DELETE` | `/api/maintenance/warranties/:id` | `modules/maintenance/maintenance.controller.ts:200` |
+| Delete work order | `DELETE` | `/api/maintenance/work-orders/:id` | `modules/maintenance/maintenance.controller.ts:141` |
+
+### Notification Inbox
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Mark all my notifications as read | `POST` | `/api/notifications/read-all` | `modules/notification-inbox/notification-inbox.controller.ts:53` |
+| Mark one of my notifications as read | `PATCH` | `/api/notifications/:id/read` | `modules/notification-inbox/notification-inbox.controller.ts:44` |
+
+### Organization User
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create an organization user without assigning positions | `POST` | `/api/backoffice/organizations/:orgId/users` | `modules/backoffice/backoffice.controller.ts:24` |
+| Replace org-scoped roles assigned to an employee user | `PUT` | `/api/backoffice/organizations/:orgId/employee-users/:userId/roles` | `modules/backoffice/backoffice.controller.ts:58` |
+
+### OTP
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Send OTP | `POST` | `/api/otp/send` | `modules/otp/otp.controller.ts:41` |
+| Verify OTP | `POST` | `/api/otp/verify` | `modules/otp/otp.controller.ts:62` |
+
+### Password Reset
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Send a password-reset code to the account's email AND phone | `POST` | `/api/auth/forgot-password/request` | `modules/auth/forgot-password.controller.ts:30` |
+| Validate a staff-issued reset link and return its set-password ticket | `POST` | `/api/auth/forgot-password/resolve-link` | `modules/auth/forgot-password.controller.ts:73` |
+| Exchange a valid reset code for a single-use set-password ticket | `POST` | `/api/auth/forgot-password/verify` | `modules/auth/forgot-password.controller.ts:62` |
+| Send a password-reset link to a customer's primary contact | `POST` | `/api/backoffice/customers/:companyId/reset-password` | `modules/auth/customer-reset.controller.ts:49` |
+
+### Payment
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Finance confirms a USD invoice paid by bank transfer — slip file required, settles the full balance | `POST` | `/api/billing/invoices/:id/confirm-offline` | `modules/billing/billing.controller.ts:81` |
+| Confirm an OTP-debit payment (CAC Bank) for one of the customer's invoices | `POST` | `/api/billing/my-invoices/:id/confirm` | `modules/billing/portal-billing.controller.ts:102` |
+| Initiate payment for one of the customer's invoices | `POST` | `/api/billing/my-invoices/:id/pay` | `modules/billing/portal-billing.controller.ts:86` |
+| Live still-payable check + payer name for a CBE bill (called while CBE is on the line) | `POST` | `/api/internal/payments/bill-query` | `modules/payment/internal-payment.controller.ts:56` |
+| Apply a payment.succeeded / payment.failed event from the payment service (idempotent) | `POST` | `/api/internal/payments/mark-paid` | `modules/payment/internal-payment.controller.ts:45` |
+| Initiate payment for an invoice | `POST` | `/api/payments/initiate` | `modules/billing/payment.controller.ts:39` |
+| Success-redirect ack: mark payment processing + invoice PAYMENT_PROCESSING (webhook remains source of truth) | `POST` | `/api/payments/redirect-success/:bookingId` | `modules/payment/payment.controller.ts:89` |
+
+### Priority Config
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a priority config | `POST` | `/api/priority-configs` | `modules/rule-engine/controllers/priority-configs.controller.ts:51` |
+| Move a priority config up or down in display order | `POST` | `/api/priority-configs/:id/move-order` | `modules/rule-engine/controllers/priority-configs.controller.ts:66` |
+| Bulk reorder priority configs by ID list | `POST` | `/api/priority-configs/reorder` | `modules/rule-engine/controllers/priority-configs.controller.ts:58` |
+| Update a priority config | `PATCH` | `/api/priority-configs/:id` | `modules/rule-engine/controllers/priority-configs.controller.ts:74` |
+| Soft-delete a priority config | `DELETE` | `/api/priority-configs/:id` | `modules/rule-engine/controllers/priority-configs.controller.ts:81` |
+
+### Priority Rule Change Request
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Submit a priority-rule change for approval | `POST` | `/api/priority-rule-change-requests` | `modules/rule-engine/controllers/priority-rule-change-requests.controller.ts:34` |
+| Approve and apply a pending change | `POST` | `/api/priority-rule-change-requests/:id/approve` | `modules/rule-engine/controllers/priority-rule-change-requests.controller.ts:52` |
+| Reject a pending change | `POST` | `/api/priority-rule-change-requests/:id/reject` | `modules/rule-engine/controllers/priority-rule-change-requests.controller.ts:65` |
+
+### Procurement
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create an asset acquisition | `POST` | `/api/procurement/acquisitions` | `modules/procurement/procurement.controller.ts:56` |
+| Create an asset disposal | `POST` | `/api/procurement/disposals` | `modules/procurement/procurement.controller.ts:90` |
+| Create a vendor | `POST` | `/api/procurement/vendors` | `modules/procurement/procurement.controller.ts:28` |
+| Update an asset acquisition | `PATCH` | `/api/procurement/acquisitions/:id` | `modules/procurement/procurement.controller.ts:75` |
+| Update a vendor | `PATCH` | `/api/procurement/vendors/:id` | `modules/procurement/procurement.controller.ts:41` |
+| Delete an asset acquisition | `DELETE` | `/api/procurement/acquisitions/:id` | `modules/procurement/procurement.controller.ts:82` |
+| Delete an asset disposal | `DELETE` | `/api/procurement/disposals/:id` | `modules/procurement/procurement.controller.ts:103` |
+| Delete a vendor | `DELETE` | `/api/procurement/vendors/:id` | `modules/procurement/procurement.controller.ts:48` |
+
+### Rate
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a rate (DRAFT) | `POST` | `/api/rates` | `modules/rule-engine/controllers/rates.controller.ts:46` |
+| CEO approves a rate | `POST` | `/api/rates/:id/approve` | `modules/rule-engine/controllers/rates.controller.ts:70` |
+| Submit rate for CEO approval | `POST` | `/api/rates/:id/submit` | `modules/rule-engine/controllers/rates.controller.ts:63` |
+| Update a DRAFT rate | `PATCH` | `/api/rates/:id` | `modules/rule-engine/controllers/rates.controller.ts:56` |
+| Soft-delete a rate | `DELETE` | `/api/rates/:id` | `modules/rule-engine/controllers/rates.controller.ts:82` |
+
+### Rate Change Request
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Propose a change to a LIVE rate | `POST` | `/api/rate-change-requests` | `modules/rule-engine/controllers/rate-change-requests.controller.ts:23` |
+| Approve a rate change and put it into effect | `POST` | `/api/rate-change-requests/:id/approve` | `modules/rule-engine/controllers/rate-change-requests.controller.ts:37` |
+| Reject a rate change — the rate keeps its current value | `POST` | `/api/rate-change-requests/:id/reject` | `modules/rule-engine/controllers/rate-change-requests.controller.ts:48` |
+
+### Route
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create route | `POST` | `/api/routes` | `modules/routes/routes.controller.ts:61` |
+| Update route | `PATCH` | `/api/routes/:id` | `modules/routes/routes.controller.ts:68` |
+| Deactivate route | `DELETE` | `/api/routes/:id` | `modules/routes/routes.controller.ts:90` |
+| Permanently delete a route (irreversible; refused while any train schedule references it) | `DELETE` | `/api/routes/:id/permanent` | `modules/routes/routes.controller.ts:79` |
+
+### Schedule
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Reschedule train for maintenance (new departure + rebalance) | `POST` | `/api/train-scheduling/schedules/:id/maintenance` | `modules/scheduling-reschedule/scheduling-reschedule.controller.ts:52` |
+| Execute a confirmed reschedule plan | `POST` | `/api/train-scheduling/schedules/:id/reschedule/execute` | `modules/scheduling-reschedule/scheduling-reschedule.controller.ts:30` |
+| Preview reschedule / government preempt plan | `POST` | `/api/train-scheduling/schedules/:id/reschedule/preview` | `modules/scheduling-reschedule/scheduling-reschedule.controller.ts:20` |
+
+### Service Type
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a service type | `POST` | `/api/service-types` | `modules/rule-engine/controllers/service-types.controller.ts:51` |
+| Move a service type up or down in display order | `POST` | `/api/service-types/:id/move-order` | `modules/rule-engine/controllers/service-types.controller.ts:36` |
+| Bulk reorder service types by ID list | `POST` | `/api/service-types/reorder` | `modules/rule-engine/controllers/service-types.controller.ts:28` |
+| Update a service type | `PATCH` | `/api/service-types/:id` | `modules/rule-engine/controllers/service-types.controller.ts:58` |
+| Soft-delete a service type | `DELETE` | `/api/service-types/:id` | `modules/rule-engine/controllers/service-types.controller.ts:65` |
+
+### Shipping Line
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a shipping line | `POST` | `/api/shipping-lines` | `modules/rule-engine/controllers/shipping-lines.controller.ts:33` |
+| Update a shipping line | `PATCH` | `/api/shipping-lines/:id` | `modules/rule-engine/controllers/shipping-lines.controller.ts:40` |
+| Soft-delete a shipping line | `DELETE` | `/api/shipping-lines/:id` | `modules/rule-engine/controllers/shipping-lines.controller.ts:47` |
+
+### Signature
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create or update the reusable saved signature | `PUT` | `/api/me/signature` | `modules/signatures/signatures.controller.ts:23` |
+
+### Support Chat
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Start chatting with a company (returns the thread if one exists) | `POST` | `/api/support/agent/conversations` | `modules/support-chat/support-chat-agent.controller.ts:49` |
+| Reply as an agent, optionally with attachments | `POST` | `/api/support/agent/conversations/:id/messages` | `modules/support-chat/support-chat-agent.controller.ts:74` |
+| Mark a thread read (agent side) | `POST` | `/api/support/agent/conversations/:id/read` | `modules/support-chat/support-chat-agent.controller.ts:114` |
+| Send a message as the customer (optionally with attachments), opening the thread if needed | `POST` | `/api/support/conversation/messages` | `modules/support-chat/support-chat.controller.ts:65` |
+| Mark my company's thread read (customer side) | `POST` | `/api/support/conversation/read` | `modules/support-chat/support-chat.controller.ts:102` |
+
+### Support Content
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Restore a version — re-saves it as a new version, never destructive | `POST` | `/api/support-content/documents/:slug/versions/:version/restore` | `modules/support-content/support-content.controller.ts:123` |
+| Upload an image or video for a help section | `POST` | `/api/support-content/media` | `modules/support-content/support-content.controller.ts:55` |
+| Replace a document's payload, recording a new version | `PATCH` | `/api/support-content/documents/:slug` | `modules/support-content/support-content.controller.ts:93` |
+
+### Train
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Register a new train | `POST` | `/api/trains` | `modules/trains/trains.controller.ts:33` |
+| Update a train | `PATCH` | `/api/trains/:id` | `modules/trains/trains.controller.ts:52` |
+| Delete a train | `DELETE` | `/api/trains/:id` | `modules/trains/trains.controller.ts:59` |
+
+### Train Build
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Build a train: code + yard + 2+ locomotives (+ optional wagons) | `POST` | `/api/train-builder` | `modules/trains/train-builder.controller.ts:50` |
+| Reactivate a deactivated train back to AVAILABLE | `POST` | `/api/train-builder/:id/activate` | `modules/trains/train-builder.controller.ts:158` |
+| Deactivate the train (park it) — only allowed with no active schedule | `POST` | `/api/train-builder/:id/deactivate` | `modules/trains/train-builder.controller.ts:149` |
+| Persist a drag-reorder of the full consist | `POST` | `/api/train-builder/:id/reorder-wagons` | `modules/trains/train-builder.controller.ts:142` |
+| Append AVAILABLE wagons from the train's yard to the consist | `POST` | `/api/train-builder/:id/wagons` | `modules/trains/train-builder.controller.ts:109` |
+| Detach one wagon and move it to MAINTENANCE status | `POST` | `/api/train-builder/:id/wagons/:wagonId/maintenance` | `modules/trains/train-builder.controller.ts:131` |
+| Replace the locomotive set (minimum 1, same yard) | `PUT` | `/api/train-builder/:id/locomotives` | `modules/trains/train-builder.controller.ts:78` |
+| Edit the train's name and fixed import/export run numbers | `PATCH` | `/api/train-builder/:id/details` | `modules/trains/train-builder.controller.ts:88` |
+| Relocate the train — its locomotives and wagons move to the new yard with it | `PATCH` | `/api/train-builder/:id/yard` | `modules/trains/train-builder.controller.ts:100` |
+| Disband the train (release wagons and locomotives) | `DELETE` | `/api/train-builder/:id` | `modules/trains/train-builder.controller.ts:165` |
+| Detach one wagon from the consist | `DELETE` | `/api/train-builder/:id/wagons/:wagonId` | `modules/trains/train-builder.controller.ts:120` |
+
+### Train Schedule
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Staff: place a paid booking onto a fitting train (notifies customer on date change) | `POST` | `/api/train-scheduling/bookings/:bookingId/allocate` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:880` |
+| Staff: expire a reservation and free its capacity | `POST` | `/api/train-scheduling/bookings/:bookingId/expire` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:845` |
+| Staff: mark a reserved booking paid and allocate it now | `POST` | `/api/train-scheduling/bookings/:bookingId/mark-paid` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:835` |
+| Re-point a booking to another OPEN same-route schedule | `POST` | `/api/train-scheduling/bookings/:bookingId/move-schedule` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:855` |
+| Preview a bulk train schedule | `POST` | `/api/train-scheduling/bulk/preview` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:302` |
+| Create a bulk train schedule | `POST` | `/api/train-scheduling/bulk/schedules` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:316` |
+| Assign bulk bookings to a train schedule | `POST` | `/api/train-scheduling/bulk/schedules/:id/assign-bookings` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:349` |
+| Cancel bulk train schedule | `POST` | `/api/train-scheduling/bulk/schedules/:id/cancel` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:976` |
+| Preview a container train schedule | `POST` | `/api/train-scheduling/container/preview` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:295` |
+| Create a container train schedule | `POST` | `/api/train-scheduling/container/schedules` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:309` |
+| Assign container bookings to a train schedule | `POST` | `/api/train-scheduling/container/schedules/:id/assign-bookings` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:335` |
+| Cancel container train schedule | `POST` | `/api/train-scheduling/container/schedules/:id/cancel` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:969` |
+| Preview a mixed-capable train schedule | `POST` | `/api/train-scheduling/preview` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:288` |
+| Permanently trim free wagons off / couple yard wagons onto the schedule's built train (weight & length limits incl. tolerance enforced, every change logged) | `POST` | `/api/train-scheduling/schedules/:id/adjust-consist` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:197` |
+| Mark a dispatched train arrived (move assets to destination yard, free assets) | `POST` | `/api/train-scheduling/schedules/:id/arrive` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:915` |
+| Assign bookings to a train schedule (mixed-capable) | `POST` | `/api/train-scheduling/schedules/:id/assign-bookings` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:323` |
+| Assign one linked unallocated booking to wagons (preserves existing assignments) | `POST` | `/api/train-scheduling/schedules/:id/assign-unassigned-booking` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:423` |
+| Confirm a booking's cargo loaded at its origin yard (any direction; train must be at that yard) | `POST` | `/api/train-scheduling/schedules/:id/bookings/:bookingId/load` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:564` |
+| Confirm a booking's cargo unloaded at its destination yard — per-booking arrival, may precede the train's final arrival | `POST` | `/api/train-scheduling/schedules/:id/bookings/:bookingId/unload` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:577` |
+| Log the train passing a station (final station triggers arrival) | `POST` | `/api/train-scheduling/schedules/:id/checkpoints` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:903` |
+| Confirm cargo loaded on the train (any direction; unblocks import-Djibouti dispatch) | `POST` | `/api/train-scheduling/schedules/:id/confirm-loading` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:662` |
+| Dispatch a scheduled train | `POST` | `/api/train-scheduling/schedules/:id/dispatch` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:514` |
+| Staff finished document review early — run the batch/payment phase now (applies to the whole route-day group) | `POST` | `/api/train-scheduling/schedules/:id/doc-review-complete` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:824` |
+| Finalize a draft train schedule | `POST` | `/api/train-scheduling/schedules/:id/finalize` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:507` |
+| Depart loaded import train from Djibouti | `POST` | `/api/train-scheduling/schedules/:id/import-djibouti/depart` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:675` |
+| Upload/check an import Djibouti-side document | `POST` | `/api/train-scheduling/schedules/:id/import-djibouti/documents` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:622` |
+| Mark import Djibouti gatepass permission granted | `POST` | `/api/train-scheduling/schedules/:id/import-djibouti/gatepass-granted` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:632` |
+| Generate import load list / marshalling document summary | `POST` | `/api/train-scheduling/schedules/:id/import-djibouti/load-list` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:685` |
+| Confirm import cargo loaded on train at Djibouti | `POST` | `/api/train-scheduling/schedules/:id/import-djibouti/loaded-on-train` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:652` |
+| Mark import train ready for loading at Djibouti | `POST` | `/api/train-scheduling/schedules/:id/import-djibouti/ready-for-loading` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:642` |
+| Confirm intercity cargo loaded (train must be at the booking's origin yard) | `POST` | `/api/train-scheduling/schedules/:id/intercity/:bookingId/load` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:590` |
+| Confirm intercity cargo unloaded at the booking's destination yard (completes the booking) | `POST` | `/api/train-scheduling/schedules/:id/intercity/:bookingId/unload` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:602` |
+| Accept intercity bookings onto this train (opens their pay window; capacity re-checked per booking) | `POST` | `/api/train-scheduling/schedules/:id/intercity/accept` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:541` |
+| Maintenance reschedule: move the train to a new departure with every allocated booking aboard — links, wagons and window settings unchanged | `POST` | `/api/train-scheduling/schedules/:id/maintenance` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:798` |
+| Pin physical wagons to train set slots | `POST` | `/api/train-scheduling/schedules/:id/pin-wagons` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:500` |
+| Run wagon-level allocation for all eligible linked bookings | `POST` | `/api/train-scheduling/schedules/:id/run-allocation` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:747` |
+| Manually run the batch fill for a schedule | `POST` | `/api/train-scheduling/schedules/:id/run-batch` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:739` |
+| Switch out commercial bookings to allocate a government booking in their place | `POST` | `/api/train-scheduling/schedules/:id/switch-government-booking` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:439` |
+| Move a wagon's whole load to another wagon (empty → move/repin, loaded → swap loads) | `POST` | `/api/train-scheduling/schedules/:id/wagons/:wagonId/move-load` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:402` |
+| Update global train scheduling rules (singleton) | `PATCH` | `/api/train-scheduling/global-rules` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:124` |
+| Open or close a schedule booking window | `PATCH` | `/api/train-scheduling/schedules/:id/booking-window` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:756` |
+| Update a container number on a wagon slot | `PATCH` | `/api/train-scheduling/schedules/:id/container-items/:itemId` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:391` |
+| Mark import bookings loaded/unloaded on this schedule (tracking only, does not affect dispatch) | `PATCH` | `/api/train-scheduling/schedules/:id/import-loading-status` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:474` |
+| Mark bookings loaded/unloaded on this schedule (any direction, pre-dispatch only) | `PATCH` | `/api/train-scheduling/schedules/:id/loading-status` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:487` |
+| Reschedule a train's departure date — only before the booking window opens, and only if the new date still leaves room for the booking lead window | `PATCH` | `/api/train-scheduling/schedules/:id/schedule-date` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:784` |
+| Override the booking-window rule for one schedule (open/close hour, duration, doc-review, payment, lead days) — only before the window opens | `PATCH` | `/api/train-scheduling/schedules/:id/window-rule` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:770` |
+| Unassign a booking from a train schedule | `DELETE` | `/api/train-scheduling/schedules/:id/bookings/:bookingId` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:363` |
+| Remove an empty wagon slot from a train | `DELETE` | `/api/train-scheduling/schedules/:id/wagons/:trainSetWagonId` | `modules/train-scheduling/controllers/train-scheduling.controller.ts:378` |
+
+### Transit Agent
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a transit agent | `POST` | `/api/transit-agents` | `modules/transit-agents/transit-agents.controller.ts:66` |
+| Update a transit agent | `PATCH` | `/api/transit-agents/:id` | `modules/transit-agents/transit-agents.controller.ts:73` |
+| Soft-delete a transit agent | `DELETE` | `/api/transit-agents/:id` | `modules/transit-agents/transit-agents.controller.ts:80` |
+
+### Truck Type
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a truck type | `POST` | `/api/truck-types` | `modules/truck-types/truck-types.controller.ts:58` |
+| Update a truck type | `PATCH` | `/api/truck-types/:id` | `modules/truck-types/truck-types.controller.ts:65` |
+| Soft-delete a truck type | `DELETE` | `/api/truck-types/:id` | `modules/truck-types/truck-types.controller.ts:72` |
+
+### User Trade Access
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Set the trade directions a backoffice user may see | `PUT` | `/api/user-trade-access/:userId` | `modules/user-trade-access/user-trade-access.controller.ts:45` |
+
+### Vehicle
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a new vehicle | `POST` | `/api/vehicles` | `modules/vehicles/vehicles.controller.ts:37` |
+| Update a vehicle | `PATCH` | `/api/vehicles/:id` | `modules/vehicles/vehicles.controller.ts:78` |
+| Delete a vehicle | `DELETE` | `/api/vehicles/:id` | `modules/vehicles/vehicles.controller.ts:88` |
+
+### Wagon
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a new wagon | `POST` | `/api/wagons` | `modules/wagons/wagons.controller.ts:39` |
+| Assign wagon to a train | `POST` | `/api/wagons/:id/assign-train` | `modules/wagons/wagons.controller.ts:100` |
+| Unassign wagon from train | `POST` | `/api/wagons/:id/unassign-train` | `modules/wagons/wagons.controller.ts:107` |
+| Set the status of multiple wagons (audited in wagon_status_logs) | `POST` | `/api/wagons/bulk-status` | `modules/wagons/wagons.controller.ts:121` |
+| Transfer multiple wagons to a destination yard | `POST` | `/api/wagons/bulk-transfer` | `modules/wagons/wagons.controller.ts:114` |
+| Update a wagon | `PATCH` | `/api/wagons/:id` | `modules/wagons/wagons.controller.ts:71` |
+| Delete a wagon | `DELETE` | `/api/wagons/:id` | `modules/wagons/wagons.controller.ts:93` |
+| Permanently delete a wagon (irreversible; refused if it has movements, containers or train-set slots) | `DELETE` | `/api/wagons/:id/permanent` | `modules/wagons/wagons.controller.ts:82` |
+
+### Wagon Transfer Request
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| File a count-only wagon-transfer request | `POST` | `/api/wagon-transfer-requests` | `modules/wagons/wagon-transfer-requests.controller.ts:50` |
+| Withdraw a request that has not moved any wagon yet (use close-short once wagons have moved) | `POST` | `/api/wagon-transfer-requests/:id/cancel` | `modules/wagons/wagon-transfer-requests.controller.ts:167` |
+| OCC: end the request with fewer wagons than asked for — what moved stays, the requester is told the shortfall | `POST` | `/api/wagon-transfer-requests/:id/close-short` | `modules/wagons/wagon-transfer-requests.controller.ts:153` |
+| OCC: pick wagons and execute the transfer | `POST` | `/api/wagon-transfer-requests/:id/fulfill` | `modules/wagons/wagon-transfer-requests.controller.ts:142` |
+| OCC: accept-and-execute a subset of pending requests (auto-picks available wagons; the rest stay PENDING) | `POST` | `/api/wagon-transfer-requests/bulk-fulfill` | `modules/wagons/wagon-transfer-requests.controller.ts:73` |
+
+### Wagon Type
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a wagon type | `POST` | `/api/wagon-types` | `modules/wagon-types/wagon-types.controller.ts:53` |
+| Update a wagon type | `PATCH` | `/api/wagon-types/:id` | `modules/wagon-types/wagon-types.controller.ts:60` |
+| Soft-delete a wagon type | `DELETE` | `/api/wagon-types/:id` | `modules/wagon-types/wagon-types.controller.ts:67` |
+
+### Warehouse
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a warehouse allocation rule | `POST` | `/api/warehouse-allocation-rules` | `modules/warehouses/warehouse-rules.controller.ts:33` |
+| Preview the yard/warehouse/zone a booking would be allocated to | `POST` | `/api/warehouse-allocation/preview` | `modules/warehouses/warehouse-rules.controller.ts:55` |
+| Create a storage / demurrage fee rule | `POST` | `/api/warehouse-fee-rules` | `modules/warehouses/warehouse-rules.controller.ts:70` |
+| Acknowledge / snooze an item fee-accrual alert | `POST` | `/api/warehouse-fees/accrual/:inventoryId/acknowledge` | `modules/warehouses/warehouse-rules.controller.ts:106` |
+| Create warehouse | `POST` | `/api/warehouses` | `modules/warehouses/warehouses.controller.ts:51` |
+| Create a yard within a warehouse | `POST` | `/api/warehouses/:warehouseId/yards` | `modules/warehouses/warehouses.controller.ts:78` |
+| Update a warehouse allocation rule | `PATCH` | `/api/warehouse-allocation-rules/:id` | `modules/warehouses/warehouse-rules.controller.ts:40` |
+| Update a fee rule | `PATCH` | `/api/warehouse-fee-rules/:id` | `modules/warehouses/warehouse-rules.controller.ts:77` |
+| Update warehouse | `PATCH` | `/api/warehouses/:id` | `modules/warehouses/warehouses.controller.ts:64` |
+| Delete a warehouse allocation rule | `DELETE` | `/api/warehouse-allocation-rules/:id` | `modules/warehouses/warehouse-rules.controller.ts:47` |
+| Delete a fee rule | `DELETE` | `/api/warehouse-fee-rules/:id` | `modules/warehouses/warehouse-rules.controller.ts:84` |
+| Remove an accrual acknowledgement (re-surface for alerts) | `DELETE` | `/api/warehouse-fees/accrual/:inventoryId/acknowledge` | `modules/warehouses/warehouse-rules.controller.ts:119` |
+
+### Warehouse Fee Invoice
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Generate a truck-detention invoice for a last-mile leg (per truck per day) | `POST` | `/api/last-mile/:id/generate-truck-detention-invoice` | `modules/warehouses/warehouse-invoice.controller.ts:28` |
+| Record a payment against a warehouse fee invoice | `POST` | `/api/warehouse-fee-invoices/:id/pay` | `modules/warehouses/warehouse-invoice.controller.ts:109` |
+| Initiate Telebirr/Waafi payment for a warehouse fee invoice | `POST` | `/api/warehouse-fee-invoices/:id/pay-online` | `modules/warehouses/warehouse-invoice.controller.ts:116` |
+| Generate a warehouse fee invoice from Batch 5 fee calculation | `POST` | `/api/warehouse-inventory/:id/generate-fee-invoice` | `modules/warehouses/warehouse-invoice.controller.ts:20` |
+| Cancel a warehouse fee invoice | `PATCH` | `/api/warehouse-fee-invoices/:id/cancel` | `modules/warehouses/warehouse-invoice.controller.ts:102` |
+
+### Warehouse Inspection Report
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Upload inspection images / documents | `POST` | `/api/warehouse-inspection-reports/:id/attachments` | `modules/warehouses/warehouse-inspection.controller.ts:68` |
+| Create an inspection / damage report for an inventory item | `POST` | `/api/warehouse-inventory/:inventoryId/inspection-reports` | `modules/warehouses/warehouse-inspection.controller.ts:37` |
+| Update an inspection report | `PATCH` | `/api/warehouse-inspection-reports/:id` | `modules/warehouses/warehouse-inspection.controller.ts:61` |
+
+### Warehouse Inventory
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Deliver import goods to the customer + capture proof of delivery | `POST` | `/api/warehouse-inventory/:id/deliver` | `modules/warehouses/warehouse-inventory.controller.ts:594` |
+| Final terminal release / gate clearance (blocked while fees unpaid) | `POST` | `/api/warehouse-inventory/:id/gate-clearance` | `modules/warehouses/warehouse-inventory.controller.ts:219` |
+| Load READY_FOR_LOADING inventory onto a wagon | `POST` | `/api/warehouse-inventory/:id/load` | `modules/warehouses/warehouse-inventory.controller.ts:384` |
+| Move inventory to another warehouse/yard/zone | `POST` | `/api/warehouse-inventory/:id/move` | `modules/warehouses/warehouse-inventory.controller.ts:359` |
+| Mark reserved inventory READY_FOR_LOADING | `POST` | `/api/warehouse-inventory/:id/ready-for-loading` | `modules/warehouses/warehouse-inventory.controller.ts:373` |
+| Mark inspected IMPORT inventory READY_FOR_PICKUP | `POST` | `/api/warehouse-inventory/:id/ready-for-pickup` | `modules/warehouses/warehouse-inventory.controller.ts:391` |
+| Issue a DO / release order for ready-for-pickup inventory | `POST` | `/api/warehouse-inventory/:id/release` | `modules/warehouses/warehouse-inventory.controller.ts:402` |
+| Mark received inventory as STORED (optional explicit warehouse/yard/zone) | `POST` | `/api/warehouse-inventory/:id/store` | `modules/warehouses/warehouse-inventory.controller.ts:366` |
+| Auto-load READY_FOR_LOADING inventory with PAID bookings | `POST` | `/api/warehouse-inventory/auto-load-ready` | `modules/warehouses/warehouse-inventory.controller.ts:125` |
+| Bulk auto-unload all arrived bookings into the warehouse | `POST` | `/api/warehouse-inventory/auto-unload-arrived` | `modules/warehouses/warehouse-inventory.controller.ts:118` |
+| Approve delivery — customer records their full name (signature optional) | `POST` | `/api/warehouse-inventory/bookings/:bookingId/approve-delivery` | `modules/warehouses/warehouse-inventory.controller.ts:470` |
+| Ask the customer to sign the handover (creates one if none, then notifies) | `POST` | `/api/warehouse-inventory/bookings/:bookingId/request-handover-signature` | `modules/warehouses/warehouse-inventory.controller.ts:509` |
+| Unload a single arrived booking into a location | `POST` | `/api/warehouse-inventory/bookings/:bookingId/unload` | `modules/warehouses/warehouse-inventory.controller.ts:209` |
+| Bulk-dispatch loaded EXPORT inventory (LOADED → DISPATCHED) | `POST` | `/api/warehouse-inventory/bulk-dispatch-export` | `modules/warehouses/warehouse-inventory.controller.ts:195` |
+| Bulk mark received inventory inspection PASSED (EXPORT → READY_FOR_LOADING) | `POST` | `/api/warehouse-inventory/bulk-mark-inspected` | `modules/warehouses/warehouse-inventory.controller.ts:202` |
+| Unload all eligible export items assigned to an arrived Djibouti-side train | `POST` | `/api/warehouse-inventory/export/auto-unload-at-djibouti` | `modules/warehouses/warehouse-inventory.controller.ts:294` |
+| Customer signs one handover (EDR last-mile: one signature per truck) | `POST` | `/api/warehouse-inventory/handovers/:handoverId/sign` | `modules/warehouses/warehouse-inventory.controller.ts:493` |
+| Unload all eligible assigned bookings of an ARRIVED import train (→ UNLOADED) | `POST` | `/api/warehouse-inventory/import/auto-unload-arrived-bookings` | `modules/warehouses/warehouse-inventory.controller.ts:244` |
+| Receive inventory at a warehouse location | `POST` | `/api/warehouse-inventory/receive` | `modules/warehouses/warehouse-inventory.controller.ts:322` |
+| Bulk-receive selected eligible PAID bookings into a location | `POST` | `/api/warehouse-inventory/receive-bulk` | `modules/warehouses/warehouse-inventory.controller.ts:140` |
+| Reserve stored inventory for a PAID booking | `POST` | `/api/warehouse-inventory/reserve` | `modules/warehouses/warehouse-inventory.controller.ts:330` |
+| Load selected inventory items onto their allocated wagons for a train | `POST` | `/api/warehouse-inventory/train/:scheduleId/load` | `modules/warehouses/warehouse-inventory.controller.ts:184` |
+| Mark loaded inventory DISPATCHED (left the terminal) | `PATCH` | `/api/warehouse-inventory/:id/dispatch` | `modules/warehouses/warehouse-inventory.controller.ts:602` |
+| Record Yes/No double handling after unloading (Yes applies the double-handling fee rule) | `PATCH` | `/api/warehouse-inventory/bookings/:bookingId/double-handling` | `modules/warehouses/warehouse-inventory.controller.ts:556` |
+
+### Warehouse Yard
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a zone within a yard | `POST` | `/api/warehouse-yards/:yardId/zones` | `modules/warehouses/warehouse-yards.controller.ts:50` |
+| Update warehouse yard | `PATCH` | `/api/warehouse-yards/:id` | `modules/warehouses/warehouse-yards.controller.ts:36` |
+
+### Warehouse Zone
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Update warehouse zone | `PATCH` | `/api/warehouse-zones/:id` | `modules/warehouses/warehouse-zones.controller.ts:37` |
+
+### Weight Limit Rule
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a weight limit rule | `POST` | `/api/weight-limit-rules` | `modules/rule-engine/controllers/weight-limit-rules.controller.ts:32` |
+| Update a weight limit rule | `PATCH` | `/api/weight-limit-rules/:id` | `modules/rule-engine/controllers/weight-limit-rules.controller.ts:39` |
+| Soft-delete a weight limit rule | `DELETE` | `/api/weight-limit-rules/:id` | `modules/rule-engine/controllers/weight-limit-rules.controller.ts:46` |
+
+### Yard
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a yard | `POST` | `/api/yards` | `modules/rule-engine/controllers/yards.controller.ts:53` |
+| Move a yard up or down in display order | `POST` | `/api/yards/:id/move-order` | `modules/rule-engine/controllers/yards.controller.ts:38` |
+| Bulk reorder yards by ID list | `POST` | `/api/yards/reorder` | `modules/rule-engine/controllers/yards.controller.ts:30` |
+| Update a yard | `PATCH` | `/api/yards/:id` | `modules/rule-engine/controllers/yards.controller.ts:60` |
+| Soft-delete a yard | `DELETE` | `/api/yards/:id` | `modules/rule-engine/controllers/yards.controller.ts:67` |
+
+### Yard Distance
+
+| Title | Method | Endpoint | Source |
+| --- | --- | --- | --- |
+| Create a yard distance | `POST` | `/api/yard-distances` | `modules/rule-engine/controllers/yard-distances.controller.ts:42` |
+| Update a yard distance | `PATCH` | `/api/yard-distances/:id` | `modules/rule-engine/controllers/yard-distances.controller.ts:49` |
+| Soft-delete a yard distance | `DELETE` | `/api/yard-distances/:id` | `modules/rule-engine/controllers/yard-distances.controller.ts:56` |
+
diff --git a/apps/edr-freight-api/package.json b/apps/edr-freight-api/package.json
index fb6a0bd31..f3ba897a0 100644
--- a/apps/edr-freight-api/package.json
+++ b/apps/edr-freight-api/package.json
@@ -60,7 +60,6 @@
     "@nestjs/typeorm": "^11.0.1",
     "@nestjs/websockets": "^11.1.27",
     "@tria-plc/api-common": "file:../../local-packages/tria-plc-api-common-1.6.0.tgz",
-    "@tria-plc/auditlog": "file:../../local-packages/tria-plc-auditlog-1.1.2.tgz",
     "@tria-plc/iamapi-common": "file:../../local-packages/tria-plc-iamapi-common-1.0.0.tgz",
     "amqp-connection-manager": "^5.0.0",
     "amqplib": "^2.0.1",
diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index c1b890719..2ef6d2fb9 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -16,7 +16,6 @@ import {
 import { IamBaselineSeeder, IamSeedModule } from "@edr/iam-seed";
 import { IamModule } from "@tria-plc/iamapi-common";
 import { SharedAuthModule } from "@tria-plc/api-common/modules/auth/shared-auth.module";
-import { MezgebModule } from "@tria-plc/auditlog";
 
 import appConfig from "./config/app.config";
 import databaseConfig from "./config/database.config";
@@ -112,7 +111,6 @@ import { LastMileRequestsModule } from "./modules/last-mile-requests/last-mile-r
 import { InterchangeDocumentsModule } from "./modules/interchange-documents/interchange-documents.module";
 import { ImportOperationsModule } from "./modules/import-operations/import-operations.module";
 import { AiModule } from "./modules/ai/ai.module";
-import { AuditModule } from "./modules/audit/audit.module";
 import { LoggerMiddleware } from "./logger.middleware";
 import { LoginAudienceMiddleware } from "./modules/auth/login-audience.middleware";
 import { PositionTypePermissionsCache } from "./common/position-type-permissions.cache";
@@ -169,19 +167,6 @@ if (!process.env.APPLICATION_NAME) {
         return dataSource;
       },
     }),
-    // Request + entity-level audit logging over RabbitMQ (@tria-plc/auditlog).
-    // Must come after TypeOrmModule above so it picks up this app's DataSource.
-    // rmqUrl falls back the same way notifications.module.ts's RABBITMQ_URL
-    // does: the dev broker only provisions the `edr` user on the `payment`
-    // vhost (docker-compose's RABBITMQ_DEFAULT_USER/VHOST), so an unset
-    // RABBITMQ_URL must land there too, not on guest@'/' (403 ACCESS_REFUSED).
-    MezgebModule.forRoot({
-      applicationName: "freight-api",
-      rmqUrl:
-        process.env.RABBITMQ_URL ??
-        process.env.PAYMENT_RABBITMQ_URL ??
-        "amqp://localhost:5672",
-    }),
     SharedAuthModule,
     IamModule.forRoot({
       applications: [EDR_FREIGHT_APPLICATION],
@@ -257,7 +242,6 @@ if (!process.env.APPLICATION_NAME) {
     EimsModule,
     FleetHistoryModule,
     AiModule,
-    AuditModule,
   ],
   providers: [
     EdrOrgSeeder,
diff --git a/apps/edr-freight-api/src/config/database.config.ts b/apps/edr-freight-api/src/config/database.config.ts
index af4a5b017..77f4b37e4 100644
--- a/apps/edr-freight-api/src/config/database.config.ts
+++ b/apps/edr-freight-api/src/config/database.config.ts
@@ -56,11 +56,6 @@ import { EmployeePositionActivePeriod } from "@tria-plc/iamapi-common/entities/i
 import { UnitConfiguration } from "@tria-plc/iamapi-common/entities/iam/organization-structure/unit-configuration.entity";
 import { Site } from "@tria-plc/iamapi-common/entities/iam/site/site.entity";
 import { SiteSetting } from "@tria-plc/iamapi-common/entities/iam/site/site-setting.entity";
-import { AuditLog, AuditLogCommand } from "@tria-plc/auditlog";
-
-// @tria-plc/auditlog's entities live in node_modules, same as the iam ones —
-// the glob below only matches this app's own src/**/*.entity.ts.
-const auditEntities = [AuditLog, AuditLogCommand];
 
 const iamEntities = [
   UnitSetting,
@@ -185,7 +180,6 @@ export function buildDataSourceOptions(): DataSourceOptions {
     entities: [
       __dirname + "/../**/*.entity.{ts,js}",
       ...iamEntities,
-      ...auditEntities,
     ],
     migrations: [],
   };
diff --git a/apps/edr-freight-api/src/main.ts b/apps/edr-freight-api/src/main.ts
index f26cd19e7..f16493273 100644
--- a/apps/edr-freight-api/src/main.ts
+++ b/apps/edr-freight-api/src/main.ts
@@ -10,7 +10,6 @@ import {
   ResponseTransformInterceptor,
   createValidationPipe,
 } from "@edr/api-common";
-import { getAuditLoggerConfig } from "@tria-plc/auditlog";
 
 import { AppModule } from "./app.module";
 
@@ -167,11 +166,6 @@ export async function createFreightApp(): Promise<NestExpressApplication> {
   app.useGlobalFilters(new HttpExceptionFilter());
   app.useGlobalInterceptors(new ResponseTransformInterceptor());
 
-  // Audit listener: consumes the RMQ events MezgebModule's client interceptor
-  // (app.module.ts) emits and persists them via the AuditLogController /
-  // AuditLogCommandController @EventPattern handlers. Same queue config the
-  // client side uses, reused from the package so the two never drift apart.
-  app.connectMicroservice(getAuditLoggerConfig());
   await app.startAllMicroservices();
 
   const config = new DocumentBuilder()
diff --git a/apps/edr-freight-api/src/modules/audit/audit.controller.ts b/apps/edr-freight-api/src/modules/audit/audit.controller.ts
deleted file mode 100644
index a7c8782b2..000000000
--- a/apps/edr-freight-api/src/modules/audit/audit.controller.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import { Controller, Get, Query } from "@nestjs/common";
-import { ApiOperation, ApiQuery, ApiTags } from "@nestjs/swagger";
-
-import { BookingStaff } from "../../common/booking-guards";
-import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
-import { AuditService } from "./audit.service";
-
-@ApiTags("audit")
-@Controller("audit")
-@BookingStaff(FREIGHT_PERMS.audit.view)
-export class AuditController {
-  constructor(private readonly auditService: AuditService) {}
-
-  @Get("logs")
-  @ApiOperation({ summary: "List freight-api audit log commands" })
-  @ApiQuery({ name: "skip", type: Number, required: false })
-  @ApiQuery({ name: "take", type: Number, required: false })
-  list(@Query("skip") skip?: string, @Query("take") take?: string) {
-    // Same fallback chain @tria-plc/auditlog's client interceptor uses to
-    // stamp AuditLog.application (mezgeb/client/client-audit.interceptor.js)
-    // — reading it here instead of a hardcoded literal means this can't
-    // silently drift out of sync with whatever APPLICATION_NAME/APP_NAME
-    // actually is at runtime.
-    const application =
-      process.env.APPLICATION_NAME ?? process.env.APP_NAME ?? "DEFAULT";
-    return this.auditService.list(
-      application,
-      skip !== undefined ? parseInt(skip, 10) : undefined,
-      take !== undefined ? parseInt(take, 10) : undefined,
-    );
-  }
-}
diff --git a/apps/edr-freight-api/src/modules/audit/audit.module.ts b/apps/edr-freight-api/src/modules/audit/audit.module.ts
deleted file mode 100644
index 635973fc6..000000000
--- a/apps/edr-freight-api/src/modules/audit/audit.module.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import { Module } from "@nestjs/common";
-import { TypeOrmModule } from "@nestjs/typeorm";
-import { AuditLogCommand } from "@tria-plc/auditlog";
-
-import { AuditController } from "./audit.controller";
-import { AuditService } from "./audit.service";
-
-@Module({
-  imports: [TypeOrmModule.forFeature([AuditLogCommand])],
-  controllers: [AuditController],
-  providers: [AuditService],
-})
-export class AuditModule {}
diff --git a/apps/edr-freight-api/src/modules/audit/audit.service.ts b/apps/edr-freight-api/src/modules/audit/audit.service.ts
deleted file mode 100644
index 04ea4beed..000000000
--- a/apps/edr-freight-api/src/modules/audit/audit.service.ts
+++ /dev/null
@@ -1,70 +0,0 @@
-import { Injectable } from "@nestjs/common";
-import { InjectRepository } from "@nestjs/typeorm";
-import { Repository } from "typeorm";
-import { AuditLogCommand } from "@tria-plc/auditlog";
-
-import { CLIENT_APP_HEADER } from "../auth/login-audience.middleware";
-
-export interface AuditLogListResult {
-  count: number;
-  items: AuditLogCommand[];
-}
-
-/**
- * Own read path onto @tria-plc/auditlog's tables, gated by AuditController's
- * @BookingStaff — the package's own AuditLogCommandController (mounted at
- * /api/audit-log-commands) ships with no guards at all, so it can't be used
- * directly for a permission-gated UI. Query mirrors the package's
- * AuditLogCommandService.buildAuditLogQuery/getAllAuditLogs exactly.
- */
-@Injectable()
-export class AuditService {
-  constructor(
-    @InjectRepository(AuditLogCommand)
-    private readonly auditLogCommandRepository: Repository<AuditLogCommand>,
-  ) {}
-
-  async list(
-    application: string,
-    skip = 0,
-    take = 10,
-  ): Promise<AuditLogListResult> {
-    const [items, count] = await this.auditLogCommandRepository
-      .createQueryBuilder("audit_log_commands")
-      .leftJoinAndSelect("audit_log_commands.auditLog", "auditLog")
-      .andWhere(
-        "(audit_log_commands.auditLogId IS NULL OR auditLog.application = :application)",
-        { application },
-      )
-      .andWhere(
-        "(audit_log_commands.auditLogId IS NULL OR auditLog.status = :status)",
-        { status: "Commit" },
-      )
-      // Backoffice-only view: portal (customer-facing) writes carry the same
-      // request-header set by every axios call from that app — see
-      // login-audience.middleware.ts. Rows with no linked auditLog (child/
-      // event commands with no request context) stay visible; they aren't
-      // attributable to any frontend, so they're not portal noise either.
-      .andWhere(
-        "(audit_log_commands.auditLogId IS NULL OR auditLog.requestHeader ->> :clientAppHeader = :clientApp)",
-        { clientAppHeader: CLIENT_APP_HEADER, clientApp: "backoffice" },
-      )
-      .select([
-        "audit_log_commands.id",
-        "audit_log_commands.createdAt",
-        "audit_log_commands.deletedAt",
-        "audit_log_commands.entityName",
-        "audit_log_commands.queryMethod",
-        "audit_log_commands.changes",
-        "audit_log_commands.payload",
-        "auditLog.id",
-        "auditLog.user",
-      ])
-      .addOrderBy("audit_log_commands.createdAt", "DESC")
-      .skip(skip)
-      .take(take)
-      .getManyAndCount();
-
-    return { count, items };
-  }
-}
diff --git a/apps/edr-freight-api/src/modules/payment/payment-events.consumer.ts b/apps/edr-freight-api/src/modules/payment/payment-events.consumer.ts
index e285c181c..91237223c 100644
--- a/apps/edr-freight-api/src/modules/payment/payment-events.consumer.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment-events.consumer.ts
@@ -1,4 +1,4 @@
-import { Injectable, Logger, SetMetadata } from "@nestjs/common";
+import { Injectable, Logger } from "@nestjs/common";
 import { Nack, RabbitSubscribe } from "@golevelup/nestjs-rabbitmq";
 import { Public } from "@edr/api-common";
 import {
@@ -14,11 +14,6 @@ import { PaymentService as PaymentSvc } from "./payment.service";
 
 const FREIGHT_QUEUE = PAYMENT_QUEUES[PaymentService.FREIGHT];
 
-// @tria-plc/auditlog's global ClientLoggerInterceptor (present in deployed builds)
-// crashes on non-HTTP contexts (`originalUrl.split` on a RabbitMQ message) and the
-// resulting requeue storm blocks payment.succeeded forever. Its IgnoreLoggerAudit
-// decorator is just this metadata key — set it directly so we don't need the package.
-@SetMetadata("ignoreAuditLogger", true)
 @Injectable()
 export class PaymentEventsConsumer {
     private readonly logger = new Logger(PaymentEventsConsumer.name);
diff --git a/apps/edr-freight-api/src/modules/rule-engine/repositories/cargo-types.repository.ts b/apps/edr-freight-api/src/modules/rule-engine/repositories/cargo-types.repository.ts
index 07993c267..d285deeb0 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/repositories/cargo-types.repository.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/repositories/cargo-types.repository.ts
@@ -91,9 +91,8 @@ export class CargoTypesRepository implements ICargoTypesRepository {
 
   /**
    * Diffs the wagon-type links through the relation query builder rather than
-   * an entity save: junction-row inserts from save() broadcast afterInsert with
-   * no entity attached, which the @tria-plc/auditlog subscriber (deployed
-   * builds) dereferences and crashes the request on.
+   * an entity save, so junction rows are written without broadcasting
+   * afterInsert events for entity-less inserts.
    */
   private async syncWagonTypes(
     id: string,
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 47fde9fb4..4728cf5f3 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -1187,11 +1187,6 @@ export const CONFIG_SETTINGS_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:settings:dropdown:manage",
     "Manage dropdown settings",
   ),
-  perm(
-    "b4c00001-0001-4000-8000-000000000001",
-    "edr_freight_app:audit:view",
-    "View audit logs",
-  ),
 ];
 
 // M. Staff / IAM admin — NEW keys only. The employee_registration / role_assignment
@@ -1894,9 +1889,6 @@ export const FREIGHT_PERMS = {
       manage: "edr_freight_app:settings:support_content:manage",
     },
   },
-  audit: {
-    view: "edr_freight_app:audit:view",
-  },
   support: {
     agentView: "edr_freight_app:support:agent_view",
     agentSend: "edr_freight_app:support:agent_send",
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index 00d5e0ddb..8d221aaad 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -43,7 +43,6 @@ import ReportsHubPage from "./pages/reports/ReportsHubPage";
 import ReportPage from "./pages/reports/ReportPage";
 import AiBookingMockTestPage from "./pages/ai/AiBookingMockTestPage";
 import PaymentsPage from "./pages/payments/PaymentsPage";
-import AuditLogsPage from "./pages/audit/AuditLogsPage";
 //import EmployeesPage from "./pages/dashboard/user-management/EmployeesPage";
 import { RequirePermission } from "./components/auth/RequirePermission";
 import { FREIGHT_PERMS } from "./lib/permissions";
@@ -773,14 +772,6 @@ const App = () => {
             </RequirePermission>
           }
         />
-        <Route
-          path="audit-logs"
-          element={
-            <RequirePermission permission={FREIGHT_PERMS.audit.view}>
-              <AuditLogsPage />
-            </RequirePermission>
-          }
-        />
         <Route
           path="contract-templates"
           element={
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts b/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts
index 9aa11043b..9b75f35f5 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts
+++ b/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts
@@ -184,13 +184,6 @@ const ROUTE_META: Array<{ prefix: string; meta: PageMeta }> = [
       subtitle: "Manage dropdown options used across the platform",
     },
   },
-  {
-    prefix: "/dashboard/audit-logs",
-    meta: {
-      title: "Audit Logs",
-      subtitle: "Request and entity-level activity recorded across the freight API",
-    },
-  },
   {
     prefix: "/dashboard/configuration/contract-validity-periods",
     meta: {
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 83e80d11e..726711a8b 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -8,7 +8,6 @@ import {
   FileSignature,
   FileText,
   Hammer,
-  History,
   Landmark,
   LayoutDashboard,
   LayoutGrid,
@@ -501,12 +500,6 @@ export const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[]
           FREIGHT_PERMS.settings.supportContent.manage,
         ],
       },
-      {
-        label: "Audit logs",
-        href: "/dashboard/audit-logs",
-        icon: <History />,
-        permission: FREIGHT_PERMS.audit.view,
-      },
       {
         label: "Configuration",
         href: "/dashboard/configuration",
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index 3b482571c..8a6a52bca 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -321,10 +321,6 @@ export const URL_CONSTANTS = {
     SUMMARY: "/payments/summary",
   },
 
-  AUDIT: {
-    LOGS: "/audit/logs",
-  },
-
   LOCOMOTIVES: {
     BASE: "/locomotives",
     BY_ID: (id: string) => `/locomotives/${id}`,
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index b74c7bef9..8e16c1d96 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -338,9 +338,6 @@ export const FREIGHT_PERMS = {
       manage: "edr_freight_app:settings:support_content:manage",
     },
   },
-  audit: {
-    view: "edr_freight_app:audit:view",
-  },
   staff: {
     roles: {
       view: "edr_freight_app:staff:roles:view",
diff --git a/apps/edr-freight-web/backoffice/src/pages/audit/AuditLogsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/audit/AuditLogsPage.tsx
deleted file mode 100644
index ef3412a3a..000000000
--- a/apps/edr-freight-web/backoffice/src/pages/audit/AuditLogsPage.tsx
+++ /dev/null
@@ -1,190 +0,0 @@
-import { Badge, Box, Card, Stack, Text } from "@mantine/core";
-import { useQuery } from "@tanstack/react-query";
-
-import { PageContainer, PageHeader } from "@/components/page";
-import { api } from "@/services/api";
-import type {
-  AuditLogRow,
-  AuditQueryMethod,
-  AuditUser,
-  LocalizedText,
-} from "@/services/audit.service";
-import {
-  DataTable,
-  DataTableFooter,
-  usePagination,
-  type ColumnDef,
-} from "@edr/ui-common";
-
-const ACTION_LABELS: Record<AuditQueryMethod, string> = {
-  INSERT: "Created",
-  UPDATE: "Updated",
-  DELETE: "Deleted",
-  INSERT_CHILD: "Linked child",
-  DELETE_CHILD: "Unlinked child",
-};
-
-const ACTION_COLORS: Record<AuditQueryMethod, string> = {
-  INSERT: "edr-green",
-  UPDATE: "yellow",
-  DELETE: "red",
-  INSERT_CHILD: "indigo",
-  DELETE_CHILD: "gray",
-};
-
-function formatDateTime(iso: string): string {
-  const d = new Date(iso);
-  return Number.isNaN(d.getTime())
-    ? "—"
-    : d.toLocaleString(undefined, {
-      year: "numeric",
-      month: "short",
-      day: "numeric",
-      hour: "2-digit",
-      minute: "2-digit",
-    });
-}
-
-// See LocalizedText: `name`/`title` lifted from a raw audited entity can be
-// a plain string or IAM's { am, en } — never render either directly.
-// "undefined  undefined" is the producer's own broken template when no user
-// was attached at all (unauthenticated/customer flows, e.g. Fayda
-// verification) — filtered out here rather than shown as raw garbage.
-function localize(value: LocalizedText | null | undefined): string | undefined {
-  if (!value) return undefined;
-  if (typeof value === "object") return value.en ?? value.am ?? undefined;
-  if (/^undefined(\s+undefined)?$/.test(value.trim())) return undefined;
-  return value;
-}
-
-function formatUser(user: AuditUser | null | undefined): string {
-  return localize(user?.name) ?? user?.id ?? "—";
-}
-
-function summarize(row: AuditLogRow): string {
-  if (row.changes?.length) {
-    return row.changes
-      .slice(0, 2)
-      .map((c) => c.field)
-      .join(", ") + (row.changes.length > 2 ? `, +${row.changes.length - 2} more` : "");
-  }
-  if (row.payload) {
-    return (
-      localize(row.payload.name) ?? localize(row.payload.title) ?? row.payload.id ?? "—"
-    );
-  }
-  return "—";
-}
-
-const tableHeader =
-  "text-xs font-semibold uppercase tracking-wide text-muted-foreground";
-
-export default function AuditLogsPage() {
-  const { pagination, setPagination } = usePagination({ pageSize: 20 });
-
-  const filter = {
-    skip: pagination.pageIndex * pagination.pageSize,
-    take: pagination.pageSize,
-  };
-
-  const { data, isLoading, isError } = useQuery(
-    api.audit.list.queryOptions({ input: { filter } }),
-  );
-
-  const rows = data?.items ?? [];
-  const total = data?.count ?? 0;
-  const pageCount = Math.max(1, Math.ceil(total / pagination.pageSize));
-
-  const columns: ColumnDef<AuditLogRow>[] = [
-    {
-      id: "time",
-      header: () => <span className={tableHeader}>Time</span>,
-      cell: ({ row }) => (
-        <span className="text-sm text-muted-foreground">
-          {formatDateTime(row.original.createdAt)}
-        </span>
-      ),
-    },
-    {
-      id: "action",
-      header: () => <span className={tableHeader}>Action</span>,
-      cell: ({ row }) => (
-        <Badge
-          color={ACTION_COLORS[row.original.queryMethod] ?? "gray"}
-          variant="light"
-          radius="sm"
-        >
-          {ACTION_LABELS[row.original.queryMethod] ?? row.original.queryMethod}
-        </Badge>
-      ),
-    },
-    {
-      id: "entity",
-      header: () => <span className={tableHeader}>Entity</span>,
-      cell: ({ row }) => (
-        <span className="font-mono text-sm text-foreground">
-          {row.original.entityName}
-        </span>
-      ),
-    },
-    {
-      id: "user",
-      header: () => <span className={tableHeader}>User</span>,
-      cell: ({ row }) => (
-        <span className="text-sm text-foreground">
-          {formatUser(row.original.auditLog?.user)}
-        </span>
-      ),
-    },
-    {
-      id: "summary",
-      header: () => <span className={tableHeader}>Summary</span>,
-      cell: ({ row }) => (
-        <span className="truncate text-sm text-muted-foreground">
-          {summarize(row.original)}
-        </span>
-      ),
-    },
-  ];
-
-  return (
-    <PageContainer>
-      <PageHeader
-        title="Audit Logs"
-        subtitle="Request and entity-level activity recorded across the freight API."
-      />
-
-      <Card p={0}>
-        <Stack gap={0}>
-          <Box px="md" pt="md" pb="sm" w="100%">
-            <Text size="sm" c="dimmed">
-              {total} record{total !== 1 ? "s" : ""}
-            </Text>
-          </Box>
-
-          <Box style={{ overflowX: "auto" }} w="100%">
-            <DataTable
-              columns={columns}
-              data={rows}
-              status={isLoading ? "loading" : isError ? "error" : "success"}
-              pagination={{
-                pageIndex: pagination.pageIndex,
-                pageSize: pagination.pageSize,
-                pageCount,
-                totalCount: total,
-              }}
-              tableOptions={{
-                state: { pagination },
-                onPaginationChange: setPagination,
-                manualPagination: true,
-                pageCount,
-              }}
-              containerClassName="border-0 shadow-none bg-transparent"
-              footer={DataTableFooter}
-            />
-          </Box>
-        </Stack>
-      </Card>
-    </PageContainer>
-  );
-}
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 895a54070..c7679056e 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -166,11 +166,6 @@ import {
   type SaveLocomotivePayload,
 } from "./locomotives.service";
 import { overviewService } from "./overview.service";
-import {
-  auditService,
-  type AuditLogListFilter,
-  type PaginatedAuditLogs,
-} from "./audit.service";
 import { reportsService } from "./reports.service";
 import type { ReportQueryInput, ReportResult } from "@/types/reports";
 import {
@@ -2153,15 +2148,6 @@ export const api = {
     ),
   },
 
-  audit: {
-    list: endpoint<{ filter?: AuditLogListFilter }, PaginatedAuditLogs>(
-      "audit",
-      "list",
-      ({ filter }) => auditService.list(filter),
-      ({ filter }) => ["audit", "list", filter ?? {}],
-    ),
-  },
-
   signatures: {
     mySignature: endpoint<void, SavedSignature | null>(
       "me",
diff --git a/apps/edr-freight-web/backoffice/src/services/audit.service.ts b/apps/edr-freight-web/backoffice/src/services/audit.service.ts
deleted file mode 100644
index ed0642d83..000000000
--- a/apps/edr-freight-web/backoffice/src/services/audit.service.ts
+++ /dev/null
@@ -1,70 +0,0 @@
-import { api as client } from "../auth/http";
-import { unwrap } from "@/utils/endpoint";
-import { URL_CONSTANTS } from "@/constants/URLS";
-
-const A = URL_CONSTANTS.AUDIT;
-
-// Shape from @tria-plc/auditlog's AuditLogCommandController — see
-// local-packages/FRONTEND_GUIDE.md.
-export type AuditQueryMethod =
-  | "INSERT"
-  | "UPDATE"
-  | "DELETE"
-  | "INSERT_CHILD"
-  | "DELETE_CHILD";
-
-export interface AuditFieldChange {
-  field: string;
-  from: unknown;
-  to: unknown;
-}
-
-// IAM entities (users, orgs, positions, ...) name themselves bilingually —
-// see edr-org.seeder.ts. Any `name`/`title` field lifted from a raw audited
-// entity (auditLog.user, payload) can come back as either a plain string or
-// this shape; both `name` fields below reflect that.
-export type LocalizedText = string | { am?: string; en?: string };
-
-// The vendored interceptor's own broken template produces a plain string
-// ("undefined  undefined") when no user was attached at all (unauthenticated/
-// customer flows) — that's the non-bilingual string case for `name` here.
-export interface AuditUser {
-  id?: string;
-  name?: LocalizedText;
-  organizationId?: string;
-  organizationName?: string;
-  [key: string]: unknown;
-}
-
-export interface AuditLogRow {
-  id?: string;
-  createdAt: string;
-  deletedAt?: string | null;
-  entityName: string;
-  queryMethod: AuditQueryMethod;
-  changes?: AuditFieldChange[] | null;
-  payload?: { name?: LocalizedText; title?: LocalizedText; id?: string } | null;
-  auditLog?: { id?: string; user?: AuditUser | null };
-}
-
-export interface AuditLogListFilter {
-  skip?: number;
-  take?: number;
-}
-
-export interface PaginatedAuditLogs {
-  items: AuditLogRow[];
-  count: number;
-}
-
-export const auditService = {
-  list: async (filter?: AuditLogListFilter): Promise<PaginatedAuditLogs> => {
-    const params: Record<string, number | undefined> = {
-      skip: filter?.skip,
-      take: filter?.take,
-    };
-    const response = await client.get<PaginatedAuditLogs>(A.LOGS, { params });
-    const data = unwrap(response.data) as PaginatedAuditLogs;
-    return { items: data.items ?? [], count: data.count ?? 0 };
-  },
-};
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 68573264b..0caaa0905 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4,6 +4,13 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+overrides:
+  date-fns: ^3.6.0
+  pdfjs-dist: ^3.11.174
+  react: 19.2.6
+  react-dom: 19.2.6
+  typeorm: 0.3.30
+
 importers:
 
   .:
@@ -98,13 +105,10 @@ importers:
         version: 11.1.27(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/platform-socket.io@11.1.27)(reflect-metadata@0.2.2)(rxjs@7.8.2)
       '@tria-plc/api-common':
         specifier: file:../../local-packages/tria-plc-api-common-1.6.0.tgz
-        version: file:local-packages/tria-plc-api-common-1.6.0.tgz(ae9a56cc1c6d93629dd85f7605ccd5b6)
-      '@tria-plc/auditlog':
-        specifier: file:../../local-packages/tria-plc-auditlog-1.1.2.tgz
-        version: file:local-packages/tria-plc-auditlog-1.1.2.tgz(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/microservices@11.1.24)(@nestjs/swagger@11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2))(@nestjs/typeorm@11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))))(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
+        version: file:local-packages/tria-plc-api-common-1.6.0.tgz(2te6mb6vb2upxetsvhkgi54vi4)
       '@tria-plc/iamapi-common':
         specifier: file:../../local-packages/tria-plc-iamapi-common-1.0.0.tgz
-        version: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(d0be280d95adfc1b38e59bdc80c5dec5)
+        version: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(776yg74vcz655pvzf2fzttkf2q)
       amqp-connection-manager:
         specifier: ^5.0.0
         version: 5.0.0(amqplib@2.0.1)
@@ -157,7 +161,7 @@ importers:
         specifier: ^4.8.3
         version: 4.8.3
       typeorm:
-        specifier: ^0.3.30
+        specifier: 0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
     devDependencies:
       '@edr/eslint-config':
@@ -357,7 +361,7 @@ importers:
         version: 6.3.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tinymce@8.6.0)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(elggzzmuouas3d7ccap2lbvoyu)
       '@types/three':
         specifier: ^0.185.3
         version: 0.185.3
@@ -559,7 +563,7 @@ importers:
         version: 10.5.0(postcss@8.5.15)
       jsdom:
         specifier: ^25.0.1
-        version: 25.0.1
+        version: 25.0.1(canvas@2.11.2)
       postcss:
         specifier: ^8.4.47
         version: 8.5.15
@@ -574,7 +578,7 @@ importers:
         version: 5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0)
       vitest:
         specifier: ^2.1.2
-        version: 2.1.9(@types/node@24.13.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0)
+        version: 2.1.9(@types/node@24.13.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0)
 
   apps/edr-freight-web/portal:
     dependencies:
@@ -604,7 +608,7 @@ importers:
         version: 5.101.0(react@19.2.6)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(vhj5jsbx2ogblwtd5crolhrpku)
       '@vis.gl/react-google-maps':
         specifier: ^1.8.3
         version: 1.8.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -698,7 +702,7 @@ importers:
         version: 10.5.0(postcss@8.5.15)
       jsdom:
         specifier: ^25.0.1
-        version: 25.0.1
+        version: 25.0.1(canvas@2.11.2)
       postcss:
         specifier: ^8.4.47
         version: 8.5.15
@@ -713,7 +717,7 @@ importers:
         version: 5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0)
       vitest:
         specifier: ^2.1.2
-        version: 2.1.9(@types/node@24.13.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0)
+        version: 2.1.9(@types/node@24.13.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0)
 
   apps/edr-gps-tracker:
     dependencies:
@@ -745,7 +749,7 @@ importers:
         specifier: ^7.8.1
         version: 7.8.2
       typeorm:
-        specifier: ^0.3.30
+        specifier: 0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
     devDependencies:
       '@edr/eslint-config':
@@ -834,10 +838,10 @@ importers:
         version: 8.1.6
       '@tria-plc/api-common':
         specifier: file:../../local-packages/tria-plc-api-common-1.6.0.tgz
-        version: file:local-packages/tria-plc-api-common-1.6.0.tgz(2b4e99ab22f78c34e7861d649f4ff29b)
+        version: file:local-packages/tria-plc-api-common-1.6.0.tgz(66zjxtt2zhydyq6w3arhrktl4y)
       '@tria-plc/iamapi-common':
         specifier: file:../../local-packages/tria-plc-iamapi-common-1.0.0.tgz
-        version: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(cc085a020c559b355f168432c579a024)
+        version: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(2duxgcsfjn5usnyutzzh6i5xr4)
       '@types/bcrypt':
         specifier: ^6.0.0
         version: 6.0.0
@@ -896,7 +900,7 @@ importers:
         specifier: ^4.2.0
         version: 4.2.0
       typeorm:
-        specifier: ^0.3.30
+        specifier: 0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
       uuid:
         specifier: ^10.0.0
@@ -973,7 +977,7 @@ importers:
         version: link:../../../packages/ui-common
       '@tanstack/react-query':
         specifier: ^5.59.0
-        version: 5.101.0(react@18.3.1)
+        version: 5.101.0(react@19.2.6)
       axios:
         specifier: ^1.7.7
         version: 1.17.0
@@ -981,32 +985,32 @@ importers:
         specifier: ^2.1.1
         version: 2.1.1
       date-fns:
-        specifier: ^3.0.0
+        specifier: ^3.6.0
         version: 3.6.0
       lucide-react:
         specifier: ^0.446.0
-        version: 0.446.0(react@18.3.1)
+        version: 0.446.0(react@19.2.6)
       next:
         specifier: ^14.2.0
-        version: 14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       react:
-        specifier: ^18.3.1
-        version: 18.3.1
+        specifier: 19.2.6
+        version: 19.2.6
       react-day-picker:
         specifier: ^9.14.0
-        version: 9.14.0(react@18.3.1)
+        version: 9.14.0(react@19.2.6)
       react-dom:
-        specifier: ^18.3.1
-        version: 18.3.1(react@18.3.1)
+        specifier: 19.2.6
+        version: 19.2.6(react@19.2.6)
       recharts:
         specifier: ^2.12.0
-        version: 2.15.4(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 2.15.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       socket.io-client:
         specifier: ^4.8.3
         version: 4.8.3
       zustand:
         specifier: ^5.0.0
-        version: 5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@18.3.1)(use-sync-external-store@1.6.0(react@18.3.1))
+        version: 5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@19.2.6)(use-sync-external-store@1.6.0(react@19.2.6))
     devDependencies:
       '@types/node':
         specifier: ^20.0.0
@@ -1046,10 +1050,10 @@ importers:
         version: link:../../../packages/ui-common
       '@hookform/resolvers':
         specifier: ^3.3.4
-        version: 3.10.0(react-hook-form@7.77.0(react@18.3.1))
+        version: 3.10.0(react-hook-form@7.77.0(react@19.2.6))
       '@tanstack/react-query':
         specifier: ^5.59.0
-        version: 5.101.0(react@18.3.1)
+        version: 5.101.0(react@19.2.6)
       '@types/qrcode':
         specifier: ^1.5.6
         version: 1.5.6
@@ -1060,7 +1064,7 @@ importers:
         specifier: ^2.1.1
         version: 2.1.1
       date-fns:
-        specifier: ^3.0.0
+        specifier: ^3.6.0
         version: 3.6.0
       jspdf:
         specifier: ^4.2.1
@@ -1070,25 +1074,25 @@ importers:
         version: 5.0.8(jspdf@4.2.1)
       lucide-react:
         specifier: ^0.446.0
-        version: 0.446.0(react@18.3.1)
+        version: 0.446.0(react@19.2.6)
       next:
         specifier: ^14.2.0
-        version: 14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       qrcode:
         specifier: ^1.5.4
         version: 1.5.4
       qrcode.react:
         specifier: ^3.1.0
-        version: 3.2.0(react@18.3.1)
+        version: 3.2.0(react@19.2.6)
       react:
-        specifier: ^18.3.1
-        version: 18.3.1
+        specifier: 19.2.6
+        version: 19.2.6
       react-dom:
-        specifier: ^18.3.1
-        version: 18.3.1(react@18.3.1)
+        specifier: 19.2.6
+        version: 19.2.6(react@19.2.6)
       react-hook-form:
         specifier: ^7.51.0
-        version: 7.77.0(react@18.3.1)
+        version: 7.77.0(react@19.2.6)
       socket.io-client:
         specifier: ^4.8.3
         version: 4.8.3
@@ -1097,7 +1101,7 @@ importers:
         version: 3.25.76
       zustand:
         specifier: ^5.0.0
-        version: 5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@18.3.1)(use-sync-external-store@1.6.0(react@18.3.1))
+        version: 5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@19.2.6)(use-sync-external-store@1.6.0(react@19.2.6))
     devDependencies:
       '@types/node':
         specifier: ^20.0.0
@@ -1279,7 +1283,7 @@ importers:
         version: 5.9.3
       vitest:
         specifier: ^2.1.2
-        version: 2.1.9(@types/node@22.20.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(terser@5.48.0)
+        version: 2.1.9(@types/node@22.20.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(terser@5.48.0)
 
   packages/api-common:
     dependencies:
@@ -1309,7 +1313,7 @@ importers:
         specifier: ^7.8.1
         version: 7.8.2
       typeorm:
-        specifier: ^0.3.20
+        specifier: 0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
       typescript:
         specifier: ^5.5.4
@@ -1377,7 +1381,7 @@ importers:
         specifier: ^29.2.5
         version: 29.4.11(@babel/core@7.29.7)(@jest/transform@29.7.0)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(jest-util@29.7.0)(jest@29.7.0(@types/node@20.19.42)(babel-plugin-macros@3.1.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))(typescript@5.9.3)
       typeorm:
-        specifier: ^0.3.20
+        specifier: 0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
       typescript:
         specifier: ^5.5.4
@@ -1439,10 +1443,10 @@ importers:
         version: link:../types
       '@mantine/core':
         specifier: ^9.3.0
-        version: 9.3.0(@mantine/hooks@9.3.0(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 9.3.0(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@tanstack/react-table':
         specifier: ^8.21.3
-        version: 8.21.3(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 8.21.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       class-variance-authority:
         specifier: ^0.7.1
         version: 0.7.1
@@ -1451,10 +1455,10 @@ importers:
         version: 2.1.1
       lucide-react:
         specifier: ^1.14.0
-        version: 1.17.0(react@18.3.1)
+        version: 1.17.0(react@19.2.6)
       radix-ui:
         specifier: ^1.4.3
-        version: 1.5.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 1.5.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       shadcn:
         specifier: ^4.7.0
         version: 4.10.0(@types/node@24.13.1)(babel-plugin-macros@3.1.0)(typescript@5.9.3)
@@ -1484,11 +1488,11 @@ importers:
         specifier: ^8.4.47
         version: 8.5.15
       react:
-        specifier: ^18.3.1
-        version: 18.3.1
+        specifier: 19.2.6
+        version: 19.2.6
       react-dom:
-        specifier: ^18.3.1
-        version: 18.3.1(react@18.3.1)
+        specifier: 19.2.6
+        version: 19.2.6(react@19.2.6)
       tailwindcss:
         specifier: ^4.3.0
         version: 4.3.0
@@ -2002,7 +2006,7 @@ packages:
     resolution: {integrity: sha512-O000MLDBDdk/EohJPFUqvnp4qnHeYkVP5B0xEG0D/L7cOKP9kefu2DXn8dj74cQfsEzUqh+sr1RzFqiL1o+PpA==}
     peerDependencies:
       '@types/react': '*'
-      react: '>=16.8.0'
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -2018,7 +2022,7 @@ packages:
     peerDependencies:
       '@emotion/react': ^11.0.0-rc.0
       '@types/react': '*'
-      react: '>=16.8.0'
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -2035,7 +2039,7 @@ packages:
   '@emotion/use-insertion-effect-with-fallbacks@1.2.0':
     resolution: {integrity: sha512-yJMtVdH59sxi/aVJBpk9FQq+OR8ll5GT8oWd57UpeaKEVGab41JWaCFA7FRLoMLloOZF/c/wsPoe+bfGmRKgDg==}
     peerDependencies:
-      react: '>=16.8.0'
+      react: 19.2.6
 
   '@emotion/utils@1.4.2':
     resolution: {integrity: sha512-3vLclRofFziIa3J2wDh9jjbkUz9qk5Vi3IZ/FSTKViB0k+ef0fPV7dYrUIugbgupYDx7v9ud/SjrtEP8Y4xLoA==}
@@ -2221,20 +2225,20 @@ packages:
   '@floating-ui/react-dom@2.1.8':
     resolution: {integrity: sha512-cC52bHwM/n/CxS87FH0yWdngEZrjdtLW/qVruo68qg+prK7ZQ4YGdut2GyDVpoGeAYe/h899rVeOVm6Oi40k2A==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@floating-ui/react@0.26.28':
     resolution: {integrity: sha512-yORQuuAtVpiRjpMhdc0wJj06b9JFjrYF4qp96j++v2NBpbi6SEGF7donUJ3TMieerQ6qVkAv1tgr7L4r5roTqw==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@floating-ui/react@0.27.19':
     resolution: {integrity: sha512-31B8h5mm8YxotlE7/AU/PhNAl8eWxAmjL/v2QOxroDNkTFLk3Uu82u63N3b6TXa4EGJeeZLVcd/9AlNlVqzeog==}
     peerDependencies:
-      react: '>=17.0.0'
-      react-dom: '>=17.0.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@floating-ui/utils@0.2.11':
     resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
@@ -2259,8 +2263,8 @@ packages:
   '@hello-pangea/dnd@18.0.1':
     resolution: {integrity: sha512-xojVWG8s/TGrKT1fC8K2tIWeejJYTAeJuj36zM//yEm/ZrnZUSFGS15BpO+jGZT1ybWvyXmeDJwPYb4dhWlbZQ==}
     peerDependencies:
-      react: ^18.0.0 || ^19.0.0
-      react-dom: ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@hono/node-server@1.19.14':
     resolution: {integrity: sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==}
@@ -2271,8 +2275,8 @@ packages:
   '@hookform/devtools@4.4.0':
     resolution: {integrity: sha512-Mtlic+uigoYBPXlfvPBfiYYUZuyMrD3pTjDpVIhL6eCZTvQkHsKBSKeZCvXWUZr8fqrkzDg27N+ZuazLKq6Vmg==}
     peerDependencies:
-      react: ^16.8.0 || ^17 || ^18 || ^19
-      react-dom: ^16.8.0 || ^17 || ^18 || ^19
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@hookform/resolvers@3.10.0':
     resolution: {integrity: sha512-79Dv+3mDF7i+2ajj7SkypSKHhl1cbln1OGavqrsF7p6mbUv11xpqpacPsGDCTRvCSjEEIez2ef1NveSVL3b0Ag==}
@@ -2680,8 +2684,8 @@ packages:
   '@lexical/devtools-core@0.48.0':
     resolution: {integrity: sha512-4kvKWW6ebgQnJNLXPLmw7dqgSChvzYIBNYtfuR6c48Sw+V/QXQTWqfIUbCIe5X4uG8EEXd5O/udXaJx7GBuP+w==}
     peerDependencies:
-      react: '>=18.x'
-      react-dom: '>=18.x'
+      react: 19.2.6
+      react-dom: 19.2.6
       typescript: '>=5.2'
     peerDependenciesMeta:
       typescript:
@@ -2786,8 +2790,8 @@ packages:
   '@lexical/react@0.48.0':
     resolution: {integrity: sha512-uVh9/QSrbtjLjVbxfJ+sfiMyhUq/rv7H6uBEVDDIw1rkZJSDY1fvf/CX+dyKgwcDFjKQZ8/9i5f9UCVPeQ01hA==}
     peerDependencies:
-      react: '>=18.x'
-      react-dom: '>=18.x'
+      react: 19.2.6
+      react-dom: 19.2.6
       typescript: '>=5.2'
       yjs: '>=13.5.22'
     peerDependenciesMeta:
@@ -2899,7 +2903,7 @@ packages:
   '@lottiefiles/react-lottie-player@3.6.0':
     resolution: {integrity: sha512-WK5TriLJT93VF3w4IjSVyveiedraZCnDhKzCPhpbeLgQeMi6zufxa3dXNc4HmAFRXq+LULPAy+Idv1rAfkReMA==}
     peerDependencies:
-      react: 16 - 19
+      react: 19.2.6
 
   '@lukeed/csprng@1.1.0':
     resolution: {integrity: sha512-Z7C/xXCiGWsg0KuKsHTKJxbWhpI3Vs5GwLfOean7MGyVFGqdRgBbAjOCh6u4bbjPc/8MJ2pZmK/0DLdCbivLDA==}
@@ -2910,30 +2914,30 @@ packages:
     peerDependencies:
       '@mantine/core': 7.17.8
       '@mantine/hooks': 7.17.8
-      react: ^18.x || ^19.x
-      react-dom: ^18.x || ^19.x
+      react: 19.2.6
+      react-dom: 19.2.6
       recharts: ^2.13.3
 
   '@mantine/core@7.17.8':
     resolution: {integrity: sha512-42sfdLZSCpsCYmLCjSuntuPcDg3PLbakSmmYfz5Auea8gZYLr+8SS5k647doVu0BRAecqYOytkX2QC5/u/8VHw==}
     peerDependencies:
       '@mantine/hooks': 7.17.8
-      react: ^18.x || ^19.x
-      react-dom: ^18.x || ^19.x
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mantine/core@9.3.0':
     resolution: {integrity: sha512-mHVCm61YVW9ipy9eHiKMqsRUm3TkOErbdw7zHs0HRw5g403nf7tSTqNGvaYE+aX1Py874qMkrUzeQfj4bjiiBA==}
     peerDependencies:
       '@mantine/hooks': 9.3.0
-      react: ^19.2.0
-      react-dom: ^19.2.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mantine/core@9.3.2':
     resolution: {integrity: sha512-Upy/Z9Sj2eW2dGrFgUy/2kISVsxMTBYTDfP2TFdsIA3PdPSBkdqfSOPX/ug3d3F3a4bnwQSqcO6+aPEpBIh8dg==}
     peerDependencies:
       '@mantine/hooks': 9.3.2
-      react: ^19.2.0
-      react-dom: ^19.2.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mantine/dates@7.17.8':
     resolution: {integrity: sha512-KYog/YL83PnsMef7EZagpOFq9I2gfnK0eYSzC8YvV9Mb6t/x9InqRssGWVb0GIr+TNILpEkhKoGaSKZNy10Q1g==}
@@ -2941,8 +2945,8 @@ packages:
       '@mantine/core': 7.17.8
       '@mantine/hooks': 7.17.8
       dayjs: '>=1.0.0'
-      react: ^18.x || ^19.x
-      react-dom: ^18.x || ^19.x
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mantine/dates@9.3.2':
     resolution: {integrity: sha512-MzHrXGoOb3rCnHBlsI/BPAjC8K5tZ4f8pzg66tsTsupVCQBaBpHSVatQwNRJ6K2JC9pyCyTa9BL803C8AiWycA==}
@@ -2950,36 +2954,40 @@ packages:
       '@mantine/core': 9.3.2
       '@mantine/hooks': 9.3.2
       dayjs: '>=1.0.0'
-      react: ^19.2.0
-      react-dom: ^19.2.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mantine/hooks@7.17.8':
     resolution: {integrity: sha512-96qygbkTjRhdkzd5HDU8fMziemN/h758/EwrFu7TlWrEP10Vw076u+Ap/sG6OT4RGPZYYoHrTlT+mkCZblWHuw==}
     peerDependencies:
-      react: ^18.x || ^19.x
+      react: 19.2.6
 
   '@mantine/hooks@9.3.0':
     resolution: {integrity: sha512-QoSr9WI4WsKWrM3qFYYizHUn3+n+CVcFMYe4sdlnmFPStvs6BacPODKJSbFlYl73Z20t82JIy0eKqt4noHQI2g==}
     peerDependencies:
-      react: ^19.2.0
+      react: 19.2.6
 
   '@mantine/hooks@9.3.2':
     resolution: {integrity: sha512-jOjpUe0x1A/k3XUiu2/aaSCasXRI5ZKZOucm3ypwsvm9F2u8C1xzwBvagrzlbNZwJRF5vNYIJtCaT7NunPyc0A==}
     peerDependencies:
-      react: ^19.2.0
+      react: 19.2.6
 
   '@mantine/notifications@7.17.8':
     resolution: {integrity: sha512-/YK16IZ198W6ru/IVecCtHcVveL08u2c8TbQTu/2p26LSIM9AbJhUkrU6H+AO0dgVVvmdmNdvPxcJnfq3S9TMg==}
     peerDependencies:
       '@mantine/core': 7.17.8
       '@mantine/hooks': 7.17.8
-      react: ^18.x || ^19.x
-      react-dom: ^18.x || ^19.x
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mantine/store@7.17.8':
     resolution: {integrity: sha512-/FrB6PAVH4NEjQ1dsc9qOB+VvVlSuyjf4oOOlM9gscPuapDP/79Ryq7JkhHYfS55VWQ/YUlY24hDI2VV+VptXg==}
     peerDependencies:
-      react: ^18.x || ^19.x
+      react: 19.2.6
+
+  '@mapbox/node-pre-gyp@1.0.11':
+    resolution: {integrity: sha512-Yhlar6v9WQgUp/He7BdgzOz8lqMQ8sU+jkCq7Wx8Myc5YFJLbEe7lgui/V7G1qB1DJykHSGwreceSaD60Y0PUQ==}
+    hasBin: true
 
   '@marijn/find-cluster-break@1.0.3':
     resolution: {integrity: sha512-FY+MKLBoTsLNJF/eLWaOsXGdz6uh3Iu1axjPf6TUq92IYumcTcXWHoS747JARLkcdlJ/Waiaxc5wQfFO8jC6NA==}
@@ -2988,15 +2996,15 @@ packages:
     resolution: {integrity: sha512-S/IPY8AjWTV2v1TGbEy5lsbQ5w+J2M2j2QDeswxP4FpNh2B49OPkpSqHbbX5GbV0YBlhfXJxtzwBJv/sQACufw==}
     engines: {node: '>=16'}
     peerDependencies:
-      react: '>= 18 || >= 19'
-      react-dom: '>= 18 || >= 19'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mdxeditor/gurx@1.2.4':
     resolution: {integrity: sha512-9ZykIFYhKaXaaSPCs1cuI+FvYDegJjbKwmA4ASE/zY+hJY6EYqvoye4esiO85CjhOw9aoD/izD/CU78/egVqmg==}
     engines: {node: '>=16'}
     peerDependencies:
-      react: '>= 18 || >= 19'
-      react-dom: '>= 18 || >= 19'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@microsoft/tsdoc@0.15.1':
     resolution: {integrity: sha512-4aErSrCR/On/e5G2hDP0wjooqDdauzEbIq8hIkIe5pXV0rtWJZvdCEKL0ykZxex+IxIwBp0eGeV48hQN07dXtw==}
@@ -3024,8 +3032,8 @@ packages:
     deprecated: This package has been replaced by @base-ui/react
     peerDependencies:
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3039,7 +3047,7 @@ packages:
     peerDependencies:
       '@mui/material': ^5.0.0
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3051,8 +3059,8 @@ packages:
       '@emotion/react': ^11.5.0
       '@emotion/styled': ^11.3.0
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@emotion/react':
         optional: true
@@ -3066,7 +3074,7 @@ packages:
     engines: {node: '>=12.0.0'}
     peerDependencies:
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3077,7 +3085,7 @@ packages:
     peerDependencies:
       '@emotion/react': ^11.4.1
       '@emotion/styled': ^11.3.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@emotion/react':
         optional: true
@@ -3091,7 +3099,7 @@ packages:
       '@emotion/react': ^11.5.0
       '@emotion/styled': ^11.3.0
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@emotion/react':
         optional: true
@@ -3113,7 +3121,7 @@ packages:
     engines: {node: '>=12.0.0'}
     peerDependencies:
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3123,7 +3131,7 @@ packages:
     engines: {node: '>=14.0.0'}
     peerDependencies:
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3136,15 +3144,15 @@ packages:
       '@emotion/styled': ^11.8.1
       '@mui/material': ^5.8.6
       '@mui/system': ^5.8.0
-      date-fns: ^2.25.0 || ^3.2.0
+      date-fns: ^3.6.0
       date-fns-jalali: ^2.13.0-0
       dayjs: ^1.10.7
       luxon: ^3.0.2
       moment: ^2.29.4
       moment-hijri: ^2.1.2
       moment-jalaali: ^0.7.4 || ^0.8.0 || ^0.9.0 || ^0.10.0
-      react: ^17.0.0 || ^18.0.0
-      react-dom: ^17.0.0 || ^18.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@emotion/react':
         optional: true
@@ -3194,35 +3202,30 @@ packages:
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   '@napi-rs/canvas-linux-arm64-musl@0.1.100':
     resolution: {integrity: sha512-K3mDW66N+xT2/V439u1alFANiBUjdEx2gLiNYnCmUsva5jZMxWTjafBYwTzYK+EMFMHrUoabuU+T1BIP5CgbYQ==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   '@napi-rs/canvas-linux-riscv64-gnu@0.1.100':
     resolution: {integrity: sha512-mooqUBTIsccZpnoQC4NgrC1v6C1vof39etLNMnBwCY+p0gajWJvAHLGQ6g/gGyS5YrpDW+GefSN4+Cvcr08UWw==}
     engines: {node: '>= 10'}
     cpu: [riscv64]
     os: [linux]
-    libc: [glibc]
 
   '@napi-rs/canvas-linux-x64-gnu@0.1.100':
     resolution: {integrity: sha512-1eCvkDCazm7FFhsT7DfGOdSaHgZVK3bt/dSBl5EWHOWmnz+I7j8tPseJqqD81NF+MH21jKUK4wQSDjN0mdhnTg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   '@napi-rs/canvas-linux-x64-musl@0.1.100':
     resolution: {integrity: sha512-20arT6lnI19S68qNlii73TSEDbECNgzMz2EpldC1V3mZFuRkeujXkcebRk0LRJe9SEUAooYiLokfMViY8IX7yA==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   '@napi-rs/canvas-win32-arm64-msvc@0.1.100':
     resolution: {integrity: sha512-DZFFT1wIAg37LJw37yhMRFfjATd3vTQzjZ1Yki8u2vhO6Hi5VE6BVaGQ1aaDu7xb4iMErz+9EOwjpS7xcxFeBw==}
@@ -3471,7 +3474,7 @@ packages:
       '@nestjs/core': ^10.0.0 || ^11.0.0
       reflect-metadata: ^0.1.13 || ^0.2.0
       rxjs: ^7.2.0
-      typeorm: ^0.3.0 || ^1.0.0-dev
+      typeorm: 0.3.30
 
   '@nestjs/websockets@11.1.27':
     resolution: {integrity: sha512-X3OgJt9KgYTvt9D7sNz9SOj3A1daAHy7DZrYhM1pky8Fh+erlKQH5IQ/tKm+GaJKA5M0srBUr1CMqjak/qNxOw==}
@@ -3508,28 +3511,24 @@ packages:
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   '@next/swc-linux-arm64-musl@14.2.33':
     resolution: {integrity: sha512-Bm+QulsAItD/x6Ih8wGIMfRJy4G73tu1HJsrccPW6AfqdZd0Sfm5Imhgkgq2+kly065rYMnCOxTBvmvFY1BKfg==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   '@next/swc-linux-x64-gnu@14.2.33':
     resolution: {integrity: sha512-FnFn+ZBgsVMbGDsTqo8zsnRzydvsGV8vfiWwUo1LD8FTmPTdV+otGSWKc4LJec0oSexFnCYVO4hX8P8qQKaSlg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   '@next/swc-linux-x64-musl@14.2.33':
     resolution: {integrity: sha512-345tsIWMzoXaQndUTDv1qypDRiebFxGYx9pYkhwY4hBRaOLt8UGfiWKr9FSSHs25dFIf8ZqIFaPdy5MljdoawA==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   '@next/swc-win32-arm64-msvc@14.2.33':
     resolution: {integrity: sha512-nscpt0G6UCTkrT2ppnJnFsYbPDQwmum4GNXYTeoTIdsmMydSKFz9Iny2jpaRupTb+Wl298+Rh82WKzt9LCcqSQ==}
@@ -3626,42 +3625,36 @@ packages:
     engines: {node: '>= 10.0.0'}
     cpu: [arm]
     os: [linux]
-    libc: [glibc]
 
   '@parcel/watcher-linux-arm-musl@2.5.6':
     resolution: {integrity: sha512-Ve3gUCG57nuUUSyjBq/MAM0CzArtuIOxsBdQ+ftz6ho8n7s1i9E1Nmk/xmP323r2YL0SONs1EuwqBp2u1k5fxg==}
     engines: {node: '>= 10.0.0'}
     cpu: [arm]
     os: [linux]
-    libc: [musl]
 
   '@parcel/watcher-linux-arm64-glibc@2.5.6':
     resolution: {integrity: sha512-f2g/DT3NhGPdBmMWYoxixqYr3v/UXcmLOYy16Bx0TM20Tchduwr4EaCbmxh1321TABqPGDpS8D/ggOTaljijOA==}
     engines: {node: '>= 10.0.0'}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   '@parcel/watcher-linux-arm64-musl@2.5.6':
     resolution: {integrity: sha512-qb6naMDGlbCwdhLj6hgoVKJl2odL34z2sqkC7Z6kzir8b5W65WYDpLB6R06KabvZdgoHI/zxke4b3zR0wAbDTA==}
     engines: {node: '>= 10.0.0'}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   '@parcel/watcher-linux-x64-glibc@2.5.6':
     resolution: {integrity: sha512-kbT5wvNQlx7NaGjzPFu8nVIW1rWqV780O7ZtkjuWaPUgpv2NMFpjYERVi0UYj1msZNyCzGlaCWEtzc+exjMGbQ==}
     engines: {node: '>= 10.0.0'}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   '@parcel/watcher-linux-x64-musl@2.5.6':
     resolution: {integrity: sha512-1JRFeC+h7RdXwldHzTsmdtYR/Ku8SylLgTU/reMuqdVD7CtLwf0VR1FqeprZ0eHQkO0vqsbvFLXUmYm/uNKJBg==}
     engines: {node: '>= 10.0.0'}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   '@parcel/watcher-win32-arm64@2.5.6':
     resolution: {integrity: sha512-3ukyebjc6eGlw9yRt678DxVF7rjXatWiHvTXqphZLvo7aC5NdEgFufVwjFfY51ijYEWpXbqF5jtrK275z52D4Q==}
@@ -3715,7 +3708,7 @@ packages:
     peerDependencies:
       '@types/react': '>=16.8.0'
       posthog-js: '>=1.257.2'
-      react: '>=16.8.0'
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3775,8 +3768,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3788,8 +3781,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3801,8 +3794,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3814,8 +3807,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3827,8 +3820,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3840,8 +3833,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3853,8 +3846,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3866,8 +3859,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3879,8 +3872,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3891,7 +3884,7 @@ packages:
     resolution: {integrity: sha512-rYOP8OMnuuPMQF1uhPVlGNcCDlkokKqGFE3JcxFViIkAXP7EvFWUliJAstrapypaBLJNHbZL6jGhbVDGTwmVhA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3901,8 +3894,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3913,7 +3906,7 @@ packages:
     resolution: {integrity: sha512-QwH4PO5urrbO+FaGd5Aglg+YJgWTyyuZ3g/6mKvsqraLkglDdckw9JafgL5McL5VEJ6EPNduPaT3ZE9BttDAqg==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3923,8 +3916,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3935,7 +3928,7 @@ packages:
     resolution: {integrity: sha512-C3vFhbyi4SW3PmbAi6Awpu4OzJtd0MxGurvSsYtr7p7nM8RNB3VAF3CUmnp2j50knpkrRcB7+ycVXzgLgF6yNA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3945,8 +3938,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3958,8 +3951,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3970,7 +3963,7 @@ packages:
     resolution: {integrity: sha512-cot/aB/mOm0IYVYTTmQcEEK1M48lZWi8FlYe5nDPQQ8NYZUlXEFgncJ9p2Kzer3RKSrY7cTTpEMLZKNo9QoP5Q==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3980,8 +3973,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3993,8 +3986,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4006,8 +3999,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4017,13 +4010,13 @@ packages:
   '@radix-ui/react-icons@1.3.2':
     resolution: {integrity: sha512-fyQIhGDhzfc9pK2kH6Pl9c4BDJGfMkPqkyIgYDthyNYoNg3wVhoJMMh19WS4Up/1KMPFVpNsT2q3WmXn2N1m6g==}
     peerDependencies:
-      react: ^16.x || ^17.x || ^18.x || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
 
   '@radix-ui/react-id@1.1.2':
     resolution: {integrity: sha512-orBC88futVpqCmhX1p4cvquNHsELQ+w+vBJnuj3ftETI5bJb0bZn3Tqu3SWN2IOcPycTnMGnhwoermvISt72sA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4033,8 +4026,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4046,8 +4039,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4059,8 +4052,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4072,8 +4065,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4085,8 +4078,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4098,8 +4091,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4111,8 +4104,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4124,8 +4117,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4137,8 +4130,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4150,8 +4143,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4163,8 +4156,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4176,8 +4169,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4189,8 +4182,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4202,8 +4195,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4215,8 +4208,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4228,8 +4221,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4241,8 +4234,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4254,8 +4247,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4266,7 +4259,7 @@ packages:
     resolution: {integrity: sha512-rCMO3QsIVKv5JTY5CVbo2MvO77SpEqqYc8AvRE7OWqRDOIqAKjsp+DrmnY9uc8NPdxB5E2z47HTYGeE2+NTptg==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4276,8 +4269,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4289,8 +4282,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4302,8 +4295,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4315,8 +4308,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4328,8 +4321,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4341,8 +4334,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4354,8 +4347,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4366,7 +4359,7 @@ packages:
     resolution: {integrity: sha512-xCso9j1/u8sEgP1RNHjFrXJLApL8LiqOkI1R4ywuN00rxWdYg4oQXuwKLS3i0j5NWLromUD27/4nlxj2UFVvIw==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4375,7 +4368,7 @@ packages:
     resolution: {integrity: sha512-PLzC90MS+ReootmjC597dvopoelpZ8Q61HJkDXZSExitIq7PL55vHNnesAHwguHK0aPfBnpdNzQtv1uliaqQrA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4384,7 +4377,7 @@ packages:
     resolution: {integrity: sha512-6c8ZqvPTWILEKnyVkP53EGRCcpnJiKTC21sS/6R1GF5xKyHJJWQEPfkqlcgUkdRQivd6tb23abUwe4ngWmY0JA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4393,7 +4386,7 @@ packages:
     resolution: {integrity: sha512-2uVLvLjgO7NZCWw01/FdqRwmA42J0BcjPMUCA+koFEOAb+zjqIP7SiFz/7zWPrKnVmSqr76Omq2ALyCuX4dhLw==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4402,7 +4395,7 @@ packages:
     resolution: {integrity: sha512-qwOiz4Tjo8CNnrOLAYUMXeZwDzXgXpvK4TKQPmWLECM9XoWvA6+0Z2/7Ag3A4ivjS4ovbLJPbskkxioFyBhr8A==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4411,7 +4404,7 @@ packages:
     resolution: {integrity: sha512-jrBWOxZITuGcnjRCM2t2U5ZPkCLxD+Ym6DjfssS5haTj2iiak/DOb64JeN6OdLfLgptb6/e2kKR+ZuTrGoZTPA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4420,7 +4413,7 @@ packages:
     resolution: {integrity: sha512-IGBQPtRFdhN6MQ8dbegVmBq1LVZluya3F1jWY+puIcQC3MHctRwTDSBWCkL/3ZcnMJLTMJ++Z+ktmvg0F89iCw==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4429,7 +4422,7 @@ packages:
     resolution: {integrity: sha512-d8a+bBY/FxikNPlgJJoaBHZX+zKVbWHYJGTLnLvveQgFSTntkGdEKv3JDtHrMS0DNYpllz2nRsTLGLKYttbpmw==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4438,7 +4431,7 @@ packages:
     resolution: {integrity: sha512-giWQp+4mxjBPt4KZ0MmyuykFNWfbDxKt4x+fPkRYmgRFJSbCZFzUglvMb/Kjn38tm10YP4ufiQZDx3zna4LU6w==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4448,8 +4441,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4462,111 +4455,111 @@ packages:
   '@react-pdf-viewer/attachment@3.12.0':
     resolution: {integrity: sha512-mhwrYJSIpCvHdERpLUotqhMgSjhtF+BTY1Yb9Fnzpcq3gLZP+Twp5Rynq21tCrVdDizPaVY7SKu400GkgdMfZw==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/bookmark@3.12.0':
     resolution: {integrity: sha512-i7nEit8vIFMAES8RFGwprZ9cXOOZb9ZStPW6E6yuObJEXcvBj/ctsbBJGZxqUZOGklM0JoB7sjHyxAriHfe92A==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/core@3.12.0':
     resolution: {integrity: sha512-8MsdlQJ4jaw3GT+zpCHS33nwnvzpY0ED6DEahZg9WngG++A5RMhk8LSlxdHelwaFFHFiXBjmOaj2Kpxh50VQRg==}
     peerDependencies:
-      pdfjs-dist: ^2.16.105 || ^3.0.279
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      pdfjs-dist: ^3.11.174
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/default-layout@3.12.0':
     resolution: {integrity: sha512-K2fS4+TJynHxxCBFuIDiFuAw3nqOh4bkBgtVZ/2pGvnFn9lLg46YGLMnTXCQqtyZzzXYh696jmlFViun3is4pA==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/full-screen@3.12.0':
     resolution: {integrity: sha512-hQouJ26QUaRBCXNMU1aI1zpJn4l4PJRvlHhuE2dZYtLl37ycjl7vBCQYZW1FwnuxMWztZsY47R43DKaZORg0pg==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/get-file@3.12.0':
     resolution: {integrity: sha512-Uhq45n2RWlZ7Ec/BtBJ0WQESRciaYIltveDXHNdWvXgFdOS8XsvB+mnTh/wzm7Cfl9hpPyzfeezifdU9AkQgQg==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/open@3.12.0':
     resolution: {integrity: sha512-vhiDEYsiQLxvZkIKT9VPYHZ1BOnv46x9eCEmRWxO1DJ8fa/GRDTA9ivXmq/ap0dGEJs6t+epleCkCEfllLR/Yw==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/page-navigation@3.12.0':
     resolution: {integrity: sha512-tVEJ48Dd5kajV1nKkrPWijglJRNBiKBTyYDKVexhiRdTHUP1f6QQXiSyDgCUb0IGSZeJzOJb1h7ApKHe8OTtuw==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/print@3.12.0':
     resolution: {integrity: sha512-xJn76CgbU/M2iNaN7wLHTg+sdOekkRMfCakFLwPrE+SR7qD6NUF4vQQKJBSVCCK5bUijzb6cWfKGfo8VA72o4Q==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/properties@3.12.0':
     resolution: {integrity: sha512-dYTCHtVwFNkpDo7QxL2qk/8zAKndLwdD1FFxBftl6jIlQbtvNdxkFfkv1HcQING9Ic+7DBryOiD7W0ze4IERYg==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/rotate@3.12.0':
     resolution: {integrity: sha512-yaxaMYPChvNOjR8+AxRmj0kvojyJKPq4XHEcIB2lJJgBY1Zra3mliDUP3Nlb4yV8BS9+yBqWn9U9mtnopQD+tw==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/scroll-mode@3.12.0':
     resolution: {integrity: sha512-okII7Xqhl6cMvl1izdEvlXNJ+vJVq/qdg53hJIDYVgBCWskLk/cpjUg/ZonBxseG9lIDP3w2VO1McT8Gn11OAg==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/search@3.12.0':
     resolution: {integrity: sha512-jAkLpis49fsDDY/HrbUZIOIhzF5vynONQNA4INQKI38r/MjveblrkNv7qbr9j5lQ/WFic5+gD1e+Mtpf1/7DiA==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/selection-mode@3.12.0':
     resolution: {integrity: sha512-yysWEu2aCtBvzSgbhgI9kT5cq2hf0FU6Z+3B7MMXz14Kxyc3y18wUqxtgbvpFEfWF0bNUUq16JtWRljtxvZ83w==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/theme@3.12.0':
     resolution: {integrity: sha512-cdBi+wR1VOZ6URCcO9plmAZQu4ZGFcd7HJdBe7VIFiGyrvl9I/Of74ONLycnDImSuONt8D3uNjPBLieeaShVeg==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/thumbnail@3.12.0':
     resolution: {integrity: sha512-Vc8j3bO6wumWZV4o6pAbktPWKDSC9tQAzOCJ3cof541u4i44C11ccYC4W9aNcsMMUSO3bNwAGWtP8OFthV5akQ==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/toolbar@3.12.0':
     resolution: {integrity: sha512-qACTU3qXHgtNK8J+T13EWio+0liilj86SJ87BdapqXynhl720OKPlSKOQqskUGqg3oTUJAhrse9XG6SFdHJx+g==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/zoom@3.12.0':
     resolution: {integrity: sha512-V0GUTyPM77+LzhoKX+T3XI10/HfGdqRTbgeP7ID60FCzcwu6kXWqJn5tzabjDKLTlFv8mJmn0aa/ppkIU97nfA==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf/fns@3.1.3':
     resolution: {integrity: sha512-0I7pApDr1/RLAKbizuLy/IHTEa93LSPy/bEwYniboC3Xqnp6Od8xFJKbKEzGw2wh/5zKFFwl00g4t9RwgIMc3w==}
@@ -4589,7 +4582,7 @@ packages:
   '@react-pdf/reconciler@2.0.0':
     resolution: {integrity: sha512-7zaPRujpbHSmCpIrZ+b9HSTJHthcVZzX0Wx7RzvQGsGBUbHP4p6s5itXrAIOuQuPvDepoHGNOvf6xUuMVvdoyw==}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
 
   '@react-pdf/render@4.5.1':
     resolution: {integrity: sha512-IW/N4HWJWtioBXCf7n02IR24VJJ8gbdS3jGypf+vW/rSErEx3/URRzh9UK6Ma8Fpog9+T/W6GE2NHJ5AAKHhVA==}
@@ -4597,7 +4590,7 @@ packages:
   '@react-pdf/renderer@4.5.1':
     resolution: {integrity: sha512-5r1VQrE6FRLXX5wWUxwZzM24E2BJMo6g8AQWuS8WyPs9ugu5yMnb2g8/RpPYka/Z6J+RUEWc32wty2NoUJF42Q==}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
 
   '@react-pdf/stylesheet@6.2.1':
     resolution: {integrity: sha512-2+UEk+7e+z8baaWi2l5kPLWmwtJeOI+T5wW9GGeN3iDH7vd3kbTqOpN1yt9mmfNVZFxQsnDHpznFb5v5UF983A==}
@@ -4614,7 +4607,7 @@ packages:
   '@reduxjs/toolkit@2.12.0':
     resolution: {integrity: sha512-KiT+RzZbp6mQET+Mg+h2c97+9j1sNflUxQkIHI7Yuzf6Peu+OYpmkn6nbHWmLLWj+1ZODUJFwGZ7gx3L9R9EOw==}
     peerDependencies:
-      react: ^16.9.0 || ^17.0.0 || ^18 || ^19
+      react: 19.2.6
       react-redux: ^7.2.1 || ^8.1.3 || ^9.0.0
     peerDependenciesMeta:
       react:
@@ -4663,79 +4656,66 @@ packages:
     resolution: {integrity: sha512-Q8CBCCQtDFrYtXoeUXSrnFXKOnyUhx6bz+SkL6A0E7V8kAiCJ5pamq1WtbfpVGhR5TSpXY6ak3avmDc5fHTyJA==}
     cpu: [arm]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-arm-musleabihf@4.61.1':
     resolution: {integrity: sha512-nwnhk1581l0FBVellGcVCAT0Oi06onEA3WB53sf01VO3I0UPBkMH9sXONYME2K0ovXcNayJfNtHfm6mpJElatQ==}
     cpu: [arm]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-arm64-gnu@4.61.1':
     resolution: {integrity: sha512-x5Xr49hwt3hdW75UOZm3395YwwzPyauktslv29KpWL/T+vVAzoT3azLcTWv0eMciBNrx+DYjH4paehHoLpPvpg==}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-arm64-musl@4.61.1':
     resolution: {integrity: sha512-unMS3H73DpaoPyyEVPjGKleM/s0mkmsauTENpw4INQY8y4+IuLNjkueQ5QCtC0D3N38Y38yhAU8OoZ20S2Tm6w==}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-loong64-gnu@4.61.1':
     resolution: {integrity: sha512-zNZzGRnAhwjFEYmvphJRV5XaQGjs62cCmeYYHUT//NbvEnHauw+I85nGG+SiVg5ld4GX8D1IbKIX+ozITQnhMQ==}
     cpu: [loong64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-loong64-musl@4.61.1':
     resolution: {integrity: sha512-LdpWGL8X209B2SIvWjqlc8VZgM6PKfontSerGepuldQmHYrAOtnMCXeJkxXGbC+PPZVOuu5czJo7fNV6aeW8rQ==}
     cpu: [loong64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-ppc64-gnu@4.61.1':
     resolution: {integrity: sha512-EC5kTtNaNGOmbMGqar8dvJy6y/hg99GAwjfBz++pxZhQATXGcRjd6c5en5wcbru0vkRmiMGsQKdMJOOf6sza4g==}
     cpu: [ppc64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-ppc64-musl@4.61.1':
     resolution: {integrity: sha512-8hiwp6D4acEcNK78I4rP0/XtS1sknWIAMJBPdR4l6zUtyTm5KiTDr5bXmWt4foY7nAN7AThDHgkLIEZOWKbzWw==}
     cpu: [ppc64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-riscv64-gnu@4.61.1':
     resolution: {integrity: sha512-10dh/h/BqA7DuMPWSxkR8uks18FRwnwOEqr5zOTEl+NOwP/OMzKX8OFR/Of9xxDA7D5qef1Nzar5WDD2kCCr1g==}
     cpu: [riscv64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-musl@4.61.1':
     resolution: {integrity: sha512-YKJ5lg35DP17gcAOggnihe+APw9HLyj1Xn7gsmGumBJAUDa6NGXNixJzmkWLhcK9TOuuyQjdamzvJefkO7qHZQ==}
     cpu: [riscv64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-s390x-gnu@4.61.1':
     resolution: {integrity: sha512-Mlil5G2Jj6a7B3LWGctg+XPL9vdXYuzCtNXfxOQ0nPjc2m6ueUktocPGH9bnAM0bNRKb/bAWTujUU7IJQdQA+g==}
     cpu: [s390x]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-x64-gnu@4.61.1':
     resolution: {integrity: sha512-bVWIOIk6pV01p4CdUbPP7CJ/434z+OooYjDuFcR+44N35YvKUC66G8MGnvcWx5mWKW3g61J+t74l3Kj15Kwn2Q==}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-x64-musl@4.61.1':
     resolution: {integrity: sha512-qy5pBvZbqNFheBz61R1rzsezjm0J7O2oNGoWtGoY89SZYLUfxAJTBAqDChqAIdB4rCiIbi9nF7yZ83GnNiLwSw==}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-openbsd-x64@4.61.1':
     resolution: {integrity: sha512-E83TXjI4zm0+5f2qO+UOudaCYIhYwpJ5jq6YCZNIZ+6CbfhKrkAGezeiASBL9ElxAxFsRS9ZhESv8mfnj6TKeg==}
@@ -4832,7 +4812,7 @@ packages:
   '@tabler/icons-react@3.44.0':
     resolution: {integrity: sha512-8+rvzBbVm/1Z3sG3x7GUNAaxIKxwgz8xaMhRs23nrCnMTKRFAhEC+82zAIFeAA0seXdrAGX5HFCkaLpGK2rVHg==}
     peerDependencies:
-      react: '>= 16'
+      react: 19.2.6
 
   '@tabler/icons@3.44.0':
     resolution: {integrity: sha512-Wn0AOZG9sg0L+bjfMqq4eNhC6pQjIrk94LvvWYNYkY8KH8wC3YILRzQlrnVJc4FUeMxH/AK97QsYCX35H3LndA==}
@@ -4879,28 +4859,24 @@ packages:
     engines: {node: '>= 20'}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   '@tailwindcss/oxide-linux-arm64-musl@4.3.0':
     resolution: {integrity: sha512-Z6sukiQsngnWO+l39X4pPbiWT81IC+PLKF+PHxIlyZbGNb9MODfYlXEVlFvej5BOZInWX01kVyzeLvHsXhfczQ==}
     engines: {node: '>= 20'}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   '@tailwindcss/oxide-linux-x64-gnu@4.3.0':
     resolution: {integrity: sha512-DRNdQRpSGzRGfARVuVkxvM8Q12nh19l4BF/G7zGA1oe+9wcC6saFBHTISrpIcKzhiXtSrlSrluCfvMuledoCTQ==}
     engines: {node: '>= 20'}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   '@tailwindcss/oxide-linux-x64-musl@4.3.0':
     resolution: {integrity: sha512-Z0IADbDo8bh6I7h2IQMx601AdXBLfFpEdUotft86evd/8ZPflZe9COPO8Q1vw+pfLWIUo9zN/JGZvwuAJqduqg==}
     engines: {node: '>= 20'}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   '@tailwindcss/oxide-wasm32-wasi@4.3.0':
     resolution: {integrity: sha512-HNZGOUxEmElksYR7S6sC5jTeNGpobAsy9u7Gu0AskJ8/20FR9GqebUyB+HBcU/ax6BHuiuJi+Oda4B+YX6H1yA==}
@@ -4949,32 +4925,32 @@ packages:
     resolution: {integrity: sha512-cpZA0+WqKXwrwMfiWZEGGF6QrIWVQFbhBtxqDF5sQsAfrFf47HIE6fiPbQU3wyAUEN2+7UNqLCQe7oG6m3f93w==}
     peerDependencies:
       '@tanstack/react-query': ^5.101.0
-      react: ^18 || ^19
+      react: 19.2.6
 
   '@tanstack/react-query@5.101.0':
     resolution: {integrity: sha512-rLlJXSpkqfizLWgkR5+eLeIk0MvTx/meEIR7LRjxic+qxiQP8zVjq7BqQkiCMNLQBlLfuOLqqr6KO5GtrDlmSg==}
     peerDependencies:
-      react: ^18 || ^19
+      react: 19.2.6
 
   '@tanstack/react-table@8.20.5':
     resolution: {integrity: sha512-WEHopKw3znbUZ61s9i0+i9g8drmDo6asTWbrQh8Us63DAk/M0FkmIqERew6P71HI75ksZ2Pxyuf4vvKh9rAkiA==}
     engines: {node: '>=12'}
     peerDependencies:
-      react: '>=16.8'
-      react-dom: '>=16.8'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@tanstack/react-table@8.21.3':
     resolution: {integrity: sha512-5nNMTSETP4ykGegmVkhjcS8tTLW6Vl4axfEGQN3v0zdHYbK4UfoqfPChclTrJ4EoK9QynqAu9oUf8VEmrpZ5Ww==}
     engines: {node: '>=12'}
     peerDependencies:
-      react: '>=16.8'
-      react-dom: '>=16.8'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@tanstack/react-virtual@3.11.2':
     resolution: {integrity: sha512-OuFzMXPF4+xZgx8UzJha0AieuMihhhaWG0tCqpp6tDzlFwOmNBPYMuLOtMJ1Tr4pXLHmgjcWhG6RlknY2oNTdQ==}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@tanstack/table-core@8.20.5':
     resolution: {integrity: sha512-P9dF7XbibHph2PFRz8gfBKEXEY/HJPOhym8CHmjF8y3q5mWpKx9xtZapXQUWCgkqvsK0R46Azuz+VaxD4Xl+Tg==}
@@ -4990,8 +4966,8 @@ packages:
   '@tinymce/tinymce-react@6.3.0':
     resolution: {integrity: sha512-E++xnn0XzDzpKr40jno2Kj7umfAE6XfINZULEBBeNjTMvbACWzA6CjiR6V8eTDc9yVmdVhIPqVzV4PqD5TZ/4g==}
     peerDependencies:
-      react: ^19.0.0 || ^18.0.0 || ^17.0.1 || ^16.7.0
-      react-dom: ^19.0.0 || ^18.0.0 || ^17.0.1 || ^16.7.0
+      react: 19.2.6
+      react-dom: 19.2.6
       tinymce: ^8.0.0 || ^7.0.0 || ^6.0.0 || ^5.5.1
     peerDependenciesMeta:
       tinymce:
@@ -5021,20 +4997,7 @@ packages:
       '@nestjs/typeorm': ^11.0.0
       reflect-metadata: ^0.2.0
       rxjs: ^7.8.0
-      typeorm: ^0.3.0
-
-  '@tria-plc/auditlog@file:local-packages/tria-plc-auditlog-1.1.2.tgz':
-    resolution: {integrity: sha512-3kRaAtETvM9wVRSbwd2jyrts9DCcSV9yFUDoEpxJfVQDsIGY2d9K0c+h1LAjfNNaogZ8eeBcroyCrnWjwBmkYA==, tarball: file:local-packages/tria-plc-auditlog-1.1.2.tgz}
-    version: 1.1.2
-    engines: {node: '>=18'}
-    peerDependencies:
-      '@nestjs/common': ^10.0.0 || ^11.0.0
-      '@nestjs/core': ^10.0.0 || ^11.0.0
-      '@nestjs/microservices': ^10.0.0 || ^11.0.0
-      '@nestjs/swagger': ^10.0.0 || ^11.0.0
-      '@nestjs/typeorm': ^10.0.0 || ^11.0.0
-      rxjs: ^7.0.0
-      typeorm: ^0.3.0
+      typeorm: 0.3.30
 
   '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz':
     resolution: {integrity: sha512-rfHSXOm/0VUMTj7HrvYysrEAqxItqfPs4Rd35qWJyaAk+snF1wTKFRVz6cRGPoQNj8fhplkVAefnvuKBuHT+xQ==, tarball: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz}
@@ -5056,15 +5019,15 @@ packages:
       class-validator: ^0.14.1
       reflect-metadata: ^0.2.0
       rxjs: ^7.8.0
-      typeorm: ^0.3.0
+      typeorm: 0.3.30
 
   '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz':
     resolution: {integrity: sha512-FTihoH0lIqKV/0s+FTJZokQw8xX3XztXIqT8eEYEZgDM2xyzVSCHY8pHCUxw0MQtiR8R97zxZJ/o192eWt+E/g==, tarball: file:local-packages/tria-plc-iamui-0.1.1.tgz}
     version: 0.1.1
     engines: {node: '>=18'}
     peerDependencies:
-      react: ^18.3.1 || ^19.0.0
-      react-dom: ^18.3.1 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@ts-morph/common@0.27.0':
     resolution: {integrity: sha512-Wf29UqxWDpc+i61k3oIOzcUfQt79PIT9y/MWfAGlrkjg6lBC1hwDECLXPVJAhWjiGbfBCxZd65F/LIZF3+jeJQ==}
@@ -5513,61 +5476,51 @@ packages:
     resolution: {integrity: sha512-zJc0H99FEPoFfSrNpa91HYfxzfAJCr502oxNK1cfdC9hlaFI43RT+JFCann9JUgZmLzzntChHyn13Sgn9ljHNg==}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   '@unrs/resolver-binding-linux-arm64-musl@1.12.2':
     resolution: {integrity: sha512-KQ3Lki6l+Pz1k/eBipN41ES+YUK30beLGb9YqcB1O542cyLCNE6GaxrfcY3T6EezmGGk84wb5XyO9loTM9tkcA==}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   '@unrs/resolver-binding-linux-loong64-gnu@1.12.2':
     resolution: {integrity: sha512-3SJGEh1DborhG6pyxvhPzCT4bbSIVihsvgJc13P1bHG7KLdNDaF9T3gsTwFc7Jw/5Y5/iWOjkEx7Zy0NvCGX3Q==}
     cpu: [loong64]
     os: [linux]
-    libc: [glibc]
 
   '@unrs/resolver-binding-linux-loong64-musl@1.12.2':
     resolution: {integrity: sha512-jiuG/Obbel7uw1PwHNFfrkiKhLAF6mnyZ6aWlOAVN9WqKm8v0OFGnciJIHu8+CMvXLQ8AD51LPzAoUfT21D5Ew==}
     cpu: [loong64]
     os: [linux]
-    libc: [musl]
 
   '@unrs/resolver-binding-linux-ppc64-gnu@1.12.2':
     resolution: {integrity: sha512-q7xRvVpmcfeL+LlZg8Pbbo6QaTZwDU5BaGZbwfhkEsXJn3Was8xYfE0RBH266xZt0rM6B7i8xAYIvjthuUIWHg==}
     cpu: [ppc64]
     os: [linux]
-    libc: [glibc]
 
   '@unrs/resolver-binding-linux-riscv64-gnu@1.12.2':
     resolution: {integrity: sha512-0CVdx6lcnT3Q9inOH8tsMIOJ6ImndllMjqJHg8RLVdB7Vq4SfkEXl9mCSsVNuNA4MCYycRicCUxPCabVHJRr6A==}
     cpu: [riscv64]
     os: [linux]
-    libc: [glibc]
 
   '@unrs/resolver-binding-linux-riscv64-musl@1.12.2':
     resolution: {integrity: sha512-iOwlRo9vnp6R6ohHQS11n0NnfdXx/omhkocmIfaPRpQhKZ+3BDMkkdRVh53qjkFkpPddf+FETA28NwGN7l5l+w==}
     cpu: [riscv64]
     os: [linux]
-    libc: [musl]
 
   '@unrs/resolver-binding-linux-s390x-gnu@1.12.2':
     resolution: {integrity: sha512-HYJtLfXq94q8iZNFT1lknx258wlkkWhZeUXJRqzKBBUJ00CvZ+N33zgbCqimLjsyw5Va6uUxhVa12mI+kaveEw==}
     cpu: [s390x]
     os: [linux]
-    libc: [glibc]
 
   '@unrs/resolver-binding-linux-x64-gnu@1.12.2':
     resolution: {integrity: sha512-mPsUhunKKDih5O96Y6enDQyHc1SqBPlY1E/SfMWDM3EdJ95Z9CArPeCVwCCqbP45ljvivdEk8Fxn+SIb1rDAJQ==}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   '@unrs/resolver-binding-linux-x64-musl@1.12.2':
     resolution: {integrity: sha512-azrt6+5ydLd8Vt210AAFis/lZevSfPw93EJRIJG+xPu4WCJ8K0kppCTpMyLPcKT7H15M4Jnt2tMp5bOvCkRC6A==}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   '@unrs/resolver-binding-openharmony-arm64@1.12.2':
     resolution: {integrity: sha512-YZ9hP4O0X9PQb8eO980qmLNGH4zT3I9+SZTdt0Pr0YyuGQhYKoOZkV02VzrzyOZJ5xIJ3UFIenKkUkGg8GjgWQ==}
@@ -5597,8 +5550,8 @@ packages:
   '@vis.gl/react-google-maps@1.8.3':
     resolution: {integrity: sha512-DW7nEuvOJ299DmdBnvGiUARrgS/+sTEO1iJgG9J8YaErZqLoq7S4TJ22f3EjJvR4dti4L4gft43JEK77nnKXDw==}
     peerDependencies:
-      react: '>=16.8.0 || ^19.0 || ^19.0.0-rc'
-      react-dom: '>=16.8.0 || ^19.0 || ^19.0.0-rc'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@vitejs/plugin-react@4.7.0':
     resolution: {integrity: sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==}
@@ -5693,6 +5646,9 @@ packages:
     resolution: {integrity: sha512-E+iruNOY8VV9s4JEbe1aNEm6MiszPRr/UfcHMz0TQh1BXSxHK+ASV1R6W4HpjBhSeS+54PIsAMCBmwD06LLsqQ==}
     hasBin: true
 
+  abbrev@1.1.1:
+    resolution: {integrity: sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==}
+
   abort-controller@3.0.0:
     resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==}
     engines: {node: '>=6.5'}
@@ -5973,6 +5929,9 @@ packages:
   append-field@1.0.0:
     resolution: {integrity: sha512-klpgFSWLW1ZEs8svjfb7g4qWY0YS5imI82dTg+QahUvJ8YqAY0P10Uk8tTyh9ZGuYEZEMaeJYCF5BFuX552hsw==}
 
+  aproba@2.1.0:
+    resolution: {integrity: sha512-tLIEcj5GuR2RSTnxNKdkK0dJ/GrC7P38sUkiDmDuHfsHmbagTFAxDVIBltoklXEVIQ/f14IL8IMJ5pn9Hez1Ew==}
+
   arch@2.2.0:
     resolution: {integrity: sha512-Of/R0wqp83cgHozfIYLbBMnej79U/SVGOOyuB3VVFv1NRM/PSFMK12x9KVtiYzJqmnU5WR2qp0Z5rHb7sWGnFQ==}
 
@@ -5988,6 +5947,11 @@ packages:
     resolution: {integrity: sha512-+25nxyyznAXF7Nef3y0EbBeqmGZgeN/BxHX29Rs39djAfaFalmQ89SE6CWyDCHzGL0yt/ycBtNOmGTW0FyGWNw==}
     engines: {node: '>= 10'}
 
+  are-we-there-yet@2.0.0:
+    resolution: {integrity: sha512-Ci/qENmwHnsYo9xKIcUJN5LeDKdJ6R1Z1j9V/J5wyq8nh/mYPEpIKJbBZXtZjG04HiK7zV/p6Vs9952MrMeUIw==}
+    engines: {node: '>=10'}
+    deprecated: This package is no longer supported.
+
   arg@4.1.3:
     resolution: {integrity: sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==}
 
@@ -6462,6 +6426,10 @@ packages:
   caniuse-lite@1.0.30001797:
     resolution: {integrity: sha512-l8xKG+gwAIExZGl9FrF7KUwuOmk6wbEPC9Xoy/RtnWv1XG0Q4LFlagaLpUv3Kiza3W/wm27zy0yWJEieYKAP6w==}
 
+  canvas@2.11.2:
+    resolution: {integrity: sha512-ItanGBMrmRV7Py2Z+Xhs7cT+FNt5K0vPL4p9EZ/UX/Mu7hFbkxSjKF2KVtPwX7UYWp7dRKnrTvReflgrItJbdw==}
+    engines: {node: '>=6'}
+
   canvg@3.0.11:
     resolution: {integrity: sha512-5ON+q7jCTgMp9cjpu4Jo6XbvfYwSB2Ow3kzHKfIyJfaCAOHLbdKPQqGKgfED/R5B+3TFFfe8pegYA+b423SRyA==}
     engines: {node: '>=10.0.0'}
@@ -6529,6 +6497,10 @@ packages:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
 
+  chownr@2.0.0:
+    resolution: {integrity: sha512-bIomtDF5KGpdogkLd9VspvFzk9KfpyyGlS8YFVZl7TGPBHL5snIOnxeshwVgPteQ9b4Eydl+pVbIyE1DcvCWgQ==}
+    engines: {node: '>=10'}
+
   chrome-trace-event@1.0.4:
     resolution: {integrity: sha512-rNjApaLzuwaOTjCiT8lSDdGN1APCiqkChLMJxJPWLunPAt5fy8xgU9/jNOchV84wfIxrA0lRQB7oCT8jrn/wrQ==}
     engines: {node: '>=6.0'}
@@ -6647,8 +6619,8 @@ packages:
   cmdk@1.1.1:
     resolution: {integrity: sha512-Vsv7kFaXm+ptHDMZ7izaRsP70GgrW9NBNGswt9OZaVBLlE0SNpDq8eu/VGXyF9r7M0azK3Wy7OlYXsuyYLFzHg==}
     peerDependencies:
-      react: ^18 || ^19 || ^19.0.0-rc
-      react-dom: ^18 || ^19 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
 
   co@4.6.0:
     resolution: {integrity: sha512-QVb0dM5HvG+uaxitm8wONl7jltx8dqhfU33DcqtOZcLSVIKSDDLDi7+0LbAKiyI8hD9u42m2YxXSkMGWThaecQ==}
@@ -6690,6 +6662,10 @@ packages:
     resolution: {integrity: sha512-Bb6Cq8oq0IjDOe8wJmi4JeNn763Xs9cfrBcaylK1tPypWzyoy2G3l90v9k64kjphl/ZJjPIShFztenRomi8WTg==}
     engines: {node: '>=18'}
 
+  color-support@1.1.3:
+    resolution: {integrity: sha512-qiBjkpbMLO/HL68y+lh4q0/O1MZFj2RX6X/KmMa3+gJD3z+WwI1ZzDHysvqHGS3mP6mznPckpXmw1nI9cJjyRg==}
+    hasBin: true
+
   colorette@2.0.20:
     resolution: {integrity: sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==}
 
@@ -6765,6 +6741,9 @@ packages:
     resolution: {integrity: sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==}
     engines: {node: ^14.18.0 || >=16.10.0}
 
+  console-control-strings@1.1.0:
+    resolution: {integrity: sha512-ty/fTekppD2fIwRvnZAVdeOiGd1c7YXEixbgJTNzqcxJWKQnjJ/V1bNEEE6hygpM3WjwHFUVK6HTjWSzV4a8sQ==}
+
   content-disposition@0.5.4:
     resolution: {integrity: sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==}
     engines: {node: '>= 0.6'}
@@ -7035,9 +7014,6 @@ packages:
   date-fns@3.6.0:
     resolution: {integrity: sha512-fRHTG8g/Gif+kSh50gaGEdToemgfj74aRX3swtiouboip5JDLAyDE9F11nHMIcvOaXeOC6D7SpNhi7uFyB7Uww==}
 
-  date-fns@4.4.0:
-    resolution: {integrity: sha512-+1UMbeh68lH1SegH83CGWwpb6OHHbpSgr3+s5Eww5M4CAgswBpoWS0AjTOfEJ33HiYKz1hdj/KTFprzXHmq/6w==}
-
   date.js@0.3.3:
     resolution: {integrity: sha512-HgigOS3h3k6HnW011nAb43c5xx5rBXk8P2v/WIT9Zv4koIaVXiH2BURguI78VVp+5Qc076T7OR378JViCnZtBw==}
 
@@ -7094,6 +7070,10 @@ packages:
     resolution: {integrity: sha512-FqUYQ+8o158GyGTrMFJms9qh3CqTKvAqgqsTnkLI8sKu0028orqBhxNMFkFen0zGyg6epACD32pjVk58ngIErQ==}
     engines: {node: '>=0.10'}
 
+  decompress-response@4.2.1:
+    resolution: {integrity: sha512-jOSne2qbyE+/r8G1VU+G/82LBs2Fs4LAsTiLSHOCOMZQl2OKZ6i8i4IyHemTe+/yIXOtTcRQMzPcgyhoFlqPkw==}
+    engines: {node: '>=8'}
+
   dedent@1.7.2:
     resolution: {integrity: sha512-WzMx3mW98SN+zn3hgemf4OzdmyNhhhKz5Ay0pUfQiMQ3e1g+xmTJWp/pKdwKVXhdSkAEGIIzqeuWrL3mV/AXbA==}
     peerDependencies:
@@ -7171,6 +7151,9 @@ packages:
     resolution: {integrity: sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==}
     engines: {node: '>=0.4.0'}
 
+  delegates@1.0.0:
+    resolution: {integrity: sha512-bd2L678uiWATM6m5Z1VzNCErI3jiGzt6HGY8OVICs40JQq/HALfbyNJmp0UDakEY4pMMaN0Ly5om/B1VI/+xfQ==}
+
   depd@2.0.0:
     resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==}
     engines: {node: '>= 0.8'}
@@ -7288,7 +7271,7 @@ packages:
   downshift@7.6.2:
     resolution: {integrity: sha512-iOv+E1Hyt3JDdL9yYcOgW7nZ7GQ2Uz6YbggwXvKUSleetYhU2nXD482Rz6CzvM4lvI1At34BYruKAL4swRGxaA==}
     peerDependencies:
-      react: '>=16.12.0'
+      react: 19.2.6
 
   dunder-proto@1.0.1:
     resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
@@ -7982,8 +7965,8 @@ packages:
     resolution: {integrity: sha512-uaBd3qC1v3KQqBEjwTUd183K6PbS+j0yR9w9VmEOLWA/tnUcSn8Xa3uck7t4dgpDoUss8xQTcj8W2L07lrnLFg==}
     peerDependencies:
       '@emotion/is-prop-valid': '*'
-      react: ^18.0.0 || ^19.0.0
-      react-dom: ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@emotion/is-prop-valid':
         optional: true
@@ -8019,6 +8002,10 @@ packages:
     resolution: {integrity: sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ==}
     engines: {node: '>=10'}
 
+  fs-minipass@2.1.0:
+    resolution: {integrity: sha512-V/JgOLFCS+R6Vcq0slCuaeWEdNC3ouDlJMNIsacH2VtALiu9mV4LPrHc5cDl8k5aw6J8jwgWWpiTo5RYhmIzvg==}
+    engines: {node: '>= 8'}
+
   fs-monkey@1.1.0:
     resolution: {integrity: sha512-QMUezzXWII9EV5aTFXW1UBVUO77wYPpjqIF8/AviUCThNeSYZykpoTixUeaNNBwmCev0AMDWMAni+f8Hxb1IFw==}
 
@@ -8053,6 +8040,11 @@ packages:
   fuzzysort@3.1.0:
     resolution: {integrity: sha512-sR9BNCjBg6LNgwvxlBd0sBABvQitkLzoVY9MYYROQVX/FvfJ4Mai9LsGhDgd8qYdds0bY77VzYd5iuB+v5rwQQ==}
 
+  gauge@3.0.2:
+    resolution: {integrity: sha512-+5J6MS/5XksCuXq++uFRsnUd7Ovu1XenbeuIuNRJxYWjgQbPuFhT14lAvsWfqfAmnwluf1OwMjz39HjfLPci0Q==}
+    engines: {node: '>=10'}
+    deprecated: This package is no longer supported.
+
   generator-function@2.0.1:
     resolution: {integrity: sha512-SFdFmIJi+ybC0vjlHN0ZGVGHc3lgE0DxPAT0djjVg+kjOnSqclqmj0KQ7ykTOLP6YxoqOvuAODGdcHJn+43q3g==}
     engines: {node: '>= 0.4'}
@@ -8254,6 +8246,9 @@ packages:
     resolution: {integrity: sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==}
     engines: {node: '>= 0.4'}
 
+  has-unicode@2.0.1:
+    resolution: {integrity: sha512-8Rf9Y83NBReMnx0gFzA8JImQACstCYWUplepDa9xprwwtmgEZUF0h/i5xSA625zB/I37EtrswSST6OXxwaaIJQ==}
+
   has-value@0.3.1:
     resolution: {integrity: sha512-gpG936j8/MzaeID5Yif+577c17TxaDmhuyVgSwtnL/q8UUTySg8Mecb+8Cf1otgLoD7DDH75axp86ER7LFsf3Q==}
     engines: {node: '>=0.10.0'}
@@ -8488,8 +8483,8 @@ packages:
   input-format@0.3.14:
     resolution: {integrity: sha512-gHMrgrbCgmT4uK5Um5eVDUohuV9lcs95ZUUN9Px2Y0VIfjTzT2wF8Q3Z4fwLFm7c5Z2OXCm53FHoovj6SlOKdg==}
     peerDependencies:
-      react: '>=18.1.0'
-      react-dom: '>=18.1.0'
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       react:
         optional: true
@@ -9295,28 +9290,24 @@ packages:
     engines: {node: '>= 12.0.0'}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   lightningcss-linux-arm64-musl@1.32.0:
     resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
     engines: {node: '>= 12.0.0'}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   lightningcss-linux-x64-gnu@1.32.0:
     resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   lightningcss-linux-x64-musl@1.32.0:
     resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   lightningcss-win32-arm64-msvc@1.32.0:
     resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
@@ -9363,7 +9354,7 @@ packages:
   little-state-machine@4.8.1:
     resolution: {integrity: sha512-liPHqaWMQ7rzZryQUDnbZ1Gclnnai3dIyaJ0nAgwZRXMzqbYrydrlCI0NDojRUbE5VYh5vu6hygEUZiH77nQkQ==}
     peerDependencies:
-      react: ^16.8.0 || ^17 || ^18 || ^19
+      react: 19.2.6
 
   load-esm@1.0.3:
     resolution: {integrity: sha512-v5xlu8eHD1+6r8EHTg6hfmO97LN8ugKtiXcy5e6oN72iD2r6u0RPfLl6fxM+7Wnh2ZRq15o0russMst44WauPA==}
@@ -9554,17 +9545,17 @@ packages:
   lucide-react@0.446.0:
     resolution: {integrity: sha512-BU7gy8MfBMqvEdDPH79VhOXSEgyG8TSPOKWaExWGCQVqnGH7wGgDngPbofu+KdtVjPQBWbEmnfMTq90CTiiDRg==}
     peerDependencies:
-      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0-rc
+      react: 19.2.6
 
   lucide-react@0.513.0:
     resolution: {integrity: sha512-CJZKq2g8Y8yN4Aq002GahSXbG2JpFv9kXwyiOAMvUBv7pxeOFHUWKB0mO7MiY4ZVFCV4aNjv2BJFq/z3DgKPQg==}
     peerDependencies:
-      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
 
   lucide-react@1.17.0:
     resolution: {integrity: sha512-9FA9evdox/JQL5PT57fdA1x/yg8T7knJ98+zjTL3UfKza6pflQUUh3XtaQIHKvnsJw1lmsEyHVlt5jchYxOQ5w==}
     peerDependencies:
-      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
 
   luxon@3.7.2:
     resolution: {integrity: sha512-vtEhXh/gNjI9Yg1u4jX/0YVPMvxzHuGgCm6tC5kZyb08yjGWGnqAjGJvcXbqQR2P3MyMEFnRbpcdFS6PBcLqew==}
@@ -9579,6 +9570,10 @@ packages:
   make-cancellable-promise@2.0.0:
     resolution: {integrity: sha512-3SEQqTpV9oqVsIWqAcmDuaNeo7yBO3tqPtqGRcKkEo0lrzD3wqbKG9mkxO65KoOgXqj+zH2phJ2LiAsdzlogSw==}
 
+  make-dir@3.1.0:
+    resolution: {integrity: sha512-g3FeP20LNwhALb/6Cz6Dd4F2ngze0jz7tbzrD2wAV+o9FeNHe4rL+yK2md0J/fiSf1sa1ADhXqi5+oVwOM/eGw==}
+    engines: {node: '>=8'}
+
   make-dir@4.0.0:
     resolution: {integrity: sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==}
     engines: {node: '>=10'}
@@ -9602,8 +9597,8 @@ packages:
       '@tabler/icons-react': '>=2.23.0'
       clsx: '>=2'
       dayjs: '>=1.11'
-      react: '>=18.0'
-      react-dom: '>=18.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   map-cache@0.2.2:
     resolution: {integrity: sha512-8y/eV9QQZCiyn1SprXSrCmqJN0yNRATe+PO8ztwqrvrbdRLA3eYJF0yaR0YayLWkMbsQSKWS9N2gPcGEc4UsZg==}
@@ -9864,6 +9859,10 @@ packages:
     resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
     engines: {node: '>=18'}
 
+  mimic-response@2.1.0:
+    resolution: {integrity: sha512-wXqjST+SLt7R009ySCglWBCFpjUygmCIfD790/kVbiGmUgfYGuB14PiTd5DwVxSV4NcYHjzMkoj5LjQZwTQLEA==}
+    engines: {node: '>=8'}
+
   minimatch@10.2.5:
     resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==}
     engines: {node: 18 || 20 || >=22}
@@ -9886,10 +9885,22 @@ packages:
     resolution: {integrity: sha512-xPrLjWkTT5E7H7VnzOjF//xBp9I40jYB4aWhb2xTFopXXfw+Wo82DDWngdUju7Doy3Wk7R8C4LAgwhLHHnf0wA==}
     engines: {node: ^16 || ^18 || >=20}
 
+  minipass@3.3.6:
+    resolution: {integrity: sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==}
+    engines: {node: '>=8'}
+
+  minipass@5.0.0:
+    resolution: {integrity: sha512-3FnjYuehv9k6ovOEbyOswadCDPX1piCfhV8ncmYtHOjuPwylVWsghTLo7rabjC3Rx5xD4HDx8Wm1xnMF7S5qFQ==}
+    engines: {node: '>=8'}
+
   minipass@7.1.3:
     resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==}
     engines: {node: '>=16 || 14 >=14.17'}
 
+  minizlib@2.1.2:
+    resolution: {integrity: sha512-bAxsR8BVfj60DWXHE3u30oHzfl4G7khkSuPW+qvpd7jFRHm7dLxOjUk1EHACJ/hxLY8phGJ0YhYHZo7jil7Qdg==}
+    engines: {node: '>= 8'}
+
   mitt@3.0.1:
     resolution: {integrity: sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==}
 
@@ -9901,6 +9912,11 @@ packages:
     resolution: {integrity: sha512-FP+p8RB8OWpF3YZBCrP5gtADmtXApB5AMLn+vdyA+PyxCjrCs00mjyUozssO33cwDeT3wNGdLxJ5M//YqtHAJw==}
     hasBin: true
 
+  mkdirp@1.0.4:
+    resolution: {integrity: sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==}
+    engines: {node: '>=10'}
+    hasBin: true
+
   moment@2.30.1:
     resolution: {integrity: sha512-uEmtNhbDOrWPFS+hdjFCBfy9f2YoyzRpwcl+DqpC6taX21FzsTLQVbMV/W7PzNSX6x/bhC1zA3c2UQ5NzH6how==}
 
@@ -9938,9 +9954,9 @@ packages:
       '@mui/icons-material': ^5.11.16
       '@mui/material': ^5.13.3
       '@mui/x-date-pickers': ^6.7.0
-      date-fns: ^2.30.0
-      react: ^18.2.0
-      react-dom: ^18.2.0
+      date-fns: ^3.6.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   multer@2.1.1:
     resolution: {integrity: sha512-mo+QTzKlx8R7E5ylSXxWzGoXoZbOsRMpyitcht8By2KHvMbf3tjwosZ/Mu/XYU6UuJ3VZnODIrak5ZrPiPyB6A==}
@@ -9960,6 +9976,9 @@ packages:
   mz@2.7.0:
     resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==}
 
+  nan@2.28.0:
+    resolution: {integrity: sha512-fTsDz99OTq2sVePhGdp4qQhggZFtKr64ZNVyVajRKtMOkJxYekplBh577PiJB12v/D3s2E5cGtOI45LWp6rnLQ==}
+
   nanoid@3.3.12:
     resolution: {integrity: sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
@@ -10001,8 +10020,8 @@ packages:
   next-themes@0.4.6:
     resolution: {integrity: sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==}
     peerDependencies:
-      react: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
 
   next@14.2.35:
     resolution: {integrity: sha512-KhYd2Hjt/O1/1aZVX3dCwGXM1QmOV4eNM2UTacK5gipDdPN/oHHK/4oVGy7X8GMfPMsUTUEmGlsy0EY1YGAkig==}
@@ -10011,8 +10030,8 @@ packages:
     peerDependencies:
       '@opentelemetry/api': ^1.1.0
       '@playwright/test': ^1.41.2
-      react: ^18.2.0
-      react-dom: ^18.2.0
+      react: 19.2.6
+      react-dom: 19.2.6
       sass: ^1.3.0
     peerDependenciesMeta:
       '@opentelemetry/api':
@@ -10050,6 +10069,15 @@ packages:
   node-fetch-native@1.6.7:
     resolution: {integrity: sha512-g9yhqoedzIUm0nTnTqAQvueMPVOuIY16bqgAJJC8XOOubYFNwz6IER9qs0Gq2Xd0+CecCKFjtdDTMA4u4xG06Q==}
 
+  node-fetch@2.7.0:
+    resolution: {integrity: sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==}
+    engines: {node: 4.x || >=6.0.0}
+    peerDependencies:
+      encoding: ^0.1.0
+    peerDependenciesMeta:
+      encoding:
+        optional: true
+
   node-fetch@3.3.2:
     resolution: {integrity: sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
@@ -10072,6 +10100,11 @@ packages:
     resolution: {integrity: sha512-Uzmd6LXpouKo8EUK68IjH4+E01w/hXyV3R3g/geCJo+rXLNfh1xucB+LOzYEOQPSiUK3h/xZf0cQGcSsmyL2Og==}
     engines: {node: '>=18'}
 
+  nopt@5.0.0:
+    resolution: {integrity: sha512-Tbj67rffqceeLpcRXrT7vKAN8CwfPeIBgM7E6iBkmKLV7bEMwpGgYLGv0jACUsECaa/vuxP0IjEont6umdMgtQ==}
+    engines: {node: '>=6'}
+    hasBin: true
+
   normalize-path@3.0.0:
     resolution: {integrity: sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==}
     engines: {node: '>=0.10.0'}
@@ -10091,6 +10124,10 @@ packages:
     resolution: {integrity: sha512-9qny7Z9DsQU8Ou39ERsPU4OZQlSTP47ShQzuKZ6PRXpYLtIFgl/DEBYEXKlvcEa+9tHVcK8CF81Y2V72qaZhWA==}
     engines: {node: '>=18'}
 
+  npmlog@5.0.1:
+    resolution: {integrity: sha512-AqZtDUWOMKs1G/8lwylVjrdYgqA4d9nu8hc+0gzRxlDb1I10+FHBGMXs6aiQHFdCUUlqH99MUMuLfzWDNDtfxw==}
+    deprecated: This package is no longer supported.
+
   nth-check@2.1.1:
     resolution: {integrity: sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==}
 
@@ -10358,6 +10395,10 @@ packages:
     resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==}
     engines: {node: '>=8'}
 
+  path2d-polyfill@2.0.1:
+    resolution: {integrity: sha512-ad/3bsalbbWhmBo0D6FZ4RNMwsLsPpL6gnvhuSaU5Vm7b06Kr5ubSltQQ0T7YKsiJQO+g22zJ4dJKNTXIyOXtA==}
+    engines: {node: '>=8'}
+
   path@0.12.7:
     resolution: {integrity: sha512-aXXC6s+1w7otVF9UletFkFcDsJeO7lSZBPUQhtb5O0xJe8LtYhj/GxldoL09bBj9+ZmE2hNoHqQSFMN5fikh4Q==}
 
@@ -10377,6 +10418,10 @@ packages:
   pdf-lib@1.17.1:
     resolution: {integrity: sha512-V/mpyJAoTsN4cnP31vc0wfNA1+p20evqqnap0KLoRUN0Yk/p3wN52DOEsL4oBFcLdb76hlpKPtzJIgo67j/XLw==}
 
+  pdfjs-dist@3.11.174:
+    resolution: {integrity: sha512-TdTZPf1trZ8/UFu5Cx/GXB7GZM30LT+wWUNfsi6Bq8ePLnb+woNKtDymI2mxZYBpMbonNFqKmiz684DIfnd8dA==}
+    engines: {node: '>=18'}
+
   pdfjs-dist@5.4.296:
     resolution: {integrity: sha512-DlOzet0HO7OEnmUmB6wWGJrrdvbyJKftI1bhMitK7O2N8W2gc757yyYBbINy9IDafXAV9wmKr9t7xsTaNKRG5Q==}
     engines: {node: '>=20.16.0 || >=22.3.0'}
@@ -10676,7 +10721,7 @@ packages:
   qrcode.react@3.2.0:
     resolution: {integrity: sha512-YietHHltOHA4+l5na1srdaMx4sVSOjV9tamHs+mwiLWAMr6QVACRUw1Neax5CptFILcNoITctJY0Ipyn5enQ8g==}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0
+      react: 19.2.6
 
   qrcode@1.5.4:
     resolution: {integrity: sha512-1ca71Zgiu6ORjHqFBDpnSMTR2ReToX4l1Au1VFLyVeBTFavzQnv5JxMFr3ukHVKpSrSA2MCk0lNJSykjUfz7Zg==}
@@ -10716,8 +10761,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -10751,60 +10796,55 @@ packages:
   react-cookie@8.1.2:
     resolution: {integrity: sha512-S45Z1y1dHyYfLEI4bFKQICuP+SwJqTPWbdc2ZpE6aQSdjSVJAjUDfwTPq8B7BWieIsgyyEWMb/QOrudtwJMjXA==}
     peerDependencies:
-      react: '>= 16.3.0'
+      react: 19.2.6
 
   react-css-nocode-editor@1.0.13:
     resolution: {integrity: sha512-RV1ZbG8aXORiQ5mDKZbKCHStCJPamp/n5Rb34q22Ug2xzMDW4DjjqO23+Qo/Y+LAoyyrFV/+lI1qq4+/O5nf2A==}
     peerDependencies:
-      react: '>=16.8.0 <= 18.1'
-      react-dom: '>=16.8.0 <= 18.1'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-day-picker@8.10.2:
     resolution: {integrity: sha512-LK68OTbHB3oJNhl9cA0qVizzp3o26w61YSjAFkYi67N86iro32wx86kSNeFU/hq+gI8m1yzWhnomMLfZ041RzQ==}
     peerDependencies:
-      date-fns: ^2.28.0 || ^3.0.0
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      date-fns: ^3.6.0
+      react: 19.2.6
 
   react-day-picker@9.14.0:
     resolution: {integrity: sha512-tBaoDWjPwe0M5pGrum4H0SR6Lyk+BO9oHnp9JbKpGKW2mlraNPgP9BMfsg5pWpwrssARmeqk7YBl2oXutZTaHA==}
     engines: {node: '>=18'}
     peerDependencies:
-      react: '>=16.8.0'
-
-  react-dom@18.3.1:
-    resolution: {integrity: sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==}
-    peerDependencies:
-      react: ^18.3.1
+      react: 19.2.6
 
   react-dom@19.2.6:
     resolution: {integrity: sha512-0prMI+hvBbPjsWnxDLxlCGyM8PN6UuWjEUCYmZhO67xIV9Xasa/r/vDnq+Xyq4Lo27g8QSbO5YzARu0D1Sps3g==}
     peerDependencies:
-      react: ^19.2.6
+      react: 19.2.6
 
   react-dropzone@14.4.1:
     resolution: {integrity: sha512-QDuV76v3uKbHiH34SpwifZ+gOLi1+RdsCO1kl5vxMT4wW8R82+sthjvBw4th3NHF/XX6FBsqDYZVNN+pnhaw0g==}
     engines: {node: '>= 10.13'}
     peerDependencies:
-      react: '>= 16.8 || 18.0.0'
+      react: 19.2.6
 
   react-hook-form@7.77.0:
     resolution: {integrity: sha512-Sslh9YDYc0GDlWT/lxasnIduNo4v3yyvqRGvmGKUre5AFjDs/HV9/OafHGD8d+sB2yoL4UIL9L8X9i0WlZZebg==}
     engines: {node: '>=18.0.0'}
     peerDependencies:
-      react: ^16.8.0 || ^17 || ^18 || ^19
+      react: 19.2.6
 
   react-hot-toast@2.6.0:
     resolution: {integrity: sha512-bH+2EBMZ4sdyou/DPrfgIouFpcRLCJ+HoCA32UoAYHn6T3Ur5yfcDCeSr5mwldl6pFOsiocmrXMuoCJ1vV8bWg==}
     engines: {node: '>=10'}
     peerDependencies:
-      react: '>=16'
-      react-dom: '>=16'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-i18next@15.7.4:
     resolution: {integrity: sha512-nyU8iKNrI5uDJch0z9+Y5XEr34b0wkyYj3Rp+tfbahxtlswxSCjcUL9H0nqXo9IR3/t5Y5PKIA3fx3MfUyR9Xw==}
     peerDependencies:
       i18next: '>= 23.4.0'
-      react: '>= 16.8.0'
+      react: 19.2.6
       react-dom: '*'
       react-native: '*'
       typescript: ^5
@@ -10820,7 +10860,7 @@ packages:
     resolution: {integrity: sha512-0ooKbGLU8JXhe1zwpQUWIeXSgLPOfwJmgheWRIUpcoA0CpyabpGhayjdG+/eA5esC1AQ8h2jWpXjJfzQzeDOCw==}
     peerDependencies:
       i18next: '>= 26.2.0'
-      react: '>= 16.8.0'
+      react: 19.2.6
       react-dom: '*'
       react-native: '*'
       typescript: ^5 || ^6
@@ -10835,18 +10875,18 @@ packages:
   react-icons@5.6.0:
     resolution: {integrity: sha512-RH93p5ki6LfOiIt0UtDyNg/cee+HLVR6cHHtW3wALfo+eOHTp8RnU2kRkI6E+H19zMIs03DyxUG/GfZMOGvmiA==}
     peerDependencies:
-      react: '*'
+      react: 19.2.6
 
   react-image-crop@11.0.10:
     resolution: {integrity: sha512-+5FfDXUgYLLqBh1Y/uQhIycpHCbXkI50a+nbfkB1C0xXXUTwkisHDo2QCB1SQJyHCqIuia4FeyReqXuMDKWQTQ==}
     peerDependencies:
-      react: '>=16.13.1'
+      react: 19.2.6
 
   react-intersection-observer@9.16.0:
     resolution: {integrity: sha512-w9nJSEp+DrW9KmQmeWHQyfaP6b03v+TdXynaoA964Wxt7mdR3An11z4NNCQgL4gKSK7y1ver2Fq+JKH6CWEzUA==}
     peerDependencies:
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       react-dom:
         optional: true
@@ -10867,27 +10907,27 @@ packages:
     resolution: {integrity: sha512-xaijuJB0kzGiUdG7nc2MOMDUDBWPyGAjZtUrow9XxUeua8IqeP+VlIfAZ3bphpcLTnSZXz6z9jcVC/TCwbfgdw==}
     peerDependencies:
       '@types/react': '>=18'
-      react: '>=18'
+      react: 19.2.6
 
   react-number-format@5.4.5:
     resolution: {integrity: sha512-y8O2yHHj3w0aE9XO8d2BCcUOOdQTRSVq+WIuMlLVucAm5XNjJAy+BoOJiuQMldVYVOKTMyvVNfnbl2Oqp+YxGw==}
     peerDependencies:
-      react: ^0.14 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^0.14 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-pdf-html@2.1.5:
     resolution: {integrity: sha512-KhmiTUcnUNbLVdZbxMcV/+Rp+PyBt+eVJHu425eNwjSsDUtytvcwS/SBdBbbpM0c4+MnnOQBOs3AiColUesM8A==}
     engines: {node: '>=16.0.0'}
     peerDependencies:
       '@react-pdf/renderer': '>=3.4.4'
-      react: '>=16'
+      react: 19.2.6
 
   react-pdf@10.4.1:
     resolution: {integrity: sha512-kS/35staVCBqS29verTQJQZXw7RfsRCPO3fdJoW1KXylcv7A9dw6DZ3vJXC2w+bIBgLw5FN4pOFvKSQtkQhPfA==}
     peerDependencies:
       '@types/react': ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -10895,21 +10935,21 @@ packages:
   react-phone-number-input@3.4.17:
     resolution: {integrity: sha512-1wcjhBAWHgEBAGLi5/XbeZI7Q3aEHNb2z/dHY6R2Gz70TQvu0ZoOT28NTdwtZf4lyRKXWufnTzVhLPBUD8LfmQ==}
     peerDependencies:
-      react: '>=16.8'
-      react-dom: '>=16.8'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-quill-new@3.8.3:
     resolution: {integrity: sha512-c96PYqFTo0pI4R3e79B3rH9LUIce1kIQbmTBu/imJQZk8305ogyLyBqKKjG2UoInDlquXqePSzmBo2aVia3ttw==}
     peerDependencies:
       quill-delta: ^5.1.0
-      react: ^16 || ^17 || ^18 || ^19
-      react-dom: ^16 || ^17 || ^18 || ^19
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-redux@9.3.0:
     resolution: {integrity: sha512-KQopgqFo/p/fgmAs5qz6p5RWaNAzq40WAu7fJIXnQpYxFPbJYtsJPWvGeF2rOBaY/kEuV77AVsX8TsQzKm+A/g==}
     peerDependencies:
       '@types/react': ^18.2.25 || ^19
-      react: ^18.0 || ^19
+      react: 19.2.6
       redux: ^5.0.0
     peerDependenciesMeta:
       '@types/react':
@@ -10926,7 +10966,7 @@ packages:
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -10936,7 +10976,7 @@ packages:
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -10944,35 +10984,35 @@ packages:
   react-resizable-panels@3.0.6:
     resolution: {integrity: sha512-b3qKHQ3MLqOgSS+FRYKapNkJZf5EQzuf6+RLiq1/IlTHw99YrZ2NJZLk4hQIzTnnIkRg2LUqyVinu6YWWpUYew==}
     peerDependencies:
-      react: ^16.14.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
-      react-dom: ^16.14.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-router-dom@6.30.4:
     resolution: {integrity: sha512-q4HvNl+mmDdkS0g+MqiBZNteQJCuimWoOyHMy4T/RQLAn9Z29+E91QXRaxOujeMl2HTzRSS0KFPd7lxX3PjV0Q==}
     engines: {node: '>=14.0.0'}
     peerDependencies:
-      react: '>=16.8'
-      react-dom: '>=16.8'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-router-dom@7.17.0:
     resolution: {integrity: sha512-fyU2yjGups/hE6Xz0I5ZYbVL8Gx29eCjgpHaRaTaVU+OOAdfRX05KsvyRm0GO8YQwOkhpU3MurW1jyMUJn+zSw==}
     engines: {node: '>=20.0.0'}
     peerDependencies:
-      react: '>=18'
-      react-dom: '>=18'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-router@6.30.4:
     resolution: {integrity: sha512-SVUsDe+DybHM/WmYKIVYhZh1o5Dcuf16yM6WjG02Q9XVFMZIJyHYhwrr6bFBXZkVP6z69kNkMyBCujt8FaFLJA==}
     engines: {node: '>=14.0.0'}
     peerDependencies:
-      react: '>=16.8'
+      react: 19.2.6
 
   react-router@7.17.0:
     resolution: {integrity: sha512-FDELK7rTMlCHO5+reyXsPlmfr7N1F91lPHsWYfMEGQm/KQ+F4JFM8jGoeQDmDvdTs93Fw9aSilH+uKRb4/jXvQ==}
     engines: {node: '>=20.0.0'}
     peerDependencies:
-      react: '>=18'
-      react-dom: '>=18'
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       react-dom:
         optional: true
@@ -10983,8 +11023,8 @@ packages:
       '@types/prop-types': ^15.7.3
       '@types/react': 0.14 - 19
       prop-types: ^15.5.8
-      react: 0.14 - 19
-      react-dom: 0.14 - 19
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/prop-types':
         optional: true
@@ -10994,20 +11034,20 @@ packages:
   react-simple-animate@3.5.3:
     resolution: {integrity: sha512-Ob+SmB5J1tXDEZyOe2Hf950K4M8VaWBBmQ3cS2BUnTORqHjhK0iKG8fB+bo47ZL15t8d3g/Y0roiqH05UBjG7A==}
     peerDependencies:
-      react-dom: ^16.8.0 || ^17 || ^18 || ^19
+      react-dom: 19.2.6
 
   react-smooth@4.0.4:
     resolution: {integrity: sha512-gnGKTpYwqL0Iii09gHobNolvX4Kiq4PKx6eWBCYYix+8cdw+cGo3do906l1NBPKkSWx1DghC1dlWG9L2uGd61Q==}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-style-singleton@2.2.3:
     resolution: {integrity: sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==}
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -11016,17 +11056,13 @@ packages:
     resolution: {integrity: sha512-U1DGlIQN5AwgjTyOEnI1oCcMuEr1pv1qOtklB2l4nyMGbHzWrI0eFsYK0zos2YWqAolJyG0IWJaqWmWj5ETh0A==}
     engines: {node: '>=10'}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
 
   react-transition-group@4.4.5:
     resolution: {integrity: sha512-pZcd1MCJoiKiBR2NRxeCRg13uCXbydPnmB4EOeRrY7480qNWO8IIgQG6zlDkm6uRMsURXPuKq0GWtiM59a5Q6g==}
     peerDependencies:
-      react: '>=16.6.0'
-      react-dom: '>=16.6.0'
-
-  react@18.3.1:
-    resolution: {integrity: sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==}
-    engines: {node: '>=0.10.0'}
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react@19.2.6:
     resolution: {integrity: sha512-sfWGGfavi0xr8Pg0sVsyHMAOziVYKgPLNrS7ig+ivMNb3wbCBw3KxtflsGBAwD3gYQlE/AEZsTLgToRrSCjb0Q==}
@@ -11076,15 +11112,15 @@ packages:
     engines: {node: '>=14'}
     deprecated: 1.x and 2.x branches are no longer active. Bump to Recharts v3 to receive latest features and bugfixes. See https://github.com/recharts/recharts/wiki/3.0-migration-guide
     peerDependencies:
-      react: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   recharts@3.8.1:
     resolution: {integrity: sha512-mwzmO1s9sFL0TduUpwndxCUNoXsBw3u3E/0+A+cLcrSfQitSG62L32N69GhqUrrT5qKcAE3pCGVINC6pqkBBQg==}
     engines: {node: '>=18'}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
       react-is: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   redux-thunk@3.1.0:
@@ -11334,9 +11370,6 @@ packages:
     resolution: {integrity: sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==}
     engines: {node: '>=v12.22.7'}
 
-  scheduler@0.23.2:
-    resolution: {integrity: sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==}
-
   scheduler@0.25.0-rc-603e6108-20241029:
     resolution: {integrity: sha512-pFwF6H1XrSdYYNLfOcGlM28/j8CGLu8IvdrxqhjWULe2bPcKiKW4CV+OWqR/9fT52mywx65l7ysNkjLKBda7eA==}
 
@@ -11464,6 +11497,12 @@ packages:
   signature_pad@2.3.2:
     resolution: {integrity: sha512-peYXLxOsIY6MES2TrRLDiNg2T++8gGbpP2yaC+6Ohtxr+a2dzoaqWosWDY9sWqTAAk6E/TyQO+LJw9zQwyu5kA==}
 
+  simple-concat@1.0.1:
+    resolution: {integrity: sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q==}
+
+  simple-get@3.1.1:
+    resolution: {integrity: sha512-CQ5LTKGfCpvE1K0n2us+kuMPbk/q0EKl82s4aheV9oXjFEz6W/Y7oQFVJuU6QG77hRT4Ghb5RURteF5vnWjupA==}
+
   sisteransi@1.0.5:
     resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
 
@@ -11529,8 +11568,8 @@ packages:
   sonner@2.0.7:
     resolution: {integrity: sha512-W6ZN4p58k8aDKA4XPcx2hpIQXBRAgyiWVkYhT7CvK6D3iAu7xjvVyhQHg2/iaKJZ1XVJ4r7XuwGL+WGEK37i9w==}
     peerDependencies:
-      react: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
-      react-dom: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
 
   source-map-js@1.2.1:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
@@ -11777,8 +11816,8 @@ packages:
     resolution: {integrity: sha512-uuzIIfnVkagcVHv9nE0VPlHPSCmXIUGKfJ42LNjxCCTDTL5sgnJ8Z7GZBq0EnLYGln77tPpEpExt2+qa+cZqSw==}
     engines: {node: '>=10'}
     peerDependencies:
-      react: '>= 16.8.0'
-      react-dom: '>= 16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
       react-is: '>= 16.8.0'
 
   styled-jsx@5.1.1:
@@ -11787,7 +11826,7 @@ packages:
     peerDependencies:
       '@babel/core': '*'
       babel-plugin-macros: '*'
-      react: '>= 16.8.0 || 17.x.x || ^18.0.0-0'
+      react: 19.2.6
     peerDependenciesMeta:
       '@babel/core':
         optional: true
@@ -11908,6 +11947,11 @@ packages:
   tar-stream@3.2.0:
     resolution: {integrity: sha512-ojzvCvVaNp6aOTFmG7jaRD0meowIAuPc3cMMhSgKiVWws1GyHbGd/xvnyuRKcKlMpt3qvxx6r0hreCNITP9hIg==}
 
+  tar@6.2.1:
+    resolution: {integrity: sha512-DZ4yORTwrbTj/7MZYq2w+/ZFdI6OZ/f9SFHR+71gIVUZhOQPHzVCLpvRnPgyaMpfWxxk/4ONva3GQSyNIKRv6A==}
+    engines: {node: '>=10'}
+    deprecated: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
+
   teex@1.0.1:
     resolution: {integrity: sha512-eYE6iEI62Ni1H8oIa7KlDU6uQBtqr4Eajni3wX7rpfXD8ysFx8z0+dri+KWEPWpBsxXfxu58x/0jvTVT1ekOSg==}
 
@@ -12105,6 +12149,9 @@ packages:
     resolution: {integrity: sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw==}
     engines: {node: '>=16'}
 
+  tr46@0.0.3:
+    resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==}
+
   tr46@5.1.1:
     resolution: {integrity: sha512-hdF5ZgjTqgAntKkklYw0R03MG2x/bSzTtkxmIRw/sTNV8YXsCJ1tfLAX23lhxhHJlEf3CRCOCGGWw3vI3GaSPw==}
     engines: {node: '>=18'}
@@ -12287,7 +12334,7 @@ packages:
     hasBin: true
     peerDependencies:
       '@faker-js/faker': '>=8.4.1'
-      typeorm: ~0.3.0
+      typeorm: 0.3.30
 
   typeorm@0.3.30:
     resolution: {integrity: sha512-8T35PzjefOdqc2ZR9mwLQj0pUGp6lQhMbK2EvVMwJVJWlaoHm0v/Q6dThNOZkFchD+0yMg8gwjKM28ePiLSXSQ==}
@@ -12467,7 +12514,7 @@ packages:
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12476,7 +12523,7 @@ packages:
     resolution: {integrity: sha512-djviaxuOOh7wkj0paeO1Q/4wMZ8Zrnag5H6yBvzN7AKKe8beOaED9SF5/ByLqsku8NP4zQqsvM2u3ew/tJK8/w==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12485,13 +12532,13 @@ packages:
     resolution: {integrity: sha512-kbeNVZ9Zkc0RFGpfMN3MNfaKNvcLNyxOAAd9O4CBZ+kCBXXscn9s/4I+8ytUER4RDpEYs5+O6Rs4PqiZ+rHr5Q==}
     engines: {node: '>=10', npm: '>=6'}
     peerDependencies:
-      react: '>=16.13'
+      react: 19.2.6
 
   use-isomorphic-layout-effect@1.2.1:
     resolution: {integrity: sha512-tpZZ+EX0gaghDAiFR37hj5MgY6ZN55kLiPkJsKxBMZ6GZdOSPJXiOzPM984oPYZ5AnehYx5WQp1+ME8I/P/pRA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12500,7 +12547,7 @@ packages:
     resolution: {integrity: sha512-mhg3xdm9NaM8q+gLT8KryJPnRFOz1/5XPBhmDEVZK1webPzDjrPk7f/mbpeLqTgB9msytYWANxgALOCJKnLvcQ==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12510,7 +12557,7 @@ packages:
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12518,7 +12565,7 @@ packages:
   use-sync-external-store@1.6.0:
     resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
 
   use@3.1.1:
     resolution: {integrity: sha512-cwESVXlO3url9YWlFW/TA9cshCEhtu7IKJ/p5soJ/gGpj7vbvFrAY/eIioQ6Dw23KjZhYgiIo8HOs1nQ2vr/oQ==}
@@ -12581,8 +12628,8 @@ packages:
   vaul@1.1.2:
     resolution: {integrity: sha512-ZFkClGpWyI2WUQjdLJ/BaGuV6AVQiJ3uELGk3OYtP+B6yCO7Cmn9vPFXVJkRaGkOJu3m8bQMgtyzNHixULceQA==}
     peerDependencies:
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
 
   verror@1.10.0:
     resolution: {integrity: sha512-ZZKSmDAEFOijERBLkmYfJ+vmk3w+7hOLYDNkRCuRuMJGEmqYNCNLyBBFwWKVMhfwaEF3WOd0Zlw86U/WC/+nYw==}
@@ -12710,6 +12757,9 @@ packages:
   webdriver-bidi-protocol@0.4.1:
     resolution: {integrity: sha512-ARrjNjtWRRs2w4Tk7nqrf2gBI0QXWuOmMCx2hU+1jUt6d00MjMxURrhxhGbrsoiZKJrhTSTzbIrc554iKI10qw==}
 
+  webidl-conversions@3.0.1:
+    resolution: {integrity: sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==}
+
   webidl-conversions@7.0.0:
     resolution: {integrity: sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==}
     engines: {node: '>=12'}
@@ -12745,6 +12795,9 @@ packages:
     resolution: {integrity: sha512-De72GdQZzNTUBBChsXueQUnPKDkg/5A5zp7pFDuQAj5UFoENpiACU0wlCvzpAGnTkj++ihpKwKyYewn/XNUbKw==}
     engines: {node: '>=18'}
 
+  whatwg-url@5.0.0:
+    resolution: {integrity: sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==}
+
   which-boxed-primitive@1.1.1:
     resolution: {integrity: sha512-TbX3mj8n0odCBFVlY8AxkqcHASw3L60jIuF8jFP78az3C2YhmGvqbHBpAjTRH2/xqYunrJ9g1jSyjCjpoWzIAA==}
     engines: {node: '>= 0.4'}
@@ -12779,6 +12832,9 @@ packages:
     engines: {node: '>=8'}
     hasBin: true
 
+  wide-align@1.1.5:
+    resolution: {integrity: sha512-eDMORYaPNZ4sQIuuYPDHdQvf4gyCF9rEEV/yPxGfwPkRodwEgiMUUXTx/dex+Me0wxx53S+NgUHaP7y3MGlDmg==}
+
   wmf@1.0.2:
     resolution: {integrity: sha512-/p9K7bEh0Dj6WbXg4JG0xvLQmIadrner1bi45VMJTfnbVHsc7yIajZyoSoK60/dtVBs12Fm6WkUI5/3WAVsNMw==}
     engines: {node: '>=0.8'}
@@ -12890,6 +12946,9 @@ packages:
   yallist@3.1.1:
     resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
 
+  yallist@4.0.0:
+    resolution: {integrity: sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==}
+
   yaml@1.10.3:
     resolution: {integrity: sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==}
     engines: {node: '>= 6'}
@@ -12986,7 +13045,7 @@ packages:
     peerDependencies:
       '@types/react': '>=18.0.0'
       immer: '>=9.0.6'
-      react: '>=18.0.0'
+      react: 19.2.6
       use-sync-external-store: '>=1.2.0'
     peerDependenciesMeta:
       '@types/react':
@@ -14014,12 +14073,6 @@ snapshots:
       '@floating-ui/core': 1.7.5
       '@floating-ui/utils': 0.2.11
 
-  '@floating-ui/react-dom@2.1.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@floating-ui/dom': 1.7.6
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-
   '@floating-ui/react-dom@2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/dom': 1.7.6
@@ -14034,14 +14087,6 @@ snapshots:
       react-dom: 19.2.6(react@19.2.6)
       tabbable: 6.4.0
 
-  '@floating-ui/react@0.27.19(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@floating-ui/react-dom': 2.1.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@floating-ui/utils': 0.2.11
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      tabbable: 6.4.0
-
   '@floating-ui/react@0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/react-dom': 2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -14105,9 +14150,9 @@ snapshots:
       - '@types/react'
       - supports-color
 
-  '@hookform/resolvers@3.10.0(react-hook-form@7.77.0(react@18.3.1))':
+  '@hookform/resolvers@3.10.0(react-hook-form@7.77.0(react@19.2.6))':
     dependencies:
-      react-hook-form: 7.77.0(react@18.3.1)
+      react-hook-form: 7.77.0(react@19.2.6)
 
   '@hookform/resolvers@5.4.0(react-hook-form@7.77.0(react@19.2.6))':
     dependencies:
@@ -14895,19 +14940,6 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
-  '@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@floating-ui/react': 0.27.19(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@mantine/hooks': 9.3.0(react@18.3.1)
-      clsx: 2.1.1
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      react-number-format: 5.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
-      type-fest: 5.7.0
-    transitivePeerDependencies:
-      - '@types/react'
-
   '@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/react': 0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -14921,6 +14953,19 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
+  '@mantine/core@9.3.0(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@floating-ui/react': 0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@mantine/hooks': 9.3.2(react@19.2.6)
+      clsx: 2.1.1
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-number-format: 5.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@19.2.6)
+      type-fest: 5.7.0
+    transitivePeerDependencies:
+      - '@types/react'
+
   '@mantine/core@9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/react': 0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -14965,10 +15010,6 @@ snapshots:
     dependencies:
       react: 19.2.6
 
-  '@mantine/hooks@9.3.0(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-
   '@mantine/hooks@9.3.0(react@19.2.6)':
     dependencies:
       react: 19.2.6
@@ -14990,6 +15031,22 @@ snapshots:
     dependencies:
       react: 19.2.6
 
+  '@mapbox/node-pre-gyp@1.0.11':
+    dependencies:
+      detect-libc: 2.1.2
+      https-proxy-agent: 5.0.1
+      make-dir: 3.1.0
+      node-fetch: 2.7.0
+      nopt: 5.0.0
+      npmlog: 5.0.1
+      rimraf: 3.0.2
+      semver: 7.8.2
+      tar: 6.2.1
+    transitivePeerDependencies:
+      - encoding
+      - supports-color
+    optional: true
+
   '@marijn/find-cluster-break@1.0.3': {}
 
   '@mdxeditor/editor@4.2.0(@codemirror/language@6.12.4)(@lezer/highlight@1.2.3)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.9.3)(yjs@13.6.32)':
@@ -15749,15 +15806,6 @@ snapshots:
 
   '@radix-ui/primitive@1.1.4': {}
 
-  '@radix-ui/react-accessible-icon@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-accessible-icon@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -15767,23 +15815,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-accordion@1.2.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collapsible': 1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-accordion@1.2.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15801,20 +15832,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-alert-dialog@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-alert-dialog@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15829,15 +15846,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-arrow@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-arrow@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -15847,15 +15855,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-aspect-ratio@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-aspect-ratio@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -15865,19 +15864,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-avatar@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-avatar@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@19.2.6)
@@ -15891,22 +15877,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-checkbox@1.3.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-checkbox@1.3.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15923,22 +15893,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-collapsible@1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-collapsible@1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15955,18 +15909,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-collection@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-collection@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@19.2.6)
@@ -15979,31 +15921,12 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-compose-refs@1.1.3(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-compose-refs@1.1.3(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-context-menu@2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-context-menu@2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16017,40 +15940,12 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-context@1.1.4(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-context@1.1.4(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-dialog@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      aria-hidden: 1.2.6
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-dialog@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16073,31 +15968,12 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-direction@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-direction@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-dismissable-layer@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-escape-keydown': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-dismissable-layer@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16111,21 +15987,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-dropdown-menu@2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-dropdown-menu@2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16141,29 +16002,12 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-focus-guards@1.1.4(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-focus-guards@1.1.4(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-focus-scope@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-focus-scope@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@19.2.6)
@@ -16175,20 +16019,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-form@0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-label': 2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-form@0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16203,23 +16033,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-hover-card@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-hover-card@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16241,13 +16054,6 @@ snapshots:
     dependencies:
       react: 19.2.6
 
-  '@radix-ui/react-id@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-id@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -16255,15 +16061,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-label@2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-label@2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -16273,32 +16070,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-menu@2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      aria-hidden: 1.2.6
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-menu@2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16325,24 +16096,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-menubar@1.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-menubar@1.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16361,28 +16114,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-navigation-menu@1.2.15(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-navigation-menu@1.2.15(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16405,26 +16136,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-one-time-password-field@0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/number': 1.1.2
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-one-time-password-field@0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/number': 1.1.2
@@ -16445,22 +16156,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-password-toggle-field@0.1.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-password-toggle-field@0.1.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16477,29 +16172,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-popover@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      aria-hidden: 1.2.6
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-popover@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16523,24 +16195,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-popper@1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@floating-ui/react-dom': 2.1.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-arrow': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-rect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/rect': 1.1.2
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-popper@1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/react-dom': 2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -16559,16 +16213,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-portal@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-portal@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -16579,15 +16223,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-presence@1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-presence@1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -16597,15 +16232,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-primitive@2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-primitive@2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@19.2.6)
@@ -16615,16 +16241,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-progress@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-progress@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@19.2.6)
@@ -16635,24 +16251,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-radio-group@1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-radio-group@1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16671,23 +16269,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-roving-focus@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-roving-focus@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16705,23 +16286,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-scroll-area@1.2.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/number': 1.1.2
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-scroll-area@1.2.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/number': 1.1.2
@@ -16739,36 +16303,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-select@2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/number': 1.1.2
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      aria-hidden: 1.2.6
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-select@2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/number': 1.1.2
@@ -16799,15 +16333,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-separator@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-separator@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -16817,25 +16342,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-slider@1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/number': 1.1.2
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-slider@1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/number': 1.1.2
@@ -16855,13 +16361,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-slot@1.2.5(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-slot@1.2.5(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@19.2.6)
@@ -16869,21 +16368,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-switch@1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-switch@1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16899,22 +16383,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-tabs@1.1.14(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-tabs@1.1.14(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16931,26 +16399,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-toast@1.2.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-toast@1.2.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16971,21 +16419,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-toggle-group@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-toggle': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-toggle-group@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -17001,17 +16434,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-toggle@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-toggle@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -17023,21 +16445,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-toolbar@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-separator': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-toggle-group': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-toolbar@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -17053,26 +16460,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-tooltip@1.2.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-tooltip@1.2.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -17093,26 +16480,12 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-use-callback-ref@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-callback-ref@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-controllable-state@1.2.3(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-controllable-state@1.2.3(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@19.2.6)
@@ -17121,13 +16494,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-effect-event@0.0.3(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-effect-event@0.0.3(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -17135,13 +16501,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-escape-keydown@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-escape-keydown@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -17149,49 +16508,24 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-is-hydrated@0.1.1(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-is-hydrated@0.1.1(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-layout-effect@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-layout-effect@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-previous@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-previous@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-rect@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/rect': 1.1.2
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-rect@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/rect': 1.1.2
@@ -17199,13 +16533,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-size@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-size@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -17213,15 +16540,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-visually-hidden@1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-visually-hidden@1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -17746,11 +17064,6 @@ snapshots:
       '@tanstack/react-query': 5.101.0(react@19.2.6)
       react: 19.2.6
 
-  '@tanstack/react-query@5.101.0(react@18.3.1)':
-    dependencies:
-      '@tanstack/query-core': 5.101.0
-      react: 18.3.1
-
   '@tanstack/react-query@5.101.0(react@19.2.6)':
     dependencies:
       '@tanstack/query-core': 5.101.0
@@ -17762,12 +17075,6 @@ snapshots:
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
 
-  '@tanstack/react-table@8.21.3(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@tanstack/table-core': 8.21.3
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-
   '@tanstack/react-table@8.21.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@tanstack/table-core': 8.21.3
@@ -17813,50 +17120,7 @@ snapshots:
 
   '@tootallnate/quickjs-emscripten@0.23.0': {}
 
-  '@tria-plc/api-common@file:local-packages/tria-plc-api-common-1.6.0.tgz(2b4e99ab22f78c34e7861d649f4ff29b)':
-    dependencies:
-      '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)
-      '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/core': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/microservices@11.1.24)(@nestjs/platform-express@11.1.24)(@nestjs/websockets@11.1.27)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/jwt': 11.0.2(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))
-      '@nestjs/microservices': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/websockets@11.1.27)(amqp-connection-manager@5.0.0(amqplib@2.0.1))(amqplib@2.0.1)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/passport': 10.0.3(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(passport@0.7.0)
-      '@nestjs/swagger': 7.4.2(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)
-      '@nestjs/throttler': 6.5.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)
-      '@nestjs/typeorm': 11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
-      argon2: 0.43.1
-      axios: 1.17.0
-      change-case: 5.4.4
-      class-transformer: 0.5.1
-      class-validator: 0.14.4
-      dotenv: 16.6.1
-      ethiopian-calendar-date-converter: 2.1.6
-      ethiopian-date: 0.0.6
-      exceljs: 4.4.0
-      file-type: 21.3.4
-      handlebars: 4.7.9
-      handlebars-helpers: 0.10.0
-      jmespath: 0.16.0
-      jose: 5.10.0
-      jsonwebtoken: 9.0.3
-      libphonenumber-js: 1.13.6
-      libreoffice-convert: 1.8.1
-      nestjs-minio-client: 2.2.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)
-      passport-jwt: 4.0.1
-      qrcode: 1.5.4
-      reflect-metadata: 0.2.2
-      rxjs: 7.8.2
-      style-object-to-css-string: 1.1.3
-      typeorm: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
-      typeorm-extension: 3.9.0(@faker-js/faker@10.4.0)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
-      uuid: 11.1.1
-      xlsx: 0.18.5
-    transitivePeerDependencies:
-      - '@faker-js/faker'
-      - debug
-      - supports-color
-
-  '@tria-plc/api-common@file:local-packages/tria-plc-api-common-1.6.0.tgz(ae9a56cc1c6d93629dd85f7605ccd5b6)':
+  '@tria-plc/api-common@file:local-packages/tria-plc-api-common-1.6.0.tgz(2te6mb6vb2upxetsvhkgi54vi4)':
     dependencies:
       '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)
       '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
@@ -17899,19 +17163,7 @@ snapshots:
       - debug
       - supports-color
 
-  '@tria-plc/auditlog@file:local-packages/tria-plc-auditlog-1.1.2.tgz(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/microservices@11.1.24)(@nestjs/swagger@11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2))(@nestjs/typeorm@11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))))(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))':
-    dependencies:
-      '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/core': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/microservices@11.1.24)(@nestjs/platform-express@11.1.24)(@nestjs/websockets@11.1.27)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/microservices': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/websockets@11.1.27)(amqp-connection-manager@5.0.0(amqplib@2.0.1))(amqplib@2.0.1)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/swagger': 11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)
-      '@nestjs/typeorm': 11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
-      amqp-connection-manager: 5.0.0(amqplib@0.10.9)
-      amqplib: 0.10.9
-      rxjs: 7.8.2
-      typeorm: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
-
-  '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(cc085a020c559b355f168432c579a024)':
+  '@tria-plc/api-common@file:local-packages/tria-plc-api-common-1.6.0.tgz(66zjxtt2zhydyq6w3arhrktl4y)':
     dependencies:
       '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)
       '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
@@ -17922,7 +17174,50 @@ snapshots:
       '@nestjs/swagger': 7.4.2(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)
       '@nestjs/throttler': 6.5.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)
       '@nestjs/typeorm': 11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
-      '@tria-plc/api-common': file:local-packages/tria-plc-api-common-1.6.0.tgz(2b4e99ab22f78c34e7861d649f4ff29b)
+      argon2: 0.43.1
+      axios: 1.17.0
+      change-case: 5.4.4
+      class-transformer: 0.5.1
+      class-validator: 0.14.4
+      dotenv: 16.6.1
+      ethiopian-calendar-date-converter: 2.1.6
+      ethiopian-date: 0.0.6
+      exceljs: 4.4.0
+      file-type: 21.3.4
+      handlebars: 4.7.9
+      handlebars-helpers: 0.10.0
+      jmespath: 0.16.0
+      jose: 5.10.0
+      jsonwebtoken: 9.0.3
+      libphonenumber-js: 1.13.6
+      libreoffice-convert: 1.8.1
+      nestjs-minio-client: 2.2.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)
+      passport-jwt: 4.0.1
+      qrcode: 1.5.4
+      reflect-metadata: 0.2.2
+      rxjs: 7.8.2
+      style-object-to-css-string: 1.1.3
+      typeorm: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
+      typeorm-extension: 3.9.0(@faker-js/faker@10.4.0)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
+      uuid: 11.1.1
+      xlsx: 0.18.5
+    transitivePeerDependencies:
+      - '@faker-js/faker'
+      - debug
+      - supports-color
+
+  '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(2duxgcsfjn5usnyutzzh6i5xr4)':
+    dependencies:
+      '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)
+      '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/core': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/microservices@11.1.24)(@nestjs/platform-express@11.1.24)(@nestjs/websockets@11.1.27)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/jwt': 11.0.2(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))
+      '@nestjs/microservices': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/websockets@11.1.27)(amqp-connection-manager@5.0.0(amqplib@2.0.1))(amqplib@2.0.1)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/passport': 10.0.3(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(passport@0.7.0)
+      '@nestjs/swagger': 7.4.2(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)
+      '@nestjs/throttler': 6.5.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)
+      '@nestjs/typeorm': 11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
+      '@tria-plc/api-common': file:local-packages/tria-plc-api-common-1.6.0.tgz(66zjxtt2zhydyq6w3arhrktl4y)
       argon2: 0.43.1
       axios: 1.17.0
       class-transformer: 0.5.1
@@ -17945,7 +17240,7 @@ snapshots:
       - '@faker-js/faker'
       - supports-color
 
-  '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(d0be280d95adfc1b38e59bdc80c5dec5)':
+  '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(776yg74vcz655pvzf2fzttkf2q)':
     dependencies:
       '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)
       '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
@@ -17956,7 +17251,7 @@ snapshots:
       '@nestjs/swagger': 11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)
       '@nestjs/throttler': 6.5.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)
       '@nestjs/typeorm': 11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
-      '@tria-plc/api-common': file:local-packages/tria-plc-api-common-1.6.0.tgz(ae9a56cc1c6d93629dd85f7605ccd5b6)
+      '@tria-plc/api-common': file:local-packages/tria-plc-api-common-1.6.0.tgz(2te6mb6vb2upxetsvhkgi54vi4)
       argon2: 0.43.1
       axios: 1.17.0
       class-transformer: 0.5.1
@@ -17979,7 +17274,7 @@ snapshots:
       - '@faker-js/faker'
       - supports-color
 
-  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)':
+  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(elggzzmuouas3d7ccap2lbvoyu)':
     dependencies:
       '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
       '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
@@ -18045,7 +17340,7 @@ snapshots:
       lodash: 4.18.1
       lucide-react: 0.513.0(react@19.2.6)
       mantine-react-table: 2.0.0-beta.9(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/dates@7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(@tabler/icons-react@3.44.0(react@19.2.6))(clsx@2.1.1)(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      mui-ethiopian-datepicker: 0.3.2(4b3af212eafdf0059f009b005d7e343d)
+      mui-ethiopian-datepicker: 0.3.2(ruap3lc7my4alz6jx6pekjrhou)
       next-themes: 0.4.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       path: 0.12.7
       pdf-lib: 1.17.1
@@ -18091,6 +17386,7 @@ snapshots:
       - '@types/react-dom'
       - bufferutil
       - debug
+      - encoding
       - pdfjs-dist
       - prop-types
       - react-is
@@ -18103,7 +17399,7 @@ snapshots:
       - utf-8-validate
       - vite
 
-  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)':
+  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(vhj5jsbx2ogblwtd5crolhrpku)':
     dependencies:
       '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
       '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
@@ -18169,7 +17465,7 @@ snapshots:
       lodash: 4.18.1
       lucide-react: 0.513.0(react@19.2.6)
       mantine-react-table: 2.0.0-beta.9(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/dates@7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(@tabler/icons-react@3.44.0(react@19.2.6))(clsx@2.1.1)(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      mui-ethiopian-datepicker: 0.3.2(4b3af212eafdf0059f009b005d7e343d)
+      mui-ethiopian-datepicker: 0.3.2(ruap3lc7my4alz6jx6pekjrhou)
       next-themes: 0.4.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       path: 0.12.7
       pdf-lib: 1.17.1
@@ -18215,6 +17511,7 @@ snapshots:
       - '@types/react-dom'
       - bufferutil
       - debug
+      - encoding
       - pdfjs-dist
       - prop-types
       - react-is
@@ -18923,6 +18220,9 @@ snapshots:
       jsonparse: 1.3.1
       through: 2.3.8
 
+  abbrev@1.1.1:
+    optional: true
+
   abort-controller@3.0.0:
     dependencies:
       event-target-shim: 5.0.1
@@ -19010,11 +18310,6 @@ snapshots:
       amqplib: 0.10.9
       promise-breaker: 6.0.0
 
-  amqp-connection-manager@5.0.0(amqplib@0.10.9):
-    dependencies:
-      amqplib: 0.10.9
-      promise-breaker: 6.0.0
-
   amqp-connection-manager@5.0.0(amqplib@2.0.1):
     dependencies:
       amqplib: 2.0.1
@@ -19206,6 +18501,9 @@ snapshots:
 
   append-field@1.0.0: {}
 
+  aproba@2.1.0:
+    optional: true
+
   arch@2.2.0: {}
 
   archiver-utils@2.1.0:
@@ -19244,6 +18542,12 @@ snapshots:
       tar-stream: 2.2.0
       zip-stream: 4.1.1
 
+  are-we-there-yet@2.0.0:
+    dependencies:
+      delegates: 1.0.0
+      readable-stream: 3.6.2
+    optional: true
+
   arg@4.1.3: {}
 
   arg@5.0.2: {}
@@ -19798,6 +19102,16 @@ snapshots:
 
   caniuse-lite@1.0.30001797: {}
 
+  canvas@2.11.2:
+    dependencies:
+      '@mapbox/node-pre-gyp': 1.0.11
+      nan: 2.28.0
+      simple-get: 3.1.1
+    transitivePeerDependencies:
+      - encoding
+      - supports-color
+    optional: true
+
   canvg@3.0.11:
     dependencies:
       '@babel/runtime': 7.29.7
@@ -19878,6 +19192,9 @@ snapshots:
     dependencies:
       readdirp: 4.1.2
 
+  chownr@2.0.0:
+    optional: true
+
   chrome-trace-event@1.0.4: {}
 
   chromium-bidi@14.0.0(devtools-protocol@0.0.1608973):
@@ -20041,6 +19358,9 @@ snapshots:
     dependencies:
       color-name: 2.1.0
 
+  color-support@1.1.3:
+    optional: true
+
   colorette@2.0.20: {}
 
   colors@1.4.0:
@@ -20104,6 +19424,9 @@ snapshots:
 
   consola@3.4.2: {}
 
+  console-control-strings@1.1.0:
+    optional: true
+
   content-disposition@0.5.4:
     dependencies:
       safe-buffer: 5.2.1
@@ -20401,8 +19724,6 @@ snapshots:
 
   date-fns@3.6.0: {}
 
-  date-fns@4.4.0: {}
-
   date.js@0.3.3:
     dependencies:
       debug: 3.1.0
@@ -20449,6 +19770,11 @@ snapshots:
 
   decode-uri-component@0.2.2: {}
 
+  decompress-response@4.2.1:
+    dependencies:
+      mimic-response: 2.1.0
+    optional: true
+
   dedent@1.7.2(babel-plugin-macros@3.1.0):
     optionalDependencies:
       babel-plugin-macros: 3.1.0
@@ -20515,6 +19841,9 @@ snapshots:
 
   delayed-stream@1.0.0: {}
 
+  delegates@1.0.0:
+    optional: true
+
   depd@2.0.0: {}
 
   dequal@2.0.3: {}
@@ -21661,6 +20990,11 @@ snapshots:
       jsonfile: 6.2.1
       universalify: 2.0.1
 
+  fs-minipass@2.1.0:
+    dependencies:
+      minipass: 3.3.6
+    optional: true
+
   fs-monkey@1.1.0: {}
 
   fs.realpath@1.0.0: {}
@@ -21693,6 +21027,19 @@ snapshots:
 
   fuzzysort@3.1.0: {}
 
+  gauge@3.0.2:
+    dependencies:
+      aproba: 2.1.0
+      color-support: 1.1.3
+      console-control-strings: 1.1.0
+      has-unicode: 2.0.1
+      object-assign: 4.1.1
+      signal-exit: 3.0.7
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+      wide-align: 1.1.5
+    optional: true
+
   generator-function@2.0.1: {}
 
   gensync@1.0.0-beta.2: {}
@@ -21935,6 +21282,9 @@ snapshots:
     dependencies:
       has-symbols: 1.1.0
 
+  has-unicode@2.0.1:
+    optional: true
+
   has-value@0.3.1:
     dependencies:
       get-value: 2.0.6
@@ -22925,7 +22275,7 @@ snapshots:
 
   jsbn@0.1.1: {}
 
-  jsdom@25.0.1:
+  jsdom@25.0.1(canvas@2.11.2):
     dependencies:
       cssstyle: 4.6.0
       data-urls: 5.0.0
@@ -22948,6 +22298,8 @@ snapshots:
       whatwg-url: 14.2.0
       ws: 8.21.0
       xml-name-validator: 5.0.0
+    optionalDependencies:
+      canvas: 2.11.2
     transitivePeerDependencies:
       - bufferutil
       - supports-color
@@ -23384,18 +22736,14 @@ snapshots:
 
   lru-cache@7.18.3: {}
 
-  lucide-react@0.446.0(react@18.3.1):
+  lucide-react@0.446.0(react@19.2.6):
     dependencies:
-      react: 18.3.1
+      react: 19.2.6
 
   lucide-react@0.513.0(react@19.2.6):
     dependencies:
       react: 19.2.6
 
-  lucide-react@1.17.0(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-
   lucide-react@1.17.0(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -23412,6 +22760,11 @@ snapshots:
 
   make-cancellable-promise@2.0.0: {}
 
+  make-dir@3.1.0:
+    dependencies:
+      semver: 6.3.1
+    optional: true
+
   make-dir@4.0.0:
     dependencies:
       semver: 7.8.2
@@ -23935,6 +23288,9 @@ snapshots:
 
   mimic-function@5.0.1: {}
 
+  mimic-response@2.1.0:
+    optional: true
+
   minimatch@10.2.5:
     dependencies:
       brace-expansion: 5.0.6
@@ -23970,8 +23326,22 @@ snapshots:
       xml: 1.0.1
       xml2js: 0.5.0
 
+  minipass@3.3.6:
+    dependencies:
+      yallist: 4.0.0
+    optional: true
+
+  minipass@5.0.0:
+    optional: true
+
   minipass@7.1.3: {}
 
+  minizlib@2.1.2:
+    dependencies:
+      minipass: 3.3.6
+      yallist: 4.0.0
+    optional: true
+
   mitt@3.0.1: {}
 
   mixin-deep@1.3.2:
@@ -23983,6 +23353,9 @@ snapshots:
     dependencies:
       minimist: 1.2.8
 
+  mkdirp@1.0.4:
+    optional: true
+
   moment@2.30.1: {}
 
   motion-dom@12.40.0:
@@ -24048,7 +23421,7 @@ snapshots:
     transitivePeerDependencies:
       - '@types/node'
 
-  mui-ethiopian-datepicker@0.3.2(4b3af212eafdf0059f009b005d7e343d):
+  mui-ethiopian-datepicker@0.3.2(ruap3lc7my4alz6jx6pekjrhou):
     dependencies:
       '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
       '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
@@ -24078,6 +23451,9 @@ snapshots:
       object-assign: 4.1.1
       thenify-all: 1.6.0
 
+  nan@2.28.0:
+    optional: true
+
   nanoid@3.3.12: {}
 
   nanomatch@1.2.13:
@@ -24121,7 +23497,7 @@ snapshots:
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
 
-  next@14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+  next@14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       '@next/env': 14.2.35
       '@swc/helpers': 0.5.5
@@ -24129,9 +23505,9 @@ snapshots:
       caniuse-lite: 1.0.30001797
       graceful-fs: 4.2.11
       postcss: 8.4.31
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      styled-jsx: 5.1.1(babel-plugin-macros@3.1.0)(react@18.3.1)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      styled-jsx: 5.1.1(babel-plugin-macros@3.1.0)(react@19.2.6)
     optionalDependencies:
       '@next/swc-darwin-arm64': 14.2.33
       '@next/swc-darwin-x64': 14.2.33
@@ -24173,6 +23549,11 @@ snapshots:
 
   node-fetch-native@1.6.7: {}
 
+  node-fetch@2.7.0:
+    dependencies:
+      whatwg-url: 5.0.0
+    optional: true
+
   node-fetch@3.3.2:
     dependencies:
       data-uri-to-buffer: 4.0.1
@@ -24192,6 +23573,11 @@ snapshots:
 
   node-releases@2.0.47: {}
 
+  nopt@5.0.0:
+    dependencies:
+      abbrev: 1.1.1
+    optional: true
+
   normalize-path@3.0.0: {}
 
   normalize-svg-path@1.1.0:
@@ -24211,6 +23597,14 @@ snapshots:
       path-key: 4.0.0
       unicorn-magic: 0.3.0
 
+  npmlog@5.0.1:
+    dependencies:
+      are-we-there-yet: 2.0.0
+      console-control-strings: 1.1.0
+      gauge: 3.0.2
+      set-blocking: 2.0.0
+    optional: true
+
   nth-check@2.1.1:
     dependencies:
       boolbase: 1.0.0
@@ -24506,6 +23900,9 @@ snapshots:
 
   path-type@4.0.0: {}
 
+  path2d-polyfill@2.0.1:
+    optional: true
+
   path@0.12.7:
     dependencies:
       process: 0.11.10
@@ -24526,6 +23923,14 @@ snapshots:
       pako: 1.0.11
       tslib: 1.14.1
 
+  pdfjs-dist@3.11.174:
+    optionalDependencies:
+      canvas: 2.11.2
+      path2d-polyfill: 2.0.1
+    transitivePeerDependencies:
+      - encoding
+      - supports-color
+
   pdfjs-dist@5.4.296:
     optionalDependencies:
       '@napi-rs/canvas': 0.1.100
@@ -24808,9 +24213,9 @@ snapshots:
 
   pure-rand@6.1.0: {}
 
-  qrcode.react@3.2.0(react@18.3.1):
+  qrcode.react@3.2.0(react@19.2.6):
     dependencies:
-      react: 18.3.1
+      react: 19.2.6
 
   qrcode@1.5.4:
     dependencies:
@@ -24852,69 +24257,6 @@ snapshots:
       parchment: 3.0.0
       quill-delta: 5.1.0
 
-  radix-ui@1.5.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-accessible-icon': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-accordion': 1.2.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-alert-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-arrow': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-aspect-ratio': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-avatar': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-checkbox': 1.3.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-collapsible': 1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context-menu': 2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-dropdown-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-form': 0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-hover-card': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-label': 2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-menubar': 1.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-navigation-menu': 1.2.15(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-one-time-password-field': 0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-password-toggle-field': 0.1.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-popover': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-progress': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-radio-group': 1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-scroll-area': 1.2.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-select': 2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-separator': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slider': 1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-switch': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-tabs': 1.1.14(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-toast': 1.2.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-toggle': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-toggle-group': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-toolbar': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-tooltip': 1.2.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-escape-keydown': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   radix-ui@1.5.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -25043,28 +24385,14 @@ snapshots:
       date-fns: 3.6.0
       react: 19.2.6
 
-  react-day-picker@9.14.0(react@18.3.1):
-    dependencies:
-      '@date-fns/tz': 1.5.0
-      '@tabby_ai/hijri-converter': 1.0.5
-      date-fns: 4.4.0
-      date-fns-jalali: 4.1.0-0
-      react: 18.3.1
-
   react-day-picker@9.14.0(react@19.2.6):
     dependencies:
       '@date-fns/tz': 1.5.0
       '@tabby_ai/hijri-converter': 1.0.5
-      date-fns: 4.4.0
+      date-fns: 3.6.0
       date-fns-jalali: 4.1.0-0
       react: 19.2.6
 
-  react-dom@18.3.1(react@18.3.1):
-    dependencies:
-      loose-envify: 1.4.0
-      react: 18.3.1
-      scheduler: 0.23.2
-
   react-dom@19.2.6(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -25077,10 +24405,6 @@ snapshots:
       prop-types: 15.8.1
       react: 19.2.6
 
-  react-hook-form@7.77.0(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-
   react-hook-form@7.77.0(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -25153,11 +24477,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  react-number-format@5.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-
   react-number-format@5.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -25177,13 +24496,16 @@ snapshots:
       make-cancellable-promise: 2.0.0
       make-event-props: 2.0.0
       merge-refs: 2.0.0(@types/react@18.3.31)
-      pdfjs-dist: 5.4.296
+      pdfjs-dist: 3.11.174
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
       tiny-invariant: 1.3.3
       warning: 4.0.3
     optionalDependencies:
       '@types/react': 18.3.31
+    transitivePeerDependencies:
+      - encoding
+      - supports-color
 
   react-phone-number-input@3.4.17(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
@@ -25214,14 +24536,6 @@ snapshots:
 
   react-refresh@0.17.0: {}
 
-  react-remove-scroll-bar@2.3.8(@types/react@18.3.31)(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-      react-style-singleton: 2.2.3(@types/react@18.3.31)(react@18.3.1)
-      tslib: 2.8.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   react-remove-scroll-bar@2.3.8(@types/react@18.3.31)(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -25230,17 +24544,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  react-remove-scroll@2.7.2(@types/react@18.3.31)(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-      react-remove-scroll-bar: 2.3.8(@types/react@18.3.31)(react@18.3.1)
-      react-style-singleton: 2.2.3(@types/react@18.3.31)(react@18.3.1)
-      tslib: 2.8.1
-      use-callback-ref: 1.3.3(@types/react@18.3.31)(react@18.3.1)
-      use-sidecar: 1.1.3(@types/react@18.3.31)(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   react-remove-scroll@2.7.2(@types/react@18.3.31)(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -25300,21 +24603,13 @@ snapshots:
     dependencies:
       react-dom: 19.2.6(react@19.2.6)
 
-  react-smooth@4.0.4(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+  react-smooth@4.0.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       fast-equals: 5.4.0
       prop-types: 15.8.1
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      react-transition-group: 4.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-
-  react-style-singleton@2.2.3(@types/react@18.3.31)(react@18.3.1):
-    dependencies:
-      get-nonce: 1.0.1
-      react: 18.3.1
-      tslib: 2.8.1
-    optionalDependencies:
-      '@types/react': 18.3.31
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-transition-group: 4.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
 
   react-style-singleton@2.2.3(@types/react@18.3.31)(react@19.2.6):
     dependencies:
@@ -25333,15 +24628,6 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
-  react-transition-group@4.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
-    dependencies:
-      '@babel/runtime': 7.29.7
-      dom-helpers: 5.2.1
-      loose-envify: 1.4.0
-      prop-types: 15.8.1
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-
   react-transition-group@4.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       '@babel/runtime': 7.29.7
@@ -25351,10 +24637,6 @@ snapshots:
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
 
-  react@18.3.1:
-    dependencies:
-      loose-envify: 1.4.0
-
   react@19.2.6: {}
 
   read-cache@1.0.0:
@@ -25417,15 +24699,15 @@ snapshots:
     dependencies:
       decimal.js-light: 2.5.1
 
-  recharts@2.15.4(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+  recharts@2.15.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       clsx: 2.1.1
       eventemitter3: 4.0.7
       lodash: 4.18.1
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
       react-is: 18.3.1
-      react-smooth: 4.0.4(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react-smooth: 4.0.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       recharts-scale: 0.4.5
       tiny-invariant: 1.3.3
       victory-vendor: 36.9.2
@@ -25723,10 +25005,6 @@ snapshots:
     dependencies:
       xmlchars: 2.2.0
 
-  scheduler@0.23.2:
-    dependencies:
-      loose-envify: 1.4.0
-
   scheduler@0.25.0-rc-603e6108-20241029: {}
 
   scheduler@0.27.0: {}
@@ -25938,6 +25216,16 @@ snapshots:
 
   signature_pad@2.3.2: {}
 
+  simple-concat@1.0.1:
+    optional: true
+
+  simple-get@3.1.1:
+    dependencies:
+      decompress-response: 4.2.1
+      once: 1.4.0
+      simple-concat: 1.0.1
+    optional: true
+
   sisteransi@1.0.5: {}
 
   slash@3.0.0: {}
@@ -26341,10 +25629,10 @@ snapshots:
     transitivePeerDependencies:
       - '@babel/core'
 
-  styled-jsx@5.1.1(babel-plugin-macros@3.1.0)(react@18.3.1):
+  styled-jsx@5.1.1(babel-plugin-macros@3.1.0)(react@19.2.6):
     dependencies:
       client-only: 0.0.1
-      react: 18.3.1
+      react: 19.2.6
     optionalDependencies:
       babel-plugin-macros: 3.1.0
 
@@ -26499,6 +25787,16 @@ snapshots:
       - bare-buffer
       - react-native-b4a
 
+  tar@6.2.1:
+    dependencies:
+      chownr: 2.0.0
+      fs-minipass: 2.1.0
+      minipass: 5.0.0
+      minizlib: 2.1.2
+      mkdirp: 1.0.4
+      yallist: 4.0.0
+    optional: true
+
   teex@1.0.1:
     dependencies:
       streamx: 2.27.0
@@ -26656,6 +25954,9 @@ snapshots:
     dependencies:
       tldts: 7.4.2
 
+  tr46@0.0.3:
+    optional: true
+
   tr46@5.1.1:
     dependencies:
       punycode: 2.3.1
@@ -27083,13 +26384,6 @@ snapshots:
       punycode: 1.4.1
       qs: 6.15.2
 
-  use-callback-ref@1.3.3(@types/react@18.3.31)(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-      tslib: 2.8.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   use-callback-ref@1.3.3(@types/react@18.3.31)(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -27122,14 +26416,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  use-sidecar@1.1.3(@types/react@18.3.31)(react@18.3.1):
-    dependencies:
-      detect-node-es: 1.1.0
-      react: 18.3.1
-      tslib: 2.8.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   use-sidecar@1.1.3(@types/react@18.3.31)(react@19.2.6):
     dependencies:
       detect-node-es: 1.1.0
@@ -27138,11 +26424,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  use-sync-external-store@1.6.0(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-    optional: true
-
   use-sync-external-store@1.6.0(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -27319,7 +26600,7 @@ snapshots:
       lightningcss: 1.32.0
       terser: 5.48.0
 
-  vitest@2.1.9(@types/node@22.20.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(terser@5.48.0):
+  vitest@2.1.9(@types/node@22.20.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(terser@5.48.0):
     dependencies:
       '@vitest/expect': 2.1.9
       '@vitest/mocker': 2.1.9(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(vite@5.4.21(@types/node@22.20.1)(lightningcss@1.32.0)(terser@5.48.0))
@@ -27343,7 +26624,7 @@ snapshots:
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 22.20.1
-      jsdom: 25.0.1
+      jsdom: 25.0.1(canvas@2.11.2)
     transitivePeerDependencies:
       - less
       - lightningcss
@@ -27355,7 +26636,7 @@ snapshots:
       - supports-color
       - terser
 
-  vitest@2.1.9(@types/node@24.13.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0):
+  vitest@2.1.9(@types/node@24.13.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0):
     dependencies:
       '@vitest/expect': 2.1.9
       '@vitest/mocker': 2.1.9(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(vite@5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0))
@@ -27379,7 +26660,7 @@ snapshots:
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 24.13.1
-      jsdom: 25.0.1
+      jsdom: 25.0.1(canvas@2.11.2)
     transitivePeerDependencies:
       - less
       - lightningcss
@@ -27443,6 +26724,9 @@ snapshots:
 
   webdriver-bidi-protocol@0.4.1: {}
 
+  webidl-conversions@3.0.1:
+    optional: true
+
   webidl-conversions@7.0.0: {}
 
   webpack-node-externals@3.0.0: {}
@@ -27501,6 +26785,12 @@ snapshots:
       tr46: 5.1.1
       webidl-conversions: 7.0.0
 
+  whatwg-url@5.0.0:
+    dependencies:
+      tr46: 0.0.3
+      webidl-conversions: 3.0.1
+    optional: true
+
   which-boxed-primitive@1.1.1:
     dependencies:
       is-bigint: 1.1.0
@@ -27557,6 +26847,11 @@ snapshots:
       siginfo: 2.0.0
       stackback: 0.0.2
 
+  wide-align@1.1.5:
+    dependencies:
+      string-width: 4.2.3
+    optional: true
+
   wmf@1.0.2: {}
 
   word-wrap@1.2.5: {}
@@ -27643,6 +26938,9 @@ snapshots:
 
   yallist@3.1.1: {}
 
+  yallist@4.0.0:
+    optional: true
+
   yaml@1.10.3: {}
 
   yaml@2.9.0: {}
@@ -27734,13 +27032,6 @@ snapshots:
 
   zod@4.4.3: {}
 
-  zustand@5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@18.3.1)(use-sync-external-store@1.6.0(react@18.3.1)):
-    optionalDependencies:
-      '@types/react': 18.3.31
-      immer: 11.1.8
-      react: 18.3.1
-      use-sync-external-store: 1.6.0(react@18.3.1)
-
   zustand@5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@19.2.6)(use-sync-external-store@1.6.0(react@19.2.6)):
     optionalDependencies:
       '@types/react': 18.3.31

From a603807e8e58b04e7a3580a85f2c753e669e6b88 Mon Sep 17 00:00:00 2001
From: ghost2023 <nathnaelwonisha@gmail.com>
Date: Wed, 12 Aug 2026 06:26:46 +0300
Subject: [PATCH 027/174] feat(freight-api): seal EDR side of contracts with
 the one global stamp

---
 .../contracts/contract-provider-stamp.spec.ts |  99 ++++++++++++
 .../contracts/contract-view-model.builder.ts  |  32 +++-
 apps/edr-freight-api/src/main.ts              |  11 +-
 .../documents/invoice-document.service.ts     |  12 +-
 .../documents/seal-markup.util.spec.ts        |  78 +++++++++
 .../billing/documents/seal-markup.util.ts     |  64 ++++++++
 .../bookings/booking-contract.service.ts      |   1 +
 .../modules/bookings/dto/contract-view.dto.ts |   6 +
 .../dto/complete-identity-verification.dto.ts |  10 ++
 .../contracts/contract-staff-stamp.spec.ts    | 152 ++++++++++++++++++
 .../contracts/contract-transition.service.ts  |  26 ++-
 .../stamp-settings.service.spec.ts            | 110 +++++++++++++
 .../stamp-settings/stamp-settings.service.ts  |  24 ++-
 .../warehouses/warehouse-inventory.service.ts |  15 +-
 .../src/seed/freight-permissions.registry.ts  |  10 +-
 .../components/profile/MySignatureCard.tsx    | 146 ++++-------------
 .../pages/bookings/BookingContractPage.tsx    |  23 +--
 .../src/pages/contracts/ContractViewPage.tsx  |  19 +--
 .../src/services/bookings.service.ts          |   7 +-
 .../src/services/contracts.service.ts         |   7 +-
 .../src/services/signatures.service.ts        |  10 +-
 21 files changed, 679 insertions(+), 183 deletions(-)
 create mode 100644 apps/edr-freight-api/src/contracts/contract-provider-stamp.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/billing/documents/seal-markup.util.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/billing/documents/seal-markup.util.ts
 create mode 100644 apps/edr-freight-api/src/modules/contracts/contract-staff-stamp.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.spec.ts

diff --git a/apps/edr-freight-api/src/contracts/contract-provider-stamp.spec.ts b/apps/edr-freight-api/src/contracts/contract-provider-stamp.spec.ts
new file mode 100644
index 000000000..023e4ac8c
--- /dev/null
+++ b/apps/edr-freight-api/src/contracts/contract-provider-stamp.spec.ts
@@ -0,0 +1,99 @@
+import { ContractViewModelBuilder, ContractSignatureView } from "./contract-view-model.builder";
+
+/**
+ * The EDR side of a contract is sealed with the ONE global company stamp, read
+ * live at render time; the client side keeps whatever stamp the customer
+ * uploaded. These specs pin that asymmetry — the standing rule is that
+ * centralizing the EDR seal must not touch customer stamps.
+ */
+describe("ContractViewModelBuilder.attachProviderStamp", () => {
+  const STAMP = "data:image/png;base64,RURS";
+
+  const build = (stampImageUrl: string | null = STAMP) => {
+    const getStampImageUrl = jest.fn().mockResolvedValue(stampImageUrl);
+    const builder = Object.create(
+      ContractViewModelBuilder.prototype,
+    ) as ContractViewModelBuilder;
+    Object.assign(builder, { stampSettings: { getStampImageUrl } });
+    return { builder, getStampImageUrl };
+  };
+
+  const sig = (role: "STAFF" | "CUSTOMER", extra: Partial<ContractSignatureView> = {}) =>
+    ({
+      role,
+      signerDisplayName: `${role} signer`,
+      signedAt: "1 January 2026",
+      signatureImageUrl: "https://minio.local/sig.png",
+      ...extra,
+    }) as ContractSignatureView;
+
+  it("stamps the EDR side with the global stamp", async () => {
+    const { builder } = build();
+    const signatures = [sig("STAFF")];
+
+    await builder.attachProviderStamp(signatures);
+
+    expect(signatures[0]!.stampImageUrl).toBe(STAMP);
+  });
+
+  it("leaves the customer side untouched", async () => {
+    const { builder } = build();
+    const customerStamp = "data:image/png;base64,Q1VTVA==";
+    const signatures = [
+      sig("CUSTOMER", { stampImageUrl: customerStamp }),
+      sig("STAFF"),
+    ];
+
+    await builder.attachProviderStamp(signatures);
+
+    expect(signatures[0]!.stampImageUrl).toBe(customerStamp);
+    expect(signatures[1]!.stampImageUrl).toBe(STAMP);
+  });
+
+  it("does not read the stamp at all when EDR has not signed yet", async () => {
+    const { builder, getStampImageUrl } = build();
+    const signatures = [sig("CUSTOMER")];
+
+    await builder.attachProviderStamp(signatures);
+
+    expect(getStampImageUrl).not.toHaveBeenCalled();
+    expect(signatures[0]!.stampImageUrl).toBeUndefined();
+  });
+
+  it("renders unstamped rather than failing when no stamp is configured", async () => {
+    const { builder } = build(null);
+    const signatures = [sig("STAFF")];
+
+    await expect(builder.attachProviderStamp(signatures)).resolves.toBeUndefined();
+    expect(signatures[0]!.stampImageUrl).toBeNull();
+  });
+
+  it("reads the stamp once for every EDR signature row", async () => {
+    const { builder, getStampImageUrl } = build();
+    const signatures = [sig("STAFF"), sig("STAFF")];
+
+    await builder.attachProviderStamp(signatures);
+
+    expect(getStampImageUrl).toHaveBeenCalledTimes(1);
+    expect(signatures.map((s) => s.stampImageUrl)).toEqual([STAMP, STAMP]);
+  });
+
+  it("is applied by loadSignatures, so the HTML view and the PDF agree", async () => {
+    const { builder } = build();
+    Object.assign(builder, {
+      bookingsRepository: {
+        findContractSignatures: jest.fn().mockResolvedValue([
+          { signerRole: "STAFF", signerDisplayName: "EDR", signedAt: new Date() },
+        ]),
+      },
+    });
+
+    const views = await (
+      builder as unknown as {
+        loadSignatures(id: string): Promise<ContractSignatureView[]>;
+      }
+    ).loadSignatures("b-1");
+
+    expect(views[0]!.stampImageUrl).toBe(STAMP);
+  });
+});
diff --git a/apps/edr-freight-api/src/contracts/contract-view-model.builder.ts b/apps/edr-freight-api/src/contracts/contract-view-model.builder.ts
index d1158d035..94a6809e6 100644
--- a/apps/edr-freight-api/src/contracts/contract-view-model.builder.ts
+++ b/apps/edr-freight-api/src/contracts/contract-view-model.builder.ts
@@ -9,6 +9,7 @@ import {
 import { ContractPricingScheduleBuilder, PricingSchedule } from './contract-pricing-schedule.builder';
 import { ContractRateScheduleBuilder, RateSchedule } from './contract-rate-schedule.builder';
 import { ContractTemplateResolver } from './contract-template.resolver';
+import { StampSettingsService } from '../modules/stamp-settings/stamp-settings.service';
 import { ContractTemplateMeta, getTemplateMeta } from './contract-template.registry';
 
 export interface ContractSignatureView {
@@ -16,6 +17,11 @@ export interface ContractSignatureView {
   signerDisplayName: string;
   signedAt: string;
   signatureImageUrl?: string | null;
+  /**
+   * Round company seal shown beside the signature. Populated for the EDR
+   * (STAFF) side only, from the single global stamp — see attachProviderStamp.
+   */
+  stampImageUrl?: string | null;
 }
 
 /**
@@ -114,6 +120,7 @@ export class ContractViewModelBuilder {
     private readonly templateResolver: ContractTemplateResolver,
     private readonly pricingBuilder: ContractPricingScheduleBuilder,
     private readonly rateScheduleBuilder: ContractRateScheduleBuilder,
+    private readonly stampSettings: StampSettingsService,
   ) {}
 
   async build(bookingId: string): Promise<{ booking: Booking; view: ContractViewModel }> {
@@ -194,7 +201,30 @@ export class ContractViewModelBuilder {
 
   private async loadSignatures(bookingId: string): Promise<ContractSignatureView[]> {
     const rows = await this.bookingsRepository.findContractSignatures(bookingId);
-    return rows.map((s) => this.toSignatureView(s));
+    const views = rows.map((s) => this.toSignatureView(s));
+    await this.attachProviderStamp(views);
+    return views;
+  }
+
+  /**
+   * Stamp the EDR side of the contract with the ONE global company stamp
+   * (StampSettingsService) — staff never upload or pick a stamp, so nothing is
+   * stored per signature and the seal is read live at render time. The client
+   * side is left alone: a customer's own stamp is their business.
+   *
+   * Read live and deliberately not snapshotted, so replacing the company stamp
+   * re-seals contracts on their next render. `getStampImageUrl()` never throws
+   * and returns a data URL, which `signatures_block.hbs` renders as-is and the
+   * signature inliner skips.
+   */
+  async attachProviderStamp(signatures: ContractSignatureView[]): Promise<void> {
+    const staff = signatures.filter((s) => s.role === 'STAFF');
+    if (staff.length === 0) return;
+
+    const stampImageUrl = await this.stampSettings.getStampImageUrl();
+    for (const sig of staff) {
+      sig.stampImageUrl = stampImageUrl;
+    }
   }
 
   toSignatureView(row: BookingContractSignature): ContractSignatureView {
diff --git a/apps/edr-freight-api/src/main.ts b/apps/edr-freight-api/src/main.ts
index f26cd19e7..5d2168baa 100644
--- a/apps/edr-freight-api/src/main.ts
+++ b/apps/edr-freight-api/src/main.ts
@@ -15,10 +15,13 @@ import { getAuditLoggerConfig } from "@tria-plc/auditlog";
 import { AppModule } from "./app.module";
 
 /**
- * JSON body ceiling. Signing posts the signature AND the company stamp as
- * base64 in one JSON body, and base64 inflates bytes by ~4/3 — a 50MB asset is
- * ~67MB on the wire. Express defaults to 100kb, which rejected any real stamp
- * image with a 413 "request entity too large".
+ * JSON body ceiling. Customer signing posts the signature AND the customer's
+ * own company stamp as base64 in one JSON body, and base64 inflates bytes by
+ * ~4/3 — a 50MB asset is ~67MB on the wire. Express defaults to 100kb, which
+ * rejected any real stamp image with a 413 "request entity too large".
+ * (Staff signing posts only a signature: EDR's seal is the one global stamp,
+ * read server-side. Uploading that stamp under Settings goes through this same
+ * ceiling, so the headroom is still needed on both counts.)
  *
  * Sized to clear the 50MB per-document ceiling
  * (`DOCUMENT_UPLOAD_MAX_BYTES`) after base64 inflation, with room for the
diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
index 72146491d..268e94ad9 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
@@ -2,6 +2,7 @@ import { Injectable } from "@nestjs/common";
 
 import { StampSettingsService } from "../../stamp-settings/stamp-settings.service";
 import { PdfRenderService } from "./pdf-render.service";
+import { sealClass, sealImageCss, sealMarkup } from "./seal-markup.util";
 import {
   PdfColor,
   assembleSinglePagePdf,
@@ -239,10 +240,8 @@ export class InvoiceDocumentService {
     const showCategory = Boolean(model.categoryHeader);
     const sealText =
       model.sealText ?? (model.kind === "RECEIPT" || model.status === "PAID" ? "EDR PAID" : "EDR");
-    const sealMarkup = model.stampImageUrl
-      ? `<img src="${esc(model.stampImageUrl)}" alt="Company stamp" />`
-      : esc(sealText);
-    const sealClass = model.stampImageUrl ? "seal seal-image" : "seal";
+    const sealInner = sealMarkup(model.stampImageUrl, sealText);
+    const sealCssClass = sealClass(model.stampImageUrl);
 
     const summaryRows = model.summary
       .map((row) => `<div><span>${esc(row.label)}</span>${esc(row.value)}</div>`)
@@ -281,8 +280,7 @@ export class InvoiceDocumentService {
     .meta { text-align: right; font-size: 12px; color: #475569; }
     .meta strong { display: block; color: #0f172a; font-size: 17px; margin-top: 5px; }
     .seal { position: absolute; right: 28px; top: 118px; width: 116px; height: 116px; border: 4px double #0f766e; border-radius: 999px; color: #0f766e; display: flex; align-items: center; justify-content: center; text-align: center; font-weight: 800; font-size: 18px; transform: rotate(-14deg); opacity: .82; }
-    .seal.seal-image { border: none; border-radius: 0; opacity: 1; transform: none; }
-    .seal img { max-width: 100%; max-height: 100%; object-fit: contain; }
+    ${sealImageCss()}
     .summary { display: grid; grid-template-columns: 1fr 1fr; gap: 12px 28px; margin: 24px 150px 16px 0; font-size: 13px; }
     .summary div { border-bottom: 1px solid #e2e8f0; padding: 7px 0; }
     .summary span { color: #64748b; display: block; font-size: 11px; margin-bottom: 3px; }
@@ -310,7 +308,7 @@ export class InvoiceDocumentService {
         Issued: ${esc(date(model.issuedAt))}
       </div>
     </div>
-    <div class="${sealClass}">${sealMarkup}</div>
+    <div class="${sealCssClass}">${sealInner}</div>
     <div class="summary">${summaryRows}</div>
     <table>
       <thead>
diff --git a/apps/edr-freight-api/src/modules/billing/documents/seal-markup.util.spec.ts b/apps/edr-freight-api/src/modules/billing/documents/seal-markup.util.spec.ts
new file mode 100644
index 000000000..d07f8ebf6
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/documents/seal-markup.util.spec.ts
@@ -0,0 +1,78 @@
+import { sealClass, sealImageCss, sealMarkup } from "./seal-markup.util";
+
+/**
+ * These three helpers are the single image-vs-text branch shared by every
+ * EDR document's round seal, so a regression here silently unstamps invoices,
+ * warehouse release papers and handover papers at once.
+ */
+describe("seal markup helpers", () => {
+  const STAMP = "data:image/png;base64,QUJD";
+
+  describe("sealMarkup", () => {
+    it("renders the stamp image when one is configured", () => {
+      expect(sealMarkup(STAMP, ["EDR", "Warehouse"])).toBe(
+        `<img src="${STAMP}" alt="Company stamp" />`,
+      );
+    });
+
+    it("falls back to text rings when no stamp is configured", () => {
+      expect(sealMarkup(null, ["EDR", "Warehouse", "Cleared"])).toBe(
+        "<span>EDR<br />Warehouse<br />Cleared</span>",
+      );
+    });
+
+    it("treats undefined as unset", () => {
+      expect(sealMarkup(undefined, "EDR")).toBe("<span>EDR</span>");
+    });
+
+    it("accepts a bare string as a single line", () => {
+      expect(sealMarkup(null, "EDR")).toBe("<span>EDR</span>");
+    });
+
+    it("escapes text lines so document data cannot inject markup", () => {
+      expect(sealMarkup(null, ['<script>alert("x")</script>'])).toBe(
+        "<span>&lt;script&gt;alert(&quot;x&quot;)&lt;/script&gt;</span>",
+      );
+    });
+
+    it("escapes the image src so it cannot break out of the attribute", () => {
+      expect(sealMarkup('data:image/png;base64,A" onerror="x', "EDR")).toBe(
+        '<img src="data:image/png;base64,A&quot; onerror=&quot;x" alt="Company stamp" />',
+      );
+    });
+  });
+
+  describe("sealClass", () => {
+    it("adds the image modifier only when stamped", () => {
+      expect(sealClass(STAMP)).toBe("seal seal-image");
+      expect(sealClass(null)).toBe("seal");
+    });
+
+    it("honours a document's own seal selector", () => {
+      expect(sealClass(STAMP, "sig-stamp-box")).toBe(
+        "sig-stamp-box sig-stamp-box-image",
+      );
+      expect(sealClass(null, "sig-stamp-box")).toBe("sig-stamp-box");
+    });
+  });
+
+  describe("sealImageCss", () => {
+    it("neutralizes the drawn ring and rotation for a real stamp image", () => {
+      const css = sealImageCss();
+
+      expect(css).toContain(".seal.seal-image { border: none;");
+      expect(css).toContain("transform: none;");
+      // The ::before pseudo-element draws the inner ring of the text seal.
+      expect(css).toContain(".seal.seal-image::before { content: none; }");
+      expect(css).toContain(".seal img { max-width: 100%;");
+    });
+
+    it("scopes every rule to the given selector", () => {
+      const css = sealImageCss("sig-stamp-box");
+
+      expect(css).not.toContain(".seal");
+      expect(css).toContain(".sig-stamp-box.sig-stamp-box-image");
+      expect(css).toContain(".sig-stamp-box img");
+    });
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/billing/documents/seal-markup.util.ts b/apps/edr-freight-api/src/modules/billing/documents/seal-markup.util.ts
new file mode 100644
index 000000000..2dd9c4715
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/documents/seal-markup.util.ts
@@ -0,0 +1,64 @@
+/**
+ * The single decision every EDR document makes about its round seal: draw the
+ * one uploaded company stamp when one is configured (StampSettingsService), or
+ * fall back to the plain text rings the document styles itself.
+ *
+ * Only the image-vs-text branch and the image overrides live here — each
+ * document keeps its own `.seal` geometry (the invoice's seal is absolutely
+ * positioned top-right, the warehouse papers' sit inline above the signature
+ * lines), so centralizing the source of the stamp does not relayout anything.
+ *
+ * These helpers are for the HTML/Chromium render path. The hand-built vector
+ * fallbacks in styled-pdf.util.ts cannot embed a raster image and continue to
+ * draw their vector seal — see InvoiceDocumentService for that caveat.
+ */
+
+/** Escape a value for interpolation into HTML text or a quoted attribute. */
+function escapeHtml(value: unknown): string {
+  return String(value ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * CSS overrides that neutralize a document's own ring/rotation styling when the
+ * seal is a real stamp image. Append inside a document's <style> block, after
+ * its own `.seal` rules. `selector` is the document's seal class ("seal").
+ */
+export function sealImageCss(selector = "seal"): string {
+  return [
+    `.${selector}.${selector}-image { border: none; border-radius: 0; opacity: 1; transform: none; }`,
+    `.${selector}.${selector}-image::before { content: none; }`,
+    `.${selector} img { max-width: 100%; max-height: 100%; object-fit: contain; }`,
+  ].join("\n    ");
+}
+
+/**
+ * Inner markup for the seal element: the stamp image, or the given text lines
+ * wrapped in a <span> (matching the `.seal span { position: relative }` rule
+ * the ring-drawing documents rely on).
+ *
+ * `stampImageUrl` is expected to be a data URL from
+ * StampSettingsService.getStampImageUrl(); null renders the text fallback.
+ */
+export function sealMarkup(
+  stampImageUrl: string | null | undefined,
+  textLines: string | string[],
+): string {
+  if (stampImageUrl) {
+    return `<img src="${escapeHtml(stampImageUrl)}" alt="Company stamp" />`;
+  }
+  const lines = Array.isArray(textLines) ? textLines : [textLines];
+  return `<span>${lines.map(escapeHtml).join("<br />")}</span>`;
+}
+
+/** Class attribute for the seal element — adds the image modifier when stamped. */
+export function sealClass(
+  stampImageUrl: string | null | undefined,
+  selector = "seal",
+): string {
+  return stampImageUrl ? `${selector} ${selector}-image` : selector;
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-contract.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-contract.service.ts
index 095928bb3..70657f9f6 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-contract.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-contract.service.ts
@@ -304,6 +304,7 @@ export class BookingContractService {
   async getSignatures(bookingId: string) {
     const rows = await this.bookingsRepository.findContractSignatures(bookingId);
     const views = rows.map((r) => this.viewModelBuilder.toSignatureView(r));
+    await this.viewModelBuilder.attachProviderStamp(views);
     await this.inlineSignatureImages(views);
     return { signatures: views };
   }
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/contract-view.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/contract-view.dto.ts
index 0dceadf43..0491969ed 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/contract-view.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/contract-view.dto.ts
@@ -12,6 +12,12 @@ export class ContractSignatureDto {
 
   @ApiPropertyOptional()
   signatureImageUrl?: string | null;
+
+  @ApiPropertyOptional({
+    description:
+      'Company seal beside the signature. Set for the EDR (STAFF) side from the single global company stamp; null for the client side.',
+  })
+  stampImageUrl?: string | null;
 }
 
 export class SavedSignatureViewDto {
diff --git a/apps/edr-freight-api/src/modules/companies/dto/complete-identity-verification.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/complete-identity-verification.dto.ts
index 6fe1ecc74..feccc855d 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/complete-identity-verification.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/complete-identity-verification.dto.ts
@@ -138,6 +138,13 @@ export class CompanyIdentityStateDto {
   })
   etradeManagerName!: string | null;
 
+  @ApiProperty({
+    nullable: true,
+    description:
+      "That manager's phone, normalized to E.164 and captured at the same lookup. Paired with the name so the portal can still tell that the owner's details came from eTrade after a refresh, when the live lookup result is long gone — without it a resumed wizard offers them back as typeable inputs.",
+  })
+  etradeManagerPhone!: string | null;
+
   @ApiProperty({
     nullable: true,
     description:
@@ -277,6 +284,8 @@ export function buildCompanyIdentityState(
 
   const etradeManagerName =
     (attrs[ETRADE_MANAGER_NAME_KEY] as string | undefined) ?? null;
+  const etradeManagerPhone =
+    (attrs[ETRADE_MANAGER_PHONE_KEY] as string | undefined) ?? null;
 
   return {
     passportAccepted,
@@ -286,6 +295,7 @@ export function buildCompanyIdentityState(
     poa,
     identityProven,
     etradeManagerName,
+    etradeManagerPhone,
     ownerMatchesEtrade: ownerNameMatchesEtrade(owner.name, etradeManagerName),
     complete: subject !== null && identityProven,
   };
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-staff-stamp.spec.ts b/apps/edr-freight-api/src/modules/contracts/contract-staff-stamp.spec.ts
new file mode 100644
index 000000000..6d370c276
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/contracts/contract-staff-stamp.spec.ts
@@ -0,0 +1,152 @@
+import { BadRequestException } from '@nestjs/common';
+
+import { ContractTransitionService } from './contract-transition.service';
+
+/**
+ * Where the booking-contract view reads the global stamp live, the contracts
+ * path SNAPSHOTS it onto the signature row at signing time, so replacing the
+ * company stamp can never restamp an already-executed contract. These specs
+ * pin the sourcing split: EDR always seals with the global stamp and staff
+ * never supply one, while the customer must upload their own.
+ */
+describe('applySignature stamp sourcing', () => {
+  const contract = { id: 'c-1', reference: 'CTR-1', status: 'SIGNED_CUSTOMER' };
+  const GLOBAL_STAMP = 'data:image/png;base64,RURS';
+
+  const build = (globalStamp: string | null = GLOBAL_STAMP) => {
+    const uploads: Array<{ code: string; image: string }> = [];
+    const saved: unknown[] = [];
+    const service = Object.create(
+      ContractTransitionService.prototype,
+    ) as ContractTransitionService;
+    Object.assign(service, {
+      logger: { warn: jest.fn(), log: jest.fn() },
+      stampSettings: {
+        getStampImageUrl: jest.fn().mockResolvedValue(globalStamp),
+      },
+      contractsRepository: {
+        saveSignature: jest.fn((row: unknown) => {
+          saved.push(row);
+          return Promise.resolve(undefined);
+        }),
+      },
+      signaturesService: {
+        getForUser: jest.fn().mockResolvedValue(null),
+        upsertForUser: jest.fn().mockResolvedValue(undefined),
+      },
+      uploadSignatureAsset: jest.fn((_c: unknown, code: string, image: string) => {
+        uploads.push({ code, image });
+        return Promise.resolve({ id: `file-${code}` });
+      }),
+    });
+    return { service, uploads, saved };
+  };
+
+  const apply = (
+    service: ContractTransitionService,
+    dto: Record<string, unknown>,
+  ) =>
+    (
+      service as unknown as {
+        applySignature(
+          c: unknown,
+          d: unknown,
+          o: { signerUserId?: string },
+        ): Promise<void>;
+      }
+    ).applySignature(contract, dto, { signerUserId: 'u-1' });
+
+  const staffDto = {
+    role: 'STAFF' as const,
+    signerDisplayName: 'E. Staff',
+    signatureImageBase64: 'data:image/png;base64,U0lH',
+  };
+
+  it('seals the EDR side with the global stamp', async () => {
+    const { service, uploads, saved } = build();
+
+    await apply(service, staffDto);
+
+    expect(uploads).toContainEqual({ code: 'stamp_staff', image: GLOBAL_STAMP });
+    expect(saved[0]).toEqual(
+      expect.objectContaining({ stampFileId: 'file-stamp_staff' }),
+    );
+  });
+
+  it('ignores a stamp a staff client tries to supply', async () => {
+    const { service, uploads } = build();
+
+    await apply(service, {
+      ...staffDto,
+      stampImageBase64: 'data:image/png;base64,SEFDSw==',
+    });
+
+    expect(uploads).toContainEqual({ code: 'stamp_staff', image: GLOBAL_STAMP });
+    expect(uploads.map((u) => u.image)).not.toContain(
+      'data:image/png;base64,SEFDSw==',
+    );
+  });
+
+  /**
+   * Failing loudly matters here: getStampImageUrl degrades to null when the
+   * stamp cannot be inlined, and silently executing an unsealed contract would
+   * be worse than refusing to counter-sign.
+   */
+  it('refuses to counter-sign when no global stamp is configured', async () => {
+    const { service, saved } = build(null);
+
+    await expect(apply(service, staffDto)).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+    await expect(apply(service, staffDto)).rejects.toThrow(/company stamp is configured/i);
+    expect(saved).toHaveLength(0);
+  });
+
+  it('requires the customer to upload their own stamp', async () => {
+    const { service, saved } = build();
+
+    await expect(
+      apply(service, {
+        role: 'CUSTOMER',
+        signerDisplayName: 'C. Customer',
+        signatureImageBase64: 'data:image/png;base64,U0lH',
+      }),
+    ).rejects.toThrow(/company stamp is required/i);
+    expect(saved).toHaveLength(0);
+  });
+
+  it('snapshots the customer stamp and never substitutes the global one', async () => {
+    const { service, uploads } = build();
+    const customerStamp = 'data:image/png;base64,Q1VTVA==';
+
+    await apply(service, {
+      role: 'CUSTOMER',
+      signerDisplayName: 'C. Customer',
+      signatureImageBase64: 'data:image/png;base64,U0lH',
+      stampImageBase64: customerStamp,
+    });
+
+    expect(uploads).toContainEqual({
+      code: 'stamp_customer',
+      image: customerStamp,
+    });
+    expect(uploads.map((u) => u.image)).not.toContain(GLOBAL_STAMP);
+  });
+
+  /**
+   * DIRECTOR/CEO rows are internal approval signatures, not party seals, so
+   * they are deliberately exempt from the stamp requirement.
+   */
+  it('lets internal approval signatures through without any stamp', async () => {
+    const { service, uploads, saved } = build();
+
+    await apply(service, {
+      role: 'DIRECTOR',
+      signerDisplayName: 'D. Director',
+      signatureImageBase64: 'data:image/png;base64,U0lH',
+    });
+
+    expect(uploads.map((u) => u.code)).toEqual(['signature_director']);
+    expect(saved[0]).toEqual(expect.objectContaining({ stampFileId: null }));
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
index ba3e3fd8b..fc3a238ea 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
@@ -35,6 +35,7 @@ import { CargoTypesService } from '../rule-engine/services/cargo-types.service';
 import { DropdownSettingsService } from '../dropdown-settings/dropdown-settings.service';
 import { FilesService } from '../files/files.service';
 import { SignaturesService } from '../signatures/signatures.service';
+import { StampSettingsService } from '../stamp-settings/stamp-settings.service';
 import { OtpService } from '../otp/otp.service';
 import { ContractTemplatesService } from '../contract-templates/contract-templates.service';
 import { ContractPricingService } from './contract-pricing.service';
@@ -175,6 +176,7 @@ export class ContractTransitionService {
     private readonly otpService: OtpService,
     private readonly notifier: ContractNotifierService,
     private readonly contractTemplates: ContractTemplatesService,
+    private readonly stampSettings: StampSettingsService,
     @InjectDataSource()
     private readonly dataSource: DataSource,
   ) {}
@@ -1103,23 +1105,39 @@ export class ContractTransitionService {
     // The company stamp is a separate image from the drawn signature. Both
     // parties to the contract (client + EDR) must seal it; DIRECTOR/CEO rows
     // are internal approval signatures, not party seals, so they stay exempt.
-    const stampRequired = role === 'CUSTOMER' || role === 'STAFF';
-    if (stampRequired && !dto.stampImageBase64) {
+    //
+    // The two parties source their seal differently: the customer uploads their
+    // own company stamp, while EDR always seals with the ONE global stamp
+    // (StampSettingsService) — staff never upload or pick a stamp.
+    if (role === 'CUSTOMER' && !dto.stampImageBase64) {
       throw new BadRequestException(
         'A company stamp is required to sign this contract.',
       );
     }
 
+    // Snapshot whichever stamp applies onto the signature row rather than
+    // referencing the global one, so replacing the company stamp later can
+    // never restamp an already-executed contract.
+    let stampImageBase64 = dto.stampImageBase64 ?? null;
+    if (role === 'STAFF') {
+      stampImageBase64 = await this.stampSettings.getStampImageUrl();
+      if (!stampImageBase64) {
+        throw new BadRequestException(
+          'No company stamp is configured. Upload the company stamp under Settings before counter-signing contracts.',
+        );
+      }
+    }
+
     const fileRecord = await this.uploadSignatureAsset(
       contract,
       `signature_${role.toLowerCase()}`,
       imageBase64,
     );
-    const stampRecord = dto.stampImageBase64
+    const stampRecord = stampImageBase64
       ? await this.uploadSignatureAsset(
           contract,
           `stamp_${role.toLowerCase()}`,
-          dto.stampImageBase64,
+          stampImageBase64,
         )
       : null;
 
diff --git a/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.spec.ts b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.spec.ts
new file mode 100644
index 000000000..ef55e9ecc
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.spec.ts
@@ -0,0 +1,110 @@
+import { Readable } from "stream";
+
+import { StampSettingsService } from "./stamp-settings.service";
+
+/**
+ * The one global company stamp feeds three document paths (invoices, warehouse
+ * papers, contract signature blocks). All three treat the returned value as a
+ * `data:` URL — so the data-URL-or-null contract of getStampImageUrl is what
+ * these specs pin down, especially its behaviour when MinIO cannot be reached.
+ */
+describe("StampSettingsService.getStampImageUrl", () => {
+  const PNG = Buffer.from("fake-png-bytes");
+  const OBJECT_URL = "https://minio.local:9000/edr-freight/stamp/company.png";
+
+  const build = (
+    overrides: {
+      stampUrl?: string | null;
+      getFileStream?: jest.Mock;
+      findSingleton?: jest.Mock;
+    } = {},
+  ) => {
+    const service = Object.create(
+      StampSettingsService.prototype,
+    ) as StampSettingsService;
+    const warn = jest.fn();
+    Object.assign(service, {
+      logger: { warn, log: jest.fn() },
+      repository: {
+        findSingleton:
+          overrides.findSingleton ??
+          jest.fn().mockResolvedValue({
+            id: "s-1",
+            stampFileId: overrides.stampUrl ? "f-1" : null,
+            stampFile: overrides.stampUrl ? { url: overrides.stampUrl } : null,
+            updatedById: null,
+            updatedAt: null,
+          }),
+        create: jest.fn(),
+        update: jest.fn(),
+      },
+      minioService: {
+        getObjectNameFromUrl: jest.fn().mockReturnValue("stamp/company.png"),
+        getFileStream:
+          overrides.getFileStream ??
+          jest.fn().mockResolvedValue(Readable.from(PNG)),
+      },
+      filesService: { upload: jest.fn() },
+    });
+    return { service, warn };
+  };
+
+  it("inlines the stored stamp as a data URL", async () => {
+    const { service } = build({ stampUrl: OBJECT_URL });
+
+    await expect(service.getStampImageUrl()).resolves.toBe(
+      `data:image/png;base64,${PNG.toString("base64")}`,
+    );
+  });
+
+  it("returns null when no stamp is configured", async () => {
+    const { service } = build({ stampUrl: null });
+
+    await expect(service.getStampImageUrl()).resolves.toBeNull();
+  });
+
+  it("passes an already-inlined data URL straight through", async () => {
+    const dataUrl = "data:image/png;base64,QUJD";
+    const { service } = build({ stampUrl: dataUrl });
+
+    await expect(service.getStampImageUrl()).resolves.toBe(dataUrl);
+  });
+
+  /**
+   * Regression: inlineImageUrl falls back to the raw object URL when MinIO is
+   * unreachable, which is right for getView (a browser can fetch it) but wrong
+   * here. ContractTransitionService base64-decodes this value to snapshot the
+   * seal — and a URL decodes to garbage bytes WITHOUT throwing, so a transient
+   * MinIO failure used to seal an executed contract with a corrupt image file.
+   * Degrade to null instead so callers draw their text/vector seal.
+   */
+  it("returns null rather than a raw object URL when MinIO inlining fails", async () => {
+    const { service, warn } = build({
+      stampUrl: OBJECT_URL,
+      getFileStream: jest.fn().mockRejectedValue(new Error("connect ECONNREFUSED")),
+    });
+
+    await expect(service.getStampImageUrl()).resolves.toBeNull();
+    expect(warn).toHaveBeenCalledWith(expect.stringMatching(/plain seal/i));
+  });
+
+  it("never throws when the settings lookup itself fails", async () => {
+    const { service, warn } = build({
+      findSingleton: jest.fn().mockRejectedValue(new Error("db is down")),
+    });
+
+    await expect(service.getStampImageUrl()).resolves.toBeNull();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("db is down"));
+  });
+
+  it("still exposes the raw URL through getView, which a browser can load", async () => {
+    const { service } = build({
+      stampUrl: OBJECT_URL,
+      getFileStream: jest.fn().mockRejectedValue(new Error("connect ECONNREFUSED")),
+    });
+
+    await expect(service.getView()).resolves.toEqual(
+      expect.objectContaining({ stampImageUrl: OBJECT_URL }),
+    );
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.ts b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.ts
index 01352e133..9bb4f3a37 100644
--- a/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.ts
+++ b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.ts
@@ -49,14 +49,30 @@ export class StampSettingsService {
   }
 
   /**
-   * The stamp image for embedding into invoice PDFs. Never throws — invoice
-   * generation must succeed even if the stamp lookup fails; callers fall back
-   * to the programmatic seal when this returns null.
+   * The stamp image for embedding into generated documents, ALWAYS as a
+   * `data:` URL or null. Never throws — document generation must succeed even
+   * if the stamp lookup fails; callers fall back to their own seal on null.
+   *
+   * The data-URL-or-null guarantee is load-bearing, not cosmetic. Callers do
+   * two things with this value that a bare MinIO URL silently corrupts:
+   * ContractTransitionService base64-decodes it to snapshot the seal onto a
+   * signature row (a URL decodes to garbage bytes, not an error, permanently
+   * sealing an executed contract with a broken image), and the HTML render
+   * path inlines it into an <img> that headless Chromium cannot fetch. So
+   * where getView() may hand a raw URL to a browser that can load it, this
+   * degrades to null and lets the caller draw its text/vector seal instead.
    */
   async getStampImageUrl(): Promise<string | null> {
     try {
       const setting = await this.get();
-      return await this.inlineImageUrl(setting.stampFile?.url);
+      const inlined = await this.inlineImageUrl(setting.stampFile?.url);
+      if (inlined && !inlined.startsWith("data:")) {
+        this.logger.warn(
+          `Company stamp could not be inlined for document rendering (falling back to the plain seal): ${inlined}`,
+        );
+        return null;
+      }
+      return inlined;
     } catch (err) {
       this.logger.warn(
         `Could not load company stamp for PDF rendering: ${(err as Error).message}`,
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 2f204bd62..239485d3c 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
@@ -34,6 +34,8 @@ import {
   primaryContactUserJoin,
 } from '../notifications/resolve-company-phone.util';
 import { SignaturesService } from '../signatures/signatures.service';
+import { StampSettingsService } from '../stamp-settings/stamp-settings.service';
+import { sealClass, sealImageCss, sealMarkup } from '../billing/documents/seal-markup.util';
 import { BulkInspectDto } from './dto/bulk-inspect.dto';
 import { BulkReceiveDto, TruckEntranceDto } from './dto/bulk-receive.dto';
 import { DeliverInventoryDto } from './dto/deliver-inventory.dto';
@@ -414,6 +416,7 @@ export class WarehouseInventoryService {
     private readonly handover: HandoverService,
     private readonly inbox: NotificationInboxService,
     private readonly events: EventEmitter2,
+    private readonly stampSettings: StampSettingsService,
   ) {}
 
   /**
@@ -3744,6 +3747,7 @@ export class WarehouseInventoryService {
     const html = this.buildReleaseDocumentHtml({
       reference,
       issuedAt,
+      stampImageUrl: await this.stampSettings.getStampImageUrl(),
       bookingReference,
       bookingStatus: row?.bookingStatus ?? null,
       customerName: row?.customerName ?? null,
@@ -4798,6 +4802,7 @@ export class WarehouseInventoryService {
     const html = this.buildHandoverDocumentHtml({
       reference,
       handedOverAt,
+      stampImageUrl: await this.stampSettings.getStampImageUrl(),
       bookingReference,
       bookingStatus: row.bookingStatus ?? null,
       customerName: row.customerName ?? null,
@@ -5603,6 +5608,8 @@ export class WarehouseInventoryService {
     truckType?: string | null;
     truckGateOut?: string | null;
     truckWeightTons?: number | null;
+    /** The one global company stamp; null falls back to the drawn text seal. */
+    stampImageUrl?: string | null;
   }): string {
     const esc = (value: unknown) =>
       String(value ?? '-')
@@ -5689,6 +5696,7 @@ export class WarehouseInventoryService {
     .seal { width: 96px; height: 96px; margin: -28px auto 0; border: 3px double #17633a; border-radius: 999px; color: #17633a; display: flex; align-items: center; justify-content: center; text-align: center; font-weight: 800; font-size: 14px; line-height: 1.05; transform: rotate(-17deg); text-transform: uppercase; }
     .seal::before { content: ""; position: absolute; width: 78px; height: 78px; border: 1px solid #17633a; border-radius: 999px; }
     .seal span { position: relative; }
+    ${sealImageCss()}
   </style>
 </head>
 <body>
@@ -5722,7 +5730,7 @@ export class WarehouseInventoryService {
     </div>
     <div class="signatures">
       <div class="line">Officer in charge name / signature / date</div>
-      <div class="seal"><span>EDR<br />Warehouse<br />Cleared</span></div>
+      <div class="${sealClass(data.stampImageUrl)}">${sealMarkup(data.stampImageUrl, ['EDR', 'Warehouse', 'Cleared'])}</div>
       <div class="line">Customer or driver name / signature / date</div>
     </div>
   </div>
@@ -5762,6 +5770,8 @@ export class WarehouseInventoryService {
       signerDisplayName: string;
       signatureImageUrl: string | null;
     } | null;
+    /** The one global company stamp; null falls back to the drawn text seal. */
+    stampImageUrl?: string | null;
   }): string {
     const esc = (value: unknown) =>
       String(value ?? '-')
@@ -5839,6 +5849,7 @@ export class WarehouseInventoryService {
     .seal { position: relative; width: 96px; height: 96px; margin: -28px auto 0; border: 3px double #17633a; border-radius: 999px; color: #17633a; display: flex; align-items: center; justify-content: center; text-align: center; font-weight: 800; font-size: 14px; line-height: 1.05; transform: rotate(-17deg); text-transform: uppercase; }
     .seal::before { content: ""; position: absolute; width: 78px; height: 78px; border: 1px solid #17633a; border-radius: 999px; }
     .seal span { position: relative; }
+    ${sealImageCss()}
   </style>
 </head>
 <body>
@@ -5882,7 +5893,7 @@ export class WarehouseInventoryService {
   </div>
   <div class="signatures">
     <div class="line">Officer in charge name / signature / date</div>
-    <div class="seal"><span>EDR<br />Warehouse<br />Handover</span></div>
+    <div class="${sealClass(data.stampImageUrl)}">${sealMarkup(data.stampImageUrl, ['EDR', 'Warehouse', 'Handover'])}</div>
     <div class="line">
       ${approval?.signatureImageUrl ? `<img class="signature-img" src="${esc(approval.signatureImageUrl)}" />` : ''}
       <div class="signature-meta">${approval ? esc(approval.signerDisplayName) : 'Customer or driver name / signature / date'}</div>
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index fb9afb5e1..56664de57 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -1301,7 +1301,10 @@ export const GRANULAR_SPLIT_PERMISSIONS: FreightPermissionSeed[] = [
     "Edit contract templates & articles",
   ),
   // Granular split of contract-template access. `view` opens the sidebar page;
-  // `read` is API-read-only for other pages that display template data.
+  // `read` is API-read-only for other pages that display template data — and is
+  // NOT written out here: deriveReadPermissions mints the `:read` twin of every
+  // `:view` key, so a hand-written one duplicates the key (Postgres 21000 on the
+  // seeder's ON CONFLICT (key) insert) and carries a v4 id where twins are v5.
   perm(
     "b4e00001-0001-4000-8000-000000000003",
     "edr_freight_app:settings:contract_templates:create",
@@ -1317,11 +1320,6 @@ export const GRANULAR_SPLIT_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:settings:contract_templates:delete",
     "Delete bulk contract templates",
   ),
-  perm(
-    "b4e00001-0001-4000-8000-000000000006",
-    "edr_freight_app:settings:contract_templates:read",
-    "Read contract template data (API only)",
-  ),
   perm(
     "b4f00001-0001-4000-8000-000000000001",
     "edr_freight_app:settings:support_content:view",
diff --git a/apps/edr-freight-web/backoffice/src/components/profile/MySignatureCard.tsx b/apps/edr-freight-web/backoffice/src/components/profile/MySignatureCard.tsx
index 0a70b3aec..b13ba4291 100644
--- a/apps/edr-freight-web/backoffice/src/components/profile/MySignatureCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/profile/MySignatureCard.tsx
@@ -1,11 +1,10 @@
 import { useState } from "react";
-import { FileSignature, Loader2, Stamp } from "lucide-react";
+import { FileSignature, Loader2 } from "lucide-react";
 import { useMutation, useQuery } from "@tanstack/react-query";
 import toast from "react-hot-toast";
 
 import { api } from "@/services/api";
 import { ContractSignaturePad } from "@/components/bookings/ContractSignaturePad";
-import { StampUpload } from "@/components/contracts/StampUpload";
 import {
   Card,
   CardContent,
@@ -27,9 +26,13 @@ import {
 } from "@edr/ui-common";
 
 /**
- * Lets the signed-in user view and update the reusable signature and company
- * stamp stored on their profile — managed independently of each other. Both
- * are offered when signing a booking contract.
+ * Lets the signed-in user view and update the reusable signature stored on
+ * their profile, offered for approval when signing a contract.
+ *
+ * Signature only — there is no per-employee stamp. EDR seals with ONE global
+ * company stamp, managed under Settings and applied server-side, so a staff
+ * member never uploads or picks a stamp. (Customers do upload their own, in
+ * the portal — that is a different card.)
  */
 export function MySignatureCard() {
   const { user } = useAuth();
@@ -39,10 +42,8 @@ export function MySignatureCard() {
   const saveMutation = useMutation(api.signatures.save.mutationOptions());
 
   const [signatureOpen, setSignatureOpen] = useState(false);
-  const [stampOpen, setStampOpen] = useState(false);
   const [signerName, setSignerName] = useState("");
   const [signatureData, setSignatureData] = useState<string | null>(null);
-  const [stampData, setStampData] = useState<string | null>(null);
 
   const defaultName =
     user?.name?.en || user?.username || user?.email || "";
@@ -60,7 +61,6 @@ export function MySignatureCard() {
       {
         signerDisplayName: signerName.trim(),
         signatureImageBase64: signatureData,
-        // Stamp untouched — it is managed by its own dialog.
       },
       {
         onSuccess: () => {
@@ -72,38 +72,16 @@ export function MySignatureCard() {
     );
   };
 
-  const openStampDialog = () => {
-    setStampData(saved?.stampImageUrl ?? null);
-    setStampOpen(true);
-  };
-
-  const saveStamp = () => {
-    if (!stampData) return;
-    saveMutation.mutate(
-      {
-        signerDisplayName: savedName || defaultName,
-        // Signature untouched — stamp-only update.
-        stampImageBase64: stampData,
-      },
-      {
-        onSuccess: () => {
-          toast.success("Stamp saved");
-          setStampOpen(false);
-        },
-        onError: () => toast.error("Failed to save stamp"),
-      },
-    );
-  };
-
   return (
     <Card>
       <CardHeader>
         <CardTitle className="flex items-center gap-2">
           <FileSignature className="size-4" />
-          Signature &amp; Stamp
+          Signature
         </CardTitle>
         <CardDescription>
-          This signature can be reused to sign booking contracts.
+          This signature can be reused to sign booking contracts. The EDR
+          company stamp is applied automatically — you do not upload one.
         </CardDescription>
       </CardHeader>
       <CardContent className="space-y-6">
@@ -112,54 +90,29 @@ export function MySignatureCard() {
             <Loader2 className="size-6 animate-spin text-primary" />
           </div>
         ) : (
-          <>
-            <div className="space-y-2">
-              {saved?.signatureImageUrl ? (
-                <>
-                  <div className="overflow-hidden rounded-lg border-2 border-dashed border-border bg-white">
-                    <img
-                      src={saved.signatureImageUrl}
-                      alt="My saved signature"
-                      className="mx-auto h-36 w-full object-contain"
-                    />
-                  </div>
-                  <p className="text-xs text-muted-foreground">
-                    Saved as {saved.signerDisplayName}
-                  </p>
-                </>
-              ) : (
-                <p className="text-sm text-muted-foreground">
-                  You have not saved a signature yet.
+          <div className="space-y-2">
+            {saved?.signatureImageUrl ? (
+              <>
+                <div className="overflow-hidden rounded-lg border-2 border-dashed border-border bg-white">
+                  <img
+                    src={saved.signatureImageUrl}
+                    alt="My saved signature"
+                    className="mx-auto h-36 w-full object-contain"
+                  />
+                </div>
+                <p className="text-xs text-muted-foreground">
+                  Saved as {saved.signerDisplayName}
                 </p>
-              )}
-              <Button variant="outline" size="sm" onClick={openSignatureDialog}>
-                {saved?.signatureImageUrl ? "Update signature" : "Add signature"}
-              </Button>
-            </div>
-
-            <div className="space-y-2">
-              {saved?.stampImageUrl ? (
-                <>
-                  <div className="overflow-hidden rounded-lg border-2 border-dashed border-border bg-white">
-                    <img
-                      src={saved.stampImageUrl}
-                      alt="My saved company stamp"
-                      className="mx-auto h-24 w-full object-contain"
-                    />
-                  </div>
-                  <p className="text-xs text-muted-foreground">Company stamp</p>
-                </>
-              ) : (
-                <p className="text-sm text-muted-foreground">
-                  You have not uploaded a company stamp yet.
-                </p>
-              )}
-              <Button variant="outline" size="sm" onClick={openStampDialog}>
-                <Stamp className="size-4" />
-                {saved?.stampImageUrl ? "Update stamp" : "Upload stamp"}
-              </Button>
-            </div>
-          </>
+              </>
+            ) : (
+              <p className="text-sm text-muted-foreground">
+                You have not saved a signature yet.
+              </p>
+            )}
+            <Button variant="outline" size="sm" onClick={openSignatureDialog}>
+              {saved?.signatureImageUrl ? "Update signature" : "Add signature"}
+            </Button>
+          </div>
         )}
       </CardContent>
 
@@ -203,39 +156,6 @@ export function MySignatureCard() {
           </DialogFooter>
         </DialogContent>
       </Dialog>
-
-      <Dialog open={stampOpen} onOpenChange={setStampOpen}>
-        <DialogContent className="sm:max-w-md">
-          <DialogHeader>
-            <DialogTitle>Company stamp</DialogTitle>
-            <DialogDescription>
-              Upload your official company stamp or seal as an image. It is
-              stored on your profile and applied next to your signature on
-              contracts.
-            </DialogDescription>
-          </DialogHeader>
-          <StampUpload
-            value={stampData}
-            onChange={setStampData}
-            description="Stored on your profile and prefilled when you sign contracts."
-          />
-          <DialogFooter>
-            <Button variant="outline" onClick={() => setStampOpen(false)}>
-              Cancel
-            </Button>
-            <Button
-              disabled={saveMutation.isPending || !stampData}
-              onClick={saveStamp}
-            >
-              {saveMutation.isPending ? (
-                <Loader2 className="size-4 animate-spin" />
-              ) : (
-                "Save stamp"
-              )}
-            </Button>
-          </DialogFooter>
-        </DialogContent>
-      </Dialog>
     </Card>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingContractPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingContractPage.tsx
index f176fc05d..e4d570da6 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingContractPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingContractPage.tsx
@@ -12,7 +12,6 @@ import toast from "react-hot-toast";
 
 import Breadcrumbs from "@/components/ui/Breadcrumbs";
 import { ContractSignaturePad } from "@/components/bookings/ContractSignaturePad";
-import { StampUpload } from "@/components/contracts/StampUpload";
 import { bookingSurface } from "@/components/bookings/booking-ui.styles";
 import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
 import { invalidateBookingDetail } from "@/utils/queryInvalidation";
@@ -41,9 +40,6 @@ export default function BookingContractPage() {
   const [signOpen, setSignOpen] = useState(false);
   const [signerName, setSignerName] = useState("");
   const [signatureData, setSignatureData] = useState<string | null>(null);
-  // Company stamp: prefilled from the profile, or uploaded here when none is
-  // saved yet.
-  const [stampData, setStampData] = useState<string | null>(null);
   // When the user has a saved signature we offer it for approval first; they
   // can switch to drawing a fresh one.
   const [drawNew, setDrawNew] = useState(false);
@@ -59,7 +55,6 @@ export default function BookingContractPage() {
 
   const savedSignature = data?.savedSignature ?? null;
   const savedSignatureImage = savedSignature?.signatureImageUrl ?? null;
-  const savedStampImage = savedSignature?.stampImageUrl ?? null;
   // Show the approval view only while a saved signature exists and the user
   // hasn't opted to draw a new one.
   const usingSaved = Boolean(savedSignatureImage) && !drawNew;
@@ -103,8 +98,6 @@ export default function BookingContractPage() {
     // approve it; otherwise start with an empty pad.
     setSignerName(savedSignature?.signerDisplayName ?? "");
     setSignatureData(null);
-    // Prefill with the reusable stamp saved on the profile; still replaceable.
-    setStampData(savedStampImage);
     setDrawNew(false);
     setSignOpen(true);
   };
@@ -113,12 +106,12 @@ export default function BookingContractPage() {
     if (!canSign || !signerName.trim()) return;
     // Approve the saved signature, or submit the freshly drawn one.
     const image = usingSaved ? savedSignatureImage : signatureData;
-    // The API rejects a STAFF signature without a stamp.
-    if (!image || !stampData) return;
+    if (!image) return;
+    // No stamp is sent: EDR's seal is the ONE global company stamp, applied
+    // server-side at render time (see StampSettingsService).
     signMutation.mutate({
       role: "STAFF",
       signatureImageBase64: image,
-      stampImageBase64: stampData,
       signerDisplayName: signerName.trim(),
       consentText: "I agree to the terms of this contract.",
     });
@@ -243,15 +236,6 @@ export default function BookingContractPage() {
               ) : (
                 <ContractSignaturePad onChange={setSignatureData} />
               )}
-              <StampUpload
-                value={stampData}
-                onChange={setStampData}
-                description={
-                  savedStampImage
-                    ? "Your saved company stamp — replace it for this contract if needed."
-                    : "Required. Attach your official company stamp or seal."
-                }
-              />
             </div>
             <DialogFooter>
               <Button variant="outline" onClick={() => setSignOpen(false)}>
@@ -261,7 +245,6 @@ export default function BookingContractPage() {
                 disabled={
                   signMutation.isPending ||
                   (!usingSaved && !signatureData) ||
-                  !stampData ||
                   !signerName.trim()
                 }
                 onClick={confirmSign}
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractViewPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractViewPage.tsx
index b49b0e25c..205413891 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractViewPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractViewPage.tsx
@@ -18,7 +18,6 @@ import toast from "react-hot-toast";
 
 import { ContractSignSuccessModal } from "@/components/contracts/ContractSignSuccessModal";
 import { ContractSignaturePad } from "@/components/bookings/ContractSignaturePad";
-import { StampUpload } from "@/components/contracts/StampUpload";
 import { contractsService } from "@/services/contracts.service";
 import { extractApiError } from "@/utils/result";
 import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
@@ -40,7 +39,6 @@ export default function ContractViewPage() {
   const [successOpen, setSuccessOpen] = useState(false);
   const [signerName, setSignerName] = useState("");
   const [signatureData, setSignatureData] = useState<string | null>(null);
-  const [stampData, setStampData] = useState<string | null>(null);
   const [drawNew, setDrawNew] = useState(false);
 
   const { data, isLoading, isError, refetch } = useQuery({
@@ -56,10 +54,11 @@ export default function ContractViewPage() {
     mutationFn: () =>
       contractsService.signContract(id!, {
         role: "STAFF",
+        // No stamp is sent: EDR's seal is the ONE global company stamp, applied
+        // server-side from StampSettingsService when the signature is stored.
         signatureImageBase64: usingSaved
           ? (savedSignatureImage as string)
           : (signatureData ?? ""),
-        stampImageBase64: stampData ?? "",
         signerDisplayName: signerName.trim(),
         consentText: "I confirm this contract on behalf of EDR.",
       }),
@@ -98,14 +97,12 @@ export default function ContractViewPage() {
   const openSign = () => {
     setSignerName(data?.savedSignature?.signerDisplayName ?? "");
     setSignatureData(null);
-    // Prefill with the reusable stamp saved on the profile; still replaceable.
-    setStampData(data?.savedSignature?.stampImageUrl ?? null);
     setDrawNew(false);
     setSignOpen(true);
   };
 
   const confirmSign = () => {
-    if (!signerName.trim() || !stampData) return;
+    if (!signerName.trim()) return;
     const image = usingSaved ? savedSignatureImage : signatureData;
     if (!image) return;
     signMutation.mutate();
@@ -243,13 +240,6 @@ export default function ContractViewPage() {
             <ContractSignaturePad onChange={setSignatureData} />
           )}
 
-          <StampUpload
-            value={stampData}
-            onChange={setStampData}
-            label="EDR company stamp"
-            description="Attach the official EDR stamp or seal — it is applied to the contract next to the signature."
-          />
-
           <Group justify="flex-end" gap="sm">
             <Button variant="default" onClick={() => setSignOpen(false)}>
               Cancel
@@ -260,8 +250,7 @@ export default function ContractViewPage() {
               disabled={
                 signMutation.isPending ||
                 !signerName.trim() ||
-                (!usingSaved && !signatureData) ||
-                !stampData
+                (!usingSaved && !signatureData)
               }
               onClick={confirmSign}
             >
diff --git a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
index c1ce4e67d..260ed225f 100644
--- a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
@@ -111,11 +111,14 @@ export interface ConsolidationDetails {
   splitBilling: { bookingShare: number; partnerShare: number } | null;
 }
 
+/**
+ * No stamp field: the backoffice only ever signs as STAFF, and EDR's seal is
+ * the ONE global company stamp applied server-side. Customer stamps are posted
+ * from the portal, not here.
+ */
 export interface SignContractPayload {
   role: "CUSTOMER" | "STAFF";
   signatureImageBase64: string;
-  /** Company stamp/seal image; the API requires one for CUSTOMER and STAFF. */
-  stampImageBase64?: string;
   signerDisplayName: string;
   consentText?: string;
 }
diff --git a/apps/edr-freight-web/backoffice/src/services/contracts.service.ts b/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
index 37971cb96..a22fe0fe6 100644
--- a/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
@@ -118,11 +118,14 @@ export interface ContractView {
   } | null;
 }
 
+/**
+ * No stamp field: the backoffice only ever counter-signs as STAFF, and EDR's
+ * seal is the ONE global company stamp, snapshotted server-side from
+ * StampSettingsService when the signature is stored.
+ */
 export interface SignContractPayload {
   role: "CUSTOMER" | "STAFF";
   signatureImageBase64: string;
-  /** Company stamp/seal image; required to sign a contract. */
-  stampImageBase64?: string;
   signerDisplayName: string;
   consentText?: string;
 }
diff --git a/apps/edr-freight-web/backoffice/src/services/signatures.service.ts b/apps/edr-freight-web/backoffice/src/services/signatures.service.ts
index 6a71c1836..d0a2dfe17 100644
--- a/apps/edr-freight-web/backoffice/src/services/signatures.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/signatures.service.ts
@@ -9,12 +9,16 @@ export interface SavedSignature {
   stampImageUrl?: string | null;
 }
 
+/**
+ * Signature only. A backoffice employee has no personal stamp — EDR seals with
+ * the one global company stamp managed under Settings — so the stamp half of
+ * PUT /me/signature is deliberately not exposed here, even though the shared
+ * endpoint still accepts it for portal (customer) users.
+ */
 export interface SaveSignaturePayload {
   signerDisplayName: string;
-  /** Omit to keep the existing saved signature (stamp-only update). */
+  /** Omit to keep the existing saved signature. */
   signatureImageBase64?: string;
-  /** Omit to keep the existing saved stamp. */
-  stampImageBase64?: string;
 }
 
 export const signaturesService = {

From 5da36eb128dd3251ed1dd03b68d2554675adb239 Mon Sep 17 00:00:00 2001
From: marshalyordanos <marshalyordanosseifu@gmail.com>
Date: Wed, 12 Aug 2026 09:36:50 +0300
Subject: [PATCH 028/174] feat: add wagon usage computation and maintenance
 logging features

- Implemented  utility to calculate wagon usage metrics for train schedules.
- Created  for sending wagons to maintenance with optional notes.
- Added unit tests for train builder maintenance functionalities, including formatting train run labels and building maintenance notes.
- Developed  component for merging train schedules with detailed previews and reasons for merging.
- Introduced  component for selecting wagons with search functionality and selection limits.
- Created  for displaying and filtering audit logs, including detailed views of individual log entries.
- Added  for handling API interactions related to audit logs, including fetching logs and entity types.
---
 apps/edr-freight-api/data/audit-endpoints.js  | 639 +++++++++++++++++
 .../src/common/booking-guards.ts              |   4 +
 .../3390000000000-CreateAuditLogs.ts          |  81 +++
 ...00000000-TransferRequestPreferredWagons.ts |  29 +
 .../3410000000000-ScheduleVoyageNumber.ts     |  28 +
 .../src/modules/audit/audit-actor.ts          |  84 +++
 .../modules/audit/audit-endpoint-matcher.ts   | 140 ++++
 .../src/modules/audit/audit-endpoints.ts      | 641 ++++++++++++++++++
 .../src/modules/audit/audit-log.repository.ts |  79 +++
 .../src/modules/audit/audit.controller.ts     |  46 ++
 .../src/modules/audit/audit.interceptor.ts    | 189 ++++++
 .../src/modules/audit/audit.module.ts         |  34 +
 .../src/modules/audit/audit.sanitizer.ts      | 195 ++++++
 .../src/modules/audit/audit.service.ts        |  71 ++
 .../modules/audit/dto/audit-log-query.dto.ts  |  64 ++
 .../audit/entities/audit-log.entity.ts        | 132 ++++
 .../modules/bookings/bookings.controller.ts   |  12 +-
 .../src/modules/bookings/bookings.service.ts  |  35 +-
 .../booking-clearance.service.spec.ts         |   2 +-
 .../contracts/booking-clearance.service.ts    |  26 +-
 .../contracts/contract-clearance.service.ts   |  26 +-
 .../modules/contracts/contracts.controller.ts |  16 +-
 .../contracts/phased-clearance.util.ts        | 128 ++++
 .../entities/train-schedule.entity.ts         |   8 +
 .../train-scheduling.controller.ts            |  44 ++
 .../dto/merge-schedule-train.dto.ts           |  23 +
 .../dto/update-schedule-train-number.dto.ts   |  40 ++
 .../train-scheduling/schedule-merge.spec.ts   | 399 +++++++++++
 .../schedule-train-number.spec.ts             | 114 ++++
 .../services/train-scheduling.service.ts      | 468 ++++++++++++-
 .../utils/schedule-wagon-usage.util.spec.ts   |  96 +++
 .../utils/schedule-wagon-usage.util.ts        |  58 ++
 .../src/modules/trains/dto/build-train.dto.ts |   4 +-
 .../dto/send-wagon-to-maintenance.dto.ts      |  15 +
 .../trains/train-builder.controller.ts        |   9 +-
 .../trains/train-builder.maintenance.spec.ts  |  83 +++
 .../modules/trains/train-builder.service.ts   |  70 +-
 .../wagons/dto/create-transfer-request.dto.ts |  26 +-
 .../entities/wagon-transfer-request.entity.ts |   8 +
 .../wagon-transfer-requests.service.spec.ts   |  91 +++
 .../wagons/wagon-transfer-requests.service.ts | 124 +++-
 .../src/seed/edr-freight.seed.ts              |  19 +
 .../src/seed/freight-permissions.registry.ts  |  15 +
 .../src/seed/freight-positions.seeder.ts      |  87 ++-
 apps/edr-freight-web/backoffice/src/App.tsx   |   2 +
 .../detail/BookingSchedulingWindowCard.tsx    |  34 +-
 .../contracts/ExportClearanceStepper.tsx      |  19 +-
 .../contracts/GlClearanceUploadModal.tsx      |  41 +-
 .../contracts/PhasedClearanceActionPanel.tsx  | 117 ++--
 .../components/layout/sidebar-sections.tsx    |   7 +
 .../trainBuilder/BuildTrainModal.tsx          |   6 +-
 .../trainScheduling/EligibleBookingsPanel.tsx |  17 +-
 .../MergeScheduleTrainModal.tsx               | 344 ++++++++++
 .../trainScheduling/ScheduleBookingsStep.tsx  |  36 +-
 .../src/components/wagons/WagonPicker.tsx     | 209 ++++++
 .../wagons/WagonYardWorkspaceModal.tsx        | 107 ++-
 .../backoffice/src/constants/URLS.ts          |   7 +
 .../backoffice/src/lib/permissions.ts         |   8 +
 .../backoffice/src/pages/AuditLogsPage.tsx    | 340 ++++++++++
 .../bookings/BookingRequestDetailPage.tsx     |   6 +-
 .../trainBuilder/TrainBuilderDetailPage.tsx   |  42 +-
 .../TrainScheduleV2DetailPage.tsx             |  43 +-
 .../TrainScheduleV2ListPage.tsx               | 133 +++-
 .../src/pages/wagons/TransferFulfillModal.tsx | 108 ++-
 .../pages/wagons/TransferRequestModals.tsx    |  75 +-
 .../src/pages/wagons/WagonTransfersPage.tsx   |  17 +
 .../src/pages/wagons/wagon-transfer-ui.tsx    |  59 ++
 .../backoffice/src/services/api.ts            |  40 +-
 .../src/services/auditLogs.service.ts         |  97 +++
 .../src/services/bookings.service.ts          |   8 +-
 .../src/services/contracts.service.ts         |   8 +-
 .../src/services/trainBuilder.service.ts      |   7 +-
 .../src/services/trainScheduling.service.ts   |  24 +
 .../backoffice/src/services/wagon.service.ts  |   6 +
 .../backoffice/src/types/booking.ts           |   6 +
 .../backoffice/src/types/trainScheduling.ts   |  54 ++
 .../src/freight/clearance-files.catalog.ts    |  42 ++
 77 files changed, 6275 insertions(+), 296 deletions(-)
 create mode 100644 apps/edr-freight-api/data/audit-endpoints.js
 create mode 100644 apps/edr-freight-api/src/migrations/3390000000000-CreateAuditLogs.ts
 create mode 100644 apps/edr-freight-api/src/migrations/3400000000000-TransferRequestPreferredWagons.ts
 create mode 100644 apps/edr-freight-api/src/migrations/3410000000000-ScheduleVoyageNumber.ts
 create mode 100644 apps/edr-freight-api/src/modules/audit/audit-actor.ts
 create mode 100644 apps/edr-freight-api/src/modules/audit/audit-endpoint-matcher.ts
 create mode 100644 apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
 create mode 100644 apps/edr-freight-api/src/modules/audit/audit-log.repository.ts
 create mode 100644 apps/edr-freight-api/src/modules/audit/audit.controller.ts
 create mode 100644 apps/edr-freight-api/src/modules/audit/audit.interceptor.ts
 create mode 100644 apps/edr-freight-api/src/modules/audit/audit.module.ts
 create mode 100644 apps/edr-freight-api/src/modules/audit/audit.sanitizer.ts
 create mode 100644 apps/edr-freight-api/src/modules/audit/audit.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/audit/dto/audit-log-query.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/audit/entities/audit-log.entity.ts
 create mode 100644 apps/edr-freight-api/src/modules/train-scheduling/dto/merge-schedule-train.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/train-scheduling/dto/update-schedule-train-number.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/train-scheduling/schedule-merge.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/train-scheduling/schedule-train-number.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.ts
 create mode 100644 apps/edr-freight-api/src/modules/trains/dto/send-wagon-to-maintenance.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/trains/train-builder.maintenance.spec.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/trainScheduling/MergeScheduleTrainModal.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/wagons/WagonPicker.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/AuditLogsPage.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/services/auditLogs.service.ts

diff --git a/apps/edr-freight-api/data/audit-endpoints.js b/apps/edr-freight-api/data/audit-endpoints.js
new file mode 100644
index 000000000..2c11ea95b
--- /dev/null
+++ b/apps/edr-freight-api/data/audit-endpoints.js
@@ -0,0 +1,639 @@
+/**
+ * Freight API — every state-changing endpoint (POST / PUT / PATCH / DELETE).
+ *
+ * Shape:  "<METHOD> <path>": [title, method, entity]
+ *
+ * Keyed by method + path rather than path alone: 50 paths serve more than one
+ * method (PATCH and DELETE on /api/contracts/:id, for example), so a path-only
+ * key would collide and drop those endpoints.
+ *
+ * Paths include the global prefix `api` (see app.setGlobalPrefix in src/main.ts).
+ * Titles come from each route's @ApiOperation summary, falling back to a
+ * humanized handler name where a route has none.
+ *
+ * Excludes the AI Assist and Account entities.
+ * Generated from the controllers under src/ — 488 endpoints.
+ */
+const AUDIT_ENDPOINTS = {
+  // Approval Rule
+  "POST /api/approval-rules": ["Create an approval rule step", "POST", "Approval Rule"],
+  "PATCH /api/approval-rules/:id": ["Update an approval rule", "PATCH", "Approval Rule"],
+  "DELETE /api/approval-rules/:id": ["Soft-delete an approval rule", "DELETE", "Approval Rule"],
+  "POST /api/approval-rules/:id/move-order": ["Move an approval step up or down within its chain", "POST", "Approval Rule"],
+  "POST /api/approval-rules/reorder": ["Bulk reorder approval steps within a chain", "POST", "Approval Rule"],
+
+  // Booking
+  "POST /api/bookings": ["Create a new freight booking (DRAFT)", "POST", "Booking"],
+  "POST /api/bookings/:bookingId/allocate-containers": ["Allocate containers to vehicles", "POST", "Booking"],
+  "PATCH /api/bookings/:id": ["Update booking", "PATCH", "Booking"],
+  "DELETE /api/bookings/:id": ["Soft-delete DRAFT booking", "DELETE", "Booking"],
+  "POST /api/bookings/:id/cancel": ["Cancel booking", "POST", "Booking"],
+  "POST /api/bookings/:id/cancel-hold": ["Customer cancels an unpaid hold (SELECTED_FOR_BATCH → CANCELLED);", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/declaration": ["GL ET uploads customs declaration on booking (GENERAL customs)", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/delivery-order": ["Upload Booking Delivery Order", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/documents": ["Customer uploads clearance documents (fieldname = document key)", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/draft-declaration": ["GL ET sends a draft customs declaration (multi-file) with an estimated price for the customer to review", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/draft-declaration/accept": ["Customer accepts the draft customs declaration — unlocks the real customs declaration step for GL Ethiopia", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/draft-declaration/change": ["Customer requests a change to the draft customs declaration with a reason — GL Ethiopia sends a corrected draft (repeatable)", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/duty": ["GL ET sets duty/tax on booking with notice attachment", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/duty-slip": ["Customer uploads duty/tax payment slip on booking", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/export-release": ["Confirm Booking Export Release", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/finalize": ["GL finalizes clearance (requires 100% approved) → CLEARANCE_READY", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/finalize-pre-clearance": ["GL ET finalizes import pre-clearance on booking", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/output-documents": ["GL uploads customs output documents (IM4/EX3/…)", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/proceed": ["Customer requests operation with a schedule day", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/release-order": ["Upload Booking Release Order", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/review": ["GL reviews a clearance document (Approve | Query)", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/ro-amendment": ["Request Booking RO Amendment", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/transit-assignee/assign": ["GL Djibouti picks the transit officer from the roster — unblocks the customs declaration; calling again reassigns", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/transit-assignee/request": ["GL ET asks GL Djibouti to name the transit officer — required before the import customs declaration", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/transit-permit": ["Upload Booking Transit Permit", "POST", "Booking"],
+  "POST /api/bookings/:id/confirm-submit": ["Confirm submit after price change", "POST", "Booking"],
+  "POST /api/bookings/:id/consolidation": ["Request freight consolidation", "POST", "Booking"],
+  "DELETE /api/bookings/:id/consolidation": ["Remove consolidation pairing", "DELETE", "Booking"],
+  "POST /api/bookings/:id/contract/generate": ["Generate contract PDF from template", "POST", "Booking"],
+  "POST /api/bookings/:id/contract/sign": ["Apply digital signature (customer or staff)", "POST", "Booking"],
+  "POST /api/bookings/:id/customer-cancel": ["Customer cancels their own booking before payment — no cancellation fee", "POST", "Booking"],
+  "POST /api/bookings/:id/customer-truck-assignment": ["Customer assigns external truck and driver for terminal pickup", "POST", "Booking"],
+  "POST /api/bookings/:id/customer-trucks": ["Add a customer self-haul truck carrying 1–2 of the booking containers", "POST", "Booking"],
+  "PATCH /api/bookings/:id/customer-trucks/:assignmentId": ["Edit a not-yet-arrived customer truck (plate/driver/type + containers)", "PATCH", "Booking"],
+  "DELETE /api/bookings/:id/customer-trucks/:assignmentId": ["Remove a not-yet-arrived customer truck from a booking", "DELETE", "Booking"],
+  "POST /api/bookings/:id/customer-trucks/:assignmentId/depart": ["Register an import truck leaving: containers loaded + weighed gross (staff)", "POST", "Booking"],
+  "POST /api/bookings/:id/customer-trucks/:assignmentId/load": ["Truck_dispatch: load selected containers onto a truck (staff)", "POST", "Booking"],
+  "POST /api/bookings/:id/customer-trucks/bulk": ["Bulk add customer trucks from array payload (Excel parsed)", "POST", "Booking"],
+  "POST /api/bookings/:id/customer/sign": ["Customer digital signature (deprecated — use POST contract/sign)", "POST", "Booking"],
+  "POST /api/bookings/:id/documents": ["Upload documents for a booking (DRAFT only)", "POST", "Booking"],
+  "PATCH /api/bookings/:id/export-handover-mode": ["Export only: choose direct truck-to-train (no warehouse, no GRN) or warehouse first", "PATCH", "Booking"],
+  "POST /api/bookings/:id/generate-grn": ["Generate a GRN over the received containers (all received, or a subset) — one GRN per batch", "POST", "Booking"],
+  "POST /api/bookings/:id/generate-price": ["Generate price preview (DRAFT or CHANGES_REQUESTED)", "POST", "Booking"],
+  "POST /api/bookings/:id/government-expedite": ["Expedite government booking to PAID / ELIGIBLE for scheduling", "POST", "Booking"],
+  "POST /api/bookings/:id/marketing/approve": ["Staff contract signature and fully execute (use contract/sign STAFF preferred)", "POST", "Booking"],
+  "POST /api/bookings/:id/operation/review": ["Operations reviews an operation request: ACCEPT (→ batch pool),", "POST", "Booking"],
+  "POST /api/bookings/:id/operations/complete": ["Mark completed", "POST", "Booking"],
+  "POST /api/bookings/:id/operations/start-transit": ["Mark in transit", "POST", "Booking"],
+  "POST /api/bookings/:id/reject": ["Customer reject price estimate", "POST", "Booking"],
+  "POST /api/bookings/:id/staff/accept": ["Staff accept intake → set contract validity window + start approval chain", "POST", "Booking"],
+  "POST /api/bookings/:id/staff/reject": ["Staff final reject", "POST", "Booking"],
+  "POST /api/bookings/:id/staff/request-changes": ["Staff return booking for customer updates", "POST", "Booking"],
+  "POST /api/bookings/:id/submit": ["Customer submit booking", "POST", "Booking"],
+  "POST /api/bookings/:id/wagon-cancellations": ["Request a partial wagon cancellation on a PAID booking — opens the cancellation-fee invoice; wagons are released only once the fee settles", "POST", "Booking"],
+  "POST /api/bookings/:id/wagon-cancellations/preview": ["Preview the fee/credit of a partial wagon cancellation (no writes)", "POST", "Booking"],
+  "POST /api/bookings/wagon-cancellations/:cancellationId/rebook": ["Rebook a wagon-cancellation credit: pick a shipment day only — the new booking is created under the contract and marked PAID (freight already paid; contract must still be valid)", "POST", "Booking"],
+  "POST /api/bookings/wagon-cancellations/:cancellationId/withdraw": ["Withdraw a fee-pending wagon cancellation (owner, or staff with the void permission)", "POST", "Booking"],
+
+  // Cargo
+  "POST /api/cargoes": ["Create a new cargo", "POST", "Cargo"],
+  "PATCH /api/cargoes/:id": ["Update a cargo", "PATCH", "Cargo"],
+  "DELETE /api/cargoes/:id": ["Delete a cargo", "DELETE", "Cargo"],
+  "POST /api/cargoes/:id/deliver": ["Mark cargo as delivered", "POST", "Cargo"],
+  "POST /api/cargoes/:id/load": ["Load cargo into a container", "POST", "Cargo"],
+  "POST /api/cargoes/:id/unload": ["Unload cargo from container", "POST", "Cargo"],
+
+  // Cargo Type
+  "POST /api/cargo-types": ["Create a cargo type", "POST", "Cargo Type"],
+  "PATCH /api/cargo-types/:id": ["Update a cargo type", "PATCH", "Cargo Type"],
+  "DELETE /api/cargo-types/:id": ["Soft-delete a cargo type", "DELETE", "Cargo Type"],
+  "POST /api/cargo-types/:id/move-order": ["Move a cargo type up or down in display order", "POST", "Cargo Type"],
+  "POST /api/cargo-types/reorder": ["Bulk reorder cargo types by ID list", "POST", "Cargo Type"],
+
+  // Company
+  "POST /api/companies": ["Create a new company (customer, freight_forwarder, dj_freight_forwarder, transporter)", "POST", "Company"],
+  "POST /api/companies/:companyId/documents": ["Upload documents for a company (onboarding)", "POST", "Company"],
+  "POST /api/companies/:companyId/profiles": ["Add a profile (employee) to a company", "POST", "Company"],
+  "PATCH /api/companies/:id": ["Update a company", "PATCH", "Company"],
+  "DELETE /api/companies/:id": ["Soft-delete a company", "DELETE", "Company"],
+  "POST /api/companies/change-requests/:id/approve": ["Approve a pending profile change request (applies the changes)", "POST", "Company"],
+  "POST /api/companies/change-requests/:id/reject": ["Reject a pending profile change request with a note", "POST", "Company"],
+  "POST /api/companies/change-requests/:id/request-changes": ["Ask for specific changes on a pending request without rejecting it (row stays open, next edit appends to it)", "POST", "Company"],
+  "POST /api/companies/company-profile": ["Create a single operational profile for the current user's company. The role starts pending and does not become the active mode", "POST", "Company"],
+  "POST /api/companies/company-profiles": ["Add operational profile(s) (importer/exporter/forwarder) to the current user's company", "POST", "Company"],
+  "POST /api/companies/company-profiles/:profileId/license": ["Add business-license document(s) to a profile. For an approved company", "POST", "Company"],
+  "DELETE /api/companies/company-profiles/:profileId/license/:fileId": ["Remove a business-license file (staged for review on an approved company)", "DELETE", "Company"],
+  "POST /api/companies/company-profiles/:profileId/license/:fileId/replace": ["Replace a business-license file with a newly uploaded one (staged for", "POST", "Company"],
+  "POST /api/companies/company-profiles/:profileId/reapply": ["Resubmit a rejected operational role for approval (→ pending)", "POST", "Company"],
+  "PATCH /api/companies/company-profiles/:profileId/status": ["Update a company profile's approval status", "PATCH", "Company"],
+  "POST /api/companies/create": ["Create a company with its associated external profile (onboarding)", "POST", "Company"],
+  "POST /api/companies/documents/:fileId/request-change": ["Ask the customer to correct one uploaded document", "POST", "Company"],
+  "POST /api/companies/fetch-etrade-info": ["Fetch company info from eTrade by TIN", "POST", "Company"],
+  "POST /api/companies/identity/fayda/complete": ["Bind a completed Fayda verification to the company's owner or Power of Attorney", "POST", "Company"],
+  "DELETE /api/companies/identity/fayda/poa": ["Remove the company's Power of Attorney — the verified identity, its details and the delegation paper together", "DELETE", "Company"],
+  "DELETE /api/companies/identity/gm": ["Clear the General Manager's identity — the \\\"same as owner\\\" declaration or a verification, and the details either wrote", "DELETE", "Company"],
+  "POST /api/companies/identity/gm/same-as-owner": ["Declare the General Manager is the company's owner, copying the owner's verified identity across", "POST", "Company"],
+  "POST /api/companies/identity/poa/same-as-owner": ["Declare the Power of Attorney is the company's owner, copying the owner's identity across", "POST", "Company"],
+  "DELETE /api/companies/identity/poa/same-as-owner": ["Undo the Power of Attorney \\\"same as owner\\\" declaration and the identity it copied, leaving the representative open to be verified in their own right", "DELETE", "Company"],
+  "PATCH /api/companies/onboarding-step": ["Persist the user's current onboarding wizard step", "PATCH", "Company"],
+  "POST /api/companies/onboarding/complete": ["Mark the current user's onboarding as complete", "POST", "Company"],
+  "POST /api/companies/onboarding/start": ["Begin onboarding: create a draft company + profile + role(s) so later steps can save incrementally", "POST", "Company"],
+  "POST /api/companies/poa-delegation": ["Upload the Power of Attorney delegation letter, replacing any existing one", "POST", "Company"],
+  "DELETE /api/companies/poa-delegation/:fileId": ["Remove the Power of Attorney delegation letter (staged for review on an approved company)", "DELETE", "Company"],
+  "PATCH /api/companies/profile": ["Update profile (flattened settings page)", "PATCH", "Company"],
+
+  // Compliance
+  "POST /api/compliance": ["Create a compliance record", "POST", "Compliance"],
+  "PATCH /api/compliance/:id": ["Update a compliance record", "PATCH", "Compliance"],
+  "DELETE /api/compliance/:id": ["Soft-delete a compliance record", "DELETE", "Compliance"],
+
+  // Consignment
+  "POST /api/consignments": ["Create a new consignment", "POST", "Consignment"],
+
+  // Container
+  "POST /api/containers": ["Create a new container", "POST", "Container"],
+  "PATCH /api/containers/:id": ["Update a container", "PATCH", "Container"],
+  "DELETE /api/containers/:id": ["Delete a container", "DELETE", "Container"],
+  "POST /api/containers/:id/assign-wagon": ["Assign container to a wagon", "POST", "Container"],
+  "POST /api/containers/:id/unassign-wagon": ["Unassign container from wagon", "POST", "Container"],
+
+  // Container Type
+  "POST /api/container-types": ["Create a container type", "POST", "Container Type"],
+  "PATCH /api/container-types/:id": ["Update a container type", "PATCH", "Container Type"],
+  "DELETE /api/container-types/:id": ["Soft-delete a container type", "DELETE", "Container Type"],
+  "POST /api/container-types/:id/move-order": ["Move a container type up or down in display order", "POST", "Container Type"],
+  "POST /api/container-types/reorder": ["Bulk reorder container types by ID list", "POST", "Container Type"],
+
+  // Contract
+  "POST /api/contracts": ["Create a new contract (DRAFT) with routes + cargo scope", "POST", "Contract"],
+  "PATCH /api/contracts/:id": ["Update contract", "PATCH", "Contract"],
+  "DELETE /api/contracts/:id": ["Soft-delete DRAFT contract", "DELETE", "Contract"],
+  "POST /api/contracts/:id/approval-steps/:stepId/approve": ["Approve one approval step in sequence", "POST", "Contract"],
+  "POST /api/contracts/:id/approval-steps/:stepId/reject": ["Reject one approval step — to the customer (terminal → REJECTED) or, via returnToStepId, back to an earlier approver (chain re-runs from there)", "POST", "Contract"],
+  "POST /api/contracts/:id/booking-requests": ["Customer submits a shipment request on a GENERAL customs contract", "POST", "Contract"],
+  "POST /api/contracts/:id/bookings": ["Create a shipment booking under a contract — Path A (customer) or Path B (GL Ethiopia)", "POST", "Contract"],
+  "POST /api/contracts/:id/bookings/:bookingId/complete": ["Complete an initiated booking after Operations finalized its clearance — cargo + binding day, window and departure checks, pricing and invoicing", "POST", "Contract"],
+  "POST /api/contracts/:id/bookings/initiate": ["Initiate a bare booking instance under an import/export contract (ONE_TIME or GENERAL) — no cargo, no date; enters per-booking clearance (AWAITING_DOCUMENTS). ONE_TIME customs instances are opened by the customer (or GL); GENERAL customs comes from a shipment request", "POST", "Contract"],
+  "POST /api/contracts/:id/cancel": ["Customer cancels their own contract (blocked while a booking is live)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/declaration": ["GL ET uploads customs declaration documents (multi-file)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/delivery-order": ["GL DJ uploads Delivery Order (import) with vessel arrival + DO collected dates", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/documents": ["Customer uploads clearance documents (fieldname = document key)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/documents/:fileKey/replace": ["GL replaces a clearance document in place (reason required) — the previous version is kept in the file history and the new one needs approving", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/duty": ["GL ET sets duty/tax requirement and advises amount with notice attachment", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/duty-slip": ["Customer uploads duty/tax payment slip on contract", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/duty/dispute": ["Customer disputes the advised duty/tax with a reason — reopens the step so GL Ethiopia can re-advise (repeatable)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/export-release": ["GL ET confirms export release after declaration", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/finalize": ["GL ET finalizes clearance → CLEARANCE_READY_FOR_BOOKING (legacy)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/finalize-export-clearance": ["GL ET finalizes export clearance after post-booking transit permit upload", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/finalize-pre-clearance": ["GL ET finalizes import pre-clearance — unlocks Djibouti DO upload", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/ops-finalize": ["Operations finalizes self-clearance → customer may create the booking", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/ops-review": ["Operations reviews a customer self-clearance document (Approve | Query)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/output-documents": ["GL uploads customs output documents (IM4/EX3/…) pre-booking", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/release-order": ["GL DJ uploads Release Order + vessel departure date (export)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/review": ["GL ET reviews a clearance document (Approve | Query)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/ro-amendment": ["GL DJ requests port amendment when RO vessel window is too short", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/transit-assignee/assign": ["GL Djibouti picks the transit officer from the roster — unblocks the customs declaration; calling again reassigns", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/transit-assignee/request": ["GL ET asks GL Djibouti to name the transit officer — required before the customs declaration", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/transit-permit": ["GL ET uploads import transit permit documents (multi-file)", "POST", "Contract"],
+  "POST /api/contracts/:id/confirm-submit": ["Confirm submit after a price change", "POST", "Contract"],
+  "POST /api/contracts/:id/contract/generate": ["Generate contract document → CONTRACT_READY", "POST", "Contract"],
+  "POST /api/contracts/:id/contract/send-signing-otp": ["Send the sudo-mode signing OTP to the contract company's registered phone (server picks the number)", "POST", "Contract"],
+  "POST /api/contracts/:id/contract/sign": ["Apply digital signature (customer or staff/director/ceo)", "POST", "Contract"],
+  "PUT /api/contracts/:id/document/articles": ["Edit this contract\\'s document articles only (per-contract; never touches the six shared templates)", "PUT", "Contract"],
+  "POST /api/contracts/:id/documents": ["Upload intake documents for a contract (DRAFT only)", "POST", "Contract"],
+  "POST /api/contracts/:id/generate-price": ["Generate unit-rate breakdown (no totals at contract phase)", "POST", "Contract"],
+  "POST /api/contracts/:id/milestones/:code/complete": ["GL marks a pre-booking (contract) milestone complete", "POST", "Contract"],
+  "POST /api/contracts/:id/renew": ["Create a renewal draft linked via renewalOfId", "POST", "Contract"],
+  "POST /api/contracts/:id/resume": ["Staff lift a suspension — contract returns to its prior status", "POST", "Contract"],
+  "POST /api/contracts/:id/staff/accept": ["Staff accept → set validity window + start approval chain", "POST", "Contract"],
+  "POST /api/contracts/:id/staff/reject": ["Staff reject contract", "POST", "Contract"],
+  "POST /api/contracts/:id/staff/request-changes": ["Staff return contract for customer updates", "POST", "Contract"],
+  "POST /api/contracts/:id/submit": ["Customer submit contract (freezes contract_rate_snapshots)", "POST", "Contract"],
+  "POST /api/contracts/:id/suspend": ["Staff freeze a signed contract (reversible, any post-signature step)", "POST", "Contract"],
+  "POST /api/contracts/:id/validate-shipment": ["Pre-create validation + authoritative price preview: full booking price breakdown (rail, first/last mile, surcharges), overweight lines and 20ft weight-pairing errors for a shipment payload (no booking created)", "POST", "Contract"],
+  "POST /api/contracts/booking-requests/:reqId/accept": ["GL marks a shipment request accepted + links the created booking", "POST", "Contract"],
+  "POST /api/contracts/booking-requests/:reqId/cancel": ["Customer cancels their own pending shipment request", "POST", "Contract"],
+  "POST /api/contracts/booking-requests/:reqId/reject": ["GL rejects a shipment request", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/documents": ["GL uploads post-booking operational documents (DO/RO/T1/…)", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/duty": ["GL ET advises duty & tax amount + declaration serial", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/duty-slip": ["Customer uploads the duty/tax payment slip", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/final-invoice": ["GL DJ raises the post-offload final invoice (amount + invoice document)", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/final-invoice-slip": ["Customer attaches the payment slip for the final invoice", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/final-invoice/approve": ["Customer approves the drafted final invoice — unlocks the payment slip", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/final-invoice/confirm": ["GL (ET or DJ) confirms the payment slip — settles the final invoice", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/incidents": ["GL DJ logs a cargo exception with photo evidence", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/milestones/:code/complete": ["GL / Ops / Terminal marks a post-booking milestone complete", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/risk": ["GL ET assigns a customs risk level (GREEN/YELLOW/RED)", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/second-duty": ["GL ET advises (or skips) the post-arrival additional duty/tax round (import)", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/second-duty-slip": ["Customer attaches the additional duty/tax payment slip", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/station-assign": ["GL station manager routes the shipment + binds staff", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/t1-close": ["Close (accept) the T1 set — GL ET after arrival (import) / GL DJ after gate pass (export)", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/t1-documents": ["GL Djibouti uploads T1 transit documents (multi-file) after wagon allocation; locked once the train departs", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/transport-document": ["GL ET uploads export transit permit documents (multi-file)", "POST", "Contract"],
+  "POST /api/gl-exchange/:entityId": ["Share a document with the other GL desk", "POST", "Contract"],
+  "PATCH /api/gl-exchange/documents/:documentId": ["Uploader edits a shared document (title, visibility, file)", "PATCH", "Contract"],
+  "DELETE /api/gl-exchange/documents/:documentId": ["Uploader removes a shared document", "DELETE", "Contract"],
+
+  // Contract Template
+  "POST /api/contract-templates": ["Create a bulk contract template for a (cargo type, customs option) pair", "POST", "Contract Template"],
+  "PATCH /api/contract-templates/:code": ["Update template metadata (name, title, recitals, active flag)", "PATCH", "Contract Template"],
+  "DELETE /api/contract-templates/:code": ["Delete a staff-created bulk template (system templates refuse)", "DELETE", "Contract Template"],
+  "POST /api/contract-templates/:code/articles": ["Add an article to the template", "POST", "Contract Template"],
+  "PUT /api/contract-templates/:code/articles": ["Replace the full ordered article list (used for reorder)", "PUT", "Contract Template"],
+  "PATCH /api/contract-templates/:code/articles/:articleId": ["Update an article's title or body", "PATCH", "Contract Template"],
+  "DELETE /api/contract-templates/:code/articles/:articleId": ["Remove an article from the template", "DELETE", "Contract Template"],
+  "POST /api/contract-templates/:code/preview": ["Render an HTML preview of the template against mock contract data", "POST", "Contract Template"],
+
+  // Driver
+  "POST /api/drivers": ["Create a new driver", "POST", "Driver"],
+  "PATCH /api/drivers/:id": ["Update a driver", "PATCH", "Driver"],
+  "DELETE /api/drivers/:id": ["Delete a driver", "DELETE", "Driver"],
+  "POST /api/drivers/:id/documents": ["Upload driver documents (code driver_docs)", "POST", "Driver"],
+  "DELETE /api/drivers/:id/documents/:fileId": ["Delete a driver document", "DELETE", "Driver"],
+
+  // Dropdown Setting
+  "POST /api/dropdown-settings": ["Create a new dropdown setting", "POST", "Dropdown Setting"],
+  "PATCH /api/dropdown-settings/:id": ["Update a dropdown setting's metadata", "PATCH", "Dropdown Setting"],
+  "DELETE /api/dropdown-settings/:id": ["Soft-delete a dropdown setting", "DELETE", "Dropdown Setting"],
+  "POST /api/dropdown-settings/:id/options": ["Append a single option to a setting", "POST", "Dropdown Setting"],
+  "PUT /api/dropdown-settings/:id/options": ["Replace the full option list for a setting", "PUT", "Dropdown Setting"],
+  "PATCH /api/dropdown-settings/options/:optionId": ["Update a single option", "PATCH", "Dropdown Setting"],
+  "DELETE /api/dropdown-settings/options/:optionId": ["Soft-delete a single option", "DELETE", "Dropdown Setting"],
+
+  // EIMS Invoice
+  "POST /api/invoices/:id/eims/register": ["Register the invoice with MoR EIMS. Idempotent — an invoice that already has an IRN is returned unchanged", "POST", "EIMS Invoice"],
+  "POST /api/invoices/:id/eims/resolve": ["Resolve an unacknowledged submission: record the IRN confirmed with MoR, or discard it. Clears the system-wide block", "POST", "EIMS Invoice"],
+  "POST /api/invoices/:id/eims/verify": ["Verify the invoice's stored IRN against EIMS", "POST", "EIMS Invoice"],
+
+  // Exchange Setting
+  "PATCH /api/exchange-settings": ["Set the USD→ETB fallback by hand (used only while CBE is unreachable)", "PATCH", "Exchange Setting"],
+
+  // Facility
+  "POST /api/facilities": ["Create a new facility", "POST", "Facility"],
+  "PATCH /api/facilities/:id": ["Update a facility", "PATCH", "Facility"],
+  "DELETE /api/facilities/:id": ["Delete a facility (soft delete)", "DELETE", "Facility"],
+
+  // Fayda Verification
+  "POST /api/fayda/verification/start": ["Start a VeriFayda 2.0 verification session", "POST", "Fayda Verification"],
+
+  // File Upload Setting
+  "POST /api/file-upload-settings": ["Create a new file upload setting", "POST", "File Upload Setting"],
+  "PATCH /api/file-upload-settings/:id": ["Update a file upload setting's metadata", "PATCH", "File Upload Setting"],
+  "DELETE /api/file-upload-settings/:id": ["Soft-delete a file upload setting", "DELETE", "File Upload Setting"],
+  "POST /api/file-upload-settings/:id/fields": ["Append a single field to a setting", "POST", "File Upload Setting"],
+  "PUT /api/file-upload-settings/:id/fields": ["Replace the full field list for a setting", "PUT", "File Upload Setting"],
+  "PATCH /api/file-upload-settings/fields/:fieldId": ["Update a single field", "PATCH", "File Upload Setting"],
+  "DELETE /api/file-upload-settings/fields/:fieldId": ["Soft-delete a single field", "DELETE", "File Upload Setting"],
+
+  // First Mile
+  "POST /api/first-mile": ["Create a first-mile leg", "POST", "First Mile"],
+  "PATCH /api/first-mile/:id": ["Update a first-mile leg", "PATCH", "First Mile"],
+  "DELETE /api/first-mile/:id": ["Soft-delete a first-mile leg", "DELETE", "First Mile"],
+  "POST /api/first-mile/:id/distances": ["Set per-vehicle actual distances (does not generate an invoice)", "POST", "First Mile"],
+  "POST /api/first-mile/:id/invoice": ["Generate the first-mile delivery-fee invoice", "POST", "First Mile"],
+  "POST /api/first-mile/:id/vehicles": ["Set the vehicles assigned to a first-mile pickup (multi-truck)", "POST", "First Mile"],
+  "POST /api/first-mile/accept/:reference": ["Accept a paid booking and create a first-mile leg", "POST", "First Mile"],
+
+  // Fuel
+  "POST /api/fuel/purchases": ["Record fuel purchase", "POST", "Fuel"],
+
+  // GPS Tracking
+  "POST /api/gps/devices": ["Register a GPS tracker", "POST", "GPS Tracking"],
+  "PATCH /api/gps/devices/:id": ["Update a GPS tracker (name / assigned vehicle)", "PATCH", "GPS Tracking"],
+  "DELETE /api/gps/devices/:id": ["Delete a GPS tracker", "DELETE", "GPS Tracking"],
+
+  // Import Operation
+  "POST /api/import-operations/customs/:bookingId/declaration": ["Batch 12: record declaration serial number", "POST", "Import Operation"],
+  "POST /api/import-operations/customs/:bookingId/documents": ["Batch 12: upload IM4/IM5/T1/permit/payment-slip documents", "POST", "Import Operation"],
+  "POST /api/import-operations/customs/:bookingId/duties-taxes-paid": ["Batch 12: mark duties and taxes paid", "POST", "Import Operation"],
+  "POST /api/import-operations/customs/:bookingId/notify-duties-taxes": ["Batch 12: notify duties and taxes", "POST", "Import Operation"],
+  "POST /api/import-operations/customs/:bookingId/release-permitted": ["Batch 12: mark import release permitted", "POST", "Import Operation"],
+  "POST /api/import-operations/customs/:bookingId/risk": ["Batch 12: assign customs risk", "POST", "Import Operation"],
+  "POST /api/import-operations/djibouti-incidents": ["Batch 8: report a Djibouti import incident / exception", "POST", "Import Operation"],
+  "POST /api/import-operations/empty-container-returns": ["Batch 16: create an empty container return record", "POST", "Import Operation"],
+  "POST /api/import-operations/empty-container-returns/:id/status": ["Batch 16: advance empty container return workflow", "POST", "Import Operation"],
+
+  // Incident
+  "POST /api/incidents": ["Report an incident", "POST", "Incident"],
+  "PATCH /api/incidents/:id": ["Update an incident", "PATCH", "Incident"],
+  "DELETE /api/incidents/:id": ["Delete an incident", "DELETE", "Incident"],
+
+  // Interchange Document
+  "PATCH /api/interchange-documents/:id/acknowledge": ["Acknowledge an interchange document", "PATCH", "Interchange Document"],
+  "PATCH /api/interchange-documents/:id/dispute": ["Dispute an interchange document", "PATCH", "Interchange Document"],
+  "POST /api/interchange-documents/generate-from-schedule": ["Generate interchange document from a train schedule handover", "POST", "Interchange Document"],
+
+  // Last Mile
+  "POST /api/last-mile": ["Create a last-mile leg", "POST", "Last Mile"],
+  "PATCH /api/last-mile/:id": ["Update a last-mile leg", "PATCH", "Last Mile"],
+  "DELETE /api/last-mile/:id": ["Soft-delete a last-mile leg", "DELETE", "Last Mile"],
+  "POST /api/last-mile/:id/detention-times": ["Set each truck\\'s own detention window (arrived at destination / returned)", "POST", "Last Mile"],
+  "POST /api/last-mile/:id/distances": ["Set per-vehicle actual distances (does not generate an invoice)", "POST", "Last Mile"],
+  "POST /api/last-mile/:id/invoice": ["Generate the delivery-fee invoice for a last-mile leg", "POST", "Last Mile"],
+  "POST /api/last-mile/:id/proof-of-delivery": ["Record proof of delivery (signature + photos) and complete the leg", "POST", "Last Mile"],
+  "POST /api/last-mile/:id/vehicles": ["Set the vehicles assigned to a last-mile delivery (multi-truck)", "POST", "Last Mile"],
+  "POST /api/last-mile/:id/warehouse-gate-times": ["Set each truck\\'s warehouse gate arrival/departure times", "POST", "Last Mile"],
+  "POST /api/last-mile/accept/:reference": ["Accept a paid booking and create a last-mile leg", "POST", "Last Mile"],
+
+  // Last Mile Request
+  "POST /api/last-mile-requests/:id/approve": ["Truck & Machinery chief approves the request — the advance defaults to the live last-mile rate; LM contract becomes signable and the advance invoice follows the customer signature", "POST", "Last Mile Request"],
+  "POST /api/last-mile-requests/:id/contract/sign": ["Customer agrees and signs the LM contract — then the advance invoice is issued", "POST", "Last Mile Request"],
+  "POST /api/last-mile-requests/:id/reject": ["Truck & Machinery chief rejects the request with a reason", "POST", "Last Mile Request"],
+  "POST /api/last-mile-requests/:id/submit": ["Customer confirms which containers go via EDR last-mile", "POST", "Last Mile Request"],
+
+  // Locomotive
+  "POST /api/locomotives": ["Create a locomotive", "POST", "Locomotive"],
+  "PATCH /api/locomotives/:id": ["Update a locomotive", "PATCH", "Locomotive"],
+  "POST /api/locomotives/:id/decommission": ["Decommission a locomotive", "POST", "Locomotive"],
+  "DELETE /api/locomotives/:id/permanent": ["Permanently delete a locomotive (irreversible; refused if any train references it)", "DELETE", "Locomotive"],
+
+  // Maintenance
+  "POST /api/maintenance/costs": ["Record maintenance cost", "POST", "Maintenance"],
+  "POST /api/maintenance/intervals": ["Define/adjust a service interval (e.g. oil change every 10,000 km)", "POST", "Maintenance"],
+  "DELETE /api/maintenance/intervals/:id": ["Deactivate a service interval (stops auto-scheduling)", "DELETE", "Maintenance"],
+  "POST /api/maintenance/parts": ["Create part", "POST", "Maintenance"],
+  "PATCH /api/maintenance/parts/:id": ["Update part", "PATCH", "Maintenance"],
+  "DELETE /api/maintenance/parts/:id": ["Delete part", "DELETE", "Maintenance"],
+  "POST /api/maintenance/schedules": ["Schedule maintenance", "POST", "Maintenance"],
+  "PATCH /api/maintenance/schedules/:id": ["Update maintenance schedule", "PATCH", "Maintenance"],
+  "POST /api/maintenance/warranties": ["Create warranty", "POST", "Maintenance"],
+  "DELETE /api/maintenance/warranties/:id": ["Delete warranty", "DELETE", "Maintenance"],
+  "POST /api/maintenance/work-orders": ["Create work order", "POST", "Maintenance"],
+  "PATCH /api/maintenance/work-orders/:id": ["Update work order", "PATCH", "Maintenance"],
+  "DELETE /api/maintenance/work-orders/:id": ["Delete work order", "DELETE", "Maintenance"],
+
+  // Notification Inbox
+  "PATCH /api/notifications/:id/read": ["Mark one of my notifications as read", "PATCH", "Notification Inbox"],
+  "POST /api/notifications/read-all": ["Mark all my notifications as read", "POST", "Notification Inbox"],
+
+  // Organization User
+  "PUT /api/backoffice/organizations/:orgId/employee-users/:userId/roles": ["Replace org-scoped roles assigned to an employee user", "PUT", "Organization User"],
+  "POST /api/backoffice/organizations/:orgId/users": ["Create an organization user without assigning positions", "POST", "Organization User"],
+
+  // OTP
+  "POST /api/otp/send": ["Send OTP", "POST", "OTP"],
+  "POST /api/otp/verify": ["Verify OTP", "POST", "OTP"],
+
+  // Password Reset
+  "POST /api/auth/forgot-password/request": ["Send a password-reset code to the account's email AND phone", "POST", "Password Reset"],
+  "POST /api/auth/forgot-password/resolve-link": ["Validate a staff-issued reset link and return its set-password ticket", "POST", "Password Reset"],
+  "POST /api/auth/forgot-password/verify": ["Exchange a valid reset code for a single-use set-password ticket", "POST", "Password Reset"],
+  "POST /api/backoffice/customers/:companyId/reset-password": ["Send a password-reset link to a customer's primary contact", "POST", "Password Reset"],
+
+  // Payment
+  "POST /api/billing/invoices/:id/confirm-offline": ["Finance confirms a USD invoice paid by bank transfer — slip file required, settles the full balance", "POST", "Payment"],
+  "POST /api/billing/my-invoices/:id/confirm": ["Confirm an OTP-debit payment (CAC Bank) for one of the customer's invoices", "POST", "Payment"],
+  "POST /api/billing/my-invoices/:id/pay": ["Initiate payment for one of the customer's invoices", "POST", "Payment"],
+  "POST /api/internal/payments/bill-query": ["Live still-payable check + payer name for a CBE bill (called while CBE is on the line)", "POST", "Payment"],
+  "POST /api/internal/payments/mark-paid": ["Apply a payment.succeeded / payment.failed event from the payment service (idempotent)", "POST", "Payment"],
+  "POST /api/payments/initiate": ["Initiate payment for an invoice", "POST", "Payment"],
+  "POST /api/payments/redirect-success/:bookingId": ["Success-redirect ack: mark payment processing + invoice PAYMENT_PROCESSING (webhook remains source of truth)", "POST", "Payment"],
+
+  // Priority Config
+  "POST /api/priority-configs": ["Create a priority config", "POST", "Priority Config"],
+  "PATCH /api/priority-configs/:id": ["Update a priority config", "PATCH", "Priority Config"],
+  "DELETE /api/priority-configs/:id": ["Soft-delete a priority config", "DELETE", "Priority Config"],
+  "POST /api/priority-configs/:id/move-order": ["Move a priority config up or down in display order", "POST", "Priority Config"],
+  "POST /api/priority-configs/reorder": ["Bulk reorder priority configs by ID list", "POST", "Priority Config"],
+
+  // Priority Rule Change Request
+  "POST /api/priority-rule-change-requests": ["Submit a priority-rule change for approval", "POST", "Priority Rule Change Request"],
+  "POST /api/priority-rule-change-requests/:id/approve": ["Approve and apply a pending change", "POST", "Priority Rule Change Request"],
+  "POST /api/priority-rule-change-requests/:id/reject": ["Reject a pending change", "POST", "Priority Rule Change Request"],
+
+  // Procurement
+  "POST /api/procurement/acquisitions": ["Create an asset acquisition", "POST", "Procurement"],
+  "PATCH /api/procurement/acquisitions/:id": ["Update an asset acquisition", "PATCH", "Procurement"],
+  "DELETE /api/procurement/acquisitions/:id": ["Delete an asset acquisition", "DELETE", "Procurement"],
+  "POST /api/procurement/disposals": ["Create an asset disposal", "POST", "Procurement"],
+  "DELETE /api/procurement/disposals/:id": ["Delete an asset disposal", "DELETE", "Procurement"],
+  "POST /api/procurement/vendors": ["Create a vendor", "POST", "Procurement"],
+  "PATCH /api/procurement/vendors/:id": ["Update a vendor", "PATCH", "Procurement"],
+  "DELETE /api/procurement/vendors/:id": ["Delete a vendor", "DELETE", "Procurement"],
+
+  // Rate
+  "POST /api/rates": ["Create a rate (DRAFT)", "POST", "Rate"],
+  "PATCH /api/rates/:id": ["Update a DRAFT rate", "PATCH", "Rate"],
+  "DELETE /api/rates/:id": ["Soft-delete a rate", "DELETE", "Rate"],
+  "POST /api/rates/:id/approve": ["CEO approves a rate", "POST", "Rate"],
+  "POST /api/rates/:id/submit": ["Submit rate for CEO approval", "POST", "Rate"],
+
+  // Rate Change Request
+  "POST /api/rate-change-requests": ["Propose a change to a LIVE rate", "POST", "Rate Change Request"],
+  "POST /api/rate-change-requests/:id/approve": ["Approve a rate change and put it into effect", "POST", "Rate Change Request"],
+  "POST /api/rate-change-requests/:id/reject": ["Reject a rate change — the rate keeps its current value", "POST", "Rate Change Request"],
+
+  // Route
+  "POST /api/routes": ["Create route", "POST", "Route"],
+  "PATCH /api/routes/:id": ["Update route", "PATCH", "Route"],
+  "DELETE /api/routes/:id": ["Deactivate route", "DELETE", "Route"],
+  "DELETE /api/routes/:id/permanent": ["Permanently delete a route (irreversible; refused while any train schedule references it)", "DELETE", "Route"],
+
+  // Schedule
+  // NOTE: duplicate route — also declared in modules/scheduling-reschedule/scheduling-reschedule.controller.ts:52.
+  // Two controllers register this same path; Nest serves whichever module loads first.
+  "POST /api/train-scheduling/schedules/:id/maintenance": ["Reschedule train for maintenance (new departure + rebalance)", "POST", "Schedule"],
+  "POST /api/train-scheduling/schedules/:id/reschedule/execute": ["Execute a confirmed reschedule plan", "POST", "Schedule"],
+  "POST /api/train-scheduling/schedules/:id/reschedule/preview": ["Preview reschedule / government preempt plan", "POST", "Schedule"],
+
+  // Service Type
+  "POST /api/service-types": ["Create a service type", "POST", "Service Type"],
+  "PATCH /api/service-types/:id": ["Update a service type", "PATCH", "Service Type"],
+  "DELETE /api/service-types/:id": ["Soft-delete a service type", "DELETE", "Service Type"],
+  "POST /api/service-types/:id/move-order": ["Move a service type up or down in display order", "POST", "Service Type"],
+  "POST /api/service-types/reorder": ["Bulk reorder service types by ID list", "POST", "Service Type"],
+
+  // Shipping Line
+  "POST /api/shipping-lines": ["Create a shipping line", "POST", "Shipping Line"],
+  "PATCH /api/shipping-lines/:id": ["Update a shipping line", "PATCH", "Shipping Line"],
+  "DELETE /api/shipping-lines/:id": ["Soft-delete a shipping line", "DELETE", "Shipping Line"],
+
+  // Signature
+  "PUT /api/me/signature": ["Create or update the reusable saved signature", "PUT", "Signature"],
+
+  // Support Chat
+  "POST /api/support/agent/conversations": ["Start chatting with a company (returns the thread if one exists)", "POST", "Support Chat"],
+  "POST /api/support/agent/conversations/:id/messages": ["Reply as an agent, optionally with attachments", "POST", "Support Chat"],
+  "POST /api/support/agent/conversations/:id/read": ["Mark a thread read (agent side)", "POST", "Support Chat"],
+  "POST /api/support/conversation/messages": ["Send a message as the customer (optionally with attachments), opening the thread if needed", "POST", "Support Chat"],
+  "POST /api/support/conversation/read": ["Mark my company's thread read (customer side)", "POST", "Support Chat"],
+
+  // Support Content
+  "PATCH /api/support-content/documents/:slug": ["Replace a document's payload, recording a new version", "PATCH", "Support Content"],
+  "POST /api/support-content/documents/:slug/versions/:version/restore": ["Restore a version — re-saves it as a new version, never destructive", "POST", "Support Content"],
+  "POST /api/support-content/media": ["Upload an image or video for a help section", "POST", "Support Content"],
+
+  // Train
+  "POST /api/trains": ["Register a new train", "POST", "Train"],
+  "PATCH /api/trains/:id": ["Update a train", "PATCH", "Train"],
+  "DELETE /api/trains/:id": ["Delete a train", "DELETE", "Train"],
+
+  // Train Build
+  "POST /api/train-builder": ["Build a train: code + yard + 2+ locomotives (+ optional wagons)", "POST", "Train Build"],
+  "DELETE /api/train-builder/:id": ["Disband the train (release wagons and locomotives)", "DELETE", "Train Build"],
+  "POST /api/train-builder/:id/activate": ["Reactivate a deactivated train back to AVAILABLE", "POST", "Train Build"],
+  "POST /api/train-builder/:id/deactivate": ["Deactivate the train (park it) — only allowed with no active schedule", "POST", "Train Build"],
+  "PATCH /api/train-builder/:id/details": ["Edit the train's name and fixed import/export run numbers", "PATCH", "Train Build"],
+  "PUT /api/train-builder/:id/locomotives": ["Replace the locomotive set (minimum 1, same yard)", "PUT", "Train Build"],
+  "POST /api/train-builder/:id/reorder-wagons": ["Persist a drag-reorder of the full consist", "POST", "Train Build"],
+  "POST /api/train-builder/:id/wagons": ["Append AVAILABLE wagons from the train's yard to the consist", "POST", "Train Build"],
+  "DELETE /api/train-builder/:id/wagons/:wagonId": ["Detach one wagon from the consist", "DELETE", "Train Build"],
+  "POST /api/train-builder/:id/wagons/:wagonId/maintenance": ["Detach one wagon and move it to MAINTENANCE status", "POST", "Train Build"],
+  "PATCH /api/train-builder/:id/yard": ["Relocate the train — its locomotives and wagons move to the new yard with it", "PATCH", "Train Build"],
+
+  // Train Schedule
+  "POST /api/train-scheduling/bookings/:bookingId/allocate": ["Staff: place a paid booking onto a fitting train (notifies customer on date change)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bookings/:bookingId/expire": ["Staff: expire a reservation and free its capacity", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bookings/:bookingId/mark-paid": ["Staff: mark a reserved booking paid and allocate it now", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bookings/:bookingId/move-schedule": ["Re-point a booking to another OPEN same-route schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bulk/preview": ["Preview a bulk train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bulk/schedules": ["Create a bulk train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bulk/schedules/:id/assign-bookings": ["Assign bulk bookings to a train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bulk/schedules/:id/cancel": ["Cancel bulk train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/container/preview": ["Preview a container train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/container/schedules": ["Create a container train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/container/schedules/:id/assign-bookings": ["Assign container bookings to a train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/container/schedules/:id/cancel": ["Cancel container train schedule", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/global-rules": ["Update global train scheduling rules (singleton)", "PATCH", "Train Schedule"],
+  "POST /api/train-scheduling/preview": ["Preview a mixed-capable train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/adjust-consist": ["Permanently trim free wagons off / couple yard wagons onto the schedule's built train (weight & length limits incl. tolerance enforced, every change logged)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/arrive": ["Mark a dispatched train arrived (move assets to destination yard, free assets)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/assign-bookings": ["Assign bookings to a train schedule (mixed-capable)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/assign-unassigned-booking": ["Assign one linked unallocated booking to wagons (preserves existing assignments)", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/booking-window": ["Open or close a schedule booking window", "PATCH", "Train Schedule"],
+  "DELETE /api/train-scheduling/schedules/:id/bookings/:bookingId": ["Unassign a booking from a train schedule", "DELETE", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/bookings/:bookingId/load": ["Confirm a booking's cargo loaded at its origin yard (any direction; train must be at that yard)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/bookings/:bookingId/unload": ["Confirm a booking's cargo unloaded at its destination yard — per-booking arrival, may precede the train's final arrival", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/checkpoints": ["Log the train passing a station (final station triggers arrival)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/confirm-loading": ["Confirm cargo loaded on the train (any direction; unblocks import-Djibouti dispatch)", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/container-items/:itemId": ["Update a container number on a wagon slot", "PATCH", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/dispatch": ["Dispatch a scheduled train", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/doc-review-complete": ["Staff finished document review early — run the batch/payment phase now (applies to the whole route-day group)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/finalize": ["Finalize a draft train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/import-djibouti/depart": ["Depart loaded import train from Djibouti", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/import-djibouti/documents": ["Upload/check an import Djibouti-side document", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/import-djibouti/gatepass-granted": ["Mark import Djibouti gatepass permission granted", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/import-djibouti/load-list": ["Generate import load list / marshalling document summary", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/import-djibouti/loaded-on-train": ["Confirm import cargo loaded on train at Djibouti", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/import-djibouti/ready-for-loading": ["Mark import train ready for loading at Djibouti", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/import-loading-status": ["Mark import bookings loaded/unloaded on this schedule (tracking only, does not affect dispatch)", "PATCH", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/intercity/:bookingId/load": ["Confirm intercity cargo loaded (train must be at the booking's origin yard)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/intercity/:bookingId/unload": ["Confirm intercity cargo unloaded at the booking's destination yard (completes the booking)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/intercity/accept": ["Accept intercity bookings onto this train (opens their pay window; capacity re-checked per booking)", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/loading-status": ["Mark bookings loaded/unloaded on this schedule (any direction, pre-dispatch only)", "PATCH", "Train Schedule"],
+  // NOTE: duplicate route — also declared in modules/train-scheduling/controllers/train-scheduling.controller.ts:798.
+  // Two controllers register this same path; Nest serves whichever module loads first.
+  "POST /api/train-scheduling/schedules/:id/maintenance [modules/train-scheduling/controllers/train-scheduling.controller.ts]": ["Maintenance reschedule: move the train to a new departure with every allocated booking aboard — links, wagons and window settings unchanged", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/pin-wagons": ["Pin physical wagons to train set slots", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/run-allocation": ["Run wagon-level allocation for all eligible linked bookings", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/run-batch": ["Manually run the batch fill for a schedule", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/schedule-date": ["Reschedule a train's departure date — only before the booking window opens, and only if the new date still leaves room for the booking lead window", "PATCH", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/switch-government-booking": ["Switch out commercial bookings to allocate a government booking in their place", "POST", "Train Schedule"],
+  "DELETE /api/train-scheduling/schedules/:id/wagons/:trainSetWagonId": ["Remove an empty wagon slot from a train", "DELETE", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/wagons/:wagonId/move-load": ["Move a wagon's whole load to another wagon (empty → move/repin, loaded → swap loads)", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/window-rule": ["Override the booking-window rule for one schedule (open/close hour, duration, doc-review, payment, lead days) — only before the window opens", "PATCH", "Train Schedule"],
+
+  // Transit Agent
+  "POST /api/transit-agents": ["Create a transit agent", "POST", "Transit Agent"],
+  "PATCH /api/transit-agents/:id": ["Update a transit agent", "PATCH", "Transit Agent"],
+  "DELETE /api/transit-agents/:id": ["Soft-delete a transit agent", "DELETE", "Transit Agent"],
+
+  // Truck Type
+  "POST /api/truck-types": ["Create a truck type", "POST", "Truck Type"],
+  "PATCH /api/truck-types/:id": ["Update a truck type", "PATCH", "Truck Type"],
+  "DELETE /api/truck-types/:id": ["Soft-delete a truck type", "DELETE", "Truck Type"],
+
+  // User Trade Access
+  "PUT /api/user-trade-access/:userId": ["Set the trade directions a backoffice user may see", "PUT", "User Trade Access"],
+
+  // Vehicle
+  "POST /api/vehicles": ["Create a new vehicle", "POST", "Vehicle"],
+  "PATCH /api/vehicles/:id": ["Update a vehicle", "PATCH", "Vehicle"],
+  "DELETE /api/vehicles/:id": ["Delete a vehicle", "DELETE", "Vehicle"],
+
+  // Wagon
+  "POST /api/wagons": ["Create a new wagon", "POST", "Wagon"],
+  "PATCH /api/wagons/:id": ["Update a wagon", "PATCH", "Wagon"],
+  "DELETE /api/wagons/:id": ["Delete a wagon", "DELETE", "Wagon"],
+  "POST /api/wagons/:id/assign-train": ["Assign wagon to a train", "POST", "Wagon"],
+  "DELETE /api/wagons/:id/permanent": ["Permanently delete a wagon (irreversible; refused if it has movements, containers or train-set slots)", "DELETE", "Wagon"],
+  "POST /api/wagons/:id/unassign-train": ["Unassign wagon from train", "POST", "Wagon"],
+  "POST /api/wagons/bulk-status": ["Set the status of multiple wagons (audited in wagon_status_logs)", "POST", "Wagon"],
+  "POST /api/wagons/bulk-transfer": ["Transfer multiple wagons to a destination yard", "POST", "Wagon"],
+
+  // Wagon Transfer Request
+  "POST /api/wagon-transfer-requests": ["File a count-only wagon-transfer request", "POST", "Wagon Transfer Request"],
+  "POST /api/wagon-transfer-requests/:id/cancel": ["Withdraw a request that has not moved any wagon yet (use close-short once wagons have moved)", "POST", "Wagon Transfer Request"],
+  "POST /api/wagon-transfer-requests/:id/close-short": ["OCC: end the request with fewer wagons than asked for — what moved stays, the requester is told the shortfall", "POST", "Wagon Transfer Request"],
+  "POST /api/wagon-transfer-requests/:id/fulfill": ["OCC: pick wagons and execute the transfer", "POST", "Wagon Transfer Request"],
+  "POST /api/wagon-transfer-requests/bulk-fulfill": ["OCC: accept-and-execute a subset of pending requests (auto-picks available wagons; the rest stay PENDING)", "POST", "Wagon Transfer Request"],
+
+  // Wagon Type
+  "POST /api/wagon-types": ["Create a wagon type", "POST", "Wagon Type"],
+  "PATCH /api/wagon-types/:id": ["Update a wagon type", "PATCH", "Wagon Type"],
+  "DELETE /api/wagon-types/:id": ["Soft-delete a wagon type", "DELETE", "Wagon Type"],
+
+  // Warehouse
+  "POST /api/warehouse-allocation-rules": ["Create a warehouse allocation rule", "POST", "Warehouse"],
+  "PATCH /api/warehouse-allocation-rules/:id": ["Update a warehouse allocation rule", "PATCH", "Warehouse"],
+  "DELETE /api/warehouse-allocation-rules/:id": ["Delete a warehouse allocation rule", "DELETE", "Warehouse"],
+  "POST /api/warehouse-allocation/preview": ["Preview the yard/warehouse/zone a booking would be allocated to", "POST", "Warehouse"],
+  "POST /api/warehouse-fee-rules": ["Create a storage / demurrage fee rule", "POST", "Warehouse"],
+  "PATCH /api/warehouse-fee-rules/:id": ["Update a fee rule", "PATCH", "Warehouse"],
+  "DELETE /api/warehouse-fee-rules/:id": ["Delete a fee rule", "DELETE", "Warehouse"],
+  "POST /api/warehouse-fees/accrual/:inventoryId/acknowledge": ["Acknowledge / snooze an item fee-accrual alert", "POST", "Warehouse"],
+  "DELETE /api/warehouse-fees/accrual/:inventoryId/acknowledge": ["Remove an accrual acknowledgement (re-surface for alerts)", "DELETE", "Warehouse"],
+  "POST /api/warehouses": ["Create warehouse", "POST", "Warehouse"],
+  "PATCH /api/warehouses/:id": ["Update warehouse", "PATCH", "Warehouse"],
+  "POST /api/warehouses/:warehouseId/yards": ["Create a yard within a warehouse", "POST", "Warehouse"],
+
+  // Warehouse Fee Invoice
+  "POST /api/last-mile/:id/generate-truck-detention-invoice": ["Generate a truck-detention invoice for a last-mile leg (per truck per day)", "POST", "Warehouse Fee Invoice"],
+  "PATCH /api/warehouse-fee-invoices/:id/cancel": ["Cancel a warehouse fee invoice", "PATCH", "Warehouse Fee Invoice"],
+  "POST /api/warehouse-fee-invoices/:id/pay": ["Record a payment against a warehouse fee invoice", "POST", "Warehouse Fee Invoice"],
+  "POST /api/warehouse-fee-invoices/:id/pay-online": ["Initiate Telebirr/Waafi payment for a warehouse fee invoice", "POST", "Warehouse Fee Invoice"],
+  "POST /api/warehouse-inventory/:id/generate-fee-invoice": ["Generate a warehouse fee invoice from Batch 5 fee calculation", "POST", "Warehouse Fee Invoice"],
+
+  // Warehouse Inspection Report
+  "PATCH /api/warehouse-inspection-reports/:id": ["Update an inspection report", "PATCH", "Warehouse Inspection Report"],
+  "POST /api/warehouse-inspection-reports/:id/attachments": ["Upload inspection images / documents", "POST", "Warehouse Inspection Report"],
+  "POST /api/warehouse-inventory/:inventoryId/inspection-reports": ["Create an inspection / damage report for an inventory item", "POST", "Warehouse Inspection Report"],
+
+  // Warehouse Inventory
+  "POST /api/warehouse-inventory/:id/deliver": ["Deliver import goods to the customer + capture proof of delivery", "POST", "Warehouse Inventory"],
+  "PATCH /api/warehouse-inventory/:id/dispatch": ["Mark loaded inventory DISPATCHED (left the terminal)", "PATCH", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/gate-clearance": ["Final terminal release / gate clearance (blocked while fees unpaid)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/load": ["Load READY_FOR_LOADING inventory onto a wagon", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/move": ["Move inventory to another warehouse/yard/zone", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/ready-for-loading": ["Mark reserved inventory READY_FOR_LOADING", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/ready-for-pickup": ["Mark inspected IMPORT inventory READY_FOR_PICKUP", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/release": ["Issue a DO / release order for ready-for-pickup inventory", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/store": ["Mark received inventory as STORED (optional explicit warehouse/yard/zone)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/auto-load-ready": ["Auto-load READY_FOR_LOADING inventory with PAID bookings", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/auto-unload-arrived": ["Bulk auto-unload all arrived bookings into the warehouse", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/bookings/:bookingId/approve-delivery": ["Approve delivery — customer records their full name (signature optional)", "POST", "Warehouse Inventory"],
+  "PATCH /api/warehouse-inventory/bookings/:bookingId/double-handling": ["Record Yes/No double handling after unloading (Yes applies the double-handling fee rule)", "PATCH", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/bookings/:bookingId/request-handover-signature": ["Ask the customer to sign the handover (creates one if none, then notifies)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/bookings/:bookingId/unload": ["Unload a single arrived booking into a location", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/bulk-dispatch-export": ["Bulk-dispatch loaded EXPORT inventory (LOADED → DISPATCHED)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/bulk-mark-inspected": ["Bulk mark received inventory inspection PASSED (EXPORT → READY_FOR_LOADING)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/export/auto-unload-at-djibouti": ["Unload all eligible export items assigned to an arrived Djibouti-side train", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/handovers/:handoverId/sign": ["Customer signs one handover (EDR last-mile: one signature per truck)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/import/auto-unload-arrived-bookings": ["Unload all eligible assigned bookings of an ARRIVED import train (→ UNLOADED)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/receive": ["Receive inventory at a warehouse location", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/receive-bulk": ["Bulk-receive selected eligible PAID bookings into a location", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/reserve": ["Reserve stored inventory for a PAID booking", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/train/:scheduleId/load": ["Load selected inventory items onto their allocated wagons for a train", "POST", "Warehouse Inventory"],
+
+  // Warehouse Yard
+  "PATCH /api/warehouse-yards/:id": ["Update warehouse yard", "PATCH", "Warehouse Yard"],
+  "POST /api/warehouse-yards/:yardId/zones": ["Create a zone within a yard", "POST", "Warehouse Yard"],
+
+  // Warehouse Zone
+  "PATCH /api/warehouse-zones/:id": ["Update warehouse zone", "PATCH", "Warehouse Zone"],
+
+  // Weight Limit Rule
+  "POST /api/weight-limit-rules": ["Create a weight limit rule", "POST", "Weight Limit Rule"],
+  "PATCH /api/weight-limit-rules/:id": ["Update a weight limit rule", "PATCH", "Weight Limit Rule"],
+  "DELETE /api/weight-limit-rules/:id": ["Soft-delete a weight limit rule", "DELETE", "Weight Limit Rule"],
+
+  // Yard
+  "POST /api/yards": ["Create a yard", "POST", "Yard"],
+  "PATCH /api/yards/:id": ["Update a yard", "PATCH", "Yard"],
+  "DELETE /api/yards/:id": ["Soft-delete a yard", "DELETE", "Yard"],
+  "POST /api/yards/:id/move-order": ["Move a yard up or down in display order", "POST", "Yard"],
+  "POST /api/yards/reorder": ["Bulk reorder yards by ID list", "POST", "Yard"],
+
+  // Yard Distance
+  "POST /api/yard-distances": ["Create a yard distance", "POST", "Yard Distance"],
+  "PATCH /api/yard-distances/:id": ["Update a yard distance", "PATCH", "Yard Distance"],
+  "DELETE /api/yard-distances/:id": ["Soft-delete a yard distance", "DELETE", "Yard Distance"],
+};
+
+module.exports = AUDIT_ENDPOINTS;
diff --git a/apps/edr-freight-api/src/common/booking-guards.ts b/apps/edr-freight-api/src/common/booking-guards.ts
index d1b5364c3..36ed7ae74 100644
--- a/apps/edr-freight-api/src/common/booking-guards.ts
+++ b/apps/edr-freight-api/src/common/booking-guards.ts
@@ -90,6 +90,10 @@ export const TrainSchedulingReschedule = () =>
 export const TrainSchedulingRulesManage = () =>
   BookingStaff(FREIGHT_PERMS.trainScheduling.rulesManage);
 
+/** Edit a schedule's operational run numbers (train + voyage) before dispatch. */
+export const TrainSchedulingEditTrainNumber = () =>
+  BookingStaff(FREIGHT_PERMS.trainScheduling.editTrainNumber);
+
 /**
  * Fleet guards take an optional granular per-resource key (locomotives:create,
  * wagons:delete, …). The legacy coarse fleet:view / fleet:manage keys remain
diff --git a/apps/edr-freight-api/src/migrations/3390000000000-CreateAuditLogs.ts b/apps/edr-freight-api/src/migrations/3390000000000-CreateAuditLogs.ts
new file mode 100644
index 000000000..b5b865ad7
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3390000000000-CreateAuditLogs.ts
@@ -0,0 +1,81 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Backoffice audit trail for every state-changing freight endpoint.
+ *
+ * No `updated_at` / `deleted_at` columns, unlike every other table here: audit
+ * rows are insert-only evidence. A soft-delete column would let an actor erase
+ * their own trail and TypeORM would then hide those rows from default queries
+ * silently — see the entity comment.
+ *
+ * `user_id` intentionally carries NO foreign key to the `iam` schema.
+ * Cross-schema FKs are forbidden platform-wide, and one here would let user
+ * deletion cascade away the record of what that user did.
+ *
+ * DDL is idempotent (`IF NOT EXISTS`) because watch-mode API instances race
+ * `migrationsRun` against each other on the shared dev database.
+ */
+export class CreateAuditLogs3390000000000 implements MigrationInterface {
+  name = "CreateAuditLogs3390000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.audit_logs (
+        id            uuid         NOT NULL DEFAULT gen_random_uuid(),
+        title         varchar(255) NOT NULL,
+        method        varchar(10)  NOT NULL,
+        url           text         NOT NULL,
+        route_path    varchar(255),
+        type          varchar(50)  NOT NULL,
+        is_success    boolean      NOT NULL,
+        user_id       uuid,
+        resource_id   varchar(64),
+        request       jsonb,
+        status_code   smallint,
+        error_message text,
+        user_name     varchar(150),
+        user_role     varchar(100),
+        ip_address    inet,
+        user_agent    text,
+        request_id    varchar(64),
+        duration_ms   integer,
+        created_at    timestamptz  NOT NULL DEFAULT now(),
+        CONSTRAINT "PK_audit_logs" PRIMARY KEY (id)
+      )
+    `);
+
+    // Every audit query is time-bounded, so created_at leads each index.
+    // DESC matches the "newest first" read path the controller exposes.
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_audit_logs_created_at"
+        ON freight.audit_logs (created_at DESC)
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_audit_logs_user_id_created_at"
+        ON freight.audit_logs (user_id, created_at DESC)
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_audit_logs_type_created_at"
+        ON freight.audit_logs (type, created_at DESC)
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_audit_logs_type_resource_id"
+        ON freight.audit_logs (type, resource_id)
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_audit_logs_route_path_created_at"
+        ON freight.audit_logs (route_path, created_at DESC)
+    `);
+    // Failures are a small slice of the table but carry the security signal
+    // (403s especially), so they get their own partial index.
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_audit_logs_failures"
+        ON freight.audit_logs (created_at DESC)
+        WHERE is_success = false
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.audit_logs`);
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3400000000000-TransferRequestPreferredWagons.ts b/apps/edr-freight-api/src/migrations/3400000000000-TransferRequestPreferredWagons.ts
new file mode 100644
index 000000000..b86327147
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3400000000000-TransferRequestPreferredWagons.ts
@@ -0,0 +1,29 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Wagons the requester specifically asked for. A transfer request stays
+ * count-driven (`quantity` is what must be delivered), but a requester who
+ * picked wagons off the yard desk now records WHICH ones — OCC sees the numbers
+ * on the queue and the fulfil picker pre-selects them.
+ *
+ * Stored as a uuid[] column rather than a join table: the list is read and
+ * written whole, never queried by wagon, and a preference carries no lifecycle
+ * of its own (no FK — a purged wagon simply drops out of the display).
+ */
+export class TransferRequestPreferredWagons3400000000000
+  implements MigrationInterface
+{
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.wagon_transfer_requests
+        ADD COLUMN IF NOT EXISTS preferred_wagon_ids uuid[]
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.wagon_transfer_requests
+        DROP COLUMN IF EXISTS preferred_wagon_ids
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3410000000000-ScheduleVoyageNumber.ts b/apps/edr-freight-api/src/migrations/3410000000000-ScheduleVoyageNumber.ts
new file mode 100644
index 000000000..dd62276d8
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3410000000000-ScheduleVoyageNumber.ts
@@ -0,0 +1,28 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Voyage number for one departure.
+ *
+ * `train_number` already exists on a schedule (the run number), but operations
+ * also quote a VOYAGE number — the sailing/run identifier yards and customs use
+ * for a specific departure. It belongs on the schedule, not the built train: one
+ * train serves many departures and each carries its own voyage.
+ *
+ * Nullable and un-indexed: it is display/reference data typed by staff, not a
+ * lookup key, and older schedules simply have none.
+ */
+export class ScheduleVoyageNumber3410000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_schedules
+        ADD COLUMN IF NOT EXISTS voyage_number varchar(20)
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_schedules
+        DROP COLUMN IF EXISTS voyage_number
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/audit/audit-actor.ts b/apps/edr-freight-api/src/modules/audit/audit-actor.ts
new file mode 100644
index 000000000..f89a7ee26
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/audit/audit-actor.ts
@@ -0,0 +1,84 @@
+/**
+ * Who acted, and does this API audit them?
+ *
+ * The staff/customer split reuses the exact discriminator the permission guards
+ * already apply (`freight-permission.guard.ts`): `userType === 'employee'` is
+ * backoffice, `individual` / `external_organization` are customers. Restating
+ * the rule instead of importing it would let the two drift apart silently.
+ */
+
+const EMPLOYEE_USER_TYPE = 'employee';
+const SUPER_ADMIN_ROLE = 'super_admin';
+
+/** The subset of the JWT payload this module reads. */
+export interface AuditActorSource {
+  id?: string;
+  sub?: string;
+  userType?: string;
+  username?: string;
+  name?: string | { en?: string; am?: string };
+  firstName?: string;
+  lastName?: string;
+  email?: string;
+  roles?: { key?: string; name?: string }[];
+  employee?: unknown;
+}
+
+export interface AuditActor {
+  userId: string | null;
+  userName: string | null;
+  userRole: string | null;
+}
+
+function isSuperAdmin(user: AuditActorSource): boolean {
+  return Boolean(user.roles?.some((role) => role.key === SUPER_ADMIN_ROLE));
+}
+
+/**
+ * Is this caller a backoffice user whose actions are audited?
+ *
+ * Only employees qualify. Customers are excluded by request, and unauthenticated
+ * callers are excluded too — which means failed logins, OTP sends and password
+ * resets produce no audit rows. That was a deliberate call: those endpoints are
+ * not backoffice actions. Note the trade-off, since failed-auth attempts are
+ * often what an incident review looks for first.
+ */
+export function isAuditableActor(user: AuditActorSource | null | undefined): boolean {
+  if (!user) return false;
+  // Super admins may not carry an `employee` userType on every token, but are
+  // unambiguously staff — the permission guards treat them the same way.
+  return user.userType === EMPLOYEE_USER_TYPE || isSuperAdmin(user);
+}
+
+/** Best-effort display name, tolerating the several shapes tokens use. */
+function resolveUserName(user: AuditActorSource): string | null {
+  if (typeof user.name === 'string' && user.name.trim()) return user.name.trim();
+
+  if (user.name && typeof user.name === 'object') {
+    const localized = user.name.en ?? user.name.am;
+    if (localized?.trim()) return localized.trim();
+  }
+
+  const composed = [user.firstName, user.lastName].filter(Boolean).join(' ').trim();
+  if (composed) return composed;
+
+  return user.username?.trim() || user.email?.trim() || null;
+}
+
+/**
+ * Snapshot the actor at the moment of the action.
+ *
+ * Name and role are copied, never referenced: resolving them from IAM at read
+ * time would rewrite history whenever someone is renamed, changes role or is
+ * deleted. An audit row from last year must still say who acted and with what
+ * authority *then*.
+ */
+export function resolveAuditActor(user: AuditActorSource): AuditActor {
+  const roleKey = user.roles?.[0]?.key ?? user.roles?.[0]?.name ?? null;
+
+  return {
+    userId: user.id ?? user.sub ?? null,
+    userName: resolveUserName(user),
+    userRole: roleKey,
+  };
+}
diff --git a/apps/edr-freight-api/src/modules/audit/audit-endpoint-matcher.ts b/apps/edr-freight-api/src/modules/audit/audit-endpoint-matcher.ts
new file mode 100644
index 000000000..75ae51fa6
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/audit/audit-endpoint-matcher.ts
@@ -0,0 +1,140 @@
+import { AUDIT_ENDPOINTS, type AuditEndpointMeta } from './audit-endpoints';
+
+/** What a matched request resolved to. */
+export interface MatchedAuditEndpoint {
+  /** Human-readable action, e.g. "Approve contract". */
+  title: string;
+  /** Primary entity, e.g. "Contract". */
+  type: string;
+  /** The route template, e.g. `/api/contracts/:id/cancel`. */
+  routePath: string;
+  /** First path parameter of the template, when the route has one. */
+  resourceId: string | null;
+}
+
+interface CompiledRoute {
+  regex: RegExp;
+  /** Param names in capture-group order, e.g. ['id', 'stepId']. */
+  paramNames: string[];
+  routePath: string;
+  meta: AuditEndpointMeta;
+  /** Literal (non-parameter) segment count — used to rank specificity. */
+  staticSegments: number;
+}
+
+const ESCAPE_REGEX = /[.*+?^${}()|[\]\\]/g;
+
+/**
+ * Two keys in AUDIT_ENDPOINTS point at the same path: one route is declared by
+ * two different controllers, so the generator suffixed the second with
+ * ` [modules/...controller.ts]` to keep both entries. Only the path itself is
+ * matchable, so the suffix is stripped here.
+ */
+function stripSourceSuffix(key: string): string {
+  const bracket = key.indexOf(' [');
+  return bracket === -1 ? key : key.slice(0, bracket);
+}
+
+/**
+ * Compile one `"/api/contracts/:id/cancel"` template into an anchored regex.
+ *
+ * A parameter matches a single path segment only (`[^/]+`), so
+ * `/api/contracts/:id` cannot swallow `/api/contracts/:id/cancel`.
+ */
+function compileTemplate(path: string): { regex: RegExp; paramNames: string[] } {
+  const paramNames: string[] = [];
+  const pattern = path
+    .split('/')
+    .map((segment) => {
+      if (!segment.startsWith(':')) {
+        return segment.replace(ESCAPE_REGEX, '\\$&');
+      }
+      paramNames.push(segment.slice(1));
+      return '([^/]+)';
+    })
+    .join('/');
+
+  return { regex: new RegExp(`^${pattern}$`), paramNames };
+}
+
+/**
+ * Method-bucketed lookup table for the audited routes.
+ *
+ * A direct `AUDIT_ENDPOINTS[url]` lookup cannot work: the keys are templates
+ * with `:params` while a live request carries real ids and a query string, so
+ * every parameterized route — most of the 488 — would miss. Templates are
+ * compiled to regexes once at module load and matched per request.
+ *
+ * Within a method, routes are ordered by literal-segment count descending, so
+ * a specific route always wins over a parameterized one that could also match
+ * (`/api/routes/:id/permanent` before `/api/routes/:id`).
+ */
+class AuditEndpointMatcher {
+  private readonly byMethod = new Map<string, CompiledRoute[]>();
+
+  constructor() {
+    for (const [key, meta] of Object.entries(AUDIT_ENDPOINTS)) {
+      const [method, rawPath] = stripSourceSuffix(key).split(' ');
+      if (!method || !rawPath) continue;
+
+      const { regex, paramNames } = compileTemplate(rawPath);
+      const bucket = this.byMethod.get(method) ?? [];
+      bucket.push({
+        regex,
+        paramNames,
+        routePath: rawPath,
+        meta,
+        staticSegments: rawPath
+          .split('/')
+          .filter((s) => s && !s.startsWith(':')).length,
+      });
+      this.byMethod.set(method, bucket);
+    }
+
+    for (const bucket of this.byMethod.values()) {
+      bucket.sort((a, b) => b.staticSegments - a.staticSegments);
+    }
+  }
+
+  /**
+   * Resolve a live request to its audit metadata, or null when the route is
+   * not audited (every GET, and anything absent from AUDIT_ENDPOINTS).
+   *
+   * `url` may include a query string; it is ignored for matching.
+   */
+  match(method: string, url: string): MatchedAuditEndpoint | null {
+    const bucket = this.byMethod.get(method.toUpperCase());
+    if (!bucket) return null;
+
+    const path = stripQuery(url);
+
+    for (const route of bucket) {
+      const result = route.regex.exec(path);
+      if (!result) continue;
+
+      const [title, , type] = route.meta;
+      return {
+        title,
+        type,
+        routePath: route.routePath,
+        // The first path parameter is the affected record in this API's
+        // conventions (`/api/contracts/:id/...`). Routes with no parameter
+        // (a create) legitimately have no resource id yet.
+        resourceId: route.paramNames.length > 0 ? result[1] : null,
+      };
+    }
+
+    return null;
+  }
+}
+
+/** Strip query string and hash from a URL, leaving the path. */
+export function stripQuery(url: string): string {
+  const queryIndex = url.indexOf('?');
+  const path = queryIndex === -1 ? url : url.slice(0, queryIndex);
+  const hashIndex = path.indexOf('#');
+  return hashIndex === -1 ? path : path.slice(0, hashIndex);
+}
+
+/** Compiled once at module load and shared by the interceptor. */
+export const auditEndpointMatcher = new AuditEndpointMatcher();
diff --git a/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts b/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
new file mode 100644
index 000000000..0526636ff
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
@@ -0,0 +1,641 @@
+/**
+ * Freight API — every state-changing endpoint (POST / PUT / PATCH / DELETE).
+ *
+ * Shape:  "<METHOD> <path>": [title, method, entity]
+ *
+ * Keyed by method + path rather than path alone: 50 paths serve more than one
+ * method (PATCH and DELETE on /api/contracts/:id, for example), so a path-only
+ * key would collide and drop those endpoints.
+ *
+ * Paths include the global prefix `api` (see app.setGlobalPrefix in src/main.ts).
+ * Titles come from each route's @ApiOperation summary, falling back to a
+ * humanized handler name where a route has none.
+ *
+ * Excludes the AI Assist and Account entities.
+ * Generated from the controllers under src/ — 488 endpoints.
+ */
+/** [title, method, entity] for one auditable route. */
+export type AuditEndpointMeta = readonly [title: string, method: string, entity: string];
+
+export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
+  // Approval Rule
+  "POST /api/approval-rules": ["Create an approval rule step", "POST", "Approval Rule"],
+  "PATCH /api/approval-rules/:id": ["Update an approval rule", "PATCH", "Approval Rule"],
+  "DELETE /api/approval-rules/:id": ["Soft-delete an approval rule", "DELETE", "Approval Rule"],
+  "POST /api/approval-rules/:id/move-order": ["Move an approval step up or down within its chain", "POST", "Approval Rule"],
+  "POST /api/approval-rules/reorder": ["Bulk reorder approval steps within a chain", "POST", "Approval Rule"],
+
+  // Booking
+  "POST /api/bookings": ["Create a new freight booking (DRAFT)", "POST", "Booking"],
+  "POST /api/bookings/:bookingId/allocate-containers": ["Allocate containers to vehicles", "POST", "Booking"],
+  "PATCH /api/bookings/:id": ["Update booking", "PATCH", "Booking"],
+  "DELETE /api/bookings/:id": ["Soft-delete DRAFT booking", "DELETE", "Booking"],
+  "POST /api/bookings/:id/cancel": ["Cancel booking", "POST", "Booking"],
+  "POST /api/bookings/:id/cancel-hold": ["Customer cancels an unpaid hold (SELECTED_FOR_BATCH → CANCELLED);", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/declaration": ["GL ET uploads customs declaration on booking (GENERAL customs)", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/delivery-order": ["Upload Booking Delivery Order", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/documents": ["Customer uploads clearance documents (fieldname = document key)", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/draft-declaration": ["GL ET sends a draft customs declaration (multi-file) with an estimated price for the customer to review", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/draft-declaration/accept": ["Customer accepts the draft customs declaration — unlocks the real customs declaration step for GL Ethiopia", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/draft-declaration/change": ["Customer requests a change to the draft customs declaration with a reason — GL Ethiopia sends a corrected draft (repeatable)", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/duty": ["GL ET sets duty/tax on booking with notice attachment", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/duty-slip": ["Customer uploads duty/tax payment slip on booking", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/export-release": ["Confirm Booking Export Release", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/finalize": ["GL finalizes clearance (requires 100% approved) → CLEARANCE_READY", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/finalize-pre-clearance": ["GL ET finalizes import pre-clearance on booking", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/output-documents": ["GL uploads customs output documents (IM4/EX3/…)", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/proceed": ["Customer requests operation with a schedule day", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/release-order": ["Upload Booking Release Order", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/review": ["GL reviews a clearance document (Approve | Query)", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/ro-amendment": ["Request Booking RO Amendment", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/transit-assignee/assign": ["GL Djibouti picks the transit officer from the roster — unblocks the customs declaration; calling again reassigns", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/transit-assignee/request": ["GL ET asks GL Djibouti to name the transit officer — required before the import customs declaration", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/transit-permit": ["Upload Booking Transit Permit", "POST", "Booking"],
+  "POST /api/bookings/:id/confirm-submit": ["Confirm submit after price change", "POST", "Booking"],
+  "POST /api/bookings/:id/consolidation": ["Request freight consolidation", "POST", "Booking"],
+  "DELETE /api/bookings/:id/consolidation": ["Remove consolidation pairing", "DELETE", "Booking"],
+  "POST /api/bookings/:id/contract/generate": ["Generate contract PDF from template", "POST", "Booking"],
+  "POST /api/bookings/:id/contract/sign": ["Apply digital signature (customer or staff)", "POST", "Booking"],
+  "POST /api/bookings/:id/customer-cancel": ["Customer cancels their own booking before payment — no cancellation fee", "POST", "Booking"],
+  "POST /api/bookings/:id/customer-truck-assignment": ["Customer assigns external truck and driver for terminal pickup", "POST", "Booking"],
+  "POST /api/bookings/:id/customer-trucks": ["Add a customer self-haul truck carrying 1–2 of the booking containers", "POST", "Booking"],
+  "PATCH /api/bookings/:id/customer-trucks/:assignmentId": ["Edit a not-yet-arrived customer truck (plate/driver/type + containers)", "PATCH", "Booking"],
+  "DELETE /api/bookings/:id/customer-trucks/:assignmentId": ["Remove a not-yet-arrived customer truck from a booking", "DELETE", "Booking"],
+  "POST /api/bookings/:id/customer-trucks/:assignmentId/depart": ["Register an import truck leaving: containers loaded + weighed gross (staff)", "POST", "Booking"],
+  "POST /api/bookings/:id/customer-trucks/:assignmentId/load": ["Truck_dispatch: load selected containers onto a truck (staff)", "POST", "Booking"],
+  "POST /api/bookings/:id/customer-trucks/bulk": ["Bulk add customer trucks from array payload (Excel parsed)", "POST", "Booking"],
+  "POST /api/bookings/:id/customer/sign": ["Customer digital signature (deprecated — use POST contract/sign)", "POST", "Booking"],
+  "POST /api/bookings/:id/documents": ["Upload documents for a booking (DRAFT only)", "POST", "Booking"],
+  "PATCH /api/bookings/:id/export-handover-mode": ["Export only: choose direct truck-to-train (no warehouse, no GRN) or warehouse first", "PATCH", "Booking"],
+  "POST /api/bookings/:id/generate-grn": ["Generate a GRN over the received containers (all received, or a subset) — one GRN per batch", "POST", "Booking"],
+  "POST /api/bookings/:id/generate-price": ["Generate price preview (DRAFT or CHANGES_REQUESTED)", "POST", "Booking"],
+  "POST /api/bookings/:id/government-expedite": ["Expedite government booking to PAID / ELIGIBLE for scheduling", "POST", "Booking"],
+  "POST /api/bookings/:id/marketing/approve": ["Staff contract signature and fully execute (use contract/sign STAFF preferred)", "POST", "Booking"],
+  "POST /api/bookings/:id/operation/review": ["Operations reviews an operation request: ACCEPT (→ batch pool),", "POST", "Booking"],
+  "POST /api/bookings/:id/operations/complete": ["Mark completed", "POST", "Booking"],
+  "POST /api/bookings/:id/operations/start-transit": ["Mark in transit", "POST", "Booking"],
+  "POST /api/bookings/:id/reject": ["Customer reject price estimate", "POST", "Booking"],
+  "POST /api/bookings/:id/staff/accept": ["Staff accept intake → set contract validity window + start approval chain", "POST", "Booking"],
+  "POST /api/bookings/:id/staff/reject": ["Staff final reject", "POST", "Booking"],
+  "POST /api/bookings/:id/staff/request-changes": ["Staff return booking for customer updates", "POST", "Booking"],
+  "POST /api/bookings/:id/submit": ["Customer submit booking", "POST", "Booking"],
+  "POST /api/bookings/:id/wagon-cancellations": ["Request a partial wagon cancellation on a PAID booking — opens the cancellation-fee invoice; wagons are released only once the fee settles", "POST", "Booking"],
+  "POST /api/bookings/:id/wagon-cancellations/preview": ["Preview the fee/credit of a partial wagon cancellation (no writes)", "POST", "Booking"],
+  "POST /api/bookings/wagon-cancellations/:cancellationId/rebook": ["Rebook a wagon-cancellation credit: pick a shipment day only — the new booking is created under the contract and marked PAID (freight already paid; contract must still be valid)", "POST", "Booking"],
+  "POST /api/bookings/wagon-cancellations/:cancellationId/withdraw": ["Withdraw a fee-pending wagon cancellation (owner, or staff with the void permission)", "POST", "Booking"],
+
+  // Cargo
+  "POST /api/cargoes": ["Create a new cargo", "POST", "Cargo"],
+  "PATCH /api/cargoes/:id": ["Update a cargo", "PATCH", "Cargo"],
+  "DELETE /api/cargoes/:id": ["Delete a cargo", "DELETE", "Cargo"],
+  "POST /api/cargoes/:id/deliver": ["Mark cargo as delivered", "POST", "Cargo"],
+  "POST /api/cargoes/:id/load": ["Load cargo into a container", "POST", "Cargo"],
+  "POST /api/cargoes/:id/unload": ["Unload cargo from container", "POST", "Cargo"],
+
+  // Cargo Type
+  "POST /api/cargo-types": ["Create a cargo type", "POST", "Cargo Type"],
+  "PATCH /api/cargo-types/:id": ["Update a cargo type", "PATCH", "Cargo Type"],
+  "DELETE /api/cargo-types/:id": ["Soft-delete a cargo type", "DELETE", "Cargo Type"],
+  "POST /api/cargo-types/:id/move-order": ["Move a cargo type up or down in display order", "POST", "Cargo Type"],
+  "POST /api/cargo-types/reorder": ["Bulk reorder cargo types by ID list", "POST", "Cargo Type"],
+
+  // Company
+  "POST /api/companies": ["Create a new company (customer, freight_forwarder, dj_freight_forwarder, transporter)", "POST", "Company"],
+  "POST /api/companies/:companyId/documents": ["Upload documents for a company (onboarding)", "POST", "Company"],
+  "POST /api/companies/:companyId/profiles": ["Add a profile (employee) to a company", "POST", "Company"],
+  "PATCH /api/companies/:id": ["Update a company", "PATCH", "Company"],
+  "DELETE /api/companies/:id": ["Soft-delete a company", "DELETE", "Company"],
+  "POST /api/companies/change-requests/:id/approve": ["Approve a pending profile change request (applies the changes)", "POST", "Company"],
+  "POST /api/companies/change-requests/:id/reject": ["Reject a pending profile change request with a note", "POST", "Company"],
+  "POST /api/companies/change-requests/:id/request-changes": ["Ask for specific changes on a pending request without rejecting it (row stays open, next edit appends to it)", "POST", "Company"],
+  "POST /api/companies/company-profile": ["Create a single operational profile for the current user's company. The role starts pending and does not become the active mode", "POST", "Company"],
+  "POST /api/companies/company-profiles": ["Add operational profile(s) (importer/exporter/forwarder) to the current user's company", "POST", "Company"],
+  "POST /api/companies/company-profiles/:profileId/license": ["Add business-license document(s) to a profile. For an approved company", "POST", "Company"],
+  "DELETE /api/companies/company-profiles/:profileId/license/:fileId": ["Remove a business-license file (staged for review on an approved company)", "DELETE", "Company"],
+  "POST /api/companies/company-profiles/:profileId/license/:fileId/replace": ["Replace a business-license file with a newly uploaded one (staged for", "POST", "Company"],
+  "POST /api/companies/company-profiles/:profileId/reapply": ["Resubmit a rejected operational role for approval (→ pending)", "POST", "Company"],
+  "PATCH /api/companies/company-profiles/:profileId/status": ["Update a company profile's approval status", "PATCH", "Company"],
+  "POST /api/companies/create": ["Create a company with its associated external profile (onboarding)", "POST", "Company"],
+  "POST /api/companies/documents/:fileId/request-change": ["Ask the customer to correct one uploaded document", "POST", "Company"],
+  "POST /api/companies/fetch-etrade-info": ["Fetch company info from eTrade by TIN", "POST", "Company"],
+  "POST /api/companies/identity/fayda/complete": ["Bind a completed Fayda verification to the company's owner or Power of Attorney", "POST", "Company"],
+  "DELETE /api/companies/identity/fayda/poa": ["Remove the company's Power of Attorney — the verified identity, its details and the delegation paper together", "DELETE", "Company"],
+  "DELETE /api/companies/identity/gm": ["Clear the General Manager's identity — the \\\"same as owner\\\" declaration or a verification, and the details either wrote", "DELETE", "Company"],
+  "POST /api/companies/identity/gm/same-as-owner": ["Declare the General Manager is the company's owner, copying the owner's verified identity across", "POST", "Company"],
+  "POST /api/companies/identity/poa/same-as-owner": ["Declare the Power of Attorney is the company's owner, copying the owner's identity across", "POST", "Company"],
+  "DELETE /api/companies/identity/poa/same-as-owner": ["Undo the Power of Attorney \\\"same as owner\\\" declaration and the identity it copied, leaving the representative open to be verified in their own right", "DELETE", "Company"],
+  "PATCH /api/companies/onboarding-step": ["Persist the user's current onboarding wizard step", "PATCH", "Company"],
+  "POST /api/companies/onboarding/complete": ["Mark the current user's onboarding as complete", "POST", "Company"],
+  "POST /api/companies/onboarding/start": ["Begin onboarding: create a draft company + profile + role(s) so later steps can save incrementally", "POST", "Company"],
+  "POST /api/companies/poa-delegation": ["Upload the Power of Attorney delegation letter, replacing any existing one", "POST", "Company"],
+  "DELETE /api/companies/poa-delegation/:fileId": ["Remove the Power of Attorney delegation letter (staged for review on an approved company)", "DELETE", "Company"],
+  "PATCH /api/companies/profile": ["Update profile (flattened settings page)", "PATCH", "Company"],
+
+  // Compliance
+  "POST /api/compliance": ["Create a compliance record", "POST", "Compliance"],
+  "PATCH /api/compliance/:id": ["Update a compliance record", "PATCH", "Compliance"],
+  "DELETE /api/compliance/:id": ["Soft-delete a compliance record", "DELETE", "Compliance"],
+
+  // Consignment
+  "POST /api/consignments": ["Create a new consignment", "POST", "Consignment"],
+
+  // Container
+  "POST /api/containers": ["Create a new container", "POST", "Container"],
+  "PATCH /api/containers/:id": ["Update a container", "PATCH", "Container"],
+  "DELETE /api/containers/:id": ["Delete a container", "DELETE", "Container"],
+  "POST /api/containers/:id/assign-wagon": ["Assign container to a wagon", "POST", "Container"],
+  "POST /api/containers/:id/unassign-wagon": ["Unassign container from wagon", "POST", "Container"],
+
+  // Container Type
+  "POST /api/container-types": ["Create a container type", "POST", "Container Type"],
+  "PATCH /api/container-types/:id": ["Update a container type", "PATCH", "Container Type"],
+  "DELETE /api/container-types/:id": ["Soft-delete a container type", "DELETE", "Container Type"],
+  "POST /api/container-types/:id/move-order": ["Move a container type up or down in display order", "POST", "Container Type"],
+  "POST /api/container-types/reorder": ["Bulk reorder container types by ID list", "POST", "Container Type"],
+
+  // Contract
+  "POST /api/contracts": ["Create a new contract (DRAFT) with routes + cargo scope", "POST", "Contract"],
+  "PATCH /api/contracts/:id": ["Update contract", "PATCH", "Contract"],
+  "DELETE /api/contracts/:id": ["Soft-delete DRAFT contract", "DELETE", "Contract"],
+  "POST /api/contracts/:id/approval-steps/:stepId/approve": ["Approve one approval step in sequence", "POST", "Contract"],
+  "POST /api/contracts/:id/approval-steps/:stepId/reject": ["Reject one approval step — to the customer (terminal → REJECTED) or, via returnToStepId, back to an earlier approver (chain re-runs from there)", "POST", "Contract"],
+  "POST /api/contracts/:id/booking-requests": ["Customer submits a shipment request on a GENERAL customs contract", "POST", "Contract"],
+  "POST /api/contracts/:id/bookings": ["Create a shipment booking under a contract — Path A (customer) or Path B (GL Ethiopia)", "POST", "Contract"],
+  "POST /api/contracts/:id/bookings/:bookingId/complete": ["Complete an initiated booking after Operations finalized its clearance — cargo + binding day, window and departure checks, pricing and invoicing", "POST", "Contract"],
+  "POST /api/contracts/:id/bookings/initiate": ["Initiate a bare booking instance under an import/export contract (ONE_TIME or GENERAL) — no cargo, no date; enters per-booking clearance (AWAITING_DOCUMENTS). ONE_TIME customs instances are opened by the customer (or GL); GENERAL customs comes from a shipment request", "POST", "Contract"],
+  "POST /api/contracts/:id/cancel": ["Customer cancels their own contract (blocked while a booking is live)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/declaration": ["GL ET uploads customs declaration documents (multi-file)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/delivery-order": ["GL DJ uploads Delivery Order (import) with vessel arrival + DO collected dates", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/documents": ["Customer uploads clearance documents (fieldname = document key)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/documents/:fileKey/replace": ["GL replaces a clearance document in place (reason required) — the previous version is kept in the file history and the new one needs approving", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/duty": ["GL ET sets duty/tax requirement and advises amount with notice attachment", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/duty-slip": ["Customer uploads duty/tax payment slip on contract", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/duty/dispute": ["Customer disputes the advised duty/tax with a reason — reopens the step so GL Ethiopia can re-advise (repeatable)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/export-release": ["GL ET confirms export release after declaration", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/finalize": ["GL ET finalizes clearance → CLEARANCE_READY_FOR_BOOKING (legacy)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/finalize-export-clearance": ["GL ET finalizes export clearance after post-booking transit permit upload", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/finalize-pre-clearance": ["GL ET finalizes import pre-clearance — unlocks Djibouti DO upload", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/ops-finalize": ["Operations finalizes self-clearance → customer may create the booking", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/ops-review": ["Operations reviews a customer self-clearance document (Approve | Query)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/output-documents": ["GL uploads customs output documents (IM4/EX3/…) pre-booking", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/release-order": ["GL DJ uploads Release Order + vessel departure date (export)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/review": ["GL ET reviews a clearance document (Approve | Query)", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/ro-amendment": ["GL DJ requests port amendment when RO vessel window is too short", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/transit-assignee/assign": ["GL Djibouti picks the transit officer from the roster — unblocks the customs declaration; calling again reassigns", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/transit-assignee/request": ["GL ET asks GL Djibouti to name the transit officer — required before the customs declaration", "POST", "Contract"],
+  "POST /api/contracts/:id/clearance/transit-permit": ["GL ET uploads import transit permit documents (multi-file)", "POST", "Contract"],
+  "POST /api/contracts/:id/confirm-submit": ["Confirm submit after a price change", "POST", "Contract"],
+  "POST /api/contracts/:id/contract/generate": ["Generate contract document → CONTRACT_READY", "POST", "Contract"],
+  "POST /api/contracts/:id/contract/send-signing-otp": ["Send the sudo-mode signing OTP to the contract company's registered phone (server picks the number)", "POST", "Contract"],
+  "POST /api/contracts/:id/contract/sign": ["Apply digital signature (customer or staff/director/ceo)", "POST", "Contract"],
+  "PUT /api/contracts/:id/document/articles": ["Edit this contract\\'s document articles only (per-contract; never touches the six shared templates)", "PUT", "Contract"],
+  "POST /api/contracts/:id/documents": ["Upload intake documents for a contract (DRAFT only)", "POST", "Contract"],
+  "POST /api/contracts/:id/generate-price": ["Generate unit-rate breakdown (no totals at contract phase)", "POST", "Contract"],
+  "POST /api/contracts/:id/milestones/:code/complete": ["GL marks a pre-booking (contract) milestone complete", "POST", "Contract"],
+  "POST /api/contracts/:id/renew": ["Create a renewal draft linked via renewalOfId", "POST", "Contract"],
+  "POST /api/contracts/:id/resume": ["Staff lift a suspension — contract returns to its prior status", "POST", "Contract"],
+  "POST /api/contracts/:id/staff/accept": ["Staff accept → set validity window + start approval chain", "POST", "Contract"],
+  "POST /api/contracts/:id/staff/reject": ["Staff reject contract", "POST", "Contract"],
+  "POST /api/contracts/:id/staff/request-changes": ["Staff return contract for customer updates", "POST", "Contract"],
+  "POST /api/contracts/:id/submit": ["Customer submit contract (freezes contract_rate_snapshots)", "POST", "Contract"],
+  "POST /api/contracts/:id/suspend": ["Staff freeze a signed contract (reversible, any post-signature step)", "POST", "Contract"],
+  "POST /api/contracts/:id/validate-shipment": ["Pre-create validation + authoritative price preview: full booking price breakdown (rail, first/last mile, surcharges), overweight lines and 20ft weight-pairing errors for a shipment payload (no booking created)", "POST", "Contract"],
+  "POST /api/contracts/booking-requests/:reqId/accept": ["GL marks a shipment request accepted + links the created booking", "POST", "Contract"],
+  "POST /api/contracts/booking-requests/:reqId/cancel": ["Customer cancels their own pending shipment request", "POST", "Contract"],
+  "POST /api/contracts/booking-requests/:reqId/reject": ["GL rejects a shipment request", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/documents": ["GL uploads post-booking operational documents (DO/RO/T1/…)", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/duty": ["GL ET advises duty & tax amount + declaration serial", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/duty-slip": ["Customer uploads the duty/tax payment slip", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/final-invoice": ["GL DJ raises the post-offload final invoice (amount + invoice document)", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/final-invoice-slip": ["Customer attaches the payment slip for the final invoice", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/final-invoice/approve": ["Customer approves the drafted final invoice — unlocks the payment slip", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/final-invoice/confirm": ["GL (ET or DJ) confirms the payment slip — settles the final invoice", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/incidents": ["GL DJ logs a cargo exception with photo evidence", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/milestones/:code/complete": ["GL / Ops / Terminal marks a post-booking milestone complete", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/risk": ["GL ET assigns a customs risk level (GREEN/YELLOW/RED)", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/second-duty": ["GL ET advises (or skips) the post-arrival additional duty/tax round (import)", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/second-duty-slip": ["Customer attaches the additional duty/tax payment slip", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/station-assign": ["GL station manager routes the shipment + binds staff", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/t1-close": ["Close (accept) the T1 set — GL ET after arrival (import) / GL DJ after gate pass (export)", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/t1-documents": ["GL Djibouti uploads T1 transit documents (multi-file) after wagon allocation; locked once the train departs", "POST", "Contract"],
+  "POST /api/contracts/bookings/:bookingId/transport-document": ["GL ET uploads export transit permit documents (multi-file)", "POST", "Contract"],
+  "POST /api/gl-exchange/:entityId": ["Share a document with the other GL desk", "POST", "Contract"],
+  "PATCH /api/gl-exchange/documents/:documentId": ["Uploader edits a shared document (title, visibility, file)", "PATCH", "Contract"],
+  "DELETE /api/gl-exchange/documents/:documentId": ["Uploader removes a shared document", "DELETE", "Contract"],
+
+  // Contract Template
+  "POST /api/contract-templates": ["Create a bulk contract template for a (cargo type, customs option) pair", "POST", "Contract Template"],
+  "PATCH /api/contract-templates/:code": ["Update template metadata (name, title, recitals, active flag)", "PATCH", "Contract Template"],
+  "DELETE /api/contract-templates/:code": ["Delete a staff-created bulk template (system templates refuse)", "DELETE", "Contract Template"],
+  "POST /api/contract-templates/:code/articles": ["Add an article to the template", "POST", "Contract Template"],
+  "PUT /api/contract-templates/:code/articles": ["Replace the full ordered article list (used for reorder)", "PUT", "Contract Template"],
+  "PATCH /api/contract-templates/:code/articles/:articleId": ["Update an article's title or body", "PATCH", "Contract Template"],
+  "DELETE /api/contract-templates/:code/articles/:articleId": ["Remove an article from the template", "DELETE", "Contract Template"],
+  "POST /api/contract-templates/:code/preview": ["Render an HTML preview of the template against mock contract data", "POST", "Contract Template"],
+
+  // Driver
+  "POST /api/drivers": ["Create a new driver", "POST", "Driver"],
+  "PATCH /api/drivers/:id": ["Update a driver", "PATCH", "Driver"],
+  "DELETE /api/drivers/:id": ["Delete a driver", "DELETE", "Driver"],
+  "POST /api/drivers/:id/documents": ["Upload driver documents (code driver_docs)", "POST", "Driver"],
+  "DELETE /api/drivers/:id/documents/:fileId": ["Delete a driver document", "DELETE", "Driver"],
+
+  // Dropdown Setting
+  "POST /api/dropdown-settings": ["Create a new dropdown setting", "POST", "Dropdown Setting"],
+  "PATCH /api/dropdown-settings/:id": ["Update a dropdown setting's metadata", "PATCH", "Dropdown Setting"],
+  "DELETE /api/dropdown-settings/:id": ["Soft-delete a dropdown setting", "DELETE", "Dropdown Setting"],
+  "POST /api/dropdown-settings/:id/options": ["Append a single option to a setting", "POST", "Dropdown Setting"],
+  "PUT /api/dropdown-settings/:id/options": ["Replace the full option list for a setting", "PUT", "Dropdown Setting"],
+  "PATCH /api/dropdown-settings/options/:optionId": ["Update a single option", "PATCH", "Dropdown Setting"],
+  "DELETE /api/dropdown-settings/options/:optionId": ["Soft-delete a single option", "DELETE", "Dropdown Setting"],
+
+  // EIMS Invoice
+  "POST /api/invoices/:id/eims/register": ["Register the invoice with MoR EIMS. Idempotent — an invoice that already has an IRN is returned unchanged", "POST", "EIMS Invoice"],
+  "POST /api/invoices/:id/eims/resolve": ["Resolve an unacknowledged submission: record the IRN confirmed with MoR, or discard it. Clears the system-wide block", "POST", "EIMS Invoice"],
+  "POST /api/invoices/:id/eims/verify": ["Verify the invoice's stored IRN against EIMS", "POST", "EIMS Invoice"],
+
+  // Exchange Setting
+  "PATCH /api/exchange-settings": ["Set the USD→ETB fallback by hand (used only while CBE is unreachable)", "PATCH", "Exchange Setting"],
+
+  // Facility
+  "POST /api/facilities": ["Create a new facility", "POST", "Facility"],
+  "PATCH /api/facilities/:id": ["Update a facility", "PATCH", "Facility"],
+  "DELETE /api/facilities/:id": ["Delete a facility (soft delete)", "DELETE", "Facility"],
+
+  // Fayda Verification
+  "POST /api/fayda/verification/start": ["Start a VeriFayda 2.0 verification session", "POST", "Fayda Verification"],
+
+  // File Upload Setting
+  "POST /api/file-upload-settings": ["Create a new file upload setting", "POST", "File Upload Setting"],
+  "PATCH /api/file-upload-settings/:id": ["Update a file upload setting's metadata", "PATCH", "File Upload Setting"],
+  "DELETE /api/file-upload-settings/:id": ["Soft-delete a file upload setting", "DELETE", "File Upload Setting"],
+  "POST /api/file-upload-settings/:id/fields": ["Append a single field to a setting", "POST", "File Upload Setting"],
+  "PUT /api/file-upload-settings/:id/fields": ["Replace the full field list for a setting", "PUT", "File Upload Setting"],
+  "PATCH /api/file-upload-settings/fields/:fieldId": ["Update a single field", "PATCH", "File Upload Setting"],
+  "DELETE /api/file-upload-settings/fields/:fieldId": ["Soft-delete a single field", "DELETE", "File Upload Setting"],
+
+  // First Mile
+  "POST /api/first-mile": ["Create a first-mile leg", "POST", "First Mile"],
+  "PATCH /api/first-mile/:id": ["Update a first-mile leg", "PATCH", "First Mile"],
+  "DELETE /api/first-mile/:id": ["Soft-delete a first-mile leg", "DELETE", "First Mile"],
+  "POST /api/first-mile/:id/distances": ["Set per-vehicle actual distances (does not generate an invoice)", "POST", "First Mile"],
+  "POST /api/first-mile/:id/invoice": ["Generate the first-mile delivery-fee invoice", "POST", "First Mile"],
+  "POST /api/first-mile/:id/vehicles": ["Set the vehicles assigned to a first-mile pickup (multi-truck)", "POST", "First Mile"],
+  "POST /api/first-mile/accept/:reference": ["Accept a paid booking and create a first-mile leg", "POST", "First Mile"],
+
+  // Fuel
+  "POST /api/fuel/purchases": ["Record fuel purchase", "POST", "Fuel"],
+
+  // GPS Tracking
+  "POST /api/gps/devices": ["Register a GPS tracker", "POST", "GPS Tracking"],
+  "PATCH /api/gps/devices/:id": ["Update a GPS tracker (name / assigned vehicle)", "PATCH", "GPS Tracking"],
+  "DELETE /api/gps/devices/:id": ["Delete a GPS tracker", "DELETE", "GPS Tracking"],
+
+  // Import Operation
+  "POST /api/import-operations/customs/:bookingId/declaration": ["Batch 12: record declaration serial number", "POST", "Import Operation"],
+  "POST /api/import-operations/customs/:bookingId/documents": ["Batch 12: upload IM4/IM5/T1/permit/payment-slip documents", "POST", "Import Operation"],
+  "POST /api/import-operations/customs/:bookingId/duties-taxes-paid": ["Batch 12: mark duties and taxes paid", "POST", "Import Operation"],
+  "POST /api/import-operations/customs/:bookingId/notify-duties-taxes": ["Batch 12: notify duties and taxes", "POST", "Import Operation"],
+  "POST /api/import-operations/customs/:bookingId/release-permitted": ["Batch 12: mark import release permitted", "POST", "Import Operation"],
+  "POST /api/import-operations/customs/:bookingId/risk": ["Batch 12: assign customs risk", "POST", "Import Operation"],
+  "POST /api/import-operations/djibouti-incidents": ["Batch 8: report a Djibouti import incident / exception", "POST", "Import Operation"],
+  "POST /api/import-operations/empty-container-returns": ["Batch 16: create an empty container return record", "POST", "Import Operation"],
+  "POST /api/import-operations/empty-container-returns/:id/status": ["Batch 16: advance empty container return workflow", "POST", "Import Operation"],
+
+  // Incident
+  "POST /api/incidents": ["Report an incident", "POST", "Incident"],
+  "PATCH /api/incidents/:id": ["Update an incident", "PATCH", "Incident"],
+  "DELETE /api/incidents/:id": ["Delete an incident", "DELETE", "Incident"],
+
+  // Interchange Document
+  "PATCH /api/interchange-documents/:id/acknowledge": ["Acknowledge an interchange document", "PATCH", "Interchange Document"],
+  "PATCH /api/interchange-documents/:id/dispute": ["Dispute an interchange document", "PATCH", "Interchange Document"],
+  "POST /api/interchange-documents/generate-from-schedule": ["Generate interchange document from a train schedule handover", "POST", "Interchange Document"],
+
+  // Last Mile
+  "POST /api/last-mile": ["Create a last-mile leg", "POST", "Last Mile"],
+  "PATCH /api/last-mile/:id": ["Update a last-mile leg", "PATCH", "Last Mile"],
+  "DELETE /api/last-mile/:id": ["Soft-delete a last-mile leg", "DELETE", "Last Mile"],
+  "POST /api/last-mile/:id/detention-times": ["Set each truck\\'s own detention window (arrived at destination / returned)", "POST", "Last Mile"],
+  "POST /api/last-mile/:id/distances": ["Set per-vehicle actual distances (does not generate an invoice)", "POST", "Last Mile"],
+  "POST /api/last-mile/:id/invoice": ["Generate the delivery-fee invoice for a last-mile leg", "POST", "Last Mile"],
+  "POST /api/last-mile/:id/proof-of-delivery": ["Record proof of delivery (signature + photos) and complete the leg", "POST", "Last Mile"],
+  "POST /api/last-mile/:id/vehicles": ["Set the vehicles assigned to a last-mile delivery (multi-truck)", "POST", "Last Mile"],
+  "POST /api/last-mile/:id/warehouse-gate-times": ["Set each truck\\'s warehouse gate arrival/departure times", "POST", "Last Mile"],
+  "POST /api/last-mile/accept/:reference": ["Accept a paid booking and create a last-mile leg", "POST", "Last Mile"],
+
+  // Last Mile Request
+  "POST /api/last-mile-requests/:id/approve": ["Truck & Machinery chief approves the request — the advance defaults to the live last-mile rate; LM contract becomes signable and the advance invoice follows the customer signature", "POST", "Last Mile Request"],
+  "POST /api/last-mile-requests/:id/contract/sign": ["Customer agrees and signs the LM contract — then the advance invoice is issued", "POST", "Last Mile Request"],
+  "POST /api/last-mile-requests/:id/reject": ["Truck & Machinery chief rejects the request with a reason", "POST", "Last Mile Request"],
+  "POST /api/last-mile-requests/:id/submit": ["Customer confirms which containers go via EDR last-mile", "POST", "Last Mile Request"],
+
+  // Locomotive
+  "POST /api/locomotives": ["Create a locomotive", "POST", "Locomotive"],
+  "PATCH /api/locomotives/:id": ["Update a locomotive", "PATCH", "Locomotive"],
+  "POST /api/locomotives/:id/decommission": ["Decommission a locomotive", "POST", "Locomotive"],
+  "DELETE /api/locomotives/:id/permanent": ["Permanently delete a locomotive (irreversible; refused if any train references it)", "DELETE", "Locomotive"],
+
+  // Maintenance
+  "POST /api/maintenance/costs": ["Record maintenance cost", "POST", "Maintenance"],
+  "POST /api/maintenance/intervals": ["Define/adjust a service interval (e.g. oil change every 10,000 km)", "POST", "Maintenance"],
+  "DELETE /api/maintenance/intervals/:id": ["Deactivate a service interval (stops auto-scheduling)", "DELETE", "Maintenance"],
+  "POST /api/maintenance/parts": ["Create part", "POST", "Maintenance"],
+  "PATCH /api/maintenance/parts/:id": ["Update part", "PATCH", "Maintenance"],
+  "DELETE /api/maintenance/parts/:id": ["Delete part", "DELETE", "Maintenance"],
+  "POST /api/maintenance/schedules": ["Schedule maintenance", "POST", "Maintenance"],
+  "PATCH /api/maintenance/schedules/:id": ["Update maintenance schedule", "PATCH", "Maintenance"],
+  "POST /api/maintenance/warranties": ["Create warranty", "POST", "Maintenance"],
+  "DELETE /api/maintenance/warranties/:id": ["Delete warranty", "DELETE", "Maintenance"],
+  "POST /api/maintenance/work-orders": ["Create work order", "POST", "Maintenance"],
+  "PATCH /api/maintenance/work-orders/:id": ["Update work order", "PATCH", "Maintenance"],
+  "DELETE /api/maintenance/work-orders/:id": ["Delete work order", "DELETE", "Maintenance"],
+
+  // Notification Inbox
+  "PATCH /api/notifications/:id/read": ["Mark one of my notifications as read", "PATCH", "Notification Inbox"],
+  "POST /api/notifications/read-all": ["Mark all my notifications as read", "POST", "Notification Inbox"],
+
+  // Organization User
+  "PUT /api/backoffice/organizations/:orgId/employee-users/:userId/roles": ["Replace org-scoped roles assigned to an employee user", "PUT", "Organization User"],
+  "POST /api/backoffice/organizations/:orgId/users": ["Create an organization user without assigning positions", "POST", "Organization User"],
+
+  // OTP
+  "POST /api/otp/send": ["Send OTP", "POST", "OTP"],
+  "POST /api/otp/verify": ["Verify OTP", "POST", "OTP"],
+
+  // Password Reset
+  "POST /api/auth/forgot-password/request": ["Send a password-reset code to the account's email AND phone", "POST", "Password Reset"],
+  "POST /api/auth/forgot-password/resolve-link": ["Validate a staff-issued reset link and return its set-password ticket", "POST", "Password Reset"],
+  "POST /api/auth/forgot-password/verify": ["Exchange a valid reset code for a single-use set-password ticket", "POST", "Password Reset"],
+  "POST /api/backoffice/customers/:companyId/reset-password": ["Send a password-reset link to a customer's primary contact", "POST", "Password Reset"],
+
+  // Payment
+  "POST /api/billing/invoices/:id/confirm-offline": ["Finance confirms a USD invoice paid by bank transfer — slip file required, settles the full balance", "POST", "Payment"],
+  "POST /api/billing/my-invoices/:id/confirm": ["Confirm an OTP-debit payment (CAC Bank) for one of the customer's invoices", "POST", "Payment"],
+  "POST /api/billing/my-invoices/:id/pay": ["Initiate payment for one of the customer's invoices", "POST", "Payment"],
+  "POST /api/internal/payments/bill-query": ["Live still-payable check + payer name for a CBE bill (called while CBE is on the line)", "POST", "Payment"],
+  "POST /api/internal/payments/mark-paid": ["Apply a payment.succeeded / payment.failed event from the payment service (idempotent)", "POST", "Payment"],
+  "POST /api/payments/initiate": ["Initiate payment for an invoice", "POST", "Payment"],
+  "POST /api/payments/redirect-success/:bookingId": ["Success-redirect ack: mark payment processing + invoice PAYMENT_PROCESSING (webhook remains source of truth)", "POST", "Payment"],
+
+  // Priority Config
+  "POST /api/priority-configs": ["Create a priority config", "POST", "Priority Config"],
+  "PATCH /api/priority-configs/:id": ["Update a priority config", "PATCH", "Priority Config"],
+  "DELETE /api/priority-configs/:id": ["Soft-delete a priority config", "DELETE", "Priority Config"],
+  "POST /api/priority-configs/:id/move-order": ["Move a priority config up or down in display order", "POST", "Priority Config"],
+  "POST /api/priority-configs/reorder": ["Bulk reorder priority configs by ID list", "POST", "Priority Config"],
+
+  // Priority Rule Change Request
+  "POST /api/priority-rule-change-requests": ["Submit a priority-rule change for approval", "POST", "Priority Rule Change Request"],
+  "POST /api/priority-rule-change-requests/:id/approve": ["Approve and apply a pending change", "POST", "Priority Rule Change Request"],
+  "POST /api/priority-rule-change-requests/:id/reject": ["Reject a pending change", "POST", "Priority Rule Change Request"],
+
+  // Procurement
+  "POST /api/procurement/acquisitions": ["Create an asset acquisition", "POST", "Procurement"],
+  "PATCH /api/procurement/acquisitions/:id": ["Update an asset acquisition", "PATCH", "Procurement"],
+  "DELETE /api/procurement/acquisitions/:id": ["Delete an asset acquisition", "DELETE", "Procurement"],
+  "POST /api/procurement/disposals": ["Create an asset disposal", "POST", "Procurement"],
+  "DELETE /api/procurement/disposals/:id": ["Delete an asset disposal", "DELETE", "Procurement"],
+  "POST /api/procurement/vendors": ["Create a vendor", "POST", "Procurement"],
+  "PATCH /api/procurement/vendors/:id": ["Update a vendor", "PATCH", "Procurement"],
+  "DELETE /api/procurement/vendors/:id": ["Delete a vendor", "DELETE", "Procurement"],
+
+  // Rate
+  "POST /api/rates": ["Create a rate (DRAFT)", "POST", "Rate"],
+  "PATCH /api/rates/:id": ["Update a DRAFT rate", "PATCH", "Rate"],
+  "DELETE /api/rates/:id": ["Soft-delete a rate", "DELETE", "Rate"],
+  "POST /api/rates/:id/approve": ["CEO approves a rate", "POST", "Rate"],
+  "POST /api/rates/:id/submit": ["Submit rate for CEO approval", "POST", "Rate"],
+
+  // Rate Change Request
+  "POST /api/rate-change-requests": ["Propose a change to a LIVE rate", "POST", "Rate Change Request"],
+  "POST /api/rate-change-requests/:id/approve": ["Approve a rate change and put it into effect", "POST", "Rate Change Request"],
+  "POST /api/rate-change-requests/:id/reject": ["Reject a rate change — the rate keeps its current value", "POST", "Rate Change Request"],
+
+  // Route
+  "POST /api/routes": ["Create route", "POST", "Route"],
+  "PATCH /api/routes/:id": ["Update route", "PATCH", "Route"],
+  "DELETE /api/routes/:id": ["Deactivate route", "DELETE", "Route"],
+  "DELETE /api/routes/:id/permanent": ["Permanently delete a route (irreversible; refused while any train schedule references it)", "DELETE", "Route"],
+
+  // Schedule
+  // NOTE: duplicate route — also declared in modules/scheduling-reschedule/scheduling-reschedule.controller.ts:52.
+  // Two controllers register this same path; Nest serves whichever module loads first.
+  "POST /api/train-scheduling/schedules/:id/maintenance": ["Reschedule train for maintenance (new departure + rebalance)", "POST", "Schedule"],
+  "POST /api/train-scheduling/schedules/:id/reschedule/execute": ["Execute a confirmed reschedule plan", "POST", "Schedule"],
+  "POST /api/train-scheduling/schedules/:id/reschedule/preview": ["Preview reschedule / government preempt plan", "POST", "Schedule"],
+
+  // Service Type
+  "POST /api/service-types": ["Create a service type", "POST", "Service Type"],
+  "PATCH /api/service-types/:id": ["Update a service type", "PATCH", "Service Type"],
+  "DELETE /api/service-types/:id": ["Soft-delete a service type", "DELETE", "Service Type"],
+  "POST /api/service-types/:id/move-order": ["Move a service type up or down in display order", "POST", "Service Type"],
+  "POST /api/service-types/reorder": ["Bulk reorder service types by ID list", "POST", "Service Type"],
+
+  // Shipping Line
+  "POST /api/shipping-lines": ["Create a shipping line", "POST", "Shipping Line"],
+  "PATCH /api/shipping-lines/:id": ["Update a shipping line", "PATCH", "Shipping Line"],
+  "DELETE /api/shipping-lines/:id": ["Soft-delete a shipping line", "DELETE", "Shipping Line"],
+
+  // Signature
+  "PUT /api/me/signature": ["Create or update the reusable saved signature", "PUT", "Signature"],
+
+  // Support Chat
+  "POST /api/support/agent/conversations": ["Start chatting with a company (returns the thread if one exists)", "POST", "Support Chat"],
+  "POST /api/support/agent/conversations/:id/messages": ["Reply as an agent, optionally with attachments", "POST", "Support Chat"],
+  "POST /api/support/agent/conversations/:id/read": ["Mark a thread read (agent side)", "POST", "Support Chat"],
+  "POST /api/support/conversation/messages": ["Send a message as the customer (optionally with attachments), opening the thread if needed", "POST", "Support Chat"],
+  "POST /api/support/conversation/read": ["Mark my company's thread read (customer side)", "POST", "Support Chat"],
+
+  // Support Content
+  "PATCH /api/support-content/documents/:slug": ["Replace a document's payload, recording a new version", "PATCH", "Support Content"],
+  "POST /api/support-content/documents/:slug/versions/:version/restore": ["Restore a version — re-saves it as a new version, never destructive", "POST", "Support Content"],
+  "POST /api/support-content/media": ["Upload an image or video for a help section", "POST", "Support Content"],
+
+  // Train
+  "POST /api/trains": ["Register a new train", "POST", "Train"],
+  "PATCH /api/trains/:id": ["Update a train", "PATCH", "Train"],
+  "DELETE /api/trains/:id": ["Delete a train", "DELETE", "Train"],
+
+  // Train Build
+  "POST /api/train-builder": ["Build a train: code + yard + 2+ locomotives (+ optional wagons)", "POST", "Train Build"],
+  "DELETE /api/train-builder/:id": ["Disband the train (release wagons and locomotives)", "DELETE", "Train Build"],
+  "POST /api/train-builder/:id/activate": ["Reactivate a deactivated train back to AVAILABLE", "POST", "Train Build"],
+  "POST /api/train-builder/:id/deactivate": ["Deactivate the train (park it) — only allowed with no active schedule", "POST", "Train Build"],
+  "PATCH /api/train-builder/:id/details": ["Edit the train's name and fixed import/export run numbers", "PATCH", "Train Build"],
+  "PUT /api/train-builder/:id/locomotives": ["Replace the locomotive set (minimum 1, same yard)", "PUT", "Train Build"],
+  "POST /api/train-builder/:id/reorder-wagons": ["Persist a drag-reorder of the full consist", "POST", "Train Build"],
+  "POST /api/train-builder/:id/wagons": ["Append AVAILABLE wagons from the train's yard to the consist", "POST", "Train Build"],
+  "DELETE /api/train-builder/:id/wagons/:wagonId": ["Detach one wagon from the consist", "DELETE", "Train Build"],
+  "POST /api/train-builder/:id/wagons/:wagonId/maintenance": ["Detach one wagon and move it to MAINTENANCE status", "POST", "Train Build"],
+  "PATCH /api/train-builder/:id/yard": ["Relocate the train — its locomotives and wagons move to the new yard with it", "PATCH", "Train Build"],
+
+  // Train Schedule
+  "POST /api/train-scheduling/bookings/:bookingId/allocate": ["Staff: place a paid booking onto a fitting train (notifies customer on date change)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bookings/:bookingId/expire": ["Staff: expire a reservation and free its capacity", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bookings/:bookingId/mark-paid": ["Staff: mark a reserved booking paid and allocate it now", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bookings/:bookingId/move-schedule": ["Re-point a booking to another OPEN same-route schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bulk/preview": ["Preview a bulk train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bulk/schedules": ["Create a bulk train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bulk/schedules/:id/assign-bookings": ["Assign bulk bookings to a train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/bulk/schedules/:id/cancel": ["Cancel bulk train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/container/preview": ["Preview a container train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/container/schedules": ["Create a container train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/container/schedules/:id/assign-bookings": ["Assign container bookings to a train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/container/schedules/:id/cancel": ["Cancel container train schedule", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/global-rules": ["Update global train scheduling rules (singleton)", "PATCH", "Train Schedule"],
+  "POST /api/train-scheduling/preview": ["Preview a mixed-capable train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/adjust-consist": ["Permanently trim free wagons off / couple yard wagons onto the schedule's built train (weight & length limits incl. tolerance enforced, every change logged)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/arrive": ["Mark a dispatched train arrived (move assets to destination yard, free assets)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/assign-bookings": ["Assign bookings to a train schedule (mixed-capable)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/assign-unassigned-booking": ["Assign one linked unallocated booking to wagons (preserves existing assignments)", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/booking-window": ["Open or close a schedule booking window", "PATCH", "Train Schedule"],
+  "DELETE /api/train-scheduling/schedules/:id/bookings/:bookingId": ["Unassign a booking from a train schedule", "DELETE", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/bookings/:bookingId/load": ["Confirm a booking's cargo loaded at its origin yard (any direction; train must be at that yard)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/bookings/:bookingId/unload": ["Confirm a booking's cargo unloaded at its destination yard — per-booking arrival, may precede the train's final arrival", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/checkpoints": ["Log the train passing a station (final station triggers arrival)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/confirm-loading": ["Confirm cargo loaded on the train (any direction; unblocks import-Djibouti dispatch)", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/container-items/:itemId": ["Update a container number on a wagon slot", "PATCH", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/dispatch": ["Dispatch a scheduled train", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/doc-review-complete": ["Staff finished document review early — run the batch/payment phase now (applies to the whole route-day group)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/finalize": ["Finalize a draft train schedule", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/import-djibouti/depart": ["Depart loaded import train from Djibouti", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/import-djibouti/documents": ["Upload/check an import Djibouti-side document", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/import-djibouti/gatepass-granted": ["Mark import Djibouti gatepass permission granted", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/import-djibouti/load-list": ["Generate import load list / marshalling document summary", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/import-djibouti/loaded-on-train": ["Confirm import cargo loaded on train at Djibouti", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/import-djibouti/ready-for-loading": ["Mark import train ready for loading at Djibouti", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/import-loading-status": ["Mark import bookings loaded/unloaded on this schedule (tracking only, does not affect dispatch)", "PATCH", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/intercity/:bookingId/load": ["Confirm intercity cargo loaded (train must be at the booking's origin yard)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/intercity/:bookingId/unload": ["Confirm intercity cargo unloaded at the booking's destination yard (completes the booking)", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/intercity/accept": ["Accept intercity bookings onto this train (opens their pay window; capacity re-checked per booking)", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/loading-status": ["Mark bookings loaded/unloaded on this schedule (any direction, pre-dispatch only)", "PATCH", "Train Schedule"],
+  // NOTE: duplicate route — also declared in modules/train-scheduling/controllers/train-scheduling.controller.ts:798.
+  // Two controllers register this same path; Nest serves whichever module loads first.
+  "POST /api/train-scheduling/schedules/:id/maintenance [modules/train-scheduling/controllers/train-scheduling.controller.ts]": ["Maintenance reschedule: move the train to a new departure with every allocated booking aboard — links, wagons and window settings unchanged", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/pin-wagons": ["Pin physical wagons to train set slots", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/run-allocation": ["Run wagon-level allocation for all eligible linked bookings", "POST", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/run-batch": ["Manually run the batch fill for a schedule", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/schedule-date": ["Reschedule a train's departure date — only before the booking window opens, and only if the new date still leaves room for the booking lead window", "PATCH", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/train-number": ["Edit a departure's train number and voyage number — allowed only until the train is dispatched", "PATCH", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/switch-government-booking": ["Switch out commercial bookings to allocate a government booking in their place", "POST", "Train Schedule"],
+  "DELETE /api/train-scheduling/schedules/:id/wagons/:trainSetWagonId": ["Remove an empty wagon slot from a train", "DELETE", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/wagons/:wagonId/move-load": ["Move a wagon's whole load to another wagon (empty → move/repin, loaded → swap loads)", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/window-rule": ["Override the booking-window rule for one schedule (open/close hour, duration, doc-review, payment, lead days) — only before the window opens", "PATCH", "Train Schedule"],
+
+  // Transit Agent
+  "POST /api/transit-agents": ["Create a transit agent", "POST", "Transit Agent"],
+  "PATCH /api/transit-agents/:id": ["Update a transit agent", "PATCH", "Transit Agent"],
+  "DELETE /api/transit-agents/:id": ["Soft-delete a transit agent", "DELETE", "Transit Agent"],
+
+  // Truck Type
+  "POST /api/truck-types": ["Create a truck type", "POST", "Truck Type"],
+  "PATCH /api/truck-types/:id": ["Update a truck type", "PATCH", "Truck Type"],
+  "DELETE /api/truck-types/:id": ["Soft-delete a truck type", "DELETE", "Truck Type"],
+
+  // User Trade Access
+  "PUT /api/user-trade-access/:userId": ["Set the trade directions a backoffice user may see", "PUT", "User Trade Access"],
+
+  // Vehicle
+  "POST /api/vehicles": ["Create a new vehicle", "POST", "Vehicle"],
+  "PATCH /api/vehicles/:id": ["Update a vehicle", "PATCH", "Vehicle"],
+  "DELETE /api/vehicles/:id": ["Delete a vehicle", "DELETE", "Vehicle"],
+
+  // Wagon
+  "POST /api/wagons": ["Create a new wagon", "POST", "Wagon"],
+  "PATCH /api/wagons/:id": ["Update a wagon", "PATCH", "Wagon"],
+  "DELETE /api/wagons/:id": ["Delete a wagon", "DELETE", "Wagon"],
+  "POST /api/wagons/:id/assign-train": ["Assign wagon to a train", "POST", "Wagon"],
+  "DELETE /api/wagons/:id/permanent": ["Permanently delete a wagon (irreversible; refused if it has movements, containers or train-set slots)", "DELETE", "Wagon"],
+  "POST /api/wagons/:id/unassign-train": ["Unassign wagon from train", "POST", "Wagon"],
+  "POST /api/wagons/bulk-status": ["Set the status of multiple wagons (audited in wagon_status_logs)", "POST", "Wagon"],
+  "POST /api/wagons/bulk-transfer": ["Transfer multiple wagons to a destination yard", "POST", "Wagon"],
+
+  // Wagon Transfer Request
+  "POST /api/wagon-transfer-requests": ["File a count-only wagon-transfer request", "POST", "Wagon Transfer Request"],
+  "POST /api/wagon-transfer-requests/:id/cancel": ["Withdraw a request that has not moved any wagon yet (use close-short once wagons have moved)", "POST", "Wagon Transfer Request"],
+  "POST /api/wagon-transfer-requests/:id/close-short": ["OCC: end the request with fewer wagons than asked for — what moved stays, the requester is told the shortfall", "POST", "Wagon Transfer Request"],
+  "POST /api/wagon-transfer-requests/:id/fulfill": ["OCC: pick wagons and execute the transfer", "POST", "Wagon Transfer Request"],
+  "POST /api/wagon-transfer-requests/bulk-fulfill": ["OCC: accept-and-execute a subset of pending requests (auto-picks available wagons; the rest stay PENDING)", "POST", "Wagon Transfer Request"],
+
+  // Wagon Type
+  "POST /api/wagon-types": ["Create a wagon type", "POST", "Wagon Type"],
+  "PATCH /api/wagon-types/:id": ["Update a wagon type", "PATCH", "Wagon Type"],
+  "DELETE /api/wagon-types/:id": ["Soft-delete a wagon type", "DELETE", "Wagon Type"],
+
+  // Warehouse
+  "POST /api/warehouse-allocation-rules": ["Create a warehouse allocation rule", "POST", "Warehouse"],
+  "PATCH /api/warehouse-allocation-rules/:id": ["Update a warehouse allocation rule", "PATCH", "Warehouse"],
+  "DELETE /api/warehouse-allocation-rules/:id": ["Delete a warehouse allocation rule", "DELETE", "Warehouse"],
+  "POST /api/warehouse-allocation/preview": ["Preview the yard/warehouse/zone a booking would be allocated to", "POST", "Warehouse"],
+  "POST /api/warehouse-fee-rules": ["Create a storage / demurrage fee rule", "POST", "Warehouse"],
+  "PATCH /api/warehouse-fee-rules/:id": ["Update a fee rule", "PATCH", "Warehouse"],
+  "DELETE /api/warehouse-fee-rules/:id": ["Delete a fee rule", "DELETE", "Warehouse"],
+  "POST /api/warehouse-fees/accrual/:inventoryId/acknowledge": ["Acknowledge / snooze an item fee-accrual alert", "POST", "Warehouse"],
+  "DELETE /api/warehouse-fees/accrual/:inventoryId/acknowledge": ["Remove an accrual acknowledgement (re-surface for alerts)", "DELETE", "Warehouse"],
+  "POST /api/warehouses": ["Create warehouse", "POST", "Warehouse"],
+  "PATCH /api/warehouses/:id": ["Update warehouse", "PATCH", "Warehouse"],
+  "POST /api/warehouses/:warehouseId/yards": ["Create a yard within a warehouse", "POST", "Warehouse"],
+
+  // Warehouse Fee Invoice
+  "POST /api/last-mile/:id/generate-truck-detention-invoice": ["Generate a truck-detention invoice for a last-mile leg (per truck per day)", "POST", "Warehouse Fee Invoice"],
+  "PATCH /api/warehouse-fee-invoices/:id/cancel": ["Cancel a warehouse fee invoice", "PATCH", "Warehouse Fee Invoice"],
+  "POST /api/warehouse-fee-invoices/:id/pay": ["Record a payment against a warehouse fee invoice", "POST", "Warehouse Fee Invoice"],
+  "POST /api/warehouse-fee-invoices/:id/pay-online": ["Initiate Telebirr/Waafi payment for a warehouse fee invoice", "POST", "Warehouse Fee Invoice"],
+  "POST /api/warehouse-inventory/:id/generate-fee-invoice": ["Generate a warehouse fee invoice from Batch 5 fee calculation", "POST", "Warehouse Fee Invoice"],
+
+  // Warehouse Inspection Report
+  "PATCH /api/warehouse-inspection-reports/:id": ["Update an inspection report", "PATCH", "Warehouse Inspection Report"],
+  "POST /api/warehouse-inspection-reports/:id/attachments": ["Upload inspection images / documents", "POST", "Warehouse Inspection Report"],
+  "POST /api/warehouse-inventory/:inventoryId/inspection-reports": ["Create an inspection / damage report for an inventory item", "POST", "Warehouse Inspection Report"],
+
+  // Warehouse Inventory
+  "POST /api/warehouse-inventory/:id/deliver": ["Deliver import goods to the customer + capture proof of delivery", "POST", "Warehouse Inventory"],
+  "PATCH /api/warehouse-inventory/:id/dispatch": ["Mark loaded inventory DISPATCHED (left the terminal)", "PATCH", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/gate-clearance": ["Final terminal release / gate clearance (blocked while fees unpaid)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/load": ["Load READY_FOR_LOADING inventory onto a wagon", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/move": ["Move inventory to another warehouse/yard/zone", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/ready-for-loading": ["Mark reserved inventory READY_FOR_LOADING", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/ready-for-pickup": ["Mark inspected IMPORT inventory READY_FOR_PICKUP", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/release": ["Issue a DO / release order for ready-for-pickup inventory", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/:id/store": ["Mark received inventory as STORED (optional explicit warehouse/yard/zone)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/auto-load-ready": ["Auto-load READY_FOR_LOADING inventory with PAID bookings", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/auto-unload-arrived": ["Bulk auto-unload all arrived bookings into the warehouse", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/bookings/:bookingId/approve-delivery": ["Approve delivery — customer records their full name (signature optional)", "POST", "Warehouse Inventory"],
+  "PATCH /api/warehouse-inventory/bookings/:bookingId/double-handling": ["Record Yes/No double handling after unloading (Yes applies the double-handling fee rule)", "PATCH", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/bookings/:bookingId/request-handover-signature": ["Ask the customer to sign the handover (creates one if none, then notifies)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/bookings/:bookingId/unload": ["Unload a single arrived booking into a location", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/bulk-dispatch-export": ["Bulk-dispatch loaded EXPORT inventory (LOADED → DISPATCHED)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/bulk-mark-inspected": ["Bulk mark received inventory inspection PASSED (EXPORT → READY_FOR_LOADING)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/export/auto-unload-at-djibouti": ["Unload all eligible export items assigned to an arrived Djibouti-side train", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/handovers/:handoverId/sign": ["Customer signs one handover (EDR last-mile: one signature per truck)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/import/auto-unload-arrived-bookings": ["Unload all eligible assigned bookings of an ARRIVED import train (→ UNLOADED)", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/receive": ["Receive inventory at a warehouse location", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/receive-bulk": ["Bulk-receive selected eligible PAID bookings into a location", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/reserve": ["Reserve stored inventory for a PAID booking", "POST", "Warehouse Inventory"],
+  "POST /api/warehouse-inventory/train/:scheduleId/load": ["Load selected inventory items onto their allocated wagons for a train", "POST", "Warehouse Inventory"],
+
+  // Warehouse Yard
+  "PATCH /api/warehouse-yards/:id": ["Update warehouse yard", "PATCH", "Warehouse Yard"],
+  "POST /api/warehouse-yards/:yardId/zones": ["Create a zone within a yard", "POST", "Warehouse Yard"],
+
+  // Warehouse Zone
+  "PATCH /api/warehouse-zones/:id": ["Update warehouse zone", "PATCH", "Warehouse Zone"],
+
+  // Weight Limit Rule
+  "POST /api/weight-limit-rules": ["Create a weight limit rule", "POST", "Weight Limit Rule"],
+  "PATCH /api/weight-limit-rules/:id": ["Update a weight limit rule", "PATCH", "Weight Limit Rule"],
+  "DELETE /api/weight-limit-rules/:id": ["Soft-delete a weight limit rule", "DELETE", "Weight Limit Rule"],
+
+  // Yard
+  "POST /api/yards": ["Create a yard", "POST", "Yard"],
+  "PATCH /api/yards/:id": ["Update a yard", "PATCH", "Yard"],
+  "DELETE /api/yards/:id": ["Soft-delete a yard", "DELETE", "Yard"],
+  "POST /api/yards/:id/move-order": ["Move a yard up or down in display order", "POST", "Yard"],
+  "POST /api/yards/reorder": ["Bulk reorder yards by ID list", "POST", "Yard"],
+
+  // Yard Distance
+  "POST /api/yard-distances": ["Create a yard distance", "POST", "Yard Distance"],
+  "PATCH /api/yard-distances/:id": ["Update a yard distance", "PATCH", "Yard Distance"],
+  "DELETE /api/yard-distances/:id": ["Soft-delete a yard distance", "DELETE", "Yard Distance"],
+};
diff --git a/apps/edr-freight-api/src/modules/audit/audit-log.repository.ts b/apps/edr-freight-api/src/modules/audit/audit-log.repository.ts
new file mode 100644
index 000000000..91d6c9901
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/audit/audit-log.repository.ts
@@ -0,0 +1,79 @@
+import { Injectable } from '@nestjs/common';
+import { BaseRepository } from '@edr/api-common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Between, FindOptionsWhere, LessThanOrEqual, MoreThanOrEqual, Repository } from 'typeorm';
+import type { QueryDeepPartialEntity } from 'typeorm/query-builder/QueryPartialEntity';
+
+import { AuditLog } from './entities/audit-log.entity';
+
+export interface AuditLogQuery {
+  type?: string;
+  userId?: string;
+  method?: string;
+  isSuccess?: boolean;
+  resourceId?: string;
+  from?: Date;
+  to?: Date;
+  skip: number;
+  take: number;
+}
+
+@Injectable()
+export class AuditLogRepository extends BaseRepository<AuditLog> {
+  constructor(
+    @InjectRepository(AuditLog)
+    private readonly auditLogRepository: Repository<AuditLog>,
+  ) {
+    super(auditLogRepository);
+  }
+
+  /**
+   * Insert one audit row.
+   *
+   * `insert` rather than `save`: save would issue a SELECT first to decide
+   * between insert and update, which is wasted work for a table that is only
+   * ever appended to.
+   */
+  async record(entry: Partial<AuditLog>): Promise<void> {
+    await this.auditLogRepository.insert(
+      entry as QueryDeepPartialEntity<AuditLog>,
+    );
+  }
+
+  /**
+   * Paginated, filtered read. Newest first — every index on this table is
+   * ordered `created_at DESC` to match.
+   */
+  async search(query: AuditLogQuery): Promise<[AuditLog[], number]> {
+    const where: FindOptionsWhere<AuditLog> = {};
+
+    if (query.type) where.type = query.type;
+    if (query.userId) where.userId = query.userId;
+    if (query.method) where.method = query.method;
+    if (query.resourceId) where.resourceId = query.resourceId;
+    if (query.isSuccess !== undefined) where.isSuccess = query.isSuccess;
+
+    // Date range: either bound may be supplied alone.
+    if (query.from && query.to) where.createdAt = Between(query.from, query.to);
+    else if (query.from) where.createdAt = MoreThanOrEqual(query.from);
+    else if (query.to) where.createdAt = LessThanOrEqual(query.to);
+
+    return this.auditLogRepository.findAndCount({
+      where,
+      order: { createdAt: 'DESC' },
+      skip: query.skip,
+      take: query.take,
+    });
+  }
+
+  /** Distinct entity types present, for populating a filter dropdown. */
+  async distinctTypes(): Promise<string[]> {
+    const rows = await this.auditLogRepository
+      .createQueryBuilder('audit_log')
+      .select('DISTINCT audit_log.type', 'type')
+      .orderBy('audit_log.type', 'ASC')
+      .getRawMany<{ type: string }>();
+
+    return rows.map((row) => row.type);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/audit/audit.controller.ts b/apps/edr-freight-api/src/modules/audit/audit.controller.ts
new file mode 100644
index 000000000..1a07a5fe5
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/audit/audit.controller.ts
@@ -0,0 +1,46 @@
+import { Controller, Get, Query } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { PaginatedResponse } from '@edr/types';
+
+import { BookingStaff } from '../../common/booking-guards';
+import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
+import { AuditService } from './audit.service';
+import { AuditLog } from './entities/audit-log.entity';
+import { AuditLogQueryDto } from './dto/audit-log-query.dto';
+
+/**
+ * Read-only view over the audit trail.
+ *
+ * Gated on `edr_freight_app:audit_log:view` — a dedicated view key rather than
+ * the broad `admin` key, so reading the trail can be granted without also
+ * granting write access to everything else.
+ *
+ * There is deliberately no write, update or delete endpoint here — rows are
+ * created only by `AuditInterceptor`, and an audit trail that can be edited
+ * through the API is not an audit trail.
+ */
+@ApiTags('audit')
+@ApiBearerAuth()
+@Controller('audit')
+export class AuditController {
+  constructor(private readonly auditService: AuditService) {}
+
+  @Get('logs')
+  @BookingStaff(FREIGHT_PERMS.auditLog.view)
+  @ApiOperation({
+    summary:
+      'List backoffice audit logs — filter by entity type, user, method, outcome and date range',
+  })
+  list(@Query() query: AuditLogQueryDto): Promise<PaginatedResponse<AuditLog>> {
+    return this.auditService.search(query);
+  }
+
+  @Get('types')
+  @BookingStaff(FREIGHT_PERMS.auditLog.view)
+  @ApiOperation({
+    summary: 'Distinct entity types present in the audit log (filter dropdown)',
+  })
+  types(): Promise<string[]> {
+    return this.auditService.listTypes();
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/audit/audit.interceptor.ts b/apps/edr-freight-api/src/modules/audit/audit.interceptor.ts
new file mode 100644
index 000000000..cf12fd4d3
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/audit/audit.interceptor.ts
@@ -0,0 +1,189 @@
+import {
+  CallHandler,
+  ExecutionContext,
+  HttpException,
+  Injectable,
+  NestInterceptor,
+} from '@nestjs/common';
+import { Observable, tap } from 'rxjs';
+import type { Request, Response } from 'express';
+
+import { AuditService } from './audit.service';
+import {
+  auditEndpointMatcher,
+  type MatchedAuditEndpoint,
+} from './audit-endpoint-matcher';
+import {
+  isAuditableActor,
+  resolveAuditActor,
+  type AuditActorSource,
+} from './audit-actor';
+import { redactUrlQuery, sanitizeRequestPayload } from './audit.sanitizer';
+
+/** Methods that can change state. Everything else is never audited. */
+const AUDITED_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+/** `error_message` ceiling — stack traces do not belong in this column. */
+const MAX_ERROR_LENGTH = 2_000;
+
+type RequestWithUser = Request & {
+  user?: AuditActorSource;
+  files?: unknown;
+  file?: unknown;
+  id?: string;
+};
+
+/**
+ * Writes one `audit_logs` row per state-changing backoffice request.
+ *
+ * An interceptor rather than the two middlewares originally sketched, for one
+ * decisive reason: Express middleware runs BEFORE guards, so `req.user` is not
+ * populated yet. Both the backoffice-only rule and `user_id` would be
+ * unavailable there. Interceptors run after guards and wrap the handler's
+ * result, so a single class covers both halves — request context on the way in,
+ * outcome on the way out — sharing one timer for `duration_ms`.
+ *
+ * Registered globally (see `audit.module.ts`), so new routes are covered
+ * automatically as long as they appear in `AUDIT_ENDPOINTS`.
+ */
+@Injectable()
+export class AuditInterceptor implements NestInterceptor {
+  constructor(private readonly auditService: AuditService) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    // Non-HTTP contexts (the RabbitMQ microservice transport) have no request.
+    if (context.getType() !== 'http') return next.handle();
+
+    const httpContext = context.switchToHttp();
+    const request = httpContext.getRequest<RequestWithUser>();
+
+    if (!AUDITED_METHODS.has(request.method)) return next.handle();
+
+    // Backoffice only. Customers and unauthenticated callers are skipped
+    // outright — decided in `audit-actor.ts`, which reuses the same
+    // `userType` discriminator as the permission guards.
+    if (!isAuditableActor(request.user)) return next.handle();
+
+    const matched = auditEndpointMatcher.match(request.method, request.originalUrl);
+    // Not in AUDIT_ENDPOINTS means the route is not a known auditable action;
+    // recording it would produce rows with no title or entity.
+    if (!matched) return next.handle();
+
+    const startedAt = Date.now();
+    // The body is captured up front: handlers are free to mutate the DTO they
+    // are given, so reading it after the fact can record post-mutation values.
+    const requestPayload = sanitizeRequestPayload(
+      request.body,
+      request.files ?? request.file,
+    );
+
+    return next.handle().pipe(
+      tap({
+        next: () => {
+          const response = httpContext.getResponse<Response>();
+          void this.write(request, matched, requestPayload, startedAt, {
+            isSuccess: true,
+            // Nest has not applied the handler's @HttpCode yet at this point
+            // for some routes; statusCode on the response object is the value
+            // actually being sent.
+            statusCode: response.statusCode,
+            errorMessage: null,
+          });
+        },
+        error: (error: unknown) => {
+          void this.write(request, matched, requestPayload, startedAt, {
+            isSuccess: false,
+            statusCode: resolveErrorStatus(error),
+            errorMessage: resolveErrorMessage(error),
+          });
+        },
+      }),
+    );
+  }
+
+  /**
+   * Build and persist the row.
+   *
+   * Deliberately not awaited by `intercept`: the audit write must not add
+   * latency to the request, and `AuditService.record` already swallows its own
+   * failures so a rejected promise cannot surface as an unhandled rejection.
+   */
+  private async write(
+    request: RequestWithUser,
+    matched: MatchedAuditEndpoint,
+    requestPayload: Record<string, unknown> | null,
+    startedAt: number,
+    outcome: {
+      isSuccess: boolean;
+      statusCode: number | null;
+      errorMessage: string | null;
+    },
+  ): Promise<void> {
+    const actor = resolveAuditActor(request.user as AuditActorSource);
+
+    await this.auditService.record({
+      title: matched.title,
+      method: request.method,
+      // Full URL including query string, with sensitive query values redacted.
+      url: redactUrlQuery(request.originalUrl),
+      routePath: matched.routePath,
+      type: matched.type,
+      isSuccess: outcome.isSuccess,
+      statusCode: outcome.statusCode,
+      errorMessage: outcome.errorMessage,
+      userId: actor.userId,
+      userName: actor.userName,
+      userRole: actor.userRole,
+      resourceId: matched.resourceId,
+      request: requestPayload,
+      ipAddress: resolveIp(request),
+      userAgent: request.headers['user-agent'] ?? null,
+      requestId: resolveRequestId(request),
+      durationMs: Date.now() - startedAt,
+    });
+  }
+}
+
+/** HTTP status for the failure, falling back to 500 for non-HTTP errors. */
+function resolveErrorStatus(error: unknown): number {
+  return error instanceof HttpException ? error.getStatus() : 500;
+}
+
+/** Message only — stack traces belong in application logs, not this column. */
+function resolveErrorMessage(error: unknown): string | null {
+  if (error instanceof HttpException) {
+    const response = error.getResponse();
+    const message =
+      typeof response === 'string'
+        ? response
+        : ((response as { message?: unknown })?.message ?? error.message);
+    const text = Array.isArray(message) ? message.join('; ') : String(message);
+    return text.slice(0, MAX_ERROR_LENGTH);
+  }
+
+  if (error instanceof Error) return error.message.slice(0, MAX_ERROR_LENGTH);
+  return error ? String(error).slice(0, MAX_ERROR_LENGTH) : null;
+}
+
+/**
+ * Client IP. The API sits behind a reverse proxy, so `req.ip` is the proxy
+ * unless `trust proxy` is set; the forwarded header is preferred and its first
+ * entry (the original client) taken.
+ */
+function resolveIp(request: Request): string | null {
+  const forwarded = request.headers['x-forwarded-for'];
+  const raw = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+  const candidate = raw?.split(',')[0]?.trim() || request.ip;
+  if (!candidate) return null;
+
+  // Normalize IPv4-mapped IPv6 (`::ffff:10.0.0.1`), which the `inet` column
+  // accepts but which reads badly and breaks grouping by address.
+  return candidate.startsWith('::ffff:') ? candidate.slice(7) : candidate;
+}
+
+/** Correlation id from the proxy/tracing layer, when present. */
+function resolveRequestId(request: RequestWithUser): string | null {
+  const header = request.headers['x-request-id'] ?? request.headers['x-correlation-id'];
+  const value = Array.isArray(header) ? header[0] : header;
+  return (value ?? request.id ?? null)?.toString().slice(0, 64) ?? null;
+}
diff --git a/apps/edr-freight-api/src/modules/audit/audit.module.ts b/apps/edr-freight-api/src/modules/audit/audit.module.ts
new file mode 100644
index 000000000..608af3672
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/audit/audit.module.ts
@@ -0,0 +1,34 @@
+import { Global, Module } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { AuditController } from './audit.controller';
+import { AuditInterceptor } from './audit.interceptor';
+import { AuditLog } from './entities/audit-log.entity';
+import { AuditLogRepository } from './audit-log.repository';
+import { AuditService } from './audit.service';
+
+/**
+ * Backoffice audit trail.
+ *
+ * `AuditInterceptor` is bound through `APP_INTERCEPTOR`, so it applies to every
+ * route in the application without touching the 488 mutating handlers
+ * individually. Coverage therefore follows `AUDIT_ENDPOINTS`: a new route is
+ * audited as soon as it appears in that map, and unknown routes are skipped
+ * rather than recorded with an empty title.
+ *
+ * Global so other modules can inject `AuditService` to record domain events
+ * that do not map cleanly onto an HTTP request.
+ */
+@Global()
+@Module({
+  imports: [TypeOrmModule.forFeature([AuditLog])],
+  controllers: [AuditController],
+  providers: [
+    AuditLogRepository,
+    AuditService,
+    { provide: APP_INTERCEPTOR, useClass: AuditInterceptor },
+  ],
+  exports: [AuditService, AuditLogRepository],
+})
+export class AuditModule {}
diff --git a/apps/edr-freight-api/src/modules/audit/audit.sanitizer.ts b/apps/edr-freight-api/src/modules/audit/audit.sanitizer.ts
new file mode 100644
index 000000000..3a934beea
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/audit/audit.sanitizer.ts
@@ -0,0 +1,195 @@
+/**
+ * Redaction and shrinking for anything copied into `audit_logs.request`.
+ *
+ * This matters more here than in a typical audit log. `main.ts` raises the JSON
+ * body ceiling to 100MB so contract signing can post a signature AND a company
+ * stamp as base64 in one request. Copying a body like that verbatim would put
+ * both a credential-grade artefact and a 100MB blob into the audit table, on
+ * the write path of every audited endpoint.
+ */
+
+const REDACTED = '[REDACTED]';
+
+/**
+ * Substring-matched against lower-cased key names, so `newPassword`,
+ * `otpCode` and `x-authorization` are all caught without enumerating variants.
+ *
+ * `signature` and `stamp` are here because contract signing posts both as
+ * base64 — they are simultaneously the largest and the most sensitive fields
+ * this API accepts.
+ */
+const SENSITIVE_KEY_PATTERNS = [
+  'password',
+  'otp',
+  'token',
+  'secret',
+  'pin',
+  'authorization',
+  'signature',
+  'stamp',
+  'apikey',
+  'api_key',
+  'credential',
+  'ssn',
+];
+
+/** Serialized `request` ceiling. Beyond this the payload is dropped for a marker. */
+const MAX_REQUEST_BYTES = 64 * 1024;
+
+/** Depth guard: deep nesting is never worth the recursion cost here. */
+const MAX_DEPTH = 6;
+
+/** Long strings (base64 blobs) are truncated rather than stored whole. */
+const MAX_STRING_LENGTH = 2_000;
+
+function isSensitiveKey(key: string): boolean {
+  const lower = key.toLowerCase();
+  return SENSITIVE_KEY_PATTERNS.some((pattern) => lower.includes(pattern));
+}
+
+/**
+ * Multer file shape, reduced to a descriptor. The buffer is never stored —
+ * Postgres is the wrong home for file bytes, and `audit_logs` doubly so.
+ */
+function isMulterFile(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null) return false;
+  const candidate = value as Record<string, unknown>;
+  return (
+    typeof candidate.originalname === 'string' &&
+    (typeof candidate.mimetype === 'string' || typeof candidate.size === 'number')
+  );
+}
+
+function describeFile(value: Record<string, unknown>): Record<string, unknown> {
+  return {
+    __file: true,
+    originalName: value.originalname ?? null,
+    mimeType: value.mimetype ?? null,
+    size: typeof value.size === 'number' ? value.size : null,
+    fieldName: value.fieldname ?? null,
+  };
+}
+
+function sanitizeValue(value: unknown, depth: number): unknown {
+  if (value === null || value === undefined) return value ?? null;
+
+  if (typeof value === 'string') {
+    return value.length > MAX_STRING_LENGTH
+      ? `${value.slice(0, MAX_STRING_LENGTH)}…[truncated ${value.length} chars]`
+      : value;
+  }
+
+  if (typeof value === 'number' || typeof value === 'boolean') return value;
+  if (value instanceof Date) return value.toISOString();
+  // Buffers are file bytes by definition — never persisted, only described.
+  if (Buffer.isBuffer(value)) return { __buffer: true, size: value.length };
+
+  if (depth >= MAX_DEPTH) return '[MAX_DEPTH]';
+
+  if (Array.isArray(value)) {
+    // Cap array length: bulk endpoints post large collections.
+    const capped = value.slice(0, 50).map((item) => sanitizeValue(item, depth + 1));
+    if (value.length > 50) capped.push(`…[${value.length - 50} more items]`);
+    return capped;
+  }
+
+  if (typeof value === 'object') {
+    if (isMulterFile(value)) return describeFile(value as Record<string, unknown>);
+
+    const out: Record<string, unknown> = {};
+    for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = isSensitiveKey(key) ? REDACTED : sanitizeValue(nested, depth + 1);
+    }
+    return out;
+  }
+
+  // Functions, symbols and anything else are not audit data.
+  return null;
+}
+
+/**
+ * Sanitize a request body (or query object) for storage.
+ *
+ * Returns null when there is nothing worth keeping, so empty bodies do not
+ * occupy jsonb rows.
+ */
+export function sanitizeRequestPayload(
+  body: unknown,
+  files?: unknown,
+): Record<string, unknown> | null {
+  const payload: Record<string, unknown> = {};
+
+  if (body && typeof body === 'object' && Object.keys(body).length > 0) {
+    const sanitizedBody = sanitizeValue(body, 0);
+    if (sanitizedBody && typeof sanitizedBody === 'object') {
+      Object.assign(payload, sanitizedBody as Record<string, unknown>);
+    }
+  }
+
+  // Multer puts uploads on `req.files`, outside `req.body`, so they are folded
+  // in explicitly — otherwise a pure-upload request records an empty payload.
+  if (files) {
+    const sanitizedFiles = sanitizeValue(files, 0);
+    if (
+      sanitizedFiles &&
+      (Array.isArray(sanitizedFiles) || typeof sanitizedFiles === 'object')
+    ) {
+      const hasEntries = Array.isArray(sanitizedFiles)
+        ? sanitizedFiles.length > 0
+        : Object.keys(sanitizedFiles as object).length > 0;
+      if (hasEntries) payload.__uploads = sanitizedFiles;
+    }
+  }
+
+  if (Object.keys(payload).length === 0) return null;
+
+  // Final size guard. A body can stay under every per-field cap and still be
+  // enormous in aggregate, so the serialized form is measured before storing.
+  const serialized = JSON.stringify(payload);
+  if (serialized && Buffer.byteLength(serialized, 'utf8') > MAX_REQUEST_BYTES) {
+    return {
+      __truncated: true,
+      reason: 'Payload exceeded the audit size limit',
+      bytes: Buffer.byteLength(serialized, 'utf8'),
+      keys: Object.keys(payload).slice(0, 50),
+    };
+  }
+
+  return payload;
+}
+
+/**
+ * Rebuild a URL with sensitive query values redacted.
+ *
+ * `url` is stored with its full query string, and query strings are a common
+ * place for one-time tokens and signed links, so the same deny-list that
+ * protects the body is applied to the query.
+ */
+export function redactUrlQuery(url: string): string {
+  const queryIndex = url.indexOf('?');
+  if (queryIndex === -1) return url;
+
+  const path = url.slice(0, queryIndex);
+  const query = url.slice(queryIndex + 1);
+  if (!query) return path;
+
+  const redacted = query
+    .split('&')
+    .map((pair) => {
+      const eq = pair.indexOf('=');
+      if (eq === -1) return pair;
+      const key = pair.slice(0, eq);
+      // Keys arrive percent-encoded; decode before matching so `api%2Dkey`
+      // is not treated as harmless.
+      let decodedKey = key;
+      try {
+        decodedKey = decodeURIComponent(key);
+      } catch {
+        /* malformed encoding — fall back to the raw key */
+      }
+      return isSensitiveKey(decodedKey) ? `${key}=${REDACTED}` : pair;
+    })
+    .join('&');
+
+  return `${path}?${redacted}`;
+}
diff --git a/apps/edr-freight-api/src/modules/audit/audit.service.ts b/apps/edr-freight-api/src/modules/audit/audit.service.ts
new file mode 100644
index 000000000..de7dfd956
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/audit/audit.service.ts
@@ -0,0 +1,71 @@
+import { BadRequestException, Injectable, Logger } from '@nestjs/common';
+import { PaginatedResponse } from '@edr/types';
+
+import { AuditLog } from './entities/audit-log.entity';
+import { AuditLogRepository } from './audit-log.repository';
+import { AuditLogQueryDto } from './dto/audit-log-query.dto';
+import {
+  buildPaginationMeta,
+  normalizePagination,
+} from '../../common/utils/pagination.util';
+
+@Injectable()
+export class AuditService {
+  private readonly logger = new Logger(AuditService.name);
+
+  constructor(private readonly auditLogRepository: AuditLogRepository) {}
+
+  /**
+   * Persist one audit row, swallowing any failure.
+   *
+   * An audit write must never turn a successful business action into an error
+   * for the user: if this table is full, misconfigured or mid-migration,
+   * contract approvals still need to work. Failures are logged so the gap is
+   * visible in application logs rather than silent.
+   */
+  async record(entry: Partial<AuditLog>): Promise<void> {
+    try {
+      await this.auditLogRepository.record(entry);
+    } catch (error) {
+      this.logger.error(
+        `Failed to write audit log for ${entry.method} ${entry.routePath}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  /** Paginated, filtered audit history, newest first. */
+  async search(query: AuditLogQueryDto): Promise<PaginatedResponse<AuditLog>> {
+    const { page, pageSize, skip, take } = normalizePagination(query);
+
+    const from = query.from ? new Date(query.from) : undefined;
+    const to = query.to ? new Date(query.to) : undefined;
+
+    // A reversed range silently returns zero rows, which reads as "nothing
+    // happened" rather than "your filter is wrong" — reject it explicitly.
+    if (from && to && from > to) {
+      throw new BadRequestException('`from` must be earlier than `to`');
+    }
+
+    const [items, total] = await this.auditLogRepository.search({
+      type: query.type,
+      userId: query.userId,
+      method: query.method,
+      resourceId: query.resourceId,
+      isSuccess:
+        query.isSuccess === undefined ? undefined : query.isSuccess === 'true',
+      from,
+      to,
+      skip,
+      take,
+    });
+
+    return { items, meta: buildPaginationMeta(total, page, pageSize) };
+  }
+
+  /** Distinct entity types, for the filter dropdown on the audit screen. */
+  async listTypes(): Promise<string[]> {
+    return this.auditLogRepository.distinctTypes();
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/audit/dto/audit-log-query.dto.ts b/apps/edr-freight-api/src/modules/audit/dto/audit-log-query.dto.ts
new file mode 100644
index 000000000..5a5199538
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/audit/dto/audit-log-query.dto.ts
@@ -0,0 +1,64 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { Transform } from 'class-transformer';
+import { IsBooleanString, IsIn, IsISO8601, IsOptional, IsString, IsUUID, MaxLength } from 'class-validator';
+
+import { PaginationQueryDto } from '../../../common/dto/pagination-query.dto';
+
+const AUDITED_METHODS = ['POST', 'PUT', 'PATCH', 'DELETE'] as const;
+
+/**
+ * Filters for the audit log read endpoint.
+ *
+ * Extends the shared pagination DTO so page/pageSize behave (and are capped)
+ * exactly as they do on every other list endpoint.
+ */
+export class AuditLogQueryDto extends PaginationQueryDto {
+  @ApiPropertyOptional({
+    description: 'Entity type, e.g. "Contract", "Booking", "Locomotive".',
+    example: 'Contract',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(50)
+  type?: string;
+
+  @ApiPropertyOptional({ description: 'IAM id of the acting backoffice user.' })
+  @IsOptional()
+  @IsUUID()
+  userId?: string;
+
+  @ApiPropertyOptional({ enum: AUDITED_METHODS })
+  @IsOptional()
+  @Transform(({ value }) => String(value).toUpperCase())
+  @IsIn([...AUDITED_METHODS])
+  method?: string;
+
+  @ApiPropertyOptional({ description: 'Id of the affected record.' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(64)
+  resourceId?: string;
+
+  @ApiPropertyOptional({
+    description: 'Filter by outcome: true = succeeded, false = failed.',
+  })
+  @IsOptional()
+  @IsBooleanString()
+  isSuccess?: string;
+
+  @ApiPropertyOptional({
+    description: 'Inclusive start of the range (ISO 8601).',
+    example: '2026-01-01T00:00:00.000Z',
+  })
+  @IsOptional()
+  @IsISO8601()
+  from?: string;
+
+  @ApiPropertyOptional({
+    description: 'Inclusive end of the range (ISO 8601).',
+    example: '2026-01-31T23:59:59.999Z',
+  })
+  @IsOptional()
+  @IsISO8601()
+  to?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/audit/entities/audit-log.entity.ts b/apps/edr-freight-api/src/modules/audit/entities/audit-log.entity.ts
new file mode 100644
index 000000000..0ff7727ff
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/audit/entities/audit-log.entity.ts
@@ -0,0 +1,132 @@
+import { Column, CreateDateColumn, Entity, Index, PrimaryGeneratedColumn } from 'typeorm';
+
+/**
+ * One backoffice action against a state-changing endpoint.
+ *
+ * Deliberately does NOT extend `BaseEntity`, which is the repo standard
+ * everywhere else. `BaseEntity` carries `updatedAt` and `deletedAt`, and both
+ * are wrong here:
+ *
+ *  - `updatedAt` implies an audit row can be edited. A record that can be
+ *    rewritten after the fact is not evidence.
+ *  - `deletedAt` (soft delete) would let anyone who can delete erase their own
+ *    trail, and TypeORM would then hide those rows from every default query —
+ *    the failure would be silent, which is the worst property an audit log can
+ *    have.
+ *
+ * Rows are insert-only: nothing in this module updates or deletes them.
+ *
+ * `userId` is a bare uuid with NO foreign key into the `iam` schema. Two
+ * reasons: cross-schema FKs are forbidden platform-wide, and a FK would let
+ * deleting a user cascade away the record of what that user did — exactly
+ * backwards. `userName` / `userRole` are point-in-time snapshots for the same
+ * reason: resolving them at read time would rewrite history whenever somebody
+ * is renamed or changes role.
+ */
+@Entity({ schema: 'freight', name: 'audit_logs' })
+// Every audit query is time-bounded, so created_at leads most indexes.
+@Index('IDX_audit_logs_created_at', ['createdAt'])
+@Index('IDX_audit_logs_user_id_created_at', ['userId', 'createdAt'])
+@Index('IDX_audit_logs_type_created_at', ['type', 'createdAt'])
+@Index('IDX_audit_logs_type_resource_id', ['type', 'resourceId'])
+@Index('IDX_audit_logs_route_path_created_at', ['routePath', 'createdAt'])
+export class AuditLog {
+  @PrimaryGeneratedColumn('uuid')
+  id!: string;
+
+  /**
+   * Human-readable action, e.g. "Approve contract" — taken from the matched
+   * entry in `AUDIT_ENDPOINTS`, which sources it from each route's
+   * `@ApiOperation` summary.
+   */
+  @Column({ name: 'title', type: 'varchar', length: 255 })
+  title!: string;
+
+  @Column({ name: 'method', type: 'varchar', length: 10 })
+  method!: string;
+
+  /**
+   * The URL as actually called, real ids and query string included
+   * (`/api/contracts/abc-123/cancel?force=true`). Query values run through the
+   * same redaction pass as the body, so a `?token=` never lands here.
+   */
+  @Column({ name: 'url', type: 'text' })
+  url!: string;
+
+  /**
+   * The route template (`/api/contracts/:id/cancel`).
+   *
+   * `url` alone cannot be grouped — every contract cancel is a distinct string.
+   * This column is the join key back to `AUDIT_ENDPOINTS` and makes
+   * "every contract cancellation" one indexed query instead of a regex scan.
+   */
+  @Column({ name: 'route_path', type: 'varchar', length: 255, nullable: true })
+  routePath?: string | null;
+
+  /** Primary entity the action touched: `Contract`, `Booking`, `Locomotive`. */
+  @Column({ name: 'type', type: 'varchar', length: 50 })
+  type!: string;
+
+  @Column({ name: 'is_success', type: 'boolean' })
+  isSuccess!: boolean;
+
+  /** IAM user id. Nullable by design — see the class comment. */
+  @Column({ name: 'user_id', type: 'uuid', nullable: true })
+  userId?: string | null;
+
+  /**
+   * Id of the affected record, recovered from the first path parameter of the
+   * matched template.
+   *
+   * `varchar`, not `uuid`: not every identifier is a uuid
+   * (`/api/contract-templates/:code`), and a create has no id at all until it
+   * succeeds. A `uuid NOT NULL` column would throw during the write and lose
+   * the audit row rather than the id.
+   */
+  @Column({ name: 'resource_id', type: 'varchar', length: 64, nullable: true })
+  resourceId?: string | null;
+
+  /**
+   * Sanitized request body. Secrets are replaced with `[REDACTED]` and uploads
+   * are reduced to `{ __file, originalName, mimeType, size }` descriptors —
+   * never raw bytes. See `audit.sanitizer.ts`.
+   */
+  @Column({ name: 'request', type: 'jsonb', nullable: true })
+  request?: Record<string, unknown> | null;
+
+  /**
+   * `isSuccess` alone cannot separate 403 (denied — the security signal worth
+   * alerting on) from 500 (broke). Both are simply `false`.
+   */
+  @Column({ name: 'status_code', type: 'smallint', nullable: true })
+  statusCode?: number | null;
+
+  @Column({ name: 'error_message', type: 'text', nullable: true })
+  errorMessage?: string | null;
+
+  /** Snapshot of the actor's display name at the time of the action. */
+  @Column({ name: 'user_name', type: 'varchar', length: 150, nullable: true })
+  userName?: string | null;
+
+  /** Snapshot of the actor's role at the time of the action. */
+  @Column({ name: 'user_role', type: 'varchar', length: 100, nullable: true })
+  userRole?: string | null;
+
+  /** Non-repudiation: the first thing asked in any incident review. */
+  @Column({ name: 'ip_address', type: 'inet', nullable: true })
+  ipAddress?: string | null;
+
+  /** Helps separate a real browser session from a script using a stolen token. */
+  @Column({ name: 'user_agent', type: 'text', nullable: true })
+  userAgent?: string | null;
+
+  /** Correlates this row with application logs/traces for the same request. */
+  @Column({ name: 'request_id', type: 'varchar', length: 64, nullable: true })
+  requestId?: string | null;
+
+  @Column({ name: 'duration_ms', type: 'integer', nullable: true })
+  durationMs?: number | null;
+
+  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
+  createdAt!: Date;
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts b/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
index f10b5f021..9c4b69ad6 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
@@ -1267,18 +1267,18 @@ export class BookingsController {
 
   @Post(':id/clearance/delivery-order')
   @BookingStaff(FREIGHT_PERMS.contracts.clearanceDjActions)
-  @UseInterceptors(FileInterceptor('file'))
+  @UseInterceptors(AnyFilesInterceptor())
   @ApiConsumes('multipart/form-data')
   async uploadBookingDeliveryOrder(
     @Param('id', ParseUUIDPipe) id: string,
-    @UploadedFile() file: Express.Multer.File,
+    @UploadedFiles() files: Express.Multer.File[],
     @Body('vesselArrivalDate') vesselArrivalDate: string | undefined,
     @Body('doCollectedDate') doCollectedDate: string | undefined,
     @CurrentUser() user: TCurrentUser,
   ) {
     const booking = await this.bookingClearanceService.uploadDeliveryOrder(
       id,
-      file,
+      files ?? [],
       resolveAuthUserId(user),
       { vesselArrivalDate, doCollectedDate },
     );
@@ -1287,17 +1287,17 @@ export class BookingsController {
 
   @Post(':id/clearance/release-order')
   @BookingStaff(FREIGHT_PERMS.contracts.clearanceDjActions)
-  @UseInterceptors(FileInterceptor('file'))
+  @UseInterceptors(AnyFilesInterceptor())
   @ApiConsumes('multipart/form-data')
   async uploadBookingReleaseOrder(
     @Param('id', ParseUUIDPipe) id: string,
-    @UploadedFile() file: Express.Multer.File,
+    @UploadedFiles() files: Express.Multer.File[],
     @Body('vesselDepartureDate') vesselDepartureDate: string,
     @CurrentUser() user: TCurrentUser,
   ) {
     const result = await this.bookingClearanceService.uploadReleaseOrder(
       id,
-      file,
+      files ?? [],
       vesselDepartureDate,
       resolveAuthUserId(user),
     );
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
index e2a3d9b0c..121c889bc 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
@@ -59,9 +59,11 @@ import { PdfRenderService } from '../billing/documents/pdf-render.service';
 import { buildTabularFallbackPdf } from '../billing/documents/styled-pdf.util';
 
 /**
- * The allocated train as the backoffice booking detail page needs it: which
- * train, its window phase, and both the planned and actual clock. Attached by
- * `findById` only when the booking is on a schedule.
+ * The train as the backoffice booking detail page needs it: which train, its
+ * window phase, and both the planned and actual clock. Attached by `findById`
+ * for the allocated train (`train_schedule_id`) or, before the batch engine has
+ * allocated one, the train the customer picked at day-commit
+ * (`requested_train_schedule_id`) — see `isRequested`.
  */
 export interface TrainScheduleSummary {
   id: string;
@@ -74,6 +76,12 @@ export interface TrainScheduleSummary {
   actualArrivalAt: string | null;
   windowPhase: string | null;
   paymentPhaseEndsAt: string | null;
+  /**
+   * True when this is the customer's requested train rather than a confirmed
+   * allocation — the state staff review at OPERATION_REQUEST_PENDING, before
+   * accepting the operation puts the booking into the batch pool.
+   */
+  isRequested: boolean;
 }
 
 /** Paginated booking list: flat `total` (backoffice) + `meta` block (portal). */
@@ -2132,15 +2140,23 @@ export class BookingsService {
     // Surface the assigned train's operational status so the portal stepper
     // can show the Arrival stage: the booking status stays IN_TRANSIT from
     // dispatch until delivery, so arrival is only knowable from the schedule.
-    if (booking.trainScheduleId) {
+    // The allocated train, or — before the batch engine has allocated one — the
+    // train the customer picked at day-commit. Staff reviewing an operation
+    // request (OPERATION_REQUEST_PENDING) must see which train they are
+    // accepting onto before they approve, and at that point only the requested
+    // id is set.
+    const summarySourceId = booking.trainScheduleId ?? booking.requestedTrainScheduleId;
+    if (summarySourceId) {
       const schedule = await this.dataSource
         .getRepository(TrainSchedule)
-        .findOne({ where: { id: booking.trainScheduleId } });
+        .findOne({ where: { id: summarySourceId } });
+      // trainScheduleStatus drives the portal's Arrival stage, so it stays tied
+      // to a real allocation — a merely requested train has not departed.
       (booking as Booking & { trainScheduleStatus?: string | null }).trainScheduleStatus =
-        schedule?.status ?? null;
-      // Backoffice staff view: the allocated train's identity and clock, so the
-      // detail page can state which train the booking rides and when it runs
-      // without a second round-trip to the schedules API.
+        booking.trainScheduleId ? (schedule?.status ?? null) : null;
+      // Backoffice staff view: the train's identity and clock, so the detail
+      // page can state which train the booking rides and when it runs without a
+      // second round-trip to the schedules API.
       (
         booking as Booking & { trainScheduleSummary?: TrainScheduleSummary | null }
       ).trainScheduleSummary = schedule
@@ -2155,6 +2171,7 @@ export class BookingsService {
             actualArrivalAt: schedule.actualArrivalAt?.toISOString() ?? null,
             windowPhase: schedule.windowPhase ?? null,
             paymentPhaseEndsAt: schedule.paymentPhaseEndsAt?.toISOString() ?? null,
+            isRequested: !booking.trainScheduleId,
           }
         : null;
     }
diff --git a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts
index df55493de..8c127e840 100644
--- a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts
@@ -291,7 +291,7 @@ describe('BookingClearanceService', () => {
       const { service, bookingsRepository } = makeService({ booking: generalExportBooking });
       const result = await service.uploadReleaseOrder(
         'b-export',
-        { fieldname: 'ro' } as Express.Multer.File,
+        [{ fieldname: 'ro' } as Express.Multer.File],
         dateStr,
       );
 
diff --git a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
index c9c15f8b0..e0d30a2be 100644
--- a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
@@ -1,6 +1,7 @@
 import { BadRequestException, Injectable } from '@nestjs/common';
 import {
   ContractDocPhase,
+  isDeliveryOrderFileCode,
   isDraftDeclarationFileCode,
   type ClearanceFinalInvoiceSummary,
   type ClearanceOffloadState,
@@ -29,7 +30,7 @@ import { GlOperationsService } from './gl-operations.service';
 import { GlExchangeService } from './gl-exchange.service';
 import { TransitAgentsService } from '../transit-agents/transit-agents.service';
 import { AdviseContractDutyDto } from './dto/phased-clearance.dto';
-import { buildWorkflowFiles, belongsOnDjClearanceQueue, belongsOnEtClearanceQueue, DJ_BOOKING_QUEUE_STATUSES, persistDeclarationUploads, persistDraftDeclarationUploads, persistTransitPermitUploads, PHASED_CUSTOMS_BOOKING_QUEUE_STATUSES } from './phased-clearance.util';
+import { buildWorkflowFiles, belongsOnDjClearanceQueue, belongsOnEtClearanceQueue, DJ_BOOKING_QUEUE_STATUSES, persistDeclarationUploads, persistDeliveryOrderUploads, persistDraftDeclarationUploads, persistReleaseOrderUploads, persistTransitPermitUploads, PHASED_CUSTOMS_BOOKING_QUEUE_STATUSES } from './phased-clearance.util';
 
 const RO_VESSEL_MIN_DAYS_CODE = 'ro_vessel_min_days';
 
@@ -813,7 +814,7 @@ export class BookingClearanceService {
 
     // GL Djibouti may have uploaded the DO early (un-gated) — count it now.
     const files = await this.filesService.findByResource(bookingId, 'bookings');
-    if (files.some((f) => f.code === 'delivery_order')) {
+    if (files.some((f) => isDeliveryOrderFileCode(f.code))) {
       await this.workflowService.completeMilestoneForBooking(bookingId, 'DO_COLLECTED');
       await this.workflowService.markReadyForOperation(bookingId);
     }
@@ -823,7 +824,7 @@ export class BookingClearanceService {
 
   async uploadDeliveryOrder(
     bookingId: string,
-    file: Express.Multer.File,
+    files: Express.Multer.File[],
     userId?: string,
     dates?: { vesselArrivalDate?: string; doCollectedDate?: string },
   ): Promise<Booking> {
@@ -832,19 +833,12 @@ export class BookingClearanceService {
       throw new BadRequestException('Delivery Order applies only to import bookings.');
     }
 
-    if (!file) throw new BadRequestException('No Delivery Order uploaded');
-
     const { vesselArrivalDate, doCollectedDate } = assertDoCollectionDates(dates);
 
     // DO upload is deliberately un-gated: GL Djibouti may attach it at any point,
     // any file type. The DO_COLLECTED milestone (and operation readiness) still
     // waits for GL Ethiopia to finalize pre-clearance so the workflow order holds.
-    await this.filesService.upsertByCode({
-      resourceId: bookingId,
-      resource: 'bookings',
-      code: 'delivery_order',
-      file,
-    });
+    await persistDeliveryOrderUploads(this.filesService, bookingId, 'bookings', files ?? []);
 
     await this.bookingsRepository.update(bookingId, {
       vesselArrivalDate,
@@ -880,7 +874,7 @@ export class BookingClearanceService {
 
   async uploadReleaseOrder(
     bookingId: string,
-    file: Express.Multer.File,
+    files: Express.Multer.File[],
     vesselDepartureDate: string,
     userId?: string,
   ): Promise<{ booking: Booking; hold: boolean; holdReason?: string }> {
@@ -894,7 +888,6 @@ export class BookingClearanceService {
       'RELEASE_ORDER_SECURED',
     );
 
-    if (!file) throw new BadRequestException('No Release Order uploaded');
     if (!vesselDepartureDate?.trim()) {
       throw new BadRequestException('Vessel departure date is required');
     }
@@ -902,12 +895,7 @@ export class BookingClearanceService {
     const minDays = await this.resolveRoMinDays();
     const leadDays = this.daysUntil(vesselDepartureDate);
 
-    await this.filesService.upsertByCode({
-      resourceId: bookingId,
-      resource: 'bookings',
-      code: 'release_order',
-      file,
-    });
+    await persistReleaseOrderUploads(this.filesService, bookingId, 'bookings', files ?? []);
 
     await this.bookingsRepository.update(bookingId, {
       vesselDepartureDate,
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 2ebd8fc70..76106a9ff 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
@@ -6,6 +6,7 @@ import {
 } from '@nestjs/common';
 import {
   ContractDocPhase,
+  isDeliveryOrderFileCode,
   type ClearanceFinalInvoiceSummary,
   type ClearanceOffloadState,
   type ClearanceSecondDuty,
@@ -36,7 +37,7 @@ import { Contract } from './entities/contract.entity';
 import { ContractDocReviewStatus } from './entities/contract-document-review.entity';
 import { FilterContractDto } from './dto/filter-contract.dto';
 import { AdviseContractDutyDto } from './dto/phased-clearance.dto';
-import { buildWorkflowFiles, persistDeclarationUploads, persistTransitPermitUploads, PHASED_CUSTOMS_CONTRACT_QUEUE_STATUSES } from './phased-clearance.util';
+import { buildWorkflowFiles, persistDeclarationUploads, persistDeliveryOrderUploads, persistReleaseOrderUploads, persistTransitPermitUploads, PHASED_CUSTOMS_CONTRACT_QUEUE_STATUSES } from './phased-clearance.util';
 
 const RO_VESSEL_MIN_DAYS_CODE = 'ro_vessel_min_days';
 
@@ -1449,7 +1450,7 @@ export class ContractClearanceService {
 
     // GL Djibouti may have uploaded the DO early (un-gated) — count it now.
     const files = await this.filesService.findByResource(contractId, 'contracts');
-    if (files.some((f) => f.code === 'delivery_order')) {
+    if (files.some((f) => isDeliveryOrderFileCode(f.code))) {
       await this.workflowService.completeMilestone(contractId, 'DO_COLLECTED');
       await this.workflowService.markReadyForBooking(contractId);
     }
@@ -1460,7 +1461,7 @@ export class ContractClearanceService {
 
   async uploadDeliveryOrder(
     contractId: string,
-    file: Express.Multer.File,
+    files: Express.Multer.File[],
     userId?: string,
     dates?: { vesselArrivalDate?: string; doCollectedDate?: string },
   ): Promise<Contract> {
@@ -1470,19 +1471,12 @@ export class ContractClearanceService {
       throw new BadRequestException('Delivery Order applies only to import contracts.');
     }
 
-    if (!file) throw new BadRequestException('No Delivery Order uploaded');
-
     const { vesselArrivalDate, doCollectedDate } = assertDoCollectionDates(dates);
 
     // DO upload is deliberately un-gated: GL Djibouti may attach it at any point,
     // any file type. The DO_COLLECTED milestone (and booking readiness) still waits
     // for GL Ethiopia to finalize pre-clearance so the workflow order holds.
-    await this.filesService.upsertByCode({
-      resourceId: contractId,
-      resource: 'contracts',
-      code: 'delivery_order',
-      file,
-    });
+    await persistDeliveryOrderUploads(this.filesService, contractId, 'contracts', files ?? []);
 
     const cycle = await this.contractsRepository.currentCycle(contractId);
     if (cycle) {
@@ -1520,7 +1514,7 @@ export class ContractClearanceService {
 
   async uploadReleaseOrder(
     contractId: string,
-    file: Express.Multer.File,
+    files: Express.Multer.File[],
     vesselDepartureDate: string,
     userId?: string,
   ): Promise<{ contract: Contract; hold: boolean; holdReason?: string }> {
@@ -1535,7 +1529,6 @@ export class ContractClearanceService {
       'RELEASE_ORDER_SECURED',
     );
 
-    if (!file) throw new BadRequestException('No Release Order uploaded');
     if (!vesselDepartureDate?.trim()) {
       throw new BadRequestException('Vessel departure date is required');
     }
@@ -1545,12 +1538,7 @@ export class ContractClearanceService {
     const cycle = await this.contractsRepository.currentCycle(contractId);
     if (!cycle) throw new BadRequestException('No clearance cycle found');
 
-    await this.filesService.upsertByCode({
-      resourceId: contractId,
-      resource: 'contracts',
-      code: 'release_order',
-      file,
-    });
+    await persistReleaseOrderUploads(this.filesService, contractId, 'contracts', files ?? []);
 
     await this.contractsRepository.updateCycle(cycle.id, {
       vesselDepartureDate,
diff --git a/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts b/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
index 0ff9b7c24..c9db49b24 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
@@ -956,20 +956,20 @@ export class ContractsController {
 
   @Post(':id/clearance/delivery-order')
   @BookingStaff(FREIGHT_PERMS.contracts.clearanceDjActions)
-  @UseInterceptors(FileInterceptor('file'))
+  @UseInterceptors(AnyFilesInterceptor())
   @ApiConsumes('multipart/form-data')
   @ApiOperation({
     summary:
-      'GL DJ uploads Delivery Order (import) with vessel arrival + DO collected dates',
+      'GL DJ uploads Delivery Order files (import) with vessel arrival + DO collected dates',
   })
   uploadDeliveryOrder(
     @Param('id', ParseUUIDPipe) id: string,
-    @UploadedFile() file: Express.Multer.File,
+    @UploadedFiles() files: Express.Multer.File[],
     @Body('vesselArrivalDate') vesselArrivalDate: string | undefined,
     @Body('doCollectedDate') doCollectedDate: string | undefined,
     @CurrentUser() user: AuthUserPayload,
   ) {
-    return this.clearanceService.uploadDeliveryOrder(id, file, resolveAuthUserId(user), {
+    return this.clearanceService.uploadDeliveryOrder(id, files ?? [], resolveAuthUserId(user), {
       vesselArrivalDate,
       doCollectedDate,
     });
@@ -977,18 +977,18 @@ export class ContractsController {
 
   @Post(':id/clearance/release-order')
   @BookingStaff(FREIGHT_PERMS.contracts.clearanceDjActions)
-  @UseInterceptors(FileInterceptor('file'))
+  @UseInterceptors(AnyFilesInterceptor())
   @ApiConsumes('multipart/form-data')
-  @ApiOperation({ summary: 'GL DJ uploads Release Order + vessel departure date (export)' })
+  @ApiOperation({ summary: 'GL DJ uploads Release Order files + vessel departure date (export)' })
   uploadReleaseOrder(
     @Param('id', ParseUUIDPipe) id: string,
-    @UploadedFile() file: Express.Multer.File,
+    @UploadedFiles() files: Express.Multer.File[],
     @Body('vesselDepartureDate') vesselDepartureDate: string,
     @CurrentUser() user: AuthUserPayload,
   ) {
     return this.clearanceService.uploadReleaseOrder(
       id,
-      file,
+      files ?? [],
       vesselDepartureDate,
       resolveAuthUserId(user),
     );
diff --git a/apps/edr-freight-api/src/modules/contracts/phased-clearance.util.ts b/apps/edr-freight-api/src/modules/contracts/phased-clearance.util.ts
index 78d0d6b47..ab2a2b2d4 100644
--- a/apps/edr-freight-api/src/modules/contracts/phased-clearance.util.ts
+++ b/apps/edr-freight-api/src/modules/contracts/phased-clearance.util.ts
@@ -5,6 +5,10 @@ import {
   draftDeclarationFileLabel,
   isDeclarationFileCode,
   isDraftDeclarationFileCode,
+  isDeliveryOrderFileCode,
+  isReleaseOrderFileCode,
+  deliveryOrderFileLabel,
+  releaseOrderFileLabel,
   isImportTransitPermitFileCode,
   isExportTransportFileCode,
   isT1TransportFileCode,
@@ -166,6 +170,98 @@ export async function persistTransitPermitUploads(
   );
 }
 
+/** Require at least one Delivery Order file in the upload batch. */
+export function assertDeliveryOrderFiles(files: Express.Multer.File[]): void {
+  if (files.length === 0) {
+    throw new BadRequestException('No Delivery Order uploaded');
+  }
+}
+
+/** Assign stable `delivery_order_*` codes for multi-file DO uploads. */
+export function normalizeDeliveryOrderFieldNames(
+  files: Express.Multer.File[],
+): Express.Multer.File[] {
+  return files.map((file, index) => ({
+    ...file,
+    fieldname: `delivery_order_${index}`,
+  }));
+}
+
+/** Replace all Delivery Order files on a resource with a new multi-file batch. */
+export async function persistDeliveryOrderUploads(
+  store: DeclarationFileStore,
+  resourceId: string,
+  resource: string,
+  files: Express.Multer.File[],
+): Promise<void> {
+  const normalized = normalizeDeliveryOrderFieldNames(files);
+  assertDeliveryOrderFiles(normalized);
+
+  const existing = await store.findByResource(resourceId, resource);
+  await Promise.all(
+    existing
+      .filter((f) => f.code && isDeliveryOrderFileCode(f.code))
+      .map((f) => store.deleteByCode(resourceId, resource, f.code!)),
+  );
+
+  await Promise.all(
+    normalized.map((file, index) =>
+      store.upload({
+        resourceId,
+        resource,
+        code: `delivery_order_${index}`,
+        file,
+      }),
+    ),
+  );
+}
+
+/** Require at least one Release Order file in the upload batch. */
+export function assertReleaseOrderFiles(files: Express.Multer.File[]): void {
+  if (files.length === 0) {
+    throw new BadRequestException('No Release Order uploaded');
+  }
+}
+
+/** Assign stable `release_order_*` codes for multi-file RO uploads. */
+export function normalizeReleaseOrderFieldNames(
+  files: Express.Multer.File[],
+): Express.Multer.File[] {
+  return files.map((file, index) => ({
+    ...file,
+    fieldname: `release_order_${index}`,
+  }));
+}
+
+/** Replace all Release Order files on a resource with a new multi-file batch. */
+export async function persistReleaseOrderUploads(
+  store: DeclarationFileStore,
+  resourceId: string,
+  resource: string,
+  files: Express.Multer.File[],
+): Promise<void> {
+  const normalized = normalizeReleaseOrderFieldNames(files);
+  assertReleaseOrderFiles(normalized);
+
+  const existing = await store.findByResource(resourceId, resource);
+  await Promise.all(
+    existing
+      .filter((f) => f.code && isReleaseOrderFileCode(f.code))
+      .map((f) => store.deleteByCode(resourceId, resource, f.code!)),
+  );
+
+  await Promise.all(
+    normalized.map((file, index) =>
+      store.upload({
+        resourceId,
+        resource,
+        code: `release_order_${index}`,
+        file,
+      }),
+    ),
+  );
+}
+
 /** Require at least one export transport document in the upload batch. */
 export function assertExportTransportFiles(files: Express.Multer.File[]): void {
   if (files.length === 0) {
@@ -422,6 +518,22 @@ export function buildWorkflowFiles(
       });
     });
 
+    const extraDeliveryOrders = files
+      .filter((f) => f.code && isDeliveryOrderFileCode(f.code) && !included.has(f.code))
+      .sort((a, b) => (a.code ?? '').localeCompare(b.code ?? ''));
+
+    extraDeliveryOrders.forEach((file, index) => {
+      if (!file.code) return;
+      included.add(file.code);
+      out.push({
+        code: file.code,
+        label: deliveryOrderFileLabel(file.code, index),
+        uploadedBy: 'gl_dj',
+        category: 'djibouti',
+        file: { id: file.id, name: file.name, url: file.url },
+      });
+    });
+
     const extraT1 = files
       .filter((f) => f.code && isT1TransportFileCode(f.code) && !included.has(f.code))
       .sort((a, b) => (a.code ?? '').localeCompare(b.code ?? ''));
@@ -440,6 +552,22 @@ export function buildWorkflowFiles(
   }
 
   if (tradeDirection === 'EXPORT') {
+    const extraReleaseOrders = files
+      .filter((f) => f.code && isReleaseOrderFileCode(f.code) && !included.has(f.code))
+      .sort((a, b) => (a.code ?? '').localeCompare(b.code ?? ''));
+
+    extraReleaseOrders.forEach((file, index) => {
+      if (!file.code) return;
+      included.add(file.code);
+      out.push({
+        code: file.code,
+        label: releaseOrderFileLabel(file.code, index),
+        uploadedBy: 'gl_dj',
+        category: 'djibouti',
+        file: { id: file.id, name: file.name, url: file.url },
+      });
+    });
+
     const extraExportTransport = files
       .filter((f) => f.code && isExportTransportFileCode(f.code) && !included.has(f.code))
       .sort((a, b) => (a.code ?? '').localeCompare(b.code ?? ''));
diff --git a/apps/edr-freight-api/src/modules/train-schedules/entities/train-schedule.entity.ts b/apps/edr-freight-api/src/modules/train-schedules/entities/train-schedule.entity.ts
index 5730120e9..cd8fe1bb9 100644
--- a/apps/edr-freight-api/src/modules/train-schedules/entities/train-schedule.entity.ts
+++ b/apps/edr-freight-api/src/modules/train-schedules/entities/train-schedule.entity.ts
@@ -64,6 +64,14 @@ export class TrainSchedule extends BaseEntity {
   @Column({ name: 'train_number', type: 'varchar', length: 20, nullable: true })
   trainNumber?: string | null;
 
+  /**
+   * Voyage (sailing) number for this departure — the identifier yards and
+   * customs quote alongside the train number. Per-departure, so it lives here
+   * rather than on the built train.
+   */
+  @Column({ name: 'voyage_number', type: 'varchar', length: 20, nullable: true })
+  voyageNumber?: string | null;
+
   // Human-facing unique schedule reference (S-YYYY-NNNNN). Shown on the schedule
   // list, booking windows, and load lists. Assigned at creation from the highest
   // sequence issued this year (see TrainSchedulesRepository.maxReferenceSequence).
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/controllers/train-scheduling.controller.ts b/apps/edr-freight-api/src/modules/train-scheduling/controllers/train-scheduling.controller.ts
index c87d118c8..93a187a95 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/controllers/train-scheduling.controller.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/controllers/train-scheduling.controller.ts
@@ -15,6 +15,7 @@ import {
   PortalCustomer,
   TrainSchedulingCancel,
   TrainSchedulingCreate,
+  TrainSchedulingEditTrainNumber,
   TrainSchedulingReschedule,
   TrainSchedulingRulesManage,
   TrainSchedulingUpdate,
@@ -52,6 +53,8 @@ import { AvailableDaysForCargoQueryDto } from "../dto/available-days-for-cargo-q
 import { UpdateTrainSchedulingGlobalRulesDto } from "../dto/update-train-scheduling-global-rules.dto";
 import { UpdateScheduleWindowRuleDto } from "../dto/update-schedule-window-rule.dto";
 import { UpdateScheduleDateDto } from "../dto/update-schedule-date.dto";
+import { MergeScheduleTrainDto } from "../dto/merge-schedule-train.dto";
+import { UpdateScheduleTrainNumberDto } from "../dto/update-schedule-train-number.dto";
 import { MaintenanceRescheduleDto } from "../dto/maintenance-reschedule.dto";
 import { TrainSchedulingService } from "../services/train-scheduling.service";
 import { BookingBatchService } from "../booking-batch.service";
@@ -795,6 +798,47 @@ export class TrainSchedulingController {
     return this.trainSchedulingService.getContainerTrainScheduleById(id);
   }
 
+  @Patch("schedules/:id/train-number")
+  @TrainSchedulingEditTrainNumber()
+  @ApiOperation({
+    summary:
+      "Edit a departure's train number and voyage number — allowed only until the train is dispatched",
+  })
+  async updateScheduleTrainNumber(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: UpdateScheduleTrainNumberDto,
+  ) {
+    await this.trainSchedulingService.updateScheduleTrainNumber(id, dto);
+    return this.trainSchedulingService.getContainerTrainScheduleById(id);
+  }
+
+  @Get("schedules/:id/merge-preview/:targetTrainId")
+  @TrainSchedulingUpdate()
+  @ApiOperation({
+    summary:
+      "What merging a train into this schedule would do — affected schedules, wagon totals and any blocking reasons. Read-only.",
+  })
+  async previewScheduleMerge(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Param("targetTrainId", ParseUUIDPipe) targetTrainId: string,
+  ) {
+    return this.trainSchedulingService.previewMerge(id, targetTrainId);
+  }
+
+  @Post("schedules/:id/merge")
+  @TrainSchedulingUpdate()
+  @ApiOperation({
+    summary:
+      "Merge another train into this schedule: its wagons join this consist, a same-day schedule on it is absorbed, and the emptied train is deactivated",
+  })
+  async mergeScheduleTrain(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: MergeScheduleTrainDto,
+  ) {
+    await this.trainSchedulingService.mergeScheduleTrain(id, dto);
+    return this.trainSchedulingService.getContainerTrainScheduleById(id);
+  }
+
   @Post("schedules/:id/maintenance")
   @TrainSchedulingReschedule()
   @ApiOperation({
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/dto/merge-schedule-train.dto.ts b/apps/edr-freight-api/src/modules/train-scheduling/dto/merge-schedule-train.dto.ts
new file mode 100644
index 000000000..8f4c09d43
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/train-scheduling/dto/merge-schedule-train.dto.ts
@@ -0,0 +1,23 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsOptional, IsString, IsUUID, MaxLength } from 'class-validator';
+
+/**
+ * Merge another train into this schedule's train. The schedule always survives:
+ * its train set is repointed at `targetTrainId`, that train's wagons join this
+ * consist, and the source train is left empty and deactivated.
+ */
+export class MergeScheduleTrainDto {
+  @ApiProperty({
+    description: "The train being merged IN. This schedule's train absorbs it.",
+  })
+  @IsUUID()
+  targetTrainId!: string;
+
+  @ApiPropertyOptional({
+    description: 'Why the trains were merged — kept on the audit trail.',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  reason?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/dto/update-schedule-train-number.dto.ts b/apps/edr-freight-api/src/modules/train-scheduling/dto/update-schedule-train-number.dto.ts
new file mode 100644
index 000000000..5756732c4
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/train-scheduling/dto/update-schedule-train-number.dto.ts
@@ -0,0 +1,40 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsOptional, IsString, MaxLength } from 'class-validator';
+
+/**
+ * Edit a departure's operational run identifiers. Both fields are optional so
+ * either can be corrected alone; the service rejects a body carrying neither,
+ * so an empty request cannot write an audit row for a no-op.
+ *
+ * Sending an empty string clears the field; omitting it leaves it unchanged.
+ */
+export class UpdateScheduleTrainNumberDto {
+  @ApiPropertyOptional({
+    example: '9201',
+    description: "Run number for this departure. Empty string clears it.",
+    maxLength: 20,
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(20)
+  trainNumber?: string;
+
+  @ApiPropertyOptional({
+    example: 'V-2026-014',
+    description: 'Voyage (sailing) number for this departure. Empty string clears it.',
+    maxLength: 20,
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(20)
+  voyageNumber?: string;
+
+  @ApiPropertyOptional({
+    description: 'Why the numbers changed — kept on the audit trail.',
+    maxLength: 500,
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  reason?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/schedule-merge.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/schedule-merge.spec.ts
new file mode 100644
index 000000000..c3acfbecb
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/train-scheduling/schedule-merge.spec.ts
@@ -0,0 +1,399 @@
+import { BadRequestException, NotFoundException } from '@nestjs/common';
+
+import { TrainSchedulingService } from './services/train-scheduling.service';
+
+/**
+ * Merging one train into a schedule. The schedule ALWAYS survives: its train
+ * set is repointed at the target train, that train's wagons join the consist,
+ * a same-day schedule on the target is absorbed (bookings move here, it is
+ * soft-deleted), and the emptied source train is deactivated.
+ *
+ * Driven against stub repositories — every rule under test is service logic.
+ */
+describe('TrainSchedulingService — train merge', () => {
+  const DAY = '2026-08-12T00:00:00.000Z';
+  const OTHER_DAY = '2026-08-14T00:00:00.000Z';
+
+  /** Rows each repository returns, keyed by entity. */
+  type Fixture = {
+    schedule: Record<string, unknown> | null;
+    train?: Record<string, unknown> | null;
+    trainSets?: Record<string, unknown>[];
+    schedules?: Record<string, unknown>[];
+    wagons?: Record<string, unknown>[];
+    wagonTypes?: Record<string, unknown>[];
+    scheduleBookings?: Record<string, unknown>[];
+    allocations?: Record<string, unknown>[];
+    milestones?: Record<string, unknown>[];
+    setWagons?: Record<string, unknown>[];
+  };
+
+  const makeService = (fx: Fixture) => {
+    const updates: Array<{ entity: string; args: unknown[] }> = [];
+    const softDeletes: string[] = [];
+
+    const repoFor = (entity: unknown) => {
+      const name = (entity as { name?: string })?.name ?? String(entity);
+      const rows = (): Record<string, unknown>[] => {
+        switch (name) {
+          case 'Train':
+            return fx.train ? [fx.train] : [];
+          case 'TrainSet':
+            return fx.trainSets ?? [];
+          case 'TrainSchedule':
+            return fx.schedules ?? [];
+          case 'Wagon':
+            return fx.wagons ?? [];
+          case 'WagonType':
+            return fx.wagonTypes ?? [];
+          case 'TrainScheduleBooking':
+            return fx.scheduleBookings ?? [];
+          case 'WagonBookingAllocation':
+            return fx.allocations ?? [];
+          case 'RouteMilestone':
+            return fx.milestones ?? [];
+          case 'TrainSetWagon':
+            return fx.setWagons ?? [];
+          default:
+            return [];
+        }
+      };
+      return {
+        find: jest.fn().mockImplementation(async () => rows()),
+        findOne: jest.fn().mockImplementation(async () => rows()[0] ?? null),
+        update: jest.fn().mockImplementation(async (...args: unknown[]) => {
+          updates.push({ entity: name, args });
+        }),
+        softDelete: jest.fn().mockImplementation(async (id: string) => {
+          softDeletes.push(id);
+        }),
+      };
+    };
+
+    const dataSource = {
+      getRepository: jest.fn().mockImplementation(repoFor),
+      transaction: jest
+        .fn()
+        .mockImplementation(async (cb: (m: unknown) => Promise<void>) =>
+          cb({ getRepository: repoFor }),
+        ),
+    };
+
+    const service = Object.create(
+      TrainSchedulingService.prototype,
+    ) as TrainSchedulingService;
+    Object.assign(service, {
+      dataSource,
+      trainSchedulesRepository: {
+        findByIdWithFullGraph: jest.fn().mockResolvedValue(fx.schedule),
+        findById: jest.fn().mockResolvedValue(fx.schedule),
+      },
+      logger: { log: jest.fn(), warn: jest.fn() },
+    });
+    return { service, updates, softDeletes };
+  };
+
+  /** A draft schedule on T1 with 10 wagons and no locomotive caps. */
+  const baseSchedule = (over: Record<string, unknown> = {}) => ({
+    id: 'S1',
+    reference: 'S-2026-00001',
+    status: 'DRAFT',
+    scheduledDepartureDate: DAY,
+    routeId: null,
+    maxWagons: 0,
+    trainSetId: 'TS1',
+    trainSet: {
+      id: 'TS1',
+      trainId: 'T1',
+      wagons: Array.from({ length: 10 }, (_, i) => ({
+        id: `sw-${i}`,
+        sequenceNo: i + 1,
+        lengthMeters: 14,
+        wagonType: { tareWeightTons: 22.4 },
+      })),
+    },
+    ...over,
+  });
+
+  const targetWagons = (n: number) =>
+    Array.from({ length: n }, (_, i) => ({
+      id: `w-${i}`,
+      wagonNumber: `200${i}`,
+      wagonTypeId: 'wt-1',
+      trainId: 'T2',
+    }));
+
+  describe('guards', () => {
+    it('refuses to merge into a dispatched schedule', async () => {
+      const { service } = makeService({
+        schedule: baseSchedule({ status: 'DISPATCHED' }),
+      });
+
+      await expect(
+        service.mergeScheduleTrain('S1', { targetTrainId: 'T2' }),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it('refuses to merge a train into itself', async () => {
+      const { service } = makeService({ schedule: baseSchedule() });
+
+      await expect(
+        service.mergeScheduleTrain('S1', { targetTrainId: 'T1' }),
+      ).rejects.toThrow(/already this schedule's train/i);
+    });
+
+    it('404s on an unknown schedule', async () => {
+      const { service } = makeService({ schedule: null });
+
+      await expect(
+        service.mergeScheduleTrain('S1', { targetTrainId: 'T2' }),
+      ).rejects.toBeInstanceOf(NotFoundException);
+    });
+
+    it('blocks when the target train has no wagons to give', async () => {
+      const { service } = makeService({
+        schedule: baseSchedule(),
+        train: { id: 'T2', code: 'TR-2' },
+        wagons: [],
+      });
+
+      await expect(
+        service.mergeScheduleTrain('S1', { targetTrainId: 'T2' }),
+      ).rejects.toThrow(/no wagons to merge/i);
+    });
+  });
+
+  describe('preview', () => {
+    it('reports the merged wagon total and the emptied source train', async () => {
+      const { service } = makeService({
+        schedule: baseSchedule(),
+        train: { id: 'T2', code: 'TR-2', trainNumber: '8002' },
+        wagons: targetWagons(40),
+        wagonTypes: [{ id: 'wt-1', lengthMeters: 14, tareWeightTons: 22.4 }],
+      });
+
+      const preview = await service.previewMerge('S1', 'T2');
+
+      expect(preview.canMerge).toBe(true);
+      expect(preview.wagons).toEqual({ current: 10, incoming: 40, merged: 50 });
+      expect(preview.sourceTrainWillDeactivate).toBe(true);
+      expect(preview.absorbedSchedule).toBeNull();
+    });
+
+    it('names the same-day schedule whose bookings move here', async () => {
+      const { service } = makeService({
+        schedule: baseSchedule(),
+        train: { id: 'T2', code: 'TR-2' },
+        trainSets: [{ id: 'TS2', trainId: 'T2' }],
+        schedules: [
+          {
+            id: 'S2',
+            reference: 'S-2026-00002',
+            status: 'SCHEDULED',
+            scheduledDepartureDate: DAY,
+            trainSetId: 'TS2',
+          },
+        ],
+        wagons: targetWagons(40),
+        wagonTypes: [{ id: 'wt-1', lengthMeters: 14, tareWeightTons: 22.4 }],
+        scheduleBookings: [
+          { id: 'sb-1', bookingId: 'bk-1', trainScheduleId: 'S2' },
+          { id: 'sb-2', bookingId: 'bk-2', trainScheduleId: 'S2' },
+        ],
+      });
+
+      const preview = await service.previewMerge('S1', 'T2');
+
+      expect(preview.absorbedSchedule).toMatchObject({
+        id: 'S2',
+        reference: 'S-2026-00002',
+        bookingsMoving: 2,
+      });
+    });
+
+    it('lists an other-day schedule as wagons-only, never absorbed', async () => {
+      const { service } = makeService({
+        schedule: baseSchedule(),
+        train: { id: 'T2', code: 'TR-2' },
+        trainSets: [{ id: 'TS2', trainId: 'T2' }],
+        schedules: [
+          {
+            id: 'S3',
+            reference: 'S-2026-00003',
+            status: 'DRAFT',
+            scheduledDepartureDate: OTHER_DAY,
+            trainSetId: 'TS2',
+          },
+        ],
+        wagons: targetWagons(40),
+        wagonTypes: [{ id: 'wt-1', lengthMeters: 14, tareWeightTons: 22.4 }],
+      });
+
+      const preview = await service.previewMerge('S1', 'T2');
+
+      expect(preview.absorbedSchedule).toBeNull();
+      expect(preview.affectedSchedules).toHaveLength(1);
+      expect(preview.affectedSchedules[0]).toMatchObject({ id: 'S3' });
+    });
+
+    it('leaves a dispatched schedule on the target untouched', async () => {
+      const { service } = makeService({
+        schedule: baseSchedule(),
+        train: { id: 'T2', code: 'TR-2' },
+        trainSets: [{ id: 'TS2', trainId: 'T2' }],
+        schedules: [
+          {
+            id: 'S4',
+            status: 'DISPATCHED',
+            scheduledDepartureDate: DAY,
+            trainSetId: 'TS2',
+          },
+        ],
+        wagons: targetWagons(40),
+        wagonTypes: [{ id: 'wt-1', lengthMeters: 14, tareWeightTons: 22.4 }],
+      });
+
+      const preview = await service.previewMerge('S1', 'T2');
+
+      // Same day, but dispatched — its cargo stays put.
+      expect(preview.absorbedSchedule).toBeNull();
+      expect(preview.affectedSchedules).toHaveLength(0);
+      expect(preview.untouchedSchedules).toHaveLength(1);
+    });
+  });
+
+  describe('commit', () => {
+    it('repoints the set, moves the wagons and deactivates the source train', async () => {
+      const { service, updates } = makeService({
+        schedule: baseSchedule(),
+        train: { id: 'T2', code: 'TR-2' },
+        wagons: targetWagons(40),
+        wagonTypes: [{ id: 'wt-1', lengthMeters: 14, tareWeightTons: 22.4 }],
+      });
+
+      await service.mergeScheduleTrain('S1', { targetTrainId: 'T2' });
+
+      const setRepoint = updates.find(
+        (u) => u.entity === 'TrainSet' && u.args[0] === 'TS1',
+      );
+      expect(setRepoint?.args[1]).toMatchObject({ trainId: 'T2' });
+
+      const wagonMove = updates.find((u) => u.entity === 'Wagon');
+      expect(wagonMove?.args[1]).toMatchObject({ trainId: 'T2' });
+
+      const trainPark = updates.find(
+        (u) => u.entity === 'Train' && u.args[0] === 'T1',
+      );
+      expect(trainPark?.args[1]).toMatchObject({ status: 'DEACTIVATED' });
+    });
+
+    it('moves the absorbed schedule\'s bookings here and soft-deletes it', async () => {
+      const { service, updates, softDeletes } = makeService({
+        schedule: baseSchedule(),
+        train: { id: 'T2', code: 'TR-2' },
+        trainSets: [{ id: 'TS2', trainId: 'T2' }],
+        schedules: [
+          {
+            id: 'S2',
+            reference: 'S-2026-00002',
+            status: 'SCHEDULED',
+            scheduledDepartureDate: DAY,
+            trainSetId: 'TS2',
+          },
+        ],
+        wagons: targetWagons(40),
+        wagonTypes: [{ id: 'wt-1', lengthMeters: 14, tareWeightTons: 22.4 }],
+        scheduleBookings: [
+          { id: 'sb-1', bookingId: 'bk-1', trainScheduleId: 'S2' },
+        ],
+      });
+
+      await service.mergeScheduleTrain('S1', { targetTrainId: 'T2' });
+
+      const bookingMove = updates.find(
+        (u) => u.entity === 'TrainScheduleBooking',
+      );
+      expect(bookingMove?.args[0]).toMatchObject({ trainScheduleId: 'S2' });
+      expect(bookingMove?.args[1]).toMatchObject({ trainScheduleId: 'S1' });
+
+      // Soft-deleted, not cancelled — the bookings still exist and still depart.
+      expect(softDeletes).toEqual(['S2']);
+    });
+
+    it('appends merged wagons after the existing consist', async () => {
+      const { service, updates } = makeService({
+        schedule: baseSchedule(),
+        train: { id: 'T2', code: 'TR-2' },
+        wagons: targetWagons(2),
+        wagonTypes: [{ id: 'wt-1', lengthMeters: 14, tareWeightTons: 22.4 }],
+        setWagons: [
+          { id: 'in-0', trainSetId: 'TS2', physicalWagonId: 'w-0' },
+          { id: 'in-1', trainSetId: 'TS2', physicalWagonId: 'w-1' },
+        ],
+      });
+
+      await service.mergeScheduleTrain('S1', { targetTrainId: 'T2' });
+
+      // 10 existing wagons occupy 1..10, so the merged pair lands at 11 and 12
+      // — staff reorder them in the train builder afterwards.
+      const seqs = updates
+        .filter((u) => u.entity === 'TrainSetWagon')
+        .map((u) => (u.args[1] as { sequenceNo: number }).sequenceNo);
+      expect(seqs).toEqual([11, 12]);
+    });
+  });
+
+  describe('capacity', () => {
+    it('blocks a merge that overruns the locomotive length cap', async () => {
+      const { service } = makeService({
+        schedule: baseSchedule({
+          trainSet: {
+            id: 'TS1',
+            trainId: 'T1',
+            // A short loco: 100m of train, already 10 × 14m = 140m used.
+            locomotive: {
+              maxPullWeightTons: 5000,
+              maxTrainLengthMeters: 100,
+            },
+            wagons: Array.from({ length: 10 }, (_, i) => ({
+              id: `sw-${i}`,
+              sequenceNo: i + 1,
+              lengthMeters: 14,
+              wagonType: { tareWeightTons: 22.4 },
+            })),
+          },
+        }),
+        train: { id: 'T2', code: 'TR-2' },
+        wagons: targetWagons(40),
+        wagonTypes: [{ id: 'wt-1', lengthMeters: 14, tareWeightTons: 22.4 }],
+      });
+
+      await expect(
+        service.mergeScheduleTrain('S1', { targetTrainId: 'T2' }),
+      ).rejects.toThrow(/exceeds max train length/i);
+    });
+
+    it('blocks a merge that overruns the pull-weight cap', async () => {
+      const { service } = makeService({
+        schedule: baseSchedule({
+          trainSet: {
+            id: 'TS1',
+            trainId: 'T1',
+            locomotive: {
+              maxPullWeightTons: 300,
+              maxTrainLengthMeters: 10000,
+            },
+            wagons: [],
+          },
+        }),
+        train: { id: 'T2', code: 'TR-2' },
+        wagons: targetWagons(40),
+        wagonTypes: [{ id: 'wt-1', lengthMeters: 14, tareWeightTons: 22.4 }],
+      });
+
+      await expect(
+        service.mergeScheduleTrain('S1', { targetTrainId: 'T2' }),
+      ).rejects.toThrow(/exceeds max pull weight/i);
+    });
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/schedule-train-number.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/schedule-train-number.spec.ts
new file mode 100644
index 000000000..d7dae50f4
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/train-scheduling/schedule-train-number.spec.ts
@@ -0,0 +1,114 @@
+import { BadRequestException, NotFoundException } from '@nestjs/common';
+
+import { TrainSchedulingService } from './services/train-scheduling.service';
+import type { UpdateScheduleTrainNumberDto } from './dto/update-schedule-train-number.dto';
+
+/**
+ * Guards around renumbering a departure. Exercised against a stub repository —
+ * the rules (dispatch lock, empty-body rejection, clear-vs-leave semantics) are
+ * pure service logic and need no database.
+ */
+describe('TrainSchedulingService.updateScheduleTrainNumber', () => {
+  const makeService = (schedule: Record<string, unknown> | null) => {
+    const update = jest.fn().mockResolvedValue(undefined);
+    const findById = jest.fn().mockResolvedValue(schedule);
+    const service = Object.create(
+      TrainSchedulingService.prototype,
+    ) as TrainSchedulingService;
+    Object.assign(service, {
+      trainSchedulesRepository: { findById, update },
+      logger: { log: jest.fn(), warn: jest.fn() },
+    });
+    return { service, update, findById };
+  };
+
+  const call = (service: TrainSchedulingService, dto: UpdateScheduleTrainNumberDto) =>
+    service.updateScheduleTrainNumber('sched-1', dto);
+
+  it('updates both numbers on a SCHEDULED train', async () => {
+    const { service, update } = makeService({
+      id: 'sched-1',
+      status: 'SCHEDULED',
+      trainNumber: '9101',
+      voyageNumber: null,
+    });
+
+    await call(service, { trainNumber: '9201', voyageNumber: 'V-2026-014' });
+
+    expect(update).toHaveBeenCalledWith('sched-1', {
+      trainNumber: '9201',
+      voyageNumber: 'V-2026-014',
+    });
+  });
+
+  it('refuses to renumber a dispatched train', async () => {
+    // The numbers are already printed on paperwork that left with the train.
+    const { service, update } = makeService({
+      id: 'sched-1',
+      status: 'DISPATCHED',
+      trainNumber: '9101',
+    });
+
+    await expect(call(service, { trainNumber: '9201' })).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+    expect(update).not.toHaveBeenCalled();
+  });
+
+  it.each(['ARRIVED', 'CANCELLED', 'COMPLETED'])(
+    'refuses to renumber a %s schedule',
+    async (status) => {
+      const { service, update } = makeService({ id: 'sched-1', status });
+
+      await expect(call(service, { trainNumber: '9201' })).rejects.toBeInstanceOf(
+        BadRequestException,
+      );
+      expect(update).not.toHaveBeenCalled();
+    },
+  );
+
+  it('rejects a body carrying neither number before touching the schedule', async () => {
+    const { service, update, findById } = makeService({
+      id: 'sched-1',
+      status: 'DRAFT',
+    });
+
+    await expect(call(service, {})).rejects.toBeInstanceOf(BadRequestException);
+    expect(findById).not.toHaveBeenCalled();
+    expect(update).not.toHaveBeenCalled();
+  });
+
+  it('leaves an omitted field untouched rather than clearing it', async () => {
+    const { service, update } = makeService({
+      id: 'sched-1',
+      status: 'DRAFT',
+      trainNumber: '9101',
+      voyageNumber: 'V-1',
+    });
+
+    await call(service, { trainNumber: '9201' });
+
+    expect(update).toHaveBeenCalledWith('sched-1', { trainNumber: '9201' });
+    expect(update.mock.calls[0][1]).not.toHaveProperty('voyageNumber');
+  });
+
+  it('clears a field when an empty string is sent', async () => {
+    const { service, update } = makeService({
+      id: 'sched-1',
+      status: 'DRAFT',
+      voyageNumber: 'V-1',
+    });
+
+    await call(service, { voyageNumber: '   ' });
+
+    expect(update).toHaveBeenCalledWith('sched-1', { voyageNumber: null });
+  });
+
+  it('404s on an unknown schedule', async () => {
+    const { service } = makeService(null);
+
+    await expect(call(service, { trainNumber: '9201' })).rejects.toBeInstanceOf(
+      NotFoundException,
+    );
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index 657703ada..8bce5fb80 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -96,6 +96,8 @@ import {
 } from '../dto/import-djibouti-operation.dto';
 import { UpdateScheduleWindowRuleDto } from '../dto/update-schedule-window-rule.dto';
 import { UpdateScheduleDateDto } from '../dto/update-schedule-date.dto';
+import { MergeScheduleTrainDto } from '../dto/merge-schedule-train.dto';
+import { UpdateScheduleTrainNumberDto } from '../dto/update-schedule-train-number.dto';
 import { MaintenanceRescheduleDto } from '../dto/maintenance-reschedule.dto';
 import { type BookingWindowConfig } from '../booking-window.config';
 import { BookingWindowGateway } from '../booking-window.gateway';
@@ -132,14 +134,17 @@ import {
 } from '../utils/wagon-plan.util';
 import { CorridorBudget } from '../corridor-capacity.util';
 import { deriveScheduleDirection } from '../utils/derive-schedule-direction.util';
+import { computeScheduleWagonUsage } from '../utils/schedule-wagon-usage.util';
 import { pickLowestFreeNumber, pickTrainNumberPool } from '../train-number.util';
 import {
   bookingCargoTons,
   bulkItemsFitFor,
   bulkItemWagonsRequired,
   bulkTonsPerWagon,
+  consistViolations,
   deriveTrainCapacityFromLocomotive,
   combinedLocomotiveLimits,
+  trainHardCaps,
   trainSetLocomotiveLimits,
   wagonTypeDimensionsFromEntity,
   LocomotiveLimits,
@@ -928,6 +933,68 @@ export class TrainSchedulingService {
     return fresh ?? schedule;
   }
 
+  /**
+   * Correct a departure's operational run identifiers — the train number and
+   * voyage number yards and customs quote.
+   *
+   * Editable only until the train leaves: once DISPATCHED (or beyond) the
+   * numbers are printed on paperwork and quoted downstream, so a late edit would
+   * desync records that already left with the train. The audit row is written by
+   * the global AuditInterceptor from the registered route.
+   */
+  async updateScheduleTrainNumber(
+    id: string,
+    dto: UpdateScheduleTrainNumberDto,
+  ): Promise<TrainSchedule> {
+    if (dto.trainNumber === undefined && dto.voyageNumber === undefined) {
+      throw new BadRequestException(
+        'Provide a train number or a voyage number to update.',
+      );
+    }
+
+    const schedule = await this.trainSchedulesRepository.findById(id);
+    if (!schedule) {
+      throw new NotFoundException(`Train schedule ${id} not found`);
+    }
+
+    // Only a train that has not left can be renumbered. CANCELLED is excluded
+    // too — renumbering a dead schedule has no meaning.
+    const editable: string[] = [
+      TrainScheduleStatusEnum.Draft,
+      TrainScheduleStatusEnum.Scheduled,
+    ];
+    if (!editable.includes(schedule.status)) {
+      throw new BadRequestException(
+        `Cannot change the train or voyage number of a ${schedule.status} schedule — ` +
+          'the numbers are fixed once the train is dispatched.',
+      );
+    }
+
+    // An empty string clears the field; an omitted field is left untouched.
+    const patch: Partial<TrainSchedule> = {};
+    if (dto.trainNumber !== undefined) {
+      patch.trainNumber = dto.trainNumber.trim() || null;
+    }
+    if (dto.voyageNumber !== undefined) {
+      patch.voyageNumber = dto.voyageNumber.trim() || null;
+    }
+
+    await this.trainSchedulesRepository.update(id, patch);
+    this.logger.log(
+      `Schedule ${schedule.reference ?? id} renumbered` +
+        (patch.trainNumber !== undefined
+          ? ` — train ${schedule.trainNumber ?? '—'} → ${patch.trainNumber ?? '—'}`
+          : '') +
+        (patch.voyageNumber !== undefined
+          ? ` — voyage ${schedule.voyageNumber ?? '—'} → ${patch.voyageNumber ?? '—'}`
+          : '') +
+        (dto.reason?.trim() ? ` (${dto.reason.trim()})` : ''),
+    );
+
+    const fresh = await this.trainSchedulesRepository.findById(id);
+    return fresh ?? schedule;
+  }
+
   /**
    * Reschedule ONE train's departure date (staff action on the ops board). Only
    * allowed while the booking window has not opened yet — an OPEN/past schedule
@@ -4072,7 +4139,15 @@ export class TrainSchedulingService {
     const [schedules, total] = await this.trainSchedulesRepository.findAndCount({
       where,
       relations: {
-        trainSet: { locomotive: true, locomotives: { locomotive: true }, train: true },
+        trainSet: {
+          locomotive: true,
+          locomotives: { locomotive: true },
+          train: true,
+          // Slot allocations back the list's "used wagons" figure — without
+          // them the row can only report the coupled consist size, which is
+          // what made the list disagree with the detail page's wagon plan.
+          wagons: { allocations: true },
+        },
         // Yards carry the route's display name used by mapScheduleListItem;
         // milestones (with yards) let it show the full corridor path.
         route: { originYard: true, destinationYard: true, milestones: { yard: true } },
@@ -5752,12 +5827,22 @@ export class TrainSchedulingService {
   }
 
   private mapScheduleListItem(schedule: import('../../train-schedules/entities/train-schedule.entity').TrainSchedule) {
+    // Wagon figures must match the detail page's wagon plan (WagonPlanGrid) —
+    // see computeScheduleWagonUsage for why the stored counter cannot be used.
+    const { wagonsUsed, wagonsTotal, wagonsReserved, wagonsRemaining } =
+      computeScheduleWagonUsage({
+        wagonSlots: schedule.trainSet?.wagons,
+        storedWagonCount: schedule.trainSet?.wagonCount,
+        scheduleBookings: schedule.scheduleBookings,
+      });
+
     return {
       id: schedule.id,
       reference: schedule.reference ?? null,
       createdAt: schedule.createdAt ?? null,
       scheduleDate: schedule.scheduledDepartureDate,
       trainNumber: schedule.trainNumber ?? null,
+      voyageNumber: schedule.voyageNumber ?? null,
       direction: schedule.direction ?? null,
       routeName: schedule.route ? formatRouteLabel(schedule.route) : null,
       origin: schedule.originStation?.label ?? schedule.originStation?.code ?? null,
@@ -5786,6 +5871,14 @@ export class TrainSchedulingService {
         currentYardId: loco.currentYardId ?? null,
       })),
       wagonCount: schedule.trainSet?.wagonCount ?? 0,
+      /** Coupled slots carrying a booking allocation — matches the wagon plan. */
+      wagonsUsed,
+      /** Coupled consist size; the denominator of "used". */
+      wagonsTotal,
+      /** Claimed by bookings (incl. unpaid) — not bookable. */
+      wagonsReserved,
+      /** Consist minus what bookings have claimed; what is still bookable. */
+      wagonsRemaining,
       totalWeightTons: roundTons(Number(schedule.trainSet?.totalWeightTons ?? 0)),
       totalLengthMeters: roundTons(Number(schedule.trainSet?.totalLengthMeters ?? 0)),
       bookingsCount: schedule.scheduleBookings?.length ?? 0,
@@ -7703,6 +7796,7 @@ export class TrainSchedulingService {
       status: schedule.status,
       freightType: this.resolveScheduleFreightType(schedule),
       trainNumber: schedule.trainNumber ?? null,
+      voyageNumber: schedule.voyageNumber ?? null,
       maxWagons: schedule.maxWagons ?? null,
       direction: schedule.direction ?? null,
       reverseWagonOrder: schedule.reverseWagonOrder ?? false,
@@ -9122,4 +9216,376 @@ export class TrainSchedulingService {
     });
     return new Set(allocations.map((a) => a.bookingId));
   }
+
+  // ── Train merge ────────────────────────────────────────────────────────────
+  // Combine two trains into one departure. The schedule the action is taken
+  // from ALWAYS survives: its train set is repointed at the target train, the
+  // target's wagons join this consist, and the source train is emptied and
+  // deactivated. When the target also runs a schedule on the SAME DAY, that
+  // schedule's bookings move here and it is soft-deleted; the target's
+  // other-day schedules contribute wagons only.
+
+  /** Statuses whose schedules may take part in a merge. */
+  private static readonly MERGEABLE_STATUSES: string[] = [
+    TrainScheduleStatusEnum.Draft,
+    TrainScheduleStatusEnum.Scheduled,
+  ];
+
+  /**
+   * Everything a merge needs to decide, gathered once. Both `previewMerge` and
+   * `mergeScheduleTrain` run this so the modal shows exactly what will happen
+   * and the commit cannot diverge from it.
+   */
+  private async planMerge(scheduleId: string, targetTrainId: string) {
+    const schedule =
+      await this.trainSchedulesRepository.findByIdWithFullGraph(scheduleId);
+    if (!schedule) {
+      throw new NotFoundException(`Train schedule ${scheduleId} not found`);
+    }
+    if (!TrainSchedulingService.MERGEABLE_STATUSES.includes(schedule.status)) {
+      throw new BadRequestException(
+        `Cannot merge into a ${schedule.status} schedule — only draft or scheduled departures can be merged.`,
+      );
+    }
+
+    const sourceTrainId = schedule.trainSet?.trainId ?? null;
+    if (sourceTrainId && sourceTrainId === targetTrainId) {
+      throw new BadRequestException(
+        'That is already this schedule\'s train — pick a different one to merge in.',
+      );
+    }
+
+    const targetTrain = await this.dataSource
+      .getRepository(Train)
+      .findOne({ where: { id: targetTrainId } });
+    if (!targetTrain) {
+      throw new NotFoundException(`Train ${targetTrainId} not found`);
+    }
+
+    // Every schedule the target train is committed to, via its train sets.
+    const targetSets = await this.dataSource
+      .getRepository(TrainSet)
+      .find({ where: { trainId: targetTrainId } });
+    const targetSetIds = targetSets.map((s) => s.id);
+    const targetSchedules = targetSetIds.length
+      ? await this.dataSource.getRepository(TrainSchedule).find({
+          where: { trainSetId: In(targetSetIds) },
+        })
+      : [];
+
+    // The same-day schedule is the one whose bookings move here. Only a
+    // draft/scheduled one qualifies — a dispatched departure keeps its cargo.
+    const sameDay = (a: Date | string, b: Date | string) =>
+      new Date(a).toISOString().slice(0, 10) ===
+      new Date(b).toISOString().slice(0, 10);
+
+    const absorbed =
+      targetSchedules.find(
+        (s) =>
+          s.id !== schedule.id &&
+          sameDay(s.scheduledDepartureDate, schedule.scheduledDepartureDate) &&
+          TrainSchedulingService.MERGEABLE_STATUSES.includes(s.status),
+      ) ?? null;
+
+    // Wagons ride with the train, so every OTHER draft/scheduled schedule on it
+    // is affected too — it gains the merged consist but never the bookings.
+    const affectedOthers = targetSchedules.filter(
+      (s) =>
+        s.id !== schedule.id &&
+        s.id !== absorbed?.id &&
+        TrainSchedulingService.MERGEABLE_STATUSES.includes(s.status),
+    );
+    const untouched = targetSchedules.filter(
+      (s) =>
+        s.id !== schedule.id &&
+        s.id !== absorbed?.id &&
+        !TrainSchedulingService.MERGEABLE_STATUSES.includes(s.status),
+    );
+
+    // The wagons joining this consist: whatever physically sits on the target
+    // train today.
+    const incomingWagons = await this.dataSource
+      .getRepository(Wagon)
+      .find({ where: { trainId: targetTrainId }, order: { wagonNumber: 'ASC' } });
+
+    const movingBookings = absorbed
+      ? await this.dataSource.getRepository(TrainScheduleBooking).find({
+          where: { trainScheduleId: absorbed.id },
+          relations: { booking: true },
+        })
+      : [];
+
+    return {
+      schedule,
+      sourceTrainId,
+      targetTrain,
+      absorbed,
+      affectedOthers,
+      untouched,
+      incomingWagons,
+      movingBookings,
+    };
+  }
+
+  /**
+   * Blocking checks, run against the plan. Returns human-readable reasons; an
+   * empty array means the merge may proceed. Kept separate from `planMerge` so
+   * the preview can SHOW the reasons rather than throwing on them.
+   */
+  private async mergeBlockers(
+    plan: Awaited<ReturnType<TrainSchedulingService['planMerge']>>,
+  ): Promise<string[]> {
+    const blockers: string[] = [];
+    const { schedule, incomingWagons, movingBookings, absorbed } = plan;
+
+    if (incomingWagons.length === 0) {
+      blockers.push(
+        `${plan.targetTrain.code} has no wagons to merge — nothing would move.`,
+      );
+    }
+
+    // ── Capacity: the merged consist must fit this schedule's locomotives ────
+    const existingSlots = (schedule.trainSet?.wagons ?? []).map((w) => ({
+      lengthMeters: Number(w.lengthMeters) || 0,
+      tareWeightTons: Number(w.wagonType?.tareWeightTons) || 0,
+      cargoTons: 0,
+    }));
+    const wagonTypeIds = [
+      ...new Set(incomingWagons.map((w) => w.wagonTypeId).filter(Boolean)),
+    ];
+    const wagonTypes = wagonTypeIds.length
+      ? await this.dataSource
+          .getRepository(WagonType)
+          .find({ where: { id: In(wagonTypeIds) } })
+      : [];
+    const typeById = new Map(wagonTypes.map((t) => [t.id, t]));
+    const incomingSlots = incomingWagons.map((w) => {
+      const t = typeById.get(w.wagonTypeId);
+      return {
+        lengthMeters: Number(t?.lengthMeters) || 0,
+        tareWeightTons: Number(t?.tareWeightTons) || 0,
+        cargoTons: 0,
+      };
+    });
+
+    const limits = trainSetLocomotiveLimits(schedule.trainSet);
+    if (limits) {
+      const rules = await this.dataSource
+        .getRepository(TrainSchedulingGlobalRules)
+        .find({ take: 1 });
+      const caps = trainHardCaps(limits, {
+        maxTrainWeightTons: rules[0]?.maxTrainWeightTons ?? undefined,
+        maxTrainLengthMeters: rules[0]?.maxTrainLengthMeters ?? undefined,
+      });
+      const merged = [...existingSlots, ...incomingSlots];
+      // maxWagons is the schedule's own slot ceiling; fall back to the consist
+      // size when it is unset so the count axis never blocks spuriously.
+      const violations = consistViolations(merged, {
+        maxWeightTons: caps.maxWeightTons,
+        maxLengthMeters: caps.maxLengthMeters,
+        maxWagonSlots: schedule.maxWagons || merged.length,
+      });
+      blockers.push(...violations);
+    }
+
+    // ── Legs: an absorbed booking must be servable by THIS schedule's route ──
+    if (absorbed && movingBookings.length) {
+      const routeYardIds = await this.routeYardSequence(schedule.routeId ?? null);
+      if (routeYardIds.length) {
+        const position = new Map(routeYardIds.map((id, i) => [id, i]));
+        const slotIds = movingBookings.map((mb) => mb.bookingId);
+        const allocations = slotIds.length
+          ? await this.dataSource.getRepository(WagonBookingAllocation).find({
+              where: { bookingId: In(slotIds) },
+              relations: { trainSetWagon: true },
+            })
+          : [];
+        const offRoute = new Set<string>();
+        for (const alloc of allocations) {
+          const board = alloc.trainSetWagon?.boardYardId ?? null;
+          const alight = alloc.trainSetWagon?.alightYardId ?? null;
+          // Null on both = rides the whole route; always compatible.
+          if (!board && !alight) continue;
+          const from = board ? position.get(board) : 0;
+          const to = alight ? position.get(alight) : routeYardIds.length - 1;
+          if (from === undefined || to === undefined || from >= to) {
+            offRoute.add(alloc.bookingId);
+          }
+        }
+        if (offRoute.size) {
+          blockers.push(
+            `${offRoute.size} booking(s) on ${absorbed.reference ?? 'the merged schedule'} ` +
+              'travel legs this schedule\'s route does not serve in the same order.',
+          );
+        }
+      }
+    }
+
+    return blockers;
+  }
+
+  /** Ordered yard ids along a route, origin first. Empty when unknown. */
+  private async routeYardSequence(routeId: string | null): Promise<string[]> {
+    if (!routeId) return [];
+    const milestones = await this.dataSource
+      .getRepository(RouteMilestone)
+      .find({ where: { routeId }, order: { sequenceNo: 'ASC' } });
+    return milestones
+      .map((m) => m.yardId)
+      .filter((id): id is string => Boolean(id));
+  }
+
+  /**
+   * What a merge WOULD do, without doing it. Drives the confirmation modal:
+   * which schedules gain wagons, which one is absorbed, and why it is blocked.
+   */
+  async previewMerge(scheduleId: string, targetTrainId: string) {
+    const plan = await this.planMerge(scheduleId, targetTrainId);
+    const blockers = await this.mergeBlockers(plan);
+
+    const existingCount = plan.schedule.trainSet?.wagons?.length ?? 0;
+    return {
+      canMerge: blockers.length === 0,
+      blockers,
+      targetTrain: {
+        id: plan.targetTrain.id,
+        code: plan.targetTrain.code,
+        trainNumber: plan.targetTrain.trainNumber ?? null,
+      },
+      wagons: {
+        current: existingCount,
+        incoming: plan.incomingWagons.length,
+        merged: existingCount + plan.incomingWagons.length,
+      },
+      /** The same-day schedule whose bookings move here and is then removed. */
+      absorbedSchedule: plan.absorbed
+        ? {
+            id: plan.absorbed.id,
+            reference: plan.absorbed.reference ?? null,
+            scheduledDepartureDate: plan.absorbed.scheduledDepartureDate,
+            status: plan.absorbed.status,
+            bookingsMoving: plan.movingBookings.length,
+          }
+        : null,
+      /** Other draft/scheduled schedules on the target — wagons only. */
+      affectedSchedules: plan.affectedOthers.map((s) => ({
+        id: s.id,
+        reference: s.reference ?? null,
+        scheduledDepartureDate: s.scheduledDepartureDate,
+        status: s.status,
+      })),
+      /** On the target train but left alone (dispatched, cancelled, …). */
+      untouchedSchedules: plan.untouched.map((s) => ({
+        id: s.id,
+        reference: s.reference ?? null,
+        scheduledDepartureDate: s.scheduledDepartureDate,
+        status: s.status,
+      })),
+      sourceTrainWillDeactivate: Boolean(plan.sourceTrainId),
+    };
+  }
+
+  /**
+   * Execute the merge. One transaction: repoint the train set, move the wagons
+   * (appended last so the builder can reorder them later), carry the absorbed
+   * schedule's bookings across, soft-delete that schedule, and deactivate the
+   * emptied source train.
+   */
+  async mergeScheduleTrain(
+    scheduleId: string,
+    dto: MergeScheduleTrainDto,
+  ): Promise<TrainSchedule> {
+    const plan = await this.planMerge(scheduleId, dto.targetTrainId);
+    const blockers = await this.mergeBlockers(plan);
+    if (blockers.length) {
+      throw new BadRequestException(blockers.join(' '));
+    }
+
+    const {
+      schedule,
+      sourceTrainId,
+      targetTrain,
+      absorbed,
+      incomingWagons,
+      movingBookings,
+    } = plan;
+    const trainSetId = schedule.trainSetId;
+
+    await this.dataSource.transaction(async (manager) => {
+      // 1. This schedule's set now runs on the target train.
+      await manager.getRepository(TrainSet).update(trainSetId, {
+        trainId: targetTrain.id,
+      });
+
+      // 2. The physical wagons follow the train.
+      if (incomingWagons.length) {
+        await manager.getRepository(Wagon).update(
+          { id: In(incomingWagons.map((w) => w.id)) },
+          { trainId: targetTrain.id },
+        );
+      }
+
+      // 3. Carry the target's train-set wagon rows into THIS consist, appended
+      //    after the existing wagons. Sequence is provisional — staff reorder
+      //    in the train builder afterwards.
+      const existing = schedule.trainSet?.wagons ?? [];
+      let nextSequence =
+        existing.reduce((max, w) => Math.max(max, w.sequenceNo ?? 0), 0) + 1;
+      const incomingSetWagons = await manager.getRepository(TrainSetWagon).find({
+        where: { physicalWagonId: In(incomingWagons.map((w) => w.id)) },
+      });
+      for (const row of incomingSetWagons) {
+        if (row.trainSetId === trainSetId) continue;
+        await manager.getRepository(TrainSetWagon).update(row.id, {
+          trainSetId,
+          sequenceNo: nextSequence,
+        });
+        nextSequence += 1;
+      }
+
+      // 4. The absorbed schedule's bookings move here. `bookingId` is uniquely
+      //    indexed, so these rows are UPDATED across rather than re-inserted.
+      if (absorbed && movingBookings.length) {
+        await manager
+          .getRepository(TrainScheduleBooking)
+          .update(
+            { trainScheduleId: absorbed.id },
+            { trainScheduleId: schedule.id },
+          );
+      }
+
+      // 5. The absorbed schedule is soft-deleted — its bookings still exist and
+      //    still depart that day, so nobody is notified and nothing is lost.
+      if (absorbed) {
+        await manager.getRepository(TrainSchedule).softDelete(absorbed.id);
+      }
+
+      // 6. The source train is now empty; park it.
+      if (sourceTrainId) {
+        await manager.getRepository(Train).update(sourceTrainId, {
+          status: Freight.TrainStatus.Deactivated,
+        });
+      }
+
+      // 7. Keep the set's cached totals honest.
+      const mergedCount =
+        (schedule.trainSet?.wagons?.length ?? 0) + incomingSetWagons.length;
+      await manager
+        .getRepository(TrainSet)
+        .update(trainSetId, { wagonCount: mergedCount });
+    });
+
+    this.logger.log(
+      `Schedule ${schedule.reference ?? scheduleId} merged with train ${targetTrain.code}` +
+        ` — ${incomingWagons.length} wagon(s) moved` +
+        (absorbed
+          ? `, absorbed ${absorbed.reference ?? absorbed.id} (${movingBookings.length} booking(s))`
+          : '') +
+        (sourceTrainId ? ', source train deactivated' : '') +
+        (dto.reason?.trim() ? ` (${dto.reason.trim()})` : ''),
+    );
+
+    const fresh = await this.trainSchedulesRepository.findById(scheduleId);
+    return fresh ?? schedule;
+  }
 }
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.spec.ts
new file mode 100644
index 000000000..8fa9c1260
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.spec.ts
@@ -0,0 +1,96 @@
+import { computeScheduleWagonUsage } from './schedule-wagon-usage.util';
+
+/** A coupled slot; `allocated` = a booking actually sits on it. */
+const slot = (allocated = false) => ({ allocations: allocated ? [{}] : [] });
+const booking = (wagonsRequired: number | null) => ({ booking: { wagonsRequired } });
+
+describe('computeScheduleWagonUsage', () => {
+  it('reports allocated slots as used, not the coupled consist size', () => {
+    // The reported bug: a 37-wagon consist carrying 3 allocated bookings read
+    // "37 wgn used" in the list while the detail page read "3 in use".
+    const slots = [...Array(34).fill(slot(false)), ...Array(3).fill(slot(true))];
+
+    const usage = computeScheduleWagonUsage({
+      wagonSlots: slots,
+      storedWagonCount: 37,
+      scheduleBookings: [],
+    });
+
+    expect(usage.wagonsUsed).toBe(3);
+    expect(usage.wagonsTotal).toBe(37);
+  });
+
+  it('counts a built train with no bookings as 0 used', () => {
+    const usage = computeScheduleWagonUsage({
+      wagonSlots: Array(40).fill(slot(false)),
+      storedWagonCount: 40,
+      scheduleBookings: [],
+    });
+
+    expect(usage.wagonsUsed).toBe(0);
+    expect(usage.wagonsRemaining).toBe(40);
+  });
+
+  it('treats wagons of an unpaid booking as reserved, so they are not bookable', () => {
+    // Booking claims 5 wagons but has no wagon plan yet: 0 used, still only 5
+    // bookable on a 10-wagon train — the reservation is not free space.
+    const usage = computeScheduleWagonUsage({
+      wagonSlots: Array(10).fill(slot(false)),
+      storedWagonCount: 10,
+      scheduleBookings: [booking(5)],
+    });
+
+    expect(usage.wagonsUsed).toBe(0);
+    expect(usage.wagonsReserved).toBe(5);
+    expect(usage.wagonsRemaining).toBe(5);
+  });
+
+  it('does not double-count a booking that is both reserved and allocated', () => {
+    // 3 allocated slots for a booking that reserved 3 wagons: 7 remain, not 4.
+    const usage = computeScheduleWagonUsage({
+      wagonSlots: [...Array(7).fill(slot(false)), ...Array(3).fill(slot(true))],
+      storedWagonCount: 10,
+      scheduleBookings: [booking(3)],
+    });
+
+    expect(usage.wagonsUsed).toBe(3);
+    expect(usage.wagonsReserved).toBe(3);
+    expect(usage.wagonsRemaining).toBe(7);
+  });
+
+  it('never reports negative remaining when claims exceed the consist', () => {
+    const usage = computeScheduleWagonUsage({
+      wagonSlots: Array(2).fill(slot(false)),
+      storedWagonCount: 2,
+      scheduleBookings: [booking(5)],
+    });
+
+    expect(usage.wagonsRemaining).toBe(0);
+  });
+
+  it('falls back to the stored counter when slot rows were not loaded', () => {
+    const usage = computeScheduleWagonUsage({
+      wagonSlots: [],
+      storedWagonCount: 12,
+      scheduleBookings: [],
+    });
+
+    expect(usage.wagonsTotal).toBe(12);
+    expect(usage.wagonsUsed).toBe(0);
+  });
+
+  it('tolerates missing relations and null wagonsRequired', () => {
+    const usage = computeScheduleWagonUsage({
+      wagonSlots: null,
+      storedWagonCount: null,
+      scheduleBookings: [booking(null)],
+    });
+
+    expect(usage).toEqual({
+      wagonsUsed: 0,
+      wagonsTotal: 0,
+      wagonsReserved: 0,
+      wagonsRemaining: 0,
+    });
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.ts b/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.ts
new file mode 100644
index 000000000..f48d60f9a
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.ts
@@ -0,0 +1,58 @@
+/**
+ * Wagon figures for a train-schedule list row.
+ *
+ * The list used to report `trainSet.wagonCount` — the COUPLED CONSIST SIZE —
+ * under the label "wgn used", so a 37-wagon train carrying 3 allocated bookings
+ * read "37 wgn used" in the list while its detail page (WagonPlanGrid) read
+ * "37 wagons · 3 in use". These helpers make the list agree with the detail
+ * page, which is the figure staff trust.
+ */
+
+/** The shape this math needs — a slot counts as used when it has allocations. */
+export interface WagonSlotLike {
+  allocations?: unknown[] | null;
+}
+
+export interface ScheduleBookingLike {
+  booking?: { wagonsRequired?: number | null } | null;
+}
+
+export interface ScheduleWagonUsage {
+  /** Coupled slots carrying at least one booking allocation. */
+  wagonsUsed: number;
+  /** Coupled consist size — the denominator of `wagonsUsed`. */
+  wagonsTotal: number;
+  /** Wagons claimed by bookings, including bookings that have not paid. */
+  wagonsReserved: number;
+  /** Consist minus what bookings have claimed — what is still bookable. */
+  wagonsRemaining: number;
+}
+
+export function computeScheduleWagonUsage(input: {
+  wagonSlots?: WagonSlotLike[] | null;
+  /** Stored counter; used only when the slot rows were not loaded. */
+  storedWagonCount?: number | null;
+  scheduleBookings?: ScheduleBookingLike[] | null;
+}): ScheduleWagonUsage {
+  const slots = input.wagonSlots ?? [];
+
+  // Same predicate as the detail page's WagonPlanGrid: a slot is in use only
+  // when a booking is actually allocated onto it.
+  const wagonsUsed = slots.filter((slot) => (slot.allocations?.length ?? 0) > 0).length;
+
+  // Prefer live slot rows; the stored counter drifts when a consist is edited
+  // without a recompute, which is why the list and detail disagreed on totals.
+  const wagonsTotal = slots.length || (input.storedWagonCount ?? 0);
+
+  // An unpaid booking still holds its wagons, so reserved space is NOT bookable.
+  const wagonsReserved = (input.scheduleBookings ?? []).reduce(
+    (sum, link) => sum + (link.booking?.wagonsRequired ?? 0),
+    0,
+  );
+
+  // Reserved subsumes allocated — an allocated booking still counts its wagons —
+  // so remaining subtracts whichever claim is larger, never both.
+  const wagonsRemaining = Math.max(0, wagonsTotal - Math.max(wagonsUsed, wagonsReserved));
+
+  return { wagonsUsed, wagonsTotal, wagonsReserved, wagonsRemaining };
+}
diff --git a/apps/edr-freight-api/src/modules/trains/dto/build-train.dto.ts b/apps/edr-freight-api/src/modules/trains/dto/build-train.dto.ts
index 0c9415e42..7b0bdd3bd 100644
--- a/apps/edr-freight-api/src/modules/trains/dto/build-train.dto.ts
+++ b/apps/edr-freight-api/src/modules/trains/dto/build-train.dto.ts
@@ -51,9 +51,9 @@ export class BuildTrainDto {
   @IsUUID('all', { each: true })
   wagonIds?: string[];
 
-  @ApiProperty({ maxLength: 100, description: 'Vogue number' })
+  @ApiProperty({ maxLength: 100, description: 'Voyage number' })
   @IsString()
-  @IsNotEmpty({ message: 'Vogue number is required' })
+  @IsNotEmpty({ message: 'Voyage number is required' })
   @MaxLength(100)
   trainName!: string;
 
diff --git a/apps/edr-freight-api/src/modules/trains/dto/send-wagon-to-maintenance.dto.ts b/apps/edr-freight-api/src/modules/trains/dto/send-wagon-to-maintenance.dto.ts
new file mode 100644
index 000000000..269c4f9b4
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/trains/dto/send-wagon-to-maintenance.dto.ts
@@ -0,0 +1,15 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsOptional, IsString, MaxLength } from 'class-validator';
+
+export class SendWagonToMaintenanceDto {
+  @ApiPropertyOptional({
+    description:
+      "Why the wagon is going to maintenance. Stored on the wagon's status-history " +
+      'log alongside the train it was detached from, matching the fleet desk flow.',
+    maxLength: 500,
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  note?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/trains/train-builder.controller.ts b/apps/edr-freight-api/src/modules/trains/train-builder.controller.ts
index c1b1459a3..248092f95 100644
--- a/apps/edr-freight-api/src/modules/trains/train-builder.controller.ts
+++ b/apps/edr-freight-api/src/modules/trains/train-builder.controller.ts
@@ -23,6 +23,7 @@ import { AssignTrainWagonsDto } from './dto/assign-train-wagons.dto';
 import { BuildTrainDto } from './dto/build-train.dto';
 import { ListBuiltTrainsQueryDto } from './dto/list-built-trains-query.dto';
 import { ReorderTrainWagonsDto } from './dto/reorder-train-wagons.dto';
+import { SendWagonToMaintenanceDto } from './dto/send-wagon-to-maintenance.dto';
 import { UpdateTrainDetailsDto } from './dto/update-train-details.dto';
 import { UpdateTrainLocomotivesDto } from './dto/update-train-locomotives.dto';
 import { UpdateTrainYardDto } from './dto/update-train-yard.dto';
@@ -135,8 +136,14 @@ export class TrainBuilderController {
     @Param('id', ParseUUIDPipe) id: string,
     @Param('wagonId', ParseUUIDPipe) wagonId: string,
     @CurrentUser() user: AuthUserPayload,
+    @Body() dto?: SendWagonToMaintenanceDto,
   ) {
-    return this.trainBuilderService.sendWagonToMaintenance(id, wagonId, resolveAuthUserId(user));
+    return this.trainBuilderService.sendWagonToMaintenance(
+      id,
+      wagonId,
+      resolveAuthUserId(user),
+      dto?.note,
+    );
   }
 
   @Post(':id/reorder-wagons')
diff --git a/apps/edr-freight-api/src/modules/trains/train-builder.maintenance.spec.ts b/apps/edr-freight-api/src/modules/trains/train-builder.maintenance.spec.ts
new file mode 100644
index 000000000..a6157db7c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/trains/train-builder.maintenance.spec.ts
@@ -0,0 +1,83 @@
+import { buildMaintenanceNotes, formatTrainRunLabel } from './train-builder.service';
+
+describe('formatTrainRunLabel', () => {
+  it('names the train by its export and import run numbers', () => {
+    // What staff actually recognise — NOT the internal code (TRN-LEDGER-PW2).
+    expect(
+      formatTrainRunLabel({
+        exportTrainNumber: '9201',
+        importTrainNumber: '9202',
+        trainNumber: 'TRN-7',
+        code: 'TRN-LEDGER-PW2',
+      }),
+    ).toBe('export 9201 / import 9202');
+  });
+
+  it('shows only the run number that is set', () => {
+    expect(
+      formatTrainRunLabel({ exportTrainNumber: '9201', code: 'TRN-LEDGER-PW2' }),
+    ).toBe('export 9201');
+    expect(
+      formatTrainRunLabel({ importTrainNumber: '9202', code: 'TRN-LEDGER-PW2' }),
+    ).toBe('import 9202');
+  });
+
+  it('falls back to the train number, then the code, when no run is set', () => {
+    expect(formatTrainRunLabel({ trainNumber: 'TRN-7', code: 'TRN-LEDGER-PW2' })).toBe(
+      'TRN-7',
+    );
+    expect(formatTrainRunLabel({ code: 'TRN-LEDGER-PW2' })).toBe('TRN-LEDGER-PW2');
+  });
+
+  it('ignores blank run numbers rather than printing empty labels', () => {
+    expect(
+      formatTrainRunLabel({ exportTrainNumber: '  ', importTrainNumber: null, code: 'C-1' }),
+    ).toBe('C-1');
+  });
+
+  it('never returns an empty label', () => {
+    expect(formatTrainRunLabel({})).toBe('unknown');
+  });
+});
+
+describe('buildMaintenanceNotes', () => {
+  it('records the operator reason together with the train it came off', () => {
+    const notes = buildMaintenanceNotes('export 9201 / import 9202', 'Brake shoe worn through');
+
+    expect(notes.statusLogNote).toBe(
+      'Brake shoe worn through (detached from train export 9201 / import 9202)',
+    );
+    expect(notes.movementNote).toBe(
+      'Sent to maintenance from train export 9201 / import 9202: Brake shoe worn through',
+    );
+  });
+
+  it('still records the train number when no reason is given', () => {
+    // The reason is optional, but which train a wagon left is never optional —
+    // the history has to answer that on its own.
+    const notes = buildMaintenanceNotes('export 9201 / import 9202');
+
+    expect(notes.statusLogNote).toBe('Detached from train export 9201 / import 9202');
+    expect(notes.movementNote).toBe('Sent to maintenance from train export 9201 / import 9202');
+  });
+
+  it('treats a whitespace-only reason as no reason', () => {
+    const notes = buildMaintenanceNotes('export 9201 / import 9202', '   ');
+
+    expect(notes.statusLogNote).toBe('Detached from train export 9201 / import 9202');
+    expect(notes.movementNote).toBe('Sent to maintenance from train export 9201 / import 9202');
+  });
+
+  it('trims padding around a real reason', () => {
+    const notes = buildMaintenanceNotes('export 9201 / import 9202', '  Coupler damage  ');
+
+    expect(notes.statusLogNote).toBe('Coupler damage (detached from train export 9201 / import 9202)');
+    expect(notes.movementNote).toBe('Sent to maintenance from train export 9201 / import 9202: Coupler damage');
+  });
+
+  it('handles a null reason from an older client', () => {
+    expect(buildMaintenanceNotes('export 9201 / import 9202', null).statusLogNote).toBe(
+      'Detached from train export 9201 / import 9202',
+    );
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/trains/train-builder.service.ts b/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
index 9da3cecf0..0f377071c 100644
--- a/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
+++ b/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
@@ -19,6 +19,7 @@ import { TrainSet } from '../train-sets/entities/train-set.entity';
 import { TrainSetWagon } from '../train-sets/entities/train-set-wagon.entity';
 import { WagonType } from '../wagon-types/entities/wagon-type.entity';
 import { WagonMovement } from '../wagons/entities/wagon-movement.entity';
+import { WagonStatusLog } from '../wagons/entities/wagon-status-log.entity';
 import { Wagon } from '../wagons/entities/wagon.entity';
 import { AssignTrainWagonsDto } from './dto/assign-train-wagons.dto';
 import { BuildTrainDto } from './dto/build-train.dto';
@@ -530,7 +531,12 @@ export class TrainBuilderService {
    * moves to MAINTENANCE status (not AVAILABLE), so it is not re-coupled until
    * it clears maintenance. The freed sequence gap is closed.
    */
-  async sendWagonToMaintenance(id: string, wagonId: string, userId?: string | null) {
+  async sendWagonToMaintenance(
+    id: string,
+    wagonId: string,
+    userId?: string | null,
+    note?: string | null,
+  ) {
     await this.dataSource.transaction(async (manager) => {
       const train = await this.getEditableTrain(manager, id);
       const wagon = await manager.getRepository(Wagon).findOne({ where: { id: wagonId } });
@@ -542,6 +548,8 @@ export class TrainBuilderService {
           `Wagon ${wagon.wagonNumber} is pinned to an active schedule and cannot be removed`,
         );
       }
+      const previousStatus = wagon.status;
+      const notes = buildMaintenanceNotes(formatTrainRunLabel(train), note);
       await manager.getRepository(Wagon).update(wagon.id, {
         trainId: null,
         sequenceNumber: null,
@@ -549,6 +557,22 @@ export class TrainBuilderService {
         importTrainNumber: null,
         exportTrainNumber: null,
       });
+
+      // Status-history row, same as the fleet desk's "Send to maintenance" —
+      // without it a maintenance detach made here is invisible in the wagon's
+      // status history. The train number is folded into the note so the history
+      // answers "which train did it come off, and why" in one line.
+      if (previousStatus !== WagonStatus.Maintenance) {
+        await manager.getRepository(WagonStatusLog).save(
+          manager.getRepository(WagonStatusLog).create({
+            wagonId: wagon.id,
+            fromStatus: previousStatus,
+            toStatus: WagonStatus.Maintenance,
+            changedByUserId: userId ?? null,
+            note: notes.statusLogNote,
+          }),
+        );
+      }
       // Audit row: which train it came off and when. The wagon does not change
       // yard here, so from/to are the same — the ledger is the wagon's history
       // surface, and a maintenance detach has to be in it.
@@ -560,7 +584,7 @@ export class TrainBuilderService {
             fromYardId: yardId,
             toYardId: yardId,
             kind: WagonMovementKind.Maintenance,
-            note: `Sent to maintenance from train ${train.trainNumber ?? train.code}`,
+            note: notes.movementNote,
             occurredAt: new Date(),
           }),
         );
@@ -1111,6 +1135,48 @@ export class TrainBuilderService {
  * pinned to a reordered wagon adopt the wagon's new position; unpinned slots
  * trail behind in their previous relative order.
  */
+/**
+ * How a train is named in a wagon's history. Staff identify a train by its
+ * OPERATIONAL run numbers — the fixed export (odd) and import (even) numbers
+ * typed at build time — not by its internal code (`TRN-LEDGER-PW2`), which is a
+ * ledger key and means nothing on the ground. Both runs are shown when set,
+ * since one built train carries the pair. Falls back to the train number, then
+ * the code, only when no run number exists.
+ */
+export function formatTrainRunLabel(train: {
+  exportTrainNumber?: string | null;
+  importTrainNumber?: string | null;
+  trainNumber?: string | null;
+  code?: string | null;
+}): string {
+  const exportNo = train.exportTrainNumber?.trim();
+  const importNo = train.importTrainNumber?.trim();
+  const runs = [
+    exportNo ? `export ${exportNo}` : null,
+    importNo ? `import ${importNo}` : null,
+  ].filter(Boolean);
+  if (runs.length) return runs.join(' / ');
+  return train.trainNumber?.trim() || train.code?.trim() || 'unknown';
+}
+
+/**
+ * Notes for a maintenance detach. The train's run numbers are always recorded —
+ * staff need to know which consist a wagon came off — and the operator's reason
+ * is folded in when given, so the wagon's status history answers "which train,
+ * and why" in one line (matching the fleet desk's Send-to-maintenance note).
+ */
+export function buildMaintenanceNotes(trainLabel: string, note?: string | null) {
+  const reason = note?.trim();
+  return {
+    statusLogNote: reason
+      ? `${reason} (detached from train ${trainLabel})`
+      : `Detached from train ${trainLabel}`,
+    movementNote: reason
+      ? `Sent to maintenance from train ${trainLabel}: ${reason}`
+      : `Sent to maintenance from train ${trainLabel}`,
+  };
+}
+
 export function orderSlotsByWagonSequence<
   T extends Pick<TrainSetWagon, 'sequenceNo' | 'physicalWagonId'>,
 >(slots: T[], newSeq: Map<string, number>): T[] {
diff --git a/apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts b/apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts
index 85c879f70..615ef0701 100644
--- a/apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts
+++ b/apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts
@@ -1,5 +1,7 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import {
+  ArrayMaxSize,
+  IsArray,
   IsInt,
   IsNotEmpty,
   IsOptional,
@@ -11,11 +13,14 @@ import {
 } from 'class-validator';
 
 /**
- * A count-only wagon-transfer request. The requester picks source yard, wagon
- * type, destination yard and HOW MANY — never the specific wagons; OCC hand-picks
- * those at fulfilment. The quantity may not exceed the AVAILABLE wagons of that
- * type currently in the source yard (enforced in the service, which is the only
- * layer that can count them), and a reason is mandatory.
+ * A wagon-transfer request. The requester picks source yard, wagon type,
+ * destination yard and HOW MANY. The quantity may not exceed the AVAILABLE
+ * wagons of that type currently in the source yard (enforced in the service,
+ * which is the only layer that can count them), and a reason is mandatory.
+ *
+ * The requester may additionally name the specific wagons they want via
+ * `preferredWagonIds`. That is a preference recorded for OCC, not a
+ * reservation — the count still drives fulfilment.
  */
 export class CreateTransferRequestDto {
   @IsUUID()
@@ -38,6 +43,17 @@ export class CreateTransferRequestDto {
   @MaxLength(2000)
   reason!: string;
 
+  @ApiPropertyOptional({
+    description:
+      'Specific wagons the requester wants, if they picked any. A preference for OCC — the wagons are not reserved.',
+    type: [String],
+  })
+  @IsOptional()
+  @IsArray()
+  @ArrayMaxSize(1000)
+  @IsUUID('4', { each: true })
+  preferredWagonIds?: string[];
+
   @ApiPropertyOptional({ description: 'Optional note for the fulfilling staff' })
   @IsOptional()
   @IsString()
diff --git a/apps/edr-freight-api/src/modules/wagons/entities/wagon-transfer-request.entity.ts b/apps/edr-freight-api/src/modules/wagons/entities/wagon-transfer-request.entity.ts
index c39b12b9d..8b1922711 100644
--- a/apps/edr-freight-api/src/modules/wagons/entities/wagon-transfer-request.entity.ts
+++ b/apps/edr-freight-api/src/modules/wagons/entities/wagon-transfer-request.entity.ts
@@ -56,6 +56,14 @@ export class WagonTransferRequest extends BaseEntity {
   })
   status!: WagonTransferRequestStatus;
 
+  /**
+   * The wagons the requester specifically asked for, when they picked any. A
+   * preference, not a reservation — the wagons stay AVAILABLE to everyone else,
+   * and OCC may still send different ones. Null/empty on a plain count request.
+   */
+  @Column({ name: 'preferred_wagon_ids', type: 'uuid', array: true, nullable: true })
+  preferredWagonIds?: string[] | null;
+
   @Column({ name: 'requested_by_user_id', type: 'uuid', nullable: true })
   requestedByUserId?: string | null;
 
diff --git a/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.spec.ts b/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.spec.ts
index 8f7457b37..74fb6d6d7 100644
--- a/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.spec.ts
@@ -149,6 +149,19 @@ describe('WagonTransferRequestsService — partial fulfilment', () => {
       expect(result.skipped).toHaveLength(0);
     });
 
+    it('auto-picks the wagons the requester named ahead of the rest', async () => {
+      // Asked for 2 and named w-3 — the auto-pick must take it even though
+      // wagon-number order would have sent w-0 and w-1.
+      build(request({ quantity: 2, preferredWagonIds: ['w-3'] }));
+      wagonRepo.find.mockResolvedValue(availableWagons(5));
+
+      await service.bulkFulfill(['req-1']);
+
+      const [{ wagonIds }] = wagonsService.bulkTransfer.mock.calls[0];
+      expect(wagonIds).toHaveLength(2);
+      expect(wagonIds[0]).toBe('w-3');
+    });
+
     it('skips only when the yard has nothing to give', async () => {
       wagonRepo.find.mockResolvedValue([]);
 
@@ -253,6 +266,84 @@ describe('WagonTransferRequestsService — partial fulfilment', () => {
       expect(requestRepo.save).not.toHaveBeenCalled();
     });
 
+    it('records the wagons the requester hand-picked', async () => {
+      wagonRepo.count.mockResolvedValue(20);
+      wagonRepo.find.mockResolvedValue(availableWagons(3));
+
+      await service.createRequest(
+        {
+          fromYardId: 'yard-a',
+          toYardId: 'yard-b',
+          wagonTypeId: 'type-1',
+          quantity: 3,
+          reason: 'Grain campaign',
+          preferredWagonIds: ['w-0', 'w-1', 'w-2'],
+        },
+        'user-1',
+      );
+
+      expect(stored.preferredWagonIds).toEqual(['w-0', 'w-1', 'w-2']);
+    });
+
+    it('leaves the picks null on a plain count request', async () => {
+      wagonRepo.count.mockResolvedValue(20);
+
+      await service.createRequest(
+        {
+          fromYardId: 'yard-a',
+          toYardId: 'yard-b',
+          wagonTypeId: 'type-1',
+          quantity: 5,
+          reason: 'Grain campaign',
+        },
+        'user-1',
+      );
+
+      expect(stored.preferredWagonIds).toBeNull();
+    });
+
+    it('refuses picks that are not available in the source yard', async () => {
+      wagonRepo.count.mockResolvedValue(20);
+      // Sitting in another yard — the requester's list is stale.
+      wagonRepo.find.mockResolvedValue([
+        { ...availableWagons(1)[0], currentYardId: 'yard-z' },
+      ]);
+
+      await expect(
+        service.createRequest(
+          {
+            fromYardId: 'yard-a',
+            toYardId: 'yard-b',
+            wagonTypeId: 'type-1',
+            quantity: 1,
+            reason: 'Grain campaign',
+            preferredWagonIds: ['w-0'],
+          },
+          'user-1',
+        ),
+      ).rejects.toThrow(/no longer available in the source yard/i);
+      expect(requestRepo.save).not.toHaveBeenCalled();
+    });
+
+    it('refuses more picks than the requested quantity', async () => {
+      wagonRepo.count.mockResolvedValue(20);
+
+      await expect(
+        service.createRequest(
+          {
+            fromYardId: 'yard-a',
+            toYardId: 'yard-b',
+            wagonTypeId: 'type-1',
+            quantity: 2,
+            reason: 'Grain campaign',
+            preferredWagonIds: ['w-0', 'w-1', 'w-2'],
+          },
+          'user-1',
+        ),
+      ).rejects.toThrow(/picked 3 wagon\(s\) but are requesting 2/i);
+      expect(requestRepo.save).not.toHaveBeenCalled();
+    });
+
     it('still refuses a same-yard move', async () => {
       await expect(
         service.createRequest(
diff --git a/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts b/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts
index 6b63460ad..dc50a8742 100644
--- a/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts
+++ b/apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts
@@ -27,6 +27,15 @@ import { WagonMovement } from './entities/wagon-movement.entity';
 import { WagonTransferRequest } from './entities/wagon-transfer-request.entity';
 import { WagonsService } from './wagons.service';
 
+/**
+ * A request as sent to clients: the entity plus the resolved wagon numbers for
+ * whatever the requester hand-picked, so the desk can name them without a
+ * second round trip.
+ */
+export interface TransferRequestView extends WagonTransferRequest {
+  preferredWagons?: Array<{ id: string; wagonNumber: string }>;
+}
+
 /** Bundled per-user activity: requests they touched + wagons they moved. */
 export interface TransferHistory {
   requests: WagonTransferRequest[];
@@ -75,11 +84,15 @@ export class WagonTransferRequestsService {
   ) {}
 
   /**
-   * Record a PENDING request. Count-only — no wagons are picked here, but the
-   * count IS capped by what the source yard can hand over right now: a request
-   * may not exceed the AVAILABLE, uncoupled wagons of that type in the source
-   * yard (the same number the yard desk shows). A reason is mandatory and is
-   * shown on the OCC queue.
+   * Record a PENDING request. The count is capped by what the source yard can
+   * hand over right now: a request may not exceed the AVAILABLE, uncoupled
+   * wagons of that type in the source yard (the same number the yard desk
+   * shows). A reason is mandatory and is shown on the OCC queue.
+   *
+   * The requester may also name the wagons they want (`preferredWagonIds`).
+   * Those are validated against the source yard here so a bad pick is rejected
+   * at request time rather than surfacing at fulfilment, but they are only a
+   * preference — the wagons are not reserved and OCC may send others.
    */
   async createRequest(
     dto: CreateTransferRequestDto,
@@ -104,11 +117,15 @@ export class WagonTransferRequestsService {
         `Only ${available} wagon(s) of this type are available in the source yard — cannot request ${dto.quantity}`,
       );
     }
+
+    const preferredWagonIds = await this.validatePreferredWagons(dto);
+
     const request = this.requestRepo.create({
       fromYardId: dto.fromYardId,
       toYardId: dto.toYardId,
       wagonTypeId: dto.wagonTypeId,
       quantity: dto.quantity,
+      preferredWagonIds,
       status: WagonTransferRequestStatus.Pending,
       requestedByUserId: userId ?? null,
       reason: dto.reason,
@@ -118,6 +135,45 @@ export class WagonTransferRequestsService {
     return this.findById(saved.id);
   }
 
+  /**
+   * Check the requester's hand-picked wagons against the source yard: each must
+   * exist, sit in that yard, match the requested type, be AVAILABLE and be
+   * uncoupled — the same conditions fulfilment will apply. Returns the
+   * de-duplicated ids, or null when the requester picked nothing.
+   */
+  private async validatePreferredWagons(
+    dto: CreateTransferRequestDto,
+  ): Promise<string[] | null> {
+    const ids = [...new Set(dto.preferredWagonIds ?? [])];
+    if (ids.length === 0) return null;
+
+    if (ids.length > dto.quantity) {
+      throw new BadRequestException(
+        `You picked ${ids.length} wagon(s) but are requesting ${dto.quantity} — pick at most ${dto.quantity}`,
+      );
+    }
+
+    const wagons = await this.wagonRepo.find({ where: { id: In(ids) } });
+    if (wagons.length !== ids.length) {
+      throw new NotFoundException('One or more selected wagons not found');
+    }
+    const unusable = wagons.filter(
+      (w) =>
+        w.currentYardId !== dto.fromYardId ||
+        w.wagonTypeId !== dto.wagonTypeId ||
+        w.status !== WagonStatus.Available ||
+        w.trainId != null,
+    );
+    if (unusable.length) {
+      throw new BadRequestException(
+        `These wagons are no longer available in the source yard: ${unusable
+          .map((w) => w.wagonNumber)
+          .join(', ')}`,
+      );
+    }
+    return ids;
+  }
+
   /**
    * AVAILABLE wagons of `wagonTypeId` currently in `yardId` — what OCC can move
    * right now. Shown on the desk beside the outstanding count so staff see at a
@@ -179,16 +235,51 @@ export class WagonTransferRequestsService {
           : 'r.createdAt';
     qb.orderBy(sortColumn, query.sortOrder ?? 'DESC');
 
-    return paginateQuery(qb, { page: query.page, pageSize: query.pageSize });
+    const page = await paginateQuery<WagonTransferRequest>(qb, {
+      page: query.page,
+      pageSize: query.pageSize,
+    });
+    return { ...page, items: await this.withPreferredWagons(page.items) };
   }
 
-  async findById(id: string): Promise<WagonTransferRequest> {
+  /**
+   * Resolve `preferredWagonIds` into wagon numbers for a page of requests in a
+   * single query, so the desk can show WHICH wagons were asked for. Ids that no
+   * longer resolve (purged wagon) simply drop out — the column carries no FK.
+   */
+  private async withPreferredWagons(
+    requests: WagonTransferRequest[],
+  ): Promise<TransferRequestView[]> {
+    const ids = [
+      ...new Set(requests.flatMap((r) => r.preferredWagonIds ?? [])),
+    ];
+    if (ids.length === 0) return requests;
+
+    const wagons = await this.wagonRepo.find({
+      where: { id: In(ids) },
+      select: { id: true, wagonNumber: true },
+    });
+    const byId = new Map(wagons.map((w) => [w.id, w.wagonNumber]));
+
+    return requests.map((r) => {
+      const picked = r.preferredWagonIds ?? [];
+      if (picked.length === 0) return r;
+      return Object.assign(r, {
+        preferredWagons: picked
+          .filter((id) => byId.has(id))
+          .map((id) => ({ id, wagonNumber: byId.get(id)! })),
+      });
+    });
+  }
+
+  async findById(id: string): Promise<TransferRequestView> {
     const request = await this.requestRepo.findOne({
       where: { id },
       relations: REQUEST_RELATIONS,
     });
     if (!request) throw new NotFoundException(`Transfer request ${id} not found`);
-    return request;
+    const [view] = await this.withPreferredWagons([request]);
+    return view;
   }
 
   /** Wagons still owed on an open request. */
@@ -411,7 +502,7 @@ export class WagonTransferRequestsService {
         continue;
       }
       const remaining = this.remainingOn(request);
-      const wagons = await this.wagonRepo.find({
+      const candidates = await this.wagonRepo.find({
         where: {
           currentYardId: request.fromYardId,
           wagonTypeId: request.wagonTypeId,
@@ -419,8 +510,19 @@ export class WagonTransferRequestsService {
           trainId: IsNull(),
         },
         order: { wagonNumber: 'ASC' },
-        take: remaining,
       });
+      // Honour the requester's picks first — any that are still available in
+      // the yard go out ahead of the plain wagon-number order, and the rest of
+      // the instalment is topped up from whatever else is on hand.
+      const preferred = new Set(request.preferredWagonIds ?? []);
+      const wagons = (
+        preferred.size
+          ? [
+              ...candidates.filter((w) => preferred.has(w.id)),
+              ...candidates.filter((w) => !preferred.has(w.id)),
+            ]
+          : candidates
+      ).slice(0, remaining);
       if (wagons.length === 0) {
         skipped.push({
           id,
@@ -479,7 +581,7 @@ export class WagonTransferRequestsService {
     });
 
     return {
-      requests,
+      requests: await this.withPreferredWagons(requests),
       movements,
       meta: {
         page: page ?? 1,
diff --git a/apps/edr-freight-api/src/seed/edr-freight.seed.ts b/apps/edr-freight-api/src/seed/edr-freight.seed.ts
index d90fe7b80..1798a8d5f 100644
--- a/apps/edr-freight-api/src/seed/edr-freight.seed.ts
+++ b/apps/edr-freight-api/src/seed/edr-freight.seed.ts
@@ -191,6 +191,24 @@ const POSITION_TYPE_PERMISSIONS = [
   },
 ] as const;
 
+/**
+ * Audit trail access.
+ *
+ * Read-only by design: `audit_logs` rows are written solely by
+ * `AuditInterceptor` and the module exposes no create/update/delete route, so
+ * there is deliberately no `:create` / `:update` / `:delete` twin to grant.
+ * The matching `:read` key is derived automatically by
+ * `deriveReadPermissions` below.
+ */
+const AUDIT_LOG_PERMISSIONS = [
+  {
+    id: "52b2cdef-5313-4954-8c69-0f8c58ea2c1e",
+    key: "edr_freight_app:audit_log:view",
+    name: { am: "የኦዲት መዝገብ ይመልከቱ", en: "View audit logs" },
+    applicationKey: EDR_FREIGHT_APPLICATION.key,
+  },
+] as const;
+
 const EDR_FREIGHT_VIEWABLE_PERMISSIONS = [
   ...EMPLOYEE_REGISTRATION_PERMISSIONS,
   ...ROLE_ASSIGNMENT_PERMISSIONS,
@@ -198,6 +216,7 @@ const EDR_FREIGHT_VIEWABLE_PERMISSIONS = [
   ...HIERARCHY_POSITION_PERMISSIONS,
   ...HIERARCHY_EMPLOYEE_ASSIGNMENT_PERMISSIONS,
   ...POSITION_TYPE_PERMISSIONS,
+  ...AUDIT_LOG_PERMISSIONS,
   ...BOOKING_RULE_ENGINE_PERMISSIONS,
 ];
 
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 4728cf5f3..57bbda267 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -1622,11 +1622,24 @@ export const FREIGHT_PERMS = {
     dispatch: "edr_freight_app:train_scheduling:dispatch",
     markPaid: "edr_freight_app:train_scheduling:mark_paid",
     expireBooking: "edr_freight_app:train_scheduling:expire_booking",
+    /**
+     * Edit a schedule's operational run numbers (train + voyage) before
+     * dispatch. Separate from `update`: these numbers are what yards and
+     * customs quote, so changing them is narrower than general scheduling edits.
+     */
+    editTrainNumber: "edr_freight_app:train_scheduling:edit_train_number",
   },
   fleet: {
     view: "edr_freight_app:fleet:view",
     manage: "edr_freight_app:fleet:manage",
   },
+  /**
+   * Audit trail. View-only: the module has no write routes, so this is the
+   * only key it needs — see AUDIT_LOG_PERMISSIONS in edr-freight.seed.ts.
+   */
+  auditLog: {
+    view: "edr_freight_app:audit_log:view",
+  },
   admin: "edr_freight_app:admin",
   ruleEngine: {
     view: (slug: RuleEngineResourceSlug) =>
@@ -2124,6 +2137,7 @@ export const ROLE_PERMISSION_PRESETS = {
     FREIGHT_PERMS.trainScheduling.dispatch,
     FREIGHT_PERMS.trainScheduling.markPaid,
     FREIGHT_PERMS.trainScheduling.expireBooking,
+    FREIGHT_PERMS.trainScheduling.editTrainNumber,
     FREIGHT_PERMS.fleet.view,
     FREIGHT_PERMS.fleet.manage,
     ...FLEET_GRANULAR_KEYS,
@@ -2288,6 +2302,7 @@ export const POSITION_PERMISSION_PRESETS = {
     FREIGHT_PERMS.trainScheduling.cancel,
     FREIGHT_PERMS.trainScheduling.reschedule,
     FREIGHT_PERMS.trainScheduling.rulesManage,
+    FREIGHT_PERMS.trainScheduling.editTrainNumber,
     FREIGHT_PERMS.fleet.view,
     FREIGHT_PERMS.fleet.manage,
     ...FLEET_GRANULAR_KEYS,
diff --git a/apps/edr-freight-api/src/seed/freight-positions.seeder.ts b/apps/edr-freight-api/src/seed/freight-positions.seeder.ts
index 09901b502..81df21a17 100644
--- a/apps/edr-freight-api/src/seed/freight-positions.seeder.ts
+++ b/apps/edr-freight-api/src/seed/freight-positions.seeder.ts
@@ -1,5 +1,6 @@
 import { Injectable, Logger } from '@nestjs/common';
 import {
+  Application,
   Organization,
   Permission,
   Position,
@@ -8,7 +9,23 @@ import {
 } from '@tria-plc/iamapi-common';
 import { DataSource, EntityManager, In } from 'typeorm';
 
-import { EDR_FREIGHT_POSITIONS } from './edr-freight.seed';
+import { EDR_FREIGHT_APPLICATION, EDR_FREIGHT_POSITIONS } from './edr-freight.seed';
+
+/**
+ * Turn a permission key into a readable fallback name for a row this seeder has
+ * to mint itself: `edr_freight_app:train_scheduling:edit_train_number` becomes
+ * "Train scheduling: edit train number". Only used for keys absent from the
+ * catalog — a key that IS catalogued keeps its curated Amharic/English name.
+ */
+const nameForKey = (key: string): { en: string } => {
+  const [, ...rest] = key.split(':');
+  const [resource, ...action] = rest;
+  const humanize = (s: string) => s.replace(/_/g, ' ');
+  const label = action.length
+    ? `${humanize(resource)}: ${humanize(action.join(' '))}`
+    : humanize(resource);
+  return { en: label.charAt(0).toUpperCase() + label.slice(1) };
+};
 
 const SEED_FLAG = 'SEED_EDR_ORG';
 const EDR_ORG_KEY = 'edr_freight';
@@ -83,7 +100,19 @@ export class FreightPositionsSeeder {
     );
   }
 
-  /** Resolve every permission key referenced by any position to its id. */
+  /**
+   * Resolve every permission key referenced by any position to its id, minting
+   * the rows that do not exist yet.
+   *
+   * The position presets draw from FREIGHT_PERMS (the registry), which is
+   * broader than the EDR_FREIGHT_PERMISSIONS catalog EdrOrgSeeder inserts —
+   * module keys like `train_scheduling:*` live only in the registry. So every
+   * newly-added preset key would otherwise abort boot with
+   * `missing_permissions:<key>` until someone hand-inserted it. Ensuring them
+   * here keeps this seeder self-sufficient: it declares the keys it needs, so
+   * it is the one that guarantees they exist. Same approach, and the same
+   * id-less insert reasoning, as FreightNotificationPermissionsSeeder.
+   */
   private async loadPermissionIds(
     manager: EntityManager,
   ): Promise<Map<string, string>> {
@@ -91,16 +120,54 @@ export class FreightPositionsSeeder {
       ...new Set(EDR_FREIGHT_POSITIONS.flatMap((p) => p.permissionKeys)),
     ];
 
-    const permissions = await manager.getRepository(Permission).find({
-      where: { key: In(keys) },
-      select: { id: true, key: true },
-    });
-
-    const map = new Map(permissions.map((p) => [p.key, p.id as string]));
+    const read = async () => {
+      const rows = await manager.getRepository(Permission).find({
+        where: { key: In(keys) },
+        select: { id: true, key: true },
+      });
+      return new Map(rows.map((p) => [p.key, p.id as string]));
+    };
 
+    let map = await read();
     const missing = keys.filter((key) => !map.has(key));
-    if (missing.length > 0) {
-      throw new Error(`missing_permissions:${missing.join(',')}`);
+    if (missing.length === 0) {
+      return map;
+    }
+
+    const application = await manager.getRepository(Application).findOne({
+      where: { key: EDR_FREIGHT_APPLICATION.key },
+      select: { id: true },
+    });
+    if (!application?.id) {
+      throw new Error(`missing_application:${EDR_FREIGHT_APPLICATION.key}`);
+    }
+
+    // Ids are left to the column default and never sent: iam.permissions has
+    // two unique columns (PK id, UQ key) and ON CONFLICT can only target one,
+    // so a hand-minted id already owned by a retired key would slip past
+    // ON CONFLICT (key) and die on the PK.
+    await manager
+      .createQueryBuilder()
+      .insert()
+      .into(Permission)
+      .values(
+        missing.map((key) => ({
+          key,
+          name: nameForKey(key),
+          applicationId: application.id as string,
+        })),
+      )
+      .orIgnore()
+      .execute();
+
+    this.logger.log(
+      `Seeded ${missing.length} permission(s) referenced by positions but absent from the catalog: ${missing.join(', ')}`,
+    );
+
+    map = await read();
+    const stillMissing = keys.filter((key) => !map.has(key));
+    if (stillMissing.length > 0) {
+      throw new Error(`missing_permissions:${stillMissing.join(',')}`);
     }
 
     return map;
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index 8d221aaad..8c97dcc08 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -41,6 +41,7 @@ import MyProfilePage from "./pages/dashboard/MyProfilePage";
 import OverviewPage from "./pages/dashboard/OverviewPage";
 import ReportsHubPage from "./pages/reports/ReportsHubPage";
 import ReportPage from "./pages/reports/ReportPage";
+import AuditLogsPage from "./pages/AuditLogsPage";
 import AiBookingMockTestPage from "./pages/ai/AiBookingMockTestPage";
 import PaymentsPage from "./pages/payments/PaymentsPage";
 //import EmployeesPage from "./pages/dashboard/user-management/EmployeesPage";
@@ -188,6 +189,7 @@ const App = () => {
         <Route path="overview" element={<RequirePermission permission={FREIGHT_PERMS.overview.view}><OverviewPage /></RequirePermission>} />
         <Route path="reports" element={<RequirePermission permission={FREIGHT_PERMS.reports.view}><ReportsHubPage /></RequirePermission>} />
         <Route path="reports/:reportKey" element={<RequirePermission permission={FREIGHT_PERMS.reports.view}><ReportPage /></RequirePermission>} />
+        <Route path="audit-logs" element={<RequirePermission permission={FREIGHT_PERMS.auditLog.view}><AuditLogsPage /></RequirePermission>} />
         {/* Dev/testing page for the mock AI booking assistant. */}
         <Route
           path="ai-booking-mock-test"
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingSchedulingWindowCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingSchedulingWindowCard.tsx
index 9b5cf91f2..7f5a4af23 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingSchedulingWindowCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingSchedulingWindowCard.tsx
@@ -142,6 +142,21 @@ export function BookingSchedulingWindowCard({
     schedule?.reference ??
     (schedule ? "Assigned train" : null);
 
+  // Before the batch engine allocates, the only train on the booking is the one
+  // the customer picked at day-commit — staff review that during Operation
+  // Review, so it is labelled as a request, not as a confirmed allocation.
+  const isRequested = schedule?.isRequested === true;
+  const trainRowLabel = isRequested ? "Requested train" : "Scheduled on train";
+
+  // A train that has already left (or is past its planned departure) can no
+  // longer carry this booking, so accepting onto it would be wrong. Called out
+  // here because this card sits above the staff-actions toolbar.
+  const departureIso =
+    schedule?.actualDepartureAt ?? schedule?.scheduledDepartureDate ?? null;
+  const hasDeparted = schedule?.actualDepartureAt
+    ? true
+    : departureIso !== null && new Date(departureIso).getTime() <= nowMs;
+
   return (
     <SectionCard
       icon={CalendarClock}
@@ -153,7 +168,7 @@ export function BookingSchedulingWindowCard({
       <Stack gap="sm">
         {trainLabel ? (
           <Row
-            label="Scheduled on train"
+            label={trainRowLabel}
             value={trainLabel}
             hint={
               schedule?.reference && schedule.reference !== trainLabel
@@ -163,13 +178,21 @@ export function BookingSchedulingWindowCard({
           />
         ) : (
           <Row
-            label="Scheduled on train"
+            label={trainRowLabel}
             value="Not yet allocated"
             tone="muted"
             hint="The booking has not been placed on a train schedule"
           />
         )}
 
+        {isRequested && trainLabel ? (
+          <Text size="xs" c="dimmed">
+            {hasDeparted
+              ? "This train has already departed — accepting the operation will not place the booking on it."
+              : "Picked by the customer at day-commit. Accepting the operation releases the booking to the batch pool for this train."}
+          </Text>
+        ) : null}
+
         {schedule?.status ? (
           <Group justify="space-between" wrap="nowrap">
             <Text size="sm" c="dimmed">
@@ -231,10 +254,15 @@ export function BookingSchedulingWindowCard({
                 formatStamp(schedule.scheduledDepartureDate) ??
                 "—"
               }
+              tone={isRequested && hasDeparted ? "danger" : undefined}
               hint={
                 schedule.actualDepartureAt
                   ? `Actual · planned ${formatStamp(schedule.scheduledDepartureDate) ?? "—"}`
-                  : "Planned"
+                  : departureIso && !hasDeparted
+                    ? `Planned · departs ${formatRelative(departureIso, nowMs)}`
+                    : hasDeparted
+                      ? "Planned — already past"
+                      : "Planned"
               }
             />
             <Row
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/ExportClearanceStepper.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/ExportClearanceStepper.tsx
index f665f388b..af68d0f55 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/ExportClearanceStepper.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/ExportClearanceStepper.tsx
@@ -1006,7 +1006,7 @@ export function ReleaseOrderCard({
   clearance: ClearanceViewLike & { vesselDepartureDate?: string | null };
   onChanged?: () => void;
 }) {
-  const [file, setFile] = useState<File | null>(null);
+  const [files, setFiles] = useState<File[]>([]);
   const [vesselDate, setVesselDate] = useState<Date | null>(
     clearance.vesselDepartureDate ? new Date(clearance.vesselDepartureDate) : null,
   );
@@ -1020,7 +1020,14 @@ export function ReleaseOrderCard({
         Release Order
       </Text>
       <Stack gap="sm">
-        <FileInput label="Release Order" value={file} onChange={setFile} size="sm" />
+        <FileInput
+          label="Release Order"
+          placeholder="Select one or more files"
+          multiple
+          value={files}
+          onChange={setFiles}
+          size="sm"
+        />
         <DateInput
           label="Vessel departure date"
           value={vesselDate}
@@ -1032,15 +1039,15 @@ export function ReleaseOrderCard({
           <Button
             color="edr-green"
             loading={loading}
-            disabled={!file || !vesselDate}
+            disabled={files.length === 0 || !vesselDate}
             onClick={async () => {
-              if (!file || !vesselDate) return;
+              if (files.length === 0 || !vesselDate) return;
               setLoading(true);
               try {
                 const iso = vesselDate.toISOString().slice(0, 10);
                 const result = isBooking
-                  ? await bookingsService.uploadReleaseOrder(entityId, file, iso)
-                  : await contractsService.uploadReleaseOrder(entityId, file, iso);
+                  ? await bookingsService.uploadReleaseOrder(entityId, files, iso)
+                  : await contractsService.uploadReleaseOrder(entityId, files, iso);
                 if (result.hold) {
                   toast.error(result.holdReason ?? "Vessel date too soon");
                 } else {
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/GlClearanceUploadModal.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/GlClearanceUploadModal.tsx
index dfe0bf0e4..95dbc787e 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/GlClearanceUploadModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/GlClearanceUploadModal.tsx
@@ -10,11 +10,10 @@ import {
   toIsoDate,
   useDoCollectionDates,
 } from "@/components/contracts/DoCollectionDateFields";
-import { PhasedFileDropzone } from "@/components/contracts/PhasedFileDropzone";
-import { findWorkflowFile } from "@/components/contracts/PhasedUploadedFileRow";
+import { PhasedMultiFileDropzone } from "@/components/contracts/PhasedFileDropzone";
 import { contractsService } from "@/services/contracts.service";
 import { bookingsService } from "@/services/bookings.service";
-import type { Freight } from "@edr/types";
+import { isDeliveryOrderFileCode, isReleaseOrderFileCode, type Freight } from "@edr/types";
 
 export type GlClearanceUploadKind = "do" | "ro";
 
@@ -44,9 +43,8 @@ export function GlClearanceUploadModal({
   vesselArrivalDate,
   doCollectedDate,
   onSuccess,
-  onPreview,
 }: GlClearanceUploadModalProps) {
-  const [file, setFile] = useState<File | null>(null);
+  const [files, setFiles] = useState<File[]>([]);
   const [vesselDate, setVesselDate] = useState<Date | null>(
     vesselDepartureDate ? new Date(vesselDepartureDate) : null,
   );
@@ -66,16 +64,16 @@ export function GlClearanceUploadModal({
   const isDo = kind === "do";
   const isRo = kind === "ro";
   const replaceMode = isDo
-    ? Boolean(findWorkflowFile(workflowFiles, "delivery_order"))
-    : Boolean(findWorkflowFile(workflowFiles, "release_order"));
+    ? workflowFiles.some((f) => isDeliveryOrderFileCode(f.code) && f.file)
+    : workflowFiles.some((f) => isReleaseOrderFileCode(f.code) && f.file);
 
   const close = () => {
-    setFile(null);
+    setFiles([]);
     onClose();
   };
 
   const submit = async () => {
-    if (!file || !kind) return;
+    if (files.length === 0 || !kind) return;
     if (isRo && !vesselDate) {
       toast.error("Vessel departure date is required.");
       return;
@@ -93,23 +91,23 @@ export function GlClearanceUploadModal({
           doCollectedDate: toIsoDate(doDates.doCollected)!,
         };
         if (isBooking) {
-          await bookingsService.uploadDeliveryOrder(entityId, file, dates);
+          await bookingsService.uploadDeliveryOrder(entityId, files, dates);
         } else {
-          await contractsService.uploadDeliveryOrder(entityId, file, dates);
+          await contractsService.uploadDeliveryOrder(entityId, files, dates);
         }
         toast.success(replaceMode ? "Delivery Order updated" : "Delivery Order uploaded");
       } else {
         const iso = vesselDate!.toISOString().slice(0, 10);
         const result = isBooking
-          ? await bookingsService.uploadReleaseOrder(entityId, file, iso)
-          : await contractsService.uploadReleaseOrder(entityId, file, iso);
+          ? await bookingsService.uploadReleaseOrder(entityId, files, iso)
+          : await contractsService.uploadReleaseOrder(entityId, files, iso);
         if (result.hold) {
           toast.error(result.holdReason ?? "Vessel date too soon");
         } else {
           toast.success(replaceMode ? "Release Order updated" : "Release Order uploaded");
         }
       }
-      setFile(null);
+      setFiles([]);
       onSuccess?.();
       close();
     } catch (e) {
@@ -152,14 +150,15 @@ export function GlClearanceUploadModal({
           <DoCollectionDateFields value={doDates} onChange={setDoDates} />
         )}
 
-        <PhasedFileDropzone
-          label={isDo ? "Delivery Order file" : "Release Order file"}
-          description={isDo ? "Any file type." : "PDF or image."}
+        <PhasedMultiFileDropzone
+          label={isDo ? "Delivery Order files" : "Release Order files"}
+          description={
+            isDo ? "Any file type. Add as many files as needed." : "PDF or image. Add as many files as needed."
+          }
           accept={isDo ? "*/*" : undefined}
-          value={file}
-          onChange={setFile}
+          value={files}
+          onChange={setFiles}
           replaceMode={replaceMode}
-          onPreview={onPreview}
         />
 
         <Group justify="flex-end" gap="sm">
@@ -170,7 +169,7 @@ export function GlClearanceUploadModal({
             color="edr-green"
             loading={loading}
             disabled={
-              !file ||
+              files.length === 0 ||
               (isRo && !vesselDate) ||
               (isDo && !doDatesComplete(doDates))
             }
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/PhasedClearanceActionPanel.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/PhasedClearanceActionPanel.tsx
index 926637db2..4b44edda6 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/PhasedClearanceActionPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/PhasedClearanceActionPanel.tsx
@@ -34,12 +34,15 @@ import {
   Truck,
   Upload,
 } from "lucide-react";
-import type { Freight } from "@edr/types";
+import {
+  deliveryOrderFileLabel,
+  isDeliveryOrderFileCode,
+  type Freight,
+} from "@edr/types";
 import toast from "react-hot-toast";
 
 import { SectionCard } from "@/components/bookings/detail/SectionCard";
 import { ExportClearanceStepper } from "@/components/contracts/ExportClearanceStepper";
-import { PhasedDocumentUploadField } from "@/components/contracts/PhasedDocumentUploadField";
 import {
   DoCollectionDateFields,
   doDatesComplete,
@@ -2133,56 +2136,82 @@ function DeliveryOrderStep({
   onViewFile?: (file: { name: string; url: string }) => void;
   onDownloadFile?: (file: { id: string; name: string }) => void;
 }) {
-  const [files, setFiles] = useState<Record<string, File | null>>({
-    delivery_order: null,
-  });
+  const [files, setFiles] = useState<File[]>([]);
   const [doDates, setDoDates] = useDoCollectionDates({
     vesselArrivalDate,
     doCollectedDate,
   });
   const [loading, setLoading] = useState(false);
-  const hasFile = Boolean(files.delivery_order);
+
+  const submit = async () => {
+    if (files.length === 0 || !doDatesComplete(doDates)) return;
+    const dates = {
+      vesselArrivalDate: toIsoDate(doDates.vesselArrival)!,
+      doCollectedDate: toIsoDate(doDates.doCollected)!,
+    };
+    setLoading(true);
+    try {
+      if (isBooking) {
+        await bookingsService.uploadDeliveryOrder(entityId, files, dates);
+      } else {
+        await contractsService.uploadDeliveryOrder(entityId, files, dates);
+      }
+      setFiles([]);
+      toast.success(replaceMode ? "Delivery Order updated" : "Delivery Order uploaded");
+      onChanged?.();
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "Upload failed");
+    } finally {
+      setLoading(false);
+    }
+  };
 
   return (
-    <PhasedDocumentUploadField
-      fields={[{ key: "delivery_order", label: "Delivery Order" }]}
-      files={files}
-      onChange={(key, file) => setFiles((prev) => ({ ...prev, [key]: file }))}
-      workflowFiles={workflowFiles}
-      replaceMode={replaceMode}
-      loading={loading}
-      disabled={!hasFile || !doDatesComplete(doDates)}
-      helperText="Upload the Djibouti Delivery Order (DO) and record when the vessel arrived and when the DO was collected."
-      submitLabel={replaceMode ? "Replace DO" : "Upload DO"}
-      extraFields={
-        <DoCollectionDateFields value={doDates} onChange={setDoDates} />
-      }
-      onViewFile={onViewFile}
-      onDownloadFile={onDownloadFile}
-      onSubmit={async () => {
-        const file = files.delivery_order;
-        if (!file || !doDatesComplete(doDates)) return;
-        const dates = {
-          vesselArrivalDate: toIsoDate(doDates.vesselArrival)!,
-          doCollectedDate: toIsoDate(doDates.doCollected)!,
-        };
-        setLoading(true);
-        try {
-          if (isBooking) {
-            await bookingsService.uploadDeliveryOrder(entityId, file, dates);
-          } else {
-            await contractsService.uploadDeliveryOrder(entityId, file, dates);
-          }
-          setFiles({ delivery_order: null });
-          toast.success(replaceMode ? "Delivery Order updated" : "Delivery Order uploaded");
-          onChanged?.();
-        } catch (e) {
-          toast.error(e instanceof Error ? e.message : "Upload failed");
-        } finally {
-          setLoading(false);
+    <Stack gap="sm">
+      <Text size="sm" c="dimmed">
+        Upload the Djibouti Delivery Order (DO) and record when the vessel arrived and when the
+        DO was collected. Add as many files as needed.
+      </Text>
+
+      {workflowFiles
+        .filter((wf) => isDeliveryOrderFileCode(wf.code) && wf.file)
+        .map((wf, index) => (
+          <PhasedUploadedFileRow
+            key={wf.code}
+            label={deliveryOrderFileLabel(wf.code, index)}
+            file={wf.file!}
+            onView={onViewFile}
+            onDownload={onDownloadFile}
+          />
+        ))}
+
+      <DoCollectionDateFields value={doDates} onChange={setDoDates} />
+
+      <PhasedMultiFileDropzone
+        label="Delivery Order files"
+        description={
+          replaceMode
+            ? "Replace the DO — upload one or more files (any file type)."
+            : "Upload one or more Delivery Order files (any file type)."
         }
-      }}
-    />
+        accept="*/*"
+        value={files}
+        onChange={setFiles}
+        replaceMode={replaceMode}
+        disabled={loading}
+      />
+
+      <Button
+        color="edr-green"
+        loading={loading}
+        disabled={files.length === 0 || !doDatesComplete(doDates)}
+        leftSection={<Upload size={16} />}
+        fullWidth
+        onClick={() => void submit()}
+      >
+        {replaceMode ? "Replace DO" : "Upload DO"}
+      </Button>
+    </Stack>
   );
 }
 
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 726711a8b..307cb10aa 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -8,6 +8,7 @@ import {
   FileSignature,
   FileText,
   Hammer,
+  History,
   Landmark,
   LayoutDashboard,
   LayoutGrid,
@@ -500,6 +501,12 @@ export const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[]
           FREIGHT_PERMS.settings.supportContent.manage,
         ],
       },
+      {
+        label: "Audit logs",
+        href: "/dashboard/audit-logs",
+        icon: <History />,
+        permission: FREIGHT_PERMS.auditLog.view,
+      },
       {
         label: "Configuration",
         href: "/dashboard/configuration",
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 21033e7fe..23c6fb220 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainBuilder/BuildTrainModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainBuilder/BuildTrainModal.tsx
@@ -88,7 +88,7 @@ export default function BuildTrainModal({ opened, onClose, onBuilt }: BuildTrain
   const handleBuild = async () => {
     if (!trainName.trim()) {
       toast({
-        title: "Enter the vogue number",
+        title: "Enter the voyage number",
         variant: "destructive",
       });
       return;
@@ -150,8 +150,8 @@ export default function BuildTrainModal({ opened, onClose, onBuilt }: BuildTrain
           wagons are attached on the next screen.
         </Text>
         <TextInput
-          label="Vogue number"
-          placeholder="Enter vogue number"
+          label="Voyage number"
+          placeholder="Enter voyage number"
           value={trainName}
           onChange={(e) => setTrainName(e.currentTarget.value)}
           maxLength={100}
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/EligibleBookingsPanel.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/EligibleBookingsPanel.tsx
index 27122d68c..641903b58 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/EligibleBookingsPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/EligibleBookingsPanel.tsx
@@ -1,7 +1,9 @@
 import { useMemo } from "react";
+import { Link } from "react-router-dom";
 import { ArrowRight, Landmark, Package } from "lucide-react";
 import {
   Accordion,
+  Anchor,
   Badge,
   Button,
   Checkbox,
@@ -50,9 +52,20 @@ function EligibleBookingRow({
       <Stack gap={4} style={{ flex: 1 }}>
         <Group gap="xs" wrap="wrap">
           <Package size={14} />
-          <Text fw={600} size="sm">
+          {/* Opens the booking in a new tab: the row is a selection control in
+              an allocation flow, so navigating away would lose staff's picks. */}
+          <Anchor
+            component={Link}
+            to={`/dashboard/booking-requests/${booking.id}`}
+            target="_blank"
+            fw={600}
+            size="sm"
+            c="edr-green.8"
+            underline="hover"
+            onClick={(e) => e.stopPropagation()}
+          >
             {booking.reference}
-          </Text>
+          </Anchor>
           {resolvedFreightType ? (
             <Badge variant="outline" size="xs">
               {resolvedFreightType}
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/MergeScheduleTrainModal.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/MergeScheduleTrainModal.tsx
new file mode 100644
index 000000000..a713918b4
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/MergeScheduleTrainModal.tsx
@@ -0,0 +1,344 @@
+import {
+  Alert,
+  Badge,
+  Box,
+  Button,
+  Card,
+  Group,
+  Loader,
+  Modal,
+  Stack,
+  Text,
+  Textarea,
+  TextInput,
+  ThemeIcon,
+} from "@mantine/core";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { isAxiosError } from "axios";
+import {
+  ArrowRight,
+  Ban,
+  CircleAlert,
+  Merge,
+  Search,
+  TriangleAlert,
+} from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { api } from "@/services/api";
+import { useToast } from "@/hooks/use-toast";
+
+function parseError(error: unknown, fallback: string): string {
+  if (isAxiosError(error)) {
+    const message = error.response?.data?.message;
+    if (Array.isArray(message)) return message.join(", ");
+    if (typeof message === "string") return message;
+  }
+  return fallback;
+}
+
+const fmtDate = (iso: string) =>
+  new Date(iso).toLocaleDateString("en-GB", {
+    day: "numeric",
+    month: "short",
+    year: "numeric",
+  });
+
+export interface MergeScheduleTrainModalProps {
+  scheduleId: string | null;
+  /** This schedule's current train — excluded from the picker. */
+  currentTrainId: string | null;
+  scheduleReference?: string | null;
+  opened: boolean;
+  onClose: () => void;
+  onMerged?: () => void;
+}
+
+/**
+ * Merge another train into this schedule.
+ *
+ * This schedule always survives: its train set is repointed at the chosen
+ * train, that train's wagons join this consist, and the emptied train is
+ * deactivated. When the chosen train also runs a schedule on the SAME DAY, that
+ * schedule's bookings move here and it is removed — its other-day schedules
+ * gain the wagons only. The server computes all of that in `previewMerge`, so
+ * the summary below is exactly what the commit will perform.
+ */
+export default function MergeScheduleTrainModal({
+  scheduleId,
+  currentTrainId,
+  scheduleReference,
+  opened,
+  onClose,
+  onMerged,
+}: MergeScheduleTrainModalProps) {
+  const { toast } = useToast();
+  const [selectedTrainId, setSelectedTrainId] = useState<string | null>(null);
+  const [search, setSearch] = useState("");
+  const [reason, setReason] = useState("");
+
+  const { data: trains = [], isLoading: trainsLoading } = useQuery({
+    ...api.trains.list.queryOptions(),
+    enabled: opened,
+  });
+
+  // The schedule's own train cannot be merged into itself.
+  const options = useMemo(() => {
+    const q = search.trim().toLowerCase();
+    return trains
+      .filter((t) => t.id !== currentTrainId)
+      .filter((t) =>
+        q
+          ? `${t.code} ${t.trainNumber ?? ""} ${t.trainName ?? ""}`
+              .toLowerCase()
+              .includes(q)
+          : true,
+      );
+  }, [trains, currentTrainId, search]);
+
+  const { data: preview, isFetching: previewLoading } = useQuery({
+    ...api.trainScheduling.previewScheduleMerge.queryOptions({
+      input: { id: scheduleId ?? "", targetTrainId: selectedTrainId ?? "" },
+    }),
+    enabled: opened && Boolean(scheduleId && selectedTrainId),
+  });
+
+  const merge = useMutation(api.trainScheduling.mergeScheduleTrain.mutationOptions());
+
+  const close = () => {
+    setSelectedTrainId(null);
+    setSearch("");
+    setReason("");
+    onClose();
+  };
+
+  const submit = async () => {
+    if (!scheduleId || !selectedTrainId || !preview?.canMerge) return;
+    try {
+      await merge.mutateAsync({
+        id: scheduleId,
+        targetTrainId: selectedTrainId,
+        ...(reason.trim() ? { reason: reason.trim() } : {}),
+      });
+      toast({ title: "Trains merged" });
+      onMerged?.();
+      close();
+    } catch (err) {
+      toast({
+        title: "Merge failed",
+        description: parseError(err, "Could not merge the trains"),
+        variant: "destructive",
+      });
+    }
+  };
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={close}
+      centered
+      size="lg"
+      radius="lg"
+      title={
+        <Group gap="sm">
+          <ThemeIcon variant="light" color="edr-green" radius="md" size={34}>
+            <Merge size={18} />
+          </ThemeIcon>
+          <Box>
+            <Text fw={600} lh={1.2}>
+              Merge another train into this one
+            </Text>
+            <Text size="xs" c="dimmed" lh={1.2}>
+              {scheduleReference ?? "This departure survives the merge"}
+            </Text>
+          </Box>
+        </Group>
+      }
+    >
+      <Stack gap="md">
+        <TextInput
+          placeholder="Search train code or number…"
+          leftSection={<Search size={15} />}
+          value={search}
+          onChange={(e) => setSearch(e.currentTarget.value)}
+          radius="md"
+        />
+
+        {trainsLoading ? (
+          <Group justify="center" py="lg">
+            <Loader size="sm" />
+          </Group>
+        ) : options.length === 0 ? (
+          <Text size="sm" c="dimmed" py="sm">
+            No other trains available to merge.
+          </Text>
+        ) : (
+          <Box
+            style={{
+              display: "grid",
+              gridTemplateColumns: "repeat(auto-fill, minmax(160px, 1fr))",
+              gap: 8,
+              maxHeight: 190,
+              overflowY: "auto",
+            }}
+          >
+            {options.map((t) => {
+              const on = t.id === selectedTrainId;
+              return (
+                <Card
+                  key={t.id}
+                  withBorder
+                  radius="md"
+                  padding="xs"
+                  onClick={() => setSelectedTrainId(t.id)}
+                  style={{
+                    cursor: "pointer",
+                    borderColor: on
+                      ? "var(--mantine-color-edr-green-5)"
+                      : undefined,
+                    background: on
+                      ? "var(--mantine-color-edr-green-0)"
+                      : undefined,
+                  }}
+                >
+                  <Text size="sm" fw={on ? 700 : 600} truncate>
+                    {t.code}
+                  </Text>
+                  <Text size="xs" c="dimmed" truncate>
+                    {t.trainNumber ? `No. ${t.trainNumber}` : "—"}
+                  </Text>
+                </Card>
+              );
+            })}
+          </Box>
+        )}
+
+        {selectedTrainId && previewLoading ? (
+          <Group justify="center" py="md">
+            <Loader size="sm" />
+          </Group>
+        ) : null}
+
+        {selectedTrainId && preview && !previewLoading ? (
+          <Stack gap="sm">
+            {preview.blockers.length ? (
+              <Alert
+                variant="light"
+                color="red"
+                icon={<CircleAlert size={16} />}
+                title="This merge is blocked"
+              >
+                <Stack gap={4}>
+                  {preview.blockers.map((b) => (
+                    <Text size="sm" key={b}>
+                      {b}
+                    </Text>
+                  ))}
+                </Stack>
+              </Alert>
+            ) : (
+              <Alert
+                variant="light"
+                color="orange"
+                icon={<TriangleAlert size={16} />}
+              >
+                This cannot be undone. Wagons are appended last — reorder them
+                afterwards in the train builder.
+              </Alert>
+            )}
+
+            <Card withBorder radius="md" padding="sm">
+              <Group gap={8} wrap="nowrap" mb={8}>
+                <Text size="sm" fw={700}>
+                  {preview.wagons.current} wagons
+                </Text>
+                <ArrowRight size={15} />
+                <Text size="sm" fw={700} c="edr-green.8">
+                  {preview.wagons.merged} wagons
+                </Text>
+                <Badge variant="light" color="edr-green" radius="sm">
+                  +{preview.wagons.incoming} from {preview.targetTrain.code}
+                </Badge>
+              </Group>
+
+              {preview.absorbedSchedule ? (
+                <Group gap={6} wrap="nowrap" mb={6}>
+                  <Badge size="sm" color="grape" variant="light" radius="sm">
+                    {fmtDate(preview.absorbedSchedule.scheduledDepartureDate)}
+                  </Badge>
+                  <Text size="sm">
+                    {preview.absorbedSchedule.reference ?? "Same-day schedule"} —{" "}
+                    <Text span fw={700}>
+                      {preview.absorbedSchedule.bookingsMoving} booking(s)
+                    </Text>{" "}
+                    move here, then it is removed
+                  </Text>
+                </Group>
+              ) : null}
+
+              {preview.affectedSchedules.map((s) => (
+                <Group gap={6} wrap="nowrap" mb={4} key={s.id}>
+                  <Badge size="sm" color="blue" variant="light" radius="sm">
+                    {fmtDate(s.scheduledDepartureDate)}
+                  </Badge>
+                  <Text size="sm" c="dimmed">
+                    {s.reference ?? s.id.slice(0, 8)} — gains the wagons, keeps
+                    its own bookings
+                  </Text>
+                </Group>
+              ))}
+
+              {preview.untouchedSchedules.map((s) => (
+                <Group gap={6} wrap="nowrap" mb={4} key={s.id}>
+                  <Badge size="sm" color="gray" variant="light" radius="sm">
+                    {fmtDate(s.scheduledDepartureDate)}
+                  </Badge>
+                  <Text size="sm" c="dimmed">
+                    {s.reference ?? s.id.slice(0, 8)} — {s.status.toLowerCase()},
+                    not affected
+                  </Text>
+                </Group>
+              ))}
+
+              {preview.sourceTrainWillDeactivate ? (
+                <Group gap={6} mt={6} wrap="nowrap">
+                  <Ban size={14} color="var(--mantine-color-red-6)" />
+                  <Text size="sm" c="red.7">
+                    This schedule&apos;s current train is emptied and deactivated.
+                  </Text>
+                </Group>
+              ) : null}
+            </Card>
+
+            {preview.canMerge ? (
+              <Textarea
+                label="Reason"
+                placeholder="Why the trains are being merged (kept on the audit trail)"
+                maxLength={500}
+                autosize
+                minRows={2}
+                value={reason}
+                onChange={(e) => setReason(e.currentTarget.value)}
+              />
+            ) : null}
+          </Stack>
+        ) : null}
+
+        <Group justify="flex-end" mt="xs">
+          <Button variant="default" onClick={close}>
+            Cancel
+          </Button>
+          <Button
+            color="edr-green"
+            leftSection={<Merge size={16} />}
+            loading={merge.isPending}
+            disabled={!preview?.canMerge || previewLoading}
+            onClick={() => void submit()}
+          >
+            Merge trains
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleBookingsStep.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleBookingsStep.tsx
index fec3d78e9..777003545 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleBookingsStep.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleBookingsStep.tsx
@@ -1,4 +1,5 @@
 import {
+  Anchor,
   Badge,
   Button,
   Group,
@@ -7,7 +8,16 @@ import {
   Tabs,
   Text,
 } from "@mantine/core";
-import { ArrowRight, FileText, Landmark, MapPin, Package, Train } from "lucide-react";
+import { Link } from "react-router-dom";
+import {
+  ArrowRight,
+  Building2,
+  FileText,
+  Landmark,
+  MapPin,
+  Package,
+  Train,
+} from "lucide-react";
 
 import type { EligibleContainerBooking, FreightType } from "@/types/trainScheduling";
 
@@ -16,6 +26,8 @@ import { EligibleBookingsPanel } from "./EligibleBookingsPanel";
 export type AssignedBookingRow = {
   id: string;
   reference: string;
+  /** Who booked it — staff scan this list by customer, not by reference. */
+  customer?: string | null;
   weightTons?: number;
   isGovernment?: boolean;
   wagonsRequired?: number | null;
@@ -90,9 +102,19 @@ export function ScheduleBookingsStep({
                 >
                   <Stack gap={4}>
                     <Group gap="xs">
-                      <Text fw={600} size="sm">
+                      {/* Only the reference is the link — the row also carries a
+                          Remove button, so an interactive control must not nest
+                          inside the anchor. */}
+                      <Anchor
+                        component={Link}
+                        to={`/dashboard/booking-requests/${booking.id}`}
+                        fw={600}
+                        size="sm"
+                        c="edr-green.8"
+                        underline="hover"
+                      >
                         {booking.reference}
-                      </Text>
+                      </Anchor>
                       {booking.weightTons != null ? (
                         <Badge variant="outline" size="xs" color="edr-green">
                           {booking.weightTons}T
@@ -119,6 +141,14 @@ export function ScheduleBookingsStep({
                         </Badge>
                       ) : null}
                     </Group>
+                    {booking.customer ? (
+                      <Group gap={4}>
+                        <Building2 size={12} />
+                        <Text size="xs" c="dimmed">
+                          {booking.customer}
+                        </Text>
+                      </Group>
+                    ) : null}
                     {booking.contractReference || booking.origin || booking.destination ? (
                       <Group gap="xs">
                         {booking.contractReference ? (
diff --git a/apps/edr-freight-web/backoffice/src/components/wagons/WagonPicker.tsx b/apps/edr-freight-web/backoffice/src/components/wagons/WagonPicker.tsx
new file mode 100644
index 000000000..e0bfdc0a3
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/wagons/WagonPicker.tsx
@@ -0,0 +1,209 @@
+import {
+  Badge,
+  Box,
+  Button,
+  Checkbox,
+  Group,
+  ScrollArea,
+  Stack,
+  Text,
+  TextInput,
+  ThemeIcon,
+  UnstyledButton,
+} from "@mantine/core";
+import { Check, Search, Train, X } from "lucide-react";
+import { useMemo, useState } from "react";
+
+import type { Wagon } from "@/services/wagon.service";
+
+export interface WagonPickerProps {
+  /** The wagons on offer — already filtered to what the yard can hand over. */
+  wagons: Wagon[];
+  selected: Set<string>;
+  onChange: (next: Set<string>) => void;
+  /** Hard ceiling on the selection; further picks are refused once reached. */
+  max?: number;
+  emptyMessage?: string;
+  maxHeight?: number;
+}
+
+/**
+ * Searchable multi-select over a list of wagons, used wherever staff name the
+ * physical wagons rather than a count. Search matches the wagon number as typed
+ * (case-insensitively, ignoring the dashes and spaces operators leave out) so
+ * "1042" finds "GON-1042".
+ */
+export function WagonPicker({
+  wagons,
+  selected,
+  onChange,
+  max,
+  emptyMessage = "No wagons available here right now.",
+  maxHeight = 260,
+}: WagonPickerProps) {
+  const [query, setQuery] = useState("");
+
+  const normalise = (s: string) => s.toLowerCase().replace(/[\s-]/g, "");
+
+  const shown = useMemo(() => {
+    const q = normalise(query.trim());
+    if (!q) return wagons;
+    return wagons.filter((w) => normalise(w.wagonNumber).includes(q));
+  }, [wagons, query]);
+
+  const ceiling = max ?? Number.MAX_SAFE_INTEGER;
+  const full = selected.size >= ceiling;
+
+  const toggle = (id: string) => {
+    const next = new Set(selected);
+    if (next.has(id)) next.delete(id);
+    else if (next.size >= ceiling) return; // at the cap — ignore the click
+    else next.add(id);
+    onChange(next);
+  };
+
+  /** Select as many of the currently-visible wagons as the cap allows. */
+  const selectShown = () => {
+    const next = new Set(selected);
+    for (const w of shown) {
+      if (next.size >= ceiling) break;
+      next.add(w.id);
+    }
+    onChange(next);
+  };
+
+  return (
+    <Stack gap="xs">
+      <Group gap="xs" wrap="nowrap">
+        <TextInput
+          style={{ flex: 1 }}
+          placeholder="Search wagon number…"
+          leftSection={<Search size={15} />}
+          value={query}
+          onChange={(e) => setQuery(e.currentTarget.value)}
+          rightSection={
+            query ? (
+              <UnstyledButton onClick={() => setQuery("")} aria-label="Clear search">
+                <X size={14} />
+              </UnstyledButton>
+            ) : null
+          }
+          radius="md"
+          size="sm"
+        />
+        <Button
+          size="compact-sm"
+          variant="light"
+          radius="md"
+          onClick={selectShown}
+          disabled={shown.length === 0 || full}
+        >
+          Select {query ? "matches" : "all"}
+        </Button>
+        {selected.size > 0 ? (
+          <Button
+            size="compact-sm"
+            variant="subtle"
+            color="gray"
+            radius="md"
+            onClick={() => onChange(new Set())}
+          >
+            Clear
+          </Button>
+        ) : null}
+      </Group>
+
+      <Group gap="xs" justify="space-between">
+        <Text size="xs" c="dimmed">
+          {shown.length} of {wagons.length} shown
+        </Text>
+        <Badge
+          variant="light"
+          color={full ? "orange" : selected.size > 0 ? "teal" : "gray"}
+          radius="sm"
+        >
+          {selected.size} selected{max != null ? ` / ${max}` : ""}
+        </Badge>
+      </Group>
+
+      {wagons.length === 0 ? (
+        <Text size="sm" c="dimmed" py="sm">
+          {emptyMessage}
+        </Text>
+      ) : shown.length === 0 ? (
+        <Text size="sm" c="dimmed" py="sm">
+          No wagon matches “{query}”.
+        </Text>
+      ) : (
+        <ScrollArea.Autosize mah={maxHeight} type="auto">
+          <Box
+            style={{
+              display: "grid",
+              gridTemplateColumns: "repeat(auto-fill, minmax(150px, 1fr))",
+              gap: 8,
+              paddingRight: 4,
+            }}
+          >
+            {shown.map((w) => {
+              const on = selected.has(w.id);
+              // At the cap, unpicked wagons stop responding — grey them out so
+              // the dead click is explained before it happens.
+              const blocked = !on && full;
+              return (
+                <UnstyledButton
+                  key={w.id}
+                  onClick={() => toggle(w.id)}
+                  disabled={blocked}
+                  style={{
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 8,
+                    padding: "8px 10px",
+                    borderRadius: 8,
+                    border: `1px solid var(--mantine-color-${
+                      on ? "edr-green-5" : "gray-3"
+                    })`,
+                    background: on
+                      ? "var(--mantine-color-edr-green-0)"
+                      : "var(--mantine-color-body)",
+                    opacity: blocked ? 0.45 : 1,
+                    cursor: blocked ? "not-allowed" : "pointer",
+                    transition: "border-color 120ms, background 120ms",
+                  }}
+                >
+                  <Checkbox
+                    checked={on}
+                    onChange={() => toggle(w.id)}
+                    disabled={blocked}
+                    size="xs"
+                    color="edr-green"
+                    tabIndex={-1}
+                    styles={{ input: { cursor: blocked ? "not-allowed" : "pointer" } }}
+                  />
+                  <ThemeIcon
+                    variant="light"
+                    color={on ? "edr-green" : "gray"}
+                    size="sm"
+                    radius="sm"
+                  >
+                    {on ? <Check size={12} /> : <Train size={12} />}
+                  </ThemeIcon>
+                  <Text
+                    size="sm"
+                    fw={on ? 700 : 500}
+                    style={{ fontVariantNumeric: "tabular-nums" }}
+                    truncate
+                  >
+                    {w.wagonNumber}
+                  </Text>
+                </UnstyledButton>
+              );
+            })}
+          </Box>
+        </ScrollArea.Autosize>
+      )}
+    </Stack>
+  );
+}
+
+export default WagonPicker;
diff --git a/apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx b/apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx
index cb9fdf86b..336b9e4ee 100644
--- a/apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx
@@ -26,6 +26,8 @@ import { api } from "@/services/api";
 import { useToast } from "@/hooks/use-toast";
 import type { Wagon } from "@/services/wagon.service";
 
+import WagonPicker from "./WagonPicker";
+
 const stripHtml = (html: string) => html.replace(/<[^>]*>/g, "").trim();
 
 export interface WagonYardWorkspaceModalProps {
@@ -140,6 +142,8 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
   const [transferYardId, setTransferYardId] = useState<string | null>(null);
   const [transferQty, setTransferQty] = useState(0);
   const [transferReason, setTransferReason] = useState("");
+  /** Specific wagons the requester named — optional; empty means "any N". */
+  const [pickedWagons, setPickedWagons] = useState<Set<string>>(new Set());
 
   const createRequest = useMutation(
     api.wagonTransferRequests.create.mutationOptions(),
@@ -240,8 +244,25 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
     setTransferYardId(null);
     setTransferQty(0);
     setTransferReason("");
+    setPickedWagons(new Set());
   }, [yardId, typeId]);
 
+  // Naming wagons IS the ask: the count follows the picks so the two can never
+  // disagree. Lowering the count by hand (below) trims the selection instead.
+  const handlePick = (next: Set<string>) => {
+    setPickedWagons(next);
+    if (next.size > 0) setTransferQty(next.size);
+  };
+
+  const handleQtyChange = (n: number) => {
+    setTransferQty(n);
+    // Asking for fewer than were picked would send a selection the API rejects
+    // (picks may not exceed quantity) — drop the extras, keeping pick order.
+    if (pickedWagons.size > n) {
+      setPickedWagons(new Set([...pickedWagons].slice(0, n)));
+    }
+  };
+
   // Reset the whole workspace when closed.
   useEffect(() => {
     if (!opened) {
@@ -274,16 +295,23 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
         wagonTypeId: typeId,
         quantity: transferQty,
         reason: transferReason,
+        ...(pickedWagons.size > 0
+          ? { preferredWagonIds: [...pickedWagons] }
+          : {}),
       });
       toast({
         title: `Requested ${transferQty} ${typeInfo.code(typeId)} wagon(s) · ${yardName(
           yardId,
         )} → ${yardName(transferYardId)}`,
-        description: "OCC will pick the wagons and complete the move.",
+        description:
+          pickedWagons.size > 0
+            ? `OCC will send the ${pickedWagons.size} wagon(s) you named where it can.`
+            : "OCC will pick the wagons and complete the move.",
       });
       setTransferQty(0);
       setTransferYardId(null);
       setTransferReason("");
+      setPickedWagons(new Set());
     } catch (err) {
       showError(err, "Request failed");
     }
@@ -438,10 +466,36 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
                           ask for more than the yard can hand over. */}
                       <QuantityField
                         value={transferQty}
-                        onChange={setTransferQty}
+                        onChange={handleQtyChange}
                         max={availableCount}
                       />
                     </div>
+
+                    {/* Optional: name the exact wagons. Leaving this empty files
+                        a plain count request and OCC picks whatever is free. */}
+                    <div>
+                      <Group justify="space-between" mb={4} wrap="wrap" gap={4}>
+                        <Text size="sm" fw={500}>
+                          Which wagons{" "}
+                          <Text span size="xs" c="dimmed" fw={400}>
+                            (optional)
+                          </Text>
+                        </Text>
+                        <Text size="xs" c="dimmed">
+                          {pickedWagons.size > 0
+                            ? `${pickedWagons.size} named — OCC will prioritise these`
+                            : "Leave empty and OCC picks any available"}
+                        </Text>
+                      </Group>
+                      <WagonPicker
+                        wagons={availableWagons}
+                        selected={pickedWagons}
+                        onChange={handlePick}
+                        max={availableCount}
+                        emptyMessage="No available wagons of this type in this yard right now."
+                      />
+                    </div>
+
                     <Select
                       label="Destination yard"
                       placeholder="Select destination"
@@ -464,23 +518,42 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
                     </div>
                     {transferYardId && transferQty > 0 ? (
                       <Card bg="var(--mantine-color-gray-0)" radius="md" padding="sm" withBorder>
-                        <Group gap={8} wrap="nowrap">
-                          <Text size="sm" fw={600}>
-                            {yardName(yardId!)} {total}
-                            <Text span c="red.6" fw={700}>
-                              {" "}
-                              −{transferQty}
+                        <Stack gap={6}>
+                          <Group gap={8} wrap="nowrap">
+                            <Text size="sm" fw={600}>
+                              {yardName(yardId!)} {total}
+                              <Text span c="red.6" fw={700}>
+                                {" "}
+                                −{transferQty}
+                              </Text>
                             </Text>
-                          </Text>
-                          <ArrowRight size={16} />
-                          <Text size="sm" fw={600}>
-                            {yardName(transferYardId)}
-                            <Text span c="teal.7" fw={700}>
-                              {" "}
-                              +{transferQty}
+                            <ArrowRight size={16} />
+                            <Text size="sm" fw={600}>
+                              {yardName(transferYardId)}
+                              <Text span c="teal.7" fw={700}>
+                                {" "}
+                                +{transferQty}
+                              </Text>
                             </Text>
-                          </Text>
-                        </Group>
+                          </Group>
+                          {pickedWagons.size > 0 ? (
+                            <Group gap={4} wrap="wrap">
+                              {availableWagons
+                                .filter((w) => pickedWagons.has(w.id))
+                                .map((w) => (
+                                  <Badge
+                                    key={w.id}
+                                    size="sm"
+                                    variant="light"
+                                    color="edr-green"
+                                    radius="sm"
+                                  >
+                                    {w.wagonNumber}
+                                  </Badge>
+                                ))}
+                            </Group>
+                          ) : null}
+                        </Stack>
                       </Card>
                     ) : null}
                     <Button
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index 8a6a52bca..d3566645e 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -57,6 +57,10 @@ export const URL_CONSTANTS = {
     BASE: "/exchange-settings",
   },
 
+  AUDIT_LOGS: {
+    BASE: "/audit",
+  },
+
   DROPDOWN_SETTINGS: {
     BASE: "/dropdown-settings",
     BY_ID: (id: string) => `/api/dropdown-settings/${id}`,
@@ -355,6 +359,9 @@ export const URL_CONSTANTS = {
       `/train-scheduling/schedules/${id}/window-rule`,
     SCHEDULE_DATE: (id: string) =>
       `/train-scheduling/schedules/${id}/schedule-date`,
+    MERGE_PREVIEW: (id: string, targetTrainId: string) =>
+      `/train-scheduling/schedules/${id}/merge-preview/${targetTrainId}`,
+    MERGE_TRAIN: (id: string) => `/train-scheduling/schedules/${id}/merge`,
     CONTRACT_BOOKING_WINDOWS: (contractId: string) =>
       `/train-scheduling/contracts/${contractId}/booking-windows`,
     MARK_BOOKING_PAID: (bookingId: string) =>
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index 8e16c1d96..74de62b74 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -105,6 +105,7 @@ export const FREIGHT_PERMS = {
     dispatch: "edr_freight_app:train_scheduling:dispatch",
     markPaid: "edr_freight_app:train_scheduling:mark_paid",
     expireBooking: "edr_freight_app:train_scheduling:expire_booking",
+    editTrainNumber: "edr_freight_app:train_scheduling:edit_train_number",
   },
   fleet: {
     view: "edr_freight_app:fleet:view",
@@ -311,6 +312,13 @@ export const FREIGHT_PERMS = {
     cancel: "edr_freight_app:warehouse_fee_invoices:cancel",
     pay: "edr_freight_app:warehouse_fee_invoices:pay",
   },
+  /**
+   * Audit trail. View-only — the API exposes no write routes for audit rows,
+   * so there is no manage/delete counterpart to grant.
+   */
+  auditLog: {
+    view: "edr_freight_app:audit_log:view",
+  },
   settings: {
     fileUpload: {
       view: "edr_freight_app:settings:file_upload:view",
diff --git a/apps/edr-freight-web/backoffice/src/pages/AuditLogsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/AuditLogsPage.tsx
new file mode 100644
index 000000000..eac18ca2a
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/AuditLogsPage.tsx
@@ -0,0 +1,340 @@
+import { useMemo, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import {
+  Badge,
+  Card,
+  Code,
+  Group,
+  Loader,
+  Modal,
+  Select,
+  Stack,
+  Table,
+  Text,
+  Tooltip,
+} from "@mantine/core";
+import {
+  usePagination,
+  type OnChangeFn,
+  type PaginationState,
+} from "@edr/ui-common";
+
+import { PageContainer, PageHeader } from "@/components/page";
+import ListControls from "@/components/common/ListControls";
+import RuleEngineListFooter from "@/components/ruleEngine/RuleEngineListFooter";
+import {
+  AUDIT_METHODS,
+  auditLogsService,
+  type AuditLog,
+  type AuditMethod,
+} from "@/services/auditLogs.service";
+
+/** Method → badge colour. Destructive actions read as the loudest. */
+const METHOD_COLORS: Record<AuditMethod, string> = {
+  POST: "green",
+  PUT: "blue",
+  PATCH: "yellow",
+  DELETE: "red",
+};
+
+const OUTCOME_OPTIONS = [
+  { value: "true", label: "Succeeded" },
+  { value: "false", label: "Failed" },
+];
+
+/** `YYYY-MM-DD` → inclusive ISO bounds, so a single day covers its full range. */
+const startOfDay = (date: string) => `${date}T00:00:00.000Z`;
+const endOfDay = (date: string) => `${date}T23:59:59.999Z`;
+
+const formatTimestamp = (value: string) => new Date(value).toLocaleString();
+
+const AuditLogsPage = () => {
+  // Server-side filters. Unlike most freight lists (which filter an
+  // already-fetched array via useListControls), audit_logs is append-only and
+  // grows without bound, so filtering and paging both happen in the API.
+  const [search, setSearch] = useState("");
+  const [dateFrom, setDateFrom] = useState<string | null>(null);
+  const [dateTo, setDateTo] = useState<string | null>(null);
+  const [type, setType] = useState<string | null>(null);
+  const [method, setMethod] = useState<string | null>(null);
+  const [outcome, setOutcome] = useState<string | null>(null);
+  const [selected, setSelected] = useState<AuditLog | null>(null);
+
+  const { pagination, setPagination } = usePagination({ pageIndex: 0, pageSize: 25 });
+
+  const query = useMemo(
+    () => ({
+      page: pagination.pageIndex + 1,
+      pageSize: pagination.pageSize,
+      type: type ?? undefined,
+      method: (method as AuditMethod | null) ?? undefined,
+      isSuccess: outcome === null ? undefined : outcome === "true",
+      // The API filters by record id; the search box is the natural place to
+      // paste one when tracing what happened to a specific contract/booking.
+      resourceId: search.trim() || undefined,
+      from: dateFrom ? startOfDay(dateFrom) : undefined,
+      to: dateTo ? endOfDay(dateTo) : undefined,
+    }),
+    [pagination, type, method, outcome, search, dateFrom, dateTo],
+  );
+
+  const logsQuery = useQuery({
+    queryKey: ["audit-logs", query],
+    queryFn: () => auditLogsService.list(query),
+  });
+
+  const typesQuery = useQuery({
+    queryKey: ["audit-logs", "types"],
+    queryFn: () => auditLogsService.types(),
+  });
+
+  const rows = logsQuery.data?.items ?? [];
+  const totalCount = logsQuery.data?.meta.total ?? 0;
+  const pageCount = logsQuery.data?.meta.totalPages ?? 0;
+
+  const hasFilters = Boolean(
+    search || dateFrom || dateTo || type || method || outcome,
+  );
+
+  const resetFilters = () => {
+    setSearch("");
+    setDateFrom(null);
+    setDateTo(null);
+    setType(null);
+    setMethod(null);
+    setOutcome(null);
+    setPagination({ pageIndex: 0, pageSize: pagination.pageSize });
+  };
+
+  /** Any filter change must return to page 1, or the view can land out of range. */
+  const onFilterChange = <T,>(setter: (value: T) => void) => (value: T) => {
+    setter(value);
+    setPagination({ pageIndex: 0, pageSize: pagination.pageSize });
+  };
+
+  // `OnChangeFn` may hand back either a new value or an updater, so both forms
+  // are resolved before storing.
+  const handlePaginationChange: OnChangeFn<PaginationState> = (updater) => {
+    setPagination((prev) =>
+      typeof updater === "function" ? updater(prev) : updater,
+    );
+  };
+
+  // `PageContainer` gives the page the same horizontal inset and vertical
+  // rhythm as every other dashboard screen; `fluid` lifts the max-width cap
+  // because the log table is wide.
+  return (
+    <PageContainer fluid>
+      <PageHeader
+        title="Audit logs"
+        subtitle="Every state-changing action taken by backoffice staff. Read-only — entries cannot be edited or removed."
+      />
+
+      <Card withBorder padding="md">
+        <Stack gap="md">
+          <ListControls
+            search={search}
+            onSearchChange={onFilterChange(setSearch)}
+            searchPlaceholder="Filter by record id…"
+            dateFrom={dateFrom}
+            onDateFromChange={onFilterChange(setDateFrom)}
+            dateTo={dateTo}
+            onDateToChange={onFilterChange(setDateTo)}
+            dateLabel="Action date"
+            hasFilters={hasFilters}
+            onReset={resetFilters}
+          >
+            <Select
+              label="Entity"
+              placeholder="All entities"
+              data={typesQuery.data ?? []}
+              value={type}
+              onChange={onFilterChange(setType)}
+              clearable
+              searchable
+              w={200}
+            />
+            <Select
+              label="Method"
+              placeholder="All methods"
+              data={[...AUDIT_METHODS]}
+              value={method}
+              onChange={onFilterChange(setMethod)}
+              clearable
+              w={150}
+            />
+            <Select
+              label="Outcome"
+              placeholder="Any outcome"
+              data={OUTCOME_OPTIONS}
+              value={outcome}
+              onChange={onFilterChange(setOutcome)}
+              clearable
+              w={160}
+            />
+          </ListControls>
+
+          {logsQuery.isLoading ? (
+            <Group justify="center" py="xl">
+              <Loader />
+            </Group>
+          ) : logsQuery.isError ? (
+            <Text c="red" ta="center" py="xl">
+              Could not load audit logs.
+            </Text>
+          ) : rows.length === 0 ? (
+            <Text c="dimmed" ta="center" py="xl">
+              No audit entries match these filters.
+            </Text>
+          ) : (
+            <Table.ScrollContainer minWidth={900}>
+              <Table highlightOnHover striped>
+                <Table.Thead>
+                  <Table.Tr>
+                    <Table.Th>Action</Table.Th>
+                    <Table.Th>Entity</Table.Th>
+                    <Table.Th>Method</Table.Th>
+                    <Table.Th>User</Table.Th>
+                    <Table.Th>Outcome</Table.Th>
+                    <Table.Th>When</Table.Th>
+                  </Table.Tr>
+                </Table.Thead>
+                <Table.Tbody>
+                  {rows.map((log) => (
+                    <Table.Tr
+                      key={log.id}
+                      onClick={() => setSelected(log)}
+                      style={{ cursor: "pointer" }}
+                    >
+                      <Table.Td maw={340}>
+                        <Text size="sm" lineClamp={2}>
+                          {log.title}
+                        </Text>
+                      </Table.Td>
+                      <Table.Td>
+                        <Badge variant="light">{log.type}</Badge>
+                      </Table.Td>
+                      <Table.Td>
+                        <Badge color={METHOD_COLORS[log.method]} variant="light">
+                          {log.method}
+                        </Badge>
+                      </Table.Td>
+                      <Table.Td>
+                        <Text size="sm">{log.userName ?? "—"}</Text>
+                        {log.userRole ? (
+                          <Text size="xs" c="dimmed">
+                            {log.userRole}
+                          </Text>
+                        ) : null}
+                      </Table.Td>
+                      <Table.Td>
+                        {log.isSuccess ? (
+                          <Badge color="green" variant="light">
+                            Success
+                          </Badge>
+                        ) : (
+                          // The status code separates "denied" (403) from
+                          // "broke" (500) — both are simply a failure here.
+                          <Tooltip
+                            label={log.errorMessage ?? "Failed"}
+                            multiline
+                            w={280}
+                            disabled={!log.errorMessage}
+                          >
+                            <Badge color="red" variant="light">
+                              Failed{log.statusCode ? ` · ${log.statusCode}` : ""}
+                            </Badge>
+                          </Tooltip>
+                        )}
+                      </Table.Td>
+                      <Table.Td>
+                        <Text size="sm">{formatTimestamp(log.createdAt)}</Text>
+                      </Table.Td>
+                    </Table.Tr>
+                  ))}
+                </Table.Tbody>
+              </Table>
+            </Table.ScrollContainer>
+          )}
+
+          <RuleEngineListFooter
+            pagination={pagination}
+            pageCount={pageCount}
+            totalCount={totalCount}
+            itemLabel="entries"
+            onPaginationChange={handlePaginationChange}
+          />
+        </Stack>
+        </Card>
+
+      <Modal
+        opened={selected !== null}
+        onClose={() => setSelected(null)}
+        title="Audit entry"
+        size="lg"
+      >
+        {selected ? (
+          <Stack gap="sm">
+            <DetailRow label="Action" value={selected.title} />
+            <DetailRow label="Entity" value={selected.type} />
+            <DetailRow label="Record id" value={selected.resourceId} />
+            <DetailRow label="Method" value={selected.method} />
+            <DetailRow label="URL" value={selected.url} />
+            <DetailRow label="Route" value={selected.routePath} />
+            <DetailRow
+              label="Outcome"
+              value={
+                selected.isSuccess
+                  ? `Success${selected.statusCode ? ` (${selected.statusCode})` : ""}`
+                  : `Failed${selected.statusCode ? ` (${selected.statusCode})` : ""}`
+              }
+            />
+            {selected.errorMessage ? (
+              <DetailRow label="Error" value={selected.errorMessage} />
+            ) : null}
+            <DetailRow label="User" value={selected.userName} />
+            <DetailRow label="Role" value={selected.userRole} />
+            <DetailRow label="User id" value={selected.userId} />
+            <DetailRow label="IP address" value={selected.ipAddress} />
+            <DetailRow label="Request id" value={selected.requestId} />
+            <DetailRow
+              label="Duration"
+              value={selected.durationMs === null ? null : `${selected.durationMs} ms`}
+            />
+            <DetailRow label="When" value={formatTimestamp(selected.createdAt)} />
+
+            <div>
+              <Text size="sm" fw={600} mb={4}>
+                Request payload
+              </Text>
+              {selected.request ? (
+                // Secrets are already redacted and uploads reduced to
+                // descriptors by the API before storage.
+                <Code block style={{ maxHeight: 320, overflow: "auto" }}>
+                  {JSON.stringify(selected.request, null, 2)}
+                </Code>
+              ) : (
+                <Text size="sm" c="dimmed">
+                  No payload recorded.
+                </Text>
+              )}
+            </div>
+          </Stack>
+        ) : null}
+      </Modal>
+    </PageContainer>
+  );
+};
+
+const DetailRow = ({ label, value }: { label: string; value: string | null }) => (
+  <Group gap="xs" wrap="nowrap" align="flex-start">
+    <Text size="sm" fw={600} w={120} style={{ flexShrink: 0 }}>
+      {label}
+    </Text>
+    <Text size="sm" style={{ wordBreak: "break-all" }}>
+      {value ?? "—"}
+    </Text>
+  </Group>
+);
+
+export default AuditLogsPage;
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
index 4367fc708..d64b07a45 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
@@ -247,7 +247,6 @@ export default function BookingRequestDetailPage() {
             <Box style={{ position: "sticky", top: 24 }}>
               <Stack gap="lg">
                 <BookingCompanyCard booking={booking} />
-                <BookingSchedulingWindowCard booking={booking} />
                 <BookingPricingSummary booking={booking} />
                 <Box id="warehouse-payments">
                   <WarehouseInfoCard
@@ -257,6 +256,11 @@ export default function BookingRequestDetailPage() {
                     tradeDirection={booking.tradeDirection}
                   />
                 </Box>
+                {/* Sits directly above the staff actions: reviewing an operation
+                    request means approving the booking onto a specific train, so
+                    that train and its clock must be readable before the approve
+                    button. */}
+                <BookingSchedulingWindowCard booking={booking} />
                 <BookingActionsToolbar
                   booking={booking}
                   mutations={mutations}
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
index 400bfc1e5..b740a6688 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
@@ -10,6 +10,7 @@ import {
   Progress,
   Stack,
   Text,
+  Textarea,
 } from "@mantine/core";
 import { useMutation, useQuery } from "@tanstack/react-query";
 import { isAxiosError } from "axios";
@@ -82,6 +83,13 @@ export default function TrainBuilderDetailPage() {
   const [deactivateOpen, setDeactivateOpen] = useState(false);
   const [maintenanceTarget, setMaintenanceTarget] =
     useState<TrainCompositionWagon | null>(null);
+  const [maintenanceNote, setMaintenanceNote] = useState("");
+  // Clearing the note with the target stops one wagon's reason being carried
+  // over onto the next wagon sent to maintenance.
+  const closeMaintenance = () => {
+    setMaintenanceTarget(null);
+    setMaintenanceNote("");
+  };
   const { user } = useAuth();
   const canAssign = hasPermission(user, FREIGHT_PERMS.trains.assignWagons);
   const canChangeLocomotives = hasPermission(user, FREIGHT_PERMS.trains.changeLocomotives);
@@ -103,6 +111,19 @@ export default function TrainBuilderDetailPage() {
   const activate = useMutation(api.trainBuilder.activate.mutationOptions());
 
   const composition = compositionQuery.data;
+  // Staff identify a train by its operational run numbers, not the internal
+  // code — mirrors formatTrainRunLabel on the API, which writes the history note.
+  const trainRunLabel =
+    [
+      composition?.exportTrainNumber?.trim()
+        ? `export ${composition.exportTrainNumber.trim()}`
+        : null,
+      composition?.importTrainNumber?.trim()
+        ? `import ${composition.importTrainNumber.trim()}`
+        : null,
+    ]
+      .filter(Boolean)
+      .join(" / ") || composition?.code;
   const busy =
     assignWagons.isPending ||
     removeWagon.isPending ||
@@ -463,7 +484,7 @@ export default function TrainBuilderDetailPage() {
 
       <Modal
         opened={Boolean(maintenanceTarget)}
-        onClose={() => setMaintenanceTarget(null)}
+        onClose={closeMaintenance}
         title={<Text fw={600}>Send wagon to maintenance?</Text>}
         radius="lg"
         centered
@@ -476,14 +497,22 @@ export default function TrainBuilderDetailPage() {
             </Text>{" "}
             is detached from train{" "}
             <Text span fw={700} c="dark">
-              {composition.code}
+              {trainRunLabel}
             </Text>{" "}
             and set to MAINTENANCE — it stays out of the available pool until it
-            clears. The detach is stamped with the time and this train number in
-            the wagon's history.
+            clears. The detach is stamped with the time and this train's run
+            numbers in the wagon's history.
           </Text>
+          <Textarea
+            label="Note"
+            placeholder="Optional note (e.g. reason for maintenance)"
+            value={maintenanceNote}
+            onChange={(e) => setMaintenanceNote(e.currentTarget.value)}
+            autosize
+            minRows={2}
+          />
           <Group justify="flex-end">
-            <Button variant="default" onClick={() => setMaintenanceTarget(null)}>
+            <Button variant="default" onClick={closeMaintenance}>
               Keep in consist
             </Button>
             <Button
@@ -495,11 +524,12 @@ export default function TrainBuilderDetailPage() {
                   await maintenanceWagon.mutateAsync({
                     id: composition.id,
                     wagonId: maintenanceTarget!.id,
+                    note: maintenanceNote.trim() || undefined,
                   });
                   toast({
                     title: `Wagon ${maintenanceTarget!.wagonNumber} sent to maintenance`,
                   });
-                  setMaintenanceTarget(null);
+                  closeMaintenance();
                 }, "Could not send wagon to maintenance")
               }
             >
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
index 9b32d19b6..cf6c37e80 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
@@ -23,6 +23,7 @@ import {
   CalendarClock,
   CheckCircle2,
   Clock,
+  Merge,
   Container as ContainerIcon,
   Eye,
   FileText,
@@ -54,6 +55,7 @@ import { ContainerPlacementGrid } from "@/components/trainScheduling/ContainerPl
 import { FleetAvailabilitySummary } from "@/components/trainScheduling/FleetAvailabilitySummary";
 import { IntercityRideAlongPanel } from "@/components/trainScheduling/IntercityRideAlongPanel";
 import { LegCapacityPanel } from "@/components/trainScheduling/LegCapacityPanel";
+import MergeScheduleTrainModal from "@/components/trainScheduling/MergeScheduleTrainModal";
 import ScheduleHistoryPanel from "@/components/trainScheduling/ScheduleHistoryPanel";
 // import { ImportLoadingConfirmationPanel } from "@/components/trainScheduling/ImportLoadingConfirmationPanel";
 import { RescheduleTrainDialog } from "@/components/trainScheduling/RescheduleTrainDialog";
@@ -114,6 +116,7 @@ export default function TrainScheduleV2DetailPage() {
   const [containerPlacements, setContainerPlacements] = useState<ContainerPlacement[]>([]);
   const [maintenanceOpen, setMaintenanceOpen] = useState(false);
   const [windowSettingsOpen, setWindowSettingsOpen] = useState(false);
+  const [mergeModalOpen, setMergeModalOpen] = useState(false);
   const [gatepassSecuredAt, setGatepassSecuredAt] = useState("");
   const [gatepassReference, setGatepassReference] = useState("");
   const [gatepassFileUrl, setGatepassFileUrl] = useState("");
@@ -400,7 +403,6 @@ export default function TrainScheduleV2DetailPage() {
   const canDispatch =
     schedule.status === "SCHEDULED" &&
     hasPermission(authUser, FREIGHT_PERMS.trainScheduling.dispatch);
-
   // Dispatch readiness: bookings with no wagon, and wagon-loaded bookings whose
   // cargo staff never marked loaded. Both are warnings, not blockers — staff can
   // still dispatch after confirming.
@@ -667,6 +669,7 @@ export default function TrainScheduleV2DetailPage() {
             assignedBookings={(schedule.bookings ?? []).map((b) => ({
               id: b.id,
               reference: b.reference ?? b.id.slice(0, 8),
+              customer: b.customer,
               weightTons: b.weightTons,
               isGovernment: b.isGovernment,
               wagonsRequired: b.wagonsRequired,
@@ -940,7 +943,7 @@ export default function TrainScheduleV2DetailPage() {
                   {schedule.trainNumber ? (
                     <Box>
                       <Text size="xs" c="dimmed" fw={600} tt="uppercase" lh={1.2}>
-                        Voyage No.
+                        Train No.
                       </Text>
                       <Text
                         ff="monospace"
@@ -952,6 +955,33 @@ export default function TrainScheduleV2DetailPage() {
                       </Text>
                     </Box>
                   ) : null}
+                  {schedule.voyageNumber ? (
+                    <Box>
+                      <Text size="xs" c="dimmed" fw={600} tt="uppercase" lh={1.2}>
+                        Voyage No.
+                      </Text>
+                      <Text
+                        ff="monospace"
+                        fw={800}
+                        lh={1.1}
+                        style={{ fontSize: 32, color: "#0f172a" }}
+                      >
+                        {schedule.voyageNumber}
+                      </Text>
+                    </Box>
+                  ) : null}
+                  {/* Merging rewrites the consist, so it is offered only while
+                      the departure can still be edited. */}
+                  {canEditBookings ? (
+                    <Button
+                      variant="light"
+                      size="compact-sm"
+                      leftSection={<Merge size={14} />}
+                      onClick={() => setMergeModalOpen(true)}
+                    >
+                      Merge
+                    </Button>
+                  ) : null}
                   {schedule.direction ? (
                     <Box>
                       <Text size="xs" c="dimmed" fw={600} tt="uppercase" lh={1.2}>
@@ -1369,6 +1399,15 @@ export default function TrainScheduleV2DetailPage() {
         onSaved={() => void detailQuery.refetch()}
       />
 
+      <MergeScheduleTrainModal
+        scheduleId={scheduleId ?? null}
+        currentTrainId={schedule.trainSet?.trainId ?? null}
+        scheduleReference={schedule.reference ?? null}
+        opened={mergeModalOpen}
+        onClose={() => setMergeModalOpen(false)}
+        onMerged={() => void detailQuery.refetch()}
+      />
+
       <SwitchGovernmentBookingModal
         key={switchTarget?.id ?? "none"}
         opened={Boolean(switchTarget)}
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 c132c2534..9755e6bee 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
@@ -134,6 +134,9 @@ export default function TrainScheduleV2ListPage() {
   // confirmation.
   const [dispatchTarget, setDispatchTarget] =
     useState<TrainScheduleListItem | null>(null);
+  // Cancelling is likewise irreversible — confirmed before the mutation fires.
+  const [cancelTarget, setCancelTarget] =
+    useState<TrainScheduleListItem | null>(null);
   const [editDateSchedule, setEditDateSchedule] =
     useState<TrainScheduleListItem | null>(null);
   const [routeId, setRouteId] = useState("");
@@ -424,9 +427,7 @@ export default function TrainScheduleV2ListPage() {
         cell: ({ row }) => (
           <Group gap={6} wrap="nowrap">
             <MetricChip value={row.original.bookingsCount} label="bkg" />
-            {/* 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" />
+            <WagonChips schedule={row.original} />
             <MetricChip value={`${row.original.totalWeightTons}T`} label="" subtle />
           </Group>
         ),
@@ -503,21 +504,7 @@ export default function TrainScheduleV2ListPage() {
                     <Menu.Item
                       color="red"
                       leftSection={<Ban size={15} />}
-                      onClick={async () => {
-                        try {
-                          await cancel.mutateAsync({
-                            id: schedule.id,
-                            freightType: schedule.freightType ?? "CONTAINER",
-                          });
-                          toast({ title: "Schedule cancelled" });
-                        } catch (err) {
-                          toast({
-                            title: "Cancel failed",
-                            description: parseError(err, "Could not cancel"),
-                            variant: "destructive",
-                          });
-                        }
-                      }}
+                      onClick={() => setCancelTarget(schedule)}
                     >
                       Cancel schedule
                     </Menu.Item>
@@ -969,10 +956,118 @@ export default function TrainScheduleV2ListPage() {
           </Group>
         </Stack>
       </Modal>
+
+      {/* Cancelling a schedule is destructive and cannot be undone, so it is
+          confirmed here rather than firing straight from the row menu. */}
+      <Modal
+        opened={cancelTarget != null}
+        onClose={() => setCancelTarget(null)}
+        title="Cancel this schedule?"
+        centered
+        radius="md"
+      >
+        <Stack gap="md">
+          <Text size="sm" c="dimmed">
+            <Text span fw={600} c="dark">
+              {cancelTarget?.trainNumber ?? cancelTarget?.reference ?? "This train"}
+            </Text>{" "}
+            will be cancelled and removed from the active schedule board. This
+            cannot be undone.
+          </Text>
+          {cancelTarget?.bookingsCount ? (
+            <Text size="sm" c="red.7" fw={500}>
+              {cancelTarget.bookingsCount} booking
+              {cancelTarget.bookingsCount === 1 ? "" : "s"} on this train will
+              need to be moved to another schedule.
+            </Text>
+          ) : null}
+          <Group justify="flex-end" gap="sm">
+            <Button variant="default" onClick={() => setCancelTarget(null)}>
+              Keep schedule
+            </Button>
+            <Button
+              color="red"
+              leftSection={<Ban size={16} />}
+              loading={cancel.isPending}
+              onClick={async () => {
+                if (!cancelTarget) return;
+                try {
+                  await cancel.mutateAsync({
+                    id: cancelTarget.id,
+                    freightType: cancelTarget.freightType ?? "CONTAINER",
+                  });
+                  toast({ title: "Schedule cancelled" });
+                  setCancelTarget(null);
+                  void schedulesQuery.refetch();
+                } catch (err) {
+                  toast({
+                    title: "Cancel failed",
+                    description: parseError(err, "Could not cancel"),
+                    variant: "destructive",
+                  });
+                }
+              }}
+            >
+              Cancel schedule
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
     </PageContainer>
   );
 }
 
+/**
+ * The row's wagon chips, matching the detail page's wagon plan: used is slots
+ * carrying a booking allocation (never the coupled consist size), and remaining
+ * excludes wagons reserved by bookings that have not paid yet — that space is
+ * claimed, so it is not bookable.
+ *
+ * Schedules whose train set has not been built yet have no consist to measure,
+ * so both figures fall back to the schedule's planned `maxWagons` ceiling.
+ * Without that fallback an unbuilt 37-wagon schedule reads "0 bookable" even
+ * though every one of its wagons is still free.
+ */
+function WagonChips({ schedule }: { schedule: TrainScheduleListItem }) {
+  // Pre-deploy API rows carry only wagonCount; fall back so the chip still
+  // renders rather than reading 0 used on every train.
+  const total = schedule.wagonsTotal ?? schedule.wagonCount;
+  const used = schedule.wagonsUsed;
+  const reserved = schedule.wagonsReserved ?? 0;
+
+  // Until the train set is built there is no consist to measure against, so
+  // `wagonsRemaining` (consist minus claimed) is 0 on every unbuilt schedule —
+  // which reads as "fully booked" when in fact nothing is booked at all. Before
+  // a consist exists, capacity is the planned ceiling minus what bookings have
+  // already claimed.
+  const planCeiling = schedule.maxWagons ?? 0;
+  const remaining =
+    total === 0 && planCeiling > 0
+      ? Math.max(0, planCeiling - Math.max(used ?? 0, reserved))
+      : schedule.wagonsRemaining;
+
+  if (used == null) {
+    return <MetricChip value={total} label="wgn" subtle />;
+  }
+
+  return (
+    <>
+      {/* An unbuilt consist has no "used out of coupled" to show; the plan
+          ceiling is the only meaningful denominator at that point. */}
+      <MetricChip
+        value={total === 0 && planCeiling > 0 ? `${used}/${planCeiling}` : `${used}/${total}`}
+        label={total === 0 && planCeiling > 0 ? "wgn planned" : "wgn used"}
+      />
+      {reserved > used ? (
+        <MetricChip value={reserved} label="reserved" subtle />
+      ) : null}
+      {remaining != null ? (
+        <MetricChip value={remaining} label="bookable" subtle />
+      ) : null}
+    </>
+  );
+}
+
 function MetricChip({
   value,
   label,
@@ -1078,7 +1173,7 @@ function ScheduleCard({
           </Group>
           <Group gap={6} wrap="nowrap">
             <MetricChip value={schedule.bookingsCount} label="bkg" />
-            <MetricChip value={schedule.wagonCount} label="wgn used" />
+            <WagonChips schedule={schedule} />
             <MetricChip value={`${schedule.totalWeightTons}T`} label="" subtle />
           </Group>
         </Group>
diff --git a/apps/edr-freight-web/backoffice/src/pages/wagons/TransferFulfillModal.tsx b/apps/edr-freight-web/backoffice/src/pages/wagons/TransferFulfillModal.tsx
index 6f5a0c129..4a4a3d870 100644
--- a/apps/edr-freight-web/backoffice/src/pages/wagons/TransferFulfillModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/wagons/TransferFulfillModal.tsx
@@ -2,19 +2,18 @@ import { Freight } from "@edr/types";
 import {
   Alert,
   Button,
-  Checkbox,
   Group,
   Loader,
   Modal,
-  ScrollArea,
   Stack,
   Text,
 } from "@mantine/core";
 import { useMutation, useQuery } from "@tanstack/react-query";
 import { AlertTriangle, ArrowRight, PackageCheck } from "lucide-react";
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import toast from "react-hot-toast";
 
+import WagonPicker from "@/components/wagons/WagonPicker";
 import { api } from "@/services/api";
 import type { WagonTransferRequest } from "@/services/wagon.service";
 
@@ -59,23 +58,21 @@ export function TransferFulfillModal({
 
   const fulfill = useMutation(api.wagonTransferRequests.fulfill.mutationOptions());
 
-  const canTake = useMemo(
-    () => Math.min(outstanding, wagons.length),
-    [outstanding, wagons.length],
-  );
+  /** The requester's picks that are still in this yard and still available. */
+  const preferredHere = useMemo(() => {
+    const asked = new Set(request?.preferredWagonIds ?? []);
+    return asked.size ? wagons.filter((w) => asked.has(w.id)) : [];
+  }, [request, wagons]);
 
-  const toggle = (id: string) =>
-    setPicked((prev) => {
-      const next = new Set(prev);
-      if (next.has(id)) next.delete(id);
-      // Never let staff pick more than is still owed — the API rejects it too.
-      else if (next.size >= outstanding) return prev;
-      else next.add(id);
-      return next;
-    });
+  const missingPreferred =
+    (request?.preferredWagonIds?.length ?? 0) - preferredHere.length;
 
-  const takeAllAvailable = () =>
-    setPicked(new Set(wagons.slice(0, canTake).map((w) => w.id)));
+  // Open on what the requester asked for: OCC confirms rather than re-picks.
+  // Re-runs when the wagon list arrives, and is capped at what is still owed.
+  useEffect(() => {
+    if (!request) return;
+    setPicked(new Set(preferredHere.slice(0, outstanding).map((w) => w.id)));
+  }, [request, preferredHere, outstanding]);
 
   const close = () => {
     setPicked(new Set());
@@ -120,27 +117,16 @@ export function TransferFulfillModal({
     >
       {!request ? null : (
         <Stack gap="sm">
-          <Group justify="space-between" wrap="wrap">
-            <Text size="sm">
-              <Text span fw={700}>
-                {outstanding}
-              </Text>{" "}
-              wagon(s) still owed ·{" "}
-              <Text span fw={700}>
-                {wagons.length}
-              </Text>{" "}
-              available in {yardLabel(request.fromYard)}
-            </Text>
-            <Button
-              variant="light"
-              size="xs"
-              radius="md"
-              disabled={canTake === 0}
-              onClick={takeAllAvailable}
-            >
-              Select {canTake}
-            </Button>
-          </Group>
+          <Text size="sm">
+            <Text span fw={700}>
+              {outstanding}
+            </Text>{" "}
+            wagon(s) still owed ·{" "}
+            <Text span fw={700}>
+              {wagons.length}
+            </Text>{" "}
+            available in {yardLabel(request.fromYard)}
+          </Text>
 
           {wagons.length < outstanding ? (
             <Alert color="yellow" radius="md" icon={<AlertTriangle size={15} />}>
@@ -150,27 +136,39 @@ export function TransferFulfillModal({
             </Alert>
           ) : null}
 
+          {preferredHere.length > 0 ? (
+            <Alert color="teal" radius="md" icon={<PackageCheck size={15} />}>
+              The requester named{" "}
+              <Text span fw={700}>
+                {preferredHere.length}
+              </Text>{" "}
+              specific wagon(s) — pre-selected below. You can change the
+              selection freely; the request is a count, not a reservation.
+            </Alert>
+          ) : null}
+
+          {missingPreferred > 0 ? (
+            <Alert color="orange" radius="md" icon={<AlertTriangle size={15} />}>
+              {missingPreferred} of the wagon(s) the requester named{" "}
+              {missingPreferred === 1 ? "is" : "are"} no longer available in this
+              yard. Pick replacements below.
+            </Alert>
+          ) : null}
+
           {isLoading ? (
             <Group justify="center" py="lg">
               <Loader size="sm" />
             </Group>
-          ) : wagons.length === 0 ? (
-            <Text c="dimmed" size="sm" py="md">
-              No available wagons of this type in the source yard right now.
-            </Text>
           ) : (
-            <ScrollArea.Autosize mah={320}>
-              <Stack gap={4}>
-                {wagons.map((w) => (
-                  <Checkbox
-                    key={w.id}
-                    checked={picked.has(w.id)}
-                    onChange={() => toggle(w.id)}
-                    label={w.wagonNumber}
-                  />
-                ))}
-              </Stack>
-            </ScrollArea.Autosize>
+            <WagonPicker
+              wagons={wagons}
+              selected={picked}
+              onChange={setPicked}
+              // Never let staff pick more than is still owed — the API rejects it too.
+              max={outstanding}
+              emptyMessage="No available wagons of this type in the source yard right now."
+              maxHeight={300}
+            />
           )}
 
           <Group justify="flex-end" gap="sm">
diff --git a/apps/edr-freight-web/backoffice/src/pages/wagons/TransferRequestModals.tsx b/apps/edr-freight-web/backoffice/src/pages/wagons/TransferRequestModals.tsx
index a58d49bf1..f23ea6ed9 100644
--- a/apps/edr-freight-web/backoffice/src/pages/wagons/TransferRequestModals.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/wagons/TransferRequestModals.tsx
@@ -15,6 +15,7 @@ import { AlertTriangle, Send, XCircle } from "lucide-react";
 import { useEffect, useState } from "react";
 import toast from "react-hot-toast";
 
+import WagonPicker from "@/components/wagons/WagonPicker";
 import { api } from "@/services/api";
 import type { WagonTransferRequest } from "@/services/wagon.service";
 
@@ -45,9 +46,11 @@ function useTransferOptions(enabled: boolean) {
 /**
  * Wagons the source yard can hand over right now — AVAILABLE and not coupled to
  * a built train. Mirrors `countAvailable` on the API, which rejects any request
- * asking for more than this, so the field must not let one be filed.
+ * asking for more than this, so the field must not let one be filed. Returns
+ * the wagons themselves so the form can also offer them for picking; `count` is
+ * null until both a yard and a type are chosen.
  */
-function useAvailableCount(
+function useAvailableWagons(
   enabled: boolean,
   fromYardId: string | null,
   wagonTypeId: string | null,
@@ -56,14 +59,15 @@ function useAvailableCount(
     ...api.wagons.list.queryOptions({ input: {} }),
     enabled: enabled && Boolean(fromYardId && wagonTypeId),
   });
-  if (!fromYardId || !wagonTypeId) return null;
-  return wagons.filter(
+  if (!fromYardId || !wagonTypeId) return { wagons: [], count: null };
+  const inYard = wagons.filter(
     (w) =>
       w.currentYardId === fromYardId &&
       w.wagonTypeId === wagonTypeId &&
       w.status === Freight.WagonStatus.Available &&
       !w.trainId,
-  ).length;
+  );
+  return { wagons: inYard, count: inYard.length };
 }
 
 export interface TransferRequestFormModalProps {
@@ -95,6 +99,8 @@ export function TransferRequestFormModal({
   const [wagonTypeId, setWagonTypeId] = useState<string | null>(null);
   const [quantity, setQuantity] = useState<number | string>(1);
   const [reason, setReason] = useState("");
+  /** Specific wagons the requester named — optional; empty means "any N". */
+  const [picked, setPicked] = useState<Set<string>>(new Set());
 
   // Re-seed on every open so a carry-over never leaks into the next request.
   useEffect(() => {
@@ -104,11 +110,27 @@ export function TransferRequestFormModal({
     setWagonTypeId(prefillFrom?.wagonTypeId ?? null);
     setQuantity(prefillFrom ? outstandingOn(prefillFrom) : 1);
     setReason(prefillFrom?.reason ?? "");
+    setPicked(new Set());
   }, [opened, prefillFrom]);
 
   const create = useMutation(api.wagonTransferRequests.create.mutationOptions());
 
-  const available = useAvailableCount(opened, fromYardId, wagonTypeId);
+  const { wagons: availableWagons, count: available } = useAvailableWagons(
+    opened,
+    fromYardId,
+    wagonTypeId,
+  );
+
+  // The picks belong to one yard+type pair; changing either invalidates them.
+  useEffect(() => {
+    setPicked(new Set());
+  }, [fromYardId, wagonTypeId]);
+
+  // Naming wagons IS the ask, so the count follows the picks.
+  const handlePick = (next: Set<string>) => {
+    setPicked(next);
+    if (next.size > 0) setQuantity(next.size);
+  };
 
   // A prefilled outstanding count (or a count typed before the yard was picked)
   // can exceed what the chosen source yard actually has — pull it back down so
@@ -118,6 +140,16 @@ export function TransferRequestFormModal({
     setQuantity((q) => (Number(q) > available ? available : q));
   }, [available]);
 
+  // Asking for fewer than were picked would send a selection the API rejects
+  // (picks may not exceed quantity) — drop the extras, keeping pick order.
+  const handleQuantityChange = (value: number | string) => {
+    setQuantity(value);
+    const n = Number(value);
+    if (Number.isFinite(n) && picked.size > n) {
+      setPicked(new Set([...picked].slice(0, Math.max(0, n))));
+    }
+  };
+
   const sameYard = Boolean(fromYardId && fromYardId === toYardId);
   const overAvailable = available != null && Number(quantity) > available;
   const valid =
@@ -136,6 +168,7 @@ export function TransferRequestFormModal({
         wagonTypeId: wagonTypeId!,
         quantity: Number(quantity),
         reason: reason.trim(),
+        ...(picked.size > 0 ? { preferredWagonIds: [...picked] } : {}),
       });
       toast.success("Transfer request filed");
       onClose();
@@ -203,7 +236,7 @@ export function TransferRequestFormModal({
           clampBehavior={available == null ? "none" : "strict"}
           allowNegative={false}
           value={quantity}
-          onChange={setQuantity}
+          onChange={handleQuantityChange}
           disabled={available === 0}
           error={
             available === 0
@@ -214,6 +247,34 @@ export function TransferRequestFormModal({
           }
           required
         />
+
+        {/* Optional: name the exact wagons. Leaving this empty files a plain
+            count request and OCC picks whatever is free. */}
+        {availableWagons.length > 0 ? (
+          <div>
+            <Group justify="space-between" mb={4} wrap="wrap" gap={4}>
+              <Text size="sm" fw={500}>
+                Which wagons{" "}
+                <Text span size="xs" c="dimmed" fw={400}>
+                  (optional)
+                </Text>
+              </Text>
+              <Text size="xs" c="dimmed">
+                {picked.size > 0
+                  ? `${picked.size} named — OCC will prioritise these`
+                  : "Leave empty and OCC picks any available"}
+              </Text>
+            </Group>
+            <WagonPicker
+              wagons={availableWagons}
+              selected={picked}
+              onChange={handlePick}
+              max={available ?? undefined}
+              maxHeight={200}
+            />
+          </div>
+        ) : null}
+
         <Textarea
           label="Reason"
           placeholder="Why the wagons are needed"
diff --git a/apps/edr-freight-web/backoffice/src/pages/wagons/WagonTransfersPage.tsx b/apps/edr-freight-web/backoffice/src/pages/wagons/WagonTransfersPage.tsx
index 1a08b5c54..323323da3 100644
--- a/apps/edr-freight-web/backoffice/src/pages/wagons/WagonTransfersPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/wagons/WagonTransfersPage.tsx
@@ -52,6 +52,7 @@ import {
   TransferRequestFormModal,
 } from "./TransferRequestModals";
 import {
+  PreferredWagonChips,
   TransferProgress,
   TransferStatusBadge,
   fmtDateTime,
@@ -195,6 +196,11 @@ export default function WagonTransfersPage() {
         <Text size="sm">{wagonTypeLabel(row.original.wagonType)}</Text>
       ),
     },
+    {
+      id: "wagons",
+      header: () => <span>Wagons requested</span>,
+      cell: ({ row }) => <PreferredWagonChips request={row.original} />,
+    },
     {
       id: "progress",
       header: () => <span>Delivered</span>,
@@ -564,6 +570,17 @@ export default function WagonTransfersPage() {
               {wagonTypeLabel(viewingReason.wagonType)} ·{" "}
               {viewingReason.quantity} wagon(s)
             </Text>
+            {viewingReason.preferredWagons?.length ? (
+              <div>
+                <Text size="xs" c="dimmed" mb={4}>
+                  Wagons requested
+                </Text>
+                <PreferredWagonChips
+                  request={viewingReason}
+                  limit={viewingReason.preferredWagons.length}
+                />
+              </div>
+            ) : null}
             <Box
               className="text-sm [&_p]:my-2 [&_ol]:list-decimal [&_ul]:list-disc [&_ol]:pl-5 [&_ul]:pl-5"
               dangerouslySetInnerHTML={{
diff --git a/apps/edr-freight-web/backoffice/src/pages/wagons/wagon-transfer-ui.tsx b/apps/edr-freight-web/backoffice/src/pages/wagons/wagon-transfer-ui.tsx
index ea73a95d2..130f37233 100644
--- a/apps/edr-freight-web/backoffice/src/pages/wagons/wagon-transfer-ui.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/wagons/wagon-transfer-ui.tsx
@@ -3,6 +3,65 @@ import { Badge, Box, Group, Progress, Text, Tooltip } from "@mantine/core";
 
 import type { WagonTransferRequest } from "@/services/wagon.service";
 
+/** How many wagon chips fit a table cell before the rest are rolled up. */
+const CHIP_LIMIT = 4;
+
+/**
+ * The wagons the requester actually named, when they picked any. Rendered as
+ * chips so a glance down the column separates "send me these 3" from a plain
+ * count request — the two are fulfilled differently.
+ */
+export function PreferredWagonChips({
+  request,
+  limit = CHIP_LIMIT,
+}: {
+  request: WagonTransferRequest;
+  limit?: number;
+}) {
+  const wagons = request.preferredWagons ?? [];
+  if (wagons.length === 0) {
+    return (
+      <Tooltip label="No specific wagons named — OCC picks any available" withArrow>
+        <Text size="xs" c="dimmed">
+          Any {request.quantity}
+        </Text>
+      </Tooltip>
+    );
+  }
+
+  const shown = wagons.slice(0, limit);
+  const rest = wagons.length - shown.length;
+
+  return (
+    <Tooltip
+      withArrow
+      multiline
+      maw={280}
+      label={`Requested: ${wagons.map((w) => w.wagonNumber).join(", ")}`}
+    >
+      <Group gap={4} wrap="wrap" maw={220}>
+        {shown.map((w) => (
+          <Badge
+            key={w.id}
+            size="sm"
+            variant="light"
+            color="edr-green"
+            radius="sm"
+            style={{ fontVariantNumeric: "tabular-nums" }}
+          >
+            {w.wagonNumber}
+          </Badge>
+        ))}
+        {rest > 0 ? (
+          <Badge size="sm" variant="outline" color="gray" radius="sm">
+            +{rest}
+          </Badge>
+        ) : null}
+      </Group>
+    </Tooltip>
+  );
+}
+
 /** Reason/note fields come from a rich-text editor and store HTML — this
  * gives a plain-text preview for list/table contexts (full formatting is
  * shown via `sanitizeHtml` + `dangerouslySetInnerHTML` where there's room). */
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index c7679056e..6c9c69788 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -67,6 +67,7 @@ import type {
   PinWagonsPayload,
   RecordCheckpointPayload,
   StaffBookingWindow,
+  ScheduleMergePreview,
   TrainScheduleDetail,
   TrainScheduleFilters,
   TrainScheduleListFilters,
@@ -596,6 +597,36 @@ export const api = {
       () => TRAIN_SCHEDULING_INVALIDATIONS,
     ),
 
+    previewScheduleMerge: endpoint<
+      { id: string; targetTrainId: string },
+      ScheduleMergePreview
+    >(
+      "train-scheduling",
+      "merge-preview",
+      ({ id, targetTrainId }) =>
+        trainSchedulingService.previewScheduleMerge(id, targetTrainId),
+      ({ id, targetTrainId }) => [
+        "train-scheduling",
+        "merge-preview",
+        id,
+        targetTrainId,
+      ],
+    ),
+
+    mergeScheduleTrain: endpoint<
+      { id: string; targetTrainId: string; reason?: string },
+      TrainScheduleDetail
+    >(
+      "train-scheduling",
+      "merge-train",
+      ({ id, ...payload }) =>
+        trainSchedulingService.mergeScheduleTrain(id, payload),
+      undefined,
+      // Wagons and bookings move between trains and schedules, so the wagon and
+      // train caches are stale too — not just the scheduling ones.
+      () => [...TRAIN_SCHEDULING_INVALIDATIONS, ["wagons"], ["trains"]],
+    ),
+
     markBookingPaid: endpoint<string, void>(
       "train-scheduling",
       "mark-booking-paid",
@@ -2040,11 +2071,14 @@ export const api = {
       () => TRAIN_BUILDER_INVALIDATIONS,
     ),
 
-    sendWagonToMaintenance: endpoint<{ id: string; wagonId: string }, TrainComposition>(
+    sendWagonToMaintenance: endpoint<
+      { id: string; wagonId: string; note?: string },
+      TrainComposition
+    >(
       "train-builder",
       "sendWagonToMaintenance",
-      ({ id, wagonId }) =>
-        trainBuilderService.sendWagonToMaintenance(id, wagonId).then((r) => r.data),
+      ({ id, wagonId, note }) =>
+        trainBuilderService.sendWagonToMaintenance(id, wagonId, note).then((r) => r.data),
       undefined,
       () => TRAIN_BUILDER_INVALIDATIONS,
     ),
diff --git a/apps/edr-freight-web/backoffice/src/services/auditLogs.service.ts b/apps/edr-freight-web/backoffice/src/services/auditLogs.service.ts
new file mode 100644
index 000000000..d52a60382
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/services/auditLogs.service.ts
@@ -0,0 +1,97 @@
+import type { PaginatedResponse } from "@edr/types";
+
+import { api as client } from "../auth/http";
+import { unwrap } from "@/utils/endpoint";
+import { URL_CONSTANTS } from "@/constants/URLS";
+import type { ApiResponse } from "@/types/apiResponse";
+
+const BASE = URL_CONSTANTS.AUDIT_LOGS.BASE;
+
+/** Methods the audit trail records. Reads are never audited. */
+export const AUDIT_METHODS = ["POST", "PUT", "PATCH", "DELETE"] as const;
+export type AuditMethod = (typeof AUDIT_METHODS)[number];
+
+/**
+ * One recorded backoffice action.
+ *
+ * Mirrors `AuditLog` in the freight API. `userName` / `userRole` are snapshots
+ * taken when the action happened, not live lookups — an old row keeps the name
+ * and role the actor had at the time.
+ */
+export interface AuditLog {
+  id: string;
+  /** Readable action, e.g. "Approve contract". */
+  title: string;
+  method: AuditMethod;
+  /** URL as called, query string included (secrets already redacted server-side). */
+  url: string;
+  /** Route template, e.g. `/api/contracts/:id/cancel`. */
+  routePath: string | null;
+  /** Entity the action touched, e.g. "Contract". */
+  type: string;
+  isSuccess: boolean;
+  statusCode: number | null;
+  errorMessage: string | null;
+  userId: string | null;
+  userName: string | null;
+  userRole: string | null;
+  resourceId: string | null;
+  /** Sanitized request body; files appear as `__file` descriptors. */
+  request: Record<string, unknown> | null;
+  ipAddress: string | null;
+  userAgent: string | null;
+  requestId: string | null;
+  durationMs: number | null;
+  createdAt: string;
+}
+
+export interface AuditLogQuery {
+  page?: number;
+  pageSize?: number;
+  type?: string;
+  userId?: string;
+  method?: AuditMethod;
+  resourceId?: string;
+  /** Omit for "any outcome". */
+  isSuccess?: boolean;
+  /** Inclusive ISO 8601 bounds. */
+  from?: string;
+  to?: string;
+}
+
+/**
+ * Drop empty filters so the request carries only what the user actually set —
+ * an empty string would otherwise be sent and fail the API's validation.
+ */
+function toParams(query: AuditLogQuery): Record<string, string | number> {
+  const params: Record<string, string | number> = {};
+
+  if (query.page) params.page = query.page;
+  if (query.pageSize) params.pageSize = query.pageSize;
+  if (query.type) params.type = query.type;
+  if (query.userId) params.userId = query.userId;
+  if (query.method) params.method = query.method;
+  if (query.resourceId) params.resourceId = query.resourceId;
+  if (query.isSuccess !== undefined) params.isSuccess = String(query.isSuccess);
+  if (query.from) params.from = query.from;
+  if (query.to) params.to = query.to;
+
+  return params;
+}
+
+export const auditLogsService = {
+  /** Paginated audit history, newest first. */
+  list: async (query: AuditLogQuery = {}): Promise<PaginatedResponse<AuditLog>> => {
+    const response = await client.get<ApiResponse<PaginatedResponse<AuditLog>>>(
+      `${BASE}/logs`,
+      { params: toParams(query) },
+    );
+    return unwrap(response.data);
+  },
+
+  /** Distinct entity types present, for the filter dropdown. */
+  types: async (): Promise<string[]> => {
+    const response = await client.get<ApiResponse<string[]>>(`${BASE}/types`);
+    return unwrap(response.data);
+  },
+};
diff --git a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
index c1ce4e67d..5c9c8d900 100644
--- a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
@@ -420,11 +420,11 @@ export const bookingsService = {
 
   uploadDeliveryOrder: async (
     id: string,
-    file: File,
+    files: File[],
     dates: { vesselArrivalDate: string; doCollectedDate: string },
   ): Promise<BookingDetail> => {
     const form = new FormData();
-    form.append("file", file);
+    files.forEach((file) => form.append("files", file));
     form.append("vesselArrivalDate", dates.vesselArrivalDate);
     form.append("doCollectedDate", dates.doCollectedDate);
     const response = await client.post(B.CLEARANCE_DELIVERY_ORDER(id), form, {
@@ -435,11 +435,11 @@ export const bookingsService = {
 
   uploadReleaseOrder: async (
     id: string,
-    file: File,
+    files: File[],
     vesselDepartureDate: string,
   ): Promise<{ hold?: boolean; holdReason?: string }> => {
     const form = new FormData();
-    form.append("file", file);
+    files.forEach((file) => form.append("files", file));
     form.append("vesselDepartureDate", vesselDepartureDate);
     const response = await client.post(B.CLEARANCE_RELEASE_ORDER(id), form, {
       headers: { "Content-Type": "multipart/form-data" },
diff --git a/apps/edr-freight-web/backoffice/src/services/contracts.service.ts b/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
index 37971cb96..042575f2c 100644
--- a/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
@@ -468,11 +468,11 @@ export const contractsService = {
 
   uploadDeliveryOrder: async (
     id: string,
-    file: File,
+    files: File[],
     dates: { vesselArrivalDate: string; doCollectedDate: string },
   ): Promise<Freight.IContract> => {
     const form = new FormData();
-    form.append("file", file);
+    files.forEach((file) => form.append("files", file));
     form.append("vesselArrivalDate", dates.vesselArrivalDate);
     form.append("doCollectedDate", dates.doCollectedDate);
     const response = await client.post(C.CLEARANCE_DELIVERY_ORDER(id), form, {
@@ -483,11 +483,11 @@ export const contractsService = {
 
   uploadReleaseOrder: async (
     id: string,
-    file: File,
+    files: File[],
     vesselDepartureDate: string,
   ): Promise<{ contract: Freight.IContract; hold: boolean; holdReason?: string }> => {
     const form = new FormData();
-    form.append("file", file);
+    files.forEach((file) => form.append("files", file));
     form.append("vesselDepartureDate", vesselDepartureDate);
     const response = await client.post(C.CLEARANCE_RELEASE_ORDER(id), form, {
       headers: { "Content-Type": "multipart/form-data" },
diff --git a/apps/edr-freight-web/backoffice/src/services/trainBuilder.service.ts b/apps/edr-freight-web/backoffice/src/services/trainBuilder.service.ts
index 3d2891415..2892cb0ec 100644
--- a/apps/edr-freight-web/backoffice/src/services/trainBuilder.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/trainBuilder.service.ts
@@ -309,8 +309,11 @@ export const trainBuilderService = {
   removeWagon: (id: string, wagonId: string) =>
     apiClient.delete<TrainComposition>(`${BASE}/${id}/wagons/${wagonId}`),
   /** Detach a wagon and move it to MAINTENANCE status. */
-  sendWagonToMaintenance: (id: string, wagonId: string) =>
-    apiClient.post<TrainComposition>(`${BASE}/${id}/wagons/${wagonId}/maintenance`),
+  /** `note` is the maintenance reason — recorded with the train it came off. */
+  sendWagonToMaintenance: (id: string, wagonId: string, note?: string) =>
+    apiClient.post<TrainComposition>(`${BASE}/${id}/wagons/${wagonId}/maintenance`, {
+      note,
+    }),
   reorderWagons: (id: string, wagonIds: string[]) =>
     apiClient.post<TrainComposition>(`${BASE}/${id}/reorder-wagons`, { wagonIds }),
   /** Park the train indefinitely — only allowed with no active schedule. */
diff --git a/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts b/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts
index 35dc23684..58e251196 100644
--- a/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts
@@ -29,6 +29,7 @@ import type {
   PinWagonsPayload,
   RecordCheckpointPayload,
   StaffBookingWindow,
+  ScheduleMergePreview,
   TrainScheduleDetail,
   UpdateScheduleWindowRulePayload,
   TrainScheduleFilters,
@@ -294,6 +295,29 @@ export const trainSchedulingService = {
     return unwrap(response.data);
   },
 
+  /** What a merge would do — drives the confirmation modal. Read-only. */
+  previewScheduleMerge: async (
+    scheduleId: string,
+    targetTrainId: string,
+  ): Promise<ScheduleMergePreview> => {
+    const response = await client.get<ScheduleMergePreview>(
+      URL_CONSTANTS.TRAIN_SCHEDULING.MERGE_PREVIEW(scheduleId, targetTrainId),
+    );
+    return unwrap(response.data);
+  },
+
+  /** Merge another train into this schedule. This schedule always survives. */
+  mergeScheduleTrain: async (
+    scheduleId: string,
+    payload: { targetTrainId: string; reason?: string },
+  ): Promise<TrainScheduleDetail> => {
+    const response = await client.post<TrainScheduleDetail>(
+      URL_CONSTANTS.TRAIN_SCHEDULING.MERGE_TRAIN(scheduleId),
+      payload,
+    );
+    return unwrap(response.data);
+  },
+
   markBookingPaid: async (bookingId: string): Promise<void> => {
     await client.post(
       URL_CONSTANTS.TRAIN_SCHEDULING.MARK_BOOKING_PAID(bookingId),
diff --git a/apps/edr-freight-web/backoffice/src/services/wagon.service.ts b/apps/edr-freight-web/backoffice/src/services/wagon.service.ts
index 858d26412..a2fc0c739 100644
--- a/apps/edr-freight-web/backoffice/src/services/wagon.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/wagon.service.ts
@@ -168,6 +168,10 @@ export interface WagonTransferRequest {
   closedShortByUserId?: string | null;
   /** Why the wagons are needed — required for new requests, shown on the queue. */
   reason?: string | null;
+  /** The wagons the requester hand-picked, if any. A preference, not a reservation. */
+  preferredWagonIds?: string[] | null;
+  /** Those same picks resolved to wagon numbers by the API, for display. */
+  preferredWagons?: Array<{ id: string; wagonNumber: string }>;
   note: string | null;
   fromYard?: { id: string; label?: string; code?: string } | null;
   toYard?: { id: string; label?: string; code?: string } | null;
@@ -182,6 +186,8 @@ export interface CreateTransferRequestPayload {
   quantity: number;
   /** Mandatory: why the wagons are needed. */
   reason: string;
+  /** Specific wagons the requester wants — at most `quantity` of them. */
+  preferredWagonIds?: string[];
   note?: string;
 }
 
diff --git a/apps/edr-freight-web/backoffice/src/types/booking.ts b/apps/edr-freight-web/backoffice/src/types/booking.ts
index 7ae93a1b7..c863dbde4 100644
--- a/apps/edr-freight-web/backoffice/src/types/booking.ts
+++ b/apps/edr-freight-web/backoffice/src/types/booking.ts
@@ -143,6 +143,12 @@ export interface BookingTrainScheduleSummary {
   actualArrivalAt: string | null;
   windowPhase: string | null;
   paymentPhaseEndsAt: string | null;
+  /**
+   * True when this is the train the customer requested at day-commit rather
+   * than a confirmed allocation — what staff see while reviewing an operation
+   * request, before accepting puts the booking into the batch pool.
+   */
+  isRequested?: boolean;
 }
 
 export interface BookingDetail {
diff --git a/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts b/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
index 94e393e1b..dd6508b73 100644
--- a/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
+++ b/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
@@ -217,7 +217,28 @@ export interface TrainScheduleListItem {
     name?: string | null;
     currentYardId?: string | null;
   }>;
+  /** Coupled consist size. NOT the used count — see `wagonsUsed`. */
   wagonCount: number;
+  /**
+   * Wagon slots actually carrying a booking allocation — the same figure the
+   * detail page's wagon plan shows. Optional until every API deploy carries it.
+   */
+  wagonsUsed?: number;
+  /** Coupled consist size; the denominator of `wagonsUsed`. */
+  wagonsTotal?: number;
+  /** Wagons claimed by bookings (including unpaid) — not bookable. */
+  wagonsReserved?: number;
+  /** Wagons still bookable: consist minus what bookings have claimed. */
+  wagonsRemaining?: number;
+  /**
+   * Planned wagon ceiling for the departure, set when the schedule is created.
+   * Independent of the coupled consist — a schedule can plan 37 wagons before a
+   * single one is coupled, which is why this is the bookable figure until the
+   * train set is built.
+   */
+  maxWagons?: number;
+  /** Plan ceiling minus the coupled consist — room left to couple. */
+  remainingWagons?: number;
   totalWeightTons: number;
   totalLengthMeters: number;
   bookingsCount: number;
@@ -571,6 +592,35 @@ export interface UpdateScheduleWindowRulePayload {
   exportBookingLeadHours?: number;
 }
 
+/** One schedule touched by a merge, as summarised for the confirmation modal. */
+export interface MergeAffectedSchedule {
+  id: string;
+  reference: string | null;
+  scheduledDepartureDate: string;
+  status: string;
+}
+
+/**
+ * What merging a train into a schedule would do, computed server-side so the
+ * modal shows exactly what the commit will perform.
+ */
+export interface ScheduleMergePreview {
+  canMerge: boolean;
+  /** Why the merge is refused. Empty when `canMerge` is true. */
+  blockers: string[];
+  targetTrain: { id: string; code: string; trainNumber: string | null };
+  wagons: { current: number; incoming: number; merged: number };
+  /** The same-day schedule whose bookings move here; it is then removed. */
+  absorbedSchedule:
+    | (MergeAffectedSchedule & { bookingsMoving: number })
+    | null;
+  /** Other draft/scheduled schedules on the target — they gain wagons only. */
+  affectedSchedules: MergeAffectedSchedule[];
+  /** On the target train but left alone (dispatched, cancelled, …). */
+  untouchedSchedules: MergeAffectedSchedule[];
+  sourceTrainWillDeactivate: boolean;
+}
+
 export interface TrainScheduleDetail {
   id: string;
   reference?: string | null;
@@ -578,6 +628,8 @@ export interface TrainScheduleDetail {
   deferredBookings?: DeferredBookingRow[];
   freightType?: FreightType | null;
   trainNumber?: string | null;
+  /** Voyage (sailing) number for this departure — editable until dispatch. */
+  voyageNumber?: string | null;
   /** Wagon cap for this departure (built-train consist size or configured limit). */
   maxWagons?: number | null;
   /** Built train (Train Builder) behind this departure, when scheduled by train. */
@@ -621,6 +673,8 @@ export interface TrainScheduleDetail {
   trainSet?: {
     id: string;
     status: string;
+    /** The built train this set runs on — null when it has none yet. */
+    trainId?: string | null;
     wagonCount: number;
     totalWeightTons: number;
     totalLengthMeters: number;
diff --git a/packages/types/src/freight/clearance-files.catalog.ts b/packages/types/src/freight/clearance-files.catalog.ts
index cb4f976eb..8fa50cba4 100644
--- a/packages/types/src/freight/clearance-files.catalog.ts
+++ b/packages/types/src/freight/clearance-files.catalog.ts
@@ -156,6 +156,48 @@ export function transitPermitFileLabel(code: string, index?: number): string {
   return code;
 }
 
+/** Legacy single Delivery Order code (pre multi-file uploads). */
+export const LEGACY_DELIVERY_ORDER_CODE = "delivery_order";
+
+/** Multi-file Delivery Order uploads use `delivery_order_0`, `delivery_order_1`, … */
+export const DELIVERY_ORDER_FILE_PREFIX = "delivery_order_";
+
+export function isDeliveryOrderFileCode(code: string | null | undefined): boolean {
+  if (!code) return false;
+  const lower = code.toLowerCase();
+  return lower === LEGACY_DELIVERY_ORDER_CODE || lower.startsWith(DELIVERY_ORDER_FILE_PREFIX);
+}
+
+export function deliveryOrderFileLabel(code: string, index?: number): string {
+  const lower = code.toLowerCase();
+  if (lower === LEGACY_DELIVERY_ORDER_CODE) return "Delivery Order";
+  if (lower.startsWith(DELIVERY_ORDER_FILE_PREFIX)) {
+    return index != null ? `Delivery Order ${index + 1}` : "Delivery Order";
+  }
+  return code;
+}
+
+/** Legacy single Release Order code (pre multi-file uploads). */
+export const LEGACY_RELEASE_ORDER_CODE = "release_order";
+
+/** Multi-file Release Order uploads use `release_order_0`, `release_order_1`, … */
+export const RELEASE_ORDER_FILE_PREFIX = "release_order_";
+
+export function isReleaseOrderFileCode(code: string | null | undefined): boolean {
+  if (!code) return false;
+  const lower = code.toLowerCase();
+  return lower === LEGACY_RELEASE_ORDER_CODE || lower.startsWith(RELEASE_ORDER_FILE_PREFIX);
+}
+
+export function releaseOrderFileLabel(code: string, index?: number): string {
+  const lower = code.toLowerCase();
+  if (lower === LEGACY_RELEASE_ORDER_CODE) return "Release Order";
+  if (lower.startsWith(RELEASE_ORDER_FILE_PREFIX)) {
+    return index != null ? `Release Order ${index + 1}` : "Release Order";
+  }
+  return code;
+}
+
 /** Legacy single T1 code (GL post-booking uploader). */
 export const LEGACY_T1_TRANSPORT_CODE = "t1_transport_document";
 

From d4767e0d0656ab09f218403ce66ed0c46555b4cd Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 12 Aug 2026 07:11:27 +0000
Subject: [PATCH 029/174] fix: an issue

---
 .../modules/companies/companies.service.ts    | 78 ++++++++++---------
 .../onboarding-requirements-response.dto.ts   | 11 +--
 .../file-upload-settings.service.ts           |  5 --
 .../poa-delegation.constants.ts               |  9 ++-
 .../src/seed/file-upload-settings.seeder.ts   | 45 ++++++++---
 .../onboarding/OnboardingWizardDialog.tsx     | 26 +++----
 .../src/pages/accounts/CompanyProfileForm.tsx | 36 ++-------
 .../new-booking-form/step-documents.tsx       | 21 +++--
 .../resubmit/useBookingDocumentSetting.ts     | 23 +++---
 .../new-contract-form/ContractDocsEditor.tsx  | 21 +++--
 .../new-contract-form/step-documents.tsx      | 20 +++--
 .../src/pages/settings/NationalitySelect.tsx  | 21 +++--
 .../src/pages/settings/TabDocuments.tsx       | 13 ++--
 .../portal/src/services/companies.service.ts  |  8 +-
 .../src/utils/documentSettingCode.test.ts     | 28 +++++++
 .../portal/src/utils/documentSettingCode.ts   | 18 +++++
 16 files changed, 206 insertions(+), 177 deletions(-)
 create mode 100644 apps/edr-freight-web/portal/src/utils/documentSettingCode.test.ts
 create mode 100644 apps/edr-freight-web/portal/src/utils/documentSettingCode.ts

diff --git a/apps/edr-freight-api/src/modules/companies/companies.service.ts b/apps/edr-freight-api/src/modules/companies/companies.service.ts
index cf2f2e84d..98b30f006 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.service.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.service.ts
@@ -256,11 +256,15 @@ export class CompaniesService {
       },
     ];
 
-  /** The nationality-based document setting code for a company. */
-  private documentSettingCodeFor(
-    nationality: CompanyNationality | null | undefined,
-  ): string {
-    return nationality === CompanyNationality.Foreign
+  /**
+   * The document setting code for a company: one of three mutually exclusive
+   * sets. A co-operative union or farm resolves to its own set regardless of
+   * nationality — it holds no business licence, so it owes a different list of
+   * papers rather than the nationality list plus extras.
+   */
+  private documentSettingCodeFor(company: Company): string {
+    if (isCooperative(company)) return COOPERATIVE_ONBOARDING_CODE;
+    return company.nationality === CompanyNationality.Foreign
       ? "company_onboarding_documents_foreign"
       : "company_onboarding_documents_ethiopian";
   }
@@ -387,13 +391,16 @@ export class CompaniesService {
       const current = needsCompany
         ? await this.companiesRepo.findById(companyId)
         : null;
-      this.assertRolesAllowedForCooperative(
-        cooperative ?? isCooperative(current),
-        roles,
-      );
+      const isCoop = cooperative ?? isCooperative(current);
+      this.assertRolesAllowedForCooperative(isCoop, roles);
+      this.assertNationalityAllowedForCooperative(isCoop, nationality);
       await this.syncCompanyProfiles(companyId, companyType, roles);
       const updates: Partial<Company> = {};
       if (nationality) updates.nationality = nationality;
+      // Ticking the box on a draft that was saved as foreign has to correct the
+      // stored nationality too, or the company keeps resolving to the foreign
+      // document set.
+      if (isCoop) updates.nationality = CompanyNationality.Ethiopian;
       if (cooperative !== undefined) {
         updates.attributes = {
           ...(current?.attributes ?? {}),
@@ -407,6 +414,7 @@ export class CompaniesService {
     }
 
     this.assertRolesAllowedForCooperative(cooperative === true, roles);
+    this.assertNationalityAllowedForCooperative(cooperative === true, nationality);
     const allowedTypes = this.getProfileTypeForCompanyType(companyType);
     const chosenTypes = roles.filter((t) => allowedTypes.includes(t));
 
@@ -458,6 +466,24 @@ export class CompaniesService {
     }
   }
 
+  /**
+   * A co-operative union or farm is registered in Ethiopia by the co-operative
+   * promotion agency, so it is always an Ethiopian company — "foreign" is not a
+   * combination that exists, and allowing it would resolve the company to a
+   * document set built around an investment licence it cannot hold.
+   */
+  private assertNationalityAllowedForCooperative(
+    cooperative: boolean,
+    nationality: CompanyNationality | undefined,
+  ): void {
+    if (!cooperative) return;
+    if (nationality === CompanyNationality.Foreign) {
+      throw new BadRequestException(
+        "A co-operative union or farm is registered in Ethiopia — it cannot onboard as a foreign company.",
+      );
+    }
+  }
+
   /**
    * Reconcile the company's operational profiles with the roles the user has
    * selected: create the missing ones, drop the ones they deselected.
@@ -1252,7 +1278,7 @@ export class CompaniesService {
     uploaded: FileRecord[],
   ): Promise<CompanyRevisionChange[]> {
     const setting = await this.fileUploadSettingsService
-      .getByCode(this.documentSettingCodeFor(company.nationality))
+      .getByCode(this.documentSettingCodeFor(company))
       .catch(() => null);
     const fields = setting?.fields ?? [];
     const singleFileCodes = new Set(
@@ -2036,35 +2062,20 @@ export class CompaniesService {
       .filter((f) => !f.get(company))
       .map((f) => ({ key: f.key, label: f.label }));
 
-    // 2. Nationality-based company documents + which are already uploaded. A
-    // co-operative adds its own set on top: it provides everything its
-    // nationality demands, plus the papers standing in for the business licence
-    // it does not hold.
+    // 2. Company documents + which are already uploaded. One set applies: the
+    // company's nationality set, or the co-operative set in its place — a union
+    // or farm holds no business licence, so it owes its own list rather than the
+    // nationality list plus extras.
     const cooperative = isCooperative(company);
-    const documentSettingCode = this.documentSettingCodeFor(
-      company.nationality,
-    );
-    const [setting, coopSetting, uploadedFiles] = await Promise.all([
+    const documentSettingCode = this.documentSettingCodeFor(company);
+    const [setting, uploadedFiles] = await Promise.all([
       this.fileUploadSettingsService
         .getByCode(documentSettingCode)
         .catch(() => null),
-      cooperative
-        ? this.fileUploadSettingsService
-          .getByCode(COOPERATIVE_ONBOARDING_CODE)
-          .catch(() => null)
-        : Promise.resolve(null),
       this.filesService.findByResource(company.id, "companies"),
     ]);
     const uploadedCodes = new Set(uploadedFiles.map((f) => f.code));
-    // The co-op set is admin-managed and could name a fileKey the nationality
-    // set already carries; the nationality field wins so the same slot is never
-    // rendered (or required) twice.
-    const baseFields = setting?.fields ?? [];
-    const baseKeys = new Set(baseFields.map((f) => f.fileKey));
-    const documents = [
-      ...baseFields,
-      ...(coopSetting?.fields ?? []).filter((f) => !baseKeys.has(f.fileKey)),
-    ]
+    const documents = (setting?.fields ?? [])
       .slice()
       .sort((a, b) => a.displayOrder - b.displayOrder)
       .map((f) => ({
@@ -2203,9 +2214,6 @@ export class CompaniesService {
 
     return new OnboardingRequirementsResponseDto({
       documentSettingCode,
-      cooperativeDocumentSettingCode: cooperative
-        ? COOPERATIVE_ONBOARDING_CODE
-        : null,
       nationality: company.nationality ?? CompanyNationality.Ethiopian,
       cooperative,
       companyInfo: {
diff --git a/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts
index 8d47dbb4e..20bd0ab06 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts
@@ -66,15 +66,11 @@ export interface OnboardingPoaState {
 }
 
 export class OnboardingRequirementsResponseDto {
-  /** Resolved document setting code (by nationality) the docs were drawn from. */
-  documentSettingCode: string;
   /**
-   * The co-operative document set, merged on top of the nationality one — null
-   * for every other company. `documents` below already carries the merged
-   * result; this is only so the portal can fetch the same extra fields when it
-   * renders the pickers from the file-settings endpoint.
+   * Resolved document setting code the docs were drawn from: the company's
+   * nationality set, or the co-operative set in its place.
    */
-  cooperativeDocumentSettingCode: string | null;
+  documentSettingCode: string;
   nationality: string;
   /**
    * The company trades as a co-operative: no business licence, so no eTrade
@@ -118,7 +114,6 @@ export class OnboardingRequirementsResponseDto {
 
   constructor(init: Omit<OnboardingRequirementsResponseDto, never>) {
     this.documentSettingCode = init.documentSettingCode;
-    this.cooperativeDocumentSettingCode = init.cooperativeDocumentSettingCode;
     this.nationality = init.nationality;
     this.cooperative = init.cooperative;
     this.companyInfo = init.companyInfo;
diff --git a/apps/edr-freight-api/src/modules/file-upload-settings/file-upload-settings.service.ts b/apps/edr-freight-api/src/modules/file-upload-settings/file-upload-settings.service.ts
index 21ddc4c91..9651d4f37 100644
--- a/apps/edr-freight-api/src/modules/file-upload-settings/file-upload-settings.service.ts
+++ b/apps/edr-freight-api/src/modules/file-upload-settings/file-upload-settings.service.ts
@@ -17,7 +17,6 @@ import {
 } from "./interfaces/file-upload-settings.repository.interface";
 import {
   COMPANY_ONBOARDING_CODE_PREFIX,
-  COOPERATIVE_ONBOARDING_CODE,
   POA_DELEGATION_FILE_KEY,
   poaDelegationField,
 } from "./poa-delegation.constants";
@@ -57,10 +56,6 @@ export class FileUploadSettingsService {
    */
   private withPoaDelegationField(setting: FileUploadSetting): FileUploadSetting {
     if (!setting.code.startsWith(COMPANY_ONBOARDING_CODE_PREFIX)) return setting;
-    // The co-operative set is merged ON TOP of a nationality set that already
-    // carries the paper; injecting it here too would hand the portal the same
-    // slot twice.
-    if (setting.code === COOPERATIVE_ONBOARDING_CODE) return setting;
     const fields = setting.fields ?? [];
     if (fields.some((f) => f.fileKey === POA_DELEGATION_FILE_KEY)) return setting;
 
diff --git a/apps/edr-freight-api/src/modules/file-upload-settings/poa-delegation.constants.ts b/apps/edr-freight-api/src/modules/file-upload-settings/poa-delegation.constants.ts
index e8d593ded..e23a87818 100644
--- a/apps/edr-freight-api/src/modules/file-upload-settings/poa-delegation.constants.ts
+++ b/apps/edr-freight-api/src/modules/file-upload-settings/poa-delegation.constants.ts
@@ -27,10 +27,11 @@ export const POA_DELEGATION_LABEL = "DARS Delegation Paper";
 export const COMPANY_ONBOARDING_CODE_PREFIX = "company_onboarding_documents_";
 
 /**
- * The co-operative onboarding set. Unlike the nationality sets it is ADDITIVE —
- * merged on top of the company's `_ethiopian`/`_foreign` set rather than
- * replacing it — which is why the delegation paper is not injected into it: the
- * set it is merged onto already carries one.
+ * The co-operative onboarding set — the third alternative to `_ethiopian` and
+ * `_foreign`, not an addition to them: a union or farm resolves to this set
+ * INSTEAD of its nationality's, because it holds no business licence and so
+ * owes a different list of papers. The delegation paper is injected into it
+ * like any other company onboarding set.
  */
 export const COOPERATIVE_ONBOARDING_CODE = `${COMPANY_ONBOARDING_CODE_PREFIX}cooperative`;
 
diff --git a/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts b/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
index abc4e613c..4f314453a 100644
--- a/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
+++ b/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
@@ -155,16 +155,27 @@ const FOREIGN_ONBOARDING_FIELDS: OnboardingField[] = [
 // ];
 
 /**
- * Extra documents a co-operative union or farm provides, merged on top of its
- * nationality set. It has a TIN but no business licence, so the papers that
- * evidence the co-operative itself stand in for the trade licence every other
- * company uploads.
+ * Documents required from a co-operative union or farm — the third alternative
+ * to the two nationality sets, not an addition to them. A co-op is always
+ * registered in Ethiopia and has a TIN but no business licence, so its
+ * registration certificate stands in for the commercial registration every
+ * other Ethiopian company uploads.
  *
- * Only the registration certificate is seeded, and the set is admin-managed
- * like every other onboarding set — what these members must actually produce
- * is a backoffice decision, edited in the file-settings editor.
+ * Admin-managed like every other onboarding set: what these members must
+ * actually produce is a backoffice decision, edited in the file-settings editor.
  */
 const COOPERATIVE_ONBOARDING_FIELDS: OnboardingField[] = [
+  {
+    fileKey: "tin_certificate",
+    fileLabel: "TIN Certificate",
+    helpText: "Verified against the TIN registry during registration.",
+    isRequired: true,
+    isMultiple: false,
+    maxFiles: 1,
+    allowedExtensions: DOC_EXTENSIONS,
+    maxSizeMb: 50,
+    displayOrder: 1,
+  },
   {
     fileKey: "cooperative_registration_certificate",
     fileLabel: "Co-operative Union / Farm Registration Certificate",
@@ -175,8 +186,20 @@ const COOPERATIVE_ONBOARDING_FIELDS: OnboardingField[] = [
     maxFiles: 1,
     allowedExtensions: DOC_EXTENSIONS,
     maxSizeMb: 50,
-    displayOrder: 1,
+    displayOrder: 2,
   },
+  {
+    fileKey: "national_id",
+    fileLabel: "National ID",
+    helpText: "Verified against the National ID API during registration.",
+    isRequired: true,
+    isMultiple: false,
+    maxFiles: 1,
+    allowedExtensions: DOC_EXTENSIONS,
+    maxSizeMb: 50,
+    displayOrder: 3,
+  },
+  poaDelegationDefault(4),
 ];
 
 interface OnboardingDocumentSetting {
@@ -201,11 +224,11 @@ const COMPANY_ONBOARDING_DOCUMENTS: OnboardingDocumentSetting[] = [
     entity: "customer",
     fields: FOREIGN_ONBOARDING_FIELDS,
   },
-  // Additive, not a nationality of its own: a union or farm still uploads
-  // everything its nationality set demands, and these on top.
+  // The third set: a union or farm resolves here INSTEAD of a nationality set
+  // (it is always Ethiopian, and holds no business licence).
   {
     code: "company_onboarding_documents_cooperative",
-    label: "Co-operative union / farm onboarding documents (additional)",
+    label: "Co-operative union / farm onboarding documents",
     entity: "customer",
     fields: COOPERATIVE_ONBOARDING_FIELDS,
   },
diff --git a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
index 6d75e502f..998f733da 100644
--- a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
+++ b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
@@ -39,6 +39,7 @@ import type {
 } from "@/services/companies.service";
 import { companiesService } from "@/services/companies.service";
 import type { UpdateProfilePayload } from "@/types/profile";
+import { documentSettingCode } from "@/utils/documentSettingCode";
 import { extractApiError } from "@/utils/result";
 
 /** Form steps rendered by CompanyProfileForm. */
@@ -116,13 +117,6 @@ function companyTypeForRoles(_roles: string[]): string {
   return "customer";
 }
 
-/** Document upload setting code per company nationality. */
-function documentSettingCode(nationality: CompanyNationality): string {
-  return nationality === "foreign"
-    ? "company_onboarding_documents_foreign"
-    : "company_onboarding_documents_ethiopian";
-}
-
 /**
  * First-run onboarding wizard with a "draft-first" flow: picking the role(s)
  * immediately creates a draft company + profile on the backend, so every
@@ -168,11 +162,15 @@ export default function OnboardingWizardDialog({
   const [cooperative, setCooperative] = useState<boolean>(
     company?.company?.attributes?.cooperative === true,
   );
-  // Ticking the box drops a role the company can no longer hold, rather than
-  // letting Continue fail on a selection the API refuses.
+  // Ticking the box drops the selections the company can no longer hold, rather
+  // than letting Continue fail on ones the API refuses: a co-op cannot forward
+  // freight, and is registered in Ethiopia so it is never foreign.
   const handleCooperativeChange = useCallback((checked: boolean) => {
     setCooperative(checked);
-    if (checked) setRoles((prev) => prev.filter((r) => r !== "freight_forwarder"));
+    if (checked) {
+      setRoles((prev) => prev.filter((r) => r !== "freight_forwarder"));
+      setNationality((prev) => (prev === "foreign" ? "ethiopian" : prev));
+    }
   }, []);
   const [documentFiles, setDocumentFiles] = useState<
     Record<string, File | File[] | null>
@@ -419,7 +417,7 @@ export default function OnboardingWizardDialog({
   // after the draft — and thus the requirements — exist).
   const resolvedDocumentSettingCode =
     requirementsQuery.data?.documentSettingCode ??
-    documentSettingCode(effectiveNationality);
+    documentSettingCode(effectiveNationality, cooperative);
 
   // Server-confirmed document state, used both to badge already-uploaded fields
   // and to keep a refreshed resume from over-shooting the documents step.
@@ -480,8 +478,6 @@ export default function OnboardingWizardDialog({
     // startOnboarding has persisted it, and the form's whole company step
     // branches on it.
     cooperative: requirementsQuery.data?.cooperative ?? cooperative,
-    extraDocumentSettingCode:
-      requirementsQuery.data?.cooperativeDocumentSettingCode ?? null,
     // A freight forwarder cannot answer the power-of-attorney question — the
     // API forces "yes" — so the step offers no way to change it.
     declarationLocked: requirementsQuery.data?.poa?.locked ?? false,
@@ -551,6 +547,10 @@ export default function OnboardingWizardDialog({
                 value={nationality}
                 onChange={setNationality}
                 embedded
+                // A co-op is registered in Ethiopia by the co-operative
+                // promotion agency — foreign is not on offer rather than
+                // refused later.
+                excludeForeign={cooperative}
               />
               {/* A co-operative union or farm registers on a TIN alone. It
                   changes what the next step asks for (typed registration, no
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 59fcc2223..aa445974f 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
@@ -66,7 +66,6 @@ export default function CompanyProfileForm({
   onIdentityChange,
   cooperative = false,
   declarationLocked = false,
-  extraDocumentSettingCode,
 }: {
   documentSettingCode: string;
   documentFiles?: Record<string, File | File[] | null>;
@@ -115,8 +114,8 @@ export default function CompanyProfileForm({
   /**
    * The company trades as a co-operative: a TIN but no business licence, so the
    * eTrade lookup is replaced by typed registration details, the per-role
-   * licence upload is not owed, and its own document set applies on top of the
-   * nationality one.
+   * licence upload is not owed, and its own document set applies instead of the
+   * nationality one (resolved by the caller into `documentSettingCode`).
    */
   cooperative?: boolean;
   /**
@@ -124,8 +123,6 @@ export default function CompanyProfileForm({
    * answer is forced to "yes" and cannot be changed here.
    */
   declarationLocked?: boolean;
-  /** Additional document set merged in (the co-operative one), if any. */
-  extraDocumentSettingCode?: string | null;
 }) {
   // A Fayda claim carries the phone as the national registry holds it, which is
   // often a local number the form's E.164 validation (and the API's
@@ -206,36 +203,15 @@ export default function CompanyProfileForm({
   const documentFiles = controlledFiles ?? internalFiles;
   const setDocumentFiles = onDocumentFilesChange ?? setInternalFiles;
 
-  const { data: nationalitySetting, isLoading: loadingDocuments } = useQuery(
+  // One set applies: the company's nationality set, or the co-operative one in
+  // its place — the caller resolves which (the API resolves the same way when
+  // it decides what is outstanding).
+  const { data: uploadSetting, isLoading: loadingDocuments } = useQuery(
     api.fileUploadSettings.getByCode.queryOptions({
       input: { code: documentSettingCode },
       refetchOnMount: false,
     }),
   );
-  // A co-operative's own documents come as a second, additive set — it uploads
-  // everything its nationality demands, plus the papers standing in for the
-  // business licence it does not hold. The API merges the same two sets when it
-  // decides what is outstanding.
-  const { data: extraSetting } = useQuery(
-    api.fileUploadSettings.getByCode.queryOptions({
-      input: { code: extraDocumentSettingCode ?? "" },
-      enabled: Boolean(extraDocumentSettingCode),
-      refetchOnMount: false,
-    }),
-  );
-  const uploadSetting = useMemo(() => {
-    if (!nationalitySetting) return nationalitySetting;
-    if (!extraSetting?.fields?.length) return nationalitySetting;
-    // Nationality wins a fileKey collision, so a slot is never rendered twice.
-    const seen = new Set(nationalitySetting.fields.map((f) => f.fileKey));
-    return {
-      ...nationalitySetting,
-      fields: [
-        ...nationalitySetting.fields,
-        ...extraSetting.fields.filter((f) => !seen.has(f.fileKey)),
-      ],
-    };
-  }, [nationalitySetting, extraSetting]);
 
   // Which fields the current step renders an input for and therefore requires.
   // Filled in further down (it depends on values this form owns), and read at
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step-documents.tsx b/apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step-documents.tsx
index de105bf21..d75092655 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step-documents.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step-documents.tsx
@@ -6,6 +6,7 @@ import { type UseFormReturn } from "react-hook-form";
 
 import useAuth from "@/hooks/useAuth";
 import { api } from "@/services/api";
+import { documentSettingCode } from "@/utils/documentSettingCode";
 import {
   operationToProfileType,
   type BookingDocuments,
@@ -20,13 +21,6 @@ type BookingForm = UseFormReturn<
   BookingFormValues
 >;
 
-/** Onboarding document setting code for the company's nationality. */
-function documentSettingCode(nationality: string | null | undefined): string {
-  return nationality === "foreign"
-    ? "company_onboarding_documents_foreign"
-    : "company_onboarding_documents_ethiopian";
-}
-
 function formatSize(bytes?: number): string {
   if (!bytes) return "";
   if (bytes < 1024) return `${bytes} B`;
@@ -48,14 +42,17 @@ function formatSize(bytes?: number): string {
 export function StepDocuments({ form }: { form: BookingForm }) {
   const auth = useAuth();
 
-  const nationality = auth.company?.company?.nationality as
-    | string
-    | null
-    | undefined;
+  const company = auth.company?.company;
+  const nationality = company?.nationality as string | null | undefined;
 
   const docSettingQuery = useQuery(
     api.fileUploadSettings.getByCode.queryOptions({
-      input: { code: documentSettingCode(nationality) },
+      input: {
+        code: documentSettingCode(
+          nationality,
+          company?.attributes?.cooperative === true,
+        ),
+      },
     }),
   );
 
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/resubmit/useBookingDocumentSetting.ts b/apps/edr-freight-web/portal/src/pages/bookings/resubmit/useBookingDocumentSetting.ts
index 65774f97f..31d42f6cd 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/resubmit/useBookingDocumentSetting.ts
+++ b/apps/edr-freight-web/portal/src/pages/bookings/resubmit/useBookingDocumentSetting.ts
@@ -2,15 +2,9 @@ import { useQuery } from "@tanstack/react-query";
 
 import useAuth from "@/hooks/useAuth";
 import { api } from "@/services/api";
+import { documentSettingCode } from "@/utils/documentSettingCode";
 
-/** Onboarding document setting code for the company's nationality. */
-export function documentSettingCode(
-  nationality: string | null | undefined,
-): string {
-  return nationality === "foreign"
-    ? "company_onboarding_documents_foreign"
-    : "company_onboarding_documents_ethiopian";
-}
+export { documentSettingCode };
 
 /**
  * Fetches the FileUploadSetting that describes the documents a booking requires
@@ -22,14 +16,17 @@ export function documentSettingCode(
  */
 export function useBookingDocumentSetting() {
   const auth = useAuth();
-  const nationality = auth.company?.company?.nationality as
-    | string
-    | null
-    | undefined;
+  const company = auth.company?.company;
+  const nationality = company?.nationality as string | null | undefined;
 
   return useQuery(
     api.fileUploadSettings.getByCode.queryOptions({
-      input: { code: documentSettingCode(nationality) },
+      input: {
+        code: documentSettingCode(
+          nationality,
+          company?.attributes?.cooperative === true,
+        ),
+      },
     }),
   );
 }
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/new-contract-form/ContractDocsEditor.tsx b/apps/edr-freight-web/portal/src/pages/contracts/new-contract-form/ContractDocsEditor.tsx
index 4d966e010..9d045c4e7 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/new-contract-form/ContractDocsEditor.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/new-contract-form/ContractDocsEditor.tsx
@@ -7,6 +7,7 @@ import type { Freight } from "@edr/types";
 import { useQuery } from "@tanstack/react-query";
 import useAuth from "@/hooks/useAuth";
 import { api } from "@/services/api";
+import { documentSettingCode } from "@/utils/documentSettingCode";
 import type { CompanyDocument } from "@/services/companies.service";
 import { downloadStoredFile } from "@/services/files.service";
 import { labelForDocCode } from "@/pages/bookings/resubmit/resubmitDocs";
@@ -15,13 +16,6 @@ import { BORDER, GREEN, INK } from "../contract-ui";
 type DocumentsValue = Record<string, File | File[] | null>;
 type ContractFile = NonNullable<Freight.IContract["files"]>[number];
 
-/** Onboarding document setting code for the company's nationality. */
-function documentSettingCode(nationality: string | null | undefined): string {
-  return nationality === "foreign"
-    ? "company_onboarding_documents_foreign"
-    : "company_onboarding_documents_ethiopian";
-}
-
 function hasFile(value: File | File[] | null | undefined): boolean {
   if (!value) return false;
   return Array.isArray(value) ? value.length > 0 : true;
@@ -95,13 +89,16 @@ export function ContractDocsEditor({
 }) {
   const auth = useAuth();
 
-  const nationality = auth.company?.company?.nationality as
-    | string
-    | null
-    | undefined;
+  const company = auth.company?.company;
+  const nationality = company?.nationality as string | null | undefined;
   const settingQuery = useQuery(
     api.fileUploadSettings.getByCode.queryOptions({
-      input: { code: documentSettingCode(nationality) },
+      input: {
+        code: documentSettingCode(
+          nationality,
+          company?.attributes?.cooperative === true,
+        ),
+      },
     }),
   );
 
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/new-contract-form/step-documents.tsx b/apps/edr-freight-web/portal/src/pages/contracts/new-contract-form/step-documents.tsx
index de4b2bd66..b0b870f72 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/new-contract-form/step-documents.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/new-contract-form/step-documents.tsx
@@ -7,6 +7,7 @@ import { type UseFormReturn } from "react-hook-form";
 
 import useAuth from "@/hooks/useAuth";
 import { api } from "@/services/api";
+import { documentSettingCode } from "@/utils/documentSettingCode";
 import {
   type ContractDocuments,
   type ContractFormInputValues,
@@ -21,12 +22,6 @@ type ContractForm = UseFormReturn<
   ContractFormValues
 >;
 
-function documentSettingCode(nationality: string | null | undefined): string {
-  return nationality === "foreign"
-    ? "company_onboarding_documents_foreign"
-    : "company_onboarding_documents_ethiopian";
-}
-
 function formatSize(bytes?: number): string {
   if (!bytes) return "";
   if (bytes < 1024) return `${bytes} B`;
@@ -61,14 +56,17 @@ export function StepDocuments({
   const auth = useAuth();
   const [errors, setErrors] = useState<Record<string, string>>({});
 
-  const nationality = auth.company?.company?.nationality as
-    | string
-    | null
-    | undefined;
+  const company = auth.company?.company;
+  const nationality = company?.nationality as string | null | undefined;
 
   const docSettingQuery = useQuery(
     api.fileUploadSettings.getByCode.queryOptions({
-      input: { code: documentSettingCode(nationality) },
+      input: {
+        code: documentSettingCode(
+          nationality,
+          company?.attributes?.cooperative === true,
+        ),
+      },
     }),
   );
 
diff --git a/apps/edr-freight-web/portal/src/pages/settings/NationalitySelect.tsx b/apps/edr-freight-web/portal/src/pages/settings/NationalitySelect.tsx
index 2115ec083..99569e748 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/NationalitySelect.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/NationalitySelect.tsx
@@ -9,6 +9,8 @@ interface NationalitySelectProps {
   onChange: (next: CompanyNationality) => void;
   /** Render only the option grid — the wizard supplies its own header/card. */
   embedded?: boolean;
+  /** Hide the foreign option (a co-operative union or farm is always Ethiopian). */
+  excludeForeign?: boolean;
 }
 
 /**
@@ -21,9 +23,10 @@ export default function NationalitySelect({
   value,
   onChange,
   embedded = false,
+  excludeForeign = false,
 }: NationalitySelectProps) {
   const grid = (
-    <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+    <SimpleGrid cols={{ base: 1, sm: excludeForeign ? 1 : 2 }} spacing="md">
       <RoleCard
         label="Ethiopian Company"
         description="Registered in Ethiopia. You'll provide a TIN certificate, commercial registration and national ID."
@@ -31,13 +34,15 @@ export default function NationalitySelect({
         selected={value === "ethiopian"}
         onClick={() => onChange("ethiopian")}
       />
-      <RoleCard
-        label="Foreign Company"
-        description="Registered abroad. You'll provide a passport and investment license."
-        icon={<Globe2 size={22} />}
-        selected={value === "foreign"}
-        onClick={() => onChange("foreign")}
-      />
+      {!excludeForeign && (
+        <RoleCard
+          label="Foreign Company"
+          description="Registered abroad. You'll provide a passport and investment license."
+          icon={<Globe2 size={22} />}
+          selected={value === "foreign"}
+          onClick={() => onChange("foreign")}
+        />
+      )}
     </SimpleGrid>
   );
 
diff --git a/apps/edr-freight-web/portal/src/pages/settings/TabDocuments.tsx b/apps/edr-freight-web/portal/src/pages/settings/TabDocuments.tsx
index 72d6738c8..584fb70d6 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabDocuments.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabDocuments.tsx
@@ -6,6 +6,7 @@ import {
   type LicenseFileStatus,
 } from "@/services/companies.service";
 import { getMinFiles } from "@/types/fileUploadSettings";
+import { documentSettingCode } from "@/utils/documentSettingCode";
 import type { ProfileResponse } from "@/types/profile";
 import {
   SmartFileInput,
@@ -57,14 +58,8 @@ interface TabDocumentsProps {
   onContinue?: () => void;
 }
 
-function documentSettingCode(nationality: string | null | undefined): string {
-  return nationality === "foreign"
-    ? "company_onboarding_documents_foreign"
-    : "company_onboarding_documents_ethiopian";
-}
-
 /**
- * The DARS delegation paper ships in the same nationality document set, but it is
+ * The DARS delegation paper ships in the same document set, but it is
  * edited on the Power of Attorney tab (where it is staged for review alongside
  * the PoA details), so it is excluded from this tab's uploader.
  */
@@ -83,7 +78,9 @@ export default function TabDocuments({
 
   const docSettingQuery = useQuery(
     api.fileUploadSettings.getByCode.queryOptions({
-      input: { code: documentSettingCode(profile.nationality) },
+      input: {
+        code: documentSettingCode(profile.nationality, profile.cooperative),
+      },
     }),
   );
 
diff --git a/apps/edr-freight-web/portal/src/services/companies.service.ts b/apps/edr-freight-web/portal/src/services/companies.service.ts
index e9cf478c3..4c1b93713 100644
--- a/apps/edr-freight-web/portal/src/services/companies.service.ts
+++ b/apps/edr-freight-web/portal/src/services/companies.service.ts
@@ -183,14 +183,8 @@ export interface OnboardingPoaState {
  * outstanding, so the client never hardcodes required fields or document sets.
  */
 export interface OnboardingRequirements {
+  /** The set the docs came from: the nationality one, or the co-operative one. */
   documentSettingCode: string;
-  /**
-   * Extra document set merged on top of the nationality one for a co-operative,
-   * null otherwise. `documents` already carries the merged list; this is only
-   * so the pickers, which render from the file-settings endpoint, can fetch the
-   * same extra fields.
-   */
-  cooperativeDocumentSettingCode: string | null;
   nationality: string;
   /** No business licence: registration typed by hand, no eTrade lookup. */
   cooperative: boolean;
diff --git a/apps/edr-freight-web/portal/src/utils/documentSettingCode.test.ts b/apps/edr-freight-web/portal/src/utils/documentSettingCode.test.ts
new file mode 100644
index 000000000..6063f1b87
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/utils/documentSettingCode.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+
+import { documentSettingCode } from "./documentSettingCode";
+
+describe("documentSettingCode", () => {
+  it("resolves the nationality set", () => {
+    expect(documentSettingCode("ethiopian")).toBe(
+      "company_onboarding_documents_ethiopian",
+    );
+    expect(documentSettingCode("foreign")).toBe(
+      "company_onboarding_documents_foreign",
+    );
+    expect(documentSettingCode(null)).toBe(
+      "company_onboarding_documents_ethiopian",
+    );
+  });
+
+  it("replaces the nationality set for a co-operative", () => {
+    expect(documentSettingCode("ethiopian", true)).toBe(
+      "company_onboarding_documents_cooperative",
+    );
+    // A co-op is never foreign, but a stale flag must not fall back to the
+    // foreign set — the co-op answer wins.
+    expect(documentSettingCode("foreign", true)).toBe(
+      "company_onboarding_documents_cooperative",
+    );
+  });
+});
diff --git a/apps/edr-freight-web/portal/src/utils/documentSettingCode.ts b/apps/edr-freight-web/portal/src/utils/documentSettingCode.ts
new file mode 100644
index 000000000..e27407c27
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/utils/documentSettingCode.ts
@@ -0,0 +1,18 @@
+/**
+ * The company document set a company resolves to — one of three, never a
+ * combination: a co-operative union or farm uploads its own papers INSTEAD of
+ * its nationality's (it holds no business licence), and is always Ethiopian.
+ *
+ * Mirrors `CompaniesService.documentSettingCodeFor` on the API; prefer the
+ * server-resolved `documentSettingCode` from onboarding requirements where one
+ * is available, and use this where only the company is at hand.
+ */
+export function documentSettingCode(
+  nationality: string | null | undefined,
+  cooperative?: boolean | null,
+): string {
+  if (cooperative) return "company_onboarding_documents_cooperative";
+  return nationality === "foreign"
+    ? "company_onboarding_documents_foreign"
+    : "company_onboarding_documents_ethiopian";
+}

From 4b8fea2d76bcbc97f7fb92868c0f0bd97a3ebd00 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 07:17:13 +0000
Subject: [PATCH 030/174] chore: update package overrides in
 pnpm-workspace.yaml for dependencies

---
 .../services/train-scheduling.service.spec.ts |   88 +
 .../services/train-scheduling.service.ts      |   55 +-
 pnpm-lock.yaml                                | 2250 +++++++++++------
 pnpm-workspace.yaml                           |    7 +
 4 files changed, 1601 insertions(+), 799 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
index 0a7384cfa..e6b3a5040 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
@@ -1646,4 +1646,92 @@ describe('TrainSchedulingService', () => {
       ).toBe(5);
     });
   });
+
+  describe('maintenanceReschedule — window reopens when it had already finished', () => {
+    const { TrainSchedule } = jest.requireActual(
+      '../../train-schedules/entities/train-schedule.entity',
+    );
+
+    const doneExportSchedule = (extra: Record<string, unknown> = {}) => ({
+      id: 'sch-done',
+      status: 'SCHEDULED',
+      direction: 'EXPORT',
+      windowPhase: 'DONE',
+      bookingWindowStatus: 'CLOSED',
+      scheduledDepartureDate: new Date('2027-06-20T05:00:00.000Z'),
+      scheduledArrivalDate: null,
+      originStationId: 'yard-origin',
+      destinationStationId: 'yard-destination',
+      scheduleBookings: [],
+      // Frozen rule snapshot: desk 8–17 EAT, 24h lead, close 120min before departure.
+      ruleWindowOpenHour: 8,
+      ruleWindowCloseHour: 17,
+      ruleExportBookingLeadHours: 24,
+      ruleExportCloseOffsetMinutes: 120,
+      ...extra,
+    });
+
+    let scheduleUpdate: jest.Mock;
+
+    beforeEach(() => {
+      scheduleUpdate = jest.fn().mockResolvedValue({ affected: 1 });
+      dataSource.getRepository.mockImplementation((entity: unknown) => {
+        if (entity === TrainSchedulingGlobalRules) {
+          return { find: jest.fn().mockResolvedValue([]) };
+        }
+        if (entity === TrainSchedule) {
+          return { update: scheduleUpdate, find: jest.fn().mockResolvedValue([]) };
+        }
+        return {
+          find: jest.fn().mockResolvedValue([]),
+          findOne: jest.fn().mockResolvedValue(null),
+          update: jest.fn(),
+        };
+      });
+      trainSchedulesRepository.findById.mockResolvedValue(null);
+    });
+
+    it('reopens a DONE export window against the new departure', async () => {
+      trainSchedulesRepository.findByIdWithFullGraph.mockResolvedValue(
+        doneExportSchedule(),
+      );
+
+      // New departure 12:00 EAT → window opens 24h earlier (12:00 EAT, inside
+      // the desk) and closes at departure − 120min = 10:00 EAT.
+      await service.maintenanceReschedule('sch-done', {
+        newDepartureDate: '2027-06-20T09:00:00.000Z',
+      } as never);
+
+      expect(scheduleUpdate).toHaveBeenCalledWith(
+        'sch-done',
+        expect.objectContaining({
+          scheduledDepartureDate: new Date('2027-06-20T09:00:00.000Z'),
+          windowPhase: 'PRE_WINDOW',
+          bookingWindowStatus: 'CLOSED',
+          windowOpensAt: new Date('2027-06-19T09:00:00.000Z'),
+          windowClosesAt: new Date('2027-06-20T07:00:00.000Z'),
+          docReviewCompletedAt: null,
+          docReviewEndsAt: null,
+          paymentPhaseEndsAt: null,
+        }),
+      );
+    });
+
+    it('keeps a FULL train closed — nothing left to sell', async () => {
+      trainSchedulesRepository.findByIdWithFullGraph.mockResolvedValue(
+        doneExportSchedule({ bookingWindowStatus: 'FULL' }),
+      );
+
+      await service.maintenanceReschedule('sch-done', {
+        newDepartureDate: '2027-06-20T09:00:00.000Z',
+      } as never);
+
+      const written = scheduleUpdate.mock.calls[0][1];
+      expect(written.scheduledDepartureDate).toEqual(
+        new Date('2027-06-20T09:00:00.000Z'),
+      );
+      expect(written.windowPhase).toBeUndefined();
+      expect(written.windowOpensAt).toBeUndefined();
+    });
+  });
 });
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index 6da28bd49..a740dc932 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -1182,13 +1182,23 @@ export class TrainSchedulingService {
       ? new Date(new Date(schedule.scheduledArrivalDate).getTime() + deltaMs)
       : undefined;
 
-    // PRE_WINDOW only: the stamped open/close were derived from the old
-    // departure and the window hasn't opened yet, so re-derive them from the
-    // schedule's own rule snapshot against the new date (joining the target
-    // day's route group timeline when one exists, exactly like
-    // updateScheduleDate). Mid/post-window schedules keep their timeline.
+    // PRE_WINDOW: the stamped open/close were derived from the old departure
+    // and the window hasn't opened yet, so re-derive them from the schedule's
+    // own rule snapshot against the new date (joining the target day's route
+    // group timeline when one exists, exactly like updateScheduleDate).
+    //
+    // DONE: the window already finished (e.g. the close offset hit and then the
+    // train was moved to a later departure). The window must follow the new
+    // departure, so it REOPENS: re-derive open/close the same way, reset the
+    // phase to PRE_WINDOW and clamp a past open into the present so the tick
+    // opens it immediately. A FULL train stays closed — there is nothing left
+    // to sell — and so does one whose re-derived window would already be over.
+    //
+    // Mid-window phases (OPEN/DOC_REVIEW/PAYMENT) keep their running timeline.
+    const reopenFromDone =
+      schedule.windowPhase === 'DONE' && schedule.bookingWindowStatus !== 'FULL';
     const windowFields =
-      schedule.windowPhase === 'PRE_WINDOW'
+      schedule.windowPhase === 'PRE_WINDOW' || reopenFromDone
         ? await (async () => {
             const merged = effectiveWindowConfig(
               schedule,
@@ -1207,12 +1217,33 @@ export class TrainSchedulingService {
                     schedule.destinationStationId,
                     departure,
                   );
-            return anchor
-              ? this.groupWindowFieldsFrom(anchor, departure)
-              : {
-                  windowOpensAt: times.windowOpensAt,
-                  windowClosesAt: times.windowClosesAt,
-                };
+            if (anchor) {
+              // groupWindowFieldsFrom copies the anchor's live phase and
+              // deadlines, so a DONE train joining a live group re-enters the
+              // group's cycle directly — no extra reset needed.
+              return this.groupWindowFieldsFrom(anchor, departure);
+            }
+            if (!reopenFromDone) {
+              return {
+                windowOpensAt: times.windowOpensAt,
+                windowClosesAt: times.windowClosesAt,
+              };
+            }
+            const now = new Date();
+            const windowOpensAt =
+              times.windowOpensAt < now ? now : times.windowOpensAt;
+            if (times.windowClosesAt.getTime() <= windowOpensAt.getTime()) {
+              return {}; // no window fits before the new departure — stay closed
+            }
+            return {
+              windowOpensAt,
+              windowClosesAt: times.windowClosesAt,
+              windowPhase: 'PRE_WINDOW',
+              bookingWindowStatus: 'CLOSED',
+              docReviewCompletedAt: null,
+              docReviewEndsAt: null,
+              paymentPhaseEndsAt: null,
+            };
           })()
         : {};
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0caaa0905..7f59d43c5 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4,13 +4,6 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
-overrides:
-  date-fns: ^3.6.0
-  pdfjs-dist: ^3.11.174
-  react: 19.2.6
-  react-dom: 19.2.6
-  typeorm: 0.3.30
-
 importers:
 
   .:
@@ -105,10 +98,10 @@ importers:
         version: 11.1.27(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/platform-socket.io@11.1.27)(reflect-metadata@0.2.2)(rxjs@7.8.2)
       '@tria-plc/api-common':
         specifier: file:../../local-packages/tria-plc-api-common-1.6.0.tgz
-        version: file:local-packages/tria-plc-api-common-1.6.0.tgz(2te6mb6vb2upxetsvhkgi54vi4)
+        version: file:local-packages/tria-plc-api-common-1.6.0.tgz(ae9a56cc1c6d93629dd85f7605ccd5b6)
       '@tria-plc/iamapi-common':
         specifier: file:../../local-packages/tria-plc-iamapi-common-1.0.0.tgz
-        version: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(776yg74vcz655pvzf2fzttkf2q)
+        version: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(d0be280d95adfc1b38e59bdc80c5dec5)
       amqp-connection-manager:
         specifier: ^5.0.0
         version: 5.0.0(amqplib@2.0.1)
@@ -161,7 +154,7 @@ importers:
         specifier: ^4.8.3
         version: 4.8.3
       typeorm:
-        specifier: 0.3.30
+        specifier: ^0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
     devDependencies:
       '@edr/eslint-config':
@@ -361,7 +354,7 @@ importers:
         version: 6.3.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tinymce@8.6.0)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(elggzzmuouas3d7ccap2lbvoyu)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)
       '@types/three':
         specifier: ^0.185.3
         version: 0.185.3
@@ -563,7 +556,7 @@ importers:
         version: 10.5.0(postcss@8.5.15)
       jsdom:
         specifier: ^25.0.1
-        version: 25.0.1(canvas@2.11.2)
+        version: 25.0.1
       postcss:
         specifier: ^8.4.47
         version: 8.5.15
@@ -578,7 +571,7 @@ importers:
         version: 5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0)
       vitest:
         specifier: ^2.1.2
-        version: 2.1.9(@types/node@24.13.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0)
+        version: 2.1.9(@types/node@24.13.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0)
 
   apps/edr-freight-web/portal:
     dependencies:
@@ -608,7 +601,7 @@ importers:
         version: 5.101.0(react@19.2.6)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(vhj5jsbx2ogblwtd5crolhrpku)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)
       '@vis.gl/react-google-maps':
         specifier: ^1.8.3
         version: 1.8.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -702,7 +695,7 @@ importers:
         version: 10.5.0(postcss@8.5.15)
       jsdom:
         specifier: ^25.0.1
-        version: 25.0.1(canvas@2.11.2)
+        version: 25.0.1
       postcss:
         specifier: ^8.4.47
         version: 8.5.15
@@ -717,7 +710,7 @@ importers:
         version: 5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0)
       vitest:
         specifier: ^2.1.2
-        version: 2.1.9(@types/node@24.13.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0)
+        version: 2.1.9(@types/node@24.13.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0)
 
   apps/edr-gps-tracker:
     dependencies:
@@ -749,7 +742,7 @@ importers:
         specifier: ^7.8.1
         version: 7.8.2
       typeorm:
-        specifier: 0.3.30
+        specifier: ^0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
     devDependencies:
       '@edr/eslint-config':
@@ -838,10 +831,10 @@ importers:
         version: 8.1.6
       '@tria-plc/api-common':
         specifier: file:../../local-packages/tria-plc-api-common-1.6.0.tgz
-        version: file:local-packages/tria-plc-api-common-1.6.0.tgz(66zjxtt2zhydyq6w3arhrktl4y)
+        version: file:local-packages/tria-plc-api-common-1.6.0.tgz(2b4e99ab22f78c34e7861d649f4ff29b)
       '@tria-plc/iamapi-common':
         specifier: file:../../local-packages/tria-plc-iamapi-common-1.0.0.tgz
-        version: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(2duxgcsfjn5usnyutzzh6i5xr4)
+        version: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(cc085a020c559b355f168432c579a024)
       '@types/bcrypt':
         specifier: ^6.0.0
         version: 6.0.0
@@ -900,7 +893,7 @@ importers:
         specifier: ^4.2.0
         version: 4.2.0
       typeorm:
-        specifier: 0.3.30
+        specifier: ^0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
       uuid:
         specifier: ^10.0.0
@@ -977,7 +970,7 @@ importers:
         version: link:../../../packages/ui-common
       '@tanstack/react-query':
         specifier: ^5.59.0
-        version: 5.101.0(react@19.2.6)
+        version: 5.101.0(react@18.3.1)
       axios:
         specifier: ^1.7.7
         version: 1.17.0
@@ -985,32 +978,32 @@ importers:
         specifier: ^2.1.1
         version: 2.1.1
       date-fns:
-        specifier: ^3.6.0
+        specifier: ^3.0.0
         version: 3.6.0
       lucide-react:
         specifier: ^0.446.0
-        version: 0.446.0(react@19.2.6)
+        version: 0.446.0(react@18.3.1)
       next:
         specifier: ^14.2.0
-        version: 14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       react:
-        specifier: 19.2.6
-        version: 19.2.6
+        specifier: ^18.3.1
+        version: 18.3.1
       react-day-picker:
         specifier: ^9.14.0
-        version: 9.14.0(react@19.2.6)
+        version: 9.14.0(react@18.3.1)
       react-dom:
-        specifier: 19.2.6
-        version: 19.2.6(react@19.2.6)
+        specifier: ^18.3.1
+        version: 18.3.1(react@18.3.1)
       recharts:
         specifier: ^2.12.0
-        version: 2.15.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 2.15.4(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       socket.io-client:
         specifier: ^4.8.3
         version: 4.8.3
       zustand:
         specifier: ^5.0.0
-        version: 5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@19.2.6)(use-sync-external-store@1.6.0(react@19.2.6))
+        version: 5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@18.3.1)(use-sync-external-store@1.6.0(react@18.3.1))
     devDependencies:
       '@types/node':
         specifier: ^20.0.0
@@ -1050,10 +1043,10 @@ importers:
         version: link:../../../packages/ui-common
       '@hookform/resolvers':
         specifier: ^3.3.4
-        version: 3.10.0(react-hook-form@7.77.0(react@19.2.6))
+        version: 3.10.0(react-hook-form@7.77.0(react@18.3.1))
       '@tanstack/react-query':
         specifier: ^5.59.0
-        version: 5.101.0(react@19.2.6)
+        version: 5.101.0(react@18.3.1)
       '@types/qrcode':
         specifier: ^1.5.6
         version: 1.5.6
@@ -1064,7 +1057,7 @@ importers:
         specifier: ^2.1.1
         version: 2.1.1
       date-fns:
-        specifier: ^3.6.0
+        specifier: ^3.0.0
         version: 3.6.0
       jspdf:
         specifier: ^4.2.1
@@ -1074,25 +1067,25 @@ importers:
         version: 5.0.8(jspdf@4.2.1)
       lucide-react:
         specifier: ^0.446.0
-        version: 0.446.0(react@19.2.6)
+        version: 0.446.0(react@18.3.1)
       next:
         specifier: ^14.2.0
-        version: 14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       qrcode:
         specifier: ^1.5.4
         version: 1.5.4
       qrcode.react:
         specifier: ^3.1.0
-        version: 3.2.0(react@19.2.6)
+        version: 3.2.0(react@18.3.1)
       react:
-        specifier: 19.2.6
-        version: 19.2.6
+        specifier: ^18.3.1
+        version: 18.3.1
       react-dom:
-        specifier: 19.2.6
-        version: 19.2.6(react@19.2.6)
+        specifier: ^18.3.1
+        version: 18.3.1(react@18.3.1)
       react-hook-form:
         specifier: ^7.51.0
-        version: 7.77.0(react@19.2.6)
+        version: 7.77.0(react@18.3.1)
       socket.io-client:
         specifier: ^4.8.3
         version: 4.8.3
@@ -1101,7 +1094,7 @@ importers:
         version: 3.25.76
       zustand:
         specifier: ^5.0.0
-        version: 5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@19.2.6)(use-sync-external-store@1.6.0(react@19.2.6))
+        version: 5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@18.3.1)(use-sync-external-store@1.6.0(react@18.3.1))
     devDependencies:
       '@types/node':
         specifier: ^20.0.0
@@ -1283,7 +1276,7 @@ importers:
         version: 5.9.3
       vitest:
         specifier: ^2.1.2
-        version: 2.1.9(@types/node@22.20.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(terser@5.48.0)
+        version: 2.1.9(@types/node@22.20.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(terser@5.48.0)
 
   packages/api-common:
     dependencies:
@@ -1313,7 +1306,7 @@ importers:
         specifier: ^7.8.1
         version: 7.8.2
       typeorm:
-        specifier: 0.3.30
+        specifier: ^0.3.20
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
       typescript:
         specifier: ^5.5.4
@@ -1381,7 +1374,7 @@ importers:
         specifier: ^29.2.5
         version: 29.4.11(@babel/core@7.29.7)(@jest/transform@29.7.0)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(jest-util@29.7.0)(jest@29.7.0(@types/node@20.19.42)(babel-plugin-macros@3.1.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))(typescript@5.9.3)
       typeorm:
-        specifier: 0.3.30
+        specifier: ^0.3.20
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
       typescript:
         specifier: ^5.5.4
@@ -1443,10 +1436,10 @@ importers:
         version: link:../types
       '@mantine/core':
         specifier: ^9.3.0
-        version: 9.3.0(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 9.3.0(@mantine/hooks@9.3.0(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@tanstack/react-table':
         specifier: ^8.21.3
-        version: 8.21.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 8.21.3(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       class-variance-authority:
         specifier: ^0.7.1
         version: 0.7.1
@@ -1455,10 +1448,10 @@ importers:
         version: 2.1.1
       lucide-react:
         specifier: ^1.14.0
-        version: 1.17.0(react@19.2.6)
+        version: 1.17.0(react@18.3.1)
       radix-ui:
         specifier: ^1.4.3
-        version: 1.5.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 1.5.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       shadcn:
         specifier: ^4.7.0
         version: 4.10.0(@types/node@24.13.1)(babel-plugin-macros@3.1.0)(typescript@5.9.3)
@@ -1488,11 +1481,11 @@ importers:
         specifier: ^8.4.47
         version: 8.5.15
       react:
-        specifier: 19.2.6
-        version: 19.2.6
+        specifier: ^18.3.1
+        version: 18.3.1
       react-dom:
-        specifier: 19.2.6
-        version: 19.2.6(react@19.2.6)
+        specifier: ^18.3.1
+        version: 18.3.1(react@18.3.1)
       tailwindcss:
         specifier: ^4.3.0
         version: 4.3.0
@@ -2006,7 +1999,7 @@ packages:
     resolution: {integrity: sha512-O000MLDBDdk/EohJPFUqvnp4qnHeYkVP5B0xEG0D/L7cOKP9kefu2DXn8dj74cQfsEzUqh+sr1RzFqiL1o+PpA==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: '>=16.8.0'
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -2022,7 +2015,7 @@ packages:
     peerDependencies:
       '@emotion/react': ^11.0.0-rc.0
       '@types/react': '*'
-      react: 19.2.6
+      react: '>=16.8.0'
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -2039,7 +2032,7 @@ packages:
   '@emotion/use-insertion-effect-with-fallbacks@1.2.0':
     resolution: {integrity: sha512-yJMtVdH59sxi/aVJBpk9FQq+OR8ll5GT8oWd57UpeaKEVGab41JWaCFA7FRLoMLloOZF/c/wsPoe+bfGmRKgDg==}
     peerDependencies:
-      react: 19.2.6
+      react: '>=16.8.0'
 
   '@emotion/utils@1.4.2':
     resolution: {integrity: sha512-3vLclRofFziIa3J2wDh9jjbkUz9qk5Vi3IZ/FSTKViB0k+ef0fPV7dYrUIugbgupYDx7v9ud/SjrtEP8Y4xLoA==}
@@ -2225,20 +2218,20 @@ packages:
   '@floating-ui/react-dom@2.1.8':
     resolution: {integrity: sha512-cC52bHwM/n/CxS87FH0yWdngEZrjdtLW/qVruo68qg+prK7ZQ4YGdut2GyDVpoGeAYe/h899rVeOVm6Oi40k2A==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@floating-ui/react@0.26.28':
     resolution: {integrity: sha512-yORQuuAtVpiRjpMhdc0wJj06b9JFjrYF4qp96j++v2NBpbi6SEGF7donUJ3TMieerQ6qVkAv1tgr7L4r5roTqw==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@floating-ui/react@0.27.19':
     resolution: {integrity: sha512-31B8h5mm8YxotlE7/AU/PhNAl8eWxAmjL/v2QOxroDNkTFLk3Uu82u63N3b6TXa4EGJeeZLVcd/9AlNlVqzeog==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=17.0.0'
+      react-dom: '>=17.0.0'
 
   '@floating-ui/utils@0.2.11':
     resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
@@ -2263,8 +2256,8 @@ packages:
   '@hello-pangea/dnd@18.0.1':
     resolution: {integrity: sha512-xojVWG8s/TGrKT1fC8K2tIWeejJYTAeJuj36zM//yEm/ZrnZUSFGS15BpO+jGZT1ybWvyXmeDJwPYb4dhWlbZQ==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
 
   '@hono/node-server@1.19.14':
     resolution: {integrity: sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==}
@@ -2275,8 +2268,8 @@ packages:
   '@hookform/devtools@4.4.0':
     resolution: {integrity: sha512-Mtlic+uigoYBPXlfvPBfiYYUZuyMrD3pTjDpVIhL6eCZTvQkHsKBSKeZCvXWUZr8fqrkzDg27N+ZuazLKq6Vmg==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8.0 || ^17 || ^18 || ^19
+      react-dom: ^16.8.0 || ^17 || ^18 || ^19
 
   '@hookform/resolvers@3.10.0':
     resolution: {integrity: sha512-79Dv+3mDF7i+2ajj7SkypSKHhl1cbln1OGavqrsF7p6mbUv11xpqpacPsGDCTRvCSjEEIez2ef1NveSVL3b0Ag==}
@@ -2684,8 +2677,8 @@ packages:
   '@lexical/devtools-core@0.48.0':
     resolution: {integrity: sha512-4kvKWW6ebgQnJNLXPLmw7dqgSChvzYIBNYtfuR6c48Sw+V/QXQTWqfIUbCIe5X4uG8EEXd5O/udXaJx7GBuP+w==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=18.x'
+      react-dom: '>=18.x'
       typescript: '>=5.2'
     peerDependenciesMeta:
       typescript:
@@ -2790,8 +2783,8 @@ packages:
   '@lexical/react@0.48.0':
     resolution: {integrity: sha512-uVh9/QSrbtjLjVbxfJ+sfiMyhUq/rv7H6uBEVDDIw1rkZJSDY1fvf/CX+dyKgwcDFjKQZ8/9i5f9UCVPeQ01hA==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=18.x'
+      react-dom: '>=18.x'
       typescript: '>=5.2'
       yjs: '>=13.5.22'
     peerDependenciesMeta:
@@ -2903,7 +2896,7 @@ packages:
   '@lottiefiles/react-lottie-player@3.6.0':
     resolution: {integrity: sha512-WK5TriLJT93VF3w4IjSVyveiedraZCnDhKzCPhpbeLgQeMi6zufxa3dXNc4HmAFRXq+LULPAy+Idv1rAfkReMA==}
     peerDependencies:
-      react: 19.2.6
+      react: 16 - 19
 
   '@lukeed/csprng@1.1.0':
     resolution: {integrity: sha512-Z7C/xXCiGWsg0KuKsHTKJxbWhpI3Vs5GwLfOean7MGyVFGqdRgBbAjOCh6u4bbjPc/8MJ2pZmK/0DLdCbivLDA==}
@@ -2914,30 +2907,30 @@ packages:
     peerDependencies:
       '@mantine/core': 7.17.8
       '@mantine/hooks': 7.17.8
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^18.x || ^19.x
+      react-dom: ^18.x || ^19.x
       recharts: ^2.13.3
 
   '@mantine/core@7.17.8':
     resolution: {integrity: sha512-42sfdLZSCpsCYmLCjSuntuPcDg3PLbakSmmYfz5Auea8gZYLr+8SS5k647doVu0BRAecqYOytkX2QC5/u/8VHw==}
     peerDependencies:
       '@mantine/hooks': 7.17.8
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^18.x || ^19.x
+      react-dom: ^18.x || ^19.x
 
   '@mantine/core@9.3.0':
     resolution: {integrity: sha512-mHVCm61YVW9ipy9eHiKMqsRUm3TkOErbdw7zHs0HRw5g403nf7tSTqNGvaYE+aX1Py874qMkrUzeQfj4bjiiBA==}
     peerDependencies:
       '@mantine/hooks': 9.3.0
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^19.2.0
+      react-dom: ^19.2.0
 
   '@mantine/core@9.3.2':
     resolution: {integrity: sha512-Upy/Z9Sj2eW2dGrFgUy/2kISVsxMTBYTDfP2TFdsIA3PdPSBkdqfSOPX/ug3d3F3a4bnwQSqcO6+aPEpBIh8dg==}
     peerDependencies:
       '@mantine/hooks': 9.3.2
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^19.2.0
+      react-dom: ^19.2.0
 
   '@mantine/dates@7.17.8':
     resolution: {integrity: sha512-KYog/YL83PnsMef7EZagpOFq9I2gfnK0eYSzC8YvV9Mb6t/x9InqRssGWVb0GIr+TNILpEkhKoGaSKZNy10Q1g==}
@@ -2945,8 +2938,8 @@ packages:
       '@mantine/core': 7.17.8
       '@mantine/hooks': 7.17.8
       dayjs: '>=1.0.0'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^18.x || ^19.x
+      react-dom: ^18.x || ^19.x
 
   '@mantine/dates@9.3.2':
     resolution: {integrity: sha512-MzHrXGoOb3rCnHBlsI/BPAjC8K5tZ4f8pzg66tsTsupVCQBaBpHSVatQwNRJ6K2JC9pyCyTa9BL803C8AiWycA==}
@@ -2954,40 +2947,36 @@ packages:
       '@mantine/core': 9.3.2
       '@mantine/hooks': 9.3.2
       dayjs: '>=1.0.0'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^19.2.0
+      react-dom: ^19.2.0
 
   '@mantine/hooks@7.17.8':
     resolution: {integrity: sha512-96qygbkTjRhdkzd5HDU8fMziemN/h758/EwrFu7TlWrEP10Vw076u+Ap/sG6OT4RGPZYYoHrTlT+mkCZblWHuw==}
     peerDependencies:
-      react: 19.2.6
+      react: ^18.x || ^19.x
 
   '@mantine/hooks@9.3.0':
     resolution: {integrity: sha512-QoSr9WI4WsKWrM3qFYYizHUn3+n+CVcFMYe4sdlnmFPStvs6BacPODKJSbFlYl73Z20t82JIy0eKqt4noHQI2g==}
     peerDependencies:
-      react: 19.2.6
+      react: ^19.2.0
 
   '@mantine/hooks@9.3.2':
     resolution: {integrity: sha512-jOjpUe0x1A/k3XUiu2/aaSCasXRI5ZKZOucm3ypwsvm9F2u8C1xzwBvagrzlbNZwJRF5vNYIJtCaT7NunPyc0A==}
     peerDependencies:
-      react: 19.2.6
+      react: ^19.2.0
 
   '@mantine/notifications@7.17.8':
     resolution: {integrity: sha512-/YK16IZ198W6ru/IVecCtHcVveL08u2c8TbQTu/2p26LSIM9AbJhUkrU6H+AO0dgVVvmdmNdvPxcJnfq3S9TMg==}
     peerDependencies:
       '@mantine/core': 7.17.8
       '@mantine/hooks': 7.17.8
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^18.x || ^19.x
+      react-dom: ^18.x || ^19.x
 
   '@mantine/store@7.17.8':
     resolution: {integrity: sha512-/FrB6PAVH4NEjQ1dsc9qOB+VvVlSuyjf4oOOlM9gscPuapDP/79Ryq7JkhHYfS55VWQ/YUlY24hDI2VV+VptXg==}
     peerDependencies:
-      react: 19.2.6
-
-  '@mapbox/node-pre-gyp@1.0.11':
-    resolution: {integrity: sha512-Yhlar6v9WQgUp/He7BdgzOz8lqMQ8sU+jkCq7Wx8Myc5YFJLbEe7lgui/V7G1qB1DJykHSGwreceSaD60Y0PUQ==}
-    hasBin: true
+      react: ^18.x || ^19.x
 
   '@marijn/find-cluster-break@1.0.3':
     resolution: {integrity: sha512-FY+MKLBoTsLNJF/eLWaOsXGdz6uh3Iu1axjPf6TUq92IYumcTcXWHoS747JARLkcdlJ/Waiaxc5wQfFO8jC6NA==}
@@ -2996,15 +2985,15 @@ packages:
     resolution: {integrity: sha512-S/IPY8AjWTV2v1TGbEy5lsbQ5w+J2M2j2QDeswxP4FpNh2B49OPkpSqHbbX5GbV0YBlhfXJxtzwBJv/sQACufw==}
     engines: {node: '>=16'}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>= 18 || >= 19'
+      react-dom: '>= 18 || >= 19'
 
   '@mdxeditor/gurx@1.2.4':
     resolution: {integrity: sha512-9ZykIFYhKaXaaSPCs1cuI+FvYDegJjbKwmA4ASE/zY+hJY6EYqvoye4esiO85CjhOw9aoD/izD/CU78/egVqmg==}
     engines: {node: '>=16'}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>= 18 || >= 19'
+      react-dom: '>= 18 || >= 19'
 
   '@microsoft/tsdoc@0.15.1':
     resolution: {integrity: sha512-4aErSrCR/On/e5G2hDP0wjooqDdauzEbIq8hIkIe5pXV0rtWJZvdCEKL0ykZxex+IxIwBp0eGeV48hQN07dXtw==}
@@ -3032,8 +3021,8 @@ packages:
     deprecated: This package has been replaced by @base-ui/react
     peerDependencies:
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3047,7 +3036,7 @@ packages:
     peerDependencies:
       '@mui/material': ^5.0.0
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: 19.2.6
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3059,8 +3048,8 @@ packages:
       '@emotion/react': ^11.5.0
       '@emotion/styled': ^11.3.0
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@emotion/react':
         optional: true
@@ -3074,7 +3063,7 @@ packages:
     engines: {node: '>=12.0.0'}
     peerDependencies:
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: 19.2.6
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3085,7 +3074,7 @@ packages:
     peerDependencies:
       '@emotion/react': ^11.4.1
       '@emotion/styled': ^11.3.0
-      react: 19.2.6
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@emotion/react':
         optional: true
@@ -3099,7 +3088,7 @@ packages:
       '@emotion/react': ^11.5.0
       '@emotion/styled': ^11.3.0
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: 19.2.6
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@emotion/react':
         optional: true
@@ -3121,7 +3110,7 @@ packages:
     engines: {node: '>=12.0.0'}
     peerDependencies:
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: 19.2.6
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3131,7 +3120,7 @@ packages:
     engines: {node: '>=14.0.0'}
     peerDependencies:
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: 19.2.6
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3144,15 +3133,15 @@ packages:
       '@emotion/styled': ^11.8.1
       '@mui/material': ^5.8.6
       '@mui/system': ^5.8.0
-      date-fns: ^3.6.0
+      date-fns: ^2.25.0 || ^3.2.0
       date-fns-jalali: ^2.13.0-0
       dayjs: ^1.10.7
       luxon: ^3.0.2
       moment: ^2.29.4
       moment-hijri: ^2.1.2
       moment-jalaali: ^0.7.4 || ^0.8.0 || ^0.9.0 || ^0.10.0
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^17.0.0 || ^18.0.0
+      react-dom: ^17.0.0 || ^18.0.0
     peerDependenciesMeta:
       '@emotion/react':
         optional: true
@@ -3202,30 +3191,35 @@ packages:
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@napi-rs/canvas-linux-arm64-musl@0.1.100':
     resolution: {integrity: sha512-K3mDW66N+xT2/V439u1alFANiBUjdEx2gLiNYnCmUsva5jZMxWTjafBYwTzYK+EMFMHrUoabuU+T1BIP5CgbYQ==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@napi-rs/canvas-linux-riscv64-gnu@0.1.100':
     resolution: {integrity: sha512-mooqUBTIsccZpnoQC4NgrC1v6C1vof39etLNMnBwCY+p0gajWJvAHLGQ6g/gGyS5YrpDW+GefSN4+Cvcr08UWw==}
     engines: {node: '>= 10'}
     cpu: [riscv64]
     os: [linux]
+    libc: [glibc]
 
   '@napi-rs/canvas-linux-x64-gnu@0.1.100':
     resolution: {integrity: sha512-1eCvkDCazm7FFhsT7DfGOdSaHgZVK3bt/dSBl5EWHOWmnz+I7j8tPseJqqD81NF+MH21jKUK4wQSDjN0mdhnTg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@napi-rs/canvas-linux-x64-musl@0.1.100':
     resolution: {integrity: sha512-20arT6lnI19S68qNlii73TSEDbECNgzMz2EpldC1V3mZFuRkeujXkcebRk0LRJe9SEUAooYiLokfMViY8IX7yA==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@napi-rs/canvas-win32-arm64-msvc@0.1.100':
     resolution: {integrity: sha512-DZFFT1wIAg37LJw37yhMRFfjATd3vTQzjZ1Yki8u2vhO6Hi5VE6BVaGQ1aaDu7xb4iMErz+9EOwjpS7xcxFeBw==}
@@ -3474,7 +3468,7 @@ packages:
       '@nestjs/core': ^10.0.0 || ^11.0.0
       reflect-metadata: ^0.1.13 || ^0.2.0
       rxjs: ^7.2.0
-      typeorm: 0.3.30
+      typeorm: ^0.3.0 || ^1.0.0-dev
 
   '@nestjs/websockets@11.1.27':
     resolution: {integrity: sha512-X3OgJt9KgYTvt9D7sNz9SOj3A1daAHy7DZrYhM1pky8Fh+erlKQH5IQ/tKm+GaJKA5M0srBUr1CMqjak/qNxOw==}
@@ -3511,24 +3505,28 @@ packages:
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@next/swc-linux-arm64-musl@14.2.33':
     resolution: {integrity: sha512-Bm+QulsAItD/x6Ih8wGIMfRJy4G73tu1HJsrccPW6AfqdZd0Sfm5Imhgkgq2+kly065rYMnCOxTBvmvFY1BKfg==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@next/swc-linux-x64-gnu@14.2.33':
     resolution: {integrity: sha512-FnFn+ZBgsVMbGDsTqo8zsnRzydvsGV8vfiWwUo1LD8FTmPTdV+otGSWKc4LJec0oSexFnCYVO4hX8P8qQKaSlg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@next/swc-linux-x64-musl@14.2.33':
     resolution: {integrity: sha512-345tsIWMzoXaQndUTDv1qypDRiebFxGYx9pYkhwY4hBRaOLt8UGfiWKr9FSSHs25dFIf8ZqIFaPdy5MljdoawA==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@next/swc-win32-arm64-msvc@14.2.33':
     resolution: {integrity: sha512-nscpt0G6UCTkrT2ppnJnFsYbPDQwmum4GNXYTeoTIdsmMydSKFz9Iny2jpaRupTb+Wl298+Rh82WKzt9LCcqSQ==}
@@ -3625,36 +3623,42 @@ packages:
     engines: {node: '>= 10.0.0'}
     cpu: [arm]
     os: [linux]
+    libc: [glibc]
 
   '@parcel/watcher-linux-arm-musl@2.5.6':
     resolution: {integrity: sha512-Ve3gUCG57nuUUSyjBq/MAM0CzArtuIOxsBdQ+ftz6ho8n7s1i9E1Nmk/xmP323r2YL0SONs1EuwqBp2u1k5fxg==}
     engines: {node: '>= 10.0.0'}
     cpu: [arm]
     os: [linux]
+    libc: [musl]
 
   '@parcel/watcher-linux-arm64-glibc@2.5.6':
     resolution: {integrity: sha512-f2g/DT3NhGPdBmMWYoxixqYr3v/UXcmLOYy16Bx0TM20Tchduwr4EaCbmxh1321TABqPGDpS8D/ggOTaljijOA==}
     engines: {node: '>= 10.0.0'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@parcel/watcher-linux-arm64-musl@2.5.6':
     resolution: {integrity: sha512-qb6naMDGlbCwdhLj6hgoVKJl2odL34z2sqkC7Z6kzir8b5W65WYDpLB6R06KabvZdgoHI/zxke4b3zR0wAbDTA==}
     engines: {node: '>= 10.0.0'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@parcel/watcher-linux-x64-glibc@2.5.6':
     resolution: {integrity: sha512-kbT5wvNQlx7NaGjzPFu8nVIW1rWqV780O7ZtkjuWaPUgpv2NMFpjYERVi0UYj1msZNyCzGlaCWEtzc+exjMGbQ==}
     engines: {node: '>= 10.0.0'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@parcel/watcher-linux-x64-musl@2.5.6':
     resolution: {integrity: sha512-1JRFeC+h7RdXwldHzTsmdtYR/Ku8SylLgTU/reMuqdVD7CtLwf0VR1FqeprZ0eHQkO0vqsbvFLXUmYm/uNKJBg==}
     engines: {node: '>= 10.0.0'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@parcel/watcher-win32-arm64@2.5.6':
     resolution: {integrity: sha512-3ukyebjc6eGlw9yRt678DxVF7rjXatWiHvTXqphZLvo7aC5NdEgFufVwjFfY51ijYEWpXbqF5jtrK275z52D4Q==}
@@ -3708,7 +3712,7 @@ packages:
     peerDependencies:
       '@types/react': '>=16.8.0'
       posthog-js: '>=1.257.2'
-      react: 19.2.6
+      react: '>=16.8.0'
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3768,8 +3772,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3781,8 +3785,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3794,8 +3798,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3807,8 +3811,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3820,8 +3824,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3833,8 +3837,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3846,8 +3850,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3859,8 +3863,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3872,8 +3876,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3884,7 +3888,7 @@ packages:
     resolution: {integrity: sha512-rYOP8OMnuuPMQF1uhPVlGNcCDlkokKqGFE3JcxFViIkAXP7EvFWUliJAstrapypaBLJNHbZL6jGhbVDGTwmVhA==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3894,8 +3898,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3906,7 +3910,7 @@ packages:
     resolution: {integrity: sha512-QwH4PO5urrbO+FaGd5Aglg+YJgWTyyuZ3g/6mKvsqraLkglDdckw9JafgL5McL5VEJ6EPNduPaT3ZE9BttDAqg==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3916,8 +3920,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3928,7 +3932,7 @@ packages:
     resolution: {integrity: sha512-C3vFhbyi4SW3PmbAi6Awpu4OzJtd0MxGurvSsYtr7p7nM8RNB3VAF3CUmnp2j50knpkrRcB7+ycVXzgLgF6yNA==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3938,8 +3942,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3951,8 +3955,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3963,7 +3967,7 @@ packages:
     resolution: {integrity: sha512-cot/aB/mOm0IYVYTTmQcEEK1M48lZWi8FlYe5nDPQQ8NYZUlXEFgncJ9p2Kzer3RKSrY7cTTpEMLZKNo9QoP5Q==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3973,8 +3977,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3986,8 +3990,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3999,8 +4003,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4010,13 +4014,13 @@ packages:
   '@radix-ui/react-icons@1.3.2':
     resolution: {integrity: sha512-fyQIhGDhzfc9pK2kH6Pl9c4BDJGfMkPqkyIgYDthyNYoNg3wVhoJMMh19WS4Up/1KMPFVpNsT2q3WmXn2N1m6g==}
     peerDependencies:
-      react: 19.2.6
+      react: ^16.x || ^17.x || ^18.x || ^19.0.0 || ^19.0.0-rc
 
   '@radix-ui/react-id@1.1.2':
     resolution: {integrity: sha512-orBC88futVpqCmhX1p4cvquNHsELQ+w+vBJnuj3ftETI5bJb0bZn3Tqu3SWN2IOcPycTnMGnhwoermvISt72sA==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4026,8 +4030,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4039,8 +4043,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4052,8 +4056,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4065,8 +4069,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4078,8 +4082,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4091,8 +4095,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4104,8 +4108,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4117,8 +4121,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4130,8 +4134,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4143,8 +4147,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4156,8 +4160,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4169,8 +4173,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4182,8 +4186,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4195,8 +4199,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4208,8 +4212,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4221,8 +4225,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4234,8 +4238,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4247,8 +4251,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4259,7 +4263,7 @@ packages:
     resolution: {integrity: sha512-rCMO3QsIVKv5JTY5CVbo2MvO77SpEqqYc8AvRE7OWqRDOIqAKjsp+DrmnY9uc8NPdxB5E2z47HTYGeE2+NTptg==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4269,8 +4273,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4282,8 +4286,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4295,8 +4299,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4308,8 +4312,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4321,8 +4325,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4334,8 +4338,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4347,8 +4351,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4359,7 +4363,7 @@ packages:
     resolution: {integrity: sha512-xCso9j1/u8sEgP1RNHjFrXJLApL8LiqOkI1R4ywuN00rxWdYg4oQXuwKLS3i0j5NWLromUD27/4nlxj2UFVvIw==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4368,7 +4372,7 @@ packages:
     resolution: {integrity: sha512-PLzC90MS+ReootmjC597dvopoelpZ8Q61HJkDXZSExitIq7PL55vHNnesAHwguHK0aPfBnpdNzQtv1uliaqQrA==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4377,7 +4381,7 @@ packages:
     resolution: {integrity: sha512-6c8ZqvPTWILEKnyVkP53EGRCcpnJiKTC21sS/6R1GF5xKyHJJWQEPfkqlcgUkdRQivd6tb23abUwe4ngWmY0JA==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4386,7 +4390,7 @@ packages:
     resolution: {integrity: sha512-2uVLvLjgO7NZCWw01/FdqRwmA42J0BcjPMUCA+koFEOAb+zjqIP7SiFz/7zWPrKnVmSqr76Omq2ALyCuX4dhLw==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4395,7 +4399,7 @@ packages:
     resolution: {integrity: sha512-qwOiz4Tjo8CNnrOLAYUMXeZwDzXgXpvK4TKQPmWLECM9XoWvA6+0Z2/7Ag3A4ivjS4ovbLJPbskkxioFyBhr8A==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4404,7 +4408,7 @@ packages:
     resolution: {integrity: sha512-jrBWOxZITuGcnjRCM2t2U5ZPkCLxD+Ym6DjfssS5haTj2iiak/DOb64JeN6OdLfLgptb6/e2kKR+ZuTrGoZTPA==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4413,7 +4417,7 @@ packages:
     resolution: {integrity: sha512-IGBQPtRFdhN6MQ8dbegVmBq1LVZluya3F1jWY+puIcQC3MHctRwTDSBWCkL/3ZcnMJLTMJ++Z+ktmvg0F89iCw==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4422,7 +4426,7 @@ packages:
     resolution: {integrity: sha512-d8a+bBY/FxikNPlgJJoaBHZX+zKVbWHYJGTLnLvveQgFSTntkGdEKv3JDtHrMS0DNYpllz2nRsTLGLKYttbpmw==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4431,7 +4435,7 @@ packages:
     resolution: {integrity: sha512-giWQp+4mxjBPt4KZ0MmyuykFNWfbDxKt4x+fPkRYmgRFJSbCZFzUglvMb/Kjn38tm10YP4ufiQZDx3zna4LU6w==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4441,8 +4445,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4455,111 +4459,111 @@ packages:
   '@react-pdf-viewer/attachment@3.12.0':
     resolution: {integrity: sha512-mhwrYJSIpCvHdERpLUotqhMgSjhtF+BTY1Yb9Fnzpcq3gLZP+Twp5Rynq21tCrVdDizPaVY7SKu400GkgdMfZw==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/bookmark@3.12.0':
     resolution: {integrity: sha512-i7nEit8vIFMAES8RFGwprZ9cXOOZb9ZStPW6E6yuObJEXcvBj/ctsbBJGZxqUZOGklM0JoB7sjHyxAriHfe92A==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/core@3.12.0':
     resolution: {integrity: sha512-8MsdlQJ4jaw3GT+zpCHS33nwnvzpY0ED6DEahZg9WngG++A5RMhk8LSlxdHelwaFFHFiXBjmOaj2Kpxh50VQRg==}
     peerDependencies:
-      pdfjs-dist: ^3.11.174
-      react: 19.2.6
-      react-dom: 19.2.6
+      pdfjs-dist: ^2.16.105 || ^3.0.279
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/default-layout@3.12.0':
     resolution: {integrity: sha512-K2fS4+TJynHxxCBFuIDiFuAw3nqOh4bkBgtVZ/2pGvnFn9lLg46YGLMnTXCQqtyZzzXYh696jmlFViun3is4pA==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/full-screen@3.12.0':
     resolution: {integrity: sha512-hQouJ26QUaRBCXNMU1aI1zpJn4l4PJRvlHhuE2dZYtLl37ycjl7vBCQYZW1FwnuxMWztZsY47R43DKaZORg0pg==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/get-file@3.12.0':
     resolution: {integrity: sha512-Uhq45n2RWlZ7Ec/BtBJ0WQESRciaYIltveDXHNdWvXgFdOS8XsvB+mnTh/wzm7Cfl9hpPyzfeezifdU9AkQgQg==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/open@3.12.0':
     resolution: {integrity: sha512-vhiDEYsiQLxvZkIKT9VPYHZ1BOnv46x9eCEmRWxO1DJ8fa/GRDTA9ivXmq/ap0dGEJs6t+epleCkCEfllLR/Yw==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/page-navigation@3.12.0':
     resolution: {integrity: sha512-tVEJ48Dd5kajV1nKkrPWijglJRNBiKBTyYDKVexhiRdTHUP1f6QQXiSyDgCUb0IGSZeJzOJb1h7ApKHe8OTtuw==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/print@3.12.0':
     resolution: {integrity: sha512-xJn76CgbU/M2iNaN7wLHTg+sdOekkRMfCakFLwPrE+SR7qD6NUF4vQQKJBSVCCK5bUijzb6cWfKGfo8VA72o4Q==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/properties@3.12.0':
     resolution: {integrity: sha512-dYTCHtVwFNkpDo7QxL2qk/8zAKndLwdD1FFxBftl6jIlQbtvNdxkFfkv1HcQING9Ic+7DBryOiD7W0ze4IERYg==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/rotate@3.12.0':
     resolution: {integrity: sha512-yaxaMYPChvNOjR8+AxRmj0kvojyJKPq4XHEcIB2lJJgBY1Zra3mliDUP3Nlb4yV8BS9+yBqWn9U9mtnopQD+tw==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/scroll-mode@3.12.0':
     resolution: {integrity: sha512-okII7Xqhl6cMvl1izdEvlXNJ+vJVq/qdg53hJIDYVgBCWskLk/cpjUg/ZonBxseG9lIDP3w2VO1McT8Gn11OAg==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/search@3.12.0':
     resolution: {integrity: sha512-jAkLpis49fsDDY/HrbUZIOIhzF5vynONQNA4INQKI38r/MjveblrkNv7qbr9j5lQ/WFic5+gD1e+Mtpf1/7DiA==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/selection-mode@3.12.0':
     resolution: {integrity: sha512-yysWEu2aCtBvzSgbhgI9kT5cq2hf0FU6Z+3B7MMXz14Kxyc3y18wUqxtgbvpFEfWF0bNUUq16JtWRljtxvZ83w==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/theme@3.12.0':
     resolution: {integrity: sha512-cdBi+wR1VOZ6URCcO9plmAZQu4ZGFcd7HJdBe7VIFiGyrvl9I/Of74ONLycnDImSuONt8D3uNjPBLieeaShVeg==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/thumbnail@3.12.0':
     resolution: {integrity: sha512-Vc8j3bO6wumWZV4o6pAbktPWKDSC9tQAzOCJ3cof541u4i44C11ccYC4W9aNcsMMUSO3bNwAGWtP8OFthV5akQ==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/toolbar@3.12.0':
     resolution: {integrity: sha512-qACTU3qXHgtNK8J+T13EWio+0liilj86SJ87BdapqXynhl720OKPlSKOQqskUGqg3oTUJAhrse9XG6SFdHJx+g==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf-viewer/zoom@3.12.0':
     resolution: {integrity: sha512-V0GUTyPM77+LzhoKX+T3XI10/HfGdqRTbgeP7ID60FCzcwu6kXWqJn5tzabjDKLTlFv8mJmn0aa/ppkIU97nfA==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
 
   '@react-pdf/fns@3.1.3':
     resolution: {integrity: sha512-0I7pApDr1/RLAKbizuLy/IHTEa93LSPy/bEwYniboC3Xqnp6Od8xFJKbKEzGw2wh/5zKFFwl00g4t9RwgIMc3w==}
@@ -4582,7 +4586,7 @@ packages:
   '@react-pdf/reconciler@2.0.0':
     resolution: {integrity: sha512-7zaPRujpbHSmCpIrZ+b9HSTJHthcVZzX0Wx7RzvQGsGBUbHP4p6s5itXrAIOuQuPvDepoHGNOvf6xUuMVvdoyw==}
     peerDependencies:
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   '@react-pdf/render@4.5.1':
     resolution: {integrity: sha512-IW/N4HWJWtioBXCf7n02IR24VJJ8gbdS3jGypf+vW/rSErEx3/URRzh9UK6Ma8Fpog9+T/W6GE2NHJ5AAKHhVA==}
@@ -4590,7 +4594,7 @@ packages:
   '@react-pdf/renderer@4.5.1':
     resolution: {integrity: sha512-5r1VQrE6FRLXX5wWUxwZzM24E2BJMo6g8AQWuS8WyPs9ugu5yMnb2g8/RpPYka/Z6J+RUEWc32wty2NoUJF42Q==}
     peerDependencies:
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   '@react-pdf/stylesheet@6.2.1':
     resolution: {integrity: sha512-2+UEk+7e+z8baaWi2l5kPLWmwtJeOI+T5wW9GGeN3iDH7vd3kbTqOpN1yt9mmfNVZFxQsnDHpznFb5v5UF983A==}
@@ -4607,7 +4611,7 @@ packages:
   '@reduxjs/toolkit@2.12.0':
     resolution: {integrity: sha512-KiT+RzZbp6mQET+Mg+h2c97+9j1sNflUxQkIHI7Yuzf6Peu+OYpmkn6nbHWmLLWj+1ZODUJFwGZ7gx3L9R9EOw==}
     peerDependencies:
-      react: 19.2.6
+      react: ^16.9.0 || ^17.0.0 || ^18 || ^19
       react-redux: ^7.2.1 || ^8.1.3 || ^9.0.0
     peerDependenciesMeta:
       react:
@@ -4656,66 +4660,79 @@ packages:
     resolution: {integrity: sha512-Q8CBCCQtDFrYtXoeUXSrnFXKOnyUhx6bz+SkL6A0E7V8kAiCJ5pamq1WtbfpVGhR5TSpXY6ak3avmDc5fHTyJA==}
     cpu: [arm]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-arm-musleabihf@4.61.1':
     resolution: {integrity: sha512-nwnhk1581l0FBVellGcVCAT0Oi06onEA3WB53sf01VO3I0UPBkMH9sXONYME2K0ovXcNayJfNtHfm6mpJElatQ==}
     cpu: [arm]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-arm64-gnu@4.61.1':
     resolution: {integrity: sha512-x5Xr49hwt3hdW75UOZm3395YwwzPyauktslv29KpWL/T+vVAzoT3azLcTWv0eMciBNrx+DYjH4paehHoLpPvpg==}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-arm64-musl@4.61.1':
     resolution: {integrity: sha512-unMS3H73DpaoPyyEVPjGKleM/s0mkmsauTENpw4INQY8y4+IuLNjkueQ5QCtC0D3N38Y38yhAU8OoZ20S2Tm6w==}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-loong64-gnu@4.61.1':
     resolution: {integrity: sha512-zNZzGRnAhwjFEYmvphJRV5XaQGjs62cCmeYYHUT//NbvEnHauw+I85nGG+SiVg5ld4GX8D1IbKIX+ozITQnhMQ==}
     cpu: [loong64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-loong64-musl@4.61.1':
     resolution: {integrity: sha512-LdpWGL8X209B2SIvWjqlc8VZgM6PKfontSerGepuldQmHYrAOtnMCXeJkxXGbC+PPZVOuu5czJo7fNV6aeW8rQ==}
     cpu: [loong64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-ppc64-gnu@4.61.1':
     resolution: {integrity: sha512-EC5kTtNaNGOmbMGqar8dvJy6y/hg99GAwjfBz++pxZhQATXGcRjd6c5en5wcbru0vkRmiMGsQKdMJOOf6sza4g==}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-ppc64-musl@4.61.1':
     resolution: {integrity: sha512-8hiwp6D4acEcNK78I4rP0/XtS1sknWIAMJBPdR4l6zUtyTm5KiTDr5bXmWt4foY7nAN7AThDHgkLIEZOWKbzWw==}
     cpu: [ppc64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-riscv64-gnu@4.61.1':
     resolution: {integrity: sha512-10dh/h/BqA7DuMPWSxkR8uks18FRwnwOEqr5zOTEl+NOwP/OMzKX8OFR/Of9xxDA7D5qef1Nzar5WDD2kCCr1g==}
     cpu: [riscv64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-musl@4.61.1':
     resolution: {integrity: sha512-YKJ5lg35DP17gcAOggnihe+APw9HLyj1Xn7gsmGumBJAUDa6NGXNixJzmkWLhcK9TOuuyQjdamzvJefkO7qHZQ==}
     cpu: [riscv64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-s390x-gnu@4.61.1':
     resolution: {integrity: sha512-Mlil5G2Jj6a7B3LWGctg+XPL9vdXYuzCtNXfxOQ0nPjc2m6ueUktocPGH9bnAM0bNRKb/bAWTujUU7IJQdQA+g==}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-x64-gnu@4.61.1':
     resolution: {integrity: sha512-bVWIOIk6pV01p4CdUbPP7CJ/434z+OooYjDuFcR+44N35YvKUC66G8MGnvcWx5mWKW3g61J+t74l3Kj15Kwn2Q==}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-x64-musl@4.61.1':
     resolution: {integrity: sha512-qy5pBvZbqNFheBz61R1rzsezjm0J7O2oNGoWtGoY89SZYLUfxAJTBAqDChqAIdB4rCiIbi9nF7yZ83GnNiLwSw==}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-openbsd-x64@4.61.1':
     resolution: {integrity: sha512-E83TXjI4zm0+5f2qO+UOudaCYIhYwpJ5jq6YCZNIZ+6CbfhKrkAGezeiASBL9ElxAxFsRS9ZhESv8mfnj6TKeg==}
@@ -4812,7 +4829,7 @@ packages:
   '@tabler/icons-react@3.44.0':
     resolution: {integrity: sha512-8+rvzBbVm/1Z3sG3x7GUNAaxIKxwgz8xaMhRs23nrCnMTKRFAhEC+82zAIFeAA0seXdrAGX5HFCkaLpGK2rVHg==}
     peerDependencies:
-      react: 19.2.6
+      react: '>= 16'
 
   '@tabler/icons@3.44.0':
     resolution: {integrity: sha512-Wn0AOZG9sg0L+bjfMqq4eNhC6pQjIrk94LvvWYNYkY8KH8wC3YILRzQlrnVJc4FUeMxH/AK97QsYCX35H3LndA==}
@@ -4859,24 +4876,28 @@ packages:
     engines: {node: '>= 20'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@tailwindcss/oxide-linux-arm64-musl@4.3.0':
     resolution: {integrity: sha512-Z6sukiQsngnWO+l39X4pPbiWT81IC+PLKF+PHxIlyZbGNb9MODfYlXEVlFvej5BOZInWX01kVyzeLvHsXhfczQ==}
     engines: {node: '>= 20'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@tailwindcss/oxide-linux-x64-gnu@4.3.0':
     resolution: {integrity: sha512-DRNdQRpSGzRGfARVuVkxvM8Q12nh19l4BF/G7zGA1oe+9wcC6saFBHTISrpIcKzhiXtSrlSrluCfvMuledoCTQ==}
     engines: {node: '>= 20'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@tailwindcss/oxide-linux-x64-musl@4.3.0':
     resolution: {integrity: sha512-Z0IADbDo8bh6I7h2IQMx601AdXBLfFpEdUotft86evd/8ZPflZe9COPO8Q1vw+pfLWIUo9zN/JGZvwuAJqduqg==}
     engines: {node: '>= 20'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@tailwindcss/oxide-wasm32-wasi@4.3.0':
     resolution: {integrity: sha512-HNZGOUxEmElksYR7S6sC5jTeNGpobAsy9u7Gu0AskJ8/20FR9GqebUyB+HBcU/ax6BHuiuJi+Oda4B+YX6H1yA==}
@@ -4925,32 +4946,32 @@ packages:
     resolution: {integrity: sha512-cpZA0+WqKXwrwMfiWZEGGF6QrIWVQFbhBtxqDF5sQsAfrFf47HIE6fiPbQU3wyAUEN2+7UNqLCQe7oG6m3f93w==}
     peerDependencies:
       '@tanstack/react-query': ^5.101.0
-      react: 19.2.6
+      react: ^18 || ^19
 
   '@tanstack/react-query@5.101.0':
     resolution: {integrity: sha512-rLlJXSpkqfizLWgkR5+eLeIk0MvTx/meEIR7LRjxic+qxiQP8zVjq7BqQkiCMNLQBlLfuOLqqr6KO5GtrDlmSg==}
     peerDependencies:
-      react: 19.2.6
+      react: ^18 || ^19
 
   '@tanstack/react-table@8.20.5':
     resolution: {integrity: sha512-WEHopKw3znbUZ61s9i0+i9g8drmDo6asTWbrQh8Us63DAk/M0FkmIqERew6P71HI75ksZ2Pxyuf4vvKh9rAkiA==}
     engines: {node: '>=12'}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8'
+      react-dom: '>=16.8'
 
   '@tanstack/react-table@8.21.3':
     resolution: {integrity: sha512-5nNMTSETP4ykGegmVkhjcS8tTLW6Vl4axfEGQN3v0zdHYbK4UfoqfPChclTrJ4EoK9QynqAu9oUf8VEmrpZ5Ww==}
     engines: {node: '>=12'}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8'
+      react-dom: '>=16.8'
 
   '@tanstack/react-virtual@3.11.2':
     resolution: {integrity: sha512-OuFzMXPF4+xZgx8UzJha0AieuMihhhaWG0tCqpp6tDzlFwOmNBPYMuLOtMJ1Tr4pXLHmgjcWhG6RlknY2oNTdQ==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   '@tanstack/table-core@8.20.5':
     resolution: {integrity: sha512-P9dF7XbibHph2PFRz8gfBKEXEY/HJPOhym8CHmjF8y3q5mWpKx9xtZapXQUWCgkqvsK0R46Azuz+VaxD4Xl+Tg==}
@@ -4966,8 +4987,8 @@ packages:
   '@tinymce/tinymce-react@6.3.0':
     resolution: {integrity: sha512-E++xnn0XzDzpKr40jno2Kj7umfAE6XfINZULEBBeNjTMvbACWzA6CjiR6V8eTDc9yVmdVhIPqVzV4PqD5TZ/4g==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^19.0.0 || ^18.0.0 || ^17.0.1 || ^16.7.0
+      react-dom: ^19.0.0 || ^18.0.0 || ^17.0.1 || ^16.7.0
       tinymce: ^8.0.0 || ^7.0.0 || ^6.0.0 || ^5.5.1
     peerDependenciesMeta:
       tinymce:
@@ -4997,7 +5018,7 @@ packages:
       '@nestjs/typeorm': ^11.0.0
       reflect-metadata: ^0.2.0
       rxjs: ^7.8.0
-      typeorm: 0.3.30
+      typeorm: ^0.3.0
 
   '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz':
     resolution: {integrity: sha512-rfHSXOm/0VUMTj7HrvYysrEAqxItqfPs4Rd35qWJyaAk+snF1wTKFRVz6cRGPoQNj8fhplkVAefnvuKBuHT+xQ==, tarball: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz}
@@ -5019,15 +5040,15 @@ packages:
       class-validator: ^0.14.1
       reflect-metadata: ^0.2.0
       rxjs: ^7.8.0
-      typeorm: 0.3.30
+      typeorm: ^0.3.0
 
   '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz':
     resolution: {integrity: sha512-FTihoH0lIqKV/0s+FTJZokQw8xX3XztXIqT8eEYEZgDM2xyzVSCHY8pHCUxw0MQtiR8R97zxZJ/o192eWt+E/g==, tarball: file:local-packages/tria-plc-iamui-0.1.1.tgz}
     version: 0.1.1
     engines: {node: '>=18'}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^18.3.1 || ^19.0.0
+      react-dom: ^18.3.1 || ^19.0.0
 
   '@ts-morph/common@0.27.0':
     resolution: {integrity: sha512-Wf29UqxWDpc+i61k3oIOzcUfQt79PIT9y/MWfAGlrkjg6lBC1hwDECLXPVJAhWjiGbfBCxZd65F/LIZF3+jeJQ==}
@@ -5476,51 +5497,61 @@ packages:
     resolution: {integrity: sha512-zJc0H99FEPoFfSrNpa91HYfxzfAJCr502oxNK1cfdC9hlaFI43RT+JFCann9JUgZmLzzntChHyn13Sgn9ljHNg==}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@unrs/resolver-binding-linux-arm64-musl@1.12.2':
     resolution: {integrity: sha512-KQ3Lki6l+Pz1k/eBipN41ES+YUK30beLGb9YqcB1O542cyLCNE6GaxrfcY3T6EezmGGk84wb5XyO9loTM9tkcA==}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@unrs/resolver-binding-linux-loong64-gnu@1.12.2':
     resolution: {integrity: sha512-3SJGEh1DborhG6pyxvhPzCT4bbSIVihsvgJc13P1bHG7KLdNDaF9T3gsTwFc7Jw/5Y5/iWOjkEx7Zy0NvCGX3Q==}
     cpu: [loong64]
     os: [linux]
+    libc: [glibc]
 
   '@unrs/resolver-binding-linux-loong64-musl@1.12.2':
     resolution: {integrity: sha512-jiuG/Obbel7uw1PwHNFfrkiKhLAF6mnyZ6aWlOAVN9WqKm8v0OFGnciJIHu8+CMvXLQ8AD51LPzAoUfT21D5Ew==}
     cpu: [loong64]
     os: [linux]
+    libc: [musl]
 
   '@unrs/resolver-binding-linux-ppc64-gnu@1.12.2':
     resolution: {integrity: sha512-q7xRvVpmcfeL+LlZg8Pbbo6QaTZwDU5BaGZbwfhkEsXJn3Was8xYfE0RBH266xZt0rM6B7i8xAYIvjthuUIWHg==}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
 
   '@unrs/resolver-binding-linux-riscv64-gnu@1.12.2':
     resolution: {integrity: sha512-0CVdx6lcnT3Q9inOH8tsMIOJ6ImndllMjqJHg8RLVdB7Vq4SfkEXl9mCSsVNuNA4MCYycRicCUxPCabVHJRr6A==}
     cpu: [riscv64]
     os: [linux]
+    libc: [glibc]
 
   '@unrs/resolver-binding-linux-riscv64-musl@1.12.2':
     resolution: {integrity: sha512-iOwlRo9vnp6R6ohHQS11n0NnfdXx/omhkocmIfaPRpQhKZ+3BDMkkdRVh53qjkFkpPddf+FETA28NwGN7l5l+w==}
     cpu: [riscv64]
     os: [linux]
+    libc: [musl]
 
   '@unrs/resolver-binding-linux-s390x-gnu@1.12.2':
     resolution: {integrity: sha512-HYJtLfXq94q8iZNFT1lknx258wlkkWhZeUXJRqzKBBUJ00CvZ+N33zgbCqimLjsyw5Va6uUxhVa12mI+kaveEw==}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
 
   '@unrs/resolver-binding-linux-x64-gnu@1.12.2':
     resolution: {integrity: sha512-mPsUhunKKDih5O96Y6enDQyHc1SqBPlY1E/SfMWDM3EdJ95Z9CArPeCVwCCqbP45ljvivdEk8Fxn+SIb1rDAJQ==}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@unrs/resolver-binding-linux-x64-musl@1.12.2':
     resolution: {integrity: sha512-azrt6+5ydLd8Vt210AAFis/lZevSfPw93EJRIJG+xPu4WCJ8K0kppCTpMyLPcKT7H15M4Jnt2tMp5bOvCkRC6A==}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@unrs/resolver-binding-openharmony-arm64@1.12.2':
     resolution: {integrity: sha512-YZ9hP4O0X9PQb8eO980qmLNGH4zT3I9+SZTdt0Pr0YyuGQhYKoOZkV02VzrzyOZJ5xIJ3UFIenKkUkGg8GjgWQ==}
@@ -5550,8 +5581,8 @@ packages:
   '@vis.gl/react-google-maps@1.8.3':
     resolution: {integrity: sha512-DW7nEuvOJ299DmdBnvGiUARrgS/+sTEO1iJgG9J8YaErZqLoq7S4TJ22f3EjJvR4dti4L4gft43JEK77nnKXDw==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0 || ^19.0 || ^19.0.0-rc'
+      react-dom: '>=16.8.0 || ^19.0 || ^19.0.0-rc'
 
   '@vitejs/plugin-react@4.7.0':
     resolution: {integrity: sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==}
@@ -5646,9 +5677,6 @@ packages:
     resolution: {integrity: sha512-E+iruNOY8VV9s4JEbe1aNEm6MiszPRr/UfcHMz0TQh1BXSxHK+ASV1R6W4HpjBhSeS+54PIsAMCBmwD06LLsqQ==}
     hasBin: true
 
-  abbrev@1.1.1:
-    resolution: {integrity: sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==}
-
   abort-controller@3.0.0:
     resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==}
     engines: {node: '>=6.5'}
@@ -5929,9 +5957,6 @@ packages:
   append-field@1.0.0:
     resolution: {integrity: sha512-klpgFSWLW1ZEs8svjfb7g4qWY0YS5imI82dTg+QahUvJ8YqAY0P10Uk8tTyh9ZGuYEZEMaeJYCF5BFuX552hsw==}
 
-  aproba@2.1.0:
-    resolution: {integrity: sha512-tLIEcj5GuR2RSTnxNKdkK0dJ/GrC7P38sUkiDmDuHfsHmbagTFAxDVIBltoklXEVIQ/f14IL8IMJ5pn9Hez1Ew==}
-
   arch@2.2.0:
     resolution: {integrity: sha512-Of/R0wqp83cgHozfIYLbBMnej79U/SVGOOyuB3VVFv1NRM/PSFMK12x9KVtiYzJqmnU5WR2qp0Z5rHb7sWGnFQ==}
 
@@ -5947,11 +5972,6 @@ packages:
     resolution: {integrity: sha512-+25nxyyznAXF7Nef3y0EbBeqmGZgeN/BxHX29Rs39djAfaFalmQ89SE6CWyDCHzGL0yt/ycBtNOmGTW0FyGWNw==}
     engines: {node: '>= 10'}
 
-  are-we-there-yet@2.0.0:
-    resolution: {integrity: sha512-Ci/qENmwHnsYo9xKIcUJN5LeDKdJ6R1Z1j9V/J5wyq8nh/mYPEpIKJbBZXtZjG04HiK7zV/p6Vs9952MrMeUIw==}
-    engines: {node: '>=10'}
-    deprecated: This package is no longer supported.
-
   arg@4.1.3:
     resolution: {integrity: sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==}
 
@@ -6426,10 +6446,6 @@ packages:
   caniuse-lite@1.0.30001797:
     resolution: {integrity: sha512-l8xKG+gwAIExZGl9FrF7KUwuOmk6wbEPC9Xoy/RtnWv1XG0Q4LFlagaLpUv3Kiza3W/wm27zy0yWJEieYKAP6w==}
 
-  canvas@2.11.2:
-    resolution: {integrity: sha512-ItanGBMrmRV7Py2Z+Xhs7cT+FNt5K0vPL4p9EZ/UX/Mu7hFbkxSjKF2KVtPwX7UYWp7dRKnrTvReflgrItJbdw==}
-    engines: {node: '>=6'}
-
   canvg@3.0.11:
     resolution: {integrity: sha512-5ON+q7jCTgMp9cjpu4Jo6XbvfYwSB2Ow3kzHKfIyJfaCAOHLbdKPQqGKgfED/R5B+3TFFfe8pegYA+b423SRyA==}
     engines: {node: '>=10.0.0'}
@@ -6497,10 +6513,6 @@ packages:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
 
-  chownr@2.0.0:
-    resolution: {integrity: sha512-bIomtDF5KGpdogkLd9VspvFzk9KfpyyGlS8YFVZl7TGPBHL5snIOnxeshwVgPteQ9b4Eydl+pVbIyE1DcvCWgQ==}
-    engines: {node: '>=10'}
-
   chrome-trace-event@1.0.4:
     resolution: {integrity: sha512-rNjApaLzuwaOTjCiT8lSDdGN1APCiqkChLMJxJPWLunPAt5fy8xgU9/jNOchV84wfIxrA0lRQB7oCT8jrn/wrQ==}
     engines: {node: '>=6.0'}
@@ -6619,8 +6631,8 @@ packages:
   cmdk@1.1.1:
     resolution: {integrity: sha512-Vsv7kFaXm+ptHDMZ7izaRsP70GgrW9NBNGswt9OZaVBLlE0SNpDq8eu/VGXyF9r7M0azK3Wy7OlYXsuyYLFzHg==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^18 || ^19 || ^19.0.0-rc
+      react-dom: ^18 || ^19 || ^19.0.0-rc
 
   co@4.6.0:
     resolution: {integrity: sha512-QVb0dM5HvG+uaxitm8wONl7jltx8dqhfU33DcqtOZcLSVIKSDDLDi7+0LbAKiyI8hD9u42m2YxXSkMGWThaecQ==}
@@ -6662,10 +6674,6 @@ packages:
     resolution: {integrity: sha512-Bb6Cq8oq0IjDOe8wJmi4JeNn763Xs9cfrBcaylK1tPypWzyoy2G3l90v9k64kjphl/ZJjPIShFztenRomi8WTg==}
     engines: {node: '>=18'}
 
-  color-support@1.1.3:
-    resolution: {integrity: sha512-qiBjkpbMLO/HL68y+lh4q0/O1MZFj2RX6X/KmMa3+gJD3z+WwI1ZzDHysvqHGS3mP6mznPckpXmw1nI9cJjyRg==}
-    hasBin: true
-
   colorette@2.0.20:
     resolution: {integrity: sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==}
 
@@ -6741,9 +6749,6 @@ packages:
     resolution: {integrity: sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==}
     engines: {node: ^14.18.0 || >=16.10.0}
 
-  console-control-strings@1.1.0:
-    resolution: {integrity: sha512-ty/fTekppD2fIwRvnZAVdeOiGd1c7YXEixbgJTNzqcxJWKQnjJ/V1bNEEE6hygpM3WjwHFUVK6HTjWSzV4a8sQ==}
-
   content-disposition@0.5.4:
     resolution: {integrity: sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==}
     engines: {node: '>= 0.6'}
@@ -7014,6 +7019,9 @@ packages:
   date-fns@3.6.0:
     resolution: {integrity: sha512-fRHTG8g/Gif+kSh50gaGEdToemgfj74aRX3swtiouboip5JDLAyDE9F11nHMIcvOaXeOC6D7SpNhi7uFyB7Uww==}
 
+  date-fns@4.4.0:
+    resolution: {integrity: sha512-+1UMbeh68lH1SegH83CGWwpb6OHHbpSgr3+s5Eww5M4CAgswBpoWS0AjTOfEJ33HiYKz1hdj/KTFprzXHmq/6w==}
+
   date.js@0.3.3:
     resolution: {integrity: sha512-HgigOS3h3k6HnW011nAb43c5xx5rBXk8P2v/WIT9Zv4koIaVXiH2BURguI78VVp+5Qc076T7OR378JViCnZtBw==}
 
@@ -7070,10 +7078,6 @@ packages:
     resolution: {integrity: sha512-FqUYQ+8o158GyGTrMFJms9qh3CqTKvAqgqsTnkLI8sKu0028orqBhxNMFkFen0zGyg6epACD32pjVk58ngIErQ==}
     engines: {node: '>=0.10'}
 
-  decompress-response@4.2.1:
-    resolution: {integrity: sha512-jOSne2qbyE+/r8G1VU+G/82LBs2Fs4LAsTiLSHOCOMZQl2OKZ6i8i4IyHemTe+/yIXOtTcRQMzPcgyhoFlqPkw==}
-    engines: {node: '>=8'}
-
   dedent@1.7.2:
     resolution: {integrity: sha512-WzMx3mW98SN+zn3hgemf4OzdmyNhhhKz5Ay0pUfQiMQ3e1g+xmTJWp/pKdwKVXhdSkAEGIIzqeuWrL3mV/AXbA==}
     peerDependencies:
@@ -7151,9 +7155,6 @@ packages:
     resolution: {integrity: sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==}
     engines: {node: '>=0.4.0'}
 
-  delegates@1.0.0:
-    resolution: {integrity: sha512-bd2L678uiWATM6m5Z1VzNCErI3jiGzt6HGY8OVICs40JQq/HALfbyNJmp0UDakEY4pMMaN0Ly5om/B1VI/+xfQ==}
-
   depd@2.0.0:
     resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==}
     engines: {node: '>= 0.8'}
@@ -7271,7 +7272,7 @@ packages:
   downshift@7.6.2:
     resolution: {integrity: sha512-iOv+E1Hyt3JDdL9yYcOgW7nZ7GQ2Uz6YbggwXvKUSleetYhU2nXD482Rz6CzvM4lvI1At34BYruKAL4swRGxaA==}
     peerDependencies:
-      react: 19.2.6
+      react: '>=16.12.0'
 
   dunder-proto@1.0.1:
     resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
@@ -7965,8 +7966,8 @@ packages:
     resolution: {integrity: sha512-uaBd3qC1v3KQqBEjwTUd183K6PbS+j0yR9w9VmEOLWA/tnUcSn8Xa3uck7t4dgpDoUss8xQTcj8W2L07lrnLFg==}
     peerDependencies:
       '@emotion/is-prop-valid': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@emotion/is-prop-valid':
         optional: true
@@ -8002,10 +8003,6 @@ packages:
     resolution: {integrity: sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ==}
     engines: {node: '>=10'}
 
-  fs-minipass@2.1.0:
-    resolution: {integrity: sha512-V/JgOLFCS+R6Vcq0slCuaeWEdNC3ouDlJMNIsacH2VtALiu9mV4LPrHc5cDl8k5aw6J8jwgWWpiTo5RYhmIzvg==}
-    engines: {node: '>= 8'}
-
   fs-monkey@1.1.0:
     resolution: {integrity: sha512-QMUezzXWII9EV5aTFXW1UBVUO77wYPpjqIF8/AviUCThNeSYZykpoTixUeaNNBwmCev0AMDWMAni+f8Hxb1IFw==}
 
@@ -8040,11 +8037,6 @@ packages:
   fuzzysort@3.1.0:
     resolution: {integrity: sha512-sR9BNCjBg6LNgwvxlBd0sBABvQitkLzoVY9MYYROQVX/FvfJ4Mai9LsGhDgd8qYdds0bY77VzYd5iuB+v5rwQQ==}
 
-  gauge@3.0.2:
-    resolution: {integrity: sha512-+5J6MS/5XksCuXq++uFRsnUd7Ovu1XenbeuIuNRJxYWjgQbPuFhT14lAvsWfqfAmnwluf1OwMjz39HjfLPci0Q==}
-    engines: {node: '>=10'}
-    deprecated: This package is no longer supported.
-
   generator-function@2.0.1:
     resolution: {integrity: sha512-SFdFmIJi+ybC0vjlHN0ZGVGHc3lgE0DxPAT0djjVg+kjOnSqclqmj0KQ7ykTOLP6YxoqOvuAODGdcHJn+43q3g==}
     engines: {node: '>= 0.4'}
@@ -8246,9 +8238,6 @@ packages:
     resolution: {integrity: sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==}
     engines: {node: '>= 0.4'}
 
-  has-unicode@2.0.1:
-    resolution: {integrity: sha512-8Rf9Y83NBReMnx0gFzA8JImQACstCYWUplepDa9xprwwtmgEZUF0h/i5xSA625zB/I37EtrswSST6OXxwaaIJQ==}
-
   has-value@0.3.1:
     resolution: {integrity: sha512-gpG936j8/MzaeID5Yif+577c17TxaDmhuyVgSwtnL/q8UUTySg8Mecb+8Cf1otgLoD7DDH75axp86ER7LFsf3Q==}
     engines: {node: '>=0.10.0'}
@@ -8483,8 +8472,8 @@ packages:
   input-format@0.3.14:
     resolution: {integrity: sha512-gHMrgrbCgmT4uK5Um5eVDUohuV9lcs95ZUUN9Px2Y0VIfjTzT2wF8Q3Z4fwLFm7c5Z2OXCm53FHoovj6SlOKdg==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=18.1.0'
+      react-dom: '>=18.1.0'
     peerDependenciesMeta:
       react:
         optional: true
@@ -9290,24 +9279,28 @@ packages:
     engines: {node: '>= 12.0.0'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   lightningcss-linux-arm64-musl@1.32.0:
     resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
     engines: {node: '>= 12.0.0'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   lightningcss-linux-x64-gnu@1.32.0:
     resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   lightningcss-linux-x64-musl@1.32.0:
     resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   lightningcss-win32-arm64-msvc@1.32.0:
     resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
@@ -9354,7 +9347,7 @@ packages:
   little-state-machine@4.8.1:
     resolution: {integrity: sha512-liPHqaWMQ7rzZryQUDnbZ1Gclnnai3dIyaJ0nAgwZRXMzqbYrydrlCI0NDojRUbE5VYh5vu6hygEUZiH77nQkQ==}
     peerDependencies:
-      react: 19.2.6
+      react: ^16.8.0 || ^17 || ^18 || ^19
 
   load-esm@1.0.3:
     resolution: {integrity: sha512-v5xlu8eHD1+6r8EHTg6hfmO97LN8ugKtiXcy5e6oN72iD2r6u0RPfLl6fxM+7Wnh2ZRq15o0russMst44WauPA==}
@@ -9545,17 +9538,17 @@ packages:
   lucide-react@0.446.0:
     resolution: {integrity: sha512-BU7gy8MfBMqvEdDPH79VhOXSEgyG8TSPOKWaExWGCQVqnGH7wGgDngPbofu+KdtVjPQBWbEmnfMTq90CTiiDRg==}
     peerDependencies:
-      react: 19.2.6
+      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0-rc
 
   lucide-react@0.513.0:
     resolution: {integrity: sha512-CJZKq2g8Y8yN4Aq002GahSXbG2JpFv9kXwyiOAMvUBv7pxeOFHUWKB0mO7MiY4ZVFCV4aNjv2BJFq/z3DgKPQg==}
     peerDependencies:
-      react: 19.2.6
+      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   lucide-react@1.17.0:
     resolution: {integrity: sha512-9FA9evdox/JQL5PT57fdA1x/yg8T7knJ98+zjTL3UfKza6pflQUUh3XtaQIHKvnsJw1lmsEyHVlt5jchYxOQ5w==}
     peerDependencies:
-      react: 19.2.6
+      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   luxon@3.7.2:
     resolution: {integrity: sha512-vtEhXh/gNjI9Yg1u4jX/0YVPMvxzHuGgCm6tC5kZyb08yjGWGnqAjGJvcXbqQR2P3MyMEFnRbpcdFS6PBcLqew==}
@@ -9570,10 +9563,6 @@ packages:
   make-cancellable-promise@2.0.0:
     resolution: {integrity: sha512-3SEQqTpV9oqVsIWqAcmDuaNeo7yBO3tqPtqGRcKkEo0lrzD3wqbKG9mkxO65KoOgXqj+zH2phJ2LiAsdzlogSw==}
 
-  make-dir@3.1.0:
-    resolution: {integrity: sha512-g3FeP20LNwhALb/6Cz6Dd4F2ngze0jz7tbzrD2wAV+o9FeNHe4rL+yK2md0J/fiSf1sa1ADhXqi5+oVwOM/eGw==}
-    engines: {node: '>=8'}
-
   make-dir@4.0.0:
     resolution: {integrity: sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==}
     engines: {node: '>=10'}
@@ -9597,8 +9586,8 @@ packages:
       '@tabler/icons-react': '>=2.23.0'
       clsx: '>=2'
       dayjs: '>=1.11'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=18.0'
+      react-dom: '>=18.0'
 
   map-cache@0.2.2:
     resolution: {integrity: sha512-8y/eV9QQZCiyn1SprXSrCmqJN0yNRATe+PO8ztwqrvrbdRLA3eYJF0yaR0YayLWkMbsQSKWS9N2gPcGEc4UsZg==}
@@ -9859,10 +9848,6 @@ packages:
     resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
     engines: {node: '>=18'}
 
-  mimic-response@2.1.0:
-    resolution: {integrity: sha512-wXqjST+SLt7R009ySCglWBCFpjUygmCIfD790/kVbiGmUgfYGuB14PiTd5DwVxSV4NcYHjzMkoj5LjQZwTQLEA==}
-    engines: {node: '>=8'}
-
   minimatch@10.2.5:
     resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==}
     engines: {node: 18 || 20 || >=22}
@@ -9885,22 +9870,10 @@ packages:
     resolution: {integrity: sha512-xPrLjWkTT5E7H7VnzOjF//xBp9I40jYB4aWhb2xTFopXXfw+Wo82DDWngdUju7Doy3Wk7R8C4LAgwhLHHnf0wA==}
     engines: {node: ^16 || ^18 || >=20}
 
-  minipass@3.3.6:
-    resolution: {integrity: sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==}
-    engines: {node: '>=8'}
-
-  minipass@5.0.0:
-    resolution: {integrity: sha512-3FnjYuehv9k6ovOEbyOswadCDPX1piCfhV8ncmYtHOjuPwylVWsghTLo7rabjC3Rx5xD4HDx8Wm1xnMF7S5qFQ==}
-    engines: {node: '>=8'}
-
   minipass@7.1.3:
     resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==}
     engines: {node: '>=16 || 14 >=14.17'}
 
-  minizlib@2.1.2:
-    resolution: {integrity: sha512-bAxsR8BVfj60DWXHE3u30oHzfl4G7khkSuPW+qvpd7jFRHm7dLxOjUk1EHACJ/hxLY8phGJ0YhYHZo7jil7Qdg==}
-    engines: {node: '>= 8'}
-
   mitt@3.0.1:
     resolution: {integrity: sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==}
 
@@ -9912,11 +9885,6 @@ packages:
     resolution: {integrity: sha512-FP+p8RB8OWpF3YZBCrP5gtADmtXApB5AMLn+vdyA+PyxCjrCs00mjyUozssO33cwDeT3wNGdLxJ5M//YqtHAJw==}
     hasBin: true
 
-  mkdirp@1.0.4:
-    resolution: {integrity: sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==}
-    engines: {node: '>=10'}
-    hasBin: true
-
   moment@2.30.1:
     resolution: {integrity: sha512-uEmtNhbDOrWPFS+hdjFCBfy9f2YoyzRpwcl+DqpC6taX21FzsTLQVbMV/W7PzNSX6x/bhC1zA3c2UQ5NzH6how==}
 
@@ -9954,9 +9922,9 @@ packages:
       '@mui/icons-material': ^5.11.16
       '@mui/material': ^5.13.3
       '@mui/x-date-pickers': ^6.7.0
-      date-fns: ^3.6.0
-      react: 19.2.6
-      react-dom: 19.2.6
+      date-fns: ^2.30.0
+      react: ^18.2.0
+      react-dom: ^18.2.0
 
   multer@2.1.1:
     resolution: {integrity: sha512-mo+QTzKlx8R7E5ylSXxWzGoXoZbOsRMpyitcht8By2KHvMbf3tjwosZ/Mu/XYU6UuJ3VZnODIrak5ZrPiPyB6A==}
@@ -9976,9 +9944,6 @@ packages:
   mz@2.7.0:
     resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==}
 
-  nan@2.28.0:
-    resolution: {integrity: sha512-fTsDz99OTq2sVePhGdp4qQhggZFtKr64ZNVyVajRKtMOkJxYekplBh577PiJB12v/D3s2E5cGtOI45LWp6rnLQ==}
-
   nanoid@3.3.12:
     resolution: {integrity: sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
@@ -10020,8 +9985,8 @@ packages:
   next-themes@0.4.6:
     resolution: {integrity: sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
 
   next@14.2.35:
     resolution: {integrity: sha512-KhYd2Hjt/O1/1aZVX3dCwGXM1QmOV4eNM2UTacK5gipDdPN/oHHK/4oVGy7X8GMfPMsUTUEmGlsy0EY1YGAkig==}
@@ -10030,8 +9995,8 @@ packages:
     peerDependencies:
       '@opentelemetry/api': ^1.1.0
       '@playwright/test': ^1.41.2
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^18.2.0
+      react-dom: ^18.2.0
       sass: ^1.3.0
     peerDependenciesMeta:
       '@opentelemetry/api':
@@ -10069,15 +10034,6 @@ packages:
   node-fetch-native@1.6.7:
     resolution: {integrity: sha512-g9yhqoedzIUm0nTnTqAQvueMPVOuIY16bqgAJJC8XOOubYFNwz6IER9qs0Gq2Xd0+CecCKFjtdDTMA4u4xG06Q==}
 
-  node-fetch@2.7.0:
-    resolution: {integrity: sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==}
-    engines: {node: 4.x || >=6.0.0}
-    peerDependencies:
-      encoding: ^0.1.0
-    peerDependenciesMeta:
-      encoding:
-        optional: true
-
   node-fetch@3.3.2:
     resolution: {integrity: sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
@@ -10100,11 +10056,6 @@ packages:
     resolution: {integrity: sha512-Uzmd6LXpouKo8EUK68IjH4+E01w/hXyV3R3g/geCJo+rXLNfh1xucB+LOzYEOQPSiUK3h/xZf0cQGcSsmyL2Og==}
     engines: {node: '>=18'}
 
-  nopt@5.0.0:
-    resolution: {integrity: sha512-Tbj67rffqceeLpcRXrT7vKAN8CwfPeIBgM7E6iBkmKLV7bEMwpGgYLGv0jACUsECaa/vuxP0IjEont6umdMgtQ==}
-    engines: {node: '>=6'}
-    hasBin: true
-
   normalize-path@3.0.0:
     resolution: {integrity: sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==}
     engines: {node: '>=0.10.0'}
@@ -10124,10 +10075,6 @@ packages:
     resolution: {integrity: sha512-9qny7Z9DsQU8Ou39ERsPU4OZQlSTP47ShQzuKZ6PRXpYLtIFgl/DEBYEXKlvcEa+9tHVcK8CF81Y2V72qaZhWA==}
     engines: {node: '>=18'}
 
-  npmlog@5.0.1:
-    resolution: {integrity: sha512-AqZtDUWOMKs1G/8lwylVjrdYgqA4d9nu8hc+0gzRxlDb1I10+FHBGMXs6aiQHFdCUUlqH99MUMuLfzWDNDtfxw==}
-    deprecated: This package is no longer supported.
-
   nth-check@2.1.1:
     resolution: {integrity: sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==}
 
@@ -10395,10 +10342,6 @@ packages:
     resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==}
     engines: {node: '>=8'}
 
-  path2d-polyfill@2.0.1:
-    resolution: {integrity: sha512-ad/3bsalbbWhmBo0D6FZ4RNMwsLsPpL6gnvhuSaU5Vm7b06Kr5ubSltQQ0T7YKsiJQO+g22zJ4dJKNTXIyOXtA==}
-    engines: {node: '>=8'}
-
   path@0.12.7:
     resolution: {integrity: sha512-aXXC6s+1w7otVF9UletFkFcDsJeO7lSZBPUQhtb5O0xJe8LtYhj/GxldoL09bBj9+ZmE2hNoHqQSFMN5fikh4Q==}
 
@@ -10418,10 +10361,6 @@ packages:
   pdf-lib@1.17.1:
     resolution: {integrity: sha512-V/mpyJAoTsN4cnP31vc0wfNA1+p20evqqnap0KLoRUN0Yk/p3wN52DOEsL4oBFcLdb76hlpKPtzJIgo67j/XLw==}
 
-  pdfjs-dist@3.11.174:
-    resolution: {integrity: sha512-TdTZPf1trZ8/UFu5Cx/GXB7GZM30LT+wWUNfsi6Bq8ePLnb+woNKtDymI2mxZYBpMbonNFqKmiz684DIfnd8dA==}
-    engines: {node: '>=18'}
-
   pdfjs-dist@5.4.296:
     resolution: {integrity: sha512-DlOzet0HO7OEnmUmB6wWGJrrdvbyJKftI1bhMitK7O2N8W2gc757yyYBbINy9IDafXAV9wmKr9t7xsTaNKRG5Q==}
     engines: {node: '>=20.16.0 || >=22.3.0'}
@@ -10721,7 +10660,7 @@ packages:
   qrcode.react@3.2.0:
     resolution: {integrity: sha512-YietHHltOHA4+l5na1srdaMx4sVSOjV9tamHs+mwiLWAMr6QVACRUw1Neax5CptFILcNoITctJY0Ipyn5enQ8g==}
     peerDependencies:
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0
 
   qrcode@1.5.4:
     resolution: {integrity: sha512-1ca71Zgiu6ORjHqFBDpnSMTR2ReToX4l1Au1VFLyVeBTFavzQnv5JxMFr3ukHVKpSrSA2MCk0lNJSykjUfz7Zg==}
@@ -10761,8 +10700,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -10796,55 +10735,60 @@ packages:
   react-cookie@8.1.2:
     resolution: {integrity: sha512-S45Z1y1dHyYfLEI4bFKQICuP+SwJqTPWbdc2ZpE6aQSdjSVJAjUDfwTPq8B7BWieIsgyyEWMb/QOrudtwJMjXA==}
     peerDependencies:
-      react: 19.2.6
+      react: '>= 16.3.0'
 
   react-css-nocode-editor@1.0.13:
     resolution: {integrity: sha512-RV1ZbG8aXORiQ5mDKZbKCHStCJPamp/n5Rb34q22Ug2xzMDW4DjjqO23+Qo/Y+LAoyyrFV/+lI1qq4+/O5nf2A==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8.0 <= 18.1'
+      react-dom: '>=16.8.0 <= 18.1'
 
   react-day-picker@8.10.2:
     resolution: {integrity: sha512-LK68OTbHB3oJNhl9cA0qVizzp3o26w61YSjAFkYi67N86iro32wx86kSNeFU/hq+gI8m1yzWhnomMLfZ041RzQ==}
     peerDependencies:
-      date-fns: ^3.6.0
-      react: 19.2.6
+      date-fns: ^2.28.0 || ^3.0.0
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   react-day-picker@9.14.0:
     resolution: {integrity: sha512-tBaoDWjPwe0M5pGrum4H0SR6Lyk+BO9oHnp9JbKpGKW2mlraNPgP9BMfsg5pWpwrssARmeqk7YBl2oXutZTaHA==}
     engines: {node: '>=18'}
     peerDependencies:
-      react: 19.2.6
+      react: '>=16.8.0'
+
+  react-dom@18.3.1:
+    resolution: {integrity: sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==}
+    peerDependencies:
+      react: ^18.3.1
 
   react-dom@19.2.6:
     resolution: {integrity: sha512-0prMI+hvBbPjsWnxDLxlCGyM8PN6UuWjEUCYmZhO67xIV9Xasa/r/vDnq+Xyq4Lo27g8QSbO5YzARu0D1Sps3g==}
     peerDependencies:
-      react: 19.2.6
+      react: ^19.2.6
 
   react-dropzone@14.4.1:
     resolution: {integrity: sha512-QDuV76v3uKbHiH34SpwifZ+gOLi1+RdsCO1kl5vxMT4wW8R82+sthjvBw4th3NHF/XX6FBsqDYZVNN+pnhaw0g==}
     engines: {node: '>= 10.13'}
     peerDependencies:
-      react: 19.2.6
+      react: '>= 16.8 || 18.0.0'
 
   react-hook-form@7.77.0:
     resolution: {integrity: sha512-Sslh9YDYc0GDlWT/lxasnIduNo4v3yyvqRGvmGKUre5AFjDs/HV9/OafHGD8d+sB2yoL4UIL9L8X9i0WlZZebg==}
     engines: {node: '>=18.0.0'}
     peerDependencies:
-      react: 19.2.6
+      react: ^16.8.0 || ^17 || ^18 || ^19
 
   react-hot-toast@2.6.0:
     resolution: {integrity: sha512-bH+2EBMZ4sdyou/DPrfgIouFpcRLCJ+HoCA32UoAYHn6T3Ur5yfcDCeSr5mwldl6pFOsiocmrXMuoCJ1vV8bWg==}
     engines: {node: '>=10'}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16'
+      react-dom: '>=16'
 
   react-i18next@15.7.4:
     resolution: {integrity: sha512-nyU8iKNrI5uDJch0z9+Y5XEr34b0wkyYj3Rp+tfbahxtlswxSCjcUL9H0nqXo9IR3/t5Y5PKIA3fx3MfUyR9Xw==}
     peerDependencies:
       i18next: '>= 23.4.0'
-      react: 19.2.6
+      react: '>= 16.8.0'
       react-dom: '*'
       react-native: '*'
       typescript: ^5
@@ -10860,7 +10804,7 @@ packages:
     resolution: {integrity: sha512-0ooKbGLU8JXhe1zwpQUWIeXSgLPOfwJmgheWRIUpcoA0CpyabpGhayjdG+/eA5esC1AQ8h2jWpXjJfzQzeDOCw==}
     peerDependencies:
       i18next: '>= 26.2.0'
-      react: 19.2.6
+      react: '>= 16.8.0'
       react-dom: '*'
       react-native: '*'
       typescript: ^5 || ^6
@@ -10875,18 +10819,18 @@ packages:
   react-icons@5.6.0:
     resolution: {integrity: sha512-RH93p5ki6LfOiIt0UtDyNg/cee+HLVR6cHHtW3wALfo+eOHTp8RnU2kRkI6E+H19zMIs03DyxUG/GfZMOGvmiA==}
     peerDependencies:
-      react: 19.2.6
+      react: '*'
 
   react-image-crop@11.0.10:
     resolution: {integrity: sha512-+5FfDXUgYLLqBh1Y/uQhIycpHCbXkI50a+nbfkB1C0xXXUTwkisHDo2QCB1SQJyHCqIuia4FeyReqXuMDKWQTQ==}
     peerDependencies:
-      react: 19.2.6
+      react: '>=16.13.1'
 
   react-intersection-observer@9.16.0:
     resolution: {integrity: sha512-w9nJSEp+DrW9KmQmeWHQyfaP6b03v+TdXynaoA964Wxt7mdR3An11z4NNCQgL4gKSK7y1ver2Fq+JKH6CWEzUA==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       react-dom:
         optional: true
@@ -10907,27 +10851,27 @@ packages:
     resolution: {integrity: sha512-xaijuJB0kzGiUdG7nc2MOMDUDBWPyGAjZtUrow9XxUeua8IqeP+VlIfAZ3bphpcLTnSZXz6z9jcVC/TCwbfgdw==}
     peerDependencies:
       '@types/react': '>=18'
-      react: 19.2.6
+      react: '>=18'
 
   react-number-format@5.4.5:
     resolution: {integrity: sha512-y8O2yHHj3w0aE9XO8d2BCcUOOdQTRSVq+WIuMlLVucAm5XNjJAy+BoOJiuQMldVYVOKTMyvVNfnbl2Oqp+YxGw==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^0.14 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^0.14 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   react-pdf-html@2.1.5:
     resolution: {integrity: sha512-KhmiTUcnUNbLVdZbxMcV/+Rp+PyBt+eVJHu425eNwjSsDUtytvcwS/SBdBbbpM0c4+MnnOQBOs3AiColUesM8A==}
     engines: {node: '>=16.0.0'}
     peerDependencies:
       '@react-pdf/renderer': '>=3.4.4'
-      react: 19.2.6
+      react: '>=16'
 
   react-pdf@10.4.1:
     resolution: {integrity: sha512-kS/35staVCBqS29verTQJQZXw7RfsRCPO3fdJoW1KXylcv7A9dw6DZ3vJXC2w+bIBgLw5FN4pOFvKSQtkQhPfA==}
     peerDependencies:
       '@types/react': ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -10935,21 +10879,21 @@ packages:
   react-phone-number-input@3.4.17:
     resolution: {integrity: sha512-1wcjhBAWHgEBAGLi5/XbeZI7Q3aEHNb2z/dHY6R2Gz70TQvu0ZoOT28NTdwtZf4lyRKXWufnTzVhLPBUD8LfmQ==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8'
+      react-dom: '>=16.8'
 
   react-quill-new@3.8.3:
     resolution: {integrity: sha512-c96PYqFTo0pI4R3e79B3rH9LUIce1kIQbmTBu/imJQZk8305ogyLyBqKKjG2UoInDlquXqePSzmBo2aVia3ttw==}
     peerDependencies:
       quill-delta: ^5.1.0
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16 || ^17 || ^18 || ^19
+      react-dom: ^16 || ^17 || ^18 || ^19
 
   react-redux@9.3.0:
     resolution: {integrity: sha512-KQopgqFo/p/fgmAs5qz6p5RWaNAzq40WAu7fJIXnQpYxFPbJYtsJPWvGeF2rOBaY/kEuV77AVsX8TsQzKm+A/g==}
     peerDependencies:
       '@types/react': ^18.2.25 || ^19
-      react: 19.2.6
+      react: ^18.0 || ^19
       redux: ^5.0.0
     peerDependenciesMeta:
       '@types/react':
@@ -10966,7 +10910,7 @@ packages:
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -10976,7 +10920,7 @@ packages:
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -10984,35 +10928,35 @@ packages:
   react-resizable-panels@3.0.6:
     resolution: {integrity: sha512-b3qKHQ3MLqOgSS+FRYKapNkJZf5EQzuf6+RLiq1/IlTHw99YrZ2NJZLk4hQIzTnnIkRg2LUqyVinu6YWWpUYew==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.14.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^16.14.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
 
   react-router-dom@6.30.4:
     resolution: {integrity: sha512-q4HvNl+mmDdkS0g+MqiBZNteQJCuimWoOyHMy4T/RQLAn9Z29+E91QXRaxOujeMl2HTzRSS0KFPd7lxX3PjV0Q==}
     engines: {node: '>=14.0.0'}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.8'
+      react-dom: '>=16.8'
 
   react-router-dom@7.17.0:
     resolution: {integrity: sha512-fyU2yjGups/hE6Xz0I5ZYbVL8Gx29eCjgpHaRaTaVU+OOAdfRX05KsvyRm0GO8YQwOkhpU3MurW1jyMUJn+zSw==}
     engines: {node: '>=20.0.0'}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=18'
+      react-dom: '>=18'
 
   react-router@6.30.4:
     resolution: {integrity: sha512-SVUsDe+DybHM/WmYKIVYhZh1o5Dcuf16yM6WjG02Q9XVFMZIJyHYhwrr6bFBXZkVP6z69kNkMyBCujt8FaFLJA==}
     engines: {node: '>=14.0.0'}
     peerDependencies:
-      react: 19.2.6
+      react: '>=16.8'
 
   react-router@7.17.0:
     resolution: {integrity: sha512-FDELK7rTMlCHO5+reyXsPlmfr7N1F91lPHsWYfMEGQm/KQ+F4JFM8jGoeQDmDvdTs93Fw9aSilH+uKRb4/jXvQ==}
     engines: {node: '>=20.0.0'}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=18'
+      react-dom: '>=18'
     peerDependenciesMeta:
       react-dom:
         optional: true
@@ -11023,8 +10967,8 @@ packages:
       '@types/prop-types': ^15.7.3
       '@types/react': 0.14 - 19
       prop-types: ^15.5.8
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: 0.14 - 19
+      react-dom: 0.14 - 19
     peerDependenciesMeta:
       '@types/prop-types':
         optional: true
@@ -11034,20 +10978,20 @@ packages:
   react-simple-animate@3.5.3:
     resolution: {integrity: sha512-Ob+SmB5J1tXDEZyOe2Hf950K4M8VaWBBmQ3cS2BUnTORqHjhK0iKG8fB+bo47ZL15t8d3g/Y0roiqH05UBjG7A==}
     peerDependencies:
-      react-dom: 19.2.6
+      react-dom: ^16.8.0 || ^17 || ^18 || ^19
 
   react-smooth@4.0.4:
     resolution: {integrity: sha512-gnGKTpYwqL0Iii09gHobNolvX4Kiq4PKx6eWBCYYix+8cdw+cGo3do906l1NBPKkSWx1DghC1dlWG9L2uGd61Q==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   react-style-singleton@2.2.3:
     resolution: {integrity: sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==}
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -11056,13 +11000,17 @@ packages:
     resolution: {integrity: sha512-U1DGlIQN5AwgjTyOEnI1oCcMuEr1pv1qOtklB2l4nyMGbHzWrI0eFsYK0zos2YWqAolJyG0IWJaqWmWj5ETh0A==}
     engines: {node: '>=10'}
     peerDependencies:
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   react-transition-group@4.4.5:
     resolution: {integrity: sha512-pZcd1MCJoiKiBR2NRxeCRg13uCXbydPnmB4EOeRrY7480qNWO8IIgQG6zlDkm6uRMsURXPuKq0GWtiM59a5Q6g==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>=16.6.0'
+      react-dom: '>=16.6.0'
+
+  react@18.3.1:
+    resolution: {integrity: sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==}
+    engines: {node: '>=0.10.0'}
 
   react@19.2.6:
     resolution: {integrity: sha512-sfWGGfavi0xr8Pg0sVsyHMAOziVYKgPLNrS7ig+ivMNb3wbCBw3KxtflsGBAwD3gYQlE/AEZsTLgToRrSCjb0Q==}
@@ -11112,15 +11060,15 @@ packages:
     engines: {node: '>=14'}
     deprecated: 1.x and 2.x branches are no longer active. Bump to Recharts v3 to receive latest features and bugfixes. See https://github.com/recharts/recharts/wiki/3.0-migration-guide
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   recharts@3.8.1:
     resolution: {integrity: sha512-mwzmO1s9sFL0TduUpwndxCUNoXsBw3u3E/0+A+cLcrSfQitSG62L32N69GhqUrrT5qKcAE3pCGVINC6pqkBBQg==}
     engines: {node: '>=18'}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
       react-is: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   redux-thunk@3.1.0:
@@ -11370,6 +11318,9 @@ packages:
     resolution: {integrity: sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==}
     engines: {node: '>=v12.22.7'}
 
+  scheduler@0.23.2:
+    resolution: {integrity: sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==}
+
   scheduler@0.25.0-rc-603e6108-20241029:
     resolution: {integrity: sha512-pFwF6H1XrSdYYNLfOcGlM28/j8CGLu8IvdrxqhjWULe2bPcKiKW4CV+OWqR/9fT52mywx65l7ysNkjLKBda7eA==}
 
@@ -11497,12 +11448,6 @@ packages:
   signature_pad@2.3.2:
     resolution: {integrity: sha512-peYXLxOsIY6MES2TrRLDiNg2T++8gGbpP2yaC+6Ohtxr+a2dzoaqWosWDY9sWqTAAk6E/TyQO+LJw9zQwyu5kA==}
 
-  simple-concat@1.0.1:
-    resolution: {integrity: sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q==}
-
-  simple-get@3.1.1:
-    resolution: {integrity: sha512-CQ5LTKGfCpvE1K0n2us+kuMPbk/q0EKl82s4aheV9oXjFEz6W/Y7oQFVJuU6QG77hRT4Ghb5RURteF5vnWjupA==}
-
   sisteransi@1.0.5:
     resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
 
@@ -11568,8 +11513,8 @@ packages:
   sonner@2.0.7:
     resolution: {integrity: sha512-W6ZN4p58k8aDKA4XPcx2hpIQXBRAgyiWVkYhT7CvK6D3iAu7xjvVyhQHg2/iaKJZ1XVJ4r7XuwGL+WGEK37i9w==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
 
   source-map-js@1.2.1:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
@@ -11816,8 +11761,8 @@ packages:
     resolution: {integrity: sha512-uuzIIfnVkagcVHv9nE0VPlHPSCmXIUGKfJ42LNjxCCTDTL5sgnJ8Z7GZBq0EnLYGln77tPpEpExt2+qa+cZqSw==}
     engines: {node: '>=10'}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: '>= 16.8.0'
+      react-dom: '>= 16.8.0'
       react-is: '>= 16.8.0'
 
   styled-jsx@5.1.1:
@@ -11826,7 +11771,7 @@ packages:
     peerDependencies:
       '@babel/core': '*'
       babel-plugin-macros: '*'
-      react: 19.2.6
+      react: '>= 16.8.0 || 17.x.x || ^18.0.0-0'
     peerDependenciesMeta:
       '@babel/core':
         optional: true
@@ -11947,11 +11892,6 @@ packages:
   tar-stream@3.2.0:
     resolution: {integrity: sha512-ojzvCvVaNp6aOTFmG7jaRD0meowIAuPc3cMMhSgKiVWws1GyHbGd/xvnyuRKcKlMpt3qvxx6r0hreCNITP9hIg==}
 
-  tar@6.2.1:
-    resolution: {integrity: sha512-DZ4yORTwrbTj/7MZYq2w+/ZFdI6OZ/f9SFHR+71gIVUZhOQPHzVCLpvRnPgyaMpfWxxk/4ONva3GQSyNIKRv6A==}
-    engines: {node: '>=10'}
-    deprecated: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
-
   teex@1.0.1:
     resolution: {integrity: sha512-eYE6iEI62Ni1H8oIa7KlDU6uQBtqr4Eajni3wX7rpfXD8ysFx8z0+dri+KWEPWpBsxXfxu58x/0jvTVT1ekOSg==}
 
@@ -12149,9 +12089,6 @@ packages:
     resolution: {integrity: sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw==}
     engines: {node: '>=16'}
 
-  tr46@0.0.3:
-    resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==}
-
   tr46@5.1.1:
     resolution: {integrity: sha512-hdF5ZgjTqgAntKkklYw0R03MG2x/bSzTtkxmIRw/sTNV8YXsCJ1tfLAX23lhxhHJlEf3CRCOCGGWw3vI3GaSPw==}
     engines: {node: '>=18'}
@@ -12334,7 +12271,7 @@ packages:
     hasBin: true
     peerDependencies:
       '@faker-js/faker': '>=8.4.1'
-      typeorm: 0.3.30
+      typeorm: ~0.3.0
 
   typeorm@0.3.30:
     resolution: {integrity: sha512-8T35PzjefOdqc2ZR9mwLQj0pUGp6lQhMbK2EvVMwJVJWlaoHm0v/Q6dThNOZkFchD+0yMg8gwjKM28ePiLSXSQ==}
@@ -12514,7 +12451,7 @@ packages:
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12523,7 +12460,7 @@ packages:
     resolution: {integrity: sha512-djviaxuOOh7wkj0paeO1Q/4wMZ8Zrnag5H6yBvzN7AKKe8beOaED9SF5/ByLqsku8NP4zQqsvM2u3ew/tJK8/w==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12532,13 +12469,13 @@ packages:
     resolution: {integrity: sha512-kbeNVZ9Zkc0RFGpfMN3MNfaKNvcLNyxOAAd9O4CBZ+kCBXXscn9s/4I+8ytUER4RDpEYs5+O6Rs4PqiZ+rHr5Q==}
     engines: {node: '>=10', npm: '>=6'}
     peerDependencies:
-      react: 19.2.6
+      react: '>=16.13'
 
   use-isomorphic-layout-effect@1.2.1:
     resolution: {integrity: sha512-tpZZ+EX0gaghDAiFR37hj5MgY6ZN55kLiPkJsKxBMZ6GZdOSPJXiOzPM984oPYZ5AnehYx5WQp1+ME8I/P/pRA==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12547,7 +12484,7 @@ packages:
     resolution: {integrity: sha512-mhg3xdm9NaM8q+gLT8KryJPnRFOz1/5XPBhmDEVZK1webPzDjrPk7f/mbpeLqTgB9msytYWANxgALOCJKnLvcQ==}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12557,7 +12494,7 @@ packages:
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12565,7 +12502,7 @@ packages:
   use-sync-external-store@1.6.0:
     resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==}
     peerDependencies:
-      react: 19.2.6
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   use@3.1.1:
     resolution: {integrity: sha512-cwESVXlO3url9YWlFW/TA9cshCEhtu7IKJ/p5soJ/gGpj7vbvFrAY/eIioQ6Dw23KjZhYgiIo8HOs1nQ2vr/oQ==}
@@ -12628,8 +12565,8 @@ packages:
   vaul@1.1.2:
     resolution: {integrity: sha512-ZFkClGpWyI2WUQjdLJ/BaGuV6AVQiJ3uELGk3OYtP+B6yCO7Cmn9vPFXVJkRaGkOJu3m8bQMgtyzNHixULceQA==}
     peerDependencies:
-      react: 19.2.6
-      react-dom: 19.2.6
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
 
   verror@1.10.0:
     resolution: {integrity: sha512-ZZKSmDAEFOijERBLkmYfJ+vmk3w+7hOLYDNkRCuRuMJGEmqYNCNLyBBFwWKVMhfwaEF3WOd0Zlw86U/WC/+nYw==}
@@ -12757,9 +12694,6 @@ packages:
   webdriver-bidi-protocol@0.4.1:
     resolution: {integrity: sha512-ARrjNjtWRRs2w4Tk7nqrf2gBI0QXWuOmMCx2hU+1jUt6d00MjMxURrhxhGbrsoiZKJrhTSTzbIrc554iKI10qw==}
 
-  webidl-conversions@3.0.1:
-    resolution: {integrity: sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==}
-
   webidl-conversions@7.0.0:
     resolution: {integrity: sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==}
     engines: {node: '>=12'}
@@ -12795,9 +12729,6 @@ packages:
     resolution: {integrity: sha512-De72GdQZzNTUBBChsXueQUnPKDkg/5A5zp7pFDuQAj5UFoENpiACU0wlCvzpAGnTkj++ihpKwKyYewn/XNUbKw==}
     engines: {node: '>=18'}
 
-  whatwg-url@5.0.0:
-    resolution: {integrity: sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==}
-
   which-boxed-primitive@1.1.1:
     resolution: {integrity: sha512-TbX3mj8n0odCBFVlY8AxkqcHASw3L60jIuF8jFP78az3C2YhmGvqbHBpAjTRH2/xqYunrJ9g1jSyjCjpoWzIAA==}
     engines: {node: '>= 0.4'}
@@ -12832,9 +12763,6 @@ packages:
     engines: {node: '>=8'}
     hasBin: true
 
-  wide-align@1.1.5:
-    resolution: {integrity: sha512-eDMORYaPNZ4sQIuuYPDHdQvf4gyCF9rEEV/yPxGfwPkRodwEgiMUUXTx/dex+Me0wxx53S+NgUHaP7y3MGlDmg==}
-
   wmf@1.0.2:
     resolution: {integrity: sha512-/p9K7bEh0Dj6WbXg4JG0xvLQmIadrner1bi45VMJTfnbVHsc7yIajZyoSoK60/dtVBs12Fm6WkUI5/3WAVsNMw==}
     engines: {node: '>=0.8'}
@@ -12946,9 +12874,6 @@ packages:
   yallist@3.1.1:
     resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
 
-  yallist@4.0.0:
-    resolution: {integrity: sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==}
-
   yaml@1.10.3:
     resolution: {integrity: sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==}
     engines: {node: '>= 6'}
@@ -13045,7 +12970,7 @@ packages:
     peerDependencies:
       '@types/react': '>=18.0.0'
       immer: '>=9.0.6'
-      react: 19.2.6
+      react: '>=18.0.0'
       use-sync-external-store: '>=1.2.0'
     peerDependenciesMeta:
       '@types/react':
@@ -14073,6 +13998,12 @@ snapshots:
       '@floating-ui/core': 1.7.5
       '@floating-ui/utils': 0.2.11
 
+  '@floating-ui/react-dom@2.1.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@floating-ui/dom': 1.7.6
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
   '@floating-ui/react-dom@2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/dom': 1.7.6
@@ -14087,6 +14018,14 @@ snapshots:
       react-dom: 19.2.6(react@19.2.6)
       tabbable: 6.4.0
 
+  '@floating-ui/react@0.27.19(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@floating-ui/react-dom': 2.1.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@floating-ui/utils': 0.2.11
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      tabbable: 6.4.0
+
   '@floating-ui/react@0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/react-dom': 2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -14150,9 +14089,9 @@ snapshots:
       - '@types/react'
       - supports-color
 
-  '@hookform/resolvers@3.10.0(react-hook-form@7.77.0(react@19.2.6))':
+  '@hookform/resolvers@3.10.0(react-hook-form@7.77.0(react@18.3.1))':
     dependencies:
-      react-hook-form: 7.77.0(react@19.2.6)
+      react-hook-form: 7.77.0(react@18.3.1)
 
   '@hookform/resolvers@5.4.0(react-hook-form@7.77.0(react@19.2.6))':
     dependencies:
@@ -14940,23 +14879,23 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
-  '@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+  '@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
-      '@floating-ui/react': 0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@mantine/hooks': 9.3.0(react@19.2.6)
+      '@floating-ui/react': 0.27.19(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@mantine/hooks': 9.3.0(react@18.3.1)
       clsx: 2.1.1
-      react: 19.2.6
-      react-dom: 19.2.6(react@19.2.6)
-      react-number-format: 5.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@19.2.6)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      react-number-format: 5.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
       type-fest: 5.7.0
     transitivePeerDependencies:
       - '@types/react'
 
-  '@mantine/core@9.3.0(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+  '@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/react': 0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@mantine/hooks': 9.3.2(react@19.2.6)
+      '@mantine/hooks': 9.3.0(react@19.2.6)
       clsx: 2.1.1
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
@@ -15010,6 +14949,10 @@ snapshots:
     dependencies:
       react: 19.2.6
 
+  '@mantine/hooks@9.3.0(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+
   '@mantine/hooks@9.3.0(react@19.2.6)':
     dependencies:
       react: 19.2.6
@@ -15031,22 +14974,6 @@ snapshots:
     dependencies:
       react: 19.2.6
 
-  '@mapbox/node-pre-gyp@1.0.11':
-    dependencies:
-      detect-libc: 2.1.2
-      https-proxy-agent: 5.0.1
-      make-dir: 3.1.0
-      node-fetch: 2.7.0
-      nopt: 5.0.0
-      npmlog: 5.0.1
-      rimraf: 3.0.2
-      semver: 7.8.2
-      tar: 6.2.1
-    transitivePeerDependencies:
-      - encoding
-      - supports-color
-    optional: true
-
   '@marijn/find-cluster-break@1.0.3': {}
 
   '@mdxeditor/editor@4.2.0(@codemirror/language@6.12.4)(@lezer/highlight@1.2.3)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.9.3)(yjs@13.6.32)':
@@ -15806,6 +15733,15 @@ snapshots:
 
   '@radix-ui/primitive@1.1.4': {}
 
+  '@radix-ui/react-accessible-icon@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-accessible-icon@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -15815,6 +15751,23 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-accordion@1.2.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-collapsible': 1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-accordion@1.2.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15832,6 +15785,20 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-alert-dialog@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-alert-dialog@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15846,6 +15813,15 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-arrow@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-arrow@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -15855,6 +15831,15 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-aspect-ratio@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-aspect-ratio@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -15864,6 +15849,19 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-avatar@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-avatar@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@19.2.6)
@@ -15877,6 +15875,22 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-checkbox@1.3.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-checkbox@1.3.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15893,6 +15907,22 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-collapsible@1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-collapsible@1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15909,6 +15939,18 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-collection@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-collection@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@19.2.6)
@@ -15921,12 +15963,31 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-compose-refs@1.1.3(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-compose-refs@1.1.3(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-context-menu@2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-context-menu@2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15940,12 +16001,40 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-context@1.1.4(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-context@1.1.4(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-dialog@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      aria-hidden: 1.2.6
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-dialog@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15968,12 +16057,31 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-direction@1.1.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-direction@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-dismissable-layer@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-escape-keydown': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-dismissable-layer@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15987,6 +16095,21 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-dropdown-menu@2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-dropdown-menu@2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16002,12 +16125,29 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-focus-guards@1.1.4(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-focus-guards@1.1.4(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-focus-scope@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-focus-scope@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@19.2.6)
@@ -16019,6 +16159,20 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-form@0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-label': 2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-form@0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16033,6 +16187,23 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-hover-card@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-hover-card@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16054,6 +16225,13 @@ snapshots:
     dependencies:
       react: 19.2.6
 
+  '@radix-ui/react-id@1.1.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-id@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -16061,6 +16239,15 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-label@2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-label@2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -16070,6 +16257,32 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-menu@2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      aria-hidden: 1.2.6
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-menu@2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16096,6 +16309,24 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-menubar@1.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-menubar@1.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16114,6 +16345,28 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-navigation-menu@1.2.15(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-navigation-menu@1.2.15(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16136,6 +16389,26 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-one-time-password-field@0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/number': 1.1.2
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-one-time-password-field@0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/number': 1.1.2
@@ -16156,6 +16429,22 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-password-toggle-field@0.1.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-password-toggle-field@0.1.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16172,6 +16461,29 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-popover@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      aria-hidden: 1.2.6
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-popover@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16195,6 +16507,24 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-popper@1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@floating-ui/react-dom': 2.1.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-arrow': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-rect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/rect': 1.1.2
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-popper@1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/react-dom': 2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -16213,6 +16543,16 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-portal@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-portal@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -16223,6 +16563,15 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-presence@1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-presence@1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -16232,6 +16581,15 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-primitive@2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-primitive@2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@19.2.6)
@@ -16241,6 +16599,16 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-progress@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-progress@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@19.2.6)
@@ -16251,6 +16619,24 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-radio-group@1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-radio-group@1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16269,6 +16655,23 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-roving-focus@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-roving-focus@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16286,6 +16689,23 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-scroll-area@1.2.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/number': 1.1.2
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-scroll-area@1.2.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/number': 1.1.2
@@ -16303,6 +16723,36 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-select@2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/number': 1.1.2
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      aria-hidden: 1.2.6
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-select@2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/number': 1.1.2
@@ -16333,6 +16783,15 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-separator@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-separator@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -16342,6 +16801,25 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-slider@1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/number': 1.1.2
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-slider@1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/number': 1.1.2
@@ -16361,6 +16839,13 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-slot@1.2.5(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-slot@1.2.5(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@19.2.6)
@@ -16368,6 +16853,21 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-switch@1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-switch@1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16383,6 +16883,22 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-tabs@1.1.14(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-tabs@1.1.14(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16399,6 +16915,26 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-toast@1.2.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-toast@1.2.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16419,6 +16955,21 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-toggle-group@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-toggle': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-toggle-group@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16434,6 +16985,17 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-toggle@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-toggle@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16445,6 +17007,21 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-toolbar@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-separator': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-toggle-group': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-toolbar@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16460,6 +17037,26 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-tooltip@1.2.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-tooltip@1.2.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16480,12 +17077,26 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
+  '@radix-ui/react-use-callback-ref@1.1.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-use-callback-ref@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-use-controllable-state@1.2.3(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-use-controllable-state@1.2.3(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@19.2.6)
@@ -16494,6 +17105,13 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-use-effect-event@0.0.3(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-use-effect-event@0.0.3(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -16501,6 +17119,13 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-use-escape-keydown@1.1.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-use-escape-keydown@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -16508,24 +17133,49 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-use-is-hydrated@0.1.1(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-use-is-hydrated@0.1.1(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-use-layout-effect@1.1.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-use-layout-effect@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-use-previous@1.1.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-use-previous@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-use-rect@1.1.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/rect': 1.1.2
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-use-rect@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/rect': 1.1.2
@@ -16533,6 +17183,13 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-use-size@1.1.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   '@radix-ui/react-use-size@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -16540,6 +17197,15 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
+  '@radix-ui/react-visually-hidden@1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   '@radix-ui/react-visually-hidden@1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -17064,6 +17730,11 @@ snapshots:
       '@tanstack/react-query': 5.101.0(react@19.2.6)
       react: 19.2.6
 
+  '@tanstack/react-query@5.101.0(react@18.3.1)':
+    dependencies:
+      '@tanstack/query-core': 5.101.0
+      react: 18.3.1
+
   '@tanstack/react-query@5.101.0(react@19.2.6)':
     dependencies:
       '@tanstack/query-core': 5.101.0
@@ -17075,6 +17746,12 @@ snapshots:
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
 
+  '@tanstack/react-table@8.21.3(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@tanstack/table-core': 8.21.3
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
   '@tanstack/react-table@8.21.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@tanstack/table-core': 8.21.3
@@ -17120,50 +17797,7 @@ snapshots:
 
   '@tootallnate/quickjs-emscripten@0.23.0': {}
 
-  '@tria-plc/api-common@file:local-packages/tria-plc-api-common-1.6.0.tgz(2te6mb6vb2upxetsvhkgi54vi4)':
-    dependencies:
-      '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)
-      '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/core': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/microservices@11.1.24)(@nestjs/platform-express@11.1.24)(@nestjs/websockets@11.1.27)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/jwt': 11.0.2(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))
-      '@nestjs/microservices': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/websockets@11.1.27)(amqp-connection-manager@5.0.0(amqplib@2.0.1))(amqplib@2.0.1)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/passport': 10.0.3(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(passport@0.7.0)
-      '@nestjs/swagger': 11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)
-      '@nestjs/throttler': 6.5.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)
-      '@nestjs/typeorm': 11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
-      argon2: 0.43.1
-      axios: 1.17.0
-      change-case: 5.4.4
-      class-transformer: 0.5.1
-      class-validator: 0.14.4
-      dotenv: 16.6.1
-      ethiopian-calendar-date-converter: 2.1.6
-      ethiopian-date: 0.0.6
-      exceljs: 4.4.0
-      file-type: 21.3.4
-      handlebars: 4.7.9
-      handlebars-helpers: 0.10.0
-      jmespath: 0.16.0
-      jose: 5.10.0
-      jsonwebtoken: 9.0.3
-      libphonenumber-js: 1.13.6
-      libreoffice-convert: 1.8.1
-      nestjs-minio-client: 2.2.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)
-      passport-jwt: 4.0.1
-      qrcode: 1.5.4
-      reflect-metadata: 0.2.2
-      rxjs: 7.8.2
-      style-object-to-css-string: 1.1.3
-      typeorm: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
-      typeorm-extension: 3.9.0(@faker-js/faker@10.4.0)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
-      uuid: 11.1.1
-      xlsx: 0.18.5
-    transitivePeerDependencies:
-      - '@faker-js/faker'
-      - debug
-      - supports-color
-
-  '@tria-plc/api-common@file:local-packages/tria-plc-api-common-1.6.0.tgz(66zjxtt2zhydyq6w3arhrktl4y)':
+  '@tria-plc/api-common@file:local-packages/tria-plc-api-common-1.6.0.tgz(2b4e99ab22f78c34e7861d649f4ff29b)':
     dependencies:
       '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)
       '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
@@ -17206,41 +17840,7 @@ snapshots:
       - debug
       - supports-color
 
-  '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(2duxgcsfjn5usnyutzzh6i5xr4)':
-    dependencies:
-      '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)
-      '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/core': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/microservices@11.1.24)(@nestjs/platform-express@11.1.24)(@nestjs/websockets@11.1.27)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/jwt': 11.0.2(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))
-      '@nestjs/microservices': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/websockets@11.1.27)(amqp-connection-manager@5.0.0(amqplib@2.0.1))(amqplib@2.0.1)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/passport': 10.0.3(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(passport@0.7.0)
-      '@nestjs/swagger': 7.4.2(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)
-      '@nestjs/throttler': 6.5.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)
-      '@nestjs/typeorm': 11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
-      '@tria-plc/api-common': file:local-packages/tria-plc-api-common-1.6.0.tgz(66zjxtt2zhydyq6w3arhrktl4y)
-      argon2: 0.43.1
-      axios: 1.17.0
-      class-transformer: 0.5.1
-      class-validator: 0.14.4
-      dotenv: 17.4.2
-      ethiopian-date: 0.0.6
-      file-type: 21.3.4
-      jose: 5.10.0
-      jsonwebtoken: 9.0.3
-      libphonenumber-js: 1.13.6
-      nestjs-minio-client: 2.2.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)
-      passport-jwt: 4.0.1
-      qrcode: 1.5.4
-      reflect-metadata: 0.2.2
-      rxjs: 7.8.2
-      typeorm: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
-      typeorm-extension: 3.9.0(@faker-js/faker@10.4.0)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
-      uuid: 11.1.1
-    transitivePeerDependencies:
-      - '@faker-js/faker'
-      - supports-color
-
-  '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(776yg74vcz655pvzf2fzttkf2q)':
+  '@tria-plc/api-common@file:local-packages/tria-plc-api-common-1.6.0.tgz(ae9a56cc1c6d93629dd85f7605ccd5b6)':
     dependencies:
       '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)
       '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
@@ -17251,7 +17851,50 @@ snapshots:
       '@nestjs/swagger': 11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)
       '@nestjs/throttler': 6.5.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)
       '@nestjs/typeorm': 11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
-      '@tria-plc/api-common': file:local-packages/tria-plc-api-common-1.6.0.tgz(2te6mb6vb2upxetsvhkgi54vi4)
+      argon2: 0.43.1
+      axios: 1.17.0
+      change-case: 5.4.4
+      class-transformer: 0.5.1
+      class-validator: 0.14.4
+      dotenv: 16.6.1
+      ethiopian-calendar-date-converter: 2.1.6
+      ethiopian-date: 0.0.6
+      exceljs: 4.4.0
+      file-type: 21.3.4
+      handlebars: 4.7.9
+      handlebars-helpers: 0.10.0
+      jmespath: 0.16.0
+      jose: 5.10.0
+      jsonwebtoken: 9.0.3
+      libphonenumber-js: 1.13.6
+      libreoffice-convert: 1.8.1
+      nestjs-minio-client: 2.2.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)
+      passport-jwt: 4.0.1
+      qrcode: 1.5.4
+      reflect-metadata: 0.2.2
+      rxjs: 7.8.2
+      style-object-to-css-string: 1.1.3
+      typeorm: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
+      typeorm-extension: 3.9.0(@faker-js/faker@10.4.0)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
+      uuid: 11.1.1
+      xlsx: 0.18.5
+    transitivePeerDependencies:
+      - '@faker-js/faker'
+      - debug
+      - supports-color
+
+  '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(cc085a020c559b355f168432c579a024)':
+    dependencies:
+      '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)
+      '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/core': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/microservices@11.1.24)(@nestjs/platform-express@11.1.24)(@nestjs/websockets@11.1.27)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/jwt': 11.0.2(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))
+      '@nestjs/microservices': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/websockets@11.1.27)(amqp-connection-manager@5.0.0(amqplib@2.0.1))(amqplib@2.0.1)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/passport': 10.0.3(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(passport@0.7.0)
+      '@nestjs/swagger': 7.4.2(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)
+      '@nestjs/throttler': 6.5.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)
+      '@nestjs/typeorm': 11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
+      '@tria-plc/api-common': file:local-packages/tria-plc-api-common-1.6.0.tgz(2b4e99ab22f78c34e7861d649f4ff29b)
       argon2: 0.43.1
       axios: 1.17.0
       class-transformer: 0.5.1
@@ -17274,7 +17917,41 @@ snapshots:
       - '@faker-js/faker'
       - supports-color
 
-  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(elggzzmuouas3d7ccap2lbvoyu)':
+  '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(d0be280d95adfc1b38e59bdc80c5dec5)':
+    dependencies:
+      '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)
+      '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/core': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/microservices@11.1.24)(@nestjs/platform-express@11.1.24)(@nestjs/websockets@11.1.27)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/jwt': 11.0.2(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))
+      '@nestjs/microservices': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/websockets@11.1.27)(amqp-connection-manager@5.0.0(amqplib@2.0.1))(amqplib@2.0.1)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/passport': 10.0.3(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(passport@0.7.0)
+      '@nestjs/swagger': 11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)
+      '@nestjs/throttler': 6.5.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)
+      '@nestjs/typeorm': 11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
+      '@tria-plc/api-common': file:local-packages/tria-plc-api-common-1.6.0.tgz(ae9a56cc1c6d93629dd85f7605ccd5b6)
+      argon2: 0.43.1
+      axios: 1.17.0
+      class-transformer: 0.5.1
+      class-validator: 0.14.4
+      dotenv: 17.4.2
+      ethiopian-date: 0.0.6
+      file-type: 21.3.4
+      jose: 5.10.0
+      jsonwebtoken: 9.0.3
+      libphonenumber-js: 1.13.6
+      nestjs-minio-client: 2.2.0(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)
+      passport-jwt: 4.0.1
+      qrcode: 1.5.4
+      reflect-metadata: 0.2.2
+      rxjs: 7.8.2
+      typeorm: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
+      typeorm-extension: 3.9.0(@faker-js/faker@10.4.0)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
+      uuid: 11.1.1
+    transitivePeerDependencies:
+      - '@faker-js/faker'
+      - supports-color
+
+  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)':
     dependencies:
       '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
       '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
@@ -17340,7 +18017,7 @@ snapshots:
       lodash: 4.18.1
       lucide-react: 0.513.0(react@19.2.6)
       mantine-react-table: 2.0.0-beta.9(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/dates@7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(@tabler/icons-react@3.44.0(react@19.2.6))(clsx@2.1.1)(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      mui-ethiopian-datepicker: 0.3.2(ruap3lc7my4alz6jx6pekjrhou)
+      mui-ethiopian-datepicker: 0.3.2(4b3af212eafdf0059f009b005d7e343d)
       next-themes: 0.4.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       path: 0.12.7
       pdf-lib: 1.17.1
@@ -17386,7 +18063,6 @@ snapshots:
       - '@types/react-dom'
       - bufferutil
       - debug
-      - encoding
       - pdfjs-dist
       - prop-types
       - react-is
@@ -17399,7 +18075,7 @@ snapshots:
       - utf-8-validate
       - vite
 
-  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(vhj5jsbx2ogblwtd5crolhrpku)':
+  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)':
     dependencies:
       '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
       '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
@@ -17465,7 +18141,7 @@ snapshots:
       lodash: 4.18.1
       lucide-react: 0.513.0(react@19.2.6)
       mantine-react-table: 2.0.0-beta.9(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/dates@7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(@tabler/icons-react@3.44.0(react@19.2.6))(clsx@2.1.1)(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      mui-ethiopian-datepicker: 0.3.2(ruap3lc7my4alz6jx6pekjrhou)
+      mui-ethiopian-datepicker: 0.3.2(4b3af212eafdf0059f009b005d7e343d)
       next-themes: 0.4.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       path: 0.12.7
       pdf-lib: 1.17.1
@@ -17511,7 +18187,6 @@ snapshots:
       - '@types/react-dom'
       - bufferutil
       - debug
-      - encoding
       - pdfjs-dist
       - prop-types
       - react-is
@@ -18220,9 +18895,6 @@ snapshots:
       jsonparse: 1.3.1
       through: 2.3.8
 
-  abbrev@1.1.1:
-    optional: true
-
   abort-controller@3.0.0:
     dependencies:
       event-target-shim: 5.0.1
@@ -18501,9 +19173,6 @@ snapshots:
 
   append-field@1.0.0: {}
 
-  aproba@2.1.0:
-    optional: true
-
   arch@2.2.0: {}
 
   archiver-utils@2.1.0:
@@ -18542,12 +19211,6 @@ snapshots:
       tar-stream: 2.2.0
       zip-stream: 4.1.1
 
-  are-we-there-yet@2.0.0:
-    dependencies:
-      delegates: 1.0.0
-      readable-stream: 3.6.2
-    optional: true
-
   arg@4.1.3: {}
 
   arg@5.0.2: {}
@@ -19102,16 +19765,6 @@ snapshots:
 
   caniuse-lite@1.0.30001797: {}
 
-  canvas@2.11.2:
-    dependencies:
-      '@mapbox/node-pre-gyp': 1.0.11
-      nan: 2.28.0
-      simple-get: 3.1.1
-    transitivePeerDependencies:
-      - encoding
-      - supports-color
-    optional: true
-
   canvg@3.0.11:
     dependencies:
       '@babel/runtime': 7.29.7
@@ -19192,9 +19845,6 @@ snapshots:
     dependencies:
       readdirp: 4.1.2
 
-  chownr@2.0.0:
-    optional: true
-
   chrome-trace-event@1.0.4: {}
 
   chromium-bidi@14.0.0(devtools-protocol@0.0.1608973):
@@ -19358,9 +20008,6 @@ snapshots:
     dependencies:
       color-name: 2.1.0
 
-  color-support@1.1.3:
-    optional: true
-
   colorette@2.0.20: {}
 
   colors@1.4.0:
@@ -19424,9 +20071,6 @@ snapshots:
 
   consola@3.4.2: {}
 
-  console-control-strings@1.1.0:
-    optional: true
-
   content-disposition@0.5.4:
     dependencies:
       safe-buffer: 5.2.1
@@ -19724,6 +20368,8 @@ snapshots:
 
   date-fns@3.6.0: {}
 
+  date-fns@4.4.0: {}
+
   date.js@0.3.3:
     dependencies:
       debug: 3.1.0
@@ -19770,11 +20416,6 @@ snapshots:
 
   decode-uri-component@0.2.2: {}
 
-  decompress-response@4.2.1:
-    dependencies:
-      mimic-response: 2.1.0
-    optional: true
-
   dedent@1.7.2(babel-plugin-macros@3.1.0):
     optionalDependencies:
       babel-plugin-macros: 3.1.0
@@ -19841,9 +20482,6 @@ snapshots:
 
   delayed-stream@1.0.0: {}
 
-  delegates@1.0.0:
-    optional: true
-
   depd@2.0.0: {}
 
   dequal@2.0.3: {}
@@ -20990,11 +21628,6 @@ snapshots:
       jsonfile: 6.2.1
       universalify: 2.0.1
 
-  fs-minipass@2.1.0:
-    dependencies:
-      minipass: 3.3.6
-    optional: true
-
   fs-monkey@1.1.0: {}
 
   fs.realpath@1.0.0: {}
@@ -21027,19 +21660,6 @@ snapshots:
 
   fuzzysort@3.1.0: {}
 
-  gauge@3.0.2:
-    dependencies:
-      aproba: 2.1.0
-      color-support: 1.1.3
-      console-control-strings: 1.1.0
-      has-unicode: 2.0.1
-      object-assign: 4.1.1
-      signal-exit: 3.0.7
-      string-width: 4.2.3
-      strip-ansi: 6.0.1
-      wide-align: 1.1.5
-    optional: true
-
   generator-function@2.0.1: {}
 
   gensync@1.0.0-beta.2: {}
@@ -21282,9 +21902,6 @@ snapshots:
     dependencies:
       has-symbols: 1.1.0
 
-  has-unicode@2.0.1:
-    optional: true
-
   has-value@0.3.1:
     dependencies:
       get-value: 2.0.6
@@ -22275,7 +22892,7 @@ snapshots:
 
   jsbn@0.1.1: {}
 
-  jsdom@25.0.1(canvas@2.11.2):
+  jsdom@25.0.1:
     dependencies:
       cssstyle: 4.6.0
       data-urls: 5.0.0
@@ -22298,8 +22915,6 @@ snapshots:
       whatwg-url: 14.2.0
       ws: 8.21.0
       xml-name-validator: 5.0.0
-    optionalDependencies:
-      canvas: 2.11.2
     transitivePeerDependencies:
       - bufferutil
       - supports-color
@@ -22736,14 +23351,18 @@ snapshots:
 
   lru-cache@7.18.3: {}
 
-  lucide-react@0.446.0(react@19.2.6):
+  lucide-react@0.446.0(react@18.3.1):
     dependencies:
-      react: 19.2.6
+      react: 18.3.1
 
   lucide-react@0.513.0(react@19.2.6):
     dependencies:
       react: 19.2.6
 
+  lucide-react@1.17.0(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+
   lucide-react@1.17.0(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -22760,11 +23379,6 @@ snapshots:
 
   make-cancellable-promise@2.0.0: {}
 
-  make-dir@3.1.0:
-    dependencies:
-      semver: 6.3.1
-    optional: true
-
   make-dir@4.0.0:
     dependencies:
       semver: 7.8.2
@@ -23288,9 +23902,6 @@ snapshots:
 
   mimic-function@5.0.1: {}
 
-  mimic-response@2.1.0:
-    optional: true
-
   minimatch@10.2.5:
     dependencies:
       brace-expansion: 5.0.6
@@ -23326,22 +23937,8 @@ snapshots:
       xml: 1.0.1
       xml2js: 0.5.0
 
-  minipass@3.3.6:
-    dependencies:
-      yallist: 4.0.0
-    optional: true
-
-  minipass@5.0.0:
-    optional: true
-
   minipass@7.1.3: {}
 
-  minizlib@2.1.2:
-    dependencies:
-      minipass: 3.3.6
-      yallist: 4.0.0
-    optional: true
-
   mitt@3.0.1: {}
 
   mixin-deep@1.3.2:
@@ -23353,9 +23950,6 @@ snapshots:
     dependencies:
       minimist: 1.2.8
 
-  mkdirp@1.0.4:
-    optional: true
-
   moment@2.30.1: {}
 
   motion-dom@12.40.0:
@@ -23421,7 +24015,7 @@ snapshots:
     transitivePeerDependencies:
       - '@types/node'
 
-  mui-ethiopian-datepicker@0.3.2(ruap3lc7my4alz6jx6pekjrhou):
+  mui-ethiopian-datepicker@0.3.2(4b3af212eafdf0059f009b005d7e343d):
     dependencies:
       '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
       '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
@@ -23451,9 +24045,6 @@ snapshots:
       object-assign: 4.1.1
       thenify-all: 1.6.0
 
-  nan@2.28.0:
-    optional: true
-
   nanoid@3.3.12: {}
 
   nanomatch@1.2.13:
@@ -23497,7 +24088,7 @@ snapshots:
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
 
-  next@14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+  next@14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
     dependencies:
       '@next/env': 14.2.35
       '@swc/helpers': 0.5.5
@@ -23505,9 +24096,9 @@ snapshots:
       caniuse-lite: 1.0.30001797
       graceful-fs: 4.2.11
       postcss: 8.4.31
-      react: 19.2.6
-      react-dom: 19.2.6(react@19.2.6)
-      styled-jsx: 5.1.1(babel-plugin-macros@3.1.0)(react@19.2.6)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      styled-jsx: 5.1.1(babel-plugin-macros@3.1.0)(react@18.3.1)
     optionalDependencies:
       '@next/swc-darwin-arm64': 14.2.33
       '@next/swc-darwin-x64': 14.2.33
@@ -23549,11 +24140,6 @@ snapshots:
 
   node-fetch-native@1.6.7: {}
 
-  node-fetch@2.7.0:
-    dependencies:
-      whatwg-url: 5.0.0
-    optional: true
-
   node-fetch@3.3.2:
     dependencies:
       data-uri-to-buffer: 4.0.1
@@ -23573,11 +24159,6 @@ snapshots:
 
   node-releases@2.0.47: {}
 
-  nopt@5.0.0:
-    dependencies:
-      abbrev: 1.1.1
-    optional: true
-
   normalize-path@3.0.0: {}
 
   normalize-svg-path@1.1.0:
@@ -23597,14 +24178,6 @@ snapshots:
       path-key: 4.0.0
       unicorn-magic: 0.3.0
 
-  npmlog@5.0.1:
-    dependencies:
-      are-we-there-yet: 2.0.0
-      console-control-strings: 1.1.0
-      gauge: 3.0.2
-      set-blocking: 2.0.0
-    optional: true
-
   nth-check@2.1.1:
     dependencies:
       boolbase: 1.0.0
@@ -23900,9 +24473,6 @@ snapshots:
 
   path-type@4.0.0: {}
 
-  path2d-polyfill@2.0.1:
-    optional: true
-
   path@0.12.7:
     dependencies:
       process: 0.11.10
@@ -23923,14 +24493,6 @@ snapshots:
       pako: 1.0.11
       tslib: 1.14.1
 
-  pdfjs-dist@3.11.174:
-    optionalDependencies:
-      canvas: 2.11.2
-      path2d-polyfill: 2.0.1
-    transitivePeerDependencies:
-      - encoding
-      - supports-color
-
   pdfjs-dist@5.4.296:
     optionalDependencies:
       '@napi-rs/canvas': 0.1.100
@@ -24213,9 +24775,9 @@ snapshots:
 
   pure-rand@6.1.0: {}
 
-  qrcode.react@3.2.0(react@19.2.6):
+  qrcode.react@3.2.0(react@18.3.1):
     dependencies:
-      react: 19.2.6
+      react: 18.3.1
 
   qrcode@1.5.4:
     dependencies:
@@ -24257,6 +24819,69 @@ snapshots:
       parchment: 3.0.0
       quill-delta: 5.1.0
 
+  radix-ui@1.5.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+    dependencies:
+      '@radix-ui/primitive': 1.1.4
+      '@radix-ui/react-accessible-icon': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-accordion': 1.2.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-alert-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-arrow': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-aspect-ratio': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-avatar': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-checkbox': 1.3.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-collapsible': 1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context-menu': 2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-dropdown-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-form': 0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-hover-card': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-label': 2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-menubar': 1.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-navigation-menu': 1.2.15(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-one-time-password-field': 0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-password-toggle-field': 0.1.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-popover': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-progress': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-radio-group': 1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-scroll-area': 1.2.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-select': 2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-separator': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slider': 1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-switch': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-tabs': 1.1.14(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-toast': 1.2.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-toggle': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-toggle-group': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-toolbar': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-tooltip': 1.2.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-escape-keydown': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
   radix-ui@1.5.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -24385,14 +25010,28 @@ snapshots:
       date-fns: 3.6.0
       react: 19.2.6
 
+  react-day-picker@9.14.0(react@18.3.1):
+    dependencies:
+      '@date-fns/tz': 1.5.0
+      '@tabby_ai/hijri-converter': 1.0.5
+      date-fns: 4.4.0
+      date-fns-jalali: 4.1.0-0
+      react: 18.3.1
+
   react-day-picker@9.14.0(react@19.2.6):
     dependencies:
       '@date-fns/tz': 1.5.0
       '@tabby_ai/hijri-converter': 1.0.5
-      date-fns: 3.6.0
+      date-fns: 4.4.0
       date-fns-jalali: 4.1.0-0
       react: 19.2.6
 
+  react-dom@18.3.1(react@18.3.1):
+    dependencies:
+      loose-envify: 1.4.0
+      react: 18.3.1
+      scheduler: 0.23.2
+
   react-dom@19.2.6(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -24405,6 +25044,10 @@ snapshots:
       prop-types: 15.8.1
       react: 19.2.6
 
+  react-hook-form@7.77.0(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+
   react-hook-form@7.77.0(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -24477,6 +25120,11 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  react-number-format@5.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
   react-number-format@5.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -24496,16 +25144,13 @@ snapshots:
       make-cancellable-promise: 2.0.0
       make-event-props: 2.0.0
       merge-refs: 2.0.0(@types/react@18.3.31)
-      pdfjs-dist: 3.11.174
+      pdfjs-dist: 5.4.296
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
       tiny-invariant: 1.3.3
       warning: 4.0.3
     optionalDependencies:
       '@types/react': 18.3.31
-    transitivePeerDependencies:
-      - encoding
-      - supports-color
 
   react-phone-number-input@3.4.17(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
@@ -24536,6 +25181,14 @@ snapshots:
 
   react-refresh@0.17.0: {}
 
+  react-remove-scroll-bar@2.3.8(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      react-style-singleton: 2.2.3(@types/react@18.3.31)(react@18.3.1)
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   react-remove-scroll-bar@2.3.8(@types/react@18.3.31)(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -24544,6 +25197,17 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
+  react-remove-scroll@2.7.2(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      react-remove-scroll-bar: 2.3.8(@types/react@18.3.31)(react@18.3.1)
+      react-style-singleton: 2.2.3(@types/react@18.3.31)(react@18.3.1)
+      tslib: 2.8.1
+      use-callback-ref: 1.3.3(@types/react@18.3.31)(react@18.3.1)
+      use-sidecar: 1.1.3(@types/react@18.3.31)(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   react-remove-scroll@2.7.2(@types/react@18.3.31)(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -24603,13 +25267,21 @@ snapshots:
     dependencies:
       react-dom: 19.2.6(react@19.2.6)
 
-  react-smooth@4.0.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+  react-smooth@4.0.4(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
     dependencies:
       fast-equals: 5.4.0
       prop-types: 15.8.1
-      react: 19.2.6
-      react-dom: 19.2.6(react@19.2.6)
-      react-transition-group: 4.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      react-transition-group: 4.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+
+  react-style-singleton@2.2.3(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      get-nonce: 1.0.1
+      react: 18.3.1
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 18.3.31
 
   react-style-singleton@2.2.3(@types/react@18.3.31)(react@19.2.6):
     dependencies:
@@ -24628,6 +25300,15 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
+  react-transition-group@4.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+    dependencies:
+      '@babel/runtime': 7.29.7
+      dom-helpers: 5.2.1
+      loose-envify: 1.4.0
+      prop-types: 15.8.1
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
   react-transition-group@4.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       '@babel/runtime': 7.29.7
@@ -24637,6 +25318,10 @@ snapshots:
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
 
+  react@18.3.1:
+    dependencies:
+      loose-envify: 1.4.0
+
   react@19.2.6: {}
 
   read-cache@1.0.0:
@@ -24699,15 +25384,15 @@ snapshots:
     dependencies:
       decimal.js-light: 2.5.1
 
-  recharts@2.15.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
+  recharts@2.15.4(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
     dependencies:
       clsx: 2.1.1
       eventemitter3: 4.0.7
       lodash: 4.18.1
-      react: 19.2.6
-      react-dom: 19.2.6(react@19.2.6)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
       react-is: 18.3.1
-      react-smooth: 4.0.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-smooth: 4.0.4(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       recharts-scale: 0.4.5
       tiny-invariant: 1.3.3
       victory-vendor: 36.9.2
@@ -25005,6 +25690,10 @@ snapshots:
     dependencies:
       xmlchars: 2.2.0
 
+  scheduler@0.23.2:
+    dependencies:
+      loose-envify: 1.4.0
+
   scheduler@0.25.0-rc-603e6108-20241029: {}
 
   scheduler@0.27.0: {}
@@ -25216,16 +25905,6 @@ snapshots:
 
   signature_pad@2.3.2: {}
 
-  simple-concat@1.0.1:
-    optional: true
-
-  simple-get@3.1.1:
-    dependencies:
-      decompress-response: 4.2.1
-      once: 1.4.0
-      simple-concat: 1.0.1
-    optional: true
-
   sisteransi@1.0.5: {}
 
   slash@3.0.0: {}
@@ -25629,10 +26308,10 @@ snapshots:
     transitivePeerDependencies:
       - '@babel/core'
 
-  styled-jsx@5.1.1(babel-plugin-macros@3.1.0)(react@19.2.6):
+  styled-jsx@5.1.1(babel-plugin-macros@3.1.0)(react@18.3.1):
     dependencies:
       client-only: 0.0.1
-      react: 19.2.6
+      react: 18.3.1
     optionalDependencies:
       babel-plugin-macros: 3.1.0
 
@@ -25787,16 +26466,6 @@ snapshots:
       - bare-buffer
       - react-native-b4a
 
-  tar@6.2.1:
-    dependencies:
-      chownr: 2.0.0
-      fs-minipass: 2.1.0
-      minipass: 5.0.0
-      minizlib: 2.1.2
-      mkdirp: 1.0.4
-      yallist: 4.0.0
-    optional: true
-
   teex@1.0.1:
     dependencies:
       streamx: 2.27.0
@@ -25954,9 +26623,6 @@ snapshots:
     dependencies:
       tldts: 7.4.2
 
-  tr46@0.0.3:
-    optional: true
-
   tr46@5.1.1:
     dependencies:
       punycode: 2.3.1
@@ -26384,6 +27050,13 @@ snapshots:
       punycode: 1.4.1
       qs: 6.15.2
 
+  use-callback-ref@1.3.3(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   use-callback-ref@1.3.3(@types/react@18.3.31)(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -26416,6 +27089,14 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
+  use-sidecar@1.1.3(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      detect-node-es: 1.1.0
+      react: 18.3.1
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
   use-sidecar@1.1.3(@types/react@18.3.31)(react@19.2.6):
     dependencies:
       detect-node-es: 1.1.0
@@ -26424,6 +27105,11 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
+  use-sync-external-store@1.6.0(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+    optional: true
+
   use-sync-external-store@1.6.0(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -26600,7 +27286,7 @@ snapshots:
       lightningcss: 1.32.0
       terser: 5.48.0
 
-  vitest@2.1.9(@types/node@22.20.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(terser@5.48.0):
+  vitest@2.1.9(@types/node@22.20.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(terser@5.48.0):
     dependencies:
       '@vitest/expect': 2.1.9
       '@vitest/mocker': 2.1.9(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(vite@5.4.21(@types/node@22.20.1)(lightningcss@1.32.0)(terser@5.48.0))
@@ -26624,7 +27310,7 @@ snapshots:
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 22.20.1
-      jsdom: 25.0.1(canvas@2.11.2)
+      jsdom: 25.0.1
     transitivePeerDependencies:
       - less
       - lightningcss
@@ -26636,7 +27322,7 @@ snapshots:
       - supports-color
       - terser
 
-  vitest@2.1.9(@types/node@24.13.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0):
+  vitest@2.1.9(@types/node@24.13.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0):
     dependencies:
       '@vitest/expect': 2.1.9
       '@vitest/mocker': 2.1.9(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(vite@5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0))
@@ -26660,7 +27346,7 @@ snapshots:
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 24.13.1
-      jsdom: 25.0.1(canvas@2.11.2)
+      jsdom: 25.0.1
     transitivePeerDependencies:
       - less
       - lightningcss
@@ -26724,9 +27410,6 @@ snapshots:
 
   webdriver-bidi-protocol@0.4.1: {}
 
-  webidl-conversions@3.0.1:
-    optional: true
-
   webidl-conversions@7.0.0: {}
 
   webpack-node-externals@3.0.0: {}
@@ -26785,12 +27468,6 @@ snapshots:
       tr46: 5.1.1
       webidl-conversions: 7.0.0
 
-  whatwg-url@5.0.0:
-    dependencies:
-      tr46: 0.0.3
-      webidl-conversions: 3.0.1
-    optional: true
-
   which-boxed-primitive@1.1.1:
     dependencies:
       is-bigint: 1.1.0
@@ -26847,11 +27524,6 @@ snapshots:
       siginfo: 2.0.0
       stackback: 0.0.2
 
-  wide-align@1.1.5:
-    dependencies:
-      string-width: 4.2.3
-    optional: true
-
   wmf@1.0.2: {}
 
   word-wrap@1.2.5: {}
@@ -26938,9 +27610,6 @@ snapshots:
 
   yallist@3.1.1: {}
 
-  yallist@4.0.0:
-    optional: true
-
   yaml@1.10.3: {}
 
   yaml@2.9.0: {}
@@ -27032,6 +27701,13 @@ snapshots:
 
   zod@4.4.3: {}
 
+  zustand@5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@18.3.1)(use-sync-external-store@1.6.0(react@18.3.1)):
+    optionalDependencies:
+      '@types/react': 18.3.31
+      immer: 11.1.8
+      react: 18.3.1
+      use-sync-external-store: 1.6.0(react@18.3.1)
+
   zustand@5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@19.2.6)(use-sync-external-store@1.6.0(react@19.2.6)):
     optionalDependencies:
       '@types/react': 18.3.31
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 14f686558..fe5740e5f 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -26,3 +26,10 @@ allowBuilds:
   tesseract.js: true
   uglifyjs-webpack-plugin: true
   unrs-resolver: false
+
+overrides:
+  date-fns: ^3.6.0
+  pdfjs-dist: ^3.11.174
+  react: 19.2.6
+  react-dom: 19.2.6
+  typeorm: 0.3.30

From 4bf1aa80530c7c4e8ce0ecb1ff9547c8355b6136 Mon Sep 17 00:00:00 2001
From: ghost2023 <nathnaelwonisha@gmail.com>
Date: Wed, 12 Aug 2026 10:28:56 +0300
Subject: [PATCH 031/174] chore: deps

---
 pnpm-lock.yaml | 2017 +++++++++++++++++-------------------------------
 1 file changed, 687 insertions(+), 1330 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7f59d43c5..7efcb2c11 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4,6 +4,13 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+overrides:
+  date-fns: ^3.6.0
+  pdfjs-dist: ^3.11.174
+  react: 19.2.6
+  react-dom: 19.2.6
+  typeorm: 0.3.30
+
 importers:
 
   .:
@@ -154,7 +161,7 @@ importers:
         specifier: ^4.8.3
         version: 4.8.3
       typeorm:
-        specifier: ^0.3.30
+        specifier: 0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
     devDependencies:
       '@edr/eslint-config':
@@ -556,7 +563,7 @@ importers:
         version: 10.5.0(postcss@8.5.15)
       jsdom:
         specifier: ^25.0.1
-        version: 25.0.1
+        version: 25.0.1(canvas@2.11.2)
       postcss:
         specifier: ^8.4.47
         version: 8.5.15
@@ -571,7 +578,7 @@ importers:
         version: 5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0)
       vitest:
         specifier: ^2.1.2
-        version: 2.1.9(@types/node@24.13.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0)
+        version: 2.1.9(@types/node@24.13.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0)
 
   apps/edr-freight-web/portal:
     dependencies:
@@ -695,7 +702,7 @@ importers:
         version: 10.5.0(postcss@8.5.15)
       jsdom:
         specifier: ^25.0.1
-        version: 25.0.1
+        version: 25.0.1(canvas@2.11.2)
       postcss:
         specifier: ^8.4.47
         version: 8.5.15
@@ -710,7 +717,7 @@ importers:
         version: 5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0)
       vitest:
         specifier: ^2.1.2
-        version: 2.1.9(@types/node@24.13.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0)
+        version: 2.1.9(@types/node@24.13.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0)
 
   apps/edr-gps-tracker:
     dependencies:
@@ -742,7 +749,7 @@ importers:
         specifier: ^7.8.1
         version: 7.8.2
       typeorm:
-        specifier: ^0.3.30
+        specifier: 0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
     devDependencies:
       '@edr/eslint-config':
@@ -893,7 +900,7 @@ importers:
         specifier: ^4.2.0
         version: 4.2.0
       typeorm:
-        specifier: ^0.3.30
+        specifier: 0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
       uuid:
         specifier: ^10.0.0
@@ -970,7 +977,7 @@ importers:
         version: link:../../../packages/ui-common
       '@tanstack/react-query':
         specifier: ^5.59.0
-        version: 5.101.0(react@18.3.1)
+        version: 5.101.0(react@19.2.6)
       axios:
         specifier: ^1.7.7
         version: 1.17.0
@@ -978,32 +985,32 @@ importers:
         specifier: ^2.1.1
         version: 2.1.1
       date-fns:
-        specifier: ^3.0.0
+        specifier: ^3.6.0
         version: 3.6.0
       lucide-react:
         specifier: ^0.446.0
-        version: 0.446.0(react@18.3.1)
+        version: 0.446.0(react@19.2.6)
       next:
         specifier: ^14.2.0
-        version: 14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       react:
-        specifier: ^18.3.1
-        version: 18.3.1
+        specifier: 19.2.6
+        version: 19.2.6
       react-day-picker:
         specifier: ^9.14.0
-        version: 9.14.0(react@18.3.1)
+        version: 9.14.0(react@19.2.6)
       react-dom:
-        specifier: ^18.3.1
-        version: 18.3.1(react@18.3.1)
+        specifier: 19.2.6
+        version: 19.2.6(react@19.2.6)
       recharts:
         specifier: ^2.12.0
-        version: 2.15.4(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 2.15.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       socket.io-client:
         specifier: ^4.8.3
         version: 4.8.3
       zustand:
         specifier: ^5.0.0
-        version: 5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@18.3.1)(use-sync-external-store@1.6.0(react@18.3.1))
+        version: 5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@19.2.6)(use-sync-external-store@1.6.0(react@19.2.6))
     devDependencies:
       '@types/node':
         specifier: ^20.0.0
@@ -1043,10 +1050,10 @@ importers:
         version: link:../../../packages/ui-common
       '@hookform/resolvers':
         specifier: ^3.3.4
-        version: 3.10.0(react-hook-form@7.77.0(react@18.3.1))
+        version: 3.10.0(react-hook-form@7.77.0(react@19.2.6))
       '@tanstack/react-query':
         specifier: ^5.59.0
-        version: 5.101.0(react@18.3.1)
+        version: 5.101.0(react@19.2.6)
       '@types/qrcode':
         specifier: ^1.5.6
         version: 1.5.6
@@ -1057,7 +1064,7 @@ importers:
         specifier: ^2.1.1
         version: 2.1.1
       date-fns:
-        specifier: ^3.0.0
+        specifier: ^3.6.0
         version: 3.6.0
       jspdf:
         specifier: ^4.2.1
@@ -1067,25 +1074,25 @@ importers:
         version: 5.0.8(jspdf@4.2.1)
       lucide-react:
         specifier: ^0.446.0
-        version: 0.446.0(react@18.3.1)
+        version: 0.446.0(react@19.2.6)
       next:
         specifier: ^14.2.0
-        version: 14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       qrcode:
         specifier: ^1.5.4
         version: 1.5.4
       qrcode.react:
         specifier: ^3.1.0
-        version: 3.2.0(react@18.3.1)
+        version: 3.2.0(react@19.2.6)
       react:
-        specifier: ^18.3.1
-        version: 18.3.1
+        specifier: 19.2.6
+        version: 19.2.6
       react-dom:
-        specifier: ^18.3.1
-        version: 18.3.1(react@18.3.1)
+        specifier: 19.2.6
+        version: 19.2.6(react@19.2.6)
       react-hook-form:
         specifier: ^7.51.0
-        version: 7.77.0(react@18.3.1)
+        version: 7.77.0(react@19.2.6)
       socket.io-client:
         specifier: ^4.8.3
         version: 4.8.3
@@ -1094,7 +1101,7 @@ importers:
         version: 3.25.76
       zustand:
         specifier: ^5.0.0
-        version: 5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@18.3.1)(use-sync-external-store@1.6.0(react@18.3.1))
+        version: 5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@19.2.6)(use-sync-external-store@1.6.0(react@19.2.6))
     devDependencies:
       '@types/node':
         specifier: ^20.0.0
@@ -1276,7 +1283,7 @@ importers:
         version: 5.9.3
       vitest:
         specifier: ^2.1.2
-        version: 2.1.9(@types/node@22.20.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(terser@5.48.0)
+        version: 2.1.9(@types/node@22.20.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(terser@5.48.0)
 
   packages/api-common:
     dependencies:
@@ -1306,7 +1313,7 @@ importers:
         specifier: ^7.8.1
         version: 7.8.2
       typeorm:
-        specifier: ^0.3.20
+        specifier: 0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
       typescript:
         specifier: ^5.5.4
@@ -1374,7 +1381,7 @@ importers:
         specifier: ^29.2.5
         version: 29.4.11(@babel/core@7.29.7)(@jest/transform@29.7.0)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(jest-util@29.7.0)(jest@29.7.0(@types/node@20.19.42)(babel-plugin-macros@3.1.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))(typescript@5.9.3)
       typeorm:
-        specifier: ^0.3.20
+        specifier: 0.3.30
         version: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
       typescript:
         specifier: ^5.5.4
@@ -1436,10 +1443,10 @@ importers:
         version: link:../types
       '@mantine/core':
         specifier: ^9.3.0
-        version: 9.3.0(@mantine/hooks@9.3.0(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@tanstack/react-table':
         specifier: ^8.21.3
-        version: 8.21.3(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 8.21.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       class-variance-authority:
         specifier: ^0.7.1
         version: 0.7.1
@@ -1448,10 +1455,10 @@ importers:
         version: 2.1.1
       lucide-react:
         specifier: ^1.14.0
-        version: 1.17.0(react@18.3.1)
+        version: 1.17.0(react@19.2.6)
       radix-ui:
         specifier: ^1.4.3
-        version: 1.5.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 1.5.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       shadcn:
         specifier: ^4.7.0
         version: 4.10.0(@types/node@24.13.1)(babel-plugin-macros@3.1.0)(typescript@5.9.3)
@@ -1481,11 +1488,11 @@ importers:
         specifier: ^8.4.47
         version: 8.5.15
       react:
-        specifier: ^18.3.1
-        version: 18.3.1
+        specifier: 19.2.6
+        version: 19.2.6
       react-dom:
-        specifier: ^18.3.1
-        version: 18.3.1(react@18.3.1)
+        specifier: 19.2.6
+        version: 19.2.6(react@19.2.6)
       tailwindcss:
         specifier: ^4.3.0
         version: 4.3.0
@@ -1999,7 +2006,7 @@ packages:
     resolution: {integrity: sha512-O000MLDBDdk/EohJPFUqvnp4qnHeYkVP5B0xEG0D/L7cOKP9kefu2DXn8dj74cQfsEzUqh+sr1RzFqiL1o+PpA==}
     peerDependencies:
       '@types/react': '*'
-      react: '>=16.8.0'
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -2015,7 +2022,7 @@ packages:
     peerDependencies:
       '@emotion/react': ^11.0.0-rc.0
       '@types/react': '*'
-      react: '>=16.8.0'
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -2032,7 +2039,7 @@ packages:
   '@emotion/use-insertion-effect-with-fallbacks@1.2.0':
     resolution: {integrity: sha512-yJMtVdH59sxi/aVJBpk9FQq+OR8ll5GT8oWd57UpeaKEVGab41JWaCFA7FRLoMLloOZF/c/wsPoe+bfGmRKgDg==}
     peerDependencies:
-      react: '>=16.8.0'
+      react: 19.2.6
 
   '@emotion/utils@1.4.2':
     resolution: {integrity: sha512-3vLclRofFziIa3J2wDh9jjbkUz9qk5Vi3IZ/FSTKViB0k+ef0fPV7dYrUIugbgupYDx7v9ud/SjrtEP8Y4xLoA==}
@@ -2218,20 +2225,20 @@ packages:
   '@floating-ui/react-dom@2.1.8':
     resolution: {integrity: sha512-cC52bHwM/n/CxS87FH0yWdngEZrjdtLW/qVruo68qg+prK7ZQ4YGdut2GyDVpoGeAYe/h899rVeOVm6Oi40k2A==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@floating-ui/react@0.26.28':
     resolution: {integrity: sha512-yORQuuAtVpiRjpMhdc0wJj06b9JFjrYF4qp96j++v2NBpbi6SEGF7donUJ3TMieerQ6qVkAv1tgr7L4r5roTqw==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@floating-ui/react@0.27.19':
     resolution: {integrity: sha512-31B8h5mm8YxotlE7/AU/PhNAl8eWxAmjL/v2QOxroDNkTFLk3Uu82u63N3b6TXa4EGJeeZLVcd/9AlNlVqzeog==}
     peerDependencies:
-      react: '>=17.0.0'
-      react-dom: '>=17.0.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@floating-ui/utils@0.2.11':
     resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
@@ -2256,8 +2263,8 @@ packages:
   '@hello-pangea/dnd@18.0.1':
     resolution: {integrity: sha512-xojVWG8s/TGrKT1fC8K2tIWeejJYTAeJuj36zM//yEm/ZrnZUSFGS15BpO+jGZT1ybWvyXmeDJwPYb4dhWlbZQ==}
     peerDependencies:
-      react: ^18.0.0 || ^19.0.0
-      react-dom: ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@hono/node-server@1.19.14':
     resolution: {integrity: sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==}
@@ -2268,8 +2275,8 @@ packages:
   '@hookform/devtools@4.4.0':
     resolution: {integrity: sha512-Mtlic+uigoYBPXlfvPBfiYYUZuyMrD3pTjDpVIhL6eCZTvQkHsKBSKeZCvXWUZr8fqrkzDg27N+ZuazLKq6Vmg==}
     peerDependencies:
-      react: ^16.8.0 || ^17 || ^18 || ^19
-      react-dom: ^16.8.0 || ^17 || ^18 || ^19
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@hookform/resolvers@3.10.0':
     resolution: {integrity: sha512-79Dv+3mDF7i+2ajj7SkypSKHhl1cbln1OGavqrsF7p6mbUv11xpqpacPsGDCTRvCSjEEIez2ef1NveSVL3b0Ag==}
@@ -2677,8 +2684,8 @@ packages:
   '@lexical/devtools-core@0.48.0':
     resolution: {integrity: sha512-4kvKWW6ebgQnJNLXPLmw7dqgSChvzYIBNYtfuR6c48Sw+V/QXQTWqfIUbCIe5X4uG8EEXd5O/udXaJx7GBuP+w==}
     peerDependencies:
-      react: '>=18.x'
-      react-dom: '>=18.x'
+      react: 19.2.6
+      react-dom: 19.2.6
       typescript: '>=5.2'
     peerDependenciesMeta:
       typescript:
@@ -2783,8 +2790,8 @@ packages:
   '@lexical/react@0.48.0':
     resolution: {integrity: sha512-uVh9/QSrbtjLjVbxfJ+sfiMyhUq/rv7H6uBEVDDIw1rkZJSDY1fvf/CX+dyKgwcDFjKQZ8/9i5f9UCVPeQ01hA==}
     peerDependencies:
-      react: '>=18.x'
-      react-dom: '>=18.x'
+      react: 19.2.6
+      react-dom: 19.2.6
       typescript: '>=5.2'
       yjs: '>=13.5.22'
     peerDependenciesMeta:
@@ -2896,7 +2903,7 @@ packages:
   '@lottiefiles/react-lottie-player@3.6.0':
     resolution: {integrity: sha512-WK5TriLJT93VF3w4IjSVyveiedraZCnDhKzCPhpbeLgQeMi6zufxa3dXNc4HmAFRXq+LULPAy+Idv1rAfkReMA==}
     peerDependencies:
-      react: 16 - 19
+      react: 19.2.6
 
   '@lukeed/csprng@1.1.0':
     resolution: {integrity: sha512-Z7C/xXCiGWsg0KuKsHTKJxbWhpI3Vs5GwLfOean7MGyVFGqdRgBbAjOCh6u4bbjPc/8MJ2pZmK/0DLdCbivLDA==}
@@ -2907,30 +2914,30 @@ packages:
     peerDependencies:
       '@mantine/core': 7.17.8
       '@mantine/hooks': 7.17.8
-      react: ^18.x || ^19.x
-      react-dom: ^18.x || ^19.x
+      react: 19.2.6
+      react-dom: 19.2.6
       recharts: ^2.13.3
 
   '@mantine/core@7.17.8':
     resolution: {integrity: sha512-42sfdLZSCpsCYmLCjSuntuPcDg3PLbakSmmYfz5Auea8gZYLr+8SS5k647doVu0BRAecqYOytkX2QC5/u/8VHw==}
     peerDependencies:
       '@mantine/hooks': 7.17.8
-      react: ^18.x || ^19.x
-      react-dom: ^18.x || ^19.x
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mantine/core@9.3.0':
     resolution: {integrity: sha512-mHVCm61YVW9ipy9eHiKMqsRUm3TkOErbdw7zHs0HRw5g403nf7tSTqNGvaYE+aX1Py874qMkrUzeQfj4bjiiBA==}
     peerDependencies:
       '@mantine/hooks': 9.3.0
-      react: ^19.2.0
-      react-dom: ^19.2.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mantine/core@9.3.2':
     resolution: {integrity: sha512-Upy/Z9Sj2eW2dGrFgUy/2kISVsxMTBYTDfP2TFdsIA3PdPSBkdqfSOPX/ug3d3F3a4bnwQSqcO6+aPEpBIh8dg==}
     peerDependencies:
       '@mantine/hooks': 9.3.2
-      react: ^19.2.0
-      react-dom: ^19.2.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mantine/dates@7.17.8':
     resolution: {integrity: sha512-KYog/YL83PnsMef7EZagpOFq9I2gfnK0eYSzC8YvV9Mb6t/x9InqRssGWVb0GIr+TNILpEkhKoGaSKZNy10Q1g==}
@@ -2938,8 +2945,8 @@ packages:
       '@mantine/core': 7.17.8
       '@mantine/hooks': 7.17.8
       dayjs: '>=1.0.0'
-      react: ^18.x || ^19.x
-      react-dom: ^18.x || ^19.x
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mantine/dates@9.3.2':
     resolution: {integrity: sha512-MzHrXGoOb3rCnHBlsI/BPAjC8K5tZ4f8pzg66tsTsupVCQBaBpHSVatQwNRJ6K2JC9pyCyTa9BL803C8AiWycA==}
@@ -2947,36 +2954,40 @@ packages:
       '@mantine/core': 9.3.2
       '@mantine/hooks': 9.3.2
       dayjs: '>=1.0.0'
-      react: ^19.2.0
-      react-dom: ^19.2.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mantine/hooks@7.17.8':
     resolution: {integrity: sha512-96qygbkTjRhdkzd5HDU8fMziemN/h758/EwrFu7TlWrEP10Vw076u+Ap/sG6OT4RGPZYYoHrTlT+mkCZblWHuw==}
     peerDependencies:
-      react: ^18.x || ^19.x
+      react: 19.2.6
 
   '@mantine/hooks@9.3.0':
     resolution: {integrity: sha512-QoSr9WI4WsKWrM3qFYYizHUn3+n+CVcFMYe4sdlnmFPStvs6BacPODKJSbFlYl73Z20t82JIy0eKqt4noHQI2g==}
     peerDependencies:
-      react: ^19.2.0
+      react: 19.2.6
 
   '@mantine/hooks@9.3.2':
     resolution: {integrity: sha512-jOjpUe0x1A/k3XUiu2/aaSCasXRI5ZKZOucm3ypwsvm9F2u8C1xzwBvagrzlbNZwJRF5vNYIJtCaT7NunPyc0A==}
     peerDependencies:
-      react: ^19.2.0
+      react: 19.2.6
 
   '@mantine/notifications@7.17.8':
     resolution: {integrity: sha512-/YK16IZ198W6ru/IVecCtHcVveL08u2c8TbQTu/2p26LSIM9AbJhUkrU6H+AO0dgVVvmdmNdvPxcJnfq3S9TMg==}
     peerDependencies:
       '@mantine/core': 7.17.8
       '@mantine/hooks': 7.17.8
-      react: ^18.x || ^19.x
-      react-dom: ^18.x || ^19.x
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mantine/store@7.17.8':
     resolution: {integrity: sha512-/FrB6PAVH4NEjQ1dsc9qOB+VvVlSuyjf4oOOlM9gscPuapDP/79Ryq7JkhHYfS55VWQ/YUlY24hDI2VV+VptXg==}
     peerDependencies:
-      react: ^18.x || ^19.x
+      react: 19.2.6
+
+  '@mapbox/node-pre-gyp@1.0.11':
+    resolution: {integrity: sha512-Yhlar6v9WQgUp/He7BdgzOz8lqMQ8sU+jkCq7Wx8Myc5YFJLbEe7lgui/V7G1qB1DJykHSGwreceSaD60Y0PUQ==}
+    hasBin: true
 
   '@marijn/find-cluster-break@1.0.3':
     resolution: {integrity: sha512-FY+MKLBoTsLNJF/eLWaOsXGdz6uh3Iu1axjPf6TUq92IYumcTcXWHoS747JARLkcdlJ/Waiaxc5wQfFO8jC6NA==}
@@ -2985,15 +2996,15 @@ packages:
     resolution: {integrity: sha512-S/IPY8AjWTV2v1TGbEy5lsbQ5w+J2M2j2QDeswxP4FpNh2B49OPkpSqHbbX5GbV0YBlhfXJxtzwBJv/sQACufw==}
     engines: {node: '>=16'}
     peerDependencies:
-      react: '>= 18 || >= 19'
-      react-dom: '>= 18 || >= 19'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@mdxeditor/gurx@1.2.4':
     resolution: {integrity: sha512-9ZykIFYhKaXaaSPCs1cuI+FvYDegJjbKwmA4ASE/zY+hJY6EYqvoye4esiO85CjhOw9aoD/izD/CU78/egVqmg==}
     engines: {node: '>=16'}
     peerDependencies:
-      react: '>= 18 || >= 19'
-      react-dom: '>= 18 || >= 19'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@microsoft/tsdoc@0.15.1':
     resolution: {integrity: sha512-4aErSrCR/On/e5G2hDP0wjooqDdauzEbIq8hIkIe5pXV0rtWJZvdCEKL0ykZxex+IxIwBp0eGeV48hQN07dXtw==}
@@ -3021,8 +3032,8 @@ packages:
     deprecated: This package has been replaced by @base-ui/react
     peerDependencies:
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3036,7 +3047,7 @@ packages:
     peerDependencies:
       '@mui/material': ^5.0.0
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3048,8 +3059,8 @@ packages:
       '@emotion/react': ^11.5.0
       '@emotion/styled': ^11.3.0
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@emotion/react':
         optional: true
@@ -3063,7 +3074,7 @@ packages:
     engines: {node: '>=12.0.0'}
     peerDependencies:
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3074,7 +3085,7 @@ packages:
     peerDependencies:
       '@emotion/react': ^11.4.1
       '@emotion/styled': ^11.3.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@emotion/react':
         optional: true
@@ -3088,7 +3099,7 @@ packages:
       '@emotion/react': ^11.5.0
       '@emotion/styled': ^11.3.0
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@emotion/react':
         optional: true
@@ -3110,7 +3121,7 @@ packages:
     engines: {node: '>=12.0.0'}
     peerDependencies:
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3120,7 +3131,7 @@ packages:
     engines: {node: '>=14.0.0'}
     peerDependencies:
       '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3133,15 +3144,15 @@ packages:
       '@emotion/styled': ^11.8.1
       '@mui/material': ^5.8.6
       '@mui/system': ^5.8.0
-      date-fns: ^2.25.0 || ^3.2.0
+      date-fns: ^3.6.0
       date-fns-jalali: ^2.13.0-0
       dayjs: ^1.10.7
       luxon: ^3.0.2
       moment: ^2.29.4
       moment-hijri: ^2.1.2
       moment-jalaali: ^0.7.4 || ^0.8.0 || ^0.9.0 || ^0.10.0
-      react: ^17.0.0 || ^18.0.0
-      react-dom: ^17.0.0 || ^18.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@emotion/react':
         optional: true
@@ -3468,7 +3479,7 @@ packages:
       '@nestjs/core': ^10.0.0 || ^11.0.0
       reflect-metadata: ^0.1.13 || ^0.2.0
       rxjs: ^7.2.0
-      typeorm: ^0.3.0 || ^1.0.0-dev
+      typeorm: 0.3.30
 
   '@nestjs/websockets@11.1.27':
     resolution: {integrity: sha512-X3OgJt9KgYTvt9D7sNz9SOj3A1daAHy7DZrYhM1pky8Fh+erlKQH5IQ/tKm+GaJKA5M0srBUr1CMqjak/qNxOw==}
@@ -3712,7 +3723,7 @@ packages:
     peerDependencies:
       '@types/react': '>=16.8.0'
       posthog-js: '>=1.257.2'
-      react: '>=16.8.0'
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3772,8 +3783,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3785,8 +3796,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3798,8 +3809,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3811,8 +3822,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3824,8 +3835,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3837,8 +3848,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3850,8 +3861,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3863,8 +3874,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3876,8 +3887,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3888,7 +3899,7 @@ packages:
     resolution: {integrity: sha512-rYOP8OMnuuPMQF1uhPVlGNcCDlkokKqGFE3JcxFViIkAXP7EvFWUliJAstrapypaBLJNHbZL6jGhbVDGTwmVhA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3898,8 +3909,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3910,7 +3921,7 @@ packages:
     resolution: {integrity: sha512-QwH4PO5urrbO+FaGd5Aglg+YJgWTyyuZ3g/6mKvsqraLkglDdckw9JafgL5McL5VEJ6EPNduPaT3ZE9BttDAqg==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3920,8 +3931,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3932,7 +3943,7 @@ packages:
     resolution: {integrity: sha512-C3vFhbyi4SW3PmbAi6Awpu4OzJtd0MxGurvSsYtr7p7nM8RNB3VAF3CUmnp2j50knpkrRcB7+ycVXzgLgF6yNA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3942,8 +3953,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3955,8 +3966,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3967,7 +3978,7 @@ packages:
     resolution: {integrity: sha512-cot/aB/mOm0IYVYTTmQcEEK1M48lZWi8FlYe5nDPQQ8NYZUlXEFgncJ9p2Kzer3RKSrY7cTTpEMLZKNo9QoP5Q==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3977,8 +3988,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -3990,8 +4001,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4003,8 +4014,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4014,13 +4025,13 @@ packages:
   '@radix-ui/react-icons@1.3.2':
     resolution: {integrity: sha512-fyQIhGDhzfc9pK2kH6Pl9c4BDJGfMkPqkyIgYDthyNYoNg3wVhoJMMh19WS4Up/1KMPFVpNsT2q3WmXn2N1m6g==}
     peerDependencies:
-      react: ^16.x || ^17.x || ^18.x || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
 
   '@radix-ui/react-id@1.1.2':
     resolution: {integrity: sha512-orBC88futVpqCmhX1p4cvquNHsELQ+w+vBJnuj3ftETI5bJb0bZn3Tqu3SWN2IOcPycTnMGnhwoermvISt72sA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4030,8 +4041,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4043,8 +4054,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4056,8 +4067,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4069,8 +4080,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4082,8 +4093,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4095,8 +4106,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4108,8 +4119,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4121,8 +4132,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4134,8 +4145,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4147,8 +4158,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4160,8 +4171,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4173,8 +4184,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4186,8 +4197,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4199,8 +4210,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4212,8 +4223,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4225,8 +4236,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4238,8 +4249,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4251,8 +4262,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4263,7 +4274,7 @@ packages:
     resolution: {integrity: sha512-rCMO3QsIVKv5JTY5CVbo2MvO77SpEqqYc8AvRE7OWqRDOIqAKjsp+DrmnY9uc8NPdxB5E2z47HTYGeE2+NTptg==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4273,8 +4284,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4286,8 +4297,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4299,8 +4310,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4312,8 +4323,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4325,8 +4336,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4338,8 +4349,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4351,8 +4362,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4363,7 +4374,7 @@ packages:
     resolution: {integrity: sha512-xCso9j1/u8sEgP1RNHjFrXJLApL8LiqOkI1R4ywuN00rxWdYg4oQXuwKLS3i0j5NWLromUD27/4nlxj2UFVvIw==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4372,7 +4383,7 @@ packages:
     resolution: {integrity: sha512-PLzC90MS+ReootmjC597dvopoelpZ8Q61HJkDXZSExitIq7PL55vHNnesAHwguHK0aPfBnpdNzQtv1uliaqQrA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4381,7 +4392,7 @@ packages:
     resolution: {integrity: sha512-6c8ZqvPTWILEKnyVkP53EGRCcpnJiKTC21sS/6R1GF5xKyHJJWQEPfkqlcgUkdRQivd6tb23abUwe4ngWmY0JA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4390,7 +4401,7 @@ packages:
     resolution: {integrity: sha512-2uVLvLjgO7NZCWw01/FdqRwmA42J0BcjPMUCA+koFEOAb+zjqIP7SiFz/7zWPrKnVmSqr76Omq2ALyCuX4dhLw==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4399,7 +4410,7 @@ packages:
     resolution: {integrity: sha512-qwOiz4Tjo8CNnrOLAYUMXeZwDzXgXpvK4TKQPmWLECM9XoWvA6+0Z2/7Ag3A4ivjS4ovbLJPbskkxioFyBhr8A==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4408,7 +4419,7 @@ packages:
     resolution: {integrity: sha512-jrBWOxZITuGcnjRCM2t2U5ZPkCLxD+Ym6DjfssS5haTj2iiak/DOb64JeN6OdLfLgptb6/e2kKR+ZuTrGoZTPA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4417,7 +4428,7 @@ packages:
     resolution: {integrity: sha512-IGBQPtRFdhN6MQ8dbegVmBq1LVZluya3F1jWY+puIcQC3MHctRwTDSBWCkL/3ZcnMJLTMJ++Z+ktmvg0F89iCw==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4426,7 +4437,7 @@ packages:
     resolution: {integrity: sha512-d8a+bBY/FxikNPlgJJoaBHZX+zKVbWHYJGTLnLvveQgFSTntkGdEKv3JDtHrMS0DNYpllz2nRsTLGLKYttbpmw==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4435,7 +4446,7 @@ packages:
     resolution: {integrity: sha512-giWQp+4mxjBPt4KZ0MmyuykFNWfbDxKt4x+fPkRYmgRFJSbCZFzUglvMb/Kjn38tm10YP4ufiQZDx3zna4LU6w==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4445,8 +4456,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -4459,111 +4470,111 @@ packages:
   '@react-pdf-viewer/attachment@3.12.0':
     resolution: {integrity: sha512-mhwrYJSIpCvHdERpLUotqhMgSjhtF+BTY1Yb9Fnzpcq3gLZP+Twp5Rynq21tCrVdDizPaVY7SKu400GkgdMfZw==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/bookmark@3.12.0':
     resolution: {integrity: sha512-i7nEit8vIFMAES8RFGwprZ9cXOOZb9ZStPW6E6yuObJEXcvBj/ctsbBJGZxqUZOGklM0JoB7sjHyxAriHfe92A==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/core@3.12.0':
     resolution: {integrity: sha512-8MsdlQJ4jaw3GT+zpCHS33nwnvzpY0ED6DEahZg9WngG++A5RMhk8LSlxdHelwaFFHFiXBjmOaj2Kpxh50VQRg==}
     peerDependencies:
-      pdfjs-dist: ^2.16.105 || ^3.0.279
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      pdfjs-dist: ^3.11.174
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/default-layout@3.12.0':
     resolution: {integrity: sha512-K2fS4+TJynHxxCBFuIDiFuAw3nqOh4bkBgtVZ/2pGvnFn9lLg46YGLMnTXCQqtyZzzXYh696jmlFViun3is4pA==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/full-screen@3.12.0':
     resolution: {integrity: sha512-hQouJ26QUaRBCXNMU1aI1zpJn4l4PJRvlHhuE2dZYtLl37ycjl7vBCQYZW1FwnuxMWztZsY47R43DKaZORg0pg==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/get-file@3.12.0':
     resolution: {integrity: sha512-Uhq45n2RWlZ7Ec/BtBJ0WQESRciaYIltveDXHNdWvXgFdOS8XsvB+mnTh/wzm7Cfl9hpPyzfeezifdU9AkQgQg==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/open@3.12.0':
     resolution: {integrity: sha512-vhiDEYsiQLxvZkIKT9VPYHZ1BOnv46x9eCEmRWxO1DJ8fa/GRDTA9ivXmq/ap0dGEJs6t+epleCkCEfllLR/Yw==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/page-navigation@3.12.0':
     resolution: {integrity: sha512-tVEJ48Dd5kajV1nKkrPWijglJRNBiKBTyYDKVexhiRdTHUP1f6QQXiSyDgCUb0IGSZeJzOJb1h7ApKHe8OTtuw==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/print@3.12.0':
     resolution: {integrity: sha512-xJn76CgbU/M2iNaN7wLHTg+sdOekkRMfCakFLwPrE+SR7qD6NUF4vQQKJBSVCCK5bUijzb6cWfKGfo8VA72o4Q==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/properties@3.12.0':
     resolution: {integrity: sha512-dYTCHtVwFNkpDo7QxL2qk/8zAKndLwdD1FFxBftl6jIlQbtvNdxkFfkv1HcQING9Ic+7DBryOiD7W0ze4IERYg==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/rotate@3.12.0':
     resolution: {integrity: sha512-yaxaMYPChvNOjR8+AxRmj0kvojyJKPq4XHEcIB2lJJgBY1Zra3mliDUP3Nlb4yV8BS9+yBqWn9U9mtnopQD+tw==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/scroll-mode@3.12.0':
     resolution: {integrity: sha512-okII7Xqhl6cMvl1izdEvlXNJ+vJVq/qdg53hJIDYVgBCWskLk/cpjUg/ZonBxseG9lIDP3w2VO1McT8Gn11OAg==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/search@3.12.0':
     resolution: {integrity: sha512-jAkLpis49fsDDY/HrbUZIOIhzF5vynONQNA4INQKI38r/MjveblrkNv7qbr9j5lQ/WFic5+gD1e+Mtpf1/7DiA==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/selection-mode@3.12.0':
     resolution: {integrity: sha512-yysWEu2aCtBvzSgbhgI9kT5cq2hf0FU6Z+3B7MMXz14Kxyc3y18wUqxtgbvpFEfWF0bNUUq16JtWRljtxvZ83w==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/theme@3.12.0':
     resolution: {integrity: sha512-cdBi+wR1VOZ6URCcO9plmAZQu4ZGFcd7HJdBe7VIFiGyrvl9I/Of74ONLycnDImSuONt8D3uNjPBLieeaShVeg==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/thumbnail@3.12.0':
     resolution: {integrity: sha512-Vc8j3bO6wumWZV4o6pAbktPWKDSC9tQAzOCJ3cof541u4i44C11ccYC4W9aNcsMMUSO3bNwAGWtP8OFthV5akQ==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/toolbar@3.12.0':
     resolution: {integrity: sha512-qACTU3qXHgtNK8J+T13EWio+0liilj86SJ87BdapqXynhl720OKPlSKOQqskUGqg3oTUJAhrse9XG6SFdHJx+g==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf-viewer/zoom@3.12.0':
     resolution: {integrity: sha512-V0GUTyPM77+LzhoKX+T3XI10/HfGdqRTbgeP7ID60FCzcwu6kXWqJn5tzabjDKLTlFv8mJmn0aa/ppkIU97nfA==}
     peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@react-pdf/fns@3.1.3':
     resolution: {integrity: sha512-0I7pApDr1/RLAKbizuLy/IHTEa93LSPy/bEwYniboC3Xqnp6Od8xFJKbKEzGw2wh/5zKFFwl00g4t9RwgIMc3w==}
@@ -4586,7 +4597,7 @@ packages:
   '@react-pdf/reconciler@2.0.0':
     resolution: {integrity: sha512-7zaPRujpbHSmCpIrZ+b9HSTJHthcVZzX0Wx7RzvQGsGBUbHP4p6s5itXrAIOuQuPvDepoHGNOvf6xUuMVvdoyw==}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
 
   '@react-pdf/render@4.5.1':
     resolution: {integrity: sha512-IW/N4HWJWtioBXCf7n02IR24VJJ8gbdS3jGypf+vW/rSErEx3/URRzh9UK6Ma8Fpog9+T/W6GE2NHJ5AAKHhVA==}
@@ -4594,7 +4605,7 @@ packages:
   '@react-pdf/renderer@4.5.1':
     resolution: {integrity: sha512-5r1VQrE6FRLXX5wWUxwZzM24E2BJMo6g8AQWuS8WyPs9ugu5yMnb2g8/RpPYka/Z6J+RUEWc32wty2NoUJF42Q==}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
 
   '@react-pdf/stylesheet@6.2.1':
     resolution: {integrity: sha512-2+UEk+7e+z8baaWi2l5kPLWmwtJeOI+T5wW9GGeN3iDH7vd3kbTqOpN1yt9mmfNVZFxQsnDHpznFb5v5UF983A==}
@@ -4611,7 +4622,7 @@ packages:
   '@reduxjs/toolkit@2.12.0':
     resolution: {integrity: sha512-KiT+RzZbp6mQET+Mg+h2c97+9j1sNflUxQkIHI7Yuzf6Peu+OYpmkn6nbHWmLLWj+1ZODUJFwGZ7gx3L9R9EOw==}
     peerDependencies:
-      react: ^16.9.0 || ^17.0.0 || ^18 || ^19
+      react: 19.2.6
       react-redux: ^7.2.1 || ^8.1.3 || ^9.0.0
     peerDependenciesMeta:
       react:
@@ -4829,7 +4840,7 @@ packages:
   '@tabler/icons-react@3.44.0':
     resolution: {integrity: sha512-8+rvzBbVm/1Z3sG3x7GUNAaxIKxwgz8xaMhRs23nrCnMTKRFAhEC+82zAIFeAA0seXdrAGX5HFCkaLpGK2rVHg==}
     peerDependencies:
-      react: '>= 16'
+      react: 19.2.6
 
   '@tabler/icons@3.44.0':
     resolution: {integrity: sha512-Wn0AOZG9sg0L+bjfMqq4eNhC6pQjIrk94LvvWYNYkY8KH8wC3YILRzQlrnVJc4FUeMxH/AK97QsYCX35H3LndA==}
@@ -4946,32 +4957,32 @@ packages:
     resolution: {integrity: sha512-cpZA0+WqKXwrwMfiWZEGGF6QrIWVQFbhBtxqDF5sQsAfrFf47HIE6fiPbQU3wyAUEN2+7UNqLCQe7oG6m3f93w==}
     peerDependencies:
       '@tanstack/react-query': ^5.101.0
-      react: ^18 || ^19
+      react: 19.2.6
 
   '@tanstack/react-query@5.101.0':
     resolution: {integrity: sha512-rLlJXSpkqfizLWgkR5+eLeIk0MvTx/meEIR7LRjxic+qxiQP8zVjq7BqQkiCMNLQBlLfuOLqqr6KO5GtrDlmSg==}
     peerDependencies:
-      react: ^18 || ^19
+      react: 19.2.6
 
   '@tanstack/react-table@8.20.5':
     resolution: {integrity: sha512-WEHopKw3znbUZ61s9i0+i9g8drmDo6asTWbrQh8Us63DAk/M0FkmIqERew6P71HI75ksZ2Pxyuf4vvKh9rAkiA==}
     engines: {node: '>=12'}
     peerDependencies:
-      react: '>=16.8'
-      react-dom: '>=16.8'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@tanstack/react-table@8.21.3':
     resolution: {integrity: sha512-5nNMTSETP4ykGegmVkhjcS8tTLW6Vl4axfEGQN3v0zdHYbK4UfoqfPChclTrJ4EoK9QynqAu9oUf8VEmrpZ5Ww==}
     engines: {node: '>=12'}
     peerDependencies:
-      react: '>=16.8'
-      react-dom: '>=16.8'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@tanstack/react-virtual@3.11.2':
     resolution: {integrity: sha512-OuFzMXPF4+xZgx8UzJha0AieuMihhhaWG0tCqpp6tDzlFwOmNBPYMuLOtMJ1Tr4pXLHmgjcWhG6RlknY2oNTdQ==}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@tanstack/table-core@8.20.5':
     resolution: {integrity: sha512-P9dF7XbibHph2PFRz8gfBKEXEY/HJPOhym8CHmjF8y3q5mWpKx9xtZapXQUWCgkqvsK0R46Azuz+VaxD4Xl+Tg==}
@@ -4987,8 +4998,8 @@ packages:
   '@tinymce/tinymce-react@6.3.0':
     resolution: {integrity: sha512-E++xnn0XzDzpKr40jno2Kj7umfAE6XfINZULEBBeNjTMvbACWzA6CjiR6V8eTDc9yVmdVhIPqVzV4PqD5TZ/4g==}
     peerDependencies:
-      react: ^19.0.0 || ^18.0.0 || ^17.0.1 || ^16.7.0
-      react-dom: ^19.0.0 || ^18.0.0 || ^17.0.1 || ^16.7.0
+      react: 19.2.6
+      react-dom: 19.2.6
       tinymce: ^8.0.0 || ^7.0.0 || ^6.0.0 || ^5.5.1
     peerDependenciesMeta:
       tinymce:
@@ -5018,7 +5029,7 @@ packages:
       '@nestjs/typeorm': ^11.0.0
       reflect-metadata: ^0.2.0
       rxjs: ^7.8.0
-      typeorm: ^0.3.0
+      typeorm: 0.3.30
 
   '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz':
     resolution: {integrity: sha512-rfHSXOm/0VUMTj7HrvYysrEAqxItqfPs4Rd35qWJyaAk+snF1wTKFRVz6cRGPoQNj8fhplkVAefnvuKBuHT+xQ==, tarball: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz}
@@ -5040,15 +5051,15 @@ packages:
       class-validator: ^0.14.1
       reflect-metadata: ^0.2.0
       rxjs: ^7.8.0
-      typeorm: ^0.3.0
+      typeorm: 0.3.30
 
   '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz':
     resolution: {integrity: sha512-FTihoH0lIqKV/0s+FTJZokQw8xX3XztXIqT8eEYEZgDM2xyzVSCHY8pHCUxw0MQtiR8R97zxZJ/o192eWt+E/g==, tarball: file:local-packages/tria-plc-iamui-0.1.1.tgz}
     version: 0.1.1
     engines: {node: '>=18'}
     peerDependencies:
-      react: ^18.3.1 || ^19.0.0
-      react-dom: ^18.3.1 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@ts-morph/common@0.27.0':
     resolution: {integrity: sha512-Wf29UqxWDpc+i61k3oIOzcUfQt79PIT9y/MWfAGlrkjg6lBC1hwDECLXPVJAhWjiGbfBCxZd65F/LIZF3+jeJQ==}
@@ -5581,8 +5592,8 @@ packages:
   '@vis.gl/react-google-maps@1.8.3':
     resolution: {integrity: sha512-DW7nEuvOJ299DmdBnvGiUARrgS/+sTEO1iJgG9J8YaErZqLoq7S4TJ22f3EjJvR4dti4L4gft43JEK77nnKXDw==}
     peerDependencies:
-      react: '>=16.8.0 || ^19.0 || ^19.0.0-rc'
-      react-dom: '>=16.8.0 || ^19.0 || ^19.0.0-rc'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   '@vitejs/plugin-react@4.7.0':
     resolution: {integrity: sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==}
@@ -5677,6 +5688,9 @@ packages:
     resolution: {integrity: sha512-E+iruNOY8VV9s4JEbe1aNEm6MiszPRr/UfcHMz0TQh1BXSxHK+ASV1R6W4HpjBhSeS+54PIsAMCBmwD06LLsqQ==}
     hasBin: true
 
+  abbrev@1.1.1:
+    resolution: {integrity: sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==}
+
   abort-controller@3.0.0:
     resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==}
     engines: {node: '>=6.5'}
@@ -5957,6 +5971,9 @@ packages:
   append-field@1.0.0:
     resolution: {integrity: sha512-klpgFSWLW1ZEs8svjfb7g4qWY0YS5imI82dTg+QahUvJ8YqAY0P10Uk8tTyh9ZGuYEZEMaeJYCF5BFuX552hsw==}
 
+  aproba@2.1.0:
+    resolution: {integrity: sha512-tLIEcj5GuR2RSTnxNKdkK0dJ/GrC7P38sUkiDmDuHfsHmbagTFAxDVIBltoklXEVIQ/f14IL8IMJ5pn9Hez1Ew==}
+
   arch@2.2.0:
     resolution: {integrity: sha512-Of/R0wqp83cgHozfIYLbBMnej79U/SVGOOyuB3VVFv1NRM/PSFMK12x9KVtiYzJqmnU5WR2qp0Z5rHb7sWGnFQ==}
 
@@ -5972,6 +5989,11 @@ packages:
     resolution: {integrity: sha512-+25nxyyznAXF7Nef3y0EbBeqmGZgeN/BxHX29Rs39djAfaFalmQ89SE6CWyDCHzGL0yt/ycBtNOmGTW0FyGWNw==}
     engines: {node: '>= 10'}
 
+  are-we-there-yet@2.0.0:
+    resolution: {integrity: sha512-Ci/qENmwHnsYo9xKIcUJN5LeDKdJ6R1Z1j9V/J5wyq8nh/mYPEpIKJbBZXtZjG04HiK7zV/p6Vs9952MrMeUIw==}
+    engines: {node: '>=10'}
+    deprecated: This package is no longer supported.
+
   arg@4.1.3:
     resolution: {integrity: sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==}
 
@@ -6446,6 +6468,10 @@ packages:
   caniuse-lite@1.0.30001797:
     resolution: {integrity: sha512-l8xKG+gwAIExZGl9FrF7KUwuOmk6wbEPC9Xoy/RtnWv1XG0Q4LFlagaLpUv3Kiza3W/wm27zy0yWJEieYKAP6w==}
 
+  canvas@2.11.2:
+    resolution: {integrity: sha512-ItanGBMrmRV7Py2Z+Xhs7cT+FNt5K0vPL4p9EZ/UX/Mu7hFbkxSjKF2KVtPwX7UYWp7dRKnrTvReflgrItJbdw==}
+    engines: {node: '>=6'}
+
   canvg@3.0.11:
     resolution: {integrity: sha512-5ON+q7jCTgMp9cjpu4Jo6XbvfYwSB2Ow3kzHKfIyJfaCAOHLbdKPQqGKgfED/R5B+3TFFfe8pegYA+b423SRyA==}
     engines: {node: '>=10.0.0'}
@@ -6513,6 +6539,10 @@ packages:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
 
+  chownr@2.0.0:
+    resolution: {integrity: sha512-bIomtDF5KGpdogkLd9VspvFzk9KfpyyGlS8YFVZl7TGPBHL5snIOnxeshwVgPteQ9b4Eydl+pVbIyE1DcvCWgQ==}
+    engines: {node: '>=10'}
+
   chrome-trace-event@1.0.4:
     resolution: {integrity: sha512-rNjApaLzuwaOTjCiT8lSDdGN1APCiqkChLMJxJPWLunPAt5fy8xgU9/jNOchV84wfIxrA0lRQB7oCT8jrn/wrQ==}
     engines: {node: '>=6.0'}
@@ -6631,8 +6661,8 @@ packages:
   cmdk@1.1.1:
     resolution: {integrity: sha512-Vsv7kFaXm+ptHDMZ7izaRsP70GgrW9NBNGswt9OZaVBLlE0SNpDq8eu/VGXyF9r7M0azK3Wy7OlYXsuyYLFzHg==}
     peerDependencies:
-      react: ^18 || ^19 || ^19.0.0-rc
-      react-dom: ^18 || ^19 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
 
   co@4.6.0:
     resolution: {integrity: sha512-QVb0dM5HvG+uaxitm8wONl7jltx8dqhfU33DcqtOZcLSVIKSDDLDi7+0LbAKiyI8hD9u42m2YxXSkMGWThaecQ==}
@@ -6674,6 +6704,10 @@ packages:
     resolution: {integrity: sha512-Bb6Cq8oq0IjDOe8wJmi4JeNn763Xs9cfrBcaylK1tPypWzyoy2G3l90v9k64kjphl/ZJjPIShFztenRomi8WTg==}
     engines: {node: '>=18'}
 
+  color-support@1.1.3:
+    resolution: {integrity: sha512-qiBjkpbMLO/HL68y+lh4q0/O1MZFj2RX6X/KmMa3+gJD3z+WwI1ZzDHysvqHGS3mP6mznPckpXmw1nI9cJjyRg==}
+    hasBin: true
+
   colorette@2.0.20:
     resolution: {integrity: sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==}
 
@@ -6749,6 +6783,9 @@ packages:
     resolution: {integrity: sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==}
     engines: {node: ^14.18.0 || >=16.10.0}
 
+  console-control-strings@1.1.0:
+    resolution: {integrity: sha512-ty/fTekppD2fIwRvnZAVdeOiGd1c7YXEixbgJTNzqcxJWKQnjJ/V1bNEEE6hygpM3WjwHFUVK6HTjWSzV4a8sQ==}
+
   content-disposition@0.5.4:
     resolution: {integrity: sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==}
     engines: {node: '>= 0.6'}
@@ -7019,9 +7056,6 @@ packages:
   date-fns@3.6.0:
     resolution: {integrity: sha512-fRHTG8g/Gif+kSh50gaGEdToemgfj74aRX3swtiouboip5JDLAyDE9F11nHMIcvOaXeOC6D7SpNhi7uFyB7Uww==}
 
-  date-fns@4.4.0:
-    resolution: {integrity: sha512-+1UMbeh68lH1SegH83CGWwpb6OHHbpSgr3+s5Eww5M4CAgswBpoWS0AjTOfEJ33HiYKz1hdj/KTFprzXHmq/6w==}
-
   date.js@0.3.3:
     resolution: {integrity: sha512-HgigOS3h3k6HnW011nAb43c5xx5rBXk8P2v/WIT9Zv4koIaVXiH2BURguI78VVp+5Qc076T7OR378JViCnZtBw==}
 
@@ -7078,6 +7112,10 @@ packages:
     resolution: {integrity: sha512-FqUYQ+8o158GyGTrMFJms9qh3CqTKvAqgqsTnkLI8sKu0028orqBhxNMFkFen0zGyg6epACD32pjVk58ngIErQ==}
     engines: {node: '>=0.10'}
 
+  decompress-response@4.2.1:
+    resolution: {integrity: sha512-jOSne2qbyE+/r8G1VU+G/82LBs2Fs4LAsTiLSHOCOMZQl2OKZ6i8i4IyHemTe+/yIXOtTcRQMzPcgyhoFlqPkw==}
+    engines: {node: '>=8'}
+
   dedent@1.7.2:
     resolution: {integrity: sha512-WzMx3mW98SN+zn3hgemf4OzdmyNhhhKz5Ay0pUfQiMQ3e1g+xmTJWp/pKdwKVXhdSkAEGIIzqeuWrL3mV/AXbA==}
     peerDependencies:
@@ -7155,6 +7193,9 @@ packages:
     resolution: {integrity: sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==}
     engines: {node: '>=0.4.0'}
 
+  delegates@1.0.0:
+    resolution: {integrity: sha512-bd2L678uiWATM6m5Z1VzNCErI3jiGzt6HGY8OVICs40JQq/HALfbyNJmp0UDakEY4pMMaN0Ly5om/B1VI/+xfQ==}
+
   depd@2.0.0:
     resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==}
     engines: {node: '>= 0.8'}
@@ -7272,7 +7313,7 @@ packages:
   downshift@7.6.2:
     resolution: {integrity: sha512-iOv+E1Hyt3JDdL9yYcOgW7nZ7GQ2Uz6YbggwXvKUSleetYhU2nXD482Rz6CzvM4lvI1At34BYruKAL4swRGxaA==}
     peerDependencies:
-      react: '>=16.12.0'
+      react: 19.2.6
 
   dunder-proto@1.0.1:
     resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
@@ -7966,8 +8007,8 @@ packages:
     resolution: {integrity: sha512-uaBd3qC1v3KQqBEjwTUd183K6PbS+j0yR9w9VmEOLWA/tnUcSn8Xa3uck7t4dgpDoUss8xQTcj8W2L07lrnLFg==}
     peerDependencies:
       '@emotion/is-prop-valid': '*'
-      react: ^18.0.0 || ^19.0.0
-      react-dom: ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@emotion/is-prop-valid':
         optional: true
@@ -8003,6 +8044,10 @@ packages:
     resolution: {integrity: sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ==}
     engines: {node: '>=10'}
 
+  fs-minipass@2.1.0:
+    resolution: {integrity: sha512-V/JgOLFCS+R6Vcq0slCuaeWEdNC3ouDlJMNIsacH2VtALiu9mV4LPrHc5cDl8k5aw6J8jwgWWpiTo5RYhmIzvg==}
+    engines: {node: '>= 8'}
+
   fs-monkey@1.1.0:
     resolution: {integrity: sha512-QMUezzXWII9EV5aTFXW1UBVUO77wYPpjqIF8/AviUCThNeSYZykpoTixUeaNNBwmCev0AMDWMAni+f8Hxb1IFw==}
 
@@ -8037,6 +8082,11 @@ packages:
   fuzzysort@3.1.0:
     resolution: {integrity: sha512-sR9BNCjBg6LNgwvxlBd0sBABvQitkLzoVY9MYYROQVX/FvfJ4Mai9LsGhDgd8qYdds0bY77VzYd5iuB+v5rwQQ==}
 
+  gauge@3.0.2:
+    resolution: {integrity: sha512-+5J6MS/5XksCuXq++uFRsnUd7Ovu1XenbeuIuNRJxYWjgQbPuFhT14lAvsWfqfAmnwluf1OwMjz39HjfLPci0Q==}
+    engines: {node: '>=10'}
+    deprecated: This package is no longer supported.
+
   generator-function@2.0.1:
     resolution: {integrity: sha512-SFdFmIJi+ybC0vjlHN0ZGVGHc3lgE0DxPAT0djjVg+kjOnSqclqmj0KQ7ykTOLP6YxoqOvuAODGdcHJn+43q3g==}
     engines: {node: '>= 0.4'}
@@ -8238,6 +8288,9 @@ packages:
     resolution: {integrity: sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==}
     engines: {node: '>= 0.4'}
 
+  has-unicode@2.0.1:
+    resolution: {integrity: sha512-8Rf9Y83NBReMnx0gFzA8JImQACstCYWUplepDa9xprwwtmgEZUF0h/i5xSA625zB/I37EtrswSST6OXxwaaIJQ==}
+
   has-value@0.3.1:
     resolution: {integrity: sha512-gpG936j8/MzaeID5Yif+577c17TxaDmhuyVgSwtnL/q8UUTySg8Mecb+8Cf1otgLoD7DDH75axp86ER7LFsf3Q==}
     engines: {node: '>=0.10.0'}
@@ -8472,8 +8525,8 @@ packages:
   input-format@0.3.14:
     resolution: {integrity: sha512-gHMrgrbCgmT4uK5Um5eVDUohuV9lcs95ZUUN9Px2Y0VIfjTzT2wF8Q3Z4fwLFm7c5Z2OXCm53FHoovj6SlOKdg==}
     peerDependencies:
-      react: '>=18.1.0'
-      react-dom: '>=18.1.0'
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       react:
         optional: true
@@ -9347,7 +9400,7 @@ packages:
   little-state-machine@4.8.1:
     resolution: {integrity: sha512-liPHqaWMQ7rzZryQUDnbZ1Gclnnai3dIyaJ0nAgwZRXMzqbYrydrlCI0NDojRUbE5VYh5vu6hygEUZiH77nQkQ==}
     peerDependencies:
-      react: ^16.8.0 || ^17 || ^18 || ^19
+      react: 19.2.6
 
   load-esm@1.0.3:
     resolution: {integrity: sha512-v5xlu8eHD1+6r8EHTg6hfmO97LN8ugKtiXcy5e6oN72iD2r6u0RPfLl6fxM+7Wnh2ZRq15o0russMst44WauPA==}
@@ -9538,17 +9591,17 @@ packages:
   lucide-react@0.446.0:
     resolution: {integrity: sha512-BU7gy8MfBMqvEdDPH79VhOXSEgyG8TSPOKWaExWGCQVqnGH7wGgDngPbofu+KdtVjPQBWbEmnfMTq90CTiiDRg==}
     peerDependencies:
-      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0-rc
+      react: 19.2.6
 
   lucide-react@0.513.0:
     resolution: {integrity: sha512-CJZKq2g8Y8yN4Aq002GahSXbG2JpFv9kXwyiOAMvUBv7pxeOFHUWKB0mO7MiY4ZVFCV4aNjv2BJFq/z3DgKPQg==}
     peerDependencies:
-      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
 
   lucide-react@1.17.0:
     resolution: {integrity: sha512-9FA9evdox/JQL5PT57fdA1x/yg8T7knJ98+zjTL3UfKza6pflQUUh3XtaQIHKvnsJw1lmsEyHVlt5jchYxOQ5w==}
     peerDependencies:
-      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
 
   luxon@3.7.2:
     resolution: {integrity: sha512-vtEhXh/gNjI9Yg1u4jX/0YVPMvxzHuGgCm6tC5kZyb08yjGWGnqAjGJvcXbqQR2P3MyMEFnRbpcdFS6PBcLqew==}
@@ -9563,6 +9616,10 @@ packages:
   make-cancellable-promise@2.0.0:
     resolution: {integrity: sha512-3SEQqTpV9oqVsIWqAcmDuaNeo7yBO3tqPtqGRcKkEo0lrzD3wqbKG9mkxO65KoOgXqj+zH2phJ2LiAsdzlogSw==}
 
+  make-dir@3.1.0:
+    resolution: {integrity: sha512-g3FeP20LNwhALb/6Cz6Dd4F2ngze0jz7tbzrD2wAV+o9FeNHe4rL+yK2md0J/fiSf1sa1ADhXqi5+oVwOM/eGw==}
+    engines: {node: '>=8'}
+
   make-dir@4.0.0:
     resolution: {integrity: sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==}
     engines: {node: '>=10'}
@@ -9586,8 +9643,8 @@ packages:
       '@tabler/icons-react': '>=2.23.0'
       clsx: '>=2'
       dayjs: '>=1.11'
-      react: '>=18.0'
-      react-dom: '>=18.0'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   map-cache@0.2.2:
     resolution: {integrity: sha512-8y/eV9QQZCiyn1SprXSrCmqJN0yNRATe+PO8ztwqrvrbdRLA3eYJF0yaR0YayLWkMbsQSKWS9N2gPcGEc4UsZg==}
@@ -9848,6 +9905,10 @@ packages:
     resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
     engines: {node: '>=18'}
 
+  mimic-response@2.1.0:
+    resolution: {integrity: sha512-wXqjST+SLt7R009ySCglWBCFpjUygmCIfD790/kVbiGmUgfYGuB14PiTd5DwVxSV4NcYHjzMkoj5LjQZwTQLEA==}
+    engines: {node: '>=8'}
+
   minimatch@10.2.5:
     resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==}
     engines: {node: 18 || 20 || >=22}
@@ -9870,10 +9931,22 @@ packages:
     resolution: {integrity: sha512-xPrLjWkTT5E7H7VnzOjF//xBp9I40jYB4aWhb2xTFopXXfw+Wo82DDWngdUju7Doy3Wk7R8C4LAgwhLHHnf0wA==}
     engines: {node: ^16 || ^18 || >=20}
 
+  minipass@3.3.6:
+    resolution: {integrity: sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==}
+    engines: {node: '>=8'}
+
+  minipass@5.0.0:
+    resolution: {integrity: sha512-3FnjYuehv9k6ovOEbyOswadCDPX1piCfhV8ncmYtHOjuPwylVWsghTLo7rabjC3Rx5xD4HDx8Wm1xnMF7S5qFQ==}
+    engines: {node: '>=8'}
+
   minipass@7.1.3:
     resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==}
     engines: {node: '>=16 || 14 >=14.17'}
 
+  minizlib@2.1.2:
+    resolution: {integrity: sha512-bAxsR8BVfj60DWXHE3u30oHzfl4G7khkSuPW+qvpd7jFRHm7dLxOjUk1EHACJ/hxLY8phGJ0YhYHZo7jil7Qdg==}
+    engines: {node: '>= 8'}
+
   mitt@3.0.1:
     resolution: {integrity: sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==}
 
@@ -9885,6 +9958,11 @@ packages:
     resolution: {integrity: sha512-FP+p8RB8OWpF3YZBCrP5gtADmtXApB5AMLn+vdyA+PyxCjrCs00mjyUozssO33cwDeT3wNGdLxJ5M//YqtHAJw==}
     hasBin: true
 
+  mkdirp@1.0.4:
+    resolution: {integrity: sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==}
+    engines: {node: '>=10'}
+    hasBin: true
+
   moment@2.30.1:
     resolution: {integrity: sha512-uEmtNhbDOrWPFS+hdjFCBfy9f2YoyzRpwcl+DqpC6taX21FzsTLQVbMV/W7PzNSX6x/bhC1zA3c2UQ5NzH6how==}
 
@@ -9922,9 +10000,9 @@ packages:
       '@mui/icons-material': ^5.11.16
       '@mui/material': ^5.13.3
       '@mui/x-date-pickers': ^6.7.0
-      date-fns: ^2.30.0
-      react: ^18.2.0
-      react-dom: ^18.2.0
+      date-fns: ^3.6.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   multer@2.1.1:
     resolution: {integrity: sha512-mo+QTzKlx8R7E5ylSXxWzGoXoZbOsRMpyitcht8By2KHvMbf3tjwosZ/Mu/XYU6UuJ3VZnODIrak5ZrPiPyB6A==}
@@ -9944,6 +10022,9 @@ packages:
   mz@2.7.0:
     resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==}
 
+  nan@2.28.0:
+    resolution: {integrity: sha512-fTsDz99OTq2sVePhGdp4qQhggZFtKr64ZNVyVajRKtMOkJxYekplBh577PiJB12v/D3s2E5cGtOI45LWp6rnLQ==}
+
   nanoid@3.3.12:
     resolution: {integrity: sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
@@ -9985,8 +10066,8 @@ packages:
   next-themes@0.4.6:
     resolution: {integrity: sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==}
     peerDependencies:
-      react: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
 
   next@14.2.35:
     resolution: {integrity: sha512-KhYd2Hjt/O1/1aZVX3dCwGXM1QmOV4eNM2UTacK5gipDdPN/oHHK/4oVGy7X8GMfPMsUTUEmGlsy0EY1YGAkig==}
@@ -9995,8 +10076,8 @@ packages:
     peerDependencies:
       '@opentelemetry/api': ^1.1.0
       '@playwright/test': ^1.41.2
-      react: ^18.2.0
-      react-dom: ^18.2.0
+      react: 19.2.6
+      react-dom: 19.2.6
       sass: ^1.3.0
     peerDependenciesMeta:
       '@opentelemetry/api':
@@ -10034,6 +10115,15 @@ packages:
   node-fetch-native@1.6.7:
     resolution: {integrity: sha512-g9yhqoedzIUm0nTnTqAQvueMPVOuIY16bqgAJJC8XOOubYFNwz6IER9qs0Gq2Xd0+CecCKFjtdDTMA4u4xG06Q==}
 
+  node-fetch@2.7.0:
+    resolution: {integrity: sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==}
+    engines: {node: 4.x || >=6.0.0}
+    peerDependencies:
+      encoding: ^0.1.0
+    peerDependenciesMeta:
+      encoding:
+        optional: true
+
   node-fetch@3.3.2:
     resolution: {integrity: sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
@@ -10056,6 +10146,11 @@ packages:
     resolution: {integrity: sha512-Uzmd6LXpouKo8EUK68IjH4+E01w/hXyV3R3g/geCJo+rXLNfh1xucB+LOzYEOQPSiUK3h/xZf0cQGcSsmyL2Og==}
     engines: {node: '>=18'}
 
+  nopt@5.0.0:
+    resolution: {integrity: sha512-Tbj67rffqceeLpcRXrT7vKAN8CwfPeIBgM7E6iBkmKLV7bEMwpGgYLGv0jACUsECaa/vuxP0IjEont6umdMgtQ==}
+    engines: {node: '>=6'}
+    hasBin: true
+
   normalize-path@3.0.0:
     resolution: {integrity: sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==}
     engines: {node: '>=0.10.0'}
@@ -10075,6 +10170,10 @@ packages:
     resolution: {integrity: sha512-9qny7Z9DsQU8Ou39ERsPU4OZQlSTP47ShQzuKZ6PRXpYLtIFgl/DEBYEXKlvcEa+9tHVcK8CF81Y2V72qaZhWA==}
     engines: {node: '>=18'}
 
+  npmlog@5.0.1:
+    resolution: {integrity: sha512-AqZtDUWOMKs1G/8lwylVjrdYgqA4d9nu8hc+0gzRxlDb1I10+FHBGMXs6aiQHFdCUUlqH99MUMuLfzWDNDtfxw==}
+    deprecated: This package is no longer supported.
+
   nth-check@2.1.1:
     resolution: {integrity: sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==}
 
@@ -10342,6 +10441,10 @@ packages:
     resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==}
     engines: {node: '>=8'}
 
+  path2d-polyfill@2.0.1:
+    resolution: {integrity: sha512-ad/3bsalbbWhmBo0D6FZ4RNMwsLsPpL6gnvhuSaU5Vm7b06Kr5ubSltQQ0T7YKsiJQO+g22zJ4dJKNTXIyOXtA==}
+    engines: {node: '>=8'}
+
   path@0.12.7:
     resolution: {integrity: sha512-aXXC6s+1w7otVF9UletFkFcDsJeO7lSZBPUQhtb5O0xJe8LtYhj/GxldoL09bBj9+ZmE2hNoHqQSFMN5fikh4Q==}
 
@@ -10361,6 +10464,10 @@ packages:
   pdf-lib@1.17.1:
     resolution: {integrity: sha512-V/mpyJAoTsN4cnP31vc0wfNA1+p20evqqnap0KLoRUN0Yk/p3wN52DOEsL4oBFcLdb76hlpKPtzJIgo67j/XLw==}
 
+  pdfjs-dist@3.11.174:
+    resolution: {integrity: sha512-TdTZPf1trZ8/UFu5Cx/GXB7GZM30LT+wWUNfsi6Bq8ePLnb+woNKtDymI2mxZYBpMbonNFqKmiz684DIfnd8dA==}
+    engines: {node: '>=18'}
+
   pdfjs-dist@5.4.296:
     resolution: {integrity: sha512-DlOzet0HO7OEnmUmB6wWGJrrdvbyJKftI1bhMitK7O2N8W2gc757yyYBbINy9IDafXAV9wmKr9t7xsTaNKRG5Q==}
     engines: {node: '>=20.16.0 || >=22.3.0'}
@@ -10660,7 +10767,7 @@ packages:
   qrcode.react@3.2.0:
     resolution: {integrity: sha512-YietHHltOHA4+l5na1srdaMx4sVSOjV9tamHs+mwiLWAMr6QVACRUw1Neax5CptFILcNoITctJY0Ipyn5enQ8g==}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0
+      react: 19.2.6
 
   qrcode@1.5.4:
     resolution: {integrity: sha512-1ca71Zgiu6ORjHqFBDpnSMTR2ReToX4l1Au1VFLyVeBTFavzQnv5JxMFr3ukHVKpSrSA2MCk0lNJSykjUfz7Zg==}
@@ -10700,8 +10807,8 @@ packages:
     peerDependencies:
       '@types/react': '*'
       '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -10735,60 +10842,55 @@ packages:
   react-cookie@8.1.2:
     resolution: {integrity: sha512-S45Z1y1dHyYfLEI4bFKQICuP+SwJqTPWbdc2ZpE6aQSdjSVJAjUDfwTPq8B7BWieIsgyyEWMb/QOrudtwJMjXA==}
     peerDependencies:
-      react: '>= 16.3.0'
+      react: 19.2.6
 
   react-css-nocode-editor@1.0.13:
     resolution: {integrity: sha512-RV1ZbG8aXORiQ5mDKZbKCHStCJPamp/n5Rb34q22Ug2xzMDW4DjjqO23+Qo/Y+LAoyyrFV/+lI1qq4+/O5nf2A==}
     peerDependencies:
-      react: '>=16.8.0 <= 18.1'
-      react-dom: '>=16.8.0 <= 18.1'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-day-picker@8.10.2:
     resolution: {integrity: sha512-LK68OTbHB3oJNhl9cA0qVizzp3o26w61YSjAFkYi67N86iro32wx86kSNeFU/hq+gI8m1yzWhnomMLfZ041RzQ==}
     peerDependencies:
-      date-fns: ^2.28.0 || ^3.0.0
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      date-fns: ^3.6.0
+      react: 19.2.6
 
   react-day-picker@9.14.0:
     resolution: {integrity: sha512-tBaoDWjPwe0M5pGrum4H0SR6Lyk+BO9oHnp9JbKpGKW2mlraNPgP9BMfsg5pWpwrssARmeqk7YBl2oXutZTaHA==}
     engines: {node: '>=18'}
     peerDependencies:
-      react: '>=16.8.0'
-
-  react-dom@18.3.1:
-    resolution: {integrity: sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==}
-    peerDependencies:
-      react: ^18.3.1
+      react: 19.2.6
 
   react-dom@19.2.6:
     resolution: {integrity: sha512-0prMI+hvBbPjsWnxDLxlCGyM8PN6UuWjEUCYmZhO67xIV9Xasa/r/vDnq+Xyq4Lo27g8QSbO5YzARu0D1Sps3g==}
     peerDependencies:
-      react: ^19.2.6
+      react: 19.2.6
 
   react-dropzone@14.4.1:
     resolution: {integrity: sha512-QDuV76v3uKbHiH34SpwifZ+gOLi1+RdsCO1kl5vxMT4wW8R82+sthjvBw4th3NHF/XX6FBsqDYZVNN+pnhaw0g==}
     engines: {node: '>= 10.13'}
     peerDependencies:
-      react: '>= 16.8 || 18.0.0'
+      react: 19.2.6
 
   react-hook-form@7.77.0:
     resolution: {integrity: sha512-Sslh9YDYc0GDlWT/lxasnIduNo4v3yyvqRGvmGKUre5AFjDs/HV9/OafHGD8d+sB2yoL4UIL9L8X9i0WlZZebg==}
     engines: {node: '>=18.0.0'}
     peerDependencies:
-      react: ^16.8.0 || ^17 || ^18 || ^19
+      react: 19.2.6
 
   react-hot-toast@2.6.0:
     resolution: {integrity: sha512-bH+2EBMZ4sdyou/DPrfgIouFpcRLCJ+HoCA32UoAYHn6T3Ur5yfcDCeSr5mwldl6pFOsiocmrXMuoCJ1vV8bWg==}
     engines: {node: '>=10'}
     peerDependencies:
-      react: '>=16'
-      react-dom: '>=16'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-i18next@15.7.4:
     resolution: {integrity: sha512-nyU8iKNrI5uDJch0z9+Y5XEr34b0wkyYj3Rp+tfbahxtlswxSCjcUL9H0nqXo9IR3/t5Y5PKIA3fx3MfUyR9Xw==}
     peerDependencies:
       i18next: '>= 23.4.0'
-      react: '>= 16.8.0'
+      react: 19.2.6
       react-dom: '*'
       react-native: '*'
       typescript: ^5
@@ -10804,7 +10906,7 @@ packages:
     resolution: {integrity: sha512-0ooKbGLU8JXhe1zwpQUWIeXSgLPOfwJmgheWRIUpcoA0CpyabpGhayjdG+/eA5esC1AQ8h2jWpXjJfzQzeDOCw==}
     peerDependencies:
       i18next: '>= 26.2.0'
-      react: '>= 16.8.0'
+      react: 19.2.6
       react-dom: '*'
       react-native: '*'
       typescript: ^5 || ^6
@@ -10819,18 +10921,18 @@ packages:
   react-icons@5.6.0:
     resolution: {integrity: sha512-RH93p5ki6LfOiIt0UtDyNg/cee+HLVR6cHHtW3wALfo+eOHTp8RnU2kRkI6E+H19zMIs03DyxUG/GfZMOGvmiA==}
     peerDependencies:
-      react: '*'
+      react: 19.2.6
 
   react-image-crop@11.0.10:
     resolution: {integrity: sha512-+5FfDXUgYLLqBh1Y/uQhIycpHCbXkI50a+nbfkB1C0xXXUTwkisHDo2QCB1SQJyHCqIuia4FeyReqXuMDKWQTQ==}
     peerDependencies:
-      react: '>=16.13.1'
+      react: 19.2.6
 
   react-intersection-observer@9.16.0:
     resolution: {integrity: sha512-w9nJSEp+DrW9KmQmeWHQyfaP6b03v+TdXynaoA964Wxt7mdR3An11z4NNCQgL4gKSK7y1ver2Fq+JKH6CWEzUA==}
     peerDependencies:
-      react: ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       react-dom:
         optional: true
@@ -10851,27 +10953,27 @@ packages:
     resolution: {integrity: sha512-xaijuJB0kzGiUdG7nc2MOMDUDBWPyGAjZtUrow9XxUeua8IqeP+VlIfAZ3bphpcLTnSZXz6z9jcVC/TCwbfgdw==}
     peerDependencies:
       '@types/react': '>=18'
-      react: '>=18'
+      react: 19.2.6
 
   react-number-format@5.4.5:
     resolution: {integrity: sha512-y8O2yHHj3w0aE9XO8d2BCcUOOdQTRSVq+WIuMlLVucAm5XNjJAy+BoOJiuQMldVYVOKTMyvVNfnbl2Oqp+YxGw==}
     peerDependencies:
-      react: ^0.14 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^0.14 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-pdf-html@2.1.5:
     resolution: {integrity: sha512-KhmiTUcnUNbLVdZbxMcV/+Rp+PyBt+eVJHu425eNwjSsDUtytvcwS/SBdBbbpM0c4+MnnOQBOs3AiColUesM8A==}
     engines: {node: '>=16.0.0'}
     peerDependencies:
       '@react-pdf/renderer': '>=3.4.4'
-      react: '>=16'
+      react: 19.2.6
 
   react-pdf@10.4.1:
     resolution: {integrity: sha512-kS/35staVCBqS29verTQJQZXw7RfsRCPO3fdJoW1KXylcv7A9dw6DZ3vJXC2w+bIBgLw5FN4pOFvKSQtkQhPfA==}
     peerDependencies:
       '@types/react': ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -10879,21 +10981,21 @@ packages:
   react-phone-number-input@3.4.17:
     resolution: {integrity: sha512-1wcjhBAWHgEBAGLi5/XbeZI7Q3aEHNb2z/dHY6R2Gz70TQvu0ZoOT28NTdwtZf4lyRKXWufnTzVhLPBUD8LfmQ==}
     peerDependencies:
-      react: '>=16.8'
-      react-dom: '>=16.8'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-quill-new@3.8.3:
     resolution: {integrity: sha512-c96PYqFTo0pI4R3e79B3rH9LUIce1kIQbmTBu/imJQZk8305ogyLyBqKKjG2UoInDlquXqePSzmBo2aVia3ttw==}
     peerDependencies:
       quill-delta: ^5.1.0
-      react: ^16 || ^17 || ^18 || ^19
-      react-dom: ^16 || ^17 || ^18 || ^19
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-redux@9.3.0:
     resolution: {integrity: sha512-KQopgqFo/p/fgmAs5qz6p5RWaNAzq40WAu7fJIXnQpYxFPbJYtsJPWvGeF2rOBaY/kEuV77AVsX8TsQzKm+A/g==}
     peerDependencies:
       '@types/react': ^18.2.25 || ^19
-      react: ^18.0 || ^19
+      react: 19.2.6
       redux: ^5.0.0
     peerDependenciesMeta:
       '@types/react':
@@ -10910,7 +11012,7 @@ packages:
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -10920,7 +11022,7 @@ packages:
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -10928,35 +11030,35 @@ packages:
   react-resizable-panels@3.0.6:
     resolution: {integrity: sha512-b3qKHQ3MLqOgSS+FRYKapNkJZf5EQzuf6+RLiq1/IlTHw99YrZ2NJZLk4hQIzTnnIkRg2LUqyVinu6YWWpUYew==}
     peerDependencies:
-      react: ^16.14.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
-      react-dom: ^16.14.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-router-dom@6.30.4:
     resolution: {integrity: sha512-q4HvNl+mmDdkS0g+MqiBZNteQJCuimWoOyHMy4T/RQLAn9Z29+E91QXRaxOujeMl2HTzRSS0KFPd7lxX3PjV0Q==}
     engines: {node: '>=14.0.0'}
     peerDependencies:
-      react: '>=16.8'
-      react-dom: '>=16.8'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-router-dom@7.17.0:
     resolution: {integrity: sha512-fyU2yjGups/hE6Xz0I5ZYbVL8Gx29eCjgpHaRaTaVU+OOAdfRX05KsvyRm0GO8YQwOkhpU3MurW1jyMUJn+zSw==}
     engines: {node: '>=20.0.0'}
     peerDependencies:
-      react: '>=18'
-      react-dom: '>=18'
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-router@6.30.4:
     resolution: {integrity: sha512-SVUsDe+DybHM/WmYKIVYhZh1o5Dcuf16yM6WjG02Q9XVFMZIJyHYhwrr6bFBXZkVP6z69kNkMyBCujt8FaFLJA==}
     engines: {node: '>=14.0.0'}
     peerDependencies:
-      react: '>=16.8'
+      react: 19.2.6
 
   react-router@7.17.0:
     resolution: {integrity: sha512-FDELK7rTMlCHO5+reyXsPlmfr7N1F91lPHsWYfMEGQm/KQ+F4JFM8jGoeQDmDvdTs93Fw9aSilH+uKRb4/jXvQ==}
     engines: {node: '>=20.0.0'}
     peerDependencies:
-      react: '>=18'
-      react-dom: '>=18'
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       react-dom:
         optional: true
@@ -10967,8 +11069,8 @@ packages:
       '@types/prop-types': ^15.7.3
       '@types/react': 0.14 - 19
       prop-types: ^15.5.8
-      react: 0.14 - 19
-      react-dom: 0.14 - 19
+      react: 19.2.6
+      react-dom: 19.2.6
     peerDependenciesMeta:
       '@types/prop-types':
         optional: true
@@ -10978,20 +11080,20 @@ packages:
   react-simple-animate@3.5.3:
     resolution: {integrity: sha512-Ob+SmB5J1tXDEZyOe2Hf950K4M8VaWBBmQ3cS2BUnTORqHjhK0iKG8fB+bo47ZL15t8d3g/Y0roiqH05UBjG7A==}
     peerDependencies:
-      react-dom: ^16.8.0 || ^17 || ^18 || ^19
+      react-dom: 19.2.6
 
   react-smooth@4.0.4:
     resolution: {integrity: sha512-gnGKTpYwqL0Iii09gHobNolvX4Kiq4PKx6eWBCYYix+8cdw+cGo3do906l1NBPKkSWx1DghC1dlWG9L2uGd61Q==}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react-style-singleton@2.2.3:
     resolution: {integrity: sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==}
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -11000,17 +11102,13 @@ packages:
     resolution: {integrity: sha512-U1DGlIQN5AwgjTyOEnI1oCcMuEr1pv1qOtklB2l4nyMGbHzWrI0eFsYK0zos2YWqAolJyG0IWJaqWmWj5ETh0A==}
     engines: {node: '>=10'}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
 
   react-transition-group@4.4.5:
     resolution: {integrity: sha512-pZcd1MCJoiKiBR2NRxeCRg13uCXbydPnmB4EOeRrY7480qNWO8IIgQG6zlDkm6uRMsURXPuKq0GWtiM59a5Q6g==}
     peerDependencies:
-      react: '>=16.6.0'
-      react-dom: '>=16.6.0'
-
-  react@18.3.1:
-    resolution: {integrity: sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==}
-    engines: {node: '>=0.10.0'}
+      react: 19.2.6
+      react-dom: 19.2.6
 
   react@19.2.6:
     resolution: {integrity: sha512-sfWGGfavi0xr8Pg0sVsyHMAOziVYKgPLNrS7ig+ivMNb3wbCBw3KxtflsGBAwD3gYQlE/AEZsTLgToRrSCjb0Q==}
@@ -11060,15 +11158,15 @@ packages:
     engines: {node: '>=14'}
     deprecated: 1.x and 2.x branches are no longer active. Bump to Recharts v3 to receive latest features and bugfixes. See https://github.com/recharts/recharts/wiki/3.0-migration-guide
     peerDependencies:
-      react: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
 
   recharts@3.8.1:
     resolution: {integrity: sha512-mwzmO1s9sFL0TduUpwndxCUNoXsBw3u3E/0+A+cLcrSfQitSG62L32N69GhqUrrT5qKcAE3pCGVINC6pqkBBQg==}
     engines: {node: '>=18'}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-      react-dom: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
+      react-dom: 19.2.6
       react-is: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   redux-thunk@3.1.0:
@@ -11318,9 +11416,6 @@ packages:
     resolution: {integrity: sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==}
     engines: {node: '>=v12.22.7'}
 
-  scheduler@0.23.2:
-    resolution: {integrity: sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==}
-
   scheduler@0.25.0-rc-603e6108-20241029:
     resolution: {integrity: sha512-pFwF6H1XrSdYYNLfOcGlM28/j8CGLu8IvdrxqhjWULe2bPcKiKW4CV+OWqR/9fT52mywx65l7ysNkjLKBda7eA==}
 
@@ -11448,6 +11543,12 @@ packages:
   signature_pad@2.3.2:
     resolution: {integrity: sha512-peYXLxOsIY6MES2TrRLDiNg2T++8gGbpP2yaC+6Ohtxr+a2dzoaqWosWDY9sWqTAAk6E/TyQO+LJw9zQwyu5kA==}
 
+  simple-concat@1.0.1:
+    resolution: {integrity: sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q==}
+
+  simple-get@3.1.1:
+    resolution: {integrity: sha512-CQ5LTKGfCpvE1K0n2us+kuMPbk/q0EKl82s4aheV9oXjFEz6W/Y7oQFVJuU6QG77hRT4Ghb5RURteF5vnWjupA==}
+
   sisteransi@1.0.5:
     resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
 
@@ -11513,8 +11614,8 @@ packages:
   sonner@2.0.7:
     resolution: {integrity: sha512-W6ZN4p58k8aDKA4XPcx2hpIQXBRAgyiWVkYhT7CvK6D3iAu7xjvVyhQHg2/iaKJZ1XVJ4r7XuwGL+WGEK37i9w==}
     peerDependencies:
-      react: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
-      react-dom: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
 
   source-map-js@1.2.1:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
@@ -11761,8 +11862,8 @@ packages:
     resolution: {integrity: sha512-uuzIIfnVkagcVHv9nE0VPlHPSCmXIUGKfJ42LNjxCCTDTL5sgnJ8Z7GZBq0EnLYGln77tPpEpExt2+qa+cZqSw==}
     engines: {node: '>=10'}
     peerDependencies:
-      react: '>= 16.8.0'
-      react-dom: '>= 16.8.0'
+      react: 19.2.6
+      react-dom: 19.2.6
       react-is: '>= 16.8.0'
 
   styled-jsx@5.1.1:
@@ -11771,7 +11872,7 @@ packages:
     peerDependencies:
       '@babel/core': '*'
       babel-plugin-macros: '*'
-      react: '>= 16.8.0 || 17.x.x || ^18.0.0-0'
+      react: 19.2.6
     peerDependenciesMeta:
       '@babel/core':
         optional: true
@@ -11892,6 +11993,11 @@ packages:
   tar-stream@3.2.0:
     resolution: {integrity: sha512-ojzvCvVaNp6aOTFmG7jaRD0meowIAuPc3cMMhSgKiVWws1GyHbGd/xvnyuRKcKlMpt3qvxx6r0hreCNITP9hIg==}
 
+  tar@6.2.1:
+    resolution: {integrity: sha512-DZ4yORTwrbTj/7MZYq2w+/ZFdI6OZ/f9SFHR+71gIVUZhOQPHzVCLpvRnPgyaMpfWxxk/4ONva3GQSyNIKRv6A==}
+    engines: {node: '>=10'}
+    deprecated: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
+
   teex@1.0.1:
     resolution: {integrity: sha512-eYE6iEI62Ni1H8oIa7KlDU6uQBtqr4Eajni3wX7rpfXD8ysFx8z0+dri+KWEPWpBsxXfxu58x/0jvTVT1ekOSg==}
 
@@ -12089,6 +12195,9 @@ packages:
     resolution: {integrity: sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw==}
     engines: {node: '>=16'}
 
+  tr46@0.0.3:
+    resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==}
+
   tr46@5.1.1:
     resolution: {integrity: sha512-hdF5ZgjTqgAntKkklYw0R03MG2x/bSzTtkxmIRw/sTNV8YXsCJ1tfLAX23lhxhHJlEf3CRCOCGGWw3vI3GaSPw==}
     engines: {node: '>=18'}
@@ -12271,7 +12380,7 @@ packages:
     hasBin: true
     peerDependencies:
       '@faker-js/faker': '>=8.4.1'
-      typeorm: ~0.3.0
+      typeorm: 0.3.30
 
   typeorm@0.3.30:
     resolution: {integrity: sha512-8T35PzjefOdqc2ZR9mwLQj0pUGp6lQhMbK2EvVMwJVJWlaoHm0v/Q6dThNOZkFchD+0yMg8gwjKM28ePiLSXSQ==}
@@ -12451,7 +12560,7 @@ packages:
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12460,7 +12569,7 @@ packages:
     resolution: {integrity: sha512-djviaxuOOh7wkj0paeO1Q/4wMZ8Zrnag5H6yBvzN7AKKe8beOaED9SF5/ByLqsku8NP4zQqsvM2u3ew/tJK8/w==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12469,13 +12578,13 @@ packages:
     resolution: {integrity: sha512-kbeNVZ9Zkc0RFGpfMN3MNfaKNvcLNyxOAAd9O4CBZ+kCBXXscn9s/4I+8ytUER4RDpEYs5+O6Rs4PqiZ+rHr5Q==}
     engines: {node: '>=10', npm: '>=6'}
     peerDependencies:
-      react: '>=16.13'
+      react: 19.2.6
 
   use-isomorphic-layout-effect@1.2.1:
     resolution: {integrity: sha512-tpZZ+EX0gaghDAiFR37hj5MgY6ZN55kLiPkJsKxBMZ6GZdOSPJXiOzPM984oPYZ5AnehYx5WQp1+ME8I/P/pRA==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12484,7 +12593,7 @@ packages:
     resolution: {integrity: sha512-mhg3xdm9NaM8q+gLT8KryJPnRFOz1/5XPBhmDEVZK1webPzDjrPk7f/mbpeLqTgB9msytYWANxgALOCJKnLvcQ==}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12494,7 +12603,7 @@ packages:
     engines: {node: '>=10'}
     peerDependencies:
       '@types/react': '*'
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
     peerDependenciesMeta:
       '@types/react':
         optional: true
@@ -12502,7 +12611,7 @@ packages:
   use-sync-external-store@1.6.0:
     resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==}
     peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: 19.2.6
 
   use@3.1.1:
     resolution: {integrity: sha512-cwESVXlO3url9YWlFW/TA9cshCEhtu7IKJ/p5soJ/gGpj7vbvFrAY/eIioQ6Dw23KjZhYgiIo8HOs1nQ2vr/oQ==}
@@ -12565,8 +12674,8 @@ packages:
   vaul@1.1.2:
     resolution: {integrity: sha512-ZFkClGpWyI2WUQjdLJ/BaGuV6AVQiJ3uELGk3OYtP+B6yCO7Cmn9vPFXVJkRaGkOJu3m8bQMgtyzNHixULceQA==}
     peerDependencies:
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+      react: 19.2.6
+      react-dom: 19.2.6
 
   verror@1.10.0:
     resolution: {integrity: sha512-ZZKSmDAEFOijERBLkmYfJ+vmk3w+7hOLYDNkRCuRuMJGEmqYNCNLyBBFwWKVMhfwaEF3WOd0Zlw86U/WC/+nYw==}
@@ -12694,6 +12803,9 @@ packages:
   webdriver-bidi-protocol@0.4.1:
     resolution: {integrity: sha512-ARrjNjtWRRs2w4Tk7nqrf2gBI0QXWuOmMCx2hU+1jUt6d00MjMxURrhxhGbrsoiZKJrhTSTzbIrc554iKI10qw==}
 
+  webidl-conversions@3.0.1:
+    resolution: {integrity: sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==}
+
   webidl-conversions@7.0.0:
     resolution: {integrity: sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==}
     engines: {node: '>=12'}
@@ -12729,6 +12841,9 @@ packages:
     resolution: {integrity: sha512-De72GdQZzNTUBBChsXueQUnPKDkg/5A5zp7pFDuQAj5UFoENpiACU0wlCvzpAGnTkj++ihpKwKyYewn/XNUbKw==}
     engines: {node: '>=18'}
 
+  whatwg-url@5.0.0:
+    resolution: {integrity: sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==}
+
   which-boxed-primitive@1.1.1:
     resolution: {integrity: sha512-TbX3mj8n0odCBFVlY8AxkqcHASw3L60jIuF8jFP78az3C2YhmGvqbHBpAjTRH2/xqYunrJ9g1jSyjCjpoWzIAA==}
     engines: {node: '>= 0.4'}
@@ -12763,6 +12878,9 @@ packages:
     engines: {node: '>=8'}
     hasBin: true
 
+  wide-align@1.1.5:
+    resolution: {integrity: sha512-eDMORYaPNZ4sQIuuYPDHdQvf4gyCF9rEEV/yPxGfwPkRodwEgiMUUXTx/dex+Me0wxx53S+NgUHaP7y3MGlDmg==}
+
   wmf@1.0.2:
     resolution: {integrity: sha512-/p9K7bEh0Dj6WbXg4JG0xvLQmIadrner1bi45VMJTfnbVHsc7yIajZyoSoK60/dtVBs12Fm6WkUI5/3WAVsNMw==}
     engines: {node: '>=0.8'}
@@ -12874,6 +12992,9 @@ packages:
   yallist@3.1.1:
     resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
 
+  yallist@4.0.0:
+    resolution: {integrity: sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==}
+
   yaml@1.10.3:
     resolution: {integrity: sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==}
     engines: {node: '>= 6'}
@@ -12970,7 +13091,7 @@ packages:
     peerDependencies:
       '@types/react': '>=18.0.0'
       immer: '>=9.0.6'
-      react: '>=18.0.0'
+      react: 19.2.6
       use-sync-external-store: '>=1.2.0'
     peerDependenciesMeta:
       '@types/react':
@@ -13998,12 +14119,6 @@ snapshots:
       '@floating-ui/core': 1.7.5
       '@floating-ui/utils': 0.2.11
 
-  '@floating-ui/react-dom@2.1.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@floating-ui/dom': 1.7.6
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-
   '@floating-ui/react-dom@2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/dom': 1.7.6
@@ -14018,14 +14133,6 @@ snapshots:
       react-dom: 19.2.6(react@19.2.6)
       tabbable: 6.4.0
 
-  '@floating-ui/react@0.27.19(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@floating-ui/react-dom': 2.1.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@floating-ui/utils': 0.2.11
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      tabbable: 6.4.0
-
   '@floating-ui/react@0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/react-dom': 2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -14089,9 +14196,9 @@ snapshots:
       - '@types/react'
       - supports-color
 
-  '@hookform/resolvers@3.10.0(react-hook-form@7.77.0(react@18.3.1))':
+  '@hookform/resolvers@3.10.0(react-hook-form@7.77.0(react@19.2.6))':
     dependencies:
-      react-hook-form: 7.77.0(react@18.3.1)
+      react-hook-form: 7.77.0(react@19.2.6)
 
   '@hookform/resolvers@5.4.0(react-hook-form@7.77.0(react@19.2.6))':
     dependencies:
@@ -14879,19 +14986,6 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
-  '@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@floating-ui/react': 0.27.19(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@mantine/hooks': 9.3.0(react@18.3.1)
-      clsx: 2.1.1
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      react-number-format: 5.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
-      type-fest: 5.7.0
-    transitivePeerDependencies:
-      - '@types/react'
-
   '@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/react': 0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -14949,10 +15043,6 @@ snapshots:
     dependencies:
       react: 19.2.6
 
-  '@mantine/hooks@9.3.0(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-
   '@mantine/hooks@9.3.0(react@19.2.6)':
     dependencies:
       react: 19.2.6
@@ -14974,6 +15064,22 @@ snapshots:
     dependencies:
       react: 19.2.6
 
+  '@mapbox/node-pre-gyp@1.0.11':
+    dependencies:
+      detect-libc: 2.1.2
+      https-proxy-agent: 5.0.1
+      make-dir: 3.1.0
+      node-fetch: 2.7.0
+      nopt: 5.0.0
+      npmlog: 5.0.1
+      rimraf: 3.0.2
+      semver: 7.8.2
+      tar: 6.2.1
+    transitivePeerDependencies:
+      - encoding
+      - supports-color
+    optional: true
+
   '@marijn/find-cluster-break@1.0.3': {}
 
   '@mdxeditor/editor@4.2.0(@codemirror/language@6.12.4)(@lezer/highlight@1.2.3)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.9.3)(yjs@13.6.32)':
@@ -15733,15 +15839,6 @@ snapshots:
 
   '@radix-ui/primitive@1.1.4': {}
 
-  '@radix-ui/react-accessible-icon@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-accessible-icon@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -15751,23 +15848,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-accordion@1.2.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collapsible': 1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-accordion@1.2.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15785,20 +15865,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-alert-dialog@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-alert-dialog@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15813,15 +15879,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-arrow@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-arrow@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -15831,15 +15888,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-aspect-ratio@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-aspect-ratio@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -15849,19 +15897,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-avatar@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-avatar@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@19.2.6)
@@ -15875,22 +15910,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-checkbox@1.3.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-checkbox@1.3.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15907,22 +15926,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-collapsible@1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-collapsible@1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -15939,18 +15942,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-collection@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-collection@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@19.2.6)
@@ -15963,31 +15954,12 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-compose-refs@1.1.3(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-compose-refs@1.1.3(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-context-menu@2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-context-menu@2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16001,40 +15973,12 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-context@1.1.4(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-context@1.1.4(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-dialog@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      aria-hidden: 1.2.6
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-dialog@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16057,31 +16001,12 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-direction@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-direction@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-dismissable-layer@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-escape-keydown': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-dismissable-layer@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16095,21 +16020,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-dropdown-menu@2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-dropdown-menu@2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16125,29 +16035,12 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-focus-guards@1.1.4(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-focus-guards@1.1.4(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-focus-scope@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-focus-scope@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@19.2.6)
@@ -16159,20 +16052,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-form@0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-label': 2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-form@0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16187,23 +16066,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-hover-card@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-hover-card@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16225,13 +16087,6 @@ snapshots:
     dependencies:
       react: 19.2.6
 
-  '@radix-ui/react-id@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-id@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -16239,15 +16094,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-label@2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-label@2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -16257,32 +16103,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-menu@2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      aria-hidden: 1.2.6
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-menu@2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16309,24 +16129,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-menubar@1.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-menubar@1.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16345,28 +16147,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-navigation-menu@1.2.15(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-navigation-menu@1.2.15(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16389,26 +16169,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-one-time-password-field@0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/number': 1.1.2
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-one-time-password-field@0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/number': 1.1.2
@@ -16429,22 +16189,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-password-toggle-field@0.1.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-password-toggle-field@0.1.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16461,29 +16205,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-popover@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      aria-hidden: 1.2.6
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-popover@1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16507,24 +16228,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-popper@1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@floating-ui/react-dom': 2.1.8(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-arrow': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-rect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/rect': 1.1.2
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-popper@1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/react-dom': 2.1.8(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -16543,16 +16246,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-portal@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-portal@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -16563,15 +16256,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-presence@1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-presence@1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -16581,15 +16265,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-primitive@2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-primitive@2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@19.2.6)
@@ -16599,16 +16274,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-progress@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-progress@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@19.2.6)
@@ -16619,24 +16284,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-radio-group@1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-radio-group@1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16655,23 +16302,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-roving-focus@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-roving-focus@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16689,23 +16319,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-scroll-area@1.2.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/number': 1.1.2
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-scroll-area@1.2.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/number': 1.1.2
@@ -16723,36 +16336,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-select@2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/number': 1.1.2
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      aria-hidden: 1.2.6
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-select@2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/number': 1.1.2
@@ -16783,15 +16366,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-separator@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-separator@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -16801,25 +16375,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-slider@1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/number': 1.1.2
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-slider@1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/number': 1.1.2
@@ -16839,13 +16394,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-slot@1.2.5(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-slot@1.2.5(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@19.2.6)
@@ -16853,21 +16401,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-switch@1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-switch@1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16883,22 +16416,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-tabs@1.1.14(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-tabs@1.1.14(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16915,26 +16432,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-toast@1.2.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-toast@1.2.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16955,21 +16452,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-toggle-group@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-toggle': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-toggle-group@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -16985,17 +16467,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-toggle@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-toggle@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -17007,21 +16478,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-toolbar@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-separator': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-toggle-group': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-toolbar@1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -17037,26 +16493,6 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-tooltip@1.2.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-tooltip@1.2.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -17077,26 +16513,12 @@ snapshots:
       '@types/react': 18.3.31
       '@types/react-dom': 18.3.7(@types/react@18.3.31)
 
-  '@radix-ui/react-use-callback-ref@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-callback-ref@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-controllable-state@1.2.3(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-controllable-state@1.2.3(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@19.2.6)
@@ -17105,13 +16527,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-effect-event@0.0.3(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-effect-event@0.0.3(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -17119,13 +16534,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-escape-keydown@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-escape-keydown@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -17133,49 +16541,24 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-is-hydrated@0.1.1(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-is-hydrated@0.1.1(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-layout-effect@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-layout-effect@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-previous@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-previous@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       react: 19.2.6
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-rect@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/rect': 1.1.2
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-rect@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/rect': 1.1.2
@@ -17183,13 +16566,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-use-size@1.1.2(@types/react@18.3.31)(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      react: 18.3.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   '@radix-ui/react-use-size@1.1.2(@types/react@18.3.31)(react@19.2.6)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@19.2.6)
@@ -17197,15 +16573,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  '@radix-ui/react-visually-hidden@1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   '@radix-ui/react-visually-hidden@1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -17730,11 +17097,6 @@ snapshots:
       '@tanstack/react-query': 5.101.0(react@19.2.6)
       react: 19.2.6
 
-  '@tanstack/react-query@5.101.0(react@18.3.1)':
-    dependencies:
-      '@tanstack/query-core': 5.101.0
-      react: 18.3.1
-
   '@tanstack/react-query@5.101.0(react@19.2.6)':
     dependencies:
       '@tanstack/query-core': 5.101.0
@@ -17746,12 +17108,6 @@ snapshots:
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
 
-  '@tanstack/react-table@8.21.3(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
-    dependencies:
-      '@tanstack/table-core': 8.21.3
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-
   '@tanstack/react-table@8.21.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@tanstack/table-core': 8.21.3
@@ -18063,6 +17419,7 @@ snapshots:
       - '@types/react-dom'
       - bufferutil
       - debug
+      - encoding
       - pdfjs-dist
       - prop-types
       - react-is
@@ -18187,6 +17544,7 @@ snapshots:
       - '@types/react-dom'
       - bufferutil
       - debug
+      - encoding
       - pdfjs-dist
       - prop-types
       - react-is
@@ -18895,6 +18253,9 @@ snapshots:
       jsonparse: 1.3.1
       through: 2.3.8
 
+  abbrev@1.1.1:
+    optional: true
+
   abort-controller@3.0.0:
     dependencies:
       event-target-shim: 5.0.1
@@ -19173,6 +18534,9 @@ snapshots:
 
   append-field@1.0.0: {}
 
+  aproba@2.1.0:
+    optional: true
+
   arch@2.2.0: {}
 
   archiver-utils@2.1.0:
@@ -19211,6 +18575,12 @@ snapshots:
       tar-stream: 2.2.0
       zip-stream: 4.1.1
 
+  are-we-there-yet@2.0.0:
+    dependencies:
+      delegates: 1.0.0
+      readable-stream: 3.6.2
+    optional: true
+
   arg@4.1.3: {}
 
   arg@5.0.2: {}
@@ -19765,6 +19135,16 @@ snapshots:
 
   caniuse-lite@1.0.30001797: {}
 
+  canvas@2.11.2:
+    dependencies:
+      '@mapbox/node-pre-gyp': 1.0.11
+      nan: 2.28.0
+      simple-get: 3.1.1
+    transitivePeerDependencies:
+      - encoding
+      - supports-color
+    optional: true
+
   canvg@3.0.11:
     dependencies:
       '@babel/runtime': 7.29.7
@@ -19845,6 +19225,9 @@ snapshots:
     dependencies:
       readdirp: 4.1.2
 
+  chownr@2.0.0:
+    optional: true
+
   chrome-trace-event@1.0.4: {}
 
   chromium-bidi@14.0.0(devtools-protocol@0.0.1608973):
@@ -20008,6 +19391,9 @@ snapshots:
     dependencies:
       color-name: 2.1.0
 
+  color-support@1.1.3:
+    optional: true
+
   colorette@2.0.20: {}
 
   colors@1.4.0:
@@ -20071,6 +19457,9 @@ snapshots:
 
   consola@3.4.2: {}
 
+  console-control-strings@1.1.0:
+    optional: true
+
   content-disposition@0.5.4:
     dependencies:
       safe-buffer: 5.2.1
@@ -20368,8 +19757,6 @@ snapshots:
 
   date-fns@3.6.0: {}
 
-  date-fns@4.4.0: {}
-
   date.js@0.3.3:
     dependencies:
       debug: 3.1.0
@@ -20416,6 +19803,11 @@ snapshots:
 
   decode-uri-component@0.2.2: {}
 
+  decompress-response@4.2.1:
+    dependencies:
+      mimic-response: 2.1.0
+    optional: true
+
   dedent@1.7.2(babel-plugin-macros@3.1.0):
     optionalDependencies:
       babel-plugin-macros: 3.1.0
@@ -20482,6 +19874,9 @@ snapshots:
 
   delayed-stream@1.0.0: {}
 
+  delegates@1.0.0:
+    optional: true
+
   depd@2.0.0: {}
 
   dequal@2.0.3: {}
@@ -21628,6 +21023,11 @@ snapshots:
       jsonfile: 6.2.1
       universalify: 2.0.1
 
+  fs-minipass@2.1.0:
+    dependencies:
+      minipass: 3.3.6
+    optional: true
+
   fs-monkey@1.1.0: {}
 
   fs.realpath@1.0.0: {}
@@ -21660,6 +21060,19 @@ snapshots:
 
   fuzzysort@3.1.0: {}
 
+  gauge@3.0.2:
+    dependencies:
+      aproba: 2.1.0
+      color-support: 1.1.3
+      console-control-strings: 1.1.0
+      has-unicode: 2.0.1
+      object-assign: 4.1.1
+      signal-exit: 3.0.7
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+      wide-align: 1.1.5
+    optional: true
+
   generator-function@2.0.1: {}
 
   gensync@1.0.0-beta.2: {}
@@ -21902,6 +21315,9 @@ snapshots:
     dependencies:
       has-symbols: 1.1.0
 
+  has-unicode@2.0.1:
+    optional: true
+
   has-value@0.3.1:
     dependencies:
       get-value: 2.0.6
@@ -22892,7 +22308,7 @@ snapshots:
 
   jsbn@0.1.1: {}
 
-  jsdom@25.0.1:
+  jsdom@25.0.1(canvas@2.11.2):
     dependencies:
       cssstyle: 4.6.0
       data-urls: 5.0.0
@@ -22915,6 +22331,8 @@ snapshots:
       whatwg-url: 14.2.0
       ws: 8.21.0
       xml-name-validator: 5.0.0
+    optionalDependencies:
+      canvas: 2.11.2
     transitivePeerDependencies:
       - bufferutil
       - supports-color
@@ -23351,18 +22769,14 @@ snapshots:
 
   lru-cache@7.18.3: {}
 
-  lucide-react@0.446.0(react@18.3.1):
+  lucide-react@0.446.0(react@19.2.6):
     dependencies:
-      react: 18.3.1
+      react: 19.2.6
 
   lucide-react@0.513.0(react@19.2.6):
     dependencies:
       react: 19.2.6
 
-  lucide-react@1.17.0(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-
   lucide-react@1.17.0(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -23379,6 +22793,11 @@ snapshots:
 
   make-cancellable-promise@2.0.0: {}
 
+  make-dir@3.1.0:
+    dependencies:
+      semver: 6.3.1
+    optional: true
+
   make-dir@4.0.0:
     dependencies:
       semver: 7.8.2
@@ -23902,6 +23321,9 @@ snapshots:
 
   mimic-function@5.0.1: {}
 
+  mimic-response@2.1.0:
+    optional: true
+
   minimatch@10.2.5:
     dependencies:
       brace-expansion: 5.0.6
@@ -23937,8 +23359,22 @@ snapshots:
       xml: 1.0.1
       xml2js: 0.5.0
 
+  minipass@3.3.6:
+    dependencies:
+      yallist: 4.0.0
+    optional: true
+
+  minipass@5.0.0:
+    optional: true
+
   minipass@7.1.3: {}
 
+  minizlib@2.1.2:
+    dependencies:
+      minipass: 3.3.6
+      yallist: 4.0.0
+    optional: true
+
   mitt@3.0.1: {}
 
   mixin-deep@1.3.2:
@@ -23950,6 +23386,9 @@ snapshots:
     dependencies:
       minimist: 1.2.8
 
+  mkdirp@1.0.4:
+    optional: true
+
   moment@2.30.1: {}
 
   motion-dom@12.40.0:
@@ -24045,6 +23484,9 @@ snapshots:
       object-assign: 4.1.1
       thenify-all: 1.6.0
 
+  nan@2.28.0:
+    optional: true
+
   nanoid@3.3.12: {}
 
   nanomatch@1.2.13:
@@ -24088,7 +23530,7 @@ snapshots:
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
 
-  next@14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+  next@14.2.35(@playwright/test@1.61.1)(babel-plugin-macros@3.1.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       '@next/env': 14.2.35
       '@swc/helpers': 0.5.5
@@ -24096,9 +23538,9 @@ snapshots:
       caniuse-lite: 1.0.30001797
       graceful-fs: 4.2.11
       postcss: 8.4.31
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      styled-jsx: 5.1.1(babel-plugin-macros@3.1.0)(react@18.3.1)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      styled-jsx: 5.1.1(babel-plugin-macros@3.1.0)(react@19.2.6)
     optionalDependencies:
       '@next/swc-darwin-arm64': 14.2.33
       '@next/swc-darwin-x64': 14.2.33
@@ -24140,6 +23582,11 @@ snapshots:
 
   node-fetch-native@1.6.7: {}
 
+  node-fetch@2.7.0:
+    dependencies:
+      whatwg-url: 5.0.0
+    optional: true
+
   node-fetch@3.3.2:
     dependencies:
       data-uri-to-buffer: 4.0.1
@@ -24159,6 +23606,11 @@ snapshots:
 
   node-releases@2.0.47: {}
 
+  nopt@5.0.0:
+    dependencies:
+      abbrev: 1.1.1
+    optional: true
+
   normalize-path@3.0.0: {}
 
   normalize-svg-path@1.1.0:
@@ -24178,6 +23630,14 @@ snapshots:
       path-key: 4.0.0
       unicorn-magic: 0.3.0
 
+  npmlog@5.0.1:
+    dependencies:
+      are-we-there-yet: 2.0.0
+      console-control-strings: 1.1.0
+      gauge: 3.0.2
+      set-blocking: 2.0.0
+    optional: true
+
   nth-check@2.1.1:
     dependencies:
       boolbase: 1.0.0
@@ -24473,6 +23933,9 @@ snapshots:
 
   path-type@4.0.0: {}
 
+  path2d-polyfill@2.0.1:
+    optional: true
+
   path@0.12.7:
     dependencies:
       process: 0.11.10
@@ -24493,6 +23956,14 @@ snapshots:
       pako: 1.0.11
       tslib: 1.14.1
 
+  pdfjs-dist@3.11.174:
+    optionalDependencies:
+      canvas: 2.11.2
+      path2d-polyfill: 2.0.1
+    transitivePeerDependencies:
+      - encoding
+      - supports-color
+
   pdfjs-dist@5.4.296:
     optionalDependencies:
       '@napi-rs/canvas': 0.1.100
@@ -24775,9 +24246,9 @@ snapshots:
 
   pure-rand@6.1.0: {}
 
-  qrcode.react@3.2.0(react@18.3.1):
+  qrcode.react@3.2.0(react@19.2.6):
     dependencies:
-      react: 18.3.1
+      react: 19.2.6
 
   qrcode@1.5.4:
     dependencies:
@@ -24819,69 +24290,6 @@ snapshots:
       parchment: 3.0.0
       quill-delta: 5.1.0
 
-  radix-ui@1.5.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
-    dependencies:
-      '@radix-ui/primitive': 1.1.4
-      '@radix-ui/react-accessible-icon': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-accordion': 1.2.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-alert-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-arrow': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-aspect-ratio': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-avatar': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-checkbox': 1.3.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-collapsible': 1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-collection': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-context-menu': 2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-dropdown-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-focus-guards': 1.1.4(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-focus-scope': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-form': 0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-hover-card': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-label': 2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-menubar': 1.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-navigation-menu': 1.2.15(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-one-time-password-field': 0.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-password-toggle-field': 0.1.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-popover': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-popper': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.6(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-progress': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-radio-group': 1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-scroll-area': 1.2.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-select': 2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-separator': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slider': 1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-switch': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-tabs': 1.1.14(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-toast': 1.2.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-toggle': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-toggle-group': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-toolbar': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-tooltip': 1.2.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-escape-keydown': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@18.3.31)(react@18.3.1)
-      '@radix-ui/react-visually-hidden': 1.2.5(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-      '@types/react-dom': 18.3.7(@types/react@18.3.31)
-
   radix-ui@1.5.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       '@radix-ui/primitive': 1.1.4
@@ -25010,28 +24418,14 @@ snapshots:
       date-fns: 3.6.0
       react: 19.2.6
 
-  react-day-picker@9.14.0(react@18.3.1):
-    dependencies:
-      '@date-fns/tz': 1.5.0
-      '@tabby_ai/hijri-converter': 1.0.5
-      date-fns: 4.4.0
-      date-fns-jalali: 4.1.0-0
-      react: 18.3.1
-
   react-day-picker@9.14.0(react@19.2.6):
     dependencies:
       '@date-fns/tz': 1.5.0
       '@tabby_ai/hijri-converter': 1.0.5
-      date-fns: 4.4.0
+      date-fns: 3.6.0
       date-fns-jalali: 4.1.0-0
       react: 19.2.6
 
-  react-dom@18.3.1(react@18.3.1):
-    dependencies:
-      loose-envify: 1.4.0
-      react: 18.3.1
-      scheduler: 0.23.2
-
   react-dom@19.2.6(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -25044,10 +24438,6 @@ snapshots:
       prop-types: 15.8.1
       react: 19.2.6
 
-  react-hook-form@7.77.0(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-
   react-hook-form@7.77.0(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -25120,11 +24510,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  react-number-format@5.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-
   react-number-format@5.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -25144,13 +24529,16 @@ snapshots:
       make-cancellable-promise: 2.0.0
       make-event-props: 2.0.0
       merge-refs: 2.0.0(@types/react@18.3.31)
-      pdfjs-dist: 5.4.296
+      pdfjs-dist: 3.11.174
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
       tiny-invariant: 1.3.3
       warning: 4.0.3
     optionalDependencies:
       '@types/react': 18.3.31
+    transitivePeerDependencies:
+      - encoding
+      - supports-color
 
   react-phone-number-input@3.4.17(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
@@ -25181,14 +24569,6 @@ snapshots:
 
   react-refresh@0.17.0: {}
 
-  react-remove-scroll-bar@2.3.8(@types/react@18.3.31)(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-      react-style-singleton: 2.2.3(@types/react@18.3.31)(react@18.3.1)
-      tslib: 2.8.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   react-remove-scroll-bar@2.3.8(@types/react@18.3.31)(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -25197,17 +24577,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  react-remove-scroll@2.7.2(@types/react@18.3.31)(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-      react-remove-scroll-bar: 2.3.8(@types/react@18.3.31)(react@18.3.1)
-      react-style-singleton: 2.2.3(@types/react@18.3.31)(react@18.3.1)
-      tslib: 2.8.1
-      use-callback-ref: 1.3.3(@types/react@18.3.31)(react@18.3.1)
-      use-sidecar: 1.1.3(@types/react@18.3.31)(react@18.3.1)
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   react-remove-scroll@2.7.2(@types/react@18.3.31)(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -25267,21 +24636,13 @@ snapshots:
     dependencies:
       react-dom: 19.2.6(react@19.2.6)
 
-  react-smooth@4.0.4(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+  react-smooth@4.0.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       fast-equals: 5.4.0
       prop-types: 15.8.1
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-      react-transition-group: 4.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-
-  react-style-singleton@2.2.3(@types/react@18.3.31)(react@18.3.1):
-    dependencies:
-      get-nonce: 1.0.1
-      react: 18.3.1
-      tslib: 2.8.1
-    optionalDependencies:
-      '@types/react': 18.3.31
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-transition-group: 4.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
 
   react-style-singleton@2.2.3(@types/react@18.3.31)(react@19.2.6):
     dependencies:
@@ -25300,15 +24661,6 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
-  react-transition-group@4.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
-    dependencies:
-      '@babel/runtime': 7.29.7
-      dom-helpers: 5.2.1
-      loose-envify: 1.4.0
-      prop-types: 15.8.1
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-
   react-transition-group@4.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       '@babel/runtime': 7.29.7
@@ -25318,10 +24670,6 @@ snapshots:
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
 
-  react@18.3.1:
-    dependencies:
-      loose-envify: 1.4.0
-
   react@19.2.6: {}
 
   read-cache@1.0.0:
@@ -25384,15 +24732,15 @@ snapshots:
     dependencies:
       decimal.js-light: 2.5.1
 
-  recharts@2.15.4(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+  recharts@2.15.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6):
     dependencies:
       clsx: 2.1.1
       eventemitter3: 4.0.7
       lodash: 4.18.1
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
       react-is: 18.3.1
-      react-smooth: 4.0.4(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react-smooth: 4.0.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       recharts-scale: 0.4.5
       tiny-invariant: 1.3.3
       victory-vendor: 36.9.2
@@ -25690,10 +25038,6 @@ snapshots:
     dependencies:
       xmlchars: 2.2.0
 
-  scheduler@0.23.2:
-    dependencies:
-      loose-envify: 1.4.0
-
   scheduler@0.25.0-rc-603e6108-20241029: {}
 
   scheduler@0.27.0: {}
@@ -25905,6 +25249,16 @@ snapshots:
 
   signature_pad@2.3.2: {}
 
+  simple-concat@1.0.1:
+    optional: true
+
+  simple-get@3.1.1:
+    dependencies:
+      decompress-response: 4.2.1
+      once: 1.4.0
+      simple-concat: 1.0.1
+    optional: true
+
   sisteransi@1.0.5: {}
 
   slash@3.0.0: {}
@@ -26308,10 +25662,10 @@ snapshots:
     transitivePeerDependencies:
       - '@babel/core'
 
-  styled-jsx@5.1.1(babel-plugin-macros@3.1.0)(react@18.3.1):
+  styled-jsx@5.1.1(babel-plugin-macros@3.1.0)(react@19.2.6):
     dependencies:
       client-only: 0.0.1
-      react: 18.3.1
+      react: 19.2.6
     optionalDependencies:
       babel-plugin-macros: 3.1.0
 
@@ -26466,6 +25820,16 @@ snapshots:
       - bare-buffer
       - react-native-b4a
 
+  tar@6.2.1:
+    dependencies:
+      chownr: 2.0.0
+      fs-minipass: 2.1.0
+      minipass: 5.0.0
+      minizlib: 2.1.2
+      mkdirp: 1.0.4
+      yallist: 4.0.0
+    optional: true
+
   teex@1.0.1:
     dependencies:
       streamx: 2.27.0
@@ -26623,6 +25987,9 @@ snapshots:
     dependencies:
       tldts: 7.4.2
 
+  tr46@0.0.3:
+    optional: true
+
   tr46@5.1.1:
     dependencies:
       punycode: 2.3.1
@@ -27050,13 +26417,6 @@ snapshots:
       punycode: 1.4.1
       qs: 6.15.2
 
-  use-callback-ref@1.3.3(@types/react@18.3.31)(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-      tslib: 2.8.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   use-callback-ref@1.3.3(@types/react@18.3.31)(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -27089,14 +26449,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  use-sidecar@1.1.3(@types/react@18.3.31)(react@18.3.1):
-    dependencies:
-      detect-node-es: 1.1.0
-      react: 18.3.1
-      tslib: 2.8.1
-    optionalDependencies:
-      '@types/react': 18.3.31
-
   use-sidecar@1.1.3(@types/react@18.3.31)(react@19.2.6):
     dependencies:
       detect-node-es: 1.1.0
@@ -27105,11 +26457,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.31
 
-  use-sync-external-store@1.6.0(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-    optional: true
-
   use-sync-external-store@1.6.0(react@19.2.6):
     dependencies:
       react: 19.2.6
@@ -27286,7 +26633,7 @@ snapshots:
       lightningcss: 1.32.0
       terser: 5.48.0
 
-  vitest@2.1.9(@types/node@22.20.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(terser@5.48.0):
+  vitest@2.1.9(@types/node@22.20.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(terser@5.48.0):
     dependencies:
       '@vitest/expect': 2.1.9
       '@vitest/mocker': 2.1.9(msw@2.14.6(@types/node@22.20.1)(typescript@5.9.3))(vite@5.4.21(@types/node@22.20.1)(lightningcss@1.32.0)(terser@5.48.0))
@@ -27310,7 +26657,7 @@ snapshots:
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 22.20.1
-      jsdom: 25.0.1
+      jsdom: 25.0.1(canvas@2.11.2)
     transitivePeerDependencies:
       - less
       - lightningcss
@@ -27322,7 +26669,7 @@ snapshots:
       - supports-color
       - terser
 
-  vitest@2.1.9(@types/node@24.13.1)(jsdom@25.0.1)(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0):
+  vitest@2.1.9(@types/node@24.13.1)(jsdom@25.0.1(canvas@2.11.2))(lightningcss@1.32.0)(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(terser@5.48.0):
     dependencies:
       '@vitest/expect': 2.1.9
       '@vitest/mocker': 2.1.9(msw@2.14.6(@types/node@24.13.1)(typescript@5.9.3))(vite@5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0))
@@ -27346,7 +26693,7 @@ snapshots:
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 24.13.1
-      jsdom: 25.0.1
+      jsdom: 25.0.1(canvas@2.11.2)
     transitivePeerDependencies:
       - less
       - lightningcss
@@ -27410,6 +26757,9 @@ snapshots:
 
   webdriver-bidi-protocol@0.4.1: {}
 
+  webidl-conversions@3.0.1:
+    optional: true
+
   webidl-conversions@7.0.0: {}
 
   webpack-node-externals@3.0.0: {}
@@ -27468,6 +26818,12 @@ snapshots:
       tr46: 5.1.1
       webidl-conversions: 7.0.0
 
+  whatwg-url@5.0.0:
+    dependencies:
+      tr46: 0.0.3
+      webidl-conversions: 3.0.1
+    optional: true
+
   which-boxed-primitive@1.1.1:
     dependencies:
       is-bigint: 1.1.0
@@ -27524,6 +26880,11 @@ snapshots:
       siginfo: 2.0.0
       stackback: 0.0.2
 
+  wide-align@1.1.5:
+    dependencies:
+      string-width: 4.2.3
+    optional: true
+
   wmf@1.0.2: {}
 
   word-wrap@1.2.5: {}
@@ -27610,6 +26971,9 @@ snapshots:
 
   yallist@3.1.1: {}
 
+  yallist@4.0.0:
+    optional: true
+
   yaml@1.10.3: {}
 
   yaml@2.9.0: {}
@@ -27701,13 +27065,6 @@ snapshots:
 
   zod@4.4.3: {}
 
-  zustand@5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@18.3.1)(use-sync-external-store@1.6.0(react@18.3.1)):
-    optionalDependencies:
-      '@types/react': 18.3.31
-      immer: 11.1.8
-      react: 18.3.1
-      use-sync-external-store: 1.6.0(react@18.3.1)
-
   zustand@5.0.14(@types/react@18.3.31)(immer@11.1.8)(react@19.2.6)(use-sync-external-store@1.6.0(react@19.2.6)):
     optionalDependencies:
       '@types/react': 18.3.31

From 4098d25ca1f07ab16a0a6f47ff30e7e7dc9b518d Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 07:33:13 +0000
Subject: [PATCH 032/174] fix issue

---
 pnpm-lock.yaml      | 33 +++++++++++++++++++++++++++++++++
 pnpm-workspace.yaml |  7 -------
 2 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7f59d43c5..68573264b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -99,6 +99,9 @@ importers:
       '@tria-plc/api-common':
         specifier: file:../../local-packages/tria-plc-api-common-1.6.0.tgz
         version: file:local-packages/tria-plc-api-common-1.6.0.tgz(ae9a56cc1c6d93629dd85f7605ccd5b6)
+      '@tria-plc/auditlog':
+        specifier: file:../../local-packages/tria-plc-auditlog-1.1.2.tgz
+        version: file:local-packages/tria-plc-auditlog-1.1.2.tgz(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/microservices@11.1.24)(@nestjs/swagger@11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2))(@nestjs/typeorm@11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))))(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
       '@tria-plc/iamapi-common':
         specifier: file:../../local-packages/tria-plc-iamapi-common-1.0.0.tgz
         version: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(d0be280d95adfc1b38e59bdc80c5dec5)
@@ -5020,6 +5023,19 @@ packages:
       rxjs: ^7.8.0
       typeorm: ^0.3.0
 
+  '@tria-plc/auditlog@file:local-packages/tria-plc-auditlog-1.1.2.tgz':
+    resolution: {integrity: sha512-3kRaAtETvM9wVRSbwd2jyrts9DCcSV9yFUDoEpxJfVQDsIGY2d9K0c+h1LAjfNNaogZ8eeBcroyCrnWjwBmkYA==, tarball: file:local-packages/tria-plc-auditlog-1.1.2.tgz}
+    version: 1.1.2
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@nestjs/common': ^10.0.0 || ^11.0.0
+      '@nestjs/core': ^10.0.0 || ^11.0.0
+      '@nestjs/microservices': ^10.0.0 || ^11.0.0
+      '@nestjs/swagger': ^10.0.0 || ^11.0.0
+      '@nestjs/typeorm': ^10.0.0 || ^11.0.0
+      rxjs: ^7.0.0
+      typeorm: ^0.3.0
+
   '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz':
     resolution: {integrity: sha512-rfHSXOm/0VUMTj7HrvYysrEAqxItqfPs4Rd35qWJyaAk+snF1wTKFRVz6cRGPoQNj8fhplkVAefnvuKBuHT+xQ==, tarball: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz}
     version: 1.0.0
@@ -17883,6 +17899,18 @@ snapshots:
       - debug
       - supports-color
 
+  '@tria-plc/auditlog@file:local-packages/tria-plc-auditlog-1.1.2.tgz(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/microservices@11.1.24)(@nestjs/swagger@11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2))(@nestjs/typeorm@11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))))(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))':
+    dependencies:
+      '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/core': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/microservices@11.1.24)(@nestjs/platform-express@11.1.24)(@nestjs/websockets@11.1.27)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/microservices': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/websockets@11.1.27)(amqp-connection-manager@5.0.0(amqplib@2.0.1))(amqplib@2.0.1)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/swagger': 11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)
+      '@nestjs/typeorm': 11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
+      amqp-connection-manager: 5.0.0(amqplib@0.10.9)
+      amqplib: 0.10.9
+      rxjs: 7.8.2
+      typeorm: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
+
   '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(cc085a020c559b355f168432c579a024)':
     dependencies:
       '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)
@@ -18982,6 +19010,11 @@ snapshots:
       amqplib: 0.10.9
       promise-breaker: 6.0.0
 
+  amqp-connection-manager@5.0.0(amqplib@0.10.9):
+    dependencies:
+      amqplib: 0.10.9
+      promise-breaker: 6.0.0
+
   amqp-connection-manager@5.0.0(amqplib@2.0.1):
     dependencies:
       amqplib: 2.0.1
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index fe5740e5f..14f686558 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -26,10 +26,3 @@ allowBuilds:
   tesseract.js: true
   uglifyjs-webpack-plugin: true
   unrs-resolver: false
-
-overrides:
-  date-fns: ^3.6.0
-  pdfjs-dist: ^3.11.174
-  react: 19.2.6
-  react-dom: 19.2.6
-  typeorm: 0.3.30

From bc7790392c4c70f63d129611d3e59d290423d384 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 07:49:31 +0000
Subject: [PATCH 033/174] fix issue

---
 apps/edr-freight-api/Dockerfile      | 2 +-
 infrastructure/docker/Dockerfile.web | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/edr-freight-api/Dockerfile b/apps/edr-freight-api/Dockerfile
index a1d86723c..c0d8ddace 100644
--- a/apps/edr-freight-api/Dockerfile
+++ b/apps/edr-freight-api/Dockerfile
@@ -17,7 +17,7 @@ COPY --from=pruner /app/out/json/ .
 COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
 RUN --mount=type=secret,id=npmrc,target=./.npmrc,required=false \
     --mount=type=cache,id=pnpm,target=/pnpm/store \
-    pnpm install --frozen-lockfile
+    pnpm install --no-frozen-lockfile
 
 FROM base AS builder
 COPY --from=installer /app/ .
diff --git a/infrastructure/docker/Dockerfile.web b/infrastructure/docker/Dockerfile.web
index 1e26bf643..66de62fc8 100644
--- a/infrastructure/docker/Dockerfile.web
+++ b/infrastructure/docker/Dockerfile.web
@@ -18,7 +18,7 @@ COPY --from=pruner /app/out/json/ .
 COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
 RUN --mount=type=secret,id=npmrc,target=./.npmrc,required=false \
     --mount=type=cache,id=pnpm,target=/pnpm/store \
-    pnpm install --frozen-lockfile
+    pnpm install --no-frozen-lockfile
 
 FROM base AS builder
 ARG TURBO_FILTER

From 03e498d6e87139c26c670ee0e0033826ac0c37d1 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 12 Aug 2026 07:53:05 +0000
Subject: [PATCH 034/174] fixes

---
 apps/edr-freight-api/src/app.module.ts        |   6 +-
 .../src/common/request-log-context.spec.ts    | 102 +++++++++++++
 apps/edr-freight-api/src/logger.middleware.ts |  21 ---
 .../etrade-business-selection.spec.ts         |  15 ++
 .../companies/services/etrade.service.ts      |   3 +-
 .../complaints/services/etradeTinService.ts   |   3 +-
 .../src/filters/http-exception.filter.ts      |  14 ++
 packages/api-common/src/index.ts              |   4 +
 .../api-common/src/logging/request-context.ts | 109 ++++++++++++++
 .../src/logging/request-log.middleware.ts     | 137 ++++++++++++++++++
 packages/types/src/freight/etrade.ts          |   3 +-
 11 files changed, 391 insertions(+), 26 deletions(-)
 create mode 100644 apps/edr-freight-api/src/common/request-log-context.spec.ts
 delete mode 100644 apps/edr-freight-api/src/logger.middleware.ts
 create mode 100644 packages/api-common/src/logging/request-context.ts
 create mode 100644 packages/api-common/src/logging/request-log.middleware.ts

diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index 029f2040b..bb7a3b9fd 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -114,7 +114,7 @@ import { InterchangeDocumentsModule } from "./modules/interchange-documents/inte
 import { ImportOperationsModule } from "./modules/import-operations/import-operations.module";
 import { AiModule } from "./modules/ai/ai.module";
 import { AuditModule } from "./modules/audit/audit.module";
-import { LoggerMiddleware } from "./logger.middleware";
+import { RequestLogMiddleware } from "@edr/api-common";
 import { LoginAudienceMiddleware } from "./modules/auth/login-audience.middleware";
 import { PositionTypePermissionsCache } from "./common/position-type-permissions.cache";
 
@@ -392,7 +392,9 @@ export class AppModule implements OnApplicationBootstrap {
   }
 
   configure(consumer: MiddlewareConsumer) {
-    consumer.apply(LoggerMiddleware).forRoutes("*");
+    // FIRST: opens the request log context every later middleware/guard/service
+    // writes into via logCtx(). Anything applied above it logs into the void.
+    consumer.apply(RequestLogMiddleware).forRoutes("*");
     consumer
       .apply(LoginAudienceMiddleware)
       .forRoutes(
diff --git a/apps/edr-freight-api/src/common/request-log-context.spec.ts b/apps/edr-freight-api/src/common/request-log-context.spec.ts
new file mode 100644
index 000000000..0aefe3695
--- /dev/null
+++ b/apps/edr-freight-api/src/common/request-log-context.spec.ts
@@ -0,0 +1,102 @@
+import { Logger } from "@nestjs/common";
+import {
+  RequestLogMiddleware,
+  getLogContext,
+  logCtx,
+  runWithLogContext,
+} from "@edr/api-common";
+
+describe("logCtx", () => {
+  it("is a no-op outside a request", () => {
+    expect(() => logCtx({ bookingId: "b1" })).not.toThrow();
+    expect(getLogContext()).toBeUndefined();
+  });
+
+  it("collects data points across the request and isolates concurrent ones", async () => {
+    const collect = async (id: string) =>
+      runWithLogContext({ requestId: id }, async () => {
+        logCtx({ bookingId: id });
+        await Promise.resolve();
+        logCtx({ from: "DRAFT", to: "SUBMITTED" }, { path: "booking.status" });
+        logCtx({ wagonId: "w1" }, { path: "wagons", mode: "push" });
+        logCtx({ wagonId: "w2" }, { path: "wagons", mode: "push" });
+        logCtx(1, { path: "smsSent", mode: "count" });
+        logCtx(1, { path: "smsSent", mode: "count" });
+        logCtx("PAID", { path: "payment.state", mode: "set" });
+        logCtx({ ignored: true }, (ctx) => {
+          ctx.custom = "yes";
+        });
+        return getLogContext();
+      });
+
+    const [a, b] = await Promise.all([collect("r1"), collect("r2")]);
+
+    expect(a).toEqual({
+      requestId: "r1",
+      bookingId: "r1",
+      booking: { status: { from: "DRAFT", to: "SUBMITTED" } },
+      wagons: [{ wagonId: "w1" }, { wagonId: "w2" }],
+      smsSent: 2,
+      payment: { state: "PAID" },
+      custom: "yes",
+    });
+    expect(b?.requestId).toBe("r2");
+    expect(b?.bookingId).toBe("r2");
+  });
+});
+
+describe("RequestLogMiddleware", () => {
+  it("emits one canonical JSON line carrying the collected context", () => {
+    const lines: string[] = [];
+    jest
+      .spyOn(Logger.prototype, "warn")
+      .mockImplementation((m) => lines.push(String(m)));
+    jest.spyOn(Logger.prototype, "log").mockImplementation(() => undefined);
+
+    const listeners: Record<string, () => void> = {};
+    const req = {
+      method: "POST",
+      url: "/api/bookings/1/submit",
+      originalUrl: "/api/bookings/1/submit?dry=1",
+      baseUrl: "/api/bookings",
+      route: { path: "/:id/submit" },
+      headers: { "user-agent": "jest", "x-request-id": "req-42" },
+      ip: "10.0.0.1",
+      query: { dry: "1" },
+      user: { id: "u-7" },
+    };
+    const res = {
+      statusCode: 409,
+      writableEnded: true,
+      setHeader: jest.fn(),
+      on: (event: string, fn: () => void) => {
+        listeners[event] = fn;
+      },
+    };
+
+    new RequestLogMiddleware().use(req, res, () => {
+      logCtx({ bookingId: "b-1" });
+      logCtx("REJECTED", { path: "booking.outcome", mode: "set" });
+    });
+    listeners.finish();
+    listeners.close(); // aborts/close after finish must not double-log
+
+    expect(lines).toHaveLength(1);
+    expect(JSON.parse(lines[0])).toMatchObject({
+      type: "http_request",
+      requestId: "req-42",
+      method: "POST",
+      route: "/api/bookings/:id/submit",
+      url: "/api/bookings/1/submit?dry=1",
+      status: 409,
+      userId: "u-7",
+      ip: "10.0.0.1",
+      userAgent: "jest",
+      query: { dry: "1" },
+      bookingId: "b-1",
+      booking: { outcome: "REJECTED" },
+    });
+    expect(res.setHeader).toHaveBeenCalledWith("x-request-id", "req-42");
+    jest.restoreAllMocks();
+  });
+});
diff --git a/apps/edr-freight-api/src/logger.middleware.ts b/apps/edr-freight-api/src/logger.middleware.ts
deleted file mode 100644
index dd7532ec8..000000000
--- a/apps/edr-freight-api/src/logger.middleware.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-import { Injectable, NestMiddleware, Logger } from "@nestjs/common";
-import { Request, Response, NextFunction } from "express";
-
-@Injectable()
-export class LoggerMiddleware implements NestMiddleware {
-  private readonly logger = new Logger("HTTP");
-
-  use(req: Request, res: Response, next: NextFunction) {
-    const start = Date.now();
-
-    res.on("finish", () => {
-      const duration = Date.now() - start;
-
-      this.logger.log(
-        `${req.method} ${req.originalUrl} ${res.statusCode} ${duration}ms`,
-      );
-    });
-
-    next();
-  }
-}
diff --git a/apps/edr-freight-api/src/modules/companies/services/etrade-business-selection.spec.ts b/apps/edr-freight-api/src/modules/companies/services/etrade-business-selection.spec.ts
index 0719d7fe8..86117d306 100644
--- a/apps/edr-freight-api/src/modules/companies/services/etrade-business-selection.spec.ts
+++ b/apps/edr-freight-api/src/modules/companies/services/etrade-business-selection.spec.ts
@@ -63,6 +63,21 @@ describe('ETradeService business selection', () => {
     expect(fetched).toEqual(['MT/AA/14/670/11551235/2017']);
   });
 
+  it('survives the null entries eTrade puts in SubGroups', () => {
+    const { service } = build();
+    const info = companyInfo();
+    (info.Businesses[0] as any).SubGroups = [
+      null,
+      { Code: 66331, Description: 'Export trade in minerals' },
+      { Code: 1, Description: null },
+    ];
+    const data = service.extractRegistrationData(
+      { LicenceNumber: 'x' } as ETradeBusinessInfo,
+      info,
+    );
+    expect(data.businesses?.[0].activity).toBe('Export trade in minerals');
+  });
+
   it('lists every licence for the picker, code prefixes stripped', () => {
     const { service } = build();
     const data = service.extractRegistrationData(
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 45cc8e840..fac57238a 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
@@ -142,7 +142,8 @@ export class ETradeService {
         tradeName: b.TradesName?.trim() || "",
         activity: (b.SubGroups ?? [])
           // Some descriptions repeat the code inline ("(65611)Import trade …").
-          .map((g) => g.Description?.replace(/^\(\d+\)\s*/, "").trim())
+          // eTrade also puts null entries in this array, so every hop is optional.
+          .map((g) => g?.Description?.replace(/^\(\d+\)\s*/, "").trim())
           .filter(Boolean)
           .join(", "),
         renewedTo: b.RenewedTo || "",
diff --git a/apps/edr-freight-web/backoffice/src/complaints/services/etradeTinService.ts b/apps/edr-freight-web/backoffice/src/complaints/services/etradeTinService.ts
index 3bdc653c4..8feb7cfb8 100644
--- a/apps/edr-freight-web/backoffice/src/complaints/services/etradeTinService.ts
+++ b/apps/edr-freight-web/backoffice/src/complaints/services/etradeTinService.ts
@@ -101,7 +101,8 @@ export function mapEtradeBusinessLicenses(
     const tradeName = String(business.TradesName ?? "").trim();
     const tradeNameAmh = String(business.TradeNameAmh ?? "").trim();
     const activities = (business.SubGroups ?? [])
-      .map((group) => String(group.Description ?? "").trim())
+      // eTrade returns null entries in this array, not just a null array.
+      .map((group) => String(group?.Description ?? "").trim())
       .filter(Boolean);
 
     const displayTradeName =
diff --git a/packages/api-common/src/filters/http-exception.filter.ts b/packages/api-common/src/filters/http-exception.filter.ts
index 3dc301a0b..3015d239f 100644
--- a/packages/api-common/src/filters/http-exception.filter.ts
+++ b/packages/api-common/src/filters/http-exception.filter.ts
@@ -7,6 +7,8 @@ import {
   Logger,
 } from "@nestjs/common";
 
+import { logCtx } from "../logging/request-context";
+
 interface ErrorResponseBody {
   success: false;
   statusCode: number;
@@ -120,6 +122,18 @@ export class HttpExceptionFilter implements ExceptionFilter {
       path: request.url,
     };
 
+    // Land the failure on the request's canonical log line too — the middleware
+    // only sees a status code, not what threw. No-op outside a request.
+    logCtx(
+      {
+        name: exception instanceof Error ? exception.name : "Error",
+        message,
+        status,
+        stack: status >= 500 ? (exception as Error)?.stack : undefined,
+      },
+      { path: "error", mode: "set" },
+    );
+
     if (status >= 500) {
       this.logger.error(
         `${request.method} ${request.url} -> ${status}`,
diff --git a/packages/api-common/src/index.ts b/packages/api-common/src/index.ts
index 8561f3721..d71f026da 100644
--- a/packages/api-common/src/index.ts
+++ b/packages/api-common/src/index.ts
@@ -6,6 +6,10 @@ export * from "./decorators/public.decorator";
 // Filters
 export * from "./filters/http-exception.filter";
 
+// Logging
+export * from "./logging/request-context";
+export * from "./logging/request-log.middleware";
+
 // Interceptors
 export * from "./interceptors/response-transform.interceptor";
 
diff --git a/packages/api-common/src/logging/request-context.ts b/packages/api-common/src/logging/request-context.ts
new file mode 100644
index 000000000..0b41222ee
--- /dev/null
+++ b/packages/api-common/src/logging/request-context.ts
@@ -0,0 +1,109 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Per-request bag of data points that end up on the canonical request log line
+ * (see request-log.middleware.ts). Anything written here is flattened into one
+ * JSON object at the end of the request, so keep it to values that are safe to
+ * ship to a log aggregator: ids, states, counts, outcomes — never secrets,
+ * tokens, or raw uploads.
+ */
+export type RequestLogContext = Record<string, unknown>;
+
+const storage = new AsyncLocalStorage<RequestLogContext>();
+
+export const getLogContext = (): RequestLogContext | undefined =>
+  storage.getStore();
+
+export const runWithLogContext = <T>(
+  seed: RequestLogContext,
+  fn: () => T,
+): T => storage.run(seed, fn);
+
+export interface LogCtxOptions {
+  /**
+   * Dot path to write under, e.g. "booking.transition". Namespacing is just a
+   * path with one segment ("payment"). Root object when omitted.
+   */
+  path?: string;
+  /**
+   * How the value lands:
+   * - `merge` (default) — shallow-merge objects into the target
+   * - `set` — overwrite the target
+   * - `push` — append to an array at the target
+   * - `count` — add the value (default 1) to a numeric counter at the target
+   */
+  mode?: "merge" | "set" | "push" | "count";
+}
+
+/** Escape hatch when the four modes don't fit: mutate the context yourself. */
+export type LogCtxMutator = (ctx: RequestLogContext, value: unknown) => void;
+
+// ponytail: fixed cap so a loop calling logCtx in `push` mode can't grow an
+// unbounded array in memory / a megabyte log line. Per-path caps if one ever
+// legitimately needs more.
+const MAX_PUSHED = 100;
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/**
+ * Append a data point to the current request's canonical log line.
+ *
+ * No-op outside an HTTP request (bootstrap, cron, queue consumers) — callers
+ * never need to guard.
+ *
+ *   logCtx({ bookingId, status });                            // root merge
+ *   logCtx(intentId, { path: "payment.intentId", mode: "set" });
+ *   logCtx({ from, to }, { path: "booking.transition" });     // namespaced
+ *   logCtx({ wagonId }, { path: "wagons", mode: "push" });    // array
+ *   logCtx(1, { path: "smsSent", mode: "count" });            // counter
+ *   logCtx(err, (ctx, e) => { ctx.lastError = String(e); });  // custom
+ */
+export function logCtx(
+  value: unknown,
+  opts: LogCtxOptions | LogCtxMutator = {},
+): void {
+  const ctx = storage.getStore();
+  if (!ctx) return;
+
+  if (typeof opts === "function") {
+    opts(ctx, value);
+    return;
+  }
+
+  const { path, mode = "merge" } = opts;
+
+  if (!path) {
+    if (isPlainObject(value)) Object.assign(ctx, value);
+    return;
+  }
+
+  const keys = path.split(".");
+  const leaf = keys.pop() as string;
+  let node: Record<string, unknown> = ctx;
+  for (const key of keys) {
+    if (!isPlainObject(node[key])) node[key] = {};
+    node = node[key] as Record<string, unknown>;
+  }
+
+  switch (mode) {
+    case "set":
+      node[leaf] = value;
+      break;
+    case "push": {
+      const arr = Array.isArray(node[leaf]) ? (node[leaf] as unknown[]) : [];
+      if (arr.length < MAX_PUSHED) arr.push(value);
+      node[leaf] = arr;
+      break;
+    }
+    case "count":
+      node[leaf] =
+        ((node[leaf] as number) ?? 0) + (typeof value === "number" ? value : 1);
+      break;
+    default:
+      node[leaf] =
+        isPlainObject(node[leaf]) && isPlainObject(value)
+          ? Object.assign(node[leaf] as Record<string, unknown>, value)
+          : value;
+  }
+}
diff --git a/packages/api-common/src/logging/request-log.middleware.ts b/packages/api-common/src/logging/request-log.middleware.ts
new file mode 100644
index 000000000..a8067bf02
--- /dev/null
+++ b/packages/api-common/src/logging/request-log.middleware.ts
@@ -0,0 +1,137 @@
+import { randomUUID } from "node:crypto";
+import { Injectable, Logger, NestMiddleware } from "@nestjs/common";
+
+import {
+  RequestLogContext,
+  logCtx,
+  runWithLogContext,
+} from "./request-context";
+
+/**
+ * Structural request/response shapes — express types are not a dependency of
+ * this package (they arrive under @nestjs/platform-express in the apps).
+ */
+interface LoggedRequest {
+  method: string;
+  url: string;
+  originalUrl?: string;
+  baseUrl?: string;
+  route?: { path?: string };
+  headers: Record<string, string | string[] | undefined>;
+  ip?: string;
+  query?: Record<string, unknown>;
+  user?: Record<string, unknown> | null;
+}
+
+interface LoggedResponse {
+  statusCode: number;
+  writableEnded?: boolean;
+  setHeader(name: string, value: string): void;
+  on(event: string, listener: () => void): void;
+}
+
+const header = (req: LoggedRequest, name: string): string | undefined => {
+  const value = req.headers[name];
+  return Array.isArray(value) ? value[0] : value;
+};
+
+const userId = (req: LoggedRequest): string | undefined => {
+  const user = req.user;
+  if (!user) return undefined;
+  const id = user.id ?? user.sub ?? user.userId;
+  return typeof id === "string" || typeof id === "number"
+    ? String(id)
+    : undefined;
+};
+
+/**
+ * Opens an AsyncLocalStorage context for the request (so anything downstream
+ * can `logCtx(...)` into it) and emits ONE canonical JSON line per request when
+ * the response ends — request metadata plus every data point collected during
+ * the flow, on the same Nest logger transport as the rest of the app.
+ *
+ * Base fields win over collected context on key collisions, so a stray
+ * `logCtx({ status })` can never corrupt the fields dashboards filter on.
+ *
+ * Apply FIRST in `configure()`: middleware registered before this one runs
+ * outside the context and its `logCtx` calls are silently dropped.
+ */
+@Injectable()
+export class RequestLogMiddleware implements NestMiddleware {
+  private readonly logger = new Logger("HTTP");
+  private readonly canonical = new Logger("request");
+
+  use(req: LoggedRequest, res: LoggedResponse, next: () => void): void {
+    const start = Date.now();
+    const requestId = header(req, "x-request-id") ?? randomUUID();
+    res.setHeader("x-request-id", requestId);
+
+    // Held by reference, NOT read back through the ALS at emit time: response
+    // "finish"/"close" listeners are plain EventEmitter callbacks, which Node
+    // does not bind to the async context they were registered in — getStore()
+    // there returns whatever context happened to call res.end().
+    const ctx: RequestLogContext = {};
+
+    runWithLogContext(ctx, () => {
+      logCtx({ requestId });
+
+      let emitted = false;
+      // "finish" covers normal responses; "close" catches client aborts, where
+      // "finish" never fires and the request would vanish from the logs.
+      const emit = () => {
+        if (emitted) return;
+        emitted = true;
+
+        const url = req.originalUrl ?? req.url;
+        const status = res.statusCode;
+        const durationMs = Date.now() - start;
+
+        this.logger.log(`${req.method} ${url} ${status} ${durationMs}ms`);
+
+        const line = {
+          ...ctx,
+          type: "http_request",
+          requestId,
+          method: req.method,
+          route: req.route?.path
+            ? `${req.baseUrl ?? ""}${req.route.path}`
+            : undefined,
+          url,
+          status,
+          durationMs,
+          userId: userId(req),
+          ip: req.ip,
+          userAgent: header(req, "user-agent"),
+          query:
+            req.query && Object.keys(req.query).length ? req.query : undefined,
+          aborted: res.writableEnded === false ? true : undefined,
+        };
+        // A circular value pushed into the context must not throw inside a
+        // response listener — that would take the process down, not the log.
+        let json: string;
+        try {
+          json = JSON.stringify(line);
+        } catch {
+          json = JSON.stringify({
+            type: "http_request",
+            requestId,
+            method: req.method,
+            url,
+            status,
+            durationMs,
+            contextSerializationFailed: true,
+          });
+        }
+
+        if (status >= 500) this.canonical.error(json);
+        else if (status >= 400) this.canonical.warn(json);
+        else this.canonical.log(json);
+      };
+
+      res.on("finish", emit);
+      res.on("close", emit);
+
+      next();
+    });
+  }
+}
diff --git a/packages/types/src/freight/etrade.ts b/packages/types/src/freight/etrade.ts
index 6f33567e4..c23492413 100644
--- a/packages/types/src/freight/etrade.ts
+++ b/packages/types/src/freight/etrade.ts
@@ -55,7 +55,8 @@ export interface ETradeCompanyInfo {
     RenewedFrom: string;
     RenewedTo: string;
     BusinessLicensingGroupMain: string | null;
-    SubGroups: Array<{ Code: number; Description: string }> | null;
+    /** eTrade returns null entries in this array as well as a null array. */
+    SubGroups: Array<{ Code: number; Description: string | null } | null> | null;
   }>;
 }
 

From 86979afccd8c247dc5c9ce62fa43be1ed0ce877b Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 07:57:20 +0000
Subject: [PATCH 035/174] fix issue

---
 apps/edr-freight-api/Dockerfile      |  2 +-
 infrastructure/docker/Dockerfile.web |  2 +-
 pnpm-lock.yaml                       | 28 ----------------------------
 3 files changed, 2 insertions(+), 30 deletions(-)

diff --git a/apps/edr-freight-api/Dockerfile b/apps/edr-freight-api/Dockerfile
index c0d8ddace..a1d86723c 100644
--- a/apps/edr-freight-api/Dockerfile
+++ b/apps/edr-freight-api/Dockerfile
@@ -17,7 +17,7 @@ COPY --from=pruner /app/out/json/ .
 COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
 RUN --mount=type=secret,id=npmrc,target=./.npmrc,required=false \
     --mount=type=cache,id=pnpm,target=/pnpm/store \
-    pnpm install --no-frozen-lockfile
+    pnpm install --frozen-lockfile
 
 FROM base AS builder
 COPY --from=installer /app/ .
diff --git a/infrastructure/docker/Dockerfile.web b/infrastructure/docker/Dockerfile.web
index 66de62fc8..1e26bf643 100644
--- a/infrastructure/docker/Dockerfile.web
+++ b/infrastructure/docker/Dockerfile.web
@@ -18,7 +18,7 @@ COPY --from=pruner /app/out/json/ .
 COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
 RUN --mount=type=secret,id=npmrc,target=./.npmrc,required=false \
     --mount=type=cache,id=pnpm,target=/pnpm/store \
-    pnpm install --no-frozen-lockfile
+    pnpm install --frozen-lockfile
 
 FROM base AS builder
 ARG TURBO_FILTER
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 68573264b..20f1adbc4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -99,9 +99,6 @@ importers:
       '@tria-plc/api-common':
         specifier: file:../../local-packages/tria-plc-api-common-1.6.0.tgz
         version: file:local-packages/tria-plc-api-common-1.6.0.tgz(ae9a56cc1c6d93629dd85f7605ccd5b6)
-      '@tria-plc/auditlog':
-        specifier: file:../../local-packages/tria-plc-auditlog-1.1.2.tgz
-        version: file:local-packages/tria-plc-auditlog-1.1.2.tgz(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/microservices@11.1.24)(@nestjs/swagger@11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2))(@nestjs/typeorm@11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))))(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
       '@tria-plc/iamapi-common':
         specifier: file:../../local-packages/tria-plc-iamapi-common-1.0.0.tgz
         version: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(d0be280d95adfc1b38e59bdc80c5dec5)
@@ -5023,19 +5020,6 @@ packages:
       rxjs: ^7.8.0
       typeorm: ^0.3.0
 
-  '@tria-plc/auditlog@file:local-packages/tria-plc-auditlog-1.1.2.tgz':
-    resolution: {integrity: sha512-3kRaAtETvM9wVRSbwd2jyrts9DCcSV9yFUDoEpxJfVQDsIGY2d9K0c+h1LAjfNNaogZ8eeBcroyCrnWjwBmkYA==, tarball: file:local-packages/tria-plc-auditlog-1.1.2.tgz}
-    version: 1.1.2
-    engines: {node: '>=18'}
-    peerDependencies:
-      '@nestjs/common': ^10.0.0 || ^11.0.0
-      '@nestjs/core': ^10.0.0 || ^11.0.0
-      '@nestjs/microservices': ^10.0.0 || ^11.0.0
-      '@nestjs/swagger': ^10.0.0 || ^11.0.0
-      '@nestjs/typeorm': ^10.0.0 || ^11.0.0
-      rxjs: ^7.0.0
-      typeorm: ^0.3.0
-
   '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz':
     resolution: {integrity: sha512-rfHSXOm/0VUMTj7HrvYysrEAqxItqfPs4Rd35qWJyaAk+snF1wTKFRVz6cRGPoQNj8fhplkVAefnvuKBuHT+xQ==, tarball: file:local-packages/tria-plc-iamapi-common-1.0.0.tgz}
     version: 1.0.0
@@ -17899,18 +17883,6 @@ snapshots:
       - debug
       - supports-color
 
-  '@tria-plc/auditlog@file:local-packages/tria-plc-auditlog-1.1.2.tgz(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/microservices@11.1.24)(@nestjs/swagger@11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2))(@nestjs/typeorm@11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))))(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))':
-    dependencies:
-      '@nestjs/common': 11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/core': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/microservices@11.1.24)(@nestjs/platform-express@11.1.24)(@nestjs/websockets@11.1.27)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/microservices': 11.1.24(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(@nestjs/websockets@11.1.27)(amqp-connection-manager@5.0.0(amqplib@2.0.1))(amqplib@2.0.1)(reflect-metadata@0.2.2)(rxjs@7.8.2)
-      '@nestjs/swagger': 11.4.4(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)
-      '@nestjs/typeorm': 11.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.24)(reflect-metadata@0.2.2)(rxjs@7.8.2)(typeorm@0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3)))
-      amqp-connection-manager: 5.0.0(amqplib@0.10.9)
-      amqplib: 0.10.9
-      rxjs: 7.8.2
-      typeorm: 0.3.30(babel-plugin-macros@3.1.0)(pg@8.21.0)(ts-node@10.9.2(@types/node@20.19.42)(typescript@5.9.3))
-
   '@tria-plc/iamapi-common@file:local-packages/tria-plc-iamapi-common-1.0.0.tgz(cc085a020c559b355f168432c579a024)':
     dependencies:
       '@nestjs/axios': 4.0.1(@nestjs/common@11.1.24(class-transformer@0.5.1)(class-validator@0.14.4)(reflect-metadata@0.2.2)(rxjs@7.8.2))(axios@1.17.0)(rxjs@7.8.2)

From bdcdb4f047c5e12846aa25c6aa2063834d585eec Mon Sep 17 00:00:00 2001
From: Roba Boru <robab@ethiopianairines.com>
Date: Wed, 12 Aug 2026 11:24:12 +0300
Subject: [PATCH 036/174] Added financial report

---
 .../src/modules/reports/reports.controller.ts |  31 +-
 .../src/modules/reports/reports.dto.ts        |  29 +
 .../src/modules/reports/reports.service.ts    | 184 +++++++
 .../edr-passenger-web/backoffice/package.json |   2 +
 .../src/app/reports/finance/layout.tsx        |   3 +
 .../src/app/reports/finance/page.tsx          | 521 ++++++++++++++++++
 .../src/components/layout/Sidebar.tsx         |   1 +
 .../backoffice/src/components/ui/Skeleton.tsx |  10 +
 .../backoffice/src/lib/api/finance.ts         |  65 +++
 .../src/lib/export/finance-workbook.ts        | 245 ++++++++
 .../backoffice/src/styles/globals.css         |  18 +
 pnpm-lock.yaml                                | 293 +++-------
 12 files changed, 1170 insertions(+), 232 deletions(-)
 create mode 100644 apps/edr-passenger-web/backoffice/src/app/reports/finance/layout.tsx
 create mode 100644 apps/edr-passenger-web/backoffice/src/app/reports/finance/page.tsx
 create mode 100644 apps/edr-passenger-web/backoffice/src/components/ui/Skeleton.tsx
 create mode 100644 apps/edr-passenger-web/backoffice/src/lib/api/finance.ts
 create mode 100644 apps/edr-passenger-web/backoffice/src/lib/export/finance-workbook.ts

diff --git a/apps/edr-passenger-api/src/modules/reports/reports.controller.ts b/apps/edr-passenger-api/src/modules/reports/reports.controller.ts
index 1eea923fd..725ddbbfc 100644
--- a/apps/edr-passenger-api/src/modules/reports/reports.controller.ts
+++ b/apps/edr-passenger-api/src/modules/reports/reports.controller.ts
@@ -8,7 +8,7 @@ import {
   ApiProduces,
 } from "@nestjs/swagger";
 import { ReportsService } from "./reports.service";
-import { BlockedSeatsRevenueLossQueryDto, GenerateReportDto } from "./reports.dto";
+import { BlockedSeatsRevenueLossQueryDto, FinanceSummaryQueryDto, GenerateReportDto } from "./reports.dto";
 import { PassengerStaff } from "../../common/passenger-guards";
 import { PASSENGER_PERMS } from "../../seed/passenger-permissions.registry";
 
@@ -83,6 +83,35 @@ export class ReportsController {
     return this.service.getPaymentDiscrepancyBySchedule(scheduleId, { search, seatClass, sort });
   }
 
+  // ── Finance Summary ──────────────────────────────────────────────────────
+
+  @Get("finance")
+  @ApiOperation({
+    summary: "Finance summary — revenue by period, origin/destination segment, and payment method",
+    description:
+      "Revenue collected in the window (PaymentIntent.paidAt), grouped by day/week/month, origin → " +
+      "destination station pair, and payment method. Filter by originStationId and/or destinationStationId " +
+      "independently to query any station-pair segment (A→B, A→D, B→C), not just a whole predefined route. " +
+      "Returns per-bucket rows plus roll-ups by period, segment, and method for charting.",
+  })
+  getFinanceSummary(@Query() query: FinanceSummaryQueryDto) {
+    return this.service.getFinanceSummary(query);
+  }
+
+  @Get("finance/export")
+  @ApiOperation({ summary: "Finance summary as CSV — one row per period + route + payment method" })
+  @ApiProduces("text/csv")
+  @ApiOkResponse({ description: "CSV export", schema: { type: "string" } })
+  async exportFinanceSummary(@Query() query: FinanceSummaryQueryDto, @Res() res: Response): Promise<void> {
+    const csv = await this.service.exportFinanceSummaryCsv(query);
+    res.setHeader("Content-Type", "text/csv; charset=utf-8");
+    res.setHeader(
+      "Content-Disposition",
+      `attachment; filename="finance-summary-${new Date().toISOString().split("T")[0]}.csv"`,
+    );
+    res.send(csv);
+  }
+
   // ── Blocked Seat Revenue Loss ──────────────────────────────────────────────
 
   @Get("blocked-seats-revenue-loss")
diff --git a/apps/edr-passenger-api/src/modules/reports/reports.dto.ts b/apps/edr-passenger-api/src/modules/reports/reports.dto.ts
index 8b8049807..6c6b304d4 100644
--- a/apps/edr-passenger-api/src/modules/reports/reports.dto.ts
+++ b/apps/edr-passenger-api/src/modules/reports/reports.dto.ts
@@ -1,6 +1,7 @@
 import { IsString, IsDateString, IsOptional, IsEnum, IsInt, Min, Max } from 'class-validator';
 import { Type } from 'class-transformer';
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { PaymentMethodType } from '@prisma/client';
 import { SeatBlockReasonCategory } from '../seats/seats.dto';
 
 export enum ReportType {
@@ -103,3 +104,31 @@ export class BlockedSeatsRevenueLossQueryDto {
   })
   @IsOptional() @IsEnum(BlockedSeatsLossSortBy) sortBy?: BlockedSeatsLossSortBy;
 }
+
+// ── Finance Summary ──────────────────────────────────────────────────────────
+
+export enum FinanceGranularity {
+  DAILY = 'daily',
+  WEEKLY = 'weekly',
+  MONTHLY = 'monthly',
+}
+
+export class FinanceSummaryQueryDto {
+  @ApiProperty({ example: '2026-07-01', description: 'Start of the window, inclusive, matched on PaymentIntent.paidAt.' })
+  @IsDateString() dateFrom: string;
+
+  @ApiProperty({ example: '2026-07-31', description: 'End of the window, inclusive, matched on PaymentIntent.paidAt.' })
+  @IsDateString() dateTo: string;
+
+  @ApiPropertyOptional({ enum: FinanceGranularity, default: FinanceGranularity.DAILY })
+  @IsOptional() @IsEnum(FinanceGranularity) granularity?: FinanceGranularity;
+
+  @ApiPropertyOptional({ description: 'Restrict to bookings departing from this station.' })
+  @IsOptional() @IsString() originStationId?: string;
+
+  @ApiPropertyOptional({ description: 'Restrict to bookings arriving at this station.' })
+  @IsOptional() @IsString() destinationStationId?: string;
+
+  @ApiPropertyOptional({ enum: PaymentMethodType, description: 'Restrict to payments made with this method.' })
+  @IsOptional() @IsEnum(PaymentMethodType) method?: PaymentMethodType;
+}
diff --git a/apps/edr-passenger-api/src/modules/reports/reports.service.ts b/apps/edr-passenger-api/src/modules/reports/reports.service.ts
index e899fdb4b..571df697e 100644
--- a/apps/edr-passenger-api/src/modules/reports/reports.service.ts
+++ b/apps/edr-passenger-api/src/modules/reports/reports.service.ts
@@ -10,6 +10,8 @@ import { FareEngineService } from "../fare-engine/fare-engine.service";
 import {
   BlockedSeatsLossSortBy,
   BlockedSeatsRevenueLossQueryDto,
+  FinanceGranularity,
+  FinanceSummaryQueryDto,
   GenerateReportDto,
   ReportType,
 } from "./reports.dto";
@@ -84,6 +86,33 @@ function toCsvCell(value: string | number): string {
   return `"${String(value).replace(/"/g, '""')}"`;
 }
 
+/**
+ * Buckets a paid-at timestamp into the requested reporting period, keyed so buckets sort
+ * chronologically as plain strings. Weekly buckets are labelled by their Monday (UTC).
+ */
+function periodKeyFor(date: Date, granularity: FinanceGranularity): string {
+  if (granularity === FinanceGranularity.MONTHLY) {
+    return date.toISOString().slice(0, 7);
+  }
+  if (granularity === FinanceGranularity.WEEKLY) {
+    const d = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+    const isoDay = d.getUTCDay() || 7; // Monday=1 .. Sunday=7
+    d.setUTCDate(d.getUTCDate() - (isoDay - 1));
+    return d.toISOString().split("T")[0];
+  }
+  return date.toISOString().split("T")[0];
+}
+
+export interface FinanceBucket {
+  period: string;
+  originStationId: string;
+  destinationStationId: string;
+  segmentLabel: string;
+  method: string;
+  bookingCount: number;
+  revenueEtbMinor: number;
+}
+
 @Injectable()
 export class ReportsService {
   private readonly logger = new Logger(ReportsService.name);
@@ -1051,6 +1080,161 @@ export class ReportsService {
     return { totalActualEtbMinor, totalPaidEtbMinor, byMethod, rows };
   }
 
+  // ── Finance Summary ────────────────────────────────────────────────────────
+
+  /**
+   * Revenue collected in the window, grouped by reporting period (day/week/month), origin →
+   * destination station pair, and payment method — the shape finance reconciles against
+   * provider settlement statements.
+   *
+   * Grouped by the booking's own origin/destination, not the parent Route — a route like
+   * "Sebeta - Dire Dawa" has intermediate stops, and a passenger may have booked any
+   * sub-segment of it (e.g. Lebu → Adama). Filtering by station lets finance ask about any
+   * A→B pair, not just whole routes.
+   *
+   * Bucketed on `PaymentIntent.paidAt` (cash actually received), not `Booking.createdAt`,
+   * so a booking made in one period but paid in another lands in the period it was paid.
+   */
+  async getFinanceSummary(query: FinanceSummaryQueryDto) {
+    const dateFrom = new Date(query.dateFrom + "T00:00:00.000Z");
+    const dateTo = new Date(query.dateTo + "T23:59:59.999Z");
+    const granularity = query.granularity ?? FinanceGranularity.DAILY;
+
+    const rateRows = await this.prisma.currencyExchangeRate.findMany({
+      where: { toCurrency: "ETB" as any },
+      orderBy: { effectiveDate: "desc" },
+    });
+    const rateToEtb = new Map<string, number>();
+    for (const r of rateRows) {
+      if (!rateToEtb.has(r.fromCurrency)) rateToEtb.set(r.fromCurrency, Number(r.rate));
+    }
+    const toEtbMinor = (minor: number, currency: string): number => {
+      if (currency === "ETB") return minor;
+      const rate = rateToEtb.get(currency);
+      return rate ? Math.round(minor * rate) : minor;
+    };
+
+    const bookings = await this.prisma.booking.findMany({
+      where: {
+        paymentIntent: {
+          paidAt: { gte: dateFrom, lte: dateTo },
+          ...(query.method ? { method: query.method } : {}),
+        },
+        ...(query.originStationId ? { originStationId: query.originStationId } : {}),
+        ...(query.destinationStationId ? { destinationStationId: query.destinationStationId } : {}),
+      },
+      select: {
+        totalMinor: true,
+        currency: true,
+        originStationId: true,
+        destinationStationId: true,
+        schedule: { select: { originStationId: true, destinationStationId: true } },
+        paymentIntent: { select: { paidAt: true, method: true } },
+      },
+    });
+
+    // Booking.originStationId/destinationStationId are set on every create path (guest and
+    // authenticated booking both pass them from the DTO); the schedule's own endpoints are
+    // only a fallback for the rare legacy row that predates those columns.
+    const stationIds = new Set<string>();
+    for (const b of bookings) {
+      const origin = b.originStationId ?? b.schedule.originStationId;
+      const destination = b.destinationStationId ?? b.schedule.destinationStationId;
+      if (origin) stationIds.add(origin);
+      if (destination) stationIds.add(destination);
+    }
+    const stations = stationIds.size > 0
+      ? await this.prisma.station.findMany({ where: { id: { in: [...stationIds] } }, select: { id: true, name: true } })
+      : [];
+    const stationName = new Map(stations.map((s) => [s.id, s.name]));
+
+    const buckets = new Map<string, FinanceBucket>();
+    const bucketFor = (
+      period: string,
+      originStationId: string,
+      destinationStationId: string,
+      segmentLabel: string,
+      method: string,
+    ): FinanceBucket => {
+      const key = `${period}|${originStationId}|${destinationStationId}|${method}`;
+      let bucket = buckets.get(key);
+      if (!bucket) {
+        bucket = { period, originStationId, destinationStationId, segmentLabel, method, bookingCount: 0, revenueEtbMinor: 0 };
+        buckets.set(key, bucket);
+      }
+      return bucket;
+    };
+
+    for (const b of bookings) {
+      const pi = b.paymentIntent!;
+      const period = periodKeyFor(pi.paidAt!, granularity);
+      const originStationId = b.originStationId ?? b.schedule.originStationId ?? "UNKNOWN";
+      const destinationStationId = b.destinationStationId ?? b.schedule.destinationStationId ?? "UNKNOWN";
+      const segmentLabel = `${stationName.get(originStationId) ?? "Unknown"} → ${stationName.get(destinationStationId) ?? "Unknown"}`;
+      const bucket = bucketFor(period, originStationId, destinationStationId, segmentLabel, pi.method);
+      bucket.bookingCount += 1;
+      bucket.revenueEtbMinor += toEtbMinor(b.totalMinor, b.currency);
+    }
+
+    const rows = [...buckets.values()].sort((a, b) =>
+      a.period === b.period
+        ? a.segmentLabel.localeCompare(b.segmentLabel) || a.method.localeCompare(b.method)
+        : a.period.localeCompare(b.period),
+    );
+
+    const totals = rows.reduce(
+      (acc, r) => {
+        acc.bookingCount += r.bookingCount;
+        acc.revenueEtbMinor += r.revenueEtbMinor;
+        return acc;
+      },
+      { bookingCount: 0, revenueEtbMinor: 0 },
+    );
+
+    const rollUp = (keyOf: (r: FinanceBucket) => string, labelOf: (r: FinanceBucket) => string) => {
+      const map = new Map<string, { key: string; label: string; revenueEtbMinor: number; bookingCount: number }>();
+      for (const r of rows) {
+        const key = keyOf(r);
+        let entry = map.get(key);
+        if (!entry) {
+          entry = { key, label: labelOf(r), revenueEtbMinor: 0, bookingCount: 0 };
+          map.set(key, entry);
+        }
+        entry.revenueEtbMinor += r.revenueEtbMinor;
+        entry.bookingCount += r.bookingCount;
+      }
+      return [...map.values()].sort((a, b) => b.revenueEtbMinor - a.revenueEtbMinor);
+    };
+
+    return {
+      granularity,
+      dateFrom: query.dateFrom,
+      dateTo: query.dateTo,
+      currency: "ETB",
+      totals,
+      byPeriod: rollUp((r) => r.period, (r) => r.period),
+      bySegment: rollUp((r) => `${r.originStationId}|${r.destinationStationId}`, (r) => r.segmentLabel),
+      byMethod: rollUp((r) => r.method, (r) => r.method),
+      rows,
+    };
+  }
+
+  /** CSV of the finance summary, one row per period + origin/destination segment + payment method. */
+  async exportFinanceSummaryCsv(query: FinanceSummaryQueryDto): Promise<string> {
+    const report = await this.getFinanceSummary(query);
+
+    const headers = ["Period", "Origin → Destination", "Payment Method", "Bookings", "Revenue (ETB)"];
+    const rows = report.rows.map((r) => [
+      r.period,
+      r.segmentLabel,
+      r.method,
+      r.bookingCount,
+      (r.revenueEtbMinor / 100).toFixed(2),
+    ]);
+
+    return [headers, ...rows].map((row) => row.map(toCsvCell).join(",")).join("\n");
+  }
+
   async getPaymentDiscrepancyBySchedule(scheduleId: string, params: {
     search?: string;
     seatClass?: string;
diff --git a/apps/edr-passenger-web/backoffice/package.json b/apps/edr-passenger-web/backoffice/package.json
index 9d4327a42..737baeda1 100644
--- a/apps/edr-passenger-web/backoffice/package.json
+++ b/apps/edr-passenger-web/backoffice/package.json
@@ -16,6 +16,8 @@
     "axios": "^1.7.7",
     "clsx": "^2.1.1",
     "date-fns": "^3.0.0",
+    "exceljs": "^4.4.0",
+    "html-to-image": "^1.11.11",
     "lucide-react": "^0.446.0",
     "next": "^14.2.0",
     "react": "^18.3.1",
diff --git a/apps/edr-passenger-web/backoffice/src/app/reports/finance/layout.tsx b/apps/edr-passenger-web/backoffice/src/app/reports/finance/layout.tsx
new file mode 100644
index 000000000..790272de1
--- /dev/null
+++ b/apps/edr-passenger-web/backoffice/src/app/reports/finance/layout.tsx
@@ -0,0 +1,3 @@
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return <>{children}</>;
+}
diff --git a/apps/edr-passenger-web/backoffice/src/app/reports/finance/page.tsx b/apps/edr-passenger-web/backoffice/src/app/reports/finance/page.tsx
new file mode 100644
index 000000000..8e3e2a23b
--- /dev/null
+++ b/apps/edr-passenger-web/backoffice/src/app/reports/finance/page.tsx
@@ -0,0 +1,521 @@
+'use client';
+
+import { useMemo, useRef, useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { Banknote, BookOpen, FileSpreadsheet, Receipt } from 'lucide-react';
+import {
+  Bar, BarChart, CartesianGrid, Line, LineChart,
+  ResponsiveContainer, Tooltip as RechartsTooltip, XAxis, YAxis,
+} from 'recharts';
+import { toPng } from 'html-to-image';
+import { apiClient } from '@/lib/api-client';
+import { financeApi, type FinanceGranularity, type FinanceSummaryFilters } from '@/lib/api/finance';
+import { buildFinanceWorkbook, type ChartImage } from '@/lib/export/finance-workbook';
+import ActionButton from '@/components/ui/ActionButton';
+import Pagination from '@/components/ui/Pagination';
+import Skeleton from '@/components/ui/Skeleton';
+import { usePagination } from '@/lib/use-pagination';
+import { formatCurrency } from '@/lib/utils';
+import { categoricalColor, getChartPalette } from '@/lib/chart-palette';
+import { useTheme } from '@/lib/theme-store';
+
+interface StationOption {
+  id: string;
+  name: string;
+  code: string;
+}
+
+// Fixed order so a method keeps its colour/slot when the method filter narrows the set.
+const PAYMENT_METHOD_ORDER = ['TELEBIRR', 'CBE_BIRR', 'EBIRR', 'WAAFI', 'CARD', 'WALLET', 'DMONEY', 'CAC_BANK', 'CBE_BILL'] as const;
+const PAYMENT_METHOD_LABELS: Record<string, string> = {
+  TELEBIRR: 'Telebirr',
+  CBE_BIRR: 'CBE Birr',
+  EBIRR: 'eBirr',
+  WAAFI: 'Waafi',
+  CARD: 'Card',
+  WALLET: 'Wallet',
+  DMONEY: 'DMoney',
+  CAC_BANK: 'CAC Bank',
+  CBE_BILL: 'CBE Bill',
+};
+function methodLabel(method: string): string {
+  return PAYMENT_METHOD_LABELS[method] ?? method;
+}
+
+function periodLabel(period: string, granularity: FinanceGranularity): string {
+  if (granularity === 'monthly') {
+    return new Date(`${period}-01T00:00:00`).toLocaleDateString('en-US', { month: 'short', year: 'numeric' });
+  }
+  return new Date(`${period}T00:00:00`).toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+}
+
+const TABLE_PAGE_SIZE = 25;
+
+/** Mirrors the loaded layout's shape (KPI tiles, two charts, method breakdown, detail table) so nothing jumps when data arrives. */
+function FinanceReportSkeleton() {
+  return (
+    <div className="space-y-6">
+      <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+        {Array.from({ length: 3 }).map((_, i) => (
+          <div key={i} className="card flex flex-col gap-3">
+            <div className="flex items-center justify-between">
+              <Skeleton className="h-3 w-24" />
+              <Skeleton className="h-7 w-7 rounded-lg" />
+            </div>
+            <Skeleton className="h-7 w-32" />
+          </div>
+        ))}
+      </div>
+
+      <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+        {Array.from({ length: 2 }).map((_, i) => (
+          <div key={i} className="card">
+            <Skeleton className="h-4 w-40 mb-4" />
+            <Skeleton className="h-[280px] w-full" />
+          </div>
+        ))}
+      </div>
+
+      <div className="card">
+        <Skeleton className="h-4 w-56 mb-2" />
+        <Skeleton className="h-3 w-32 mb-4" />
+        <Skeleton className="h-7 w-full mb-4" />
+        <div className="space-y-2">
+          {Array.from({ length: 4 }).map((_, i) => (
+            <Skeleton key={i} className="h-5 w-full" />
+          ))}
+        </div>
+      </div>
+
+      <div className="card p-0">
+        <div className="px-4 pt-4 pb-3">
+          <Skeleton className="h-4 w-52" />
+        </div>
+        <div className="px-4 pb-4 space-y-2">
+          {Array.from({ length: 8 }).map((_, i) => (
+            <Skeleton key={i} className="h-8 w-full" />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function FinanceReportPage() {
+  const isDark = useTheme((s) => s.isDark);
+  const palette = getChartPalette(isDark);
+
+  const [dateRangePreset, setDateRangePreset] = useState('90');
+  const [customFrom, setCustomFrom] = useState('');
+  const [customTo, setCustomTo] = useState('');
+  const [granularity, setGranularity] = useState<FinanceGranularity>('daily');
+  const [originStationId, setOriginStationId] = useState('');
+  const [destinationStationId, setDestinationStationId] = useState('');
+  const [method, setMethod] = useState('');
+  const [exporting, setExporting] = useState(false);
+
+  const trendCardRef = useRef<HTMLDivElement>(null);
+  const segmentCardRef = useRef<HTMLDivElement>(null);
+  const methodCardRef = useRef<HTMLDivElement>(null);
+
+  const { dateFrom, dateTo } = useMemo(() => {
+    const end = new Date();
+    end.setHours(23, 59, 59, 999);
+
+    if (dateRangePreset === 'custom') {
+      if (customFrom && customTo) {
+        return customFrom <= customTo
+          ? { dateFrom: customFrom, dateTo: customTo }
+          : { dateFrom: customTo, dateTo: customFrom };
+      }
+      const fallbackStart = new Date(end);
+      fallbackStart.setDate(end.getDate() - 90);
+      return {
+        dateFrom: fallbackStart.toISOString().split('T')[0],
+        dateTo: end.toISOString().split('T')[0],
+      };
+    }
+
+    const start = new Date(end);
+    start.setDate(end.getDate() - Number(dateRangePreset));
+    return {
+      dateFrom: start.toISOString().split('T')[0],
+      dateTo: end.toISOString().split('T')[0],
+    };
+  }, [dateRangePreset, customFrom, customTo]);
+
+  const filters: FinanceSummaryFilters = useMemo(
+    () => ({
+      dateFrom,
+      dateTo,
+      granularity,
+      originStationId: originStationId || undefined,
+      destinationStationId: destinationStationId || undefined,
+      method: method || undefined,
+    }),
+    [dateFrom, dateTo, granularity, originStationId, destinationStationId, method],
+  );
+
+  const { data: stations = [] } = useQuery<StationOption[]>({
+    queryKey: ['stations'],
+    queryFn: () => apiClient.get<StationOption[]>('/stations'),
+  });
+
+  const { data, isLoading, isFetching, isError } = useQuery({
+    queryKey: ['reports-finance', filters],
+    placeholderData: (previous) => previous,
+    queryFn: () => financeApi.getSummary(filters),
+  });
+
+  const rows = data?.rows ?? [];
+  const pg = usePagination(rows, TABLE_PAGE_SIZE);
+
+  const resetFilters = () => {
+    setDateRangePreset('90');
+    setCustomFrom('');
+    setCustomTo('');
+    setGranularity('daily');
+    setOriginStationId('');
+    setDestinationStationId('');
+    setMethod('');
+  };
+
+  /** Captures a chart card as a PNG data URL, sized to the card's actual on-screen pixels. */
+  const captureCard = async (node: HTMLDivElement | null): Promise<ChartImage | undefined> => {
+    if (!node) return undefined;
+    const rect = node.getBoundingClientRect();
+    const dataUrl = await toPng(node, { pixelRatio: 2, cacheBust: true, backgroundColor: palette.surface });
+    return { dataUrl, width: Math.round(rect.width), height: Math.round(rect.height) };
+  };
+
+  const doExport = async () => {
+    if (!data) return;
+    setExporting(true);
+    try {
+      const [trend, segment, method_] = await Promise.all([
+        captureCard(trendCardRef.current),
+        captureCard(segmentCardRef.current),
+        captureCard(methodCardRef.current),
+      ]);
+
+      const stationLabel = (id: string) => stations.find((s) => s.id === id)?.name ?? 'Any';
+
+      const blob = await buildFinanceWorkbook({
+        report: data,
+        filters: {
+          dateFrom,
+          dateTo,
+          granularity,
+          originLabel: originStationId ? stationLabel(originStationId) : 'Any',
+          destinationLabel: destinationStationId ? stationLabel(destinationStationId) : 'Any',
+          methodLabel: method ? methodLabel(method) : 'All',
+        },
+        methodLabel,
+        periodLabel,
+        images: { trend, segment, method: method_ },
+      });
+
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = `finance-summary-${dateFrom}-to-${dateTo}.xlsx`;
+      a.click();
+      URL.revokeObjectURL(url);
+    } finally {
+      setExporting(false);
+    }
+  };
+
+  const trendData = useMemo(
+    () =>
+      (data?.byPeriod ?? [])
+        .slice()
+        .sort((a, b) => a.key.localeCompare(b.key))
+        .map((p) => ({
+          label: periodLabel(p.key, data!.granularity),
+          revenue: p.revenueEtbMinor / 100,
+        })),
+    [data],
+  );
+
+  const segmentData = useMemo(
+    () =>
+      (data?.bySegment ?? [])
+        .slice()
+        .sort((a, b) => b.revenueEtbMinor - a.revenueEtbMinor)
+        .map((r) => ({ label: r.label, revenue: r.revenueEtbMinor })),
+    [data],
+  );
+
+  const methodBreakdown = useMemo(() => {
+    const rowsByMethod = data?.byMethod ?? [];
+    const total = rowsByMethod.reduce((sum, r) => sum + r.revenueEtbMinor, 0);
+    return rowsByMethod
+      .slice()
+      .sort((a, b) => PAYMENT_METHOD_ORDER.indexOf(a.key as any) - PAYMENT_METHOD_ORDER.indexOf(b.key as any))
+      .map((r) => ({
+        ...r,
+        color: categoricalColor(palette, PAYMENT_METHOD_ORDER.indexOf(r.key as any)),
+        sharePercent: total > 0 ? (r.revenueEtbMinor / total) * 100 : 0,
+      }));
+  }, [data, palette]);
+
+  const totals = data?.totals;
+  const hasData = (totals?.bookingCount ?? 0) > 0;
+  const avgPerBookingMinor = hasData ? Math.round(totals!.revenueEtbMinor / totals!.bookingCount) : 0;
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-start justify-between gap-4 flex-wrap">
+        <div>
+          <h1 className="text-3xl font-bold text-foreground">Finance Summary</h1>
+          <p className="text-muted-foreground mt-1">
+            Revenue collected by period, origin/destination, and payment method — for daily, weekly, or monthly finance reporting.
+          </p>
+        </div>
+        <ActionButton icon={FileSpreadsheet} variant="secondary" onClick={doExport} loading={exporting} disabled={!hasData}>
+          Export
+        </ActionButton>
+      </div>
+
+      {/* Filters */}
+      <div className="card">
+        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-6">
+          <div>
+            <label className="label">Date Range</label>
+            <select className="input" value={dateRangePreset} onChange={(e) => setDateRangePreset(e.target.value)}>
+              <option value="7">Last 7 Days</option>
+              <option value="30">Last 30 Days</option>
+              <option value="90">Last 90 Days</option>
+              <option value="custom">Custom Range</option>
+            </select>
+          </div>
+          {dateRangePreset === 'custom' && (
+            <>
+              <div>
+                <label className="label">Start Date</label>
+                <input type="date" className="input" value={customFrom} onChange={(e) => setCustomFrom(e.target.value)} />
+              </div>
+              <div>
+                <label className="label">End Date</label>
+                <input type="date" className="input" value={customTo} onChange={(e) => setCustomTo(e.target.value)} />
+              </div>
+            </>
+          )}
+          <div>
+            <label className="label">Granularity</label>
+            <select className="input" value={granularity} onChange={(e) => setGranularity(e.target.value as FinanceGranularity)}>
+              <option value="daily">Daily</option>
+              <option value="weekly">Weekly</option>
+              <option value="monthly">Monthly</option>
+            </select>
+          </div>
+          <div>
+            <label className="label">Origin</label>
+            <select className="input" value={originStationId} onChange={(e) => setOriginStationId(e.target.value)}>
+              <option value="">Any origin</option>
+              {stations.map((s) => (
+                <option key={s.id} value={s.id}>{s.name}</option>
+              ))}
+            </select>
+          </div>
+          <div>
+            <label className="label">Destination</label>
+            <select className="input" value={destinationStationId} onChange={(e) => setDestinationStationId(e.target.value)}>
+              <option value="">Any destination</option>
+              {stations.map((s) => (
+                <option key={s.id} value={s.id}>{s.name}</option>
+              ))}
+            </select>
+          </div>
+          <div>
+            <label className="label">Payment Method</label>
+            <select className="input" value={method} onChange={(e) => setMethod(e.target.value)}>
+              <option value="">All methods</option>
+              {PAYMENT_METHOD_ORDER.map((m) => (
+                <option key={m} value={m}>{methodLabel(m)}</option>
+              ))}
+            </select>
+          </div>
+        </div>
+        <div className="mt-4 flex items-center justify-between">
+          <button type="button" onClick={resetFilters} className="text-xs text-primary hover:underline">
+            Reset filters
+          </button>
+          {isFetching && <span className="text-xs text-muted-foreground">Refreshing…</span>}
+        </div>
+        {isError && <p className="text-xs text-red-500 mt-3">Failed to load the finance summary. Check the filters and try again.</p>}
+      </div>
+
+      {isLoading && !data ? (
+        <FinanceReportSkeleton />
+      ) : !hasData ? (
+        <div className="card py-16 text-center text-muted-foreground">
+          <Banknote className="h-10 w-10 mx-auto mb-3 opacity-30" />
+          <p>No paid bookings in this window.</p>
+          <p className="text-xs mt-1">Widen the date range, or clear the origin/destination/method filters.</p>
+        </div>
+      ) : (
+        <div className={isFetching ? 'opacity-60 transition-opacity space-y-6' : 'space-y-6'}>
+          {/* KPI tiles */}
+          <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+            <div className="card flex flex-col gap-1">
+              <div className="flex items-center justify-between">
+                <p className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">Revenue</p>
+                <div className="rounded-lg bg-emerald-100 dark:bg-emerald-900/30 p-1.5">
+                  <Banknote className="h-4 w-4 text-emerald-600 dark:text-emerald-400" />
+                </div>
+              </div>
+              <p className="text-2xl font-bold text-emerald-600 dark:text-emerald-400 tabular-nums mt-1">
+                {formatCurrency(totals!.revenueEtbMinor, 'ETB')}
+              </p>
+            </div>
+            <div className="card flex flex-col gap-1">
+              <div className="flex items-center justify-between">
+                <p className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">Bookings</p>
+                <div className="rounded-lg bg-blue-100 dark:bg-blue-900/30 p-1.5">
+                  <BookOpen className="h-4 w-4 text-blue-600 dark:text-blue-400" />
+                </div>
+              </div>
+              <p className="text-2xl font-bold tabular-nums mt-1">{totals!.bookingCount.toLocaleString()}</p>
+            </div>
+            <div className="card flex flex-col gap-1">
+              <div className="flex items-center justify-between">
+                <p className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">Avg. per Booking</p>
+                <div className="rounded-lg bg-amber-100 dark:bg-amber-900/30 p-1.5">
+                  <Receipt className="h-4 w-4 text-amber-600 dark:text-amber-400" />
+                </div>
+              </div>
+              <p className="text-2xl font-bold tabular-nums mt-1">{formatCurrency(avgPerBookingMinor, 'ETB')}</p>
+            </div>
+          </div>
+
+          {/* Trend + route charts */}
+          <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+            <div className="card" ref={trendCardRef}>
+              <h3 className="text-base font-semibold mb-4">
+                Revenue Trend <span className="text-xs font-normal text-muted-foreground">(ETB, {granularity})</span>
+              </h3>
+              {trendData.length > 0 ? (
+                <ResponsiveContainer width="100%" height={280}>
+                  <LineChart data={trendData}>
+                    <CartesianGrid strokeDasharray="3 3" stroke={palette.grid} />
+                    <XAxis dataKey="label" tick={{ fontSize: 11, fill: palette.textMuted }} />
+                    <YAxis tick={{ fontSize: 11, fill: palette.textMuted }} />
+                    <RechartsTooltip formatter={(value: number) => `ETB ${Math.round(value).toLocaleString()}`} />
+                    <Line type="monotone" dataKey="revenue" name="Revenue" stroke={palette.sequential} dot={{ r: 3 }} strokeWidth={2} />
+                  </LineChart>
+                </ResponsiveContainer>
+              ) : (
+                <div className="h-[280px] flex items-center justify-center text-muted-foreground text-sm">No data for selected range</div>
+              )}
+            </div>
+
+            <div className="card" ref={segmentCardRef}>
+              <h3 className="text-base font-semibold mb-4">Revenue by Segment</h3>
+              {segmentData.length > 0 ? (
+                <ResponsiveContainer width="100%" height={280}>
+                  <BarChart data={segmentData}>
+                    <CartesianGrid strokeDasharray="3 3" stroke={palette.grid} />
+                    <XAxis dataKey="label" tick={{ fontSize: 11, fill: palette.textMuted }} />
+                    <YAxis tick={{ fontSize: 11, fill: palette.textMuted }} />
+                    <RechartsTooltip formatter={(value: number) => `ETB ${Math.round(value).toLocaleString()}`} />
+                    <Bar dataKey="revenue" fill={palette.sequential} radius={[3, 3, 0, 0]} />
+                  </BarChart>
+                </ResponsiveContainer>
+              ) : (
+                <div className="h-[280px] flex items-center justify-center text-muted-foreground text-sm">No data for selected range</div>
+              )}
+            </div>
+          </div>
+
+          {/* Payment method breakdown — part-to-whole stacked bar + legend table */}
+          <div className="card" ref={methodCardRef}>
+            <h3 className="text-base font-semibold text-foreground">Revenue by Payment Method</h3>
+            <p className="text-xs text-muted-foreground mt-1 mb-4">Share of revenue, in ETB</p>
+            <div
+              className="flex w-full h-7 rounded-md overflow-hidden"
+              role="img"
+              aria-label={`Revenue by payment method: ${methodBreakdown
+                .map((m) => `${methodLabel(m.key)} ${m.sharePercent.toFixed(0)}%`)
+                .join(', ')}`}
+            >
+              {methodBreakdown.map((m, i) => (
+                <div
+                  key={m.key}
+                  className="h-full"
+                  style={{ width: `${m.sharePercent}%`, background: m.color, marginRight: i < methodBreakdown.length - 1 ? 2 : 0 }}
+                  title={`${methodLabel(m.key)} — ${formatCurrency(m.revenueEtbMinor, 'ETB')}`}
+                />
+              ))}
+            </div>
+            <table className="w-full text-sm mt-4">
+              <thead>
+                <tr className="text-xs uppercase tracking-wider text-muted-foreground">
+                  <th className="text-left font-medium py-2">Method</th>
+                  <th className="text-right font-medium py-2">Bookings</th>
+                  <th className="text-right font-medium py-2">Share</th>
+                  <th className="text-right font-medium py-2">Revenue</th>
+                </tr>
+              </thead>
+              <tbody className="divide-y divide-border">
+                {methodBreakdown.map((m) => (
+                  <tr key={m.key}>
+                    <td className="py-2">
+                      <span className="flex items-center gap-2">
+                        <span className="h-2.5 w-2.5 rounded-sm shrink-0" style={{ background: m.color }} aria-hidden="true" />
+                        <span className="text-foreground">{methodLabel(m.key)}</span>
+                      </span>
+                    </td>
+                    <td className="py-2 text-right tabular-nums text-muted-foreground">{m.bookingCount.toLocaleString()}</td>
+                    <td className="py-2 text-right tabular-nums text-muted-foreground">{m.sharePercent.toFixed(1)}%</td>
+                    <td className="py-2 text-right tabular-nums text-foreground font-medium">{formatCurrency(m.revenueEtbMinor, 'ETB')}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+
+          {/* Detail table */}
+          <div className="card p-0">
+            <div className="px-4 pt-4 pb-3">
+              <h3 className="text-sm font-semibold uppercase tracking-wider text-muted-foreground">
+                Period × Segment × Method detail
+              </h3>
+            </div>
+            <div className="overflow-x-auto">
+              <table className="w-full text-sm">
+                <thead className="bg-gray-50 dark:bg-gray-800">
+                  <tr>
+                    {['Period', 'Segment', 'Method', 'Bookings', 'Revenue'].map((h) => (
+                      <th key={h} className="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-400 whitespace-nowrap">
+                        {h}
+                      </th>
+                    ))}
+                  </tr>
+                </thead>
+                <tbody className="bg-white dark:bg-gray-900 divide-y divide-gray-200 dark:divide-gray-700">
+                  {pg.paged.map((r, i) => (
+                    <tr key={`${r.period}-${r.originStationId}-${r.destinationStationId}-${r.method}-${i}`} className="hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors">
+                      <td className="px-4 py-3 whitespace-nowrap text-foreground">{periodLabel(r.period, granularity)}</td>
+                      <td className="px-4 py-3 whitespace-nowrap text-muted-foreground">{r.segmentLabel}</td>
+                      <td className="px-4 py-3 whitespace-nowrap text-muted-foreground">{methodLabel(r.method)}</td>
+                      <td className="px-4 py-3 tabular-nums whitespace-nowrap">{r.bookingCount.toLocaleString()}</td>
+                      <td className="px-4 py-3 tabular-nums whitespace-nowrap font-medium">{formatCurrency(r.revenueEtbMinor, 'ETB')}</td>
+                    </tr>
+                  ))}
+                  {pg.paged.length === 0 && (
+                    <tr>
+                      <td colSpan={5} className="py-8 text-center text-sm text-muted-foreground">No rows on this page</td>
+                    </tr>
+                  )}
+                </tbody>
+              </table>
+            </div>
+            <Pagination currentPage={pg.page} totalPages={pg.totalPages} onPageChange={pg.setPage} />
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/apps/edr-passenger-web/backoffice/src/components/layout/Sidebar.tsx b/apps/edr-passenger-web/backoffice/src/components/layout/Sidebar.tsx
index 616488917..58a773b2f 100644
--- a/apps/edr-passenger-web/backoffice/src/components/layout/Sidebar.tsx
+++ b/apps/edr-passenger-web/backoffice/src/components/layout/Sidebar.tsx
@@ -123,6 +123,7 @@ const navigationSections: { title: string; items: NavItem[] }[] = [
     title: 'Analytics & Reports',
     items: [
       { name: 'Overall',              href: '/reports/overall',                icon: BarChart3,      permission: PERMS.reports.view },
+      { name: 'Finance',             href: '/reports/finance',                icon: DollarSign,     permission: PERMS.reports.view },
       { name: 'Seats',               href: '/reports/seats',                  icon: Armchair,       permission: PERMS.reports.view },
       { name: 'Blocked Seats',       href: '/reports/blocked-seats',          icon: Ban,            permission: PERMS.reports.view },
       { name: 'Passengers',          href: '/reports/passengers',             icon: Users,          permission: PERMS.reports.view },
diff --git a/apps/edr-passenger-web/backoffice/src/components/ui/Skeleton.tsx b/apps/edr-passenger-web/backoffice/src/components/ui/Skeleton.tsx
new file mode 100644
index 000000000..e6f24fb02
--- /dev/null
+++ b/apps/edr-passenger-web/backoffice/src/components/ui/Skeleton.tsx
@@ -0,0 +1,10 @@
+import { cn } from '@/lib/utils';
+
+interface SkeletonProps {
+  className?: string;
+}
+
+/** A shimmering placeholder block. Give it the size/shape of the content it stands in for. */
+export default function Skeleton({ className }: SkeletonProps) {
+  return <div className={cn('skeleton', className)} aria-hidden="true" />;
+}
diff --git a/apps/edr-passenger-web/backoffice/src/lib/api/finance.ts b/apps/edr-passenger-web/backoffice/src/lib/api/finance.ts
new file mode 100644
index 000000000..d99aaeae2
--- /dev/null
+++ b/apps/edr-passenger-web/backoffice/src/lib/api/finance.ts
@@ -0,0 +1,65 @@
+import { apiClient } from '@/lib/api-client';
+
+export type FinanceGranularity = 'daily' | 'weekly' | 'monthly';
+
+export interface FinanceSummaryFilters {
+  dateFrom: string;
+  dateTo: string;
+  granularity?: FinanceGranularity;
+  originStationId?: string;
+  destinationStationId?: string;
+  method?: string;
+}
+
+export interface FinanceBucketRow {
+  period: string;
+  originStationId: string;
+  destinationStationId: string;
+  segmentLabel: string;
+  method: string;
+  bookingCount: number;
+  revenueEtbMinor: number;
+}
+
+export interface FinanceRollupRow {
+  key: string;
+  label: string;
+  revenueEtbMinor: number;
+  bookingCount: number;
+}
+
+export interface FinanceTotals {
+  bookingCount: number;
+  revenueEtbMinor: number;
+}
+
+export interface FinanceSummaryReport {
+  granularity: FinanceGranularity;
+  dateFrom: string;
+  dateTo: string;
+  currency: string;
+  totals: FinanceTotals;
+  byPeriod: FinanceRollupRow[];
+  bySegment: FinanceRollupRow[];
+  byMethod: FinanceRollupRow[];
+  rows: FinanceBucketRow[];
+}
+
+/** Drops blanks so the API applies its own defaults (granularity=daily, no station/method filter). */
+function toParams(filters: FinanceSummaryFilters): Record<string, string> {
+  const params: Record<string, string> = { dateFrom: filters.dateFrom, dateTo: filters.dateTo };
+  if (filters.granularity) params.granularity = filters.granularity;
+  if (filters.originStationId) params.originStationId = filters.originStationId;
+  if (filters.destinationStationId) params.destinationStationId = filters.destinationStationId;
+  if (filters.method) params.method = filters.method;
+  return params;
+}
+
+export const financeApi = {
+  getSummary: (filters: FinanceSummaryFilters) =>
+    apiClient.get<FinanceSummaryReport>('/reports/finance', { params: toParams(filters) }),
+
+  /** CSV export. `getRaw` because the endpoint streams a bare CSV body, not the `{success,data}` envelope. */
+  exportCsv: (filters: FinanceSummaryFilters) =>
+    apiClient.getRaw<string>('/reports/finance/export', { params: toParams(filters) }),
+};
diff --git a/apps/edr-passenger-web/backoffice/src/lib/export/finance-workbook.ts b/apps/edr-passenger-web/backoffice/src/lib/export/finance-workbook.ts
new file mode 100644
index 000000000..da8f172be
--- /dev/null
+++ b/apps/edr-passenger-web/backoffice/src/lib/export/finance-workbook.ts
@@ -0,0 +1,245 @@
+import ExcelJS from 'exceljs';
+import type { FinanceGranularity, FinanceSummaryReport } from '@/lib/api/finance';
+
+// Brand palette — rgb(20,113,76), the same green used by ActionButton's primary variant,
+// so the exported file reads as the same product as the on-screen report.
+const BRAND = 'FF14714C';
+const BRAND_DARK = 'FF0E5A3D';
+const BRAND_TINT = 'FFEAF5EF';
+const INK = 'FF1F2937';
+const MUTED = 'FF6B7280';
+const ROW_ALT = 'FFF7F8F7';
+const BORDER = 'FFE2E5E1';
+const WHITE = 'FFFFFFFF';
+
+const CURRENCY_FMT = '"ETB" #,##0.00';
+const THIN_BORDER: Partial<ExcelJS.Borders> = {
+  top: { style: 'thin', color: { argb: BORDER } },
+  left: { style: 'thin', color: { argb: BORDER } },
+  bottom: { style: 'thin', color: { argb: BORDER } },
+  right: { style: 'thin', color: { argb: BORDER } },
+};
+
+export interface ChartImage {
+  dataUrl: string;
+  width: number;
+  height: number;
+}
+
+export interface FinanceWorkbookInput {
+  report: FinanceSummaryReport;
+  filters: { dateFrom: string; dateTo: string; granularity: FinanceGranularity; originLabel: string; destinationLabel: string; methodLabel: string };
+  methodLabel: (method: string) => string;
+  periodLabel: (period: string, granularity: FinanceGranularity) => string;
+  images: { trend?: ChartImage; segment?: ChartImage; method?: ChartImage };
+}
+
+function styleHeaderCell(cell: ExcelJS.Cell) {
+  cell.font = { bold: true, color: { argb: WHITE }, size: 11 };
+  cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: BRAND } };
+  cell.alignment = { vertical: 'middle', horizontal: 'left' };
+  cell.border = THIN_BORDER;
+}
+
+function addTableHeader(ws: ExcelJS.Worksheet, rowIndex: number, headers: string[], alignRight: Set<number> = new Set()) {
+  const row = ws.getRow(rowIndex);
+  headers.forEach((h, i) => {
+    const cell = row.getCell(i + 1);
+    cell.value = h;
+    styleHeaderCell(cell);
+    if (alignRight.has(i)) cell.alignment = { vertical: 'middle', horizontal: 'right' };
+  });
+  row.height = 20;
+  row.commit();
+}
+
+function bandRow(ws: ExcelJS.Worksheet, rowIndex: number, colCount: number, isAlt: boolean) {
+  const row = ws.getRow(rowIndex);
+  for (let c = 1; c <= colCount; c++) {
+    const cell = row.getCell(c);
+    cell.border = THIN_BORDER;
+    if (isAlt) cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: ROW_ALT } };
+  }
+}
+
+function titleBanner(ws: ExcelJS.Worksheet, title: string, subtitle: string, colSpan: number) {
+  ws.mergeCells(1, 1, 1, colSpan);
+  const titleCell = ws.getCell(1, 1);
+  titleCell.value = title;
+  titleCell.font = { bold: true, size: 18, color: { argb: WHITE } };
+  titleCell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: BRAND } };
+  titleCell.alignment = { vertical: 'middle', horizontal: 'left', indent: 1 };
+  ws.getRow(1).height = 34;
+  for (let c = 1; c <= colSpan; c++) ws.getCell(1, c).fill = titleCell.fill;
+
+  ws.mergeCells(2, 1, 2, colSpan);
+  const subCell = ws.getCell(2, 1);
+  subCell.value = subtitle;
+  subCell.font = { italic: true, size: 10, color: { argb: MUTED } };
+  subCell.alignment = { vertical: 'middle', horizontal: 'left', indent: 1 };
+  ws.getRow(2).height = 18;
+}
+
+function kpiCard(ws: ExcelJS.Worksheet, startRow: number, startCol: number, span: number, label: string, value: string, accent: string) {
+  ws.mergeCells(startRow, startCol, startRow, startCol + span - 1);
+  ws.mergeCells(startRow + 1, startCol, startRow + 1, startCol + span - 1);
+
+  const labelCell = ws.getCell(startRow, startCol);
+  labelCell.value = label.toUpperCase();
+  labelCell.font = { bold: true, size: 9, color: { argb: MUTED } };
+  labelCell.alignment = { vertical: 'middle', horizontal: 'left', indent: 1 };
+
+  const valueCell = ws.getCell(startRow + 1, startCol);
+  valueCell.value = value;
+  valueCell.font = { bold: true, size: 16, color: { argb: accent } };
+  valueCell.alignment = { vertical: 'middle', horizontal: 'left', indent: 1 };
+
+  for (let r = startRow; r <= startRow + 1; r++) {
+    for (let c = startCol; c < startCol + span; c++) {
+      const cell = ws.getCell(r, c);
+      cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: BRAND_TINT } };
+      cell.border = {
+        top: r === startRow ? { style: 'thin', color: { argb: BORDER } } : undefined,
+        bottom: r === startRow + 1 ? { style: 'thin', color: { argb: BORDER } } : undefined,
+        left: c === startCol ? { style: 'thin', color: { argb: BORDER } } : undefined,
+        right: c === startCol + span - 1 ? { style: 'thin', color: { argb: BORDER } } : undefined,
+      };
+    }
+  }
+  ws.getRow(startRow).height = 16;
+  ws.getRow(startRow + 1).height = 26;
+}
+
+function addImage(wb: ExcelJS.Workbook, ws: ExcelJS.Worksheet, image: ChartImage | undefined, anchorRow: number, heading: string) {
+  const headingCell = ws.getCell(anchorRow, 1);
+  headingCell.value = heading;
+  headingCell.font = { bold: true, size: 12, color: { argb: INK } };
+  ws.getRow(anchorRow).height = 20;
+
+  if (!image) {
+    const emptyCell = ws.getCell(anchorRow + 1, 1);
+    emptyCell.value = 'No chart available for the current filters.';
+    emptyCell.font = { italic: true, size: 10, color: { argb: MUTED } };
+    return anchorRow + 3;
+  }
+
+  const maxWidth = 640;
+  const scale = image.width > maxWidth ? maxWidth / image.width : 1;
+  const width = Math.round(image.width * scale);
+  const height = Math.round(image.height * scale);
+
+  const imageId = wb.addImage({ base64: image.dataUrl, extension: 'png' });
+  ws.addImage(imageId, {
+    tl: { col: 0.15, row: anchorRow + 0.15 },
+    ext: { width, height },
+  });
+
+  // Advance past the image height (≈20px per row) plus a spacer row.
+  const rowsUsed = Math.ceil(height / 20) + 2;
+  return anchorRow + rowsUsed;
+}
+
+export async function buildFinanceWorkbook(input: FinanceWorkbookInput): Promise<Blob> {
+  const { report, filters, images } = input;
+  const methodLabel = input.methodLabel;
+  const periodLabel = input.periodLabel;
+
+  const wb = new ExcelJS.Workbook();
+  wb.creator = 'EDR Passenger Backoffice';
+  wb.created = new Date();
+
+  // ── Summary sheet ─────────────────────────────────────────────────────────
+  const summary = wb.addWorksheet('Summary', { views: [{ showGridLines: false }] });
+  summary.columns = [{ width: 16 }, { width: 16 }, { width: 16 }, { width: 16 }, { width: 16 }, { width: 16 }];
+
+  titleBanner(
+    summary,
+    'EDR Passenger — Finance Summary',
+    `${filters.dateFrom} to ${filters.dateTo} · ${filters.granularity} · Origin: ${filters.originLabel} · Destination: ${filters.destinationLabel} · Method: ${filters.methodLabel} · Generated ${new Date().toLocaleString('en-US')}`,
+    6,
+  );
+
+  const avgPerBooking = report.totals.bookingCount > 0 ? report.totals.revenueEtbMinor / report.totals.bookingCount : 0;
+  kpiCard(summary, 4, 1, 2, 'Total Revenue', `ETB ${(report.totals.revenueEtbMinor / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}`, BRAND_DARK);
+  kpiCard(summary, 4, 3, 2, 'Bookings', report.totals.bookingCount.toLocaleString('en-US'), INK);
+  kpiCard(summary, 4, 5, 2, 'Avg. per Booking', `ETB ${(avgPerBooking / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}`, INK);
+
+  let cursor = 7;
+  cursor = addImage(wb, summary, images.trend, cursor, 'Revenue Trend') + 1;
+  cursor = addImage(wb, summary, images.segment, cursor, 'Revenue by Segment') + 1;
+  addImage(wb, summary, images.method, cursor, 'Revenue by Payment Method');
+
+  // ── By Period sheet ──────────────────────────────────────────────────────
+  const byPeriod = wb.addWorksheet('By Period', { views: [{ state: 'frozen', ySplit: 1 }] });
+  byPeriod.columns = [{ width: 18 }, { width: 14 }, { width: 20 }];
+  addTableHeader(byPeriod, 1, ['Period', 'Bookings', 'Revenue (ETB)'], new Set([1, 2]));
+  const periodRows = [...report.byPeriod].sort((a, b) => a.key.localeCompare(b.key));
+  periodRows.forEach((p, i) => {
+    const r = byPeriod.getRow(i + 2);
+    r.getCell(1).value = periodLabel(p.key, report.granularity);
+    r.getCell(2).value = p.bookingCount;
+    r.getCell(2).alignment = { horizontal: 'right' };
+    r.getCell(3).value = p.revenueEtbMinor / 100;
+    r.getCell(3).numFmt = CURRENCY_FMT;
+    r.getCell(3).alignment = { horizontal: 'right' };
+    bandRow(byPeriod, i + 2, 3, i % 2 === 1);
+  });
+  byPeriod.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 3 } };
+
+  // ── By Segment sheet ─────────────────────────────────────────────────────
+  const bySegment = wb.addWorksheet('By Segment', { views: [{ state: 'frozen', ySplit: 1 }] });
+  bySegment.columns = [{ width: 34 }, { width: 14 }, { width: 20 }];
+  addTableHeader(bySegment, 1, ['Origin → Destination', 'Bookings', 'Revenue (ETB)'], new Set([1, 2]));
+  report.bySegment.forEach((s, i) => {
+    const r = bySegment.getRow(i + 2);
+    r.getCell(1).value = s.label;
+    r.getCell(2).value = s.bookingCount;
+    r.getCell(2).alignment = { horizontal: 'right' };
+    r.getCell(3).value = s.revenueEtbMinor / 100;
+    r.getCell(3).numFmt = CURRENCY_FMT;
+    r.getCell(3).alignment = { horizontal: 'right' };
+    bandRow(bySegment, i + 2, 3, i % 2 === 1);
+  });
+  bySegment.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 3 } };
+
+  // ── By Method sheet ──────────────────────────────────────────────────────
+  const byMethod = wb.addWorksheet('By Method', { views: [{ state: 'frozen', ySplit: 1 }] });
+  byMethod.columns = [{ width: 20 }, { width: 14 }, { width: 20 }, { width: 12 }];
+  addTableHeader(byMethod, 1, ['Payment Method', 'Bookings', 'Revenue (ETB)', 'Share'], new Set([1, 2, 3]));
+  const methodTotal = report.byMethod.reduce((sum, m) => sum + m.revenueEtbMinor, 0);
+  report.byMethod.forEach((m, i) => {
+    const r = byMethod.getRow(i + 2);
+    r.getCell(1).value = methodLabel(m.key);
+    r.getCell(2).value = m.bookingCount;
+    r.getCell(2).alignment = { horizontal: 'right' };
+    r.getCell(3).value = m.revenueEtbMinor / 100;
+    r.getCell(3).numFmt = CURRENCY_FMT;
+    r.getCell(3).alignment = { horizontal: 'right' };
+    r.getCell(4).value = methodTotal > 0 ? m.revenueEtbMinor / methodTotal : 0;
+    r.getCell(4).numFmt = '0.0%';
+    r.getCell(4).alignment = { horizontal: 'right' };
+    bandRow(byMethod, i + 2, 4, i % 2 === 1);
+  });
+  byMethod.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 4 } };
+
+  // ── Detail sheet — every row, unpaginated ───────────────────────────────
+  const detail = wb.addWorksheet('Detail', { views: [{ state: 'frozen', ySplit: 1 }] });
+  detail.columns = [{ width: 18 }, { width: 34 }, { width: 18 }, { width: 14 }, { width: 20 }];
+  addTableHeader(detail, 1, ['Period', 'Origin → Destination', 'Payment Method', 'Bookings', 'Revenue (ETB)'], new Set([2, 3]));
+  report.rows.forEach((row, i) => {
+    const r = detail.getRow(i + 2);
+    r.getCell(1).value = periodLabel(row.period, report.granularity);
+    r.getCell(2).value = row.segmentLabel;
+    r.getCell(3).value = methodLabel(row.method);
+    r.getCell(4).value = row.bookingCount;
+    r.getCell(4).alignment = { horizontal: 'right' };
+    r.getCell(5).value = row.revenueEtbMinor / 100;
+    r.getCell(5).numFmt = CURRENCY_FMT;
+    r.getCell(5).alignment = { horizontal: 'right' };
+    bandRow(detail, i + 2, 5, i % 2 === 1);
+  });
+  detail.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 5 } };
+
+  const buffer = await wb.xlsx.writeBuffer();
+  return new Blob([buffer], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
+}
diff --git a/apps/edr-passenger-web/backoffice/src/styles/globals.css b/apps/edr-passenger-web/backoffice/src/styles/globals.css
index e14e614af..4fd8c86dc 100644
--- a/apps/edr-passenger-web/backoffice/src/styles/globals.css
+++ b/apps/edr-passenger-web/backoffice/src/styles/globals.css
@@ -68,6 +68,24 @@
   .animate-fade-up {
     animation: fade-up 0.25s cubic-bezier(0.22, 1, 0.36, 1) both;
   }
+
+  @keyframes shimmer {
+    from { background-position: -300px 0; }
+    to   { background-position: 300px 0; }
+  }
+  .skeleton {
+    border-radius: 0.5rem;
+    background-color: hsl(var(--muted));
+    background-image: linear-gradient(
+      90deg,
+      hsl(var(--muted)) 0%,
+      hsl(var(--muted-foreground) / 0.18) 50%,
+      hsl(var(--muted)) 100%
+    );
+    background-size: 600px 100%;
+    background-repeat: no-repeat;
+    animation: shimmer 1.5s ease-in-out infinite;
+  }
 }
 
 @layer components {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 68573264b..d67adb2bc 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -604,7 +604,7 @@ importers:
         version: 5.101.0(react@19.2.6)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)
       '@vis.gl/react-google-maps':
         specifier: ^1.8.3
         version: 1.8.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -983,6 +983,12 @@ importers:
       date-fns:
         specifier: ^3.0.0
         version: 3.6.0
+      exceljs:
+        specifier: ^4.4.0
+        version: 4.4.0
+      html-to-image:
+        specifier: ^1.11.11
+        version: 1.11.13
       lucide-react:
         specifier: ^0.446.0
         version: 0.446.0(react@18.3.1)
@@ -8338,6 +8344,9 @@ packages:
     resolution: {integrity: sha512-XxzooSo6oBoxBEUazgjdXj7VwTn/iSTSZzTYKzYY6I916tkaYzypHxy+pbVU1h+0UQ9JlVf5XkNQyxOAiiQO1g==}
     engines: {node: '>=0.10.0'}
 
+  html-to-image@1.11.13:
+    resolution: {integrity: sha512-cuOPoI7WApyhBElTTb9oqsawRvZ0rHhaHwghRLlTuffoD1B2aDemlCruLeZrUIIdvG7gs9xeELEPm6PhuASqrg==}
+
   html-url-attributes@3.0.1:
     resolution: {integrity: sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ==}
 
@@ -13063,11 +13072,11 @@ snapshots:
       '@babel/helpers': 7.29.7
       '@babel/parser': 7.29.7
       '@babel/template': 7.29.7
-      '@babel/traverse': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
       '@babel/types': 7.29.7
       '@jridgewell/remapping': 2.3.5
       convert-source-map: 2.0.0
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       gensync: 1.0.0-beta.2
       json5: 2.2.3
       semver: 6.3.1
@@ -13102,7 +13111,7 @@ snapshots:
       '@babel/helper-optimise-call-expression': 7.29.7
       '@babel/helper-replace-supers': 7.29.7(@babel/core@7.29.7)
       '@babel/helper-skip-transparent-expression-wrappers': 7.29.7
-      '@babel/traverse': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
       semver: 6.3.1
     transitivePeerDependencies:
       - supports-color
@@ -13111,14 +13120,7 @@ snapshots:
 
   '@babel/helper-member-expression-to-functions@7.29.7':
     dependencies:
-      '@babel/traverse': 7.29.7
-      '@babel/types': 7.29.7
-    transitivePeerDependencies:
-      - supports-color
-
-  '@babel/helper-module-imports@7.29.7':
-    dependencies:
-      '@babel/traverse': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
       '@babel/types': 7.29.7
     transitivePeerDependencies:
       - supports-color
@@ -13133,9 +13135,9 @@ snapshots:
   '@babel/helper-module-transforms@7.29.7(@babel/core@7.29.7)':
     dependencies:
       '@babel/core': 7.29.7
-      '@babel/helper-module-imports': 7.29.7
+      '@babel/helper-module-imports': 7.29.7(supports-color@5.5.0)
       '@babel/helper-validator-identifier': 7.29.7
-      '@babel/traverse': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
@@ -13150,13 +13152,13 @@ snapshots:
       '@babel/core': 7.29.7
       '@babel/helper-member-expression-to-functions': 7.29.7
       '@babel/helper-optimise-call-expression': 7.29.7
-      '@babel/traverse': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
   '@babel/helper-skip-transparent-expression-wrappers@7.29.7':
     dependencies:
-      '@babel/traverse': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
       '@babel/types': 7.29.7
     transitivePeerDependencies:
       - supports-color
@@ -13309,18 +13311,6 @@ snapshots:
       '@babel/parser': 7.29.7
       '@babel/types': 7.29.7
 
-  '@babel/traverse@7.29.7':
-    dependencies:
-      '@babel/code-frame': 7.29.7
-      '@babel/generator': 7.29.7
-      '@babel/helper-globals': 7.29.7
-      '@babel/parser': 7.29.7
-      '@babel/template': 7.29.7
-      '@babel/types': 7.29.7
-      debug: 4.4.3(supports-color@8.1.1)
-    transitivePeerDependencies:
-      - supports-color
-
   '@babel/traverse@7.29.7(supports-color@5.5.0)':
     dependencies:
       '@babel/code-frame': 7.29.7
@@ -13805,7 +13795,7 @@ snapshots:
 
   '@emotion/babel-plugin@11.13.5':
     dependencies:
-      '@babel/helper-module-imports': 7.29.7
+      '@babel/helper-module-imports': 7.29.7(supports-color@5.5.0)
       '@babel/runtime': 7.29.7
       '@emotion/hash': 0.9.2
       '@emotion/memoize': 0.9.0
@@ -13971,7 +13961,7 @@ snapshots:
   '@eslint/eslintrc@2.1.4':
     dependencies:
       ajv: 6.15.0
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       espree: 9.6.1
       globals: 13.24.0
       ignore: 5.3.2
@@ -14131,7 +14121,7 @@ snapshots:
   '@humanwhocodes/config-array@0.13.0':
     dependencies:
       '@humanwhocodes/object-schema': 2.0.3
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       minimatch: 3.1.5
     transitivePeerDependencies:
       - supports-color
@@ -15730,7 +15720,7 @@ snapshots:
 
   '@puppeteer/browsers@2.13.2':
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       extract-zip: 2.0.1
       progress: 2.0.3
       proxy-agent: 6.5.0
@@ -17804,7 +17794,7 @@ snapshots:
 
   '@tokenizer/inflate@0.4.1':
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       token-types: 6.1.2
     transitivePeerDependencies:
       - supports-color
@@ -18103,130 +18093,6 @@ snapshots:
       - utf-8-validate
       - vite
 
-  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)':
-    dependencies:
-      '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
-      '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
-      '@hookform/resolvers': 5.4.0(react-hook-form@7.77.0(react@19.2.6))
-      '@lottiefiles/react-lottie-player': 3.6.0(react@19.2.6)
-      '@mantine/charts': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(recharts@3.8.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)(redux@5.0.1))
-      '@mantine/core': 7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@mantine/dates': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@mantine/hooks': 7.17.8(react@19.2.6)
-      '@mantine/notifications': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-accordion': 1.2.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-alert-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-avatar': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-checkbox': 1.3.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-collapsible': 1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-context-menu': 2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-dropdown-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-hover-card': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-label': 2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-navigation-menu': 1.2.15(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-popover': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-progress': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-radio-group': 1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-scroll-area': 1.2.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-select': 2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-separator': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@19.2.6)
-      '@radix-ui/react-switch': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-tabs': 1.1.14(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-toast': 1.2.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-tooltip': 1.2.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@react-pdf-viewer/core': 3.12.0(pdfjs-dist@5.4.296)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@react-pdf-viewer/default-layout': 3.12.0(pdfjs-dist@5.4.296)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@react-pdf/renderer': 4.5.1(react@19.2.6)
-      '@reduxjs/toolkit': 2.12.0(react-redux@9.3.0(@types/react@18.3.31)(react@19.2.6)(redux@5.0.1))(react@19.2.6)
-      '@tabler/icons-react': 3.44.0(react@19.2.6)
-      '@tailwindcss/vite': 4.3.0(vite@5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0))
-      '@tanstack/react-query': 5.101.0(react@19.2.6)
-      '@tanstack/react-query-devtools': 5.101.0(@tanstack/react-query@5.101.0(react@19.2.6))(react@19.2.6)
-      '@tanstack/react-table': 8.21.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@tinymce/tinymce-react': 6.3.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tinymce@7.9.3)
-      '@types/dompurify': 3.2.0
-      '@types/node': 24.13.1
-      '@types/tinymce': 4.6.9
-      axios: 1.17.0
-      class-variance-authority: 0.7.1
-      clsx: 2.1.1
-      cmdk: 1.1.1(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      date-fns: 3.6.0
-      dayjs: 1.11.21
-      dompurify: 3.4.8
-      ethiopian-calendar-date-converter: 2.1.6
-      ethiopian-calendar-new: 1.1.0
-      file-type: 18.7.0
-      framer-motion: 12.40.0(@emotion/is-prop-valid@1.4.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      html2canvas: 1.4.1
-      i18next: 25.10.10(typescript@5.9.3)
-      i18next-browser-languagedetector: 8.2.1
-      jquery: 3.7.1
-      js-cookie: 3.0.8
-      jspdf: 3.0.4
-      lodash: 4.18.1
-      lucide-react: 0.513.0(react@19.2.6)
-      mantine-react-table: 2.0.0-beta.9(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/dates@7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(@tabler/icons-react@3.44.0(react@19.2.6))(clsx@2.1.1)(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      mui-ethiopian-datepicker: 0.3.2(4b3af212eafdf0059f009b005d7e343d)
-      next-themes: 0.4.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      path: 0.12.7
-      pdf-lib: 1.17.1
-      qs: 6.15.2
-      react: 19.2.6
-      react-cookie: 8.1.2(@types/react@18.3.31)(react@19.2.6)
-      react-css-nocode-editor: 1.0.13(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)
-      react-day-picker: 8.10.2(date-fns@3.6.0)(react@19.2.6)
-      react-dom: 19.2.6(react@19.2.6)
-      react-dropzone: 14.4.1(react@19.2.6)
-      react-hook-form: 7.77.0(react@19.2.6)
-      react-i18next: 15.7.4(i18next@25.10.10(typescript@5.9.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.9.3)
-      react-icons: 5.6.0(react@19.2.6)
-      react-image-crop: 11.0.10(react@19.2.6)
-      react-intersection-observer: 9.16.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      react-pdf: 10.4.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      react-pdf-html: 2.1.5(@react-pdf/renderer@4.5.1(react@19.2.6))(react@19.2.6)
-      react-redux: 9.3.0(@types/react@18.3.31)(react@19.2.6)(redux@5.0.1)
-      react-resizable-panels: 3.0.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      react-router-dom: 7.17.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      react-signature-canvas: 1.1.0-alpha.2(@types/prop-types@15.7.15)(@types/react@18.3.31)(prop-types@15.8.1)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      recharts: 3.8.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)(redux@5.0.1)
-      rollup-plugin-visualizer: 7.0.1(rollup@4.61.1)
-      socket.io-client: 4.8.3
-      sonner: 2.0.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      tailwind-merge: 3.6.0
-      tailwind-scrollbar-hide: 4.0.0(tailwindcss@4.3.0)
-      tailwindcss: 4.3.0
-      tailwindcss-animate: 1.0.7(tailwindcss@4.3.0)
-      tinymce: 7.9.3
-      url: 0.11.4
-      vaul: 1.1.2(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      xlsx: 0.18.5
-      zod: 3.25.76
-    transitivePeerDependencies:
-      - '@babel/core'
-      - '@emotion/is-prop-valid'
-      - '@mui/icons-material'
-      - '@mui/material'
-      - '@mui/x-date-pickers'
-      - '@types/prop-types'
-      - '@types/react'
-      - '@types/react-dom'
-      - bufferutil
-      - debug
-      - pdfjs-dist
-      - prop-types
-      - react-is
-      - react-native
-      - redux
-      - rolldown
-      - rollup
-      - supports-color
-      - typescript
-      - utf-8-validate
-      - vite
-
   '@ts-morph/common@0.27.0':
     dependencies:
       fast-glob: 3.3.3
@@ -18624,7 +18490,7 @@ snapshots:
       '@typescript-eslint/types': 8.60.1
       '@typescript-eslint/typescript-estree': 8.60.1(typescript@5.9.3)
       '@typescript-eslint/visitor-keys': 8.60.1
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       eslint: 8.57.1
       typescript: 5.9.3
     transitivePeerDependencies:
@@ -18634,7 +18500,7 @@ snapshots:
     dependencies:
       '@typescript-eslint/tsconfig-utils': 8.60.1(typescript@5.9.3)
       '@typescript-eslint/types': 8.60.1
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       typescript: 5.9.3
     transitivePeerDependencies:
       - supports-color
@@ -18653,7 +18519,7 @@ snapshots:
       '@typescript-eslint/types': 8.60.1
       '@typescript-eslint/typescript-estree': 8.60.1(typescript@5.9.3)
       '@typescript-eslint/utils': 8.60.1(eslint@8.57.1)(typescript@5.9.3)
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       eslint: 8.57.1
       ts-api-utils: 2.5.0(typescript@5.9.3)
       typescript: 5.9.3
@@ -18668,7 +18534,7 @@ snapshots:
       '@typescript-eslint/tsconfig-utils': 8.60.1(typescript@5.9.3)
       '@typescript-eslint/types': 8.60.1
       '@typescript-eslint/visitor-keys': 8.60.1
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       minimatch: 10.2.5
       semver: 7.8.2
       tinyglobby: 0.2.17
@@ -18957,7 +18823,7 @@ snapshots:
 
   agent-base@6.0.2:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
@@ -19471,16 +19337,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  babel-plugin-styled-components@2.3.0(styled-components@5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6))(supports-color@5.5.0):
-    dependencies:
-      '@babel/helper-annotate-as-pure': 7.29.7
-      '@babel/helper-module-imports': 7.29.7(supports-color@5.5.0)
-      '@babel/plugin-syntax-jsx': 7.29.7(@babel/core@7.29.7)
-      picomatch: 4.0.4
-      styled-components: 5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)
-    transitivePeerDependencies:
-      - supports-color
-
   babel-polyfill@6.26.0:
     dependencies:
       babel-runtime: 6.26.0
@@ -19636,7 +19492,7 @@ snapshots:
     dependencies:
       bytes: 3.1.2
       content-type: 1.0.5
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       http-errors: 2.0.1
       iconv-lite: 0.7.2
       on-finished: 2.4.1
@@ -20685,7 +20541,7 @@ snapshots:
   engine.io-client@6.6.5:
     dependencies:
       '@socket.io/component-emitter': 3.1.2
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       engine.io-parser: 5.2.3
       ws: 8.20.1
       xmlhttprequest-ssl: 2.1.2
@@ -20705,7 +20561,7 @@ snapshots:
       base64id: 2.0.0
       cookie: 0.7.2
       cors: 2.8.6
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       engine.io-parser: 5.2.3
       ws: 8.21.0
     transitivePeerDependencies:
@@ -20936,7 +20792,7 @@ snapshots:
   eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       eslint: 8.57.1
       get-tsconfig: 4.14.0
       is-bun-module: 2.0.0
@@ -21064,7 +20920,7 @@ snapshots:
       ajv: 6.15.0
       chalk: 4.1.2
       cross-spawn: 7.0.6
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       doctrine: 3.0.0
       escape-string-regexp: 4.0.0
       eslint-scope: 7.2.2
@@ -21301,7 +21157,7 @@ snapshots:
       content-type: 1.0.5
       cookie: 0.7.2
       cookie-signature: 1.2.2
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       depd: 2.0.0
       encodeurl: 2.0.0
       escape-html: 1.0.3
@@ -21354,7 +21210,7 @@ snapshots:
 
   extract-zip@2.0.1:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       get-stream: 5.2.0
       yauzl: 2.10.0
     optionalDependencies:
@@ -21509,7 +21365,7 @@ snapshots:
 
   finalhandler@2.1.1:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       encodeurl: 2.0.0
       escape-html: 1.0.3
       on-finished: 2.4.1
@@ -21757,7 +21613,7 @@ snapshots:
     dependencies:
       basic-ftp: 5.3.1
       data-uri-to-buffer: 6.0.2
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
@@ -22046,6 +21902,8 @@ snapshots:
       is-self-closing: 1.0.1
       kind-of: 6.0.3
 
+  html-to-image@1.11.13: {}
+
   html-url-attributes@3.0.1: {}
 
   html2canvas@1.4.1:
@@ -22064,7 +21922,7 @@ snapshots:
   http-proxy-agent@7.0.2:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
@@ -22077,14 +21935,14 @@ snapshots:
   https-proxy-agent@5.0.1:
     dependencies:
       agent-base: 6.0.2
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
   https-proxy-agent@7.0.6:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
@@ -22524,7 +22382,7 @@ snapshots:
 
   istanbul-lib-source-maps@4.0.1:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       istanbul-lib-coverage: 3.2.2
       source-map: 0.6.1
     transitivePeerDependencies:
@@ -23184,7 +23042,7 @@ snapshots:
     dependencies:
       chalk: 5.6.2
       commander: 13.1.0
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       execa: 8.0.1
       lilconfig: 3.1.3
       listr2: 8.3.3
@@ -23871,7 +23729,7 @@ snapshots:
   micromark@4.0.2:
     dependencies:
       '@types/debug': 4.1.13
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       decode-named-character-reference: 1.3.0
       devlop: 1.1.0
       micromark-core-commonmark: 2.0.3
@@ -24397,7 +24255,7 @@ snapshots:
     dependencies:
       '@tootallnate/quickjs-emscripten': 0.23.0
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       get-uri: 6.0.5
       http-proxy-agent: 7.0.2
       https-proxy-agent: 7.0.6
@@ -24747,7 +24605,7 @@ snapshots:
   proxy-agent@6.5.0:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       http-proxy-agent: 7.0.2
       https-proxy-agent: 7.0.6
       lru-cache: 7.18.3
@@ -24776,7 +24634,7 @@ snapshots:
     dependencies:
       '@puppeteer/browsers': 2.13.2
       chromium-bidi: 14.0.0(devtools-protocol@0.0.1608973)
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       devtools-protocol: 0.0.1608973
       typed-query-selector: 2.12.2
       webdriver-bidi-protocol: 0.4.1
@@ -25029,15 +24887,6 @@ snapshots:
       - '@babel/core'
       - react-is
 
-  react-css-nocode-editor@1.0.13(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6):
-    dependencies:
-      react: 19.2.6
-      react-dom: 19.2.6(react@19.2.6)
-      styled-components: 5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)
-    transitivePeerDependencies:
-      - '@babel/core'
-      - react-is
-
   react-day-picker@8.10.2(date-fns@3.6.0)(react@19.2.6):
     dependencies:
       date-fns: 3.6.0
@@ -25648,7 +25497,7 @@ snapshots:
 
   router@2.2.0:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       depd: 2.0.0
       is-promise: 4.0.0
       parseurl: 1.3.3
@@ -25770,7 +25619,7 @@ snapshots:
 
   send@1.2.1:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       encodeurl: 2.0.0
       escape-html: 1.0.3
       etag: 1.8.1
@@ -25986,7 +25835,7 @@ snapshots:
 
   socket.io-adapter@2.5.8:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       ws: 8.21.0
     transitivePeerDependencies:
       - bufferutil
@@ -25996,7 +25845,7 @@ snapshots:
   socket.io-client@4.8.3:
     dependencies:
       '@socket.io/component-emitter': 3.1.2
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       engine.io-client: 6.6.5
       socket.io-parser: 4.2.6
     transitivePeerDependencies:
@@ -26007,7 +25856,7 @@ snapshots:
   socket.io-parser@4.2.6:
     dependencies:
       '@socket.io/component-emitter': 3.1.2
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
@@ -26016,7 +25865,7 @@ snapshots:
       accepts: 1.3.8
       base64id: 2.0.0
       cors: 2.8.6
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       engine.io: 6.6.9
       socket.io-adapter: 2.5.8
       socket.io-parser: 4.2.6
@@ -26028,7 +25877,7 @@ snapshots:
   socks-proxy-agent@8.0.5:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       socks: 2.8.9
     transitivePeerDependencies:
       - supports-color
@@ -26323,24 +26172,6 @@ snapshots:
     transitivePeerDependencies:
       - '@babel/core'
 
-  styled-components@5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6):
-    dependencies:
-      '@babel/helper-module-imports': 7.29.7(supports-color@5.5.0)
-      '@babel/traverse': 7.29.7(supports-color@5.5.0)
-      '@emotion/is-prop-valid': 1.4.0
-      '@emotion/stylis': 0.8.5
-      '@emotion/unitless': 0.7.5
-      babel-plugin-styled-components: 2.3.0(styled-components@5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6))(supports-color@5.5.0)
-      css-to-react-native: 3.2.0
-      hoist-non-react-statics: 3.3.2
-      react: 19.2.6
-      react-dom: 19.2.6(react@19.2.6)
-      react-is: 19.2.7
-      shallowequal: 1.1.0
-      supports-color: 5.5.0
-    transitivePeerDependencies:
-      - '@babel/core'
-
   styled-jsx@5.1.1(babel-plugin-macros@3.1.0)(react@18.3.1):
     dependencies:
       client-only: 0.0.1
@@ -26366,7 +26197,7 @@ snapshots:
     dependencies:
       component-emitter: 1.3.1
       cookiejar: 2.1.4
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       fast-safe-stringify: 2.1.1
       form-data: 4.0.5
       formidable: 3.5.4
@@ -26879,7 +26710,7 @@ snapshots:
       app-root-path: 3.1.0
       buffer: 6.0.3
       dayjs: 1.11.21
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       dedent: 1.7.2(babel-plugin-macros@3.1.0)
       dotenv: 16.6.1
       glob: 10.5.0
@@ -26903,7 +26734,7 @@ snapshots:
       app-root-path: 3.1.0
       buffer: 6.0.3
       dayjs: 1.11.21
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       dedent: 1.7.2(babel-plugin-macros@3.1.0)
       dotenv: 16.6.1
       glob: 10.5.0
@@ -27264,7 +27095,7 @@ snapshots:
   vite-node@2.1.9(@types/node@22.20.1)(lightningcss@1.32.0)(terser@5.48.0):
     dependencies:
       cac: 6.7.14
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       es-module-lexer: 1.7.0
       pathe: 1.1.2
       vite: 5.4.21(@types/node@22.20.1)(lightningcss@1.32.0)(terser@5.48.0)
@@ -27282,7 +27113,7 @@ snapshots:
   vite-node@2.1.9(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0):
     dependencies:
       cac: 6.7.14
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       es-module-lexer: 1.7.0
       pathe: 1.1.2
       vite: 5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0)
@@ -27329,7 +27160,7 @@ snapshots:
       '@vitest/spy': 2.1.9
       '@vitest/utils': 2.1.9
       chai: 5.3.3
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       expect-type: 1.3.0
       magic-string: 0.30.21
       pathe: 1.1.2
@@ -27365,7 +27196,7 @@ snapshots:
       '@vitest/spy': 2.1.9
       '@vitest/utils': 2.1.9
       chai: 5.3.3
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       expect-type: 1.3.0
       magic-string: 0.30.21
       pathe: 1.1.2

From 2a3a2316657e14a58b88aed7cf6e0dbb10ff4647 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 12 Aug 2026 08:25:39 +0000
Subject: [PATCH 037/174] fix: auto select ethiopian when chosing the coop
 option

---
 .../src/components/onboarding/OnboardingWizardDialog.tsx    | 3 ++-
 .../portal/src/pages/settings/NationalitySelect.tsx         | 6 +++++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
index 998f733da..d5a87a4ee 100644
--- a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
+++ b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
@@ -169,7 +169,8 @@ export default function OnboardingWizardDialog({
     setCooperative(checked);
     if (checked) {
       setRoles((prev) => prev.filter((r) => r !== "freight_forwarder"));
-      setNationality((prev) => (prev === "foreign" ? "ethiopian" : prev));
+      // Ethiopian is then the only answer left, so it is made rather than asked.
+      setNationality("ethiopian");
     }
   }, []);
   const [documentFiles, setDocumentFiles] = useState<
diff --git a/apps/edr-freight-web/portal/src/pages/settings/NationalitySelect.tsx b/apps/edr-freight-web/portal/src/pages/settings/NationalitySelect.tsx
index 99569e748..3eb7fd87e 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/NationalitySelect.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/NationalitySelect.tsx
@@ -29,7 +29,11 @@ export default function NationalitySelect({
     <SimpleGrid cols={{ base: 1, sm: excludeForeign ? 1 : 2 }} spacing="md">
       <RoleCard
         label="Ethiopian Company"
-        description="Registered in Ethiopia. You'll provide a TIN certificate, commercial registration and national ID."
+        description={
+          excludeForeign
+            ? "Registered in Ethiopia. You'll provide a TIN certificate, your co-operative registration certificate and national ID."
+            : "Registered in Ethiopia. You'll provide a TIN certificate, commercial registration and national ID."
+        }
         icon={<MapPin size={22} />}
         selected={value === "ethiopian"}
         onClick={() => onChange("ethiopian")}

From abeb296157e8f6dfe858bd187ae0a2ba48311c94 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 12 Aug 2026 08:39:54 +0000
Subject: [PATCH 038/174] fix: file upload seeder

---
 .../src/seed/file-upload-settings.seeder.ts   | 79 ++++++++++++-------
 1 file changed, 51 insertions(+), 28 deletions(-)

diff --git a/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts b/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
index 4f314453a..dd8f9bd20 100644
--- a/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
+++ b/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
@@ -1,6 +1,7 @@
 import { Injectable, Logger } from "@nestjs/common";
 import { DataSource } from "typeorm";
 
+import { FileUploadField } from "../modules/file-upload-settings/entities/file-upload-field.entity";
 import { FileUploadSetting } from "../modules/file-upload-settings/entities/file-upload-setting.entity";
 import { poaDelegationField } from "../modules/file-upload-settings/poa-delegation.constants";
 
@@ -165,10 +166,13 @@ const FOREIGN_ONBOARDING_FIELDS: OnboardingField[] = [
  * actually produce is a backoffice decision, edited in the file-settings editor.
  */
 const COOPERATIVE_ONBOARDING_FIELDS: OnboardingField[] = [
+  // First on purpose: only the first field of a new set is seeded, and this is
+  // the paper that distinguishes a co-operative from every other company.
   {
-    fileKey: "tin_certificate",
-    fileLabel: "TIN Certificate",
-    helpText: "Verified against the TIN registry during registration.",
+    fileKey: "cooperative_registration_certificate",
+    fileLabel: "Co-operative Union / Farm Registration Certificate",
+    helpText:
+      "Certificate issued by the co-operative promotion agency that registered the union or farm.",
     isRequired: true,
     isMultiple: false,
     maxFiles: 1,
@@ -177,10 +181,9 @@ const COOPERATIVE_ONBOARDING_FIELDS: OnboardingField[] = [
     displayOrder: 1,
   },
   {
-    fileKey: "cooperative_registration_certificate",
-    fileLabel: "Co-operative Union / Farm Registration Certificate",
-    helpText:
-      "Certificate issued by the co-operative promotion agency that registered the union or farm.",
+    fileKey: "tin_certificate",
+    fileLabel: "TIN Certificate",
+    helpText: "Verified against the TIN registry during registration.",
     isRequired: true,
     isMultiple: false,
     maxFiles: 1,
@@ -662,16 +665,15 @@ export class FileUploadSettingsSeeder {
   async run() {
     const settingRepository = this.dataSource.getRepository(FileUploadSetting);
 
-    // Seed only into an empty table: any existing rows (including
-    // soft-deleted ones, which would still conflict on the unique `code`)
-    // mean the data is admin-managed, so leave it untouched.
-    const existing = await settingRepository.count({ withDeleted: true });
-    if (existing > 0) {
-      this.logger.log(
-        `file_upload_settings already has ${existing} rows — skipping seed`,
-      );
-      return;
-    }
+    // Seed per CODE, not "only into an empty table". An existing row is
+    // admin-managed and never touched — including a soft-deleted one, which
+    // means the set was removed on purpose (and would still conflict on the
+    // unique `code`). What the table-wide check got wrong is the other half: a
+    // set added to this file after the first boot could never reach a database
+    // that already held the others, so it existed in code and nowhere else.
+    const existingCodes = new Set(
+      (await settingRepository.find({ withDeleted: true })).map((s) => s.code),
+    );
 
     const allSettings: Array<
       OnboardingDocumentSetting & { description: string }
@@ -701,20 +703,41 @@ export class FileUploadSettingsSeeder {
         })),
       ];
 
-    // Insert setting rows only — no FileUploadField rows. Fields start empty
-    // and are configured from the backoffice file-settings editor; the field
-    // definitions above are kept as reference defaults.
-    await settingRepository.insert(
-      allSettings.map((documentSetting) => ({
-        code: documentSetting.code,
-        label: documentSetting.label,
-        description: documentSetting.description,
-        entity: documentSetting.entity,
-      })),
+    const missing = allSettings.filter((s) => !existingCodes.has(s.code));
+    if (missing.length === 0) {
+      this.logger.log("file upload settings up to date — nothing to seed");
+      return;
+    }
+
+    const inserted = await settingRepository.save(
+      missing.map((documentSetting) =>
+        settingRepository.create({
+          code: documentSetting.code,
+          label: documentSetting.label,
+          description: documentSetting.description,
+          entity: documentSetting.entity,
+        }),
+      ),
     );
 
+    // A brand-new set gets exactly ONE field: its first reference default. The
+    // rest of the list above stays documentation — what a set actually asks for
+    // is a backoffice decision, edited in the file-settings editor. Seeding one
+    // means a set is never born empty (an empty set silently requires nothing),
+    // while leaving the admin a single row to extend rather than a list to prune.
+    const fieldRepository = this.dataSource.getRepository(FileUploadField);
+    const firstFields = inserted.flatMap((setting) => {
+      const reference = missing.find((s) => s.code === setting.code)?.fields[0];
+      return reference
+        ? [fieldRepository.create({ ...reference, settingId: setting.id })]
+        : [];
+    });
+    if (firstFields.length > 0) await fieldRepository.save(firstFields);
+
     this.logger.log(
-      `Seeded ${allSettings.length} file upload settings with empty fields`,
+      `Seeded ${missing.length} file upload settings (${firstFields.length} with a default field): ${missing
+        .map((s) => s.code)
+        .join(", ")}`,
     );
   }
 }

From 325cbbc8828345b8585da2a9680e9ceef7b6a71f Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 08:40:02 +0000
Subject: [PATCH 039/174] fix issue

---
 pnpm-lock.yaml | 162 ++++++++++++++++++++++++-------------------------
 1 file changed, 78 insertions(+), 84 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 20f1adbc4..78ec96cd7 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -237,16 +237,16 @@ importers:
         version: 18.0.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@hookform/resolvers':
         specifier: ^5.4.0
-        version: 5.4.0(react-hook-form@7.77.0(react@19.2.6))
+        version: 5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@3.25.76)
       '@mantine/core':
         specifier: ^9.3.0
-        version: 9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@mantine/dates':
         specifier: ^9.3.0
-        version: 9.3.2(@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@9.3.0(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 9.3.2(@mantine/core@9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@9.3.2(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@mantine/hooks':
         specifier: ^9.3.0
-        version: 9.3.0(react@19.2.6)
+        version: 9.3.2(react@19.2.6)
       '@mdxeditor/editor':
         specifier: ^4.2.0
         version: 4.2.0(@codemirror/language@6.12.4)(@lezer/highlight@1.2.3)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.9.3)(yjs@13.6.32)
@@ -354,7 +354,7 @@ importers:
         version: 6.3.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tinymce@8.6.0)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(e4483b467c1e4b1b4b359f6670e164a6)
       '@types/three':
         specifier: ^0.185.3
         version: 0.185.3
@@ -586,13 +586,13 @@ importers:
         version: 5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@4.4.3)
       '@mantine/core':
         specifier: ^9.3.0
-        version: 9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@mantine/dates':
         specifier: ^9.3.0
-        version: 9.3.2(@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@9.3.0(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 9.3.2(@mantine/core@9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@9.3.2(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@mantine/hooks':
         specifier: ^9.3.0
-        version: 9.3.0(react@19.2.6)
+        version: 9.3.2(react@19.2.6)
       '@posthog/react':
         specifier: ^1.10.3
         version: 1.10.3(@types/react@18.3.31)(posthog-js@1.400.1)(react@19.2.6)
@@ -601,7 +601,7 @@ importers:
         version: 5.101.0(react@19.2.6)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(ea394f4c73a62db876565d0b255299aa)
       '@vis.gl/react-google-maps':
         specifier: ^1.8.3
         version: 1.8.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -1436,7 +1436,7 @@ importers:
         version: link:../types
       '@mantine/core':
         specifier: ^9.3.0
-        version: 9.3.0(@mantine/hooks@9.3.0(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 9.3.2(@mantine/hooks@9.3.2(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@tanstack/react-table':
         specifier: ^8.21.3
         version: 8.21.3(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
@@ -2276,11 +2276,6 @@ packages:
     peerDependencies:
       react-hook-form: ^7.0.0
 
-  '@hookform/resolvers@5.4.0':
-    resolution: {integrity: sha512-EIsqr/t/qbinPIhGjMdtvutIN1Kk4uwbROE9/UQ93CAVGR7GkA7Y92+fX80OzXi/OB67jVFYwKGO1WzkxmkFZw==}
-    peerDependencies:
-      react-hook-form: ^7.55.0
-
   '@hookform/resolvers@5.6.0':
     resolution: {integrity: sha512-qtgE4NUK/WQFPq8aDe+GOhr0/UiUSKT0m9ta9SMnDS5ZE63yC850ShAGz1lxtwO+dBjhUKvUxmHwkp4eN7/kBQ==}
     peerDependencies:
@@ -2918,13 +2913,6 @@ packages:
       react: ^18.x || ^19.x
       react-dom: ^18.x || ^19.x
 
-  '@mantine/core@9.3.0':
-    resolution: {integrity: sha512-mHVCm61YVW9ipy9eHiKMqsRUm3TkOErbdw7zHs0HRw5g403nf7tSTqNGvaYE+aX1Py874qMkrUzeQfj4bjiiBA==}
-    peerDependencies:
-      '@mantine/hooks': 9.3.0
-      react: ^19.2.0
-      react-dom: ^19.2.0
-
   '@mantine/core@9.3.2':
     resolution: {integrity: sha512-Upy/Z9Sj2eW2dGrFgUy/2kISVsxMTBYTDfP2TFdsIA3PdPSBkdqfSOPX/ug3d3F3a4bnwQSqcO6+aPEpBIh8dg==}
     peerDependencies:
@@ -2955,11 +2943,6 @@ packages:
     peerDependencies:
       react: ^18.x || ^19.x
 
-  '@mantine/hooks@9.3.0':
-    resolution: {integrity: sha512-QoSr9WI4WsKWrM3qFYYizHUn3+n+CVcFMYe4sdlnmFPStvs6BacPODKJSbFlYl73Z20t82JIy0eKqt4noHQI2g==}
-    peerDependencies:
-      react: ^19.2.0
-
   '@mantine/hooks@9.3.2':
     resolution: {integrity: sha512-jOjpUe0x1A/k3XUiu2/aaSCasXRI5ZKZOucm3ypwsvm9F2u8C1xzwBvagrzlbNZwJRF5vNYIJtCaT7NunPyc0A==}
     peerDependencies:
@@ -5224,9 +5207,6 @@ packages:
   '@types/jquery@3.5.34':
     resolution: {integrity: sha512-3m3939S3erqmTLJANS/uy0B6V7BorKx7RorcGZVjZ62dF5PAGbKEDZK1CuLtKombJkFA2T1jl8LAIIs7IV6gBQ==}
 
-  '@types/jquery@4.0.1':
-    resolution: {integrity: sha512-9a59A/tycXgYuPABcp6/3spSShn0NT2UOM4EfHvMumjYi4lJWTsK5SZWjhx3yRm9IHGCeWXdV2YfNsrWrft/CA==}
-
   '@types/js-cookie@3.0.6':
     resolution: {integrity: sha512-wkw9yd1kEXOPnvEeEV1Go1MmxtBJL0RR79aOTAApecWFVu7w0NNXNqhcWgvw2YgZDYadliXkl14pa3WXw5jlCQ==}
 
@@ -9068,10 +9048,6 @@ packages:
     resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==}
     hasBin: true
 
-  js-yaml@4.2.0:
-    resolution: {integrity: sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==}
-    hasBin: true
-
   js-yaml@4.3.0:
     resolution: {integrity: sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==}
     hasBin: true
@@ -13960,7 +13936,7 @@ snapshots:
       globals: 13.24.0
       ignore: 5.3.2
       import-fresh: 3.3.1
-      js-yaml: 4.2.0
+      js-yaml: 4.3.0
       minimatch: 3.1.5
       strip-json-comments: 3.1.1
     transitivePeerDependencies:
@@ -14093,10 +14069,19 @@ snapshots:
     dependencies:
       react-hook-form: 7.77.0(react@18.3.1)
 
-  '@hookform/resolvers@5.4.0(react-hook-form@7.77.0(react@19.2.6))':
+  '@hookform/resolvers@5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@3.25.76)':
     dependencies:
       '@standard-schema/utils': 0.3.0
       react-hook-form: 7.77.0(react@19.2.6)
+    optionalDependencies:
+      '@sinclair/typebox': 0.27.10
+      '@standard-schema/spec': 1.1.0
+      ajv: 8.20.0
+      ajv-formats: 2.1.1(ajv@8.20.0)
+      class-transformer: 0.5.1
+      class-validator: 0.14.4
+      effect: 3.21.0
+      zod: 3.25.76
 
   '@hookform/resolvers@5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@4.4.3)':
     dependencies:
@@ -14879,10 +14864,10 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
-  '@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@mantine/core@9.3.2(@mantine/hooks@9.3.2(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@floating-ui/react': 0.27.19(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@mantine/hooks': 9.3.0(react@18.3.1)
+      '@mantine/hooks': 9.3.2(react@18.3.1)
       clsx: 2.1.1
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
@@ -14892,19 +14877,6 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
-  '@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
-    dependencies:
-      '@floating-ui/react': 0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@mantine/hooks': 9.3.0(react@19.2.6)
-      clsx: 2.1.1
-      react: 19.2.6
-      react-dom: 19.2.6(react@19.2.6)
-      react-number-format: 5.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@19.2.6)
-      type-fest: 5.7.0
-    transitivePeerDependencies:
-      - '@types/react'
-
   '@mantine/core@9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/react': 0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -14927,15 +14899,6 @@ snapshots:
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
 
-  '@mantine/dates@9.3.2(@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@9.3.0(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
-    dependencies:
-      '@mantine/core': 9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@mantine/hooks': 9.3.0(react@19.2.6)
-      clsx: 2.1.1
-      dayjs: 1.11.21
-      react: 19.2.6
-      react-dom: 19.2.6(react@19.2.6)
-
   '@mantine/dates@9.3.2(@mantine/core@9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@9.3.2(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@mantine/core': 9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -14949,14 +14912,10 @@ snapshots:
     dependencies:
       react: 19.2.6
 
-  '@mantine/hooks@9.3.0(react@18.3.1)':
+  '@mantine/hooks@9.3.2(react@18.3.1)':
     dependencies:
       react: 18.3.1
 
-  '@mantine/hooks@9.3.0(react@19.2.6)':
-    dependencies:
-      react: 19.2.6
-
   '@mantine/hooks@9.3.2(react@19.2.6)':
     dependencies:
       react: 19.2.6
@@ -17951,11 +17910,11 @@ snapshots:
       - '@faker-js/faker'
       - supports-color
 
-  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)':
+  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(e4483b467c1e4b1b4b359f6670e164a6)':
     dependencies:
       '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
       '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
-      '@hookform/resolvers': 5.4.0(react-hook-form@7.77.0(react@19.2.6))
+      '@hookform/resolvers': 5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@3.25.76)
       '@lottiefiles/react-lottie-player': 3.6.0(react@19.2.6)
       '@mantine/charts': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(recharts@3.8.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)(redux@5.0.1))
       '@mantine/core': 7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -18058,11 +18017,29 @@ snapshots:
       - '@mui/icons-material'
       - '@mui/material'
       - '@mui/x-date-pickers'
+      - '@sinclair/typebox'
+      - '@standard-schema/spec'
       - '@types/prop-types'
       - '@types/react'
       - '@types/react-dom'
+      - '@typeschema/main'
+      - '@vinejs/vine'
+      - ajv
+      - ajv-errors
+      - ajv-formats
+      - arktype
+      - ata-validator
       - bufferutil
+      - class-transformer
+      - class-validator
+      - computed-types
       - debug
+      - effect
+      - fluentvalidation-ts
+      - fp-ts
+      - io-ts
+      - joi
+      - nope-validator
       - pdfjs-dist
       - prop-types
       - react-is
@@ -18070,16 +18047,21 @@ snapshots:
       - redux
       - rolldown
       - rollup
+      - superstruct
       - supports-color
+      - typanion
       - typescript
       - utf-8-validate
+      - valibot
+      - vest
       - vite
+      - yup
 
-  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)':
+  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(ea394f4c73a62db876565d0b255299aa)':
     dependencies:
       '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
       '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
-      '@hookform/resolvers': 5.4.0(react-hook-form@7.77.0(react@19.2.6))
+      '@hookform/resolvers': 5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@3.25.76)
       '@lottiefiles/react-lottie-player': 3.6.0(react@19.2.6)
       '@mantine/charts': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(recharts@3.8.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)(redux@5.0.1))
       '@mantine/core': 7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -18182,11 +18164,29 @@ snapshots:
       - '@mui/icons-material'
       - '@mui/material'
       - '@mui/x-date-pickers'
+      - '@sinclair/typebox'
+      - '@standard-schema/spec'
       - '@types/prop-types'
       - '@types/react'
       - '@types/react-dom'
+      - '@typeschema/main'
+      - '@vinejs/vine'
+      - ajv
+      - ajv-errors
+      - ajv-formats
+      - arktype
+      - ata-validator
       - bufferutil
+      - class-transformer
+      - class-validator
+      - computed-types
       - debug
+      - effect
+      - fluentvalidation-ts
+      - fp-ts
+      - io-ts
+      - joi
+      - nope-validator
       - pdfjs-dist
       - prop-types
       - react-is
@@ -18194,10 +18194,15 @@ snapshots:
       - redux
       - rolldown
       - rollup
+      - superstruct
       - supports-color
+      - typanion
       - typescript
       - utf-8-validate
+      - valibot
+      - vest
       - vite
+      - yup
 
   '@ts-morph/common@0.27.0':
     dependencies:
@@ -18397,8 +18402,6 @@ snapshots:
     dependencies:
       '@types/sizzle': 2.3.10
 
-  '@types/jquery@4.0.1': {}
-
   '@types/js-cookie@3.0.6': {}
 
   '@types/json-schema@7.0.15': {}
@@ -18537,7 +18540,7 @@ snapshots:
 
   '@types/tinymce@4.6.9':
     dependencies:
-      '@types/jquery': 4.0.1
+      '@types/jquery': 3.5.34
 
   '@types/tmp@0.2.6': {}
 
@@ -18982,11 +18985,6 @@ snapshots:
       amqplib: 0.10.9
       promise-breaker: 6.0.0
 
-  amqp-connection-manager@5.0.0(amqplib@0.10.9):
-    dependencies:
-      amqplib: 0.10.9
-      promise-breaker: 6.0.0
-
   amqp-connection-manager@5.0.0(amqplib@2.0.1):
     dependencies:
       amqplib: 2.0.1
@@ -20148,7 +20146,7 @@ snapshots:
   cosmiconfig@8.3.6(typescript@5.9.3):
     dependencies:
       import-fresh: 3.3.1
-      js-yaml: 4.2.0
+      js-yaml: 4.3.0
       parse-json: 5.2.0
       path-type: 4.0.0
     optionalDependencies:
@@ -20158,7 +20156,7 @@ snapshots:
     dependencies:
       env-paths: 2.2.1
       import-fresh: 3.3.1
-      js-yaml: 4.2.0
+      js-yaml: 4.3.0
       parse-json: 5.2.0
     optionalDependencies:
       typescript: 5.9.3
@@ -21054,7 +21052,7 @@ snapshots:
       imurmurhash: 0.1.4
       is-glob: 4.0.3
       is-path-inside: 3.0.3
-      js-yaml: 4.2.0
+      js-yaml: 4.3.0
       json-stable-stringify-without-jsonify: 1.0.1
       levn: 0.4.1
       lodash.merge: 4.6.2
@@ -22887,10 +22885,6 @@ snapshots:
     dependencies:
       argparse: 2.0.1
 
-  js-yaml@4.2.0:
-    dependencies:
-      argparse: 2.0.1
-
   js-yaml@4.3.0:
     dependencies:
       argparse: 2.0.1

From 879f0b890da66ae1a828b0a7cabf4dd0f4309c00 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 12 Aug 2026 08:42:16 +0000
Subject: [PATCH 040/174] fix: file size limit

---
 .../portal/src/components/onboarding/RoleLicenseStep.tsx        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/edr-freight-web/portal/src/components/onboarding/RoleLicenseStep.tsx b/apps/edr-freight-web/portal/src/components/onboarding/RoleLicenseStep.tsx
index a485d40c1..8270bce74 100644
--- a/apps/edr-freight-web/portal/src/components/onboarding/RoleLicenseStep.tsx
+++ b/apps/edr-freight-web/portal/src/components/onboarding/RoleLicenseStep.tsx
@@ -50,7 +50,7 @@ function buildLicenseSetting(
         isMultiple: true,
         maxFiles: 10,
         allowedExtensions: ["pdf", "png", "jpg", "jpeg"],
-        maxSizeMb: 10,
+        maxSizeMb: 25,
         order: 1,
       },
     ],

From 08bd110e5b849072d494c7aa1f4978f389ad32a9 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 08:56:47 +0000
Subject: [PATCH 041/174] changes

---
 pnpm-lock.yaml | 307 ++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 255 insertions(+), 52 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f90cc87f2..a56272063 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -354,7 +354,7 @@ importers:
         version: 6.3.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tinymce@8.6.0)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(e4483b467c1e4b1b4b359f6670e164a6)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)
       '@types/three':
         specifier: ^0.185.3
         version: 0.185.3
@@ -601,7 +601,7 @@ importers:
         version: 5.101.0(react@19.2.6)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)
       '@vis.gl/react-google-maps':
         specifier: ^1.8.3
         version: 1.8.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -13032,11 +13032,11 @@ snapshots:
       '@babel/helpers': 7.29.7
       '@babel/parser': 7.29.7
       '@babel/template': 7.29.7
-      '@babel/traverse': 7.29.7(supports-color@5.5.0)
+      '@babel/traverse': 7.29.7
       '@babel/types': 7.29.7
       '@jridgewell/remapping': 2.3.5
       convert-source-map: 2.0.0
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       gensync: 1.0.0-beta.2
       json5: 2.2.3
       semver: 6.3.1
@@ -13071,7 +13071,7 @@ snapshots:
       '@babel/helper-optimise-call-expression': 7.29.7
       '@babel/helper-replace-supers': 7.29.7(@babel/core@7.29.7)
       '@babel/helper-skip-transparent-expression-wrappers': 7.29.7
-      '@babel/traverse': 7.29.7(supports-color@5.5.0)
+      '@babel/traverse': 7.29.7
       semver: 6.3.1
     transitivePeerDependencies:
       - supports-color
@@ -13080,7 +13080,14 @@ snapshots:
 
   '@babel/helper-member-expression-to-functions@7.29.7':
     dependencies:
-      '@babel/traverse': 7.29.7(supports-color@5.5.0)
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-imports@7.29.7':
+    dependencies:
+      '@babel/traverse': 7.29.7
       '@babel/types': 7.29.7
     transitivePeerDependencies:
       - supports-color
@@ -13095,9 +13102,9 @@ snapshots:
   '@babel/helper-module-transforms@7.29.7(@babel/core@7.29.7)':
     dependencies:
       '@babel/core': 7.29.7
-      '@babel/helper-module-imports': 7.29.7(supports-color@5.5.0)
+      '@babel/helper-module-imports': 7.29.7
       '@babel/helper-validator-identifier': 7.29.7
-      '@babel/traverse': 7.29.7(supports-color@5.5.0)
+      '@babel/traverse': 7.29.7
     transitivePeerDependencies:
       - supports-color
 
@@ -13112,13 +13119,13 @@ snapshots:
       '@babel/core': 7.29.7
       '@babel/helper-member-expression-to-functions': 7.29.7
       '@babel/helper-optimise-call-expression': 7.29.7
-      '@babel/traverse': 7.29.7(supports-color@5.5.0)
+      '@babel/traverse': 7.29.7
     transitivePeerDependencies:
       - supports-color
 
   '@babel/helper-skip-transparent-expression-wrappers@7.29.7':
     dependencies:
-      '@babel/traverse': 7.29.7(supports-color@5.5.0)
+      '@babel/traverse': 7.29.7
       '@babel/types': 7.29.7
     transitivePeerDependencies:
       - supports-color
@@ -13271,6 +13278,18 @@ snapshots:
       '@babel/parser': 7.29.7
       '@babel/types': 7.29.7
 
+  '@babel/traverse@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/generator': 7.29.7
+      '@babel/helper-globals': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+      debug: 4.4.3(supports-color@8.1.1)
+    transitivePeerDependencies:
+      - supports-color
+
   '@babel/traverse@7.29.7(supports-color@5.5.0)':
     dependencies:
       '@babel/code-frame': 7.29.7
@@ -13755,7 +13774,7 @@ snapshots:
 
   '@emotion/babel-plugin@11.13.5':
     dependencies:
-      '@babel/helper-module-imports': 7.29.7(supports-color@5.5.0)
+      '@babel/helper-module-imports': 7.29.7
       '@babel/runtime': 7.29.7
       '@emotion/hash': 0.9.2
       '@emotion/memoize': 0.9.0
@@ -13921,7 +13940,7 @@ snapshots:
   '@eslint/eslintrc@2.1.4':
     dependencies:
       ajv: 6.15.0
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       espree: 9.6.1
       globals: 13.24.0
       ignore: 5.3.2
@@ -14090,7 +14109,7 @@ snapshots:
   '@humanwhocodes/config-array@0.13.0':
     dependencies:
       '@humanwhocodes/object-schema': 2.0.3
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       minimatch: 3.1.5
     transitivePeerDependencies:
       - supports-color
@@ -15663,7 +15682,7 @@ snapshots:
 
   '@puppeteer/browsers@2.13.2':
     dependencies:
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       extract-zip: 2.0.1
       progress: 2.0.3
       proxy-agent: 6.5.0
@@ -17737,7 +17756,7 @@ snapshots:
 
   '@tokenizer/inflate@0.4.1':
     dependencies:
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       token-types: 6.1.2
     transitivePeerDependencies:
       - supports-color
@@ -18047,6 +18066,153 @@ snapshots:
       - vite
       - yup
 
+  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(ea394f4c73a62db876565d0b255299aa)':
+    dependencies:
+      '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
+      '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
+      '@hookform/resolvers': 5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@3.25.76)
+      '@lottiefiles/react-lottie-player': 3.6.0(react@19.2.6)
+      '@mantine/charts': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(recharts@3.8.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)(redux@5.0.1))
+      '@mantine/core': 7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@mantine/dates': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@mantine/hooks': 7.17.8(react@19.2.6)
+      '@mantine/notifications': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-accordion': 1.2.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-alert-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-avatar': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-checkbox': 1.3.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-collapsible': 1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-context-menu': 2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-dropdown-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-hover-card': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-label': 2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-navigation-menu': 1.2.15(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-popover': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-progress': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-radio-group': 1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-scroll-area': 1.2.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-select': 2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-separator': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@19.2.6)
+      '@radix-ui/react-switch': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-tabs': 1.1.14(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-toast': 1.2.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@radix-ui/react-tooltip': 1.2.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-pdf-viewer/core': 3.12.0(pdfjs-dist@5.4.296)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-pdf-viewer/default-layout': 3.12.0(pdfjs-dist@5.4.296)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@react-pdf/renderer': 4.5.1(react@19.2.6)
+      '@reduxjs/toolkit': 2.12.0(react-redux@9.3.0(@types/react@18.3.31)(react@19.2.6)(redux@5.0.1))(react@19.2.6)
+      '@tabler/icons-react': 3.44.0(react@19.2.6)
+      '@tailwindcss/vite': 4.3.0(vite@5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0))
+      '@tanstack/react-query': 5.101.0(react@19.2.6)
+      '@tanstack/react-query-devtools': 5.101.0(@tanstack/react-query@5.101.0(react@19.2.6))(react@19.2.6)
+      '@tanstack/react-table': 8.21.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@tinymce/tinymce-react': 6.3.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tinymce@7.9.3)
+      '@types/dompurify': 3.2.0
+      '@types/node': 24.13.1
+      '@types/tinymce': 4.6.9
+      axios: 1.17.0
+      class-variance-authority: 0.7.1
+      clsx: 2.1.1
+      cmdk: 1.1.1(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      date-fns: 3.6.0
+      dayjs: 1.11.21
+      dompurify: 3.4.8
+      ethiopian-calendar-date-converter: 2.1.6
+      ethiopian-calendar-new: 1.1.0
+      file-type: 18.7.0
+      framer-motion: 12.40.0(@emotion/is-prop-valid@1.4.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      html2canvas: 1.4.1
+      i18next: 25.10.10(typescript@5.9.3)
+      i18next-browser-languagedetector: 8.2.1
+      jquery: 3.7.1
+      js-cookie: 3.0.8
+      jspdf: 3.0.4
+      lodash: 4.18.1
+      lucide-react: 0.513.0(react@19.2.6)
+      mantine-react-table: 2.0.0-beta.9(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/dates@7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(@tabler/icons-react@3.44.0(react@19.2.6))(clsx@2.1.1)(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      mui-ethiopian-datepicker: 0.3.2(4b3af212eafdf0059f009b005d7e343d)
+      next-themes: 0.4.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      path: 0.12.7
+      pdf-lib: 1.17.1
+      qs: 6.15.2
+      react: 19.2.6
+      react-cookie: 8.1.2(@types/react@18.3.31)(react@19.2.6)
+      react-css-nocode-editor: 1.0.13(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)
+      react-day-picker: 8.10.2(date-fns@3.6.0)(react@19.2.6)
+      react-dom: 19.2.6(react@19.2.6)
+      react-dropzone: 14.4.1(react@19.2.6)
+      react-hook-form: 7.77.0(react@19.2.6)
+      react-i18next: 15.7.4(i18next@25.10.10(typescript@5.9.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.9.3)
+      react-icons: 5.6.0(react@19.2.6)
+      react-image-crop: 11.0.10(react@19.2.6)
+      react-intersection-observer: 9.16.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-pdf: 10.4.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-pdf-html: 2.1.5(@react-pdf/renderer@4.5.1(react@19.2.6))(react@19.2.6)
+      react-redux: 9.3.0(@types/react@18.3.31)(react@19.2.6)(redux@5.0.1)
+      react-resizable-panels: 3.0.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-router-dom: 7.17.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-signature-canvas: 1.1.0-alpha.2(@types/prop-types@15.7.15)(@types/react@18.3.31)(prop-types@15.8.1)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      recharts: 3.8.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)(redux@5.0.1)
+      rollup-plugin-visualizer: 7.0.1(rollup@4.61.1)
+      socket.io-client: 4.8.3
+      sonner: 2.0.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      tailwind-merge: 3.6.0
+      tailwind-scrollbar-hide: 4.0.0(tailwindcss@4.3.0)
+      tailwindcss: 4.3.0
+      tailwindcss-animate: 1.0.7(tailwindcss@4.3.0)
+      tinymce: 7.9.3
+      url: 0.11.4
+      vaul: 1.1.2(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      xlsx: 0.18.5
+      zod: 3.25.76
+    transitivePeerDependencies:
+      - '@babel/core'
+      - '@emotion/is-prop-valid'
+      - '@mui/icons-material'
+      - '@mui/material'
+      - '@mui/x-date-pickers'
+      - '@sinclair/typebox'
+      - '@standard-schema/spec'
+      - '@types/prop-types'
+      - '@types/react'
+      - '@types/react-dom'
+      - '@typeschema/main'
+      - '@vinejs/vine'
+      - ajv
+      - ajv-errors
+      - ajv-formats
+      - arktype
+      - ata-validator
+      - bufferutil
+      - class-transformer
+      - class-validator
+      - computed-types
+      - debug
+      - effect
+      - fluentvalidation-ts
+      - fp-ts
+      - io-ts
+      - joi
+      - nope-validator
+      - pdfjs-dist
+      - prop-types
+      - react-is
+      - react-native
+      - redux
+      - rolldown
+      - rollup
+      - superstruct
+      - supports-color
+      - typanion
+      - typescript
+      - utf-8-validate
+      - valibot
+      - vest
+      - vite
+      - yup
+
   '@ts-morph/common@0.27.0':
     dependencies:
       fast-glob: 3.3.3
@@ -18442,7 +18608,7 @@ snapshots:
       '@typescript-eslint/types': 8.60.1
       '@typescript-eslint/typescript-estree': 8.60.1(typescript@5.9.3)
       '@typescript-eslint/visitor-keys': 8.60.1
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       eslint: 8.57.1
       typescript: 5.9.3
     transitivePeerDependencies:
@@ -18452,7 +18618,7 @@ snapshots:
     dependencies:
       '@typescript-eslint/tsconfig-utils': 8.60.1(typescript@5.9.3)
       '@typescript-eslint/types': 8.60.1
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       typescript: 5.9.3
     transitivePeerDependencies:
       - supports-color
@@ -18471,7 +18637,7 @@ snapshots:
       '@typescript-eslint/types': 8.60.1
       '@typescript-eslint/typescript-estree': 8.60.1(typescript@5.9.3)
       '@typescript-eslint/utils': 8.60.1(eslint@8.57.1)(typescript@5.9.3)
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       eslint: 8.57.1
       ts-api-utils: 2.5.0(typescript@5.9.3)
       typescript: 5.9.3
@@ -18486,7 +18652,7 @@ snapshots:
       '@typescript-eslint/tsconfig-utils': 8.60.1(typescript@5.9.3)
       '@typescript-eslint/types': 8.60.1
       '@typescript-eslint/visitor-keys': 8.60.1
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       minimatch: 10.2.5
       semver: 7.8.2
       tinyglobby: 0.2.17
@@ -18775,7 +18941,7 @@ snapshots:
 
   agent-base@6.0.2:
     dependencies:
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
     transitivePeerDependencies:
       - supports-color
 
@@ -19284,6 +19450,16 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  babel-plugin-styled-components@2.3.0(styled-components@5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6))(supports-color@5.5.0):
+    dependencies:
+      '@babel/helper-annotate-as-pure': 7.29.7
+      '@babel/helper-module-imports': 7.29.7(supports-color@5.5.0)
+      '@babel/plugin-syntax-jsx': 7.29.7(@babel/core@7.29.7)
+      picomatch: 4.0.4
+      styled-components: 5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)
+    transitivePeerDependencies:
+      - supports-color
+
   babel-polyfill@6.26.0:
     dependencies:
       babel-runtime: 6.26.0
@@ -19439,7 +19615,7 @@ snapshots:
     dependencies:
       bytes: 3.1.2
       content-type: 1.0.5
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       http-errors: 2.0.1
       iconv-lite: 0.7.2
       on-finished: 2.4.1
@@ -20488,7 +20664,7 @@ snapshots:
   engine.io-client@6.6.5:
     dependencies:
       '@socket.io/component-emitter': 3.1.2
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       engine.io-parser: 5.2.3
       ws: 8.20.1
       xmlhttprequest-ssl: 2.1.2
@@ -20508,7 +20684,7 @@ snapshots:
       base64id: 2.0.0
       cookie: 0.7.2
       cors: 2.8.6
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       engine.io-parser: 5.2.3
       ws: 8.21.0
     transitivePeerDependencies:
@@ -20739,7 +20915,7 @@ snapshots:
   eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       eslint: 8.57.1
       get-tsconfig: 4.14.0
       is-bun-module: 2.0.0
@@ -20867,7 +21043,7 @@ snapshots:
       ajv: 6.15.0
       chalk: 4.1.2
       cross-spawn: 7.0.6
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       doctrine: 3.0.0
       escape-string-regexp: 4.0.0
       eslint-scope: 7.2.2
@@ -21104,7 +21280,7 @@ snapshots:
       content-type: 1.0.5
       cookie: 0.7.2
       cookie-signature: 1.2.2
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       depd: 2.0.0
       encodeurl: 2.0.0
       escape-html: 1.0.3
@@ -21157,7 +21333,7 @@ snapshots:
 
   extract-zip@2.0.1:
     dependencies:
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       get-stream: 5.2.0
       yauzl: 2.10.0
     optionalDependencies:
@@ -21312,7 +21488,7 @@ snapshots:
 
   finalhandler@2.1.1:
     dependencies:
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       encodeurl: 2.0.0
       escape-html: 1.0.3
       on-finished: 2.4.1
@@ -21560,7 +21736,7 @@ snapshots:
     dependencies:
       basic-ftp: 5.3.1
       data-uri-to-buffer: 6.0.2
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
     transitivePeerDependencies:
       - supports-color
 
@@ -21869,7 +22045,7 @@ snapshots:
   http-proxy-agent@7.0.2:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
     transitivePeerDependencies:
       - supports-color
 
@@ -21882,14 +22058,14 @@ snapshots:
   https-proxy-agent@5.0.1:
     dependencies:
       agent-base: 6.0.2
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
     transitivePeerDependencies:
       - supports-color
 
   https-proxy-agent@7.0.6:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
     transitivePeerDependencies:
       - supports-color
 
@@ -22329,7 +22505,7 @@ snapshots:
 
   istanbul-lib-source-maps@4.0.1:
     dependencies:
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       istanbul-lib-coverage: 3.2.2
       source-map: 0.6.1
     transitivePeerDependencies:
@@ -22985,7 +23161,7 @@ snapshots:
     dependencies:
       chalk: 5.6.2
       commander: 13.1.0
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       execa: 8.0.1
       lilconfig: 3.1.3
       listr2: 8.3.3
@@ -23672,7 +23848,7 @@ snapshots:
   micromark@4.0.2:
     dependencies:
       '@types/debug': 4.1.13
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       decode-named-character-reference: 1.3.0
       devlop: 1.1.0
       micromark-core-commonmark: 2.0.3
@@ -24198,7 +24374,7 @@ snapshots:
     dependencies:
       '@tootallnate/quickjs-emscripten': 0.23.0
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       get-uri: 6.0.5
       http-proxy-agent: 7.0.2
       https-proxy-agent: 7.0.6
@@ -24548,7 +24724,7 @@ snapshots:
   proxy-agent@6.5.0:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       http-proxy-agent: 7.0.2
       https-proxy-agent: 7.0.6
       lru-cache: 7.18.3
@@ -24577,7 +24753,7 @@ snapshots:
     dependencies:
       '@puppeteer/browsers': 2.13.2
       chromium-bidi: 14.0.0(devtools-protocol@0.0.1608973)
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       devtools-protocol: 0.0.1608973
       typed-query-selector: 2.12.2
       webdriver-bidi-protocol: 0.4.1
@@ -24830,6 +25006,15 @@ snapshots:
       - '@babel/core'
       - react-is
 
+  react-css-nocode-editor@1.0.13(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      styled-components: 5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)
+    transitivePeerDependencies:
+      - '@babel/core'
+      - react-is
+
   react-day-picker@8.10.2(date-fns@3.6.0)(react@19.2.6):
     dependencies:
       date-fns: 3.6.0
@@ -25440,7 +25625,7 @@ snapshots:
 
   router@2.2.0:
     dependencies:
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       depd: 2.0.0
       is-promise: 4.0.0
       parseurl: 1.3.3
@@ -25562,7 +25747,7 @@ snapshots:
 
   send@1.2.1:
     dependencies:
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       encodeurl: 2.0.0
       escape-html: 1.0.3
       etag: 1.8.1
@@ -25778,7 +25963,7 @@ snapshots:
 
   socket.io-adapter@2.5.8:
     dependencies:
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       ws: 8.21.0
     transitivePeerDependencies:
       - bufferutil
@@ -25788,7 +25973,7 @@ snapshots:
   socket.io-client@4.8.3:
     dependencies:
       '@socket.io/component-emitter': 3.1.2
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       engine.io-client: 6.6.5
       socket.io-parser: 4.2.6
     transitivePeerDependencies:
@@ -25799,7 +25984,7 @@ snapshots:
   socket.io-parser@4.2.6:
     dependencies:
       '@socket.io/component-emitter': 3.1.2
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
     transitivePeerDependencies:
       - supports-color
 
@@ -25808,7 +25993,7 @@ snapshots:
       accepts: 1.3.8
       base64id: 2.0.0
       cors: 2.8.6
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       engine.io: 6.6.9
       socket.io-adapter: 2.5.8
       socket.io-parser: 4.2.6
@@ -25820,7 +26005,7 @@ snapshots:
   socks-proxy-agent@8.0.5:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       socks: 2.8.9
     transitivePeerDependencies:
       - supports-color
@@ -26115,6 +26300,24 @@ snapshots:
     transitivePeerDependencies:
       - '@babel/core'
 
+  styled-components@5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6):
+    dependencies:
+      '@babel/helper-module-imports': 7.29.7(supports-color@5.5.0)
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
+      '@emotion/is-prop-valid': 1.4.0
+      '@emotion/stylis': 0.8.5
+      '@emotion/unitless': 0.7.5
+      babel-plugin-styled-components: 2.3.0(styled-components@5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6))(supports-color@5.5.0)
+      css-to-react-native: 3.2.0
+      hoist-non-react-statics: 3.3.2
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-is: 19.2.7
+      shallowequal: 1.1.0
+      supports-color: 5.5.0
+    transitivePeerDependencies:
+      - '@babel/core'
+
   styled-jsx@5.1.1(babel-plugin-macros@3.1.0)(react@18.3.1):
     dependencies:
       client-only: 0.0.1
@@ -26140,7 +26343,7 @@ snapshots:
     dependencies:
       component-emitter: 1.3.1
       cookiejar: 2.1.4
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       fast-safe-stringify: 2.1.1
       form-data: 4.0.5
       formidable: 3.5.4
@@ -26653,7 +26856,7 @@ snapshots:
       app-root-path: 3.1.0
       buffer: 6.0.3
       dayjs: 1.11.21
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       dedent: 1.7.2(babel-plugin-macros@3.1.0)
       dotenv: 16.6.1
       glob: 10.5.0
@@ -26677,7 +26880,7 @@ snapshots:
       app-root-path: 3.1.0
       buffer: 6.0.3
       dayjs: 1.11.21
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       dedent: 1.7.2(babel-plugin-macros@3.1.0)
       dotenv: 16.6.1
       glob: 10.5.0
@@ -27038,7 +27241,7 @@ snapshots:
   vite-node@2.1.9(@types/node@22.20.1)(lightningcss@1.32.0)(terser@5.48.0):
     dependencies:
       cac: 6.7.14
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       es-module-lexer: 1.7.0
       pathe: 1.1.2
       vite: 5.4.21(@types/node@22.20.1)(lightningcss@1.32.0)(terser@5.48.0)
@@ -27056,7 +27259,7 @@ snapshots:
   vite-node@2.1.9(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0):
     dependencies:
       cac: 6.7.14
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       es-module-lexer: 1.7.0
       pathe: 1.1.2
       vite: 5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0)
@@ -27103,7 +27306,7 @@ snapshots:
       '@vitest/spy': 2.1.9
       '@vitest/utils': 2.1.9
       chai: 5.3.3
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       expect-type: 1.3.0
       magic-string: 0.30.21
       pathe: 1.1.2
@@ -27139,7 +27342,7 @@ snapshots:
       '@vitest/spy': 2.1.9
       '@vitest/utils': 2.1.9
       chai: 5.3.3
-      debug: 4.4.3(supports-color@5.5.0)
+      debug: 4.4.3(supports-color@8.1.1)
       expect-type: 1.3.0
       magic-string: 0.30.21
       pathe: 1.1.2

From 357aae7d82dc060e4421236907cd68795c2a4f30 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 09:08:08 +0000
Subject: [PATCH 042/174] fix issue

---
 pnpm-lock.yaml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a56272063..1538a044a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -354,7 +354,7 @@ importers:
         version: 6.3.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tinymce@8.6.0)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(e4483b467c1e4b1b4b359f6670e164a6)
       '@types/three':
         specifier: ^0.185.3
         version: 0.185.3
@@ -601,7 +601,7 @@ importers:
         version: 5.101.0(react@19.2.6)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(ea394f4c73a62db876565d0b255299aa)
       '@vis.gl/react-google-maps':
         specifier: ^1.8.3
         version: 1.8.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -20888,7 +20888,7 @@ snapshots:
       '@typescript-eslint/parser': 8.60.1(eslint@8.57.1)(typescript@5.9.3)
       eslint: 8.57.1
       eslint-import-resolver-node: 0.3.10
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1)
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@8.57.1)
       eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.1)
       eslint-plugin-jsx-a11y: 6.10.2(eslint@8.57.1)
       eslint-plugin-react: 7.37.5(eslint@8.57.1)
@@ -20912,7 +20912,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1):
+  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0)(eslint@8.57.1):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
       debug: 4.4.3(supports-color@8.1.1)
@@ -20927,14 +20927,14 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-module-utils@2.13.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1):
+  eslint-module-utils@2.13.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.1):
     dependencies:
       debug: 3.2.7(supports-color@8.1.1)
     optionalDependencies:
       '@typescript-eslint/parser': 8.60.1(eslint@8.57.1)(typescript@5.9.3)
       eslint: 8.57.1
       eslint-import-resolver-node: 0.3.10
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1)
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@8.57.1)
     transitivePeerDependencies:
       - supports-color
 
@@ -20949,7 +20949,7 @@ snapshots:
       doctrine: 2.1.0
       eslint: 8.57.1
       eslint-import-resolver-node: 0.3.10
-      eslint-module-utils: 2.13.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1)
+      eslint-module-utils: 2.13.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.1)
       hasown: 2.0.4
       is-core-module: 2.16.2
       is-glob: 4.0.3

From 4efd65c1057b37c7f6c9f2498c1b23a177359381 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 09:20:28 +0000
Subject: [PATCH 043/174] feat: key bulk templates by trade direction
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bulk contract templates are now unique per (cargo type, trade direction,
customs option) instead of (cargo type, customs option). Intercity is
domestic and crosses no border, so it carries no customs variant:
with_customs stays null there, enforced by a check constraint.

Contract resolution already passed the trade direction through but the
bulk lookup dropped it, so one template served all three directions.

Container templates are unchanged — cargo_type_id is null on those rows,
which keeps them out of both the new index and the constraint.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ...420000000000-BulkTemplateTradeDirection.ts |  69 +++++++++
 .../bulk-template-direction.spec.ts           | 134 ++++++++++++++++++
 .../contract-templates.controller.ts          |   2 +-
 .../contract-templates.repository.ts          |  28 +++-
 .../contract-templates.service.ts             | 122 +++++++++++-----
 .../dto/contract-template.dto.ts              |  19 ++-
 .../entities/contract-template.entity.ts      |  52 ++++++-
 .../ContractTemplatesPage.tsx                 |  78 +++++++---
 .../services/contract-templates.service.ts    |  15 +-
 9 files changed, 448 insertions(+), 71 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3420000000000-BulkTemplateTradeDirection.ts
 create mode 100644 apps/edr-freight-api/src/modules/contract-templates/bulk-template-direction.spec.ts

diff --git a/apps/edr-freight-api/src/migrations/3420000000000-BulkTemplateTradeDirection.ts b/apps/edr-freight-api/src/migrations/3420000000000-BulkTemplateTradeDirection.ts
new file mode 100644
index 000000000..e76591205
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3420000000000-BulkTemplateTradeDirection.ts
@@ -0,0 +1,69 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Bulk contract templates gain trade direction, so the unique key becomes
+ * (cargo type, direction, customs option) instead of (cargo type, customs).
+ *
+ * Intercity is domestic and crosses no border, so it has no customs variant at
+ * all: with_customs stays NULL there, enforced by ck_bulk_intercity_no_customs.
+ * The unique index coalesces that NULL so two intercity templates for the same
+ * cargo type still collide (plain NULLs never do).
+ *
+ * No backfill: staff-created bulk templates are keyed by cargo_type_id and no
+ * such row exists yet — the seeded direction-keyed bulk rows were retired by
+ * 3320000000000 and carry a NULL cargo_type_id. The five system container
+ * templates are untouched: cargo_type_id IS NULL keeps them out of both the
+ * index and the check.
+ */
+export class BulkTemplateTradeDirection3420000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.contract_templates
+        ADD COLUMN IF NOT EXISTS trade_direction varchar(20)
+    `);
+
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS freight.uq_contract_templates_cargo_customs`,
+    );
+
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS uq_contract_templates_cargo_dir_customs
+        ON freight.contract_templates
+           (cargo_type_id, trade_direction, COALESCE(with_customs, false))
+        WHERE deleted_at IS NULL AND cargo_type_id IS NOT NULL
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE freight.contract_templates
+        DROP CONSTRAINT IF EXISTS ck_bulk_intercity_no_customs
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.contract_templates
+        ADD CONSTRAINT ck_bulk_intercity_no_customs CHECK (
+          cargo_type_id IS NULL
+          OR (
+            trade_direction IN ('IMPORT', 'EXPORT', 'INTERCITY')
+            AND (trade_direction = 'INTERCITY') = (with_customs IS NULL)
+          )
+        )
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.contract_templates
+        DROP CONSTRAINT IF EXISTS ck_bulk_intercity_no_customs
+    `);
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS freight.uq_contract_templates_cargo_dir_customs`,
+    );
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS uq_contract_templates_cargo_customs
+        ON freight.contract_templates (cargo_type_id, with_customs)
+        WHERE deleted_at IS NULL AND cargo_type_id IS NOT NULL
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.contract_templates DROP COLUMN IF EXISTS trade_direction
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/contract-templates/bulk-template-direction.spec.ts b/apps/edr-freight-api/src/modules/contract-templates/bulk-template-direction.spec.ts
new file mode 100644
index 000000000..b822387da
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/contract-templates/bulk-template-direction.spec.ts
@@ -0,0 +1,134 @@
+import { BadRequestException } from '@nestjs/common';
+
+import { ContractTemplatesRepository } from './contract-templates.repository';
+import { ContractTemplatesService } from './contract-templates.service';
+import {
+  bulkTemplateCode,
+  bulkTemplateDirectionFor,
+} from './entities/contract-template.entity';
+
+describe('bulkTemplateDirectionFor', () => {
+  it('maps the contract-side DOMESTIC onto the template-side INTERCITY', () => {
+    expect(bulkTemplateDirectionFor('DOMESTIC')).toBe('INTERCITY');
+    expect(bulkTemplateDirectionFor('INTERCITY')).toBe('INTERCITY');
+    expect(bulkTemplateDirectionFor(null)).toBe('INTERCITY');
+    expect(bulkTemplateDirectionFor(undefined)).toBe('INTERCITY');
+    expect(bulkTemplateDirectionFor('IMPORT')).toBe('IMPORT');
+    expect(bulkTemplateDirectionFor('EXPORT')).toBe('EXPORT');
+  });
+});
+
+describe('bulkTemplateCode', () => {
+  it('gives each direction/customs combination its own code', () => {
+    expect(bulkTemplateCode('STEEL', 'IMPORT', true)).toBe('BULK_IMPORT_STEEL_CUSTOMS');
+    expect(bulkTemplateCode('STEEL', 'IMPORT', false)).toBe(
+      'BULK_IMPORT_STEEL_NO_CUSTOMS',
+    );
+    expect(bulkTemplateCode('STEEL', 'EXPORT', true)).toBe('BULK_EXPORT_STEEL_CUSTOMS');
+    expect(bulkTemplateCode('STEEL', 'EXPORT', false)).toBe(
+      'BULK_EXPORT_STEEL_NO_CUSTOMS',
+    );
+  });
+
+  it('leaves intercity unsuffixed — it crosses no border', () => {
+    expect(bulkTemplateCode('STEEL', 'INTERCITY', null)).toBe('BULK_INTERCITY_STEEL');
+  });
+
+  it('produces 5 distinct codes per cargo type', () => {
+    const codes = [
+      bulkTemplateCode('STEEL', 'IMPORT', true),
+      bulkTemplateCode('STEEL', 'IMPORT', false),
+      bulkTemplateCode('STEEL', 'EXPORT', true),
+      bulkTemplateCode('STEEL', 'EXPORT', false),
+      bulkTemplateCode('STEEL', 'INTERCITY', null),
+    ];
+    expect(new Set(codes).size).toBe(5);
+  });
+});
+
+describe('ContractTemplatesService bulk create/resolve', () => {
+  function build() {
+    const repository = {
+      findCargoType: jest.fn(() =>
+        Promise.resolve({
+          id: 'cargo-1',
+          code: 'STEEL',
+          cargoTypeName: 'Steel',
+          hasContractTemplate: true,
+        }),
+      ),
+      findByCargoCombo: jest.fn(() => Promise.resolve(null)),
+      findActiveBulkTemplate: jest.fn(() => Promise.resolve(null)),
+      findByCode: jest.fn(() => Promise.resolve(null)),
+      saveTemplate: jest.fn((template) => Promise.resolve(template)),
+    } as unknown as ContractTemplatesRepository;
+    return {
+      repository,
+      service: new ContractTemplatesService(repository, {} as never),
+    };
+  }
+
+  it('stores direction and customs on an import template', async () => {
+    const { service } = build();
+    const created = await service.create({
+      cargoTypeId: 'cargo-1',
+      tradeDirection: 'EXPORT',
+      withCustoms: true,
+    });
+    expect(created.code).toBe('BULK_EXPORT_STEEL_CUSTOMS');
+    expect(created.tradeDirection).toBe('EXPORT');
+    expect(created.withCustoms).toBe(true);
+    expect(created.documentTitle).toBe(
+      'Steel Transportation and Customs Clearance Services',
+    );
+  });
+
+  it('stores a null customs flag for intercity', async () => {
+    const { service } = build();
+    const created = await service.create({
+      cargoTypeId: 'cargo-1',
+      tradeDirection: 'INTERCITY',
+    });
+    expect(created.code).toBe('BULK_INTERCITY_STEEL');
+    expect(created.withCustoms).toBeNull();
+    expect(created.documentTitle).toBe('Steel Transportation Services');
+  });
+
+  it('rejects a customs flag on intercity', async () => {
+    const { service } = build();
+    await expect(
+      service.create({
+        cargoTypeId: 'cargo-1',
+        tradeDirection: 'INTERCITY',
+        withCustoms: false,
+      }),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('requires a customs flag on import and export', async () => {
+    const { service } = build();
+    await expect(
+      service.create({ cargoTypeId: 'cargo-1', tradeDirection: 'IMPORT' }),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('resolves a domestic bulk contract to the intercity template, ignoring its customs flag', async () => {
+    const { repository, service } = build();
+    await service.findActiveForContract('DOMESTIC', 'BULK', true, 'cargo-1');
+    expect(repository.findActiveBulkTemplate).toHaveBeenCalledWith(
+      'cargo-1',
+      'INTERCITY',
+      null,
+    );
+  });
+
+  it('resolves an import bulk contract on direction and customs', async () => {
+    const { repository, service } = build();
+    await service.findActiveForContract('IMPORT', 'BULK', false, 'cargo-1');
+    expect(repository.findActiveBulkTemplate).toHaveBeenCalledWith(
+      'cargo-1',
+      'IMPORT',
+      false,
+    );
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/contract-templates/contract-templates.controller.ts b/apps/edr-freight-api/src/modules/contract-templates/contract-templates.controller.ts
index 7053d224f..cce30c187 100644
--- a/apps/edr-freight-api/src/modules/contract-templates/contract-templates.controller.ts
+++ b/apps/edr-freight-api/src/modules/contract-templates/contract-templates.controller.ts
@@ -61,7 +61,7 @@ export class ContractTemplatesController {
   ])
   @ApiOperation({
     summary:
-      "Create a bulk contract template for a (cargo type, customs option) pair",
+      "Create a bulk contract template for a (cargo type, trade direction, customs option) combination",
   })
   create(@Body() dto: CreateContractTemplateDto) {
     return this.service.create(dto);
diff --git a/apps/edr-freight-api/src/modules/contract-templates/contract-templates.repository.ts b/apps/edr-freight-api/src/modules/contract-templates/contract-templates.repository.ts
index 9d50b1677..1df3b1302 100644
--- a/apps/edr-freight-api/src/modules/contract-templates/contract-templates.repository.ts
+++ b/apps/edr-freight-api/src/modules/contract-templates/contract-templates.repository.ts
@@ -1,10 +1,13 @@
 import { BaseRepository } from "@edr/api-common";
 import { Injectable } from "@nestjs/common";
 import { InjectRepository } from "@nestjs/typeorm";
-import { Repository } from "typeorm";
+import { IsNull, Repository } from "typeorm";
 
 import { CargoType } from "../rule-engine/entities/cargo-type.entity";
-import { ContractTemplate } from "./entities/contract-template.entity";
+import {
+  BulkTemplateDirection,
+  ContractTemplate,
+} from "./entities/contract-template.entity";
 
 @Injectable()
 export class ContractTemplatesRepository extends BaseRepository<ContractTemplate> {
@@ -28,24 +31,35 @@ export class ContractTemplatesRepository extends BaseRepository<ContractTemplate
 
   findByCargoCombo(
     cargoTypeId: string,
-    withCustoms: boolean,
+    tradeDirection: BulkTemplateDirection,
+    withCustoms: boolean | null,
   ): Promise<ContractTemplate | null> {
-    return this.repository.findOne({ where: { cargoTypeId, withCustoms } });
+    return this.repository.findOne({
+      where: { cargoTypeId, tradeDirection, withCustoms: withCustoms ?? IsNull() },
+    });
   }
 
   /**
    * The active bulk template covering this cargo type: written against the
    * cargo type itself or against its parent group (the two are mutually
-   * exclusive, so at most one row matches).
+   * exclusive, so at most one row matches). Intercity templates carry no
+   * customs variant, so they are matched on a null flag.
    */
   findActiveBulkTemplate(
     cargoTypeId: string,
-    withCustoms: boolean,
+    tradeDirection: BulkTemplateDirection,
+    withCustoms: boolean | null,
   ): Promise<ContractTemplate | null> {
     return this.repository
       .createQueryBuilder("t")
       .where("t.is_active = true")
-      .andWhere("t.with_customs = :withCustoms", { withCustoms })
+      .andWhere("t.trade_direction = :tradeDirection", { tradeDirection })
+      .andWhere(
+        withCustoms === null
+          ? "t.with_customs IS NULL"
+          : "t.with_customs = :withCustoms",
+        withCustoms === null ? {} : { withCustoms },
+      )
       .andWhere(
         `(t.cargo_type_id = :cargoTypeId OR t.cargo_type_id = (
            SELECT c.parent_group_id FROM freight.cargo_types c
diff --git a/apps/edr-freight-api/src/modules/contract-templates/contract-templates.service.ts b/apps/edr-freight-api/src/modules/contract-templates/contract-templates.service.ts
index da9c849f7..3b2e43cff 100644
--- a/apps/edr-freight-api/src/modules/contract-templates/contract-templates.service.ts
+++ b/apps/edr-freight-api/src/modules/contract-templates/contract-templates.service.ts
@@ -23,6 +23,9 @@ import {
   UpdateContractTemplateDto,
 } from "./dto/contract-template.dto";
 import {
+  BulkTemplateDirection,
+  bulkTemplateCode,
+  bulkTemplateDirectionFor,
   CONTRACT_TEMPLATE_CODES,
   ContractTemplate,
   ContractTemplateArticle,
@@ -77,10 +80,13 @@ export class ContractTemplatesService {
   }
 
   /**
-   * Staff-created bulk template for one (cargo type, customs option) pair.
-   * The cargo type must have hasContractTemplate enabled and the combination
-   * must not already exist — the same commodity + customs pairing is edited,
-   * never duplicated.
+   * Staff-created bulk template for one (cargo type, direction, customs
+   * option) triple. The cargo type must have hasContractTemplate enabled and
+   * the combination must not already exist — the same commodity + direction +
+   * customs pairing is edited, never duplicated.
+   *
+   * Intercity is domestic and crosses no border, so it carries no customs
+   * variant: the flag must be omitted and is stored as null.
    */
   async create(dto: CreateContractTemplateDto): Promise<ContractTemplate> {
     const cargoType = await this.repository.findCargoType(dto.cargoTypeId);
@@ -92,31 +98,46 @@ export class ContractTemplatesService {
         `"${cargoType.cargoTypeName}" does not allow contract templates — enable "has contract template" on the cargo type first`,
       );
     }
-    const variant = dto.withCustoms ? "with" : "without";
+
+    const direction = dto.tradeDirection;
+    const intercity = direction === "INTERCITY";
+    if (intercity && dto.withCustoms !== undefined) {
+      throw new BadRequestException(
+        "Intercity contracts are domestic and cross no border — they have no customs clearing variant",
+      );
+    }
+    if (!intercity && dto.withCustoms === undefined) {
+      throw new BadRequestException(
+        `A ${direction.toLowerCase()} template must state whether customs clearing is included`,
+      );
+    }
+    const withCustoms = intercity ? null : Boolean(dto.withCustoms);
+
+    const label = this.comboLabel(cargoType.cargoTypeName, direction, withCustoms);
     const existing = await this.repository.findByCargoCombo(
       dto.cargoTypeId,
-      dto.withCustoms,
+      direction,
+      withCustoms,
     );
     if (existing) {
       throw new ConflictException(
-        `A "${cargoType.cargoTypeName}" template ${variant} customs clearing already exists — edit that template instead`,
+        `${label} already exists — edit that template instead`,
       );
     }
 
     const template = new ContractTemplate();
-    template.code = `BULK_${cargoType.code}_${dto.withCustoms ? "CUSTOMS" : "NO_CUSTOMS"}`.toUpperCase();
-    template.name =
-      dto.name ??
-      `${cargoType.cargoTypeName} Bulk Contract (${variant} customs clearing)`;
+    template.code = bulkTemplateCode(cargoType.code, direction, withCustoms);
+    template.name = dto.name ?? label;
     template.description = dto.description ?? null;
-    template.documentTitle = dto.withCustoms
+    template.documentTitle = withCustoms
       ? `${cargoType.cargoTypeName} Transportation and Customs Clearance Services`
       : `${cargoType.cargoTypeName} Transportation Services`;
     template.whereasClauses = [];
     template.articles = [];
     template.isActive = true;
     template.cargoTypeId = cargoType.id;
-    template.withCustoms = dto.withCustoms;
+    template.tradeDirection = direction;
+    template.withCustoms = withCustoms;
     template.isSystem = false;
     try {
       return await this.repository.saveTemplate(template);
@@ -124,13 +145,29 @@ export class ContractTemplatesService {
       // Partial unique index backstop for concurrent creates of the same combo.
       if ((error as { code?: string })?.code === "23505") {
         throw new ConflictException(
-          `A "${cargoType.cargoTypeName}" template ${variant} customs clearing already exists — edit that template instead`,
+          `${label} already exists — edit that template instead`,
         );
       }
       throw error;
     }
   }
 
+  /** Human label for one bulk combination, used for names and conflict errors. */
+  private comboLabel(
+    cargoTypeName: string,
+    direction: BulkTemplateDirection,
+    withCustoms: boolean | null,
+  ): string {
+    const dir = direction.charAt(0) + direction.slice(1).toLowerCase();
+    const customs =
+      withCustoms === null
+        ? ""
+        : withCustoms
+          ? ", with customs clearing"
+          : ", without customs clearing";
+    return `${cargoTypeName} Bulk Contract (${dir}${customs})`;
+  }
+
   /** Bulk templates only — the five seeded container templates are permanent. */
   async remove(code: string): Promise<void> {
     const template = await this.getByCode(code);
@@ -146,9 +183,10 @@ export class ContractTemplatesService {
    * The active template used when generating a contract document. Container
    * contracts resolve through the fixed direction/customs codes; bulk contracts
    * resolve through the staff-created template for the contract's cargo type
-   * (or its parent group) and customs option. Null when nothing matches or the
-   * match is deactivated (the renderer then falls back to the built-in generic
-   * layout).
+   * (or its parent group), trade direction and customs option. A domestic
+   * contract resolves to the intercity template regardless of its customs flag.
+   * Null when nothing matches or the match is deactivated (the renderer then
+   * falls back to the built-in generic layout).
    */
   async findActiveForContract(
     tradeDirection?: string | null,
@@ -159,9 +197,11 @@ export class ContractTemplatesService {
     const isBulk = (freightType ?? "").toUpperCase().includes("BULK");
     if (isBulk) {
       if (!cargoTypeId) return null;
+      const direction = bulkTemplateDirectionFor(tradeDirection);
       return this.repository.findActiveBulkTemplate(
         cargoTypeId,
-        Boolean(customsClearingEnabled),
+        direction,
+        direction === "INTERCITY" ? null : Boolean(customsClearingEnabled),
       );
     }
     const code = contractTemplateCodeFor(
@@ -274,18 +314,31 @@ export class ContractTemplatesService {
 
   /**
    * Registry key the mock preview renders against. Staff-created bulk
-   * templates aren't in the fixed code map — they preview against the
-   * representative bulk import pack matching their customs option.
+   * templates aren't in the fixed code map — they preview against the bulk
+   * pack matching their own direction and customs option.
    */
   private previewKeyFor(template: ContractTemplate): string {
     if (template.cargoTypeId) {
-      return template.withCustoms
-        ? "IMP_BULK_USD_FORWARDING"
-        : "IMP_BULK_USD_TRANSPORT_ONLY";
+      const direction = bulkTemplateDirectionFor(template.tradeDirection);
+      const dir =
+        direction === "IMPORT" ? "IMP" : direction === "EXPORT" ? "EXP" : "DOM";
+      const scope = template.withCustoms ? "FORWARDING" : "TRANSPORT_ONLY";
+      return `${dir}_BULK_USD_${scope}`;
     }
     return PREVIEW_TEMPLATE_KEYS[template.code as ContractTemplateCode];
   }
 
+  /**
+   * Preview direction: bulk templates carry it on the row, the fixed container
+   * codes carry it as the code prefix.
+   */
+  private previewDirectionFor(template: ContractTemplate): BulkTemplateDirection {
+    if (template.cargoTypeId) {
+      return bulkTemplateDirectionFor(template.tradeDirection);
+    }
+    return bulkTemplateDirectionFor(template.code.split("_")[0]);
+  }
+
   private buildMockView(
     template: ContractTemplate,
     dynamicTemplate: ContractDynamicTemplateView,
@@ -294,11 +347,12 @@ export class ContractTemplatesService {
     const previewKey = this.previewKeyFor(template);
     const meta = getTemplateMeta(previewKey);
     const isBulk = Boolean(template.cargoTypeId) || code.includes("BULK");
+    const direction = this.previewDirectionFor(template);
     const now = new Date();
 
     // Representative rate schedule so the admin preview shows the live-rate
     // table shape. Real contracts populate this from freight.rates (LIVE).
-    const rateSchedule = this.mockRateSchedule(code, isBulk);
+    const rateSchedule = this.mockRateSchedule(direction, isBulk);
 
     return {
       bookingId: "00000000-0000-0000-0000-000000000000",
@@ -336,11 +390,7 @@ export class ContractTemplatesService {
       schedule: {
         originLabel: isBulk ? "Nagad Railway Station" : "SGTD Freight Station",
         destinationLabel: "Galaan Multipurpose Port (GMP)",
-        tradeDirection: code.startsWith("IMPORT")
-          ? "IMPORT"
-          : code.startsWith("EXPORT")
-            ? "EXPORT"
-            : "DOMESTIC",
+        tradeDirection: direction === "INTERCITY" ? "DOMESTIC" : direction,
         freightType: isBulk ? "BULK" : "CONTAINER",
         serviceType: "Rail transport and customs clearance",
         scheduledDate: "—",
@@ -379,16 +429,14 @@ export class ContractTemplatesService {
   }
 
   /** Static, representative rate schedule for the admin preview only. */
-  private mockRateSchedule(code: string, isBulk: boolean): RateSchedule {
-    const dir = code.startsWith("IMPORT")
-      ? "import"
-      : code.startsWith("EXPORT")
-        ? "export"
-        : "domestic";
+  private mockRateSchedule(
+    direction: BulkTemplateDirection,
+    isBulk: boolean,
+  ): RateSchedule {
     const lane =
-      dir === "export"
+      direction === "EXPORT"
         ? "Galaan Multipurpose Port → SGTD"
-        : dir === "domestic"
+        : direction === "INTERCITY"
           ? "Mojo Dry Port → Dire Dawa"
           : "Negad → Mojo Dry Port";
 
diff --git a/apps/edr-freight-api/src/modules/contract-templates/dto/contract-template.dto.ts b/apps/edr-freight-api/src/modules/contract-templates/dto/contract-template.dto.ts
index c8911d8e5..9f7579dbd 100644
--- a/apps/edr-freight-api/src/modules/contract-templates/dto/contract-template.dto.ts
+++ b/apps/edr-freight-api/src/modules/contract-templates/dto/contract-template.dto.ts
@@ -3,6 +3,7 @@ import { Type } from "class-transformer";
 import {
   IsArray,
   IsBoolean,
+  IsIn,
   IsInt,
   IsOptional,
   IsString,
@@ -13,6 +14,11 @@ import {
   ValidateNested,
 } from "class-validator";
 
+import {
+  BULK_TEMPLATE_DIRECTIONS,
+  BulkTemplateDirection,
+} from "../entities/contract-template.entity";
+
 export class CreateContractTemplateDto {
   @ApiProperty({
     description:
@@ -23,10 +29,19 @@ export class CreateContractTemplateDto {
   cargoTypeId!: string;
 
   @ApiProperty({
-    description: "Whether this is the with-customs-clearing variant",
+    description: "Trade direction this template is written for",
+    enum: BULK_TEMPLATE_DIRECTIONS,
   })
+  @IsIn(BULK_TEMPLATE_DIRECTIONS as unknown as string[])
+  tradeDirection!: BulkTemplateDirection;
+
+  @ApiPropertyOptional({
+    description:
+      "Whether this is the with-customs-clearing variant. Required for IMPORT/EXPORT, rejected for INTERCITY (domestic movements cross no border)",
+  })
+  @IsOptional()
   @IsBoolean()
-  withCustoms!: boolean;
+  withCustoms?: boolean;
 
   @ApiPropertyOptional({ description: "Display name (derived from the cargo type when omitted)" })
   @IsOptional()
diff --git a/apps/edr-freight-api/src/modules/contract-templates/entities/contract-template.entity.ts b/apps/edr-freight-api/src/modules/contract-templates/entities/contract-template.entity.ts
index af0721572..e070aa1e4 100644
--- a/apps/edr-freight-api/src/modules/contract-templates/entities/contract-template.entity.ts
+++ b/apps/edr-freight-api/src/modules/contract-templates/entities/contract-template.entity.ts
@@ -9,10 +9,10 @@ import { CargoType } from "../../rule-engine/entities/cargo-type.entity";
  * template). These are system rows: always present, never deletable.
  *
  * Bulk templates are NOT seeded — staff create them per bulk cargo type
- * (`cargoTypeId`) and customs option (`withCustoms`), one template per
- * combination. Their codes are generated as BULK_<cargo code>_(NO_)CUSTOMS.
- * The retired direction-keyed bulk codes remain listed so old frozen document
- * snapshots still label correctly.
+ * (`cargoTypeId`), trade direction (`tradeDirection`) and customs option
+ * (`withCustoms`), one template per combination. Their codes are generated by
+ * `bulkTemplateCode` below. The retired direction-keyed bulk codes remain
+ * listed so old frozen document snapshots still label correctly.
  *
  * Contracts store DOMESTIC for intercity movements; the template layer labels
  * those INTERCITY to match the commercial vocabulary used on the printed
@@ -82,9 +82,41 @@ export function contractTemplateCodeFor(
   return `${direction}_${freight}_${customs}` as ContractTemplateCode;
 }
 
+/** The three directions a bulk template can be written for. */
+export const BULK_TEMPLATE_DIRECTIONS = ["IMPORT", "EXPORT", "INTERCITY"] as const;
+
+export type BulkTemplateDirection = (typeof BULK_TEMPLATE_DIRECTIONS)[number];
+
+/**
+ * Contracts store DOMESTIC for intercity movements; templates use INTERCITY.
+ * Anything that is not an explicit IMPORT/EXPORT is domestic, matching
+ * `contractTemplateCodeFor`.
+ */
+export function bulkTemplateDirectionFor(
+  tradeDirection?: string | null,
+): BulkTemplateDirection {
+  const value = (tradeDirection ?? "").toUpperCase();
+  return value === "IMPORT" || value === "EXPORT" ? value : "INTERCITY";
+}
+
+/**
+ * Generated code for a staff-created bulk template. Intercity gets no customs
+ * suffix — it crosses no border, so the variant does not exist.
+ */
+export function bulkTemplateCode(
+  cargoCode: string,
+  direction: BulkTemplateDirection,
+  withCustoms: boolean | null,
+): string {
+  const suffix =
+    direction === "INTERCITY" ? "" : withCustoms ? "_CUSTOMS" : "_NO_CUSTOMS";
+  return `BULK_${direction}_${cargoCode}${suffix}`.toUpperCase();
+}
+
 @Entity({ schema: "freight", name: "contract_templates" })
 // Uniqueness lives in partial DB indexes (live rows only): code, and
-// (cargo_type_id, with_customs) for staff-created bulk templates.
+// (cargo_type_id, trade_direction, coalesce(with_customs,false)) for
+// staff-created bulk templates.
 @Index(["code"])
 export class ContractTemplate extends BaseEntity {
   @Column({ name: "code", type: "varchar", length: 80 })
@@ -118,7 +150,15 @@ export class ContractTemplate extends BaseEntity {
   @JoinColumn({ name: "cargo_type_id" })
   cargoType?: CargoType | null;
 
-  /** Bulk templates only: whether this is the with-customs-clearing variant. */
+  /** Bulk templates only: IMPORT, EXPORT or INTERCITY. */
+  @Column({ name: "trade_direction", type: "varchar", length: 20, nullable: true })
+  tradeDirection?: BulkTemplateDirection | null;
+
+  /**
+   * Bulk templates only: whether this is the with-customs-clearing variant.
+   * Always null for INTERCITY templates — domestic movements have no customs
+   * leg, so neither variant applies.
+   */
   @Column({ name: "with_customs", type: "boolean", nullable: true })
   withCustoms?: boolean | null;
 
diff --git a/apps/edr-freight-web/backoffice/src/pages/contract_templates/ContractTemplatesPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contract_templates/ContractTemplatesPage.tsx
index 1a66bbdd5..1adcd2e6c 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contract_templates/ContractTemplatesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contract_templates/ContractTemplatesPage.tsx
@@ -38,7 +38,10 @@ import {
 } from "@/hooks/contract-templates/useContractTemplates";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import { cargoTypesService } from "@/services/cargo-types.service";
-import type { ContractTemplate } from "@/services/contract-templates.service";
+import type {
+  BulkTemplateDirection,
+  ContractTemplate,
+} from "@/services/contract-templates.service";
 import TemplatePreviewModal from "./TemplatePreviewModal";
 
 const DIRECTION_LABEL: Record<string, string> = {
@@ -68,6 +71,14 @@ function customsVariant(template: ContractTemplate): boolean | null {
   return null;
 }
 
+// Bulk templates carry the direction on the row; the fixed container codes
+// carry it as the code prefix.
+function directionOf(template: ContractTemplate): string {
+  return isBulk(template)
+    ? template.tradeDirection ?? "INTERCITY"
+    : template.code.split("_")[0];
+}
+
 function formatUpdated(value: string): string {
   return new Date(value).toLocaleDateString("en-GB", {
     day: "numeric",
@@ -105,7 +116,7 @@ export default function ContractTemplatesPage() {
     <PageContainer>
       <PageHeader
         title="Contract templates"
-        subtitle="The five container contract documents are built in — one per trade direction and customs-clearing option. Bulk contracts are written per cargo type: create one template per commodity and customs option. Articles are fully editable."
+        subtitle="The five container contract documents are built in — one per trade direction and customs-clearing option. Bulk contracts are written per cargo type: create one template per trade direction, customs option and commodity. Articles are fully editable."
         action={
           canCreate ? (
             <Button
@@ -194,9 +205,13 @@ export default function ContractTemplatesPage() {
 }
 
 /**
- * Staff pick the customs option first, then a bulk cargo type that has
- * "has contract template" enabled. One template per combination — the API
- * rejects duplicates, so an existing pairing must be edited instead.
+ * Staff pick the trade direction, then the customs option, then a bulk cargo
+ * type that has "has contract template" enabled. One template per
+ * (direction, customs, cargo type) combination — the API rejects duplicates,
+ * so an existing combination must be edited instead.
+ *
+ * Intercity is domestic and crosses no border, so the customs choice does not
+ * apply there and is hidden.
  */
 function CreateTemplateModal({
   opened,
@@ -207,9 +222,11 @@ function CreateTemplateModal({
   onClose: () => void;
   onCreated: (code: string) => void;
 }) {
+  const [direction, setDirection] = useState<BulkTemplateDirection>("IMPORT");
   const [withCustoms, setWithCustoms] = useState<string>("true");
   const [cargoTypeId, setCargoTypeId] = useState<string | null>(null);
   const create = useCreateContractTemplate();
+  const intercity = direction === "INTERCITY";
 
   const { data: cargoTypes, isLoading } = useQuery({
     queryKey: ["cargo-types", "contract-template-options"],
@@ -238,19 +255,42 @@ function CreateTemplateModal({
       <Stack gap="md">
         <div>
           <Text size="sm" fw={500} mb={6}>
-            Customs clearing
+            Trade direction
           </Text>
           <SegmentedControl
             fullWidth
-            value={withCustoms}
-            onChange={setWithCustoms}
+            value={direction}
+            onChange={(value) => setDirection(value as BulkTemplateDirection)}
             data={[
-              { value: "true", label: "With customs clearing" },
-              { value: "false", label: "Without customs clearing" },
+              { value: "IMPORT", label: "Import" },
+              { value: "EXPORT", label: "Export" },
+              { value: "INTERCITY", label: "Intercity" },
             ]}
           />
         </div>
 
+        {intercity ? (
+          <Text size="xs" c="dimmed">
+            Intercity contracts are domestic and cross no border, so they have
+            no customs clearing variant — one template per cargo type.
+          </Text>
+        ) : (
+          <div>
+            <Text size="sm" fw={500} mb={6}>
+              Customs clearing
+            </Text>
+            <SegmentedControl
+              fullWidth
+              value={withCustoms}
+              onChange={setWithCustoms}
+              data={[
+                { value: "true", label: "With customs clearing" },
+                { value: "false", label: "Without customs clearing" },
+              ]}
+            />
+          </div>
+        )}
+
         <Select
           label="Bulk cargo type"
           description="Only cargo types with “has contract template” enabled are listed"
@@ -273,7 +313,12 @@ function CreateTemplateModal({
             onClick={() => {
               if (!cargoTypeId) return;
               create.mutate(
-                { cargoTypeId, withCustoms: withCustoms === "true" },
+                {
+                  cargoTypeId,
+                  tradeDirection: direction,
+                  // Omitted for intercity — the API rejects the flag there.
+                  ...(intercity ? {} : { withCustoms: withCustoms === "true" }),
+                },
                 {
                   onSuccess: (template) =>
                     onCreated((template as ContractTemplate).code),
@@ -305,10 +350,12 @@ function TemplateCard({
   onDelete: () => void;
 }) {
   const bulk = isBulk(template);
-  const direction = template.code.split("_")[0];
+  const direction = directionOf(template);
   const customs = customsVariant(template);
   const kicker = bulk
-    ? `${template.cargoType?.cargoTypeName ?? "Bulk cargo"} · Bulk`
+    ? `${template.cargoType?.cargoTypeName ?? "Bulk cargo"} · ${
+        DIRECTION_LABEL[direction] ?? direction
+      } · Bulk`
     : `${DIRECTION_LABEL[direction] ?? direction} · Container`;
 
   return (
@@ -336,9 +383,8 @@ function TemplateCard({
                 style={{
                   borderRadius: 999,
                   flexShrink: 0,
-                  background: bulk
-                    ? "var(--mantine-color-teal-5)"
-                    : DIRECTION_DOT[direction] ?? "var(--mantine-color-gray-5)",
+                  background:
+                    DIRECTION_DOT[direction] ?? "var(--mantine-color-gray-5)",
                 }}
               />
               <Text size="xs" fw={600} tt="uppercase" lts="0.06em" c="dimmed">
diff --git a/apps/edr-freight-web/backoffice/src/services/contract-templates.service.ts b/apps/edr-freight-web/backoffice/src/services/contract-templates.service.ts
index 7952395b5..f283b8af3 100644
--- a/apps/edr-freight-web/backoffice/src/services/contract-templates.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/contract-templates.service.ts
@@ -2,6 +2,10 @@ import { api as client } from "../auth/http";
 
 const BASE = "/contract-templates";
 
+export const BULK_TEMPLATE_DIRECTIONS = ["IMPORT", "EXPORT", "INTERCITY"] as const;
+
+export type BulkTemplateDirection = (typeof BULK_TEMPLATE_DIRECTIONS)[number];
+
 export interface ContractTemplateArticle {
   id: string;
   title: string;
@@ -23,7 +27,12 @@ export interface ContractTemplate {
   /** Bulk templates only: the cargo type this template is written for. */
   cargoTypeId?: string | null;
   cargoType?: { id: string; cargoTypeName: string } | null;
-  /** Bulk templates only: whether this is the with-customs-clearing variant. */
+  /** Bulk templates only: IMPORT, EXPORT or INTERCITY. */
+  tradeDirection?: BulkTemplateDirection | null;
+  /**
+   * Bulk templates only: whether this is the with-customs-clearing variant.
+   * Null for intercity — domestic movements have no customs leg.
+   */
   withCustoms?: boolean | null;
   /** The five seeded container templates — cannot be deleted. */
   isSystem: boolean;
@@ -33,7 +42,9 @@ export interface ContractTemplate {
 
 export interface CreateContractTemplatePayload {
   cargoTypeId: string;
-  withCustoms: boolean;
+  tradeDirection: BulkTemplateDirection;
+  /** Omitted for INTERCITY — the API rejects the flag there. */
+  withCustoms?: boolean;
   name?: string;
   description?: string;
 }

From bd9f7f354a412888a35c08d1a8896128ad6c656f Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 12 Aug 2026 09:31:31 +0000
Subject: [PATCH 044/174] feat(freight-api): enrich canonical request log line

Emit the request line as raw JSON on stdout (level/time/logger as fields)
instead of through Nest's console logger, whose prefix made it unparsable.

Collect data points via logCtx at the flow chokepoints: BaseRepository
writes (status changes, creates, deletes), invoice transitions, payment
intent lifecycle + outbound payment-service calls, booking/contract entry
state, review-note reasons, signatures and OTP verify outcomes.
---
 .../src/common/request-log-context.spec.ts    | 50 ++++++++++++-
 .../src/modules/billing/billing.service.ts    | 59 ++++++++++++++-
 .../modules/bookings/bookings.repository.ts   |  9 ++-
 .../src/modules/bookings/bookings.service.ts  | 17 ++++-
 .../contracts/contract-transition.service.ts  | 15 +++-
 .../modules/contracts/contracts.service.ts    | 14 +++-
 .../src/modules/otp/otp.service.ts            |  8 ++
 .../modules/payment/payment-client.service.ts | 14 ++++
 .../src/modules/payment/payment.service.ts    | 73 +++++++++++++++++++
 .../src/logging/request-log.middleware.ts     | 18 ++++-
 .../src/repositories/base.repository.ts       | 32 +++++++-
 11 files changed, 295 insertions(+), 14 deletions(-)

diff --git a/apps/edr-freight-api/src/common/request-log-context.spec.ts b/apps/edr-freight-api/src/common/request-log-context.spec.ts
index 0aefe3695..403b1a137 100644
--- a/apps/edr-freight-api/src/common/request-log-context.spec.ts
+++ b/apps/edr-freight-api/src/common/request-log-context.spec.ts
@@ -1,5 +1,7 @@
 import { Logger } from "@nestjs/common";
+import type { Repository } from "typeorm";
 import {
+  BaseRepository,
   RequestLogMiddleware,
   getLogContext,
   logCtx,
@@ -47,10 +49,13 @@ describe("logCtx", () => {
 
 describe("RequestLogMiddleware", () => {
   it("emits one canonical JSON line carrying the collected context", () => {
+    // Raw stdout, not the Nest logger — the line must be parsable JSON with no
+    // "[Nest] … LOG [request]" prefix in front of it.
     const lines: string[] = [];
-    jest
-      .spyOn(Logger.prototype, "warn")
-      .mockImplementation((m) => lines.push(String(m)));
+    jest.spyOn(process.stdout, "write").mockImplementation((chunk) => {
+      lines.push(String(chunk));
+      return true;
+    });
     jest.spyOn(Logger.prototype, "log").mockImplementation(() => undefined);
 
     const listeners: Record<string, () => void> = {};
@@ -82,7 +87,11 @@ describe("RequestLogMiddleware", () => {
     listeners.close(); // aborts/close after finish must not double-log
 
     expect(lines).toHaveLength(1);
+    expect(lines[0].endsWith("\n")).toBe(true);
+    expect(lines[0].startsWith("{")).toBe(true);
     expect(JSON.parse(lines[0])).toMatchObject({
+      level: "warn",
+      logger: "request",
       type: "http_request",
       requestId: "req-42",
       method: "POST",
@@ -100,3 +109,38 @@ describe("RequestLogMiddleware", () => {
     jest.restoreAllMocks();
   });
 });
+
+describe("BaseRepository write trail", () => {
+  class TestRepo extends BaseRepository<{ id: string; status?: string }> {
+    constructor(repo: Repository<{ id: string; status?: string }>) {
+      super(repo);
+    }
+  }
+
+  const typeormRepo = {
+    metadata: { tableName: "booking" },
+    create: (data: unknown) => data,
+    save: async (data: unknown) => data,
+    update: async () => undefined,
+    findOne: async () => ({ id: "b-1", status: "SUBMITTED" }),
+    softDelete: async () => undefined,
+    delete: async () => undefined,
+  } as unknown as Repository<{ id: string; status?: string }>;
+
+  it("records creates, status changes and deletes without any service opting in", async () => {
+    const ctx = await runWithLogContext({}, async () => {
+      const repo = new TestRepo(typeormRepo);
+      await repo.create({ id: "b-1" });
+      await repo.update("b-1", { status: "SUBMITTED" });
+      await repo.update("b-1", { id: "b-1" }); // no status → no transition entry
+      await repo.softDelete("b-1");
+      return getLogContext();
+    });
+
+    expect(ctx).toEqual({
+      db: { created: { booking: 1 }, updated: { booking: 2 } },
+      statusChanges: [{ entity: "booking", id: "b-1", status: "SUBMITTED" }],
+      deleted: [{ entity: "booking", id: "b-1" }],
+    });
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 9a31466f0..6c7e8455d 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -8,6 +8,7 @@ import {
   NotFoundException,
 } from "@nestjs/common";
 import { EventEmitter2 } from "@nestjs/event-emitter";
+import { logCtx } from "@edr/api-common";
 import { DataSource, EntityManager, In } from "typeorm";
 
 import { Booking } from "../bookings/entities/booking.entity";
@@ -951,6 +952,24 @@ export class BillingService {
 
       await mg.update(Invoice, { id: invoice.id }, { status, ...extra });
 
+      // Every invoice status move in the app funnels through here — money
+      // changing state is the single most-asked question in support.
+      logCtx(
+        {
+          invoiceId: invoice.id,
+          invoiceNumber: invoice.invoiceNumber,
+          source: invoice.source,
+          sourceId: invoice.sourceId,
+          from: invoice.status,
+          to: status,
+          event,
+          amount: Number(invoice.totalAmount),
+          currency: invoice.currency,
+          paymentId: extra.paymentId ?? invoice.paymentId ?? undefined,
+        },
+        { path: "invoiceTransitions", mode: "push" },
+      );
+
       const updated = { ...invoice, ...extra, status } as Invoice;
       return {
         result: updated,
@@ -1320,6 +1339,21 @@ export class BillingService {
       throw new BadRequestException("Invoice has no outstanding balance.");
     }
 
+    logCtx(
+      {
+        invoiceId: invoice.id,
+        invoiceNumber: invoice.invoiceNumber,
+        source: invoice.source,
+        sourceId: invoice.sourceId,
+        companyId: invoice.companyId,
+        amountDue,
+        currency: invoice.currency,
+        method: opts.method ?? "TELEBIRR",
+        platform: opts.platform,
+      },
+      { path: "payment.payInvoice" },
+    );
+
     // CAC Bank is an OTP debit — the bank SMSes the code to this number, so it is
     // required up front (the payment service rejects it otherwise, as a 502 here).
     if (
@@ -1443,7 +1477,24 @@ export class BillingService {
       // first on DESC, which would hand back an unissued invoice.
       order: { issuedAt: { direction: "DESC", nulls: "LAST" } },
     });
-    if (!invoice) return null;
+    if (!invoice) {
+      logCtx(
+        { paymentId, outcome: "no-invoice-for-payment" },
+        { path: "payment.settleInvoice" },
+      );
+      return null;
+    }
+
+    logCtx(
+      {
+        paymentId,
+        providerTxnId,
+        invoiceId: invoice.id,
+        invoiceNumber: invoice.invoiceNumber,
+        invoiceStatus: invoice.status,
+      },
+      { path: "payment.settleInvoice" },
+    );
 
     const settleable: Freight.InvoiceStatus[] = [
       ...OPEN_STATUSES,
@@ -1453,6 +1504,12 @@ export class BillingService {
       // Already PAID is the ordinary idempotent no-op (redelivery, or settled
       // inline by payInvoice). Anything else means money was captured with
       // nowhere to land — that needs a person, so say so loudly.
+      logCtx(
+        invoice.status === Freight.InvoiceStatus.Paid
+          ? "already-paid"
+          : "captured-with-nowhere-to-land",
+        { path: "payment.settleInvoice.outcome", mode: "set" },
+      );
       if (invoice.status !== Freight.InvoiceStatus.Paid) {
         this.logger.error(
           `Payment ${paymentId} succeeded but invoice ${invoice.invoiceNumber} ` +
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
index 1c5cc7481..2b1463a95 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
@@ -1,4 +1,4 @@
-import { BaseRepository } from '@edr/api-common';
+import { BaseRepository, logCtx } from '@edr/api-common';
 import { SchedulingStatus } from '@edr/types';
 import { ConflictException, Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
@@ -631,6 +631,13 @@ export class BookingsRepository extends BaseRepository<Booking> {
     authorId?: string,
   ): Promise<BookingReviewNote> {
     const repo = this.dataSource.getRepository(BookingReviewNote);
+    // Every rejection/cancellation/change-request reason in the booking flow is
+    // written through here — the "why" behind the status change on the same log
+    // line as the status change itself.
+    logCtx(
+      { bookingId, type, note, authorId },
+      { path: 'reviewNotes', mode: 'push' },
+    );
     return repo.save(
       repo.create({ bookingId, note, type, authorId: authorId ?? null }),
     );
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
index 121c889bc..6c3f14ecb 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
@@ -9,7 +9,7 @@ import {
   NotFoundException,
 } from '@nestjs/common';
 import { Freight, SchedulingStatus } from '@edr/types';
-import { insertWithGeneratedReference } from '@edr/api-common';
+import { insertWithGeneratedReference, logCtx } from '@edr/api-common';
 // import { CustomersService } from '../customers/customers.service';
 import { CompaniesService } from '../companies/companies.service';
 import { CompanyKind, CompanyStatus } from '../companies/entities/company.entity';
@@ -2115,6 +2115,21 @@ export class BookingsService {
       throw new NotFoundException(`Booking ${id} not found`);
     }
 
+    // Nearly every booking flow loads the booking through here, so this one
+    // call puts the human-searchable reference + entry state on the request log
+    // line for all of them. Entry state only — the write trail (statusChanges)
+    // shows where it ended up.
+    logCtx(
+      {
+        id: booking.id,
+        reference: booking.reference,
+        statusAtEntry: booking.status,
+        companyId: booking.companyId,
+        contractId: booking.contractId ?? undefined,
+      },
+      { path: "booking" },
+    );
+
     if (booking.files && booking.files.length > 0) {
       booking.files = await Promise.all(
         booking.files.map(async (file: FileRecord) => {
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
index fc3a238ea..e6f208ae2 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
@@ -9,7 +9,7 @@ import { InjectDataSource } from '@nestjs/typeorm';
 import { DataSource } from 'typeorm';
 import { randomUUID } from 'node:crypto';
 import { Readable } from 'stream';
-import { insertWithGeneratedReference } from '@edr/api-common';
+import { insertWithGeneratedReference, logCtx } from '@edr/api-common';
 import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
 
 import { ContractDocumentViewModelBuilder } from '../../contracts/contract-document-view-model.builder';
@@ -1084,6 +1084,19 @@ export class ContractTransitionService {
   ): Promise<void> {
     const role = dto.role as ContractSignerRole;
 
+    // Both sign() and counterSign() land here — who signed what, and whether the
+    // ink came from the request or the signer's saved profile signature.
+    logCtx(
+      {
+        contractId: contract.id,
+        reference: contract.reference,
+        role,
+        signerUserId: options.signerUserId,
+        usedDrawnImage: Boolean(dto.signatureImageBase64),
+      },
+      { path: "contractSignatures", mode: "push" },
+    );
+
     // Resolve the signature image. The client may send a freshly-drawn image, or
     // omit it to reuse the signer's saved profile signature. Fall back to the
     // saved one whenever no image is supplied.
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 6e170f126..607a6f525 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
@@ -7,7 +7,7 @@ import {
 } from '@nestjs/common';
 import { InjectDataSource } from '@nestjs/typeorm';
 import { DataSource } from 'typeorm';
-import { insertWithGeneratedReference } from '@edr/api-common';
+import { insertWithGeneratedReference, logCtx } from '@edr/api-common';
 
 import { YardCountry } from '@edr/types';
 //
@@ -811,6 +811,18 @@ export class ContractsService {
       throw new NotFoundException(`Contract ${id} not found`);
     }
 
+    // Entry state for every contract flow (submit, approve, sign, suspend…) —
+    // see the equivalent in BookingsService.findById.
+    logCtx(
+      {
+        id: contract.id,
+        reference: contract.reference,
+        statusAtEntry: contract.status,
+        companyId: contract.companyId,
+      },
+      { path: "contract" },
+    );
+
     if (contract.files && contract.files.length > 0) {
       contract.files = await Promise.all(
         contract.files.map(async (file: FileRecord) => {
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 a7361fbdd..42d46226a 100644
--- a/apps/edr-freight-api/src/modules/otp/otp.service.ts
+++ b/apps/edr-freight-api/src/modules/otp/otp.service.ts
@@ -1,6 +1,7 @@
 // otp.service.ts
 
 import { BadRequestException, Injectable, Logger } from "@nestjs/common";
+import { logCtx } from "@edr/api-common";
 import { randomInt } from "node:crypto";
 
 import { OtpRepository } from "./otp.repository";
@@ -317,6 +318,13 @@ export class OtpService {
       }`;
     if (result === "ok") this.logger.log(line);
     else this.logger.warn(line);
+
+    // Outcome only — the target is a phone number / email address and stays out
+    // of the canonical line. Channels are safe and say which one was used.
+    logCtx(
+      { mode, result, channels: channelsOf(target) },
+      { path: "otp.verify", mode: "push" },
+    );
   }
 
   /**
diff --git a/apps/edr-freight-api/src/modules/payment/payment-client.service.ts b/apps/edr-freight-api/src/modules/payment/payment-client.service.ts
index 26a0cf5ed..de220fd59 100644
--- a/apps/edr-freight-api/src/modules/payment/payment-client.service.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment-client.service.ts
@@ -7,6 +7,7 @@ import {
 import { HttpService } from "@nestjs/axios";
 import { AxiosError } from "axios";
 import { firstValueFrom } from "rxjs";
+import { logCtx } from "@edr/api-common";
 import {
   InitiatePaymentRequest,
   PaymentIntentSnapshot,
@@ -111,6 +112,16 @@ export class PaymentClientService {
     body?: unknown,
   ): Promise<T> {
     const url = `${this.baseUrl}${path}`;
+    // Every hop to the payment service lands on the request log line: which
+    // call, how slow, and what it answered. A settle that never happened is
+    // almost always one of these coming back 4xx/5xx or timing out.
+    const startedAt = Date.now();
+    const trace = (extra: Record<string, unknown>) =>
+      logCtx(
+        { method, path, ms: Date.now() - startedAt, ...extra },
+        { path: "outbound.payment", mode: "push" },
+      );
+
     try {
       const response = await firstValueFrom(
         this.http.request<T>({
@@ -122,9 +133,11 @@ export class PaymentClientService {
             : {},
         }),
       );
+      trace({ status: response.status });
       return response.data;
     } catch (err) {
       if (err instanceof AxiosError && err.response) {
+        trace({ status: err.response.status });
         if (err.response.status === 404) throw err;
         const detail =
           (err.response.data as { message?: string | string[] })?.message ??
@@ -136,6 +149,7 @@ export class PaymentClientService {
       }
       const message =
         err instanceof Error && err.message ? err.message : String(err);
+      trace({ unreachable: true, error: message });
       this.logger.error(
         `payment service unreachable (${method} ${path}): ${message}`,
       );
diff --git a/apps/edr-freight-api/src/modules/payment/payment.service.ts b/apps/edr-freight-api/src/modules/payment/payment.service.ts
index 316f3e8fe..4d27c8c77 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.service.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.service.ts
@@ -7,6 +7,7 @@ import {
   Logger,
   NotFoundException,
 } from "@nestjs/common";
+import { logCtx } from "@edr/api-common";
 import { applyBookingRefDirectionScope } from "../user-trade-access/trade-scope.util";
 import { PaymentEntity } from "./entities/payment.entity";
 import { PaymentRepository } from "./payment.repository";
@@ -214,8 +215,16 @@ export class PaymentService {
         PaymentReferenceType.SHIPMENT,
         referenceId,
       );
+      logCtx(
+        { referenceId, paid: result.paid, unverifiable: result.unverifiable },
+        { path: "payment.reconcile" },
+      );
       return { paid: result.paid, unverifiable: result.unverifiable };
     } catch (err) {
+      logCtx(
+        { referenceId, unverifiable: true, error: (err as Error).message },
+        { path: "payment.reconcile" },
+      );
       this.logger.warn(
         `Reconcile for shipment ${referenceId} failed: ${(err as Error).message}`,
       );
@@ -224,6 +233,18 @@ export class PaymentService {
   }
 
   async initiate(input: InitiateIntentInput): Promise<InitiateIntentResult> {
+    logCtx(
+      {
+        referenceId: input.referenceId,
+        source: input.source,
+        orderRef: input.orderRef,
+        method: input.method,
+        amountMinor: input.amountMinor,
+        currency: input.currency,
+        platform: input.platform,
+      },
+      { path: "payment.initiate" },
+    );
     try {
       const isCbeBill = input.method === ProviderMethod.CBE_BILL;
       // CBE settles ETB only (docs/cbe/CBE_IMPLEMENTATION_PLAN.md D8).
@@ -268,6 +289,17 @@ export class PaymentService {
 
       const intent = await this.upsertIntent(input, snapshot);
 
+      logCtx(
+        {
+          intentId: intent.id,
+          providerStatus: snapshot.status,
+          providerTxnId: snapshot.providerTxnId,
+          merchantOrderId: snapshot.merchantOrderId,
+          immediateSuccess,
+        },
+        { path: "payment.initiate" },
+      );
+
       if (immediateSuccess) {
         // Settle the projection but DO NOT notify billing — billing settles
         // inline once it has stored intentId on the invoice (see payInvoice),
@@ -428,6 +460,17 @@ export class PaymentService {
       otp,
     );
 
+    logCtx(
+      {
+        intentId: local.id,
+        refId: local.refId,
+        gatewayIntentId: snapshot.intentId,
+        providerStatus: confirmed.status,
+        failureCode: confirmed.failureCode,
+      },
+      { path: "payment.confirmOtp" },
+    );
+
     if (confirmed.status === ProviderPaymentStatus.SUCCEEDED) {
       await this.markIntentSucceeded(local.id, {
         providerTxnId: confirmed.providerTxnId,
@@ -460,6 +503,16 @@ export class PaymentService {
   ): Promise<{ alreadyFinalized: boolean }> {
     const intent = await this.paymentRepo.findOneBy({ id: intentId });
     if (!intent) throw new NotFoundException("PaymentIntent not found");
+    logCtx(
+      {
+        intentId,
+        refId: intent.refId,
+        priorStatus: intent.status,
+        providerTxnId: opts.providerTxnId,
+        notifyBilling: opts.notify !== false,
+      },
+      { path: "payment.settle" },
+    );
     if (intent.status === "success") {
       // Still notify billing: a prior delivery may have flipped the intent to
       // success and then died before the invoice settled (the two steps are not
@@ -471,6 +524,7 @@ export class PaymentService {
           opts.paidAt ?? intent.paidAt ?? undefined,
         );
       }
+      logCtx(true, { path: "payment.settle.alreadyFinalized", mode: "set" });
       return { alreadyFinalized: true };
     }
 
@@ -507,6 +561,15 @@ export class PaymentService {
     referenceId: string,
   ): Promise<{ acknowledged: boolean }> {
     const intent = await this.paymentRepo.findOneBy({ refId: referenceId });
+    logCtx(
+      {
+        referenceId,
+        intentId: intent?.id,
+        intentStatus: intent?.status ?? "none",
+        method: intent?.method,
+      },
+      { path: "payment.successRedirect" },
+    );
     if (!intent || intent.method === "cbe-bill") {
       return { acknowledged: false };
     }
@@ -533,6 +596,16 @@ export class PaymentService {
   }): Promise<void> {
     const intent = await this.paymentRepo.findOneBy({ id: input.intentId });
     if (!intent) throw new NotFoundException("PaymentIntent not found");
+    logCtx(
+      {
+        intentId: intent.id,
+        refId: intent.refId,
+        priorStatus: intent.status,
+        failureCode: input.failureCode,
+        failureMessage: input.failureMessage,
+      },
+      { path: "payment.failed" },
+    );
     if (intent.status === "success" || intent.status === "canceled") return;
 
     await this.paymentRepo.update(
diff --git a/packages/api-common/src/logging/request-log.middleware.ts b/packages/api-common/src/logging/request-log.middleware.ts
index a8067bf02..b25463161 100644
--- a/packages/api-common/src/logging/request-log.middleware.ts
+++ b/packages/api-common/src/logging/request-log.middleware.ts
@@ -59,7 +59,6 @@ const userId = (req: LoggedRequest): string | undefined => {
 @Injectable()
 export class RequestLogMiddleware implements NestMiddleware {
   private readonly logger = new Logger("HTTP");
-  private readonly canonical = new Logger("request");
 
   use(req: LoggedRequest, res: LoggedResponse, next: () => void): void {
     const start = Date.now();
@@ -90,6 +89,12 @@ export class RequestLogMiddleware implements NestMiddleware {
 
         const line = {
           ...ctx,
+          // Fields the Nest console prefix used to carry. They are IN the JSON
+          // now because this line is written raw (see below) — a log shipper
+          // needs level and time as parsable fields, not as console decoration.
+          time: new Date().toISOString(),
+          level: status >= 500 ? "error" : status >= 400 ? "warn" : "info",
+          logger: "request",
           type: "http_request",
           requestId,
           method: req.method,
@@ -113,6 +118,9 @@ export class RequestLogMiddleware implements NestMiddleware {
           json = JSON.stringify(line);
         } catch {
           json = JSON.stringify({
+            time: line.time,
+            level: line.level,
+            logger: "request",
             type: "http_request",
             requestId,
             method: req.method,
@@ -123,9 +131,11 @@ export class RequestLogMiddleware implements NestMiddleware {
           });
         }
 
-        if (status >= 500) this.canonical.error(json);
-        else if (status >= 400) this.canonical.warn(json);
-        else this.canonical.log(json);
+        // Written raw, NOT through Nest's Logger: the console logger wraps every
+        // message in "[Nest] pid - date LEVEL [ctx] …", which makes the line
+        // un-parsable as JSON. Same destination the Nest logger writes to
+        // (stdout, stderr for errors) — only the decoration is dropped.
+        (status >= 500 ? process.stderr : process.stdout).write(`${json}\n`);
       };
 
       res.on("finish", emit);
diff --git a/packages/api-common/src/repositories/base.repository.ts b/packages/api-common/src/repositories/base.repository.ts
index 6374d84a7..c0cc7073b 100644
--- a/packages/api-common/src/repositories/base.repository.ts
+++ b/packages/api-common/src/repositories/base.repository.ts
@@ -7,9 +7,16 @@ import {
   Repository,
 } from "typeorm";
 
+import { logCtx } from "../logging/request-context";
+
 export abstract class BaseRepository<T extends ObjectLiteral> {
   protected constructor(protected readonly repository: Repository<T>) {}
 
+  /** Table name, for the write trail on the canonical request log line. */
+  private get table(): string {
+    return this.repository.metadata.tableName;
+  }
+
   /** Find a single entity by its primary key. */
   async findById(
     id: string,
@@ -34,22 +41,43 @@ export abstract class BaseRepository<T extends ObjectLiteral> {
   /** Create and persist a new entity. */
   async create(data: DeepPartial<T>): Promise<T> {
     const entity = this.repository.create(data);
-    return this.repository.save(entity);
+    const saved = await this.repository.save(entity);
+    logCtx(1, { path: `db.created.${this.table}`, mode: "count" });
+    return saved;
   }
 
-  /** Patch an entity in place and return the reloaded row. */
+  /**
+   * Patch an entity in place and return the reloaded row.
+   *
+   * Every domain status machine in this app (booking, contract, wagon,
+   * warehouse, transfer request…) lands here, so this is the one place that can
+   * record "what state did this request actually move" without every service
+   * remembering to log it.
+   */
   async update(id: string, data: DeepPartial<T>): Promise<T | null> {
     await this.repository.update(id, data as never);
+    logCtx(1, { path: `db.updated.${this.table}`, mode: "count" });
+    if (data && typeof data === "object" && "status" in data) {
+      logCtx(
+        { entity: this.table, id, status: (data as { status: unknown }).status },
+        { path: "statusChanges", mode: "push" },
+      );
+    }
     return this.findById(id);
   }
 
   /** Soft-delete an entity by primary key (sets deleted_at). */
   async softDelete(id: string): Promise<void> {
     await this.repository.softDelete(id);
+    logCtx({ entity: this.table, id }, { path: "deleted", mode: "push" });
   }
 
   /** Permanently delete an entity. Avoid in domain code; prefer softDelete. */
   async hardDelete(id: string): Promise<void> {
     await this.repository.delete(id);
+    logCtx(
+      { entity: this.table, id, hard: true },
+      { path: "deleted", mode: "push" },
+    );
   }
 }

From 068ee49a9f39b682bd669d702cf1a5b18b040d42 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 12 Aug 2026 09:33:21 +0000
Subject: [PATCH 045/174] style: invoice

---
 .../src/components/customers/PersonCard.tsx   | 112 +++
 .../src/components/customers/index.ts         |   5 +
 .../pages/customers/CustomerDetailPage.tsx    | 830 +++++++++---------
 3 files changed, 528 insertions(+), 419 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/customers/PersonCard.tsx

diff --git a/apps/edr-freight-web/backoffice/src/components/customers/PersonCard.tsx b/apps/edr-freight-web/backoffice/src/components/customers/PersonCard.tsx
new file mode 100644
index 000000000..b4a201fd1
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/customers/PersonCard.tsx
@@ -0,0 +1,112 @@
+import { Badge, Card, Divider, Group, Stack, Text } from "@mantine/core";
+import type { ReactNode } from "react";
+
+export interface PersonField {
+  label: string;
+  value?: string | null;
+}
+
+export interface PersonCardProps {
+  /** OWNER / POA / CONTACT PERSON — the person's role, not their name. */
+  title: string;
+  icon?: ReactNode;
+  /**
+   * Identity state. `undefined` = this person has no identity check at all
+   * (contact person), so no badge is rendered rather than a misleading "not
+   * verified" one.
+   */
+  verified?: boolean;
+  /** Extra pills after the verification badge (e.g. "Verifies for this company"). */
+  badges?: ReactNode;
+  /** Rendered between the header and the fields — alerts, match warnings. */
+  notice?: ReactNode;
+  fields: PersonField[];
+  /** Shown when the API returned nothing for every field. */
+  emptyMessage: string;
+  /** Attachments or anything else that belongs to this person. */
+  children?: ReactNode;
+}
+
+/**
+ * One person in the customer's people column: owner, power of attorney, contact
+ * person. Empty fields are dropped rather than rendered as "—", so a field the
+ * API stops sending simply disappears instead of leaving a dead row behind.
+ */
+export function PersonCard({
+  title,
+  icon,
+  verified,
+  badges,
+  notice,
+  fields,
+  emptyMessage,
+  children,
+}: PersonCardProps) {
+  const filled = fields.filter(
+    (f) => f.value != null && String(f.value).trim(),
+  );
+
+  return (
+    <Card>
+      <Stack gap="sm">
+        <Group gap={8} wrap="wrap">
+          {icon}
+          <Text
+            size="xs"
+            fw={700}
+            c="edr-muted"
+            tt="uppercase"
+            style={{ letterSpacing: "0.06em" }}
+          >
+            {title}
+          </Text>
+          {verified !== undefined &&
+            (verified ? (
+              <Badge size="xs" color="edr-green" variant="light">
+                Fayda verified
+              </Badge>
+            ) : (
+              <Badge size="xs" color="gray" variant="light">
+                Not verified
+              </Badge>
+            ))}
+          {badges}
+        </Group>
+
+        {notice}
+
+        {filled.length > 0 ? (
+          <Stack gap="xs">
+            {filled.map((f) => (
+              <Stack key={f.label} gap={0}>
+                <Text size="xs" c="edr-muted">
+                  {f.label}
+                </Text>
+                <Text
+                  size="sm"
+                  c="edr-text"
+                  style={{ wordBreak: "break-word" }}
+                >
+                  {f.value}
+                </Text>
+              </Stack>
+            ))}
+          </Stack>
+        ) : (
+          <Text size="sm" c="dimmed">
+            {emptyMessage}
+          </Text>
+        )}
+
+        {children && (
+          <>
+            <Divider />
+            {children}
+          </>
+        )}
+      </Stack>
+    </Card>
+  );
+}
+
+export default PersonCard;
diff --git a/apps/edr-freight-web/backoffice/src/components/customers/index.ts b/apps/edr-freight-web/backoffice/src/components/customers/index.ts
index 81f25fcb2..daeb11311 100644
--- a/apps/edr-freight-web/backoffice/src/components/customers/index.ts
+++ b/apps/edr-freight-web/backoffice/src/components/customers/index.ts
@@ -24,4 +24,9 @@ export {
   type ResetPasswordActionProps,
 } from "./ResetPasswordAction";
 export { formatBytes, formatDate, formatMoney, humanize } from "./format";
+export {
+  PersonCard,
+  type PersonCardProps,
+  type PersonField,
+} from "./PersonCard";
 export { TableCard, type TableCardProps } from "./TableCard";
diff --git a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
index a6367786a..73f6a618b 100644
--- a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
@@ -8,7 +8,7 @@ import {
   Card,
   Center,
   Container,
-  Divider,
+  Grid,
   Group,
   Loader,
   SimpleGrid,
@@ -21,6 +21,7 @@ import {
   ArrowLeft,
   ArrowRight,
   Banknote,
+  Contact,
   Download,
   Eye,
   FileText,
@@ -32,6 +33,8 @@ import {
   FilePen,
   Paperclip,
   Receipt,
+  UserCheck,
+  UserRound,
 } from "lucide-react";
 import { useQuery } from "@tanstack/react-query";
 import { useMemo, useState } from "react";
@@ -46,6 +49,7 @@ import {
   CompanyTypeBadge,
   InvoiceStatusBadge,
   PaymentStatusBadge,
+  PersonCard,
   ProfileApprovalActions,
   ProfileChips,
   ProfileStatusBadge,
@@ -259,7 +263,9 @@ export default function CustomerDetailPage() {
                     variant="subtle"
                     color="gray"
                     aria-label={`View ${f.name}`}
-                    onClick={() => void fetchViewableFile(f.id, f.name).then(view)}
+                    onClick={() =>
+                      void fetchViewableFile(f.id, f.name).then(view)
+                    }
                   >
                     <Eye size={14} />
                   </ActionIcon>
@@ -268,7 +274,9 @@ export default function CustomerDetailPage() {
                     type="button"
                     size="xs"
                     lineClamp={1}
-                    onClick={() => void fetchViewableFile(f.id, f.name).then(view)}
+                    onClick={() =>
+                      void fetchViewableFile(f.id, f.name).then(view)
+                    }
                     style={{
                       maxWidth: 170,
                       textAlign: "left",
@@ -615,7 +623,10 @@ export default function CustomerDetailPage() {
     [],
   );
 
-  const licenseProfiles = (company?.companyProfiles ?? []).filter(
+  /** Never read `company.companyProfiles` directly — an endpoint that stops
+   *  loading the relation would otherwise crash the whole page. */
+  const profiles = company?.companyProfiles ?? [];
+  const licenseProfiles = profiles.filter(
     (p) => p.licenseFiles && p.licenseFiles.length > 0,
   );
 
@@ -629,14 +640,13 @@ export default function CustomerDetailPage() {
     [documents],
   );
   const poaLive = poaDocuments.filter((d) => d.code === POA_DELEGATION_CODE);
-  const poaFields = [
-    { label: "PoA name", value: company?.poaName },
-    { label: "PoA email", value: company?.poaEmail },
-    { label: "PoA phone", value: company?.poaPhone },
-    { label: "PoA location", value: company?.poaLocation },
-    { label: "PoA address", value: company?.poaAddress },
-  ];
-  const hasPoaDetails = poaFields.some((f) => f.value?.trim());
+  const hasPoaDetails = [
+    company?.poaName,
+    company?.poaEmail,
+    company?.poaPhone,
+    company?.poaLocation,
+    company?.poaAddress,
+  ].some((v) => v?.trim());
   // Shared with the portal (buildCompanyIdentityState) — same derivation, so
   // this page can never disagree with the rule the API actually enforces.
   const identityState = company?.identity;
@@ -645,9 +655,7 @@ export default function CustomerDetailPage() {
   const hasEtradeRecord = Boolean(company?.licenceNumber?.trim());
   // A freight forwarder acts on other companies' behalf, so its PoA — details
   // and DARS delegation paper both — is mandatory rather than optional.
-  const poaMandatory = (company?.companyProfiles ?? []).some(
-    (p) => p.type === "freight_forwarder",
-  );
+  const poaMandatory = profiles.some((p) => p.type === "freight_forwarder");
   const delegationMissing =
     company?.identity?.poaDeclared === "yes" && poaLive.length === 0;
 
@@ -685,8 +693,9 @@ export default function CustomerDetailPage() {
         ]}
         backTo="/dashboard/customers"
         title={company.name}
-        subtitle={`TIN ${company.tin}${company.country ? ` · ${company.country}` : ""
-          }`}
+        subtitle={`TIN ${company.tin}${
+          company.country ? ` · ${company.country}` : ""
+        }`}
         meta={
           <Group gap="xs" wrap="nowrap">
             <CompanyTypeBadge type={company.type} />
@@ -749,7 +758,7 @@ export default function CustomerDetailPage() {
               items={[
                 {
                   label: "Profiles",
-                  value: company.companyProfiles.length,
+                  value: profiles.length,
                   icon: IdCard,
                   color: "edr-green",
                 },
@@ -761,9 +770,7 @@ export default function CustomerDetailPage() {
                     : "Pending approval",
                   value: stillOnboarding
                     ? "—"
-                    : company.companyProfiles.filter(
-                        (p) => p.status === "pending",
-                      ).length,
+                    : profiles.filter((p) => p.status === "pending").length,
                   icon: IdCard,
                   color: "yellow",
                 },
@@ -782,407 +789,392 @@ export default function CustomerDetailPage() {
               ]}
             />
 
-            <Card>
-              <Stack gap="lg">
-                <Text fw={600} c="edr-text">
-                  Company information
-                </Text>
-                <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="lg">
-                  <InfoField label="TIN" value={company.tin} />
-                  <InfoField label="VAT number" value={company.vatNumber} />
-                  <InfoField label="FAN number" value={company.fanNumber} />
-                  <InfoField
-                    label="Submitted on"
-                    value={formatDate(company.createdAt)}
-                  />
-                  <InfoField
-                    label="Approved on"
-                    value={
-                      company.approvedAt
-                        ? formatDate(company.approvedAt)
-                        : "Not yet approved"
-                    }
-                  />
-                  <InfoField
-                    label="Owner identity"
-                    value={
-                      ownerIdentity?.verified
-                        ? "Fayda verified"
-                        : ownerIdentity?.passportNumber
-                          ? `Passport ${ownerIdentity.passportNumber}`
-                          : "Not verified"
-                    }
-                  />
-                  <InfoField label="Country" value={company.country} />
-                  <InfoField
-                    label="Nationality"
-                    value={
-                      company.nationality
-                        ? humanize(company.nationality)
-                        : undefined
-                    }
-                  />
-                  {/* Why this company's registration was typed rather than
-                      fetched, and why it carries no business licence. */}
-                  <InfoField
-                    label="Registration"
-                    value={
-                      company.cooperative
-                        ? "Co-operative union / farm (no trade licence)"
-                        : "eTrade trade licence"
-                    }
-                  />
-                  <InfoField label="Address" value={company.address} />
-                  <InfoField label="Website" value={company.website} />
-                  <InfoField label="Email" value={company.email} />
-                  <InfoField label="Phone" value={company.phone} />
-                  <Box />
-                  <InfoField
-                    label="Contact person"
-                    value={company.contactPersonName}
-                  />
-                  <InfoField
-                    label="Contact phone"
-                    value={company.contactPersonPhone}
-                  />
-                  <Box />
-                  <InfoField label="Owner" value={company.ownerName} />
-                  <InfoField label="Owner email" value={company.ownerEmail} />
-                  <InfoField label="Owner phone" value={company.ownerPhone} />
-                </SimpleGrid>
-              </Stack>
-            </Card>
-
-            <Card>
-              <Stack gap="lg">
-                <Group gap="xs" wrap="nowrap" justify="space-between">
-                  <Group gap="xs" wrap="nowrap">
-                    <Text fw={600} c="edr-text">
-                      eTrade registration
-                    </Text>
-                    {hasEtradeRecord ? (
-                      <Badge size="sm" color="edr-green" variant="light">
-                        Verified with eTrade
-                      </Badge>
-                    ) : (
-                      <Badge size="sm" color="gray" variant="light">
-                        No eTrade record
-                      </Badge>
-                    )}
-                  </Group>
-                  {hasEtradeRecord && (
-                    <ActionIcon
-                      variant="default"
-                      aria-label="Download TIN record"
-                      onClick={() => downloadTinRecord(company)}
-                    >
-                      <Download size={16} />
-                    </ActionIcon>
-                  )}
-                </Group>
-                {hasEtradeRecord ? (
-                  <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="lg">
-                    <InfoField
-                      label="License number"
-                      value={company.licenceNumber}
-                    />
-                    <InfoField label="Status" value={company.statusDescription} />
-                    <InfoField
-                      label="Date registered"
-                      value={company.dateRegistered}
-                    />
-                    <InfoField label="Renewed from" value={company.renewedFrom} />
-                    <InfoField label="Renewal date" value={company.renewalDate} />
-                    <InfoField label="Renewed to" value={company.renewedTo} />
-                    <InfoField label="Region" value={company.region} />
-                    <InfoField label="Zone" value={company.zone} />
-                    <InfoField label="Woreda" value={company.woreda} />
-                    <InfoField label="Kebele" value={company.kebele} />
-                    <InfoField label="House No" value={company.houseNo} />
-                  </SimpleGrid>
-                ) : (
-                  <Text size="sm" c="dimmed">
-                    No eTrade registration record on file for this customer's
-                    TIN.
-                  </Text>
-                )}
-              </Stack>
-            </Card>
-
-            <Card>
-              <Stack gap="lg">
-                <Group gap="xs" wrap="nowrap">
-                  <Text fw={600} c="edr-text">
-                    Owner identity
-                  </Text>
-                  {identityState?.subject === "owner" && (
-                    <Badge size="sm" color="blue" variant="light">
-                      Verifies for this company
-                    </Badge>
-                  )}
-                  {ownerIdentity?.verified ? (
-                    <Badge size="sm" color="edr-green" variant="light">
-                      Fayda verified
-                    </Badge>
-                  ) : (
-                    <Badge size="sm" color="gray" variant="light">
-                      Not verified
-                    </Badge>
-                  )}
-                </Group>
-
-                {/* THE check: is the owner the company put forward the person
-                    the eTrade licence actually names? Advisory — eTrade and
-                    Fayda transliterate Amharic names differently, so this is a
-                    prompt to look, not a verdict. */}
-                {identityState?.ownerMatchesEtrade === false ? (
-                  <Alert
-                    color="amber"
-                    variant="light"
-                    icon={<AlertTriangle size={16} />}
-                    title="Does not match the eTrade licence"
-                  >
-                    The licence names{" "}
-                    <strong>{identityState.etradeManagerName}</strong>, but this
-                    company recorded <strong>{company.ownerName}</strong>.
-                  </Alert>
-                ) : identityState?.ownerMatchesEtrade === true ? (
-                  <Badge
-                    size="sm"
-                    color="edr-green"
-                    variant="light"
-                    style={{ alignSelf: "flex-start" }}
-                  >
-                    Matches the eTrade licence
-                  </Badge>
-                ) : company.cooperative ? (
-                  <Text size="xs" c="dimmed">
-                    A co-operative union or farm holds no trade licence, so
-                    there is no eTrade record to check the owner against.
-                  </Text>
-                ) : (
-                  <Text size="xs" c="dimmed">
-                    No eTrade manager name on file to compare against.
-                  </Text>
-                )}
-                {ownerIdentity?.verified ? (
-                  <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="lg">
-                    <InfoField label="Name" value={ownerIdentity.name} />
-                    <InfoField label="Phone" value={ownerIdentity.phone} />
-                    <InfoField label="Email" value={ownerIdentity.email} />
-                    <InfoField label="Address" value={ownerIdentity.address} />
-                    <InfoField
-                      label="Verified at"
-                      value={formatDate(ownerIdentity.verifiedAt)}
-                    />
-                    <InfoField
-                      label="Birthdate"
-                      value={ownerIdentity.birthdate}
-                    />
-                    <InfoField label="Gender" value={ownerIdentity.gender} />
-                    <InfoField
-                      label="Passport number"
-                      value={ownerIdentity.passportNumber}
-                    />
-                  </SimpleGrid>
-                ) : (
-                  <Text size="sm" c="dimmed">
-                    {ownerIdentity?.passportNumber
-                      ? `Not Fayda verified — identified by passport ${ownerIdentity.passportNumber}.`
-                      : "The company owner has not verified their identity with Fayda."}
-                  </Text>
-                )}
-              </Stack>
-            </Card>
-
-            <Card>
-              <Stack gap="lg">
-                <Group justify="space-between" wrap="nowrap">
-                  <Group gap="xs" wrap="nowrap">
-                    <Text fw={600} c="edr-text">
-                      Power of Attorney
-                    </Text>
-                    {poaMandatory && (
-                      <Badge size="xs" color="blue" variant="light">
-                        Required for freight forwarder
-                      </Badge>
-                    )}
-                  </Group>
-                  {delegationMissing ? (
-                    <Badge size="sm" color="red" variant="light">
-                      DARS delegation paper missing
-                    </Badge>
-                  ) : poaLive.length > 0 ? (
-                    <Badge size="sm" color="edr-green" variant="light">
-                      DARS delegation paper on file
-                    </Badge>
-                  ) : (
-                    <Badge size="sm" color="gray" variant="light">
-                      Not provided
-                    </Badge>
-                  )}
-                </Group>
-
-                {hasPoaDetails ? (
-                  <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="lg">
-                    {poaFields.map((f) => (
-                      <InfoField
-                        key={f.label}
-                        label={f.label}
-                        value={f.value}
-                      />
-                    ))}
-                    <InfoField
-                      label="PoA Fayda"
-                      value={
-                        poaIdentity?.verified ? "Verified" : "Not verified"
-                      }
-                    />
-                    {poaIdentity?.verified && (
-                      <>
+            <Grid gap="lg" align="flex-start">
+              {/* Company facts — the wide column. People live in the narrow one
+                  beside it, so nothing about a person is stated twice. */}
+              <Grid.Col span={{ base: 12, lg: 8 }}>
+                <Stack gap="lg">
+                  <Card>
+                    <Stack gap="lg">
+                      <Text fw={600} c="edr-text">
+                        Company information
+                      </Text>
+                      <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="lg">
+                        <InfoField label="TIN" value={company.tin} />
                         <InfoField
-                          label="PoA verified at"
-                          value={formatDate(poaIdentity.verifiedAt)}
+                          label="VAT number"
+                          value={company.vatNumber}
+                        />
+                        <InfoField label="Country" value={company.country} />
+                        <InfoField
+                          label="Nationality"
+                          value={
+                            company.nationality
+                              ? humanize(company.nationality)
+                              : undefined
+                          }
+                        />
+                        {/* Why this company's registration was typed rather
+                            than fetched, and why it carries no licence. */}
+                        <InfoField
+                          label="Registration"
+                          value={
+                            company.cooperative
+                              ? "Co-operative union / farm (no trade licence)"
+                              : "eTrade trade licence"
+                          }
+                        />
+                        <InfoField label="Address" value={company.address} />
+                        <InfoField label="Email" value={company.email} />
+                        <InfoField label="Phone" value={company.phone} />
+                        <InfoField label="Website" value={company.website} />
+                        <InfoField
+                          label="Submitted on"
+                          value={formatDate(company.createdAt)}
                         />
                         <InfoField
-                          label="PoA birthdate"
-                          value={poaIdentity.birthdate}
+                          label="Approved on"
+                          value={
+                            company.approvedAt
+                              ? formatDate(company.approvedAt)
+                              : "Not yet approved"
+                          }
                         />
-                        <InfoField label="PoA gender" value={poaIdentity.gender} />
-                      </>
-                    )}
-                  </SimpleGrid>
-                ) : (
-                  <Text size="sm" c="dimmed">
-                    No Power of Attorney representative recorded for this
-                    customer.
-                  </Text>
-                )}
+                      </SimpleGrid>
+                    </Stack>
+                  </Card>
 
-                <Divider />
-
-                <Stack gap="sm">
-                  <Text
-                    size="xs"
-                    fw={600}
-                    c="edr-muted"
-                    tt="uppercase"
-                    style={{ letterSpacing: "0.04em" }}
-                  >
-                    DARS delegation paper
-                  </Text>
-
-                  {documentsQuery.isLoading ? (
-                    <Group gap="xs">
-                      <Loader size="xs" />
-                      <Text size="sm" c="dimmed">
-                        Loading documents…
-                      </Text>
-                    </Group>
-                  ) : documentsQuery.isError ? (
-                    <Group gap="sm">
-                      <Text size="sm" c="red">
-                        Failed to load documents.
-                      </Text>
-                      <Anchor
-                        component="button"
-                        type="button"
-                        size="xs"
-                        onClick={() => void documentsQuery.refetch()}
-                      >
-                        Retry
-                      </Anchor>
-                    </Group>
-                  ) : poaDocuments.length === 0 ? (
-                    <Text size="sm" c="dimmed">
-                      No DARS delegation paper uploaded.
-                    </Text>
-                  ) : (
-                    poaDocuments.map((doc) => (
-                      <Group key={doc.id} justify="space-between" wrap="nowrap">
-                        <Group gap="sm" wrap="nowrap" style={{ minWidth: 0 }}>
-                          <Paperclip
-                            size={14}
-                            className="shrink-0 text-edr-muted"
-                          />
-                          <Anchor
-                            component="button"
-                            type="button"
-                            size="sm"
-                            lineClamp={1}
-                            onClick={() =>
-                              void fetchViewableFile(doc.id, doc.name).then(view)
-                            }
-                          >
-                            {doc.name}
-                          </Anchor>
-                          <Text size="xs" c="dimmed" className="shrink-0">
-                            {formatBytes(doc.size)} ·{" "}
-                            {formatDate(doc.uploadedAt)}
+                  <Card>
+                    <Stack gap="lg">
+                      <Group gap="xs" wrap="nowrap" justify="space-between">
+                        <Group gap="xs" wrap="nowrap">
+                          <Text fw={600} c="edr-text">
+                            eTrade registration
                           </Text>
-                          {doc.code === POA_DELEGATION_PENDING_CODE && (
-                            <Badge
-                              size="xs"
-                              color="yellow"
-                              variant="light"
-                              className="shrink-0"
-                            >
-                              Pending approval
+                          {hasEtradeRecord ? (
+                            <Badge size="sm" color="edr-green" variant="light">
+                              Verified with eTrade
+                            </Badge>
+                          ) : (
+                            <Badge size="sm" color="gray" variant="light">
+                              No eTrade record
                             </Badge>
                           )}
                         </Group>
-                        <Group gap={4} wrap="nowrap">
+                        {hasEtradeRecord && (
                           <ActionIcon
-                            variant="subtle"
-                            color="gray"
-                            aria-label={`Preview ${doc.name}`}
-                            onClick={() =>
-                              void fetchViewableFile(doc.id, doc.name).then(view)
-                            }
-                          >
-                            <Eye size={16} />
-                          </ActionIcon>
-                          <ActionIcon
-                            component="button"
-                            type="button"
-                            onClick={() =>
-                              void downloadBookingFile(doc.id, doc.name)
-                            }
-                            variant="subtle"
-                            color="gray"
-                            aria-label={`Download ${doc.name}`}
+                            variant="default"
+                            aria-label="Download TIN record"
+                            onClick={() => downloadTinRecord(company)}
                           >
                             <Download size={16} />
                           </ActionIcon>
-                        </Group>
+                        )}
                       </Group>
-                    ))
-                  )}
-                </Stack>
-              </Stack>
-            </Card>
+                      {hasEtradeRecord ? (
+                        <SimpleGrid
+                          cols={{ base: 1, sm: 2, lg: 3 }}
+                          spacing="lg"
+                        >
+                          <InfoField
+                            label="License number"
+                            value={company.licenceNumber}
+                          />
+                          <InfoField
+                            label="Status"
+                            value={company.statusDescription}
+                          />
+                          <InfoField
+                            label="Date registered"
+                            value={company.dateRegistered}
+                          />
+                          <InfoField
+                            label="Renewed from"
+                            value={company.renewedFrom}
+                          />
+                          <InfoField
+                            label="Renewal date"
+                            value={company.renewalDate}
+                          />
+                          <InfoField
+                            label="Renewed to"
+                            value={company.renewedTo}
+                          />
+                          <InfoField label="Region" value={company.region} />
+                          <InfoField label="Zone" value={company.zone} />
+                          <InfoField label="Woreda" value={company.woreda} />
+                          <InfoField label="Kebele" value={company.kebele} />
+                          <InfoField label="House No" value={company.houseNo} />
+                        </SimpleGrid>
+                      ) : (
+                        <Text size="sm" c="dimmed">
+                          No eTrade registration record on file for this
+                          customer's TIN.
+                        </Text>
+                      )}
+                    </Stack>
+                  </Card>
 
-            <Card>
-              <Stack gap="md">
-                <Group justify="space-between">
-                  <Text fw={600} c="edr-text">
-                    Role profiles
-                  </Text>
-                  <ProfileChips profiles={company.companyProfiles} />
-                </Group>
-                <Box style={{ overflowX: "auto" }} w="100%">
-                  <Box miw={1040}>
-                    <DataTable
-                      columns={profileColumns}
-                      data={company.companyProfiles}
-                      status="success"
-                      emptyMessage="No profiles registered."
-                      containerClassName="border-0 shadow-none bg-transparent"
-                    />
-                  </Box>
-                </Box>
-              </Stack>
-            </Card>
+                  <Card>
+                    <Stack gap="md">
+                      <Group justify="space-between">
+                        <Text fw={600} c="edr-text">
+                          Role profiles
+                        </Text>
+                        <ProfileChips profiles={profiles} />
+                      </Group>
+                      {/* Narrower than the old full-width layout — the table
+                          shares the row with the people column now. */}
+                      <Box style={{ overflowX: "auto" }} w="100%">
+                        <Box miw={760}>
+                          <DataTable
+                            columns={profileColumns}
+                            data={profiles}
+                            status="success"
+                            emptyMessage="No profiles registered."
+                            containerClassName="border-0 shadow-none bg-transparent"
+                          />
+                        </Box>
+                      </Box>
+                    </Stack>
+                  </Card>
+                </Stack>
+              </Grid.Col>
+
+              {/* People: owner, then power of attorney, then contact person —
+                  the order a reviewer checks them in. */}
+              <Grid.Col span={{ base: 12, lg: 4 }}>
+                <Stack gap="md">
+                  <PersonCard
+                    title="Owner"
+                    icon={<UserRound size={15} className="text-edr-muted" />}
+                    verified={Boolean(ownerIdentity?.verified)}
+                    badges={
+                      <>
+                        {identityState?.subject === "owner" && (
+                          <Badge size="xs" color="blue" variant="light">
+                            Verifies for this company
+                          </Badge>
+                        )}
+                        {identityState?.ownerMatchesEtrade === true && (
+                          <Badge size="xs" color="edr-green" variant="light">
+                            Matches eTrade licence
+                          </Badge>
+                        )}
+                      </>
+                    }
+                    notice={
+                      /* THE check: is the owner the company put forward the
+                         person the eTrade licence actually names? Advisory —
+                         eTrade and Fayda transliterate Amharic names
+                         differently, so this is a prompt to look, not a
+                         verdict. */
+                      identityState?.ownerMatchesEtrade === false ? (
+                        <Alert
+                          color="amber"
+                          variant="light"
+                          p="xs"
+                          icon={<AlertTriangle size={16} />}
+                          title="Does not match the eTrade licence"
+                        >
+                          <Text size="xs">
+                            The licence names{" "}
+                            <strong>{identityState.etradeManagerName}</strong>,
+                            but this company recorded{" "}
+                            <strong>{company.ownerName ?? "nobody"}</strong>.
+                          </Text>
+                        </Alert>
+                      ) : !ownerIdentity?.verified &&
+                        ownerIdentity?.passportNumber ? (
+                        <Text size="xs" c="dimmed">
+                          Identified by passport rather than Fayda.
+                        </Text>
+                      ) : null
+                    }
+                    fields={[
+                      {
+                        label: "Name",
+                        value: company.ownerName ?? ownerIdentity?.name,
+                      },
+                      {
+                        label: "Email",
+                        value: company.ownerEmail ?? ownerIdentity?.email,
+                      },
+                      {
+                        label: "Phone",
+                        value: company.ownerPhone ?? ownerIdentity?.phone,
+                      },
+                      {
+                        label: "Passport number",
+                        value: ownerIdentity?.passportNumber,
+                      },
+                      { label: "Address", value: ownerIdentity?.address },
+                      { label: "Birthdate", value: ownerIdentity?.birthdate },
+                      { label: "Gender", value: ownerIdentity?.gender },
+                      {
+                        label: "Verified on",
+                        value: ownerIdentity?.verifiedAt
+                          ? formatDate(ownerIdentity.verifiedAt)
+                          : null,
+                      },
+                    ]}
+                    emptyMessage="No owner recorded for this company."
+                  />
+
+                  <PersonCard
+                    title="Power of attorney"
+                    icon={<UserCheck size={15} className="text-edr-muted" />}
+                    verified={
+                      // No PoA at all → no badge, rather than a "not verified"
+                      // that reads as a problem where none exists.
+                      hasPoaDetails || identityState?.poaDeclared === "yes"
+                        ? Boolean(poaIdentity?.verified)
+                        : undefined
+                    }
+                    badges={
+                      <>
+                        {identityState?.subject === "poa" && (
+                          <Badge size="xs" color="blue" variant="light">
+                            Verifies for this company
+                          </Badge>
+                        )}
+                        {poaMandatory && (
+                          <Badge size="xs" color="blue" variant="light">
+                            Required for freight forwarder
+                          </Badge>
+                        )}
+                        {delegationMissing && (
+                          <Badge size="xs" color="red" variant="light">
+                            Delegation paper missing
+                          </Badge>
+                        )}
+                      </>
+                    }
+                    fields={[
+                      { label: "Name", value: company.poaName },
+                      { label: "Email", value: company.poaEmail },
+                      { label: "Phone", value: company.poaPhone },
+                      { label: "Location", value: company.poaLocation },
+                      { label: "Address", value: company.poaAddress },
+                      { label: "Birthdate", value: poaIdentity?.birthdate },
+                      { label: "Gender", value: poaIdentity?.gender },
+                      {
+                        label: "Verified on",
+                        value: poaIdentity?.verifiedAt
+                          ? formatDate(poaIdentity.verifiedAt)
+                          : null,
+                      },
+                    ]}
+                    emptyMessage="No representative recorded for this customer."
+                  >
+                    <Stack gap="xs">
+                      <Text size="xs" c="edr-muted">
+                        DARS delegation paper
+                      </Text>
+
+                      {documentsQuery.isLoading ? (
+                        <Group gap="xs">
+                          <Loader size="xs" />
+                          <Text size="sm" c="dimmed">
+                            Loading…
+                          </Text>
+                        </Group>
+                      ) : documentsQuery.isError ? (
+                        <Group gap="sm">
+                          <Text size="sm" c="red">
+                            Failed to load documents.
+                          </Text>
+                          <Anchor
+                            component="button"
+                            type="button"
+                            size="xs"
+                            onClick={() => void documentsQuery.refetch()}
+                          >
+                            Retry
+                          </Anchor>
+                        </Group>
+                      ) : poaDocuments.length === 0 ? (
+                        <Text size="sm" c="dimmed">
+                          Not uploaded.
+                        </Text>
+                      ) : (
+                        poaDocuments.map((doc) => (
+                          <Stack key={doc.id} gap={2}>
+                            <Group gap={6} wrap="nowrap">
+                              <Paperclip
+                                size={13}
+                                className="shrink-0 text-edr-muted"
+                              />
+                              <Anchor
+                                component="button"
+                                type="button"
+                                size="sm"
+                                lineClamp={1}
+                                style={{ flex: 1, textAlign: "left" }}
+                                onClick={() =>
+                                  void fetchViewableFile(doc.id, doc.name).then(
+                                    view,
+                                  )
+                                }
+                              >
+                                {doc.name}
+                              </Anchor>
+                              <ActionIcon
+                                size="sm"
+                                variant="subtle"
+                                color="gray"
+                                aria-label={`Preview ${doc.name}`}
+                                onClick={() =>
+                                  void fetchViewableFile(doc.id, doc.name).then(
+                                    view,
+                                  )
+                                }
+                              >
+                                <Eye size={15} />
+                              </ActionIcon>
+                              <ActionIcon
+                                size="sm"
+                                component="button"
+                                type="button"
+                                variant="subtle"
+                                color="gray"
+                                aria-label={`Download ${doc.name}`}
+                                onClick={() =>
+                                  void downloadBookingFile(doc.id, doc.name)
+                                }
+                              >
+                                <Download size={15} />
+                              </ActionIcon>
+                            </Group>
+                            <Group gap={6} pl={19} wrap="wrap">
+                              <Text size="xs" c="dimmed">
+                                {formatBytes(doc.size)} ·{" "}
+                                {formatDate(doc.uploadedAt)}
+                              </Text>
+                              {doc.code === POA_DELEGATION_PENDING_CODE && (
+                                <Badge size="xs" color="yellow" variant="light">
+                                  Pending approval
+                                </Badge>
+                              )}
+                            </Group>
+                          </Stack>
+                        ))
+                      )}
+                    </Stack>
+                  </PersonCard>
+
+                  <PersonCard
+                    title="Contact person"
+                    icon={<Contact size={15} className="text-edr-muted" />}
+                    fields={[
+                      { label: "Name", value: company.contactPersonName },
+                      { label: "Phone", value: company.contactPersonPhone },
+                    ]}
+                    emptyMessage="No contact person recorded."
+                  />
+                </Stack>
+              </Grid.Col>
+            </Grid>
           </Stack>
         </Tabs.Panel>
 
@@ -1198,9 +1190,9 @@ export default function CustomerDetailPage() {
               error={
                 bookingsQuery.isError
                   ? {
-                    message: "Failed to load bookings.",
-                    onRetry: () => void bookingsQuery.refetch(),
-                  }
+                      message: "Failed to load bookings.",
+                      onRetry: () => void bookingsQuery.refetch(),
+                    }
                   : undefined
               }
             />
@@ -1220,9 +1212,9 @@ export default function CustomerDetailPage() {
                 error={
                   documentsQuery.isError
                     ? {
-                      message: "Failed to load documents.",
-                      onRetry: () => void documentsQuery.refetch(),
-                    }
+                        message: "Failed to load documents.",
+                        onRetry: () => void documentsQuery.refetch(),
+                      }
                     : undefined
                 }
               />
@@ -1297,9 +1289,9 @@ export default function CustomerDetailPage() {
               error={
                 paymentsQuery.isError
                   ? {
-                    message: "Failed to load payments.",
-                    onRetry: () => void paymentsQuery.refetch(),
-                  }
+                      message: "Failed to load payments.",
+                      onRetry: () => void paymentsQuery.refetch(),
+                    }
                   : undefined
               }
             />
@@ -1320,9 +1312,9 @@ export default function CustomerDetailPage() {
                 error={
                   invoicesQuery.isError
                     ? {
-                      message: "Failed to load invoices.",
-                      onRetry: () => void invoicesQuery.refetch(),
-                    }
+                        message: "Failed to load invoices.",
+                        onRetry: () => void invoicesQuery.refetch(),
+                      }
                     : undefined
                 }
                 pagination={{

From 02a264930b4db14ffac3a1fbd37cf63addb77afc Mon Sep 17 00:00:00 2001
From: ghost2023 <nathnaelwonisha@gmail.com>
Date: Wed, 12 Aug 2026 13:04:18 +0300
Subject: [PATCH 046/174] fix: consolidate stamp settings into single company
 stamp page

---
 apps/edr-freight-web/backoffice/src/App.tsx   | 25 +++++++++++--------
 .../components/layout/sidebar-sections.tsx    | 14 +++++------
 ...sPage.tsx => CompanyStampSettingsPage.tsx} | 22 ++++++++++------
 .../backoffice/src/user-management/route.tsx  | 23 ++++++++++++++++-
 4 files changed, 57 insertions(+), 27 deletions(-)
 rename apps/edr-freight-web/backoffice/src/pages/settings/{InvoiceStampSettingsPage.tsx => CompanyStampSettingsPage.tsx} (70%)

diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index f48f302a1..83cf82909 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -51,8 +51,7 @@ import { NO_ACCESS_PATH, resolveLandingPath } from "./lib/landing";
 import NoAccessPage from "./pages/NoAccessPage";
 import FileUploadSettingsPage from "./pages/documents/FileUploadSettingsPage";
 import DropdownSettingsPage from "./pages/dropdown_settings/DropdownSettingsPage";
-import StampSettings from "./record-management/components/Settings/uploadTeeterandSingature";
-import InvoiceStampSettingsPage from "./pages/settings/InvoiceStampSettingsPage";
+import CompanyStampSettingsPage from "./pages/settings/CompanyStampSettingsPage";
 import ContractTemplatesPage from "./pages/contract_templates/ContractTemplatesPage";
 import PortalContentPage from "./pages/portal_content/PortalContentPage";
 import ContractTemplateEditorPage from "./pages/contract_templates/ContractTemplateEditorPage";
@@ -786,24 +785,28 @@ const App = () => {
             </RequirePermission>
           }
         />
+        {/*
+          The ONE company stamp, for every generated document. The per-officer
+          teeter (ማህተም) that used to sit beside it at /dashboard/stamp-settings
+          now lives at /user-management/teeter-and-signature — it is a different
+          thing (an individual's approval stamp), and pairing the two here was
+          the duplication.
+        */}
         <Route
           path="stamp-settings"
-          element={
-            <RequirePermission permission={FREIGHT_PERMS.settings.stamp.view}>
-              <StampSettings />
-            </RequirePermission>
-          }
-        />
-        <Route
-          path="invoice-stamp-settings"
           element={
             <RequirePermission
               permission={FREIGHT_PERMS.settings.invoiceStamp.view}
             >
-              <InvoiceStampSettingsPage />
+              <CompanyStampSettingsPage />
             </RequirePermission>
           }
         />
+        {/* Old URL kept alive so existing links/bookmarks do not 404. */}
+        <Route
+          path="invoice-stamp-settings"
+          element={<Navigate to="/dashboard/stamp-settings" replace />}
+        />
         <Route
           path="contract-templates"
           element={
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 777877fd6..c06b5a7e1 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -19,6 +19,7 @@ import {
   PackageOpen,
   Paperclip,
   Receipt,
+  Stamp,
   ScrollText,
   Send,
   Settings,
@@ -486,15 +487,12 @@ export const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[]
         permission: FREIGHT_PERMS.settings.dropdown.view,
       },
       {
-        label: "Stamp settings",
+        // One entry, one stamp. The former "Stamp settings" entry here pointed
+        // at the per-officer teeter (ማህተም), not a company seal — it moved to
+        // /user-management/teeter-and-signature.
+        label: "Company stamp",
         href: "/dashboard/stamp-settings",
-        icon: <FileSignature />,
-        permission: FREIGHT_PERMS.settings.stamp.view,
-      },
-      {
-        label: "Invoice stamp",
-        href: "/dashboard/invoice-stamp-settings",
-        icon: <Receipt />,
+        icon: <Stamp />,
         permission: FREIGHT_PERMS.settings.invoiceStamp.view,
       },
       {
diff --git a/apps/edr-freight-web/backoffice/src/pages/settings/InvoiceStampSettingsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/settings/CompanyStampSettingsPage.tsx
similarity index 70%
rename from apps/edr-freight-web/backoffice/src/pages/settings/InvoiceStampSettingsPage.tsx
rename to apps/edr-freight-web/backoffice/src/pages/settings/CompanyStampSettingsPage.tsx
index 407218d70..730458f2a 100644
--- a/apps/edr-freight-web/backoffice/src/pages/settings/InvoiceStampSettingsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/settings/CompanyStampSettingsPage.tsx
@@ -17,10 +17,16 @@ import {
 } from "@/hooks/useStampSettings";
 
 /**
- * The one company stamp/seal stamped onto every generated invoice/receipt
- * PDF (InvoiceDocumentService). Single global image — no per-employee choice.
+ * The ONE company stamp/seal, read by every document path server-side via
+ * StampSettingsService: invoices and receipts (InvoiceDocumentService),
+ * warehouse release + handover papers, and the EDR side of contract signature
+ * blocks. Single global image — no per-employee choice, and staff never upload
+ * one when signing.
+ *
+ * Not to be confused with the per-officer teeter (ማህተም) at
+ * /user-management/teeter-and-signature, which is genuinely per-person.
  */
-export default function InvoiceStampSettingsPage() {
+export default function CompanyStampSettingsPage() {
   const { data, isLoading } = useStampSettingsQuery();
   const setStamp = useSetStamp();
   const clearStamp = useClearStamp();
@@ -47,11 +53,13 @@ export default function InvoiceStampSettingsPage() {
     <div className="p-4 w-full max-w-screen-sm mx-auto">
       <Card className="shadow-lg border-gray-200 dark:border-gray-700">
         <CardHeader>
-          <CardTitle>Invoice stamp</CardTitle>
+          <CardTitle>Company stamp</CardTitle>
           <CardDescription>
-            Stamped onto every generated invoice and receipt PDF. Replacing it
-            here changes it everywhere at once — there is no per-invoice or
-            per-user choice.
+            The single EDR seal, applied to every generated document — invoices
+            and receipts, warehouse release and handover papers, and the EDR
+            side of signed contracts. Replacing it here changes it everywhere at
+            once; there is no per-document, per-invoice or per-employee choice.
+            Staff do not upload their own.
           </CardDescription>
         </CardHeader>
         <CardContent className="space-y-4">
diff --git a/apps/edr-freight-web/backoffice/src/user-management/route.tsx b/apps/edr-freight-web/backoffice/src/user-management/route.tsx
index f1e2a8611..ed6b13413 100644
--- a/apps/edr-freight-web/backoffice/src/user-management/route.tsx
+++ b/apps/edr-freight-web/backoffice/src/user-management/route.tsx
@@ -3,7 +3,7 @@ import { Navigate, Outlet, Route } from "react-router-dom";
 
 import { useAuth } from "@/auth/useAuth";
 import { NO_ACCESS_PATH, resolveLandingPath } from "@/lib/landing";
-import { isSuperAdmin } from "@/lib/permissions";
+import { FREIGHT_PERMS, isSuperAdmin } from "@/lib/permissions";
 import { WithPermission } from "@/shared/hooks/useHas";
 import PendingExternalUsers from "@/super-admin/components/externalUsers/PendingExternalUsers";
 import TemplatePage from "@/super-admin/components/templates/components/templates";
@@ -44,6 +44,8 @@ import { SidebarProvider } from "@/shared/common/ui/sidebar";
 import { AuthProvider as UmAuthProvider } from "@/shared/context/AuthContext";
 import { PermissionProvider } from "@/shared/context/PermissionContext";
 import UserManagementPage from "@/pages/UserManagementPage";
+import { RequirePermission } from "@/components/auth/RequirePermission";
+import UploadTeeterAndSignature from "@/record-management/components/Settings/uploadTeeterandSingature";
 
 /**
  * Provider shell for the vendored IAM UI. Feeds its Auth + Permission contexts
@@ -138,6 +140,25 @@ export function UserManagementRoutes(): ReactElement {
                           path="user-management/position-management"
                           element={<PositionManagementPage />}
                         />
+                        {/*
+                          The per-officer teeter (ማህተም) + signature upload. This
+                          is NOT the company stamp: it is the individual approval
+                          stamp a record officer applies to records, locale-aware
+                          (am/en) and genuinely per-person. It used to sit at
+                          /dashboard/stamp-settings under Settings, next to the
+                          single global company stamp, which read as duplication.
+                          Permission gate unchanged from that route.
+                        */}
+                        <Route
+                          path="user-management/teeter-and-signature"
+                          element={
+                            <RequirePermission
+                              permission={FREIGHT_PERMS.settings.stamp.view}
+                            >
+                              <UploadTeeterAndSignature />
+                            </RequirePermission>
+                          }
+                        />
                         <Route
                           path="user-management/migrated-records-management"
                           element={<MigratedDataManagementPage />}

From 2a816912fcae7842b1dbcb011a18d7378eae1a42 Mon Sep 17 00:00:00 2001
From: ghost2023 <nathnaelwonisha@gmail.com>
Date: Wed, 12 Aug 2026 13:18:29 +0300
Subject: [PATCH 047/174] fix(freight-permissions): split company stamp from
 per-officer teeter permission

---
 .../stamp-settings.controller.ts              |  6 ++--
 .../src/seed/freight-permissions.registry.ts  | 31 ++++++++++++-------
 apps/edr-freight-web/backoffice/src/App.tsx   |  2 +-
 .../components/layout/sidebar-sections.tsx    |  2 +-
 .../backoffice/src/lib/permissions.ts         | 13 +++++---
 .../backoffice/src/user-management/route.tsx  |  8 +++--
 .../src/logging/request-log.middleware.ts     |  6 +---
 7 files changed, 40 insertions(+), 28 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.controller.ts b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.controller.ts
index f03d55058..1ba60139e 100644
--- a/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.controller.ts
+++ b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.controller.ts
@@ -15,21 +15,21 @@ export class StampSettingsController {
   constructor(private readonly service: StampSettingsService) {}
 
   @Get()
-  @BookingStaff([FREIGHT_PERMS.settings.invoiceStamp.view, FREIGHT_PERMS.admin])
+  @BookingStaff([FREIGHT_PERMS.settings.stamp.view, FREIGHT_PERMS.admin])
   @ApiOperation({ summary: "Current company stamp used on invoice/receipt PDFs" })
   get() {
     return this.service.getView();
   }
 
   @Put()
-  @BookingStaff([FREIGHT_PERMS.settings.invoiceStamp.manage, FREIGHT_PERMS.admin])
+  @BookingStaff([FREIGHT_PERMS.settings.stamp.manage, FREIGHT_PERMS.admin])
   @ApiOperation({ summary: "Replace the company stamp" })
   update(@Body() dto: UpdateStampSettingDto, @CurrentUser() user: TCurrentUser) {
     return this.service.setStamp(dto.stampImageBase64, user?.id ?? null);
   }
 
   @Delete()
-  @BookingStaff([FREIGHT_PERMS.settings.invoiceStamp.manage, FREIGHT_PERMS.admin])
+  @BookingStaff([FREIGHT_PERMS.settings.stamp.manage, FREIGHT_PERMS.admin])
   @ApiOperation({
     summary: "Clear the company stamp (invoices fall back to the plain seal)",
   })
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 67df922b5..f0b719d63 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -1190,22 +1190,28 @@ export const CONFIG_SETTINGS_PERMISSIONS: FreightPermissionSeed[] = [
   perm(
     "b4b00002-0001-4000-8000-000000000001",
     "edr_freight_app:settings:stamp:view",
-    "View stamp settings",
+    "View the company stamp",
   ),
   perm(
     "b4b00002-0001-4000-8000-000000000002",
     "edr_freight_app:settings:stamp:manage",
-    "Manage stamp settings",
+    "Manage the company stamp",
   ),
+  // The per-officer approval teeter (ማህተም) — an individual's own stamp +
+  // signature, not the company seal. It used to ride on settings:stamp:*, which
+  // now gates the ONE company stamp; this key was split out when the two were
+  // untangled. `settings:invoice_stamp:*` retired at the same time: it gated the
+  // company stamp before the fold and is deliberately left orphaned in any DB
+  // that already seeded it (the seeder upserts by key and never deletes).
   perm(
     "b4b00003-0001-4000-8000-000000000001",
-    "edr_freight_app:settings:invoice_stamp:view",
-    "View invoice stamp settings",
+    "edr_freight_app:settings:teeter:view",
+    "View own approval teeter and signature",
   ),
   perm(
     "b4b00003-0001-4000-8000-000000000002",
-    "edr_freight_app:settings:invoice_stamp:manage",
-    "Manage invoice stamp settings",
+    "edr_freight_app:settings:teeter:manage",
+    "Manage own approval teeter and signature",
   ),
   perm(
     "b4c00001-0001-4000-8000-000000000001",
@@ -1907,15 +1913,18 @@ export const FREIGHT_PERMS = {
       view: "edr_freight_app:settings:dropdown:view",
       manage: "edr_freight_app:settings:dropdown:manage",
     },
+    // The ONE company stamp/seal, applied to every generated document
+    // (invoices, receipts, warehouse papers, the EDR side of contracts).
     stamp: {
       view: "edr_freight_app:settings:stamp:view",
       manage: "edr_freight_app:settings:stamp:manage",
     },
-    // Company stamp/seal image stamped onto invoice/receipt PDFs — separate
-    // from `stamp` above, which is the per-employee approval-record teeter.
-    invoiceStamp: {
-      view: "edr_freight_app:settings:invoice_stamp:view",
-      manage: "edr_freight_app:settings:invoice_stamp:manage",
+    // The per-officer approval teeter (ማህተም) + signature — genuinely per-person,
+    // and NOT the company seal above. Retired: `invoiceStamp`, which used to
+    // gate the company stamp before the two were untangled.
+    teeter: {
+      view: "edr_freight_app:settings:teeter:view",
+      manage: "edr_freight_app:settings:teeter:manage",
     },
     exchangeRate: {
       view: "edr_freight_app:settings:exchange_rate:view",
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index 83cf82909..64f91da72 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -796,7 +796,7 @@ const App = () => {
           path="stamp-settings"
           element={
             <RequirePermission
-              permission={FREIGHT_PERMS.settings.invoiceStamp.view}
+              permission={FREIGHT_PERMS.settings.stamp.view}
             >
               <CompanyStampSettingsPage />
             </RequirePermission>
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index c06b5a7e1..95608b6db 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -493,7 +493,7 @@ export const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[]
         label: "Company stamp",
         href: "/dashboard/stamp-settings",
         icon: <Stamp />,
-        permission: FREIGHT_PERMS.settings.invoiceStamp.view,
+        permission: FREIGHT_PERMS.settings.stamp.view,
       },
       {
         label: "Contract templates",
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index 26b46e37b..c69aa5d1b 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -328,15 +328,18 @@ export const FREIGHT_PERMS = {
       view: "edr_freight_app:settings:dropdown:view",
       manage: "edr_freight_app:settings:dropdown:manage",
     },
+    // The ONE company stamp/seal, applied to every generated document
+    // (invoices, receipts, warehouse papers, the EDR side of contracts).
     stamp: {
       view: "edr_freight_app:settings:stamp:view",
       manage: "edr_freight_app:settings:stamp:manage",
     },
-    // Company stamp/seal image stamped onto invoice/receipt PDFs — separate
-    // from `stamp` above, which is the per-employee approval-record teeter.
-    invoiceStamp: {
-      view: "edr_freight_app:settings:invoice_stamp:view",
-      manage: "edr_freight_app:settings:invoice_stamp:manage",
+    // The per-officer approval teeter (ማህተም) + signature — genuinely per-person,
+    // and NOT the company seal above. Retired: `invoiceStamp`, which used to
+    // gate the company stamp before the two were untangled.
+    teeter: {
+      view: "edr_freight_app:settings:teeter:view",
+      manage: "edr_freight_app:settings:teeter:manage",
     },
     exchangeRate: {
       view: "edr_freight_app:settings:exchange_rate:view",
diff --git a/apps/edr-freight-web/backoffice/src/user-management/route.tsx b/apps/edr-freight-web/backoffice/src/user-management/route.tsx
index ed6b13413..a336b3f9f 100644
--- a/apps/edr-freight-web/backoffice/src/user-management/route.tsx
+++ b/apps/edr-freight-web/backoffice/src/user-management/route.tsx
@@ -147,13 +147,17 @@ export function UserManagementRoutes(): ReactElement {
                           (am/en) and genuinely per-person. It used to sit at
                           /dashboard/stamp-settings under Settings, next to the
                           single global company stamp, which read as duplication.
-                          Permission gate unchanged from that route.
+
+                          Gated by settings:teeter:*, split out of settings:stamp:*
+                          when the two were untangled — settings:stamp:* now means
+                          the company stamp, so anyone who held it for the teeter
+                          needs the new key granted.
                         */}
                         <Route
                           path="user-management/teeter-and-signature"
                           element={
                             <RequirePermission
-                              permission={FREIGHT_PERMS.settings.stamp.view}
+                              permission={FREIGHT_PERMS.settings.teeter.view}
                             >
                               <UploadTeeterAndSignature />
                             </RequirePermission>
diff --git a/packages/api-common/src/logging/request-log.middleware.ts b/packages/api-common/src/logging/request-log.middleware.ts
index b25463161..5d9ead8b0 100644
--- a/packages/api-common/src/logging/request-log.middleware.ts
+++ b/packages/api-common/src/logging/request-log.middleware.ts
@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { Injectable, Logger, NestMiddleware } from "@nestjs/common";
+import { Injectable, NestMiddleware } from "@nestjs/common";
 
 import {
   RequestLogContext,
@@ -58,8 +58,6 @@ const userId = (req: LoggedRequest): string | undefined => {
  */
 @Injectable()
 export class RequestLogMiddleware implements NestMiddleware {
-  private readonly logger = new Logger("HTTP");
-
   use(req: LoggedRequest, res: LoggedResponse, next: () => void): void {
     const start = Date.now();
     const requestId = header(req, "x-request-id") ?? randomUUID();
@@ -85,8 +83,6 @@ export class RequestLogMiddleware implements NestMiddleware {
         const status = res.statusCode;
         const durationMs = Date.now() - start;
 
-        this.logger.log(`${req.method} ${url} ${status} ${durationMs}ms`);
-
         const line = {
           ...ctx,
           // Fields the Nest console prefix used to carry. They are IN the JSON

From a02d24806b0544f1bc58f4980afaf7ba4c653b7b Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 11:22:51 +0000
Subject: [PATCH 048/174] feat(rule-engine): add fuel surcharge rate trigger
 and cargo flag

---
 .../contract-rate-schedule.builder.ts         |  31 ++++++
 .../migrations/3430000000000-FuelSurcharge.ts |  62 +++++++++++
 .../rule-engine/dto/create-cargo-type.dto.ts  |   9 ++
 .../rule-engine/dto/create-rate.dto.ts        |  14 ++-
 .../rule-engine/entities/cargo-type.entity.ts |   8 ++
 .../rule-engine/entities/rate-type.util.ts    |   2 +
 .../rule-engine/entities/rate-unit.util.ts    |   3 +
 .../rule-engine/entities/rate.entity.ts       |  14 +++
 .../rule-engine/rule-engine.service.spec.ts   | 102 ++++++++++++++++++
 .../rule-engine/rule-engine.service.ts        |  57 ++++++++++
 .../rule-engine/services/rates.service.ts     |  85 +++++++++++++--
 .../src/pages/ruleEngine/CargoTypesPage.tsx   |   5 +
 .../ruleEngine/RuleEngineResourcePage.tsx     |  24 +++--
 .../src/pages/ruleEngine/config/resources.ts  |  62 +++++++++--
 .../backoffice/src/services/rates.service.ts  |   2 +
 15 files changed, 455 insertions(+), 25 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3430000000000-FuelSurcharge.ts

diff --git a/apps/edr-freight-api/src/contracts/contract-rate-schedule.builder.ts b/apps/edr-freight-api/src/contracts/contract-rate-schedule.builder.ts
index c62a875bf..c644d6117 100644
--- a/apps/edr-freight-api/src/contracts/contract-rate-schedule.builder.ts
+++ b/apps/edr-freight-api/src/contracts/contract-rate-schedule.builder.ts
@@ -44,6 +44,7 @@ const UNIT_LABELS: Record<string, string> = {
   PER_CONTAINER: 'per container',
   PER_KM: 'per km',
   PER_TON_KM: 'per ton per km',
+  PER_LITER: 'per liter',
   PER_INVOICE: 'per invoice',
   FLAT: 'flat',
 };
@@ -66,6 +67,7 @@ const TRIGGER_ROUTE_LABELS: Partial<Record<Rate['trigger'], string>> = {
   DEMURRAGE: 'Demurrage / wagon detention',
   PIL_EXTRA_FEE: 'PIL shipping line extra fee',
   CUSTOMS_CLEARANCE: 'Customs clearance service',
+  FUEL: 'Fuel surcharge',
 };
 
 @Injectable()
@@ -101,6 +103,15 @@ export class ContractRateScheduleBuilder {
         continue;
       }
 
+      // Fuel is sold per lane + commodity — only lanes matching the contract's
+      // direction belong on its schedule, labeled with their leg.
+      if (rate.trigger === 'FUEL') {
+        if (this.fuelDirectionMatches(rate, direction)) {
+          surcharges.push(this.fuelRow(rate));
+        }
+        continue;
+      }
+
       // Everything left is a trigger-based charge (surcharge / demurrage / customs).
       surcharges.push(this.surchargeRow(rate));
     }
@@ -176,6 +187,26 @@ export class ContractRateScheduleBuilder {
     };
   }
 
+  private fuelDirectionMatches(rate: Rate, direction: ContractDirection): boolean {
+    const want =
+      direction === 'IMP' ? 'IMPORT' : direction === 'EXP' ? 'EXPORT' : 'DOMESTIC';
+    return rate.tradeDirection === want;
+  }
+
+  /** Fuel row — the lane matters, so it rides along in the charge label. */
+  private fuelRow(rate: Rate): RateScheduleRow {
+    const origin = rate.originYard?.label ?? rate.originYard?.code ?? '—';
+    const destination =
+      rate.destinationYard?.label ?? rate.destinationYard?.code ?? '—';
+    return {
+      route: `Fuel surcharge (${origin} → ${destination})`,
+      cargo: this.cargoLabel(rate),
+      currency: rate.currency,
+      amount: this.formatAmount(rate.rateValue),
+      unit: this.unitLabel(rate.rateUnit),
+    };
+  }
+
   private surchargeRow(rate: Rate): RateScheduleRow {
     return {
       route: TRIGGER_ROUTE_LABELS[rate.trigger] ?? this.titleCase(rate.trigger),
diff --git a/apps/edr-freight-api/src/migrations/3430000000000-FuelSurcharge.ts b/apps/edr-freight-api/src/migrations/3430000000000-FuelSurcharge.ts
new file mode 100644
index 000000000..dfd0d25cf
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3430000000000-FuelSurcharge.ts
@@ -0,0 +1,62 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Fuel surcharge, sold per lane + commodity:
+ *
+ * - cargo_types.has_fuel marks the commodities that incur it (same shape as
+ *   has_lashing — the booking's cargo type flag is what fires the charge).
+ * - rates.base_liters carries the liters a PER_LITER fuel rate bills
+ *   (price = base_liters × rate_value, once per booking). NULL on every other
+ *   rate shape, including PER_WAGON fuel rates (wagons × rate_value).
+ * - CK_rates_yard_scope gains FUEL in its yard-carrying branch: fuel is priced
+ *   per origin → destination leg like customs clearance and container return.
+ */
+export class FuelSurcharge3430000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.cargo_types
+        ADD COLUMN IF NOT EXISTS has_fuel boolean NOT NULL DEFAULT false
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE freight.rates
+        ADD COLUMN IF NOT EXISTS base_liters numeric(14,4)
+    `);
+
+    await queryRunner.query(
+      `ALTER TABLE freight.rates DROP CONSTRAINT IF EXISTS "CK_rates_yard_scope"`,
+    );
+    await queryRunner.query(`
+      ALTER TABLE freight.rates ADD CONSTRAINT "CK_rates_yard_scope" CHECK (
+        deleted_at IS NOT NULL OR status = 'SUPERSEDED' OR
+        CASE
+          WHEN (trigger = 'ALWAYS' AND applies_to IN ('BULK', 'CONTAINER', 'INTERCITY'))
+            OR trigger IN ('CUSTOMS_CLEARANCE', 'WITH_RETURN', 'FUEL')
+          THEN origin_yard_id IS NOT NULL AND destination_yard_id IS NOT NULL
+          ELSE origin_yard_id IS NULL AND destination_yard_id IS NULL
+        END
+      )
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE freight.rates DROP CONSTRAINT IF EXISTS "CK_rates_yard_scope"`,
+    );
+    await queryRunner.query(`
+      ALTER TABLE freight.rates ADD CONSTRAINT "CK_rates_yard_scope" CHECK (
+        deleted_at IS NOT NULL OR status = 'SUPERSEDED' OR
+        CASE
+          WHEN (trigger = 'ALWAYS' AND applies_to IN ('BULK', 'CONTAINER', 'INTERCITY'))
+            OR trigger IN ('CUSTOMS_CLEARANCE', 'WITH_RETURN')
+          THEN origin_yard_id IS NOT NULL AND destination_yard_id IS NOT NULL
+          ELSE origin_yard_id IS NULL AND destination_yard_id IS NULL
+        END
+      )
+    `);
+    await queryRunner.query(`ALTER TABLE freight.rates DROP COLUMN IF EXISTS base_liters`);
+    await queryRunner.query(
+      `ALTER TABLE freight.cargo_types DROP COLUMN IF EXISTS has_fuel`,
+    );
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/rule-engine/dto/create-cargo-type.dto.ts b/apps/edr-freight-api/src/modules/rule-engine/dto/create-cargo-type.dto.ts
index d116a4b4a..67f5d2547 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/dto/create-cargo-type.dto.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/dto/create-cargo-type.dto.ts
@@ -70,6 +70,15 @@ export class CreateCargoTypeDto {
   @IsBoolean()
   hasLashing?: boolean;
 
+  @ApiPropertyOptional({
+    default: false,
+    description:
+      'When true, bookings of this cargo type incur the lane-scoped FUEL surcharge.',
+  })
+  @IsOptional()
+  @IsBoolean()
+  hasFuel?: boolean;
+
   @ApiPropertyOptional({
     default: false,
     description:
diff --git a/apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts b/apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts
index 45a5838bd..eccb14017 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts
@@ -7,7 +7,8 @@ import {
   RATE_UNITS,
 } from '../entities/rate.entity';
 
-const TRADE_DIRECTIONS = ['IMPORT', 'EXPORT', 'BOTH'] as const;
+// DOMESTIC is accepted only for FUEL rates (an intercity fuel lane).
+const TRADE_DIRECTIONS = ['IMPORT', 'EXPORT', 'BOTH', 'DOMESTIC'] as const;
 // ETB is accepted only for last-mile rates; the service forces USD elsewhere.
 const CURRENCIES = ['USD', 'ETB'] as const;
 export const INTERCITY_KINDS = ['CONTAINER', 'BULK'] as const;
@@ -94,6 +95,17 @@ export class CreateRateDto {
   @IsIn([...RATE_UNITS])
   rateUnit?: string;
 
+  @ApiPropertyOptional({
+    description:
+      'FUEL rates billed PER_LITER only: liters the surcharge covers — price = baseLiters × rateValue, once per booking. Required there, rejected elsewhere.',
+    minimum: 0,
+  })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Transform(({ value }) => (value === null || value === undefined || value === '' ? undefined : Number(value)))
+  baseLiters?: number;
+
   @ApiPropertyOptional({
     description:
       'Distance band start (km, inclusive). Container last-mile rates only (rateUnit = PER_KM).',
diff --git a/apps/edr-freight-api/src/modules/rule-engine/entities/cargo-type.entity.ts b/apps/edr-freight-api/src/modules/rule-engine/entities/cargo-type.entity.ts
index b7717684a..7084e233a 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/entities/cargo-type.entity.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/entities/cargo-type.entity.ts
@@ -82,6 +82,14 @@ export class CargoType extends BaseEntity {
   @Column({ name: 'has_lashing', type: 'boolean', default: false })
   hasLashing!: boolean;
 
+  /**
+   * Whether bookings of this cargo incur the fuel surcharge. Billed off the
+   * lane-scoped FUEL rate for the booking's direction + route + this cargo
+   * type (per liter or per wagon).
+   */
+  @Column({ name: 'has_fuel', type: 'boolean', default: false })
+  hasFuel!: boolean;
+
   /**
    * Whether staff may write bulk contract templates against this cargo type.
    * Mutually exclusive between a parent group and its children: if the parent
diff --git a/apps/edr-freight-api/src/modules/rule-engine/entities/rate-type.util.ts b/apps/edr-freight-api/src/modules/rule-engine/entities/rate-type.util.ts
index a5b5bfc30..536e35527 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/entities/rate-type.util.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/entities/rate-type.util.ts
@@ -46,6 +46,8 @@ export function deriveRateType(input: {
         return 'PIL_EXTRA_FEE';
       case 'CUSTOMS_CLEARANCE':
         return 'CUSTOMS_CLEARANCE';
+      case 'FUEL':
+        return 'FUEL_SURCHARGE';
     }
   }
 
diff --git a/apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.ts b/apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.ts
index a3d336605..3d5b1401e 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.ts
@@ -74,6 +74,9 @@ function unitsForShape(input: {
       case 'LASHING':
         // Bulk-only cargo securing — per ton or per wagon.
         return ['PER_TON', 'PER_WAGON'];
+      case 'FUEL':
+        // Per wagon (wagons × rate) or per liter (baseLiters × rate, once).
+        return ['PER_WAGON', 'PER_LITER'];
       case 'CONSOLIDATION':
         return ['PER_CONTAINER', 'FLAT'];
       case 'SHIPPING_LINE':
diff --git a/apps/edr-freight-api/src/modules/rule-engine/entities/rate.entity.ts b/apps/edr-freight-api/src/modules/rule-engine/entities/rate.entity.ts
index e7089f08c..925a3555a 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/entities/rate.entity.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/entities/rate.entity.ts
@@ -24,6 +24,7 @@ export const RATE_TYPES = [
   'RETURN_SURCHARGE',
   'PIL_EXTRA_FEE',
   'CUSTOMS_CLEARANCE',
+  'FUEL_SURCHARGE',
 ] as const;
 
 export type RateType = typeof RATE_TYPES[number];
@@ -41,6 +42,8 @@ export const RATE_UNITS = [
   'PER_KM',
   // Last-mile bulk: price = tons × km × rateValue.
   'PER_TON_KM',
+  // Fuel surcharge only: price = baseLiters × rateValue, once per booking.
+  'PER_LITER',
   'PER_INVOICE',
   'FLAT',
 ] as const;
@@ -92,6 +95,9 @@ export const RATE_TRIGGERS = [
   // Customs clearance service fee — billed up front via a clearance invoice,
   // never auto-applied to booking pricing (matchesTrigger returns false).
   'CUSTOMS_CLEARANCE',
+  // Fuel surcharge — fires when the booking's cargo type has hasFuel = true,
+  // billed off the lane-scoped rate (direction + route + cargo type).
+  'FUEL',
 ] as const;
 export type RateTrigger = typeof RATE_TRIGGERS[number];
 
@@ -163,6 +169,14 @@ export class Rate extends BaseEntity {
    * containerTypeId): the rate applies when minKm <= km < maxKm (maxKm NULL =
    * open-ended). NULL on every other rate shape.
    */
+  /**
+   * FUEL rates billed PER_LITER only: the liters the surcharge covers —
+   * price = baseLiters × rateValue, once per booking. NULL on every other
+   * rate shape (a PER_WAGON fuel rate bills wagons × rateValue instead).
+   */
+  @Column({ name: 'base_liters', type: 'numeric', precision: 14, scale: 4, nullable: true })
+  baseLiters?: number | null;
+
   @Column({ name: 'min_km', type: 'numeric', precision: 10, scale: 2, nullable: true })
   minKm?: number | null;
 
diff --git a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.spec.ts b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.spec.ts
index a736d4b05..440616298 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.spec.ts
@@ -422,3 +422,105 @@ describe('RuleEngineService — lashing (bulk-only, per direction + commodity)',
     expect(lashingMods(result)).toHaveLength(0);
   });
 });
+
+describe('RuleEngineService — fuel surcharge (per lane + cargo type)', () => {
+  const fuelPerLiter: Rate = {
+    id: 'rate-fuel-liter',
+    rateType: 'FUEL_SURCHARGE',
+    trigger: 'FUEL',
+    rateValue: 2,
+    rateUnit: 'PER_LITER',
+    baseLiters: 100,
+    currency: 'USD',
+    status: 'LIVE',
+    containerTypeId: null,
+    cargoTypeId: 'cargo-steel',
+    tradeDirection: 'IMPORT',
+    originYardId: 'yard-nagad',
+    destinationYardId: 'yard-mojo',
+  } as Rate;
+
+  const buildService = (rates: Rate[], hasFuel = true): RuleEngineService =>
+    new RuleEngineService(
+      {
+        findById: jest
+          .fn()
+          .mockResolvedValue({ hasFuel, hasLashing: false, requiresDirectorApproval: false }),
+      } as never,
+      { findById: jest.fn().mockResolvedValue(null) } as never,
+      { findActiveByContainerTypeId: jest.fn().mockResolvedValue([]) } as never,
+      { findAllActive: jest.fn().mockResolvedValue([]) } as never,
+      { findLiveRates: jest.fn().mockResolvedValue(rates) } as never,
+      { findById: jest.fn().mockResolvedValue(null) } as never,
+      {} as never,
+    );
+
+  const fuelInput = (
+    overrides: Partial<BookingEvaluationInput> = {},
+  ): BookingEvaluationInput => ({
+    serviceTypeId: 'svc-1',
+    paymentCurrency: 'USD',
+    tradeDirection: 'IMPORT',
+    isHazardous: false,
+    cargoTypeId: 'cargo-steel',
+    originYardId: 'yard-nagad',
+    destinationYardId: 'yard-mojo',
+    totalWagons: 0,
+    bulkTons: 100,
+    bulkWagons: 4,
+    containers: [],
+    ...overrides,
+  });
+
+  const fuelMods = (result: Awaited<ReturnType<RuleEngineService['evaluate']>>) =>
+    result.appliedModifiers.filter((m) => m.surchargeCode === 'FUEL_SURCHARGE');
+
+  it('PER_LITER bills base liters × rate value once, regardless of wagons', async () => {
+    const result = await buildService([fuelPerLiter]).evaluate(fuelInput());
+    const mods = fuelMods(result);
+    expect(mods).toHaveLength(1);
+    expect(mods[0].triggerValue).toBe(100);
+    expect(mods[0].calculatedAmount).toBe(200);
+    expect(mods[0].billingUnit).toBe('PER_LITER');
+  });
+
+  it('PER_WAGON bills the wagons the cargo occupies', async () => {
+    const result = await buildService([
+      { ...fuelPerLiter, rateUnit: 'PER_WAGON', baseLiters: null, rateValue: 50 } as Rate,
+    ]).evaluate(fuelInput());
+    const mods = fuelMods(result);
+    expect(mods[0].triggerValue).toBe(4);
+    expect(mods[0].calculatedAmount).toBe(200);
+  });
+
+  it('a rate for another lane, direction or commodity never bills', async () => {
+    for (const wrong of [
+      { tradeDirection: 'EXPORT' },
+      { originYardId: 'yard-other' },
+      { destinationYardId: 'yard-other' },
+      { cargoTypeId: 'cargo-wheat' },
+    ]) {
+      const result = await buildService([{ ...fuelPerLiter, ...wrong } as Rate]).evaluate(
+        fuelInput(),
+      );
+      expect(fuelMods(result)).toHaveLength(0);
+    }
+  });
+
+  it('a domestic booking bills the DOMESTIC fuel lane', async () => {
+    const result = await buildService([
+      { ...fuelPerLiter, tradeDirection: 'DOMESTIC' } as Rate,
+    ]).evaluate(fuelInput({ tradeDirection: 'DOMESTIC' }));
+    expect(fuelMods(result)).toHaveLength(1);
+  });
+
+  it('no fuel charge when the cargo type does not have hasFuel', async () => {
+    const result = await buildService([fuelPerLiter], false).evaluate(fuelInput());
+    expect(fuelMods(result)).toHaveLength(0);
+  });
+
+  it('no matching lane rate bills nothing (lenient, like lashing)', async () => {
+    const result = await buildService([]).evaluate(fuelInput());
+    expect(fuelMods(result)).toHaveLength(0);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
index ac2e854e4..a290aeb33 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
@@ -175,6 +175,9 @@ export class RuleEngineService {
     // matchesTrigger can fire the LASHING rate. Falls back to an explicit
     // input flag when no cargo type is set (e.g. container bookings).
     let hasLashing = input.hasLashing === true;
+    // Fuel is likewise a cargo-type property (hasFuel), billed off the
+    // lane-scoped FUEL rate — see fuelCharges.
+    let hasFuel = false;
     if (input.cargoTypeId) {
       const cargoType = await this.cargoTypesRepo.findById(input.cargoTypeId);
       if (!cargoType) {
@@ -186,6 +189,9 @@ export class RuleEngineService {
         if (cargoType.hasLashing) {
           hasLashing = true;
         }
+        if (cargoType.hasFuel) {
+          hasFuel = true;
+        }
       }
     }
 
@@ -328,6 +334,9 @@ export class RuleEngineService {
       // Lashing is sold per cargo kind + container type — billed by the
       // kind-aware block below, never by this generic loop.
       if (rate.trigger === 'LASHING') continue;
+      // Fuel is sold per lane + cargo type — billed by the route-matched
+      // block below, never by this route-agnostic loop.
+      if (rate.trigger === 'FUEL') continue;
       const triggered = this.matchesTrigger(rate.trigger, {
         isHazardous: input.isHazardous,
         hasReefer,
@@ -442,6 +451,10 @@ export class RuleEngineService {
       appliedModifiers.push(...this.lashingCharges(input, liveRates));
     }
 
+    if (hasFuel) {
+      appliedModifiers.push(...this.fuelCharges(input, liveRates));
+    }
+
     return {
       priorityScore,
       appliedModifiers,
@@ -632,6 +645,50 @@ export class RuleEngineService {
     return modifiers;
   }
 
+  /**
+   * Fuel surcharge — fires when the booking's cargo type has hasFuel = true,
+   * billed off the FUEL rate matching the booking's lane (trade direction +
+   * origin + destination) and cargo type. PER_LITER bills baseLiters ×
+   * rateValue once per booking; PER_WAGON bills the wagons the cargo occupies.
+   * No matching lane rate simply bills nothing — same leniency as lashing.
+   */
+  private fuelCharges(
+    input: BookingEvaluationInput,
+    liveRates: Rate[],
+  ): AppliedCargoModifier[] {
+    const modifiers: AppliedCargoModifier[] = [];
+    const rate = liveRates.find(
+      (r) =>
+        r.trigger === 'FUEL' &&
+        r.currency === 'USD' &&
+        r.tradeDirection === input.tradeDirection &&
+        r.originYardId === input.originYardId &&
+        r.destinationYardId === input.destinationYardId &&
+        r.cargoTypeId === input.cargoTypeId,
+    );
+    if (!rate) return modifiers;
+
+    const rateValue = Number(rate.rateValue);
+    const wagons = Math.max(
+      0,
+      Number(input.bulkWagons ?? 0) || Number(input.totalWagons ?? 0),
+    );
+    const billedQty =
+      rate.rateUnit === 'PER_LITER' ? Number(rate.baseLiters ?? 0) : wagons;
+    const amount = billedQty * rateValue;
+    if (!(amount > 0)) return modifiers;
+    modifiers.push({
+      rateId: rate.id,
+      surchargeCode: this.surchargeCode(rate),
+      triggerValue: billedQty,
+      calculatedAmount: amount,
+      currency: rate.currency,
+      unitPriceUsd: rateValue,
+      billingUnit: rate.rateUnit,
+    });
+    return modifiers;
+  }
+
   /**
    * Messages for container lines whose total weight exceeds the hard capacity
    * ceiling (weight_limit_rules.max_capacity_tons). Non-empty ⇒ the booking
diff --git a/apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts b/apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts
index 971097377..232cd9299 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts
@@ -121,15 +121,16 @@ export class RatesService {
   }
 
   /**
-   * Rates sold per direction + route. Base freight always; customs clearance
-   * and empty-container return are the surcharges that are too — their fee
-   * depends on the lane (and, for returns, the container type).
+   * Rates sold per direction + route. Base freight always; customs clearance,
+   * empty-container return and fuel are the surcharges that are too — their
+   * fee depends on the lane (and, for returns, the container type).
    */
   private isRouteScoped(appliesTo: Rate['appliesTo'], trigger: Rate['trigger']): boolean {
     return (
       this.isBaseFreight(appliesTo, trigger) ||
       trigger === 'CUSTOMS_CLEARANCE' ||
-      trigger === 'WITH_RETURN'
+      trigger === 'WITH_RETURN' ||
+      trigger === 'FUEL'
     );
   }
 
@@ -160,7 +161,9 @@ export class RatesService {
     appliesTo: Rate['appliesTo'],
     tradeDirection: string | null,
   ): { origin: YardCountry; destination: YardCountry } {
-    if (appliesTo === 'INTERCITY') {
+    // DOMESTIC only reaches here on a FUEL rate's intercity lane — it stays
+    // inside Ethiopia exactly like intercity base freight.
+    if (appliesTo === 'INTERCITY' || tradeDirection === 'DOMESTIC') {
       return { origin: YardCountry.ETHIOPIA, destination: YardCountry.ETHIOPIA };
     }
     return tradeDirection === 'EXPORT'
@@ -291,6 +294,31 @@ export class RatesService {
       }
       return;
     }
+    if (trigger === 'FUEL') {
+      // Fuel is sold per lane + commodity: the direction says which countries
+      // the leg spans (DOMESTIC = intercity, inside Ethiopia) and the cargo
+      // type names the commodity — different commodities price differently.
+      if (
+        tradeDirection !== 'IMPORT' &&
+        tradeDirection !== 'EXPORT' &&
+        tradeDirection !== 'DOMESTIC'
+      ) {
+        throw new BadRequestException(
+          'A fuel rate must say whether it covers IMPORT, EXPORT or DOMESTIC (intercity).',
+        );
+      }
+      if (containerTypeId) {
+        throw new BadRequestException(
+          'A fuel rate cannot be scoped to a container type.',
+        );
+      }
+      if (!cargoTypeId) {
+        throw new BadRequestException(
+          'A fuel rate must name the cargo type it covers.',
+        );
+      }
+      return;
+    }
     if (trigger === 'WITH_RETURN') {
       // Returning the empty box only exists on imports (the box goes back to
       // the port) — export return rates are rejected until the business sells
@@ -502,15 +530,21 @@ export class RatesService {
           : (dto.containerTypeId ?? null);
     const cargoTypeId =
       (trigger === 'CUSTOMS_CLEARANCE' && cargoKind === 'BULK') ||
-      trigger === 'LASHING'
+      trigger === 'LASHING' ||
+      trigger === 'FUEL'
         ? (dto.cargoTypeId ?? null)
         : isSurcharge
           ? null
           : (dto.cargoTypeId ?? null);
     // Intercity never leaves Ethiopia, so it has no trade direction to store —
-    // its yard pair already says where it runs.
+    // its yard pair already says where it runs. (Fuel is the exception: its
+    // intercity lane is stored as DOMESTIC, since appliesTo = OTHER says
+    // nothing about the direction.)
     const tradeDirection =
-      trigger === 'CUSTOMS_CLEARANCE' || trigger === 'WITH_RETURN' || trigger === 'LASHING'
+      trigger === 'CUSTOMS_CLEARANCE' ||
+      trigger === 'WITH_RETURN' ||
+      trigger === 'LASHING' ||
+      trigger === 'FUEL'
         ? (dto.tradeDirection ?? null)
         : isSurcharge || appliesTo === 'INTERCITY'
           ? null
@@ -563,6 +597,8 @@ export class RatesService {
       await this.assertNoBandOverlap({ rateUnit, containerTypeId, minKm, maxKm });
     }
 
+    const baseLiters = this.resolveBaseLiters(rateUnit, dto.baseLiters);
+
     await this.assertNoDuplicatePattern({
       rateType,
       ...(this.resolvesSingleRate(appliesTo, trigger) ? {} : { rateUnit }),
@@ -588,6 +624,7 @@ export class RatesService {
       currency: appliesTo === 'LAST_MILE' ? (dto.currency ?? 'ETB') : 'USD',
       rateValue: dto.rateValue,
       rateUnit,
+      baseLiters,
       minKm,
       maxKm,
       status: 'DRAFT',
@@ -595,6 +632,25 @@ export class RatesService {
     });
   }
 
+  /**
+   * The liters a PER_LITER fuel rate bills (price = baseLiters × rateValue,
+   * once per booking). Required there; cleared on every other rate shape —
+   * a PER_WAGON fuel rate bills wagons × rateValue and carries none.
+   */
+  private resolveBaseLiters(
+    rateUnit: Rate['rateUnit'],
+    baseLiters?: number | null,
+  ): number | null {
+    if (rateUnit !== 'PER_LITER') return null;
+    const liters = Number(baseLiters);
+    if (!(liters > 0)) {
+      throw new BadRequestException(
+        'A per-liter fuel rate needs a base liters amount — the price is base liters × rate value.',
+      );
+    }
+    return liters;
+  }
+
   /**
    * Update a DRAFT rate in place. Nothing prices off a draft, so a direct edit
    * is safe. A LIVE rate cannot take this path — see `applyApprovedUpdate`.
@@ -680,14 +736,18 @@ export class RatesService {
     const keepsCargoType =
       !isSurcharge ||
       (trigger === 'CUSTOMS_CLEARANCE' && cargoKind === 'BULK') ||
-      trigger === 'LASHING';
+      trigger === 'LASHING' ||
+      trigger === 'FUEL';
     const cargoTypeId = !keepsCargoType
       ? null
       : dto.cargoTypeId !== undefined
         ? dto.cargoTypeId
         : existing.cargoTypeId;
     const tradeDirection =
-      trigger === 'CUSTOMS_CLEARANCE' || trigger === 'WITH_RETURN' || trigger === 'LASHING'
+      trigger === 'CUSTOMS_CLEARANCE' ||
+      trigger === 'WITH_RETURN' ||
+      trigger === 'LASHING' ||
+      trigger === 'FUEL'
         ? dto.tradeDirection !== undefined
           ? dto.tradeDirection
           : existing.tradeDirection
@@ -788,6 +848,11 @@ export class RatesService {
       ignoreId: id,
     });
 
+    updates.baseLiters = this.resolveBaseLiters(
+      rateUnit,
+      dto.baseLiters !== undefined ? dto.baseLiters : existing.baseLiters,
+    );
+
     updates.currency =
       appliesTo === 'LAST_MILE'
         ? (dto.currency ?? existing.currency ?? 'ETB')
diff --git a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/CargoTypesPage.tsx b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/CargoTypesPage.tsx
index 2b5839a42..769ae757c 100644
--- a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/CargoTypesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/CargoTypesPage.tsx
@@ -55,6 +55,8 @@ interface CargoNode extends RuleEngineRecord {
   requiresDirectorApproval?: boolean;
   /** When true, bookings of this cargo type incur the flat LASHING surcharge. */
   hasLashing?: boolean;
+  /** When true, bookings of this cargo type incur the lane-scoped FUEL surcharge. */
+  hasFuel?: boolean;
   /** Staff may write bulk contract templates for this cargo type (parent XOR children). */
   hasContractTemplate?: boolean;
   /** How this cargo is measured (PER_TON / PER_ITEM); null for groups/unset. */
@@ -114,6 +116,9 @@ const FORM_FIELDS: FormFieldDef[] = [
   // When on, every booking of this cargo type is charged the flat LASHING
   // surcharge (a rate with trigger = Lashing).
   { name: "hasLashing", label: "Charge lashing fee", type: "boolean" },
+  // When on, bookings of this cargo type incur the fuel surcharge, billed off
+  // the lane-scoped FUEL rate (direction + route + cargo type) under Rates.
+  { name: "hasFuel", label: "Charge fuel fee", type: "boolean" },
   // Lets staff write bulk contract templates for this cargo type. The API
   // rejects the save when the parent group (or a child) already has it on —
   // the template must live on exactly one level.
diff --git a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
index 3751d17a6..e345fb65a 100644
--- a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
@@ -100,19 +100,27 @@ const yardOptionsForLegEnd = (
   } else if (
     appliesTo === "CONTAINER" ||
     appliesTo === "BULK" ||
-    // Customs clearance + empty-container return are sold per direction +
-    // route, so their yard dropdowns narrow exactly like base freight.
+    // Customs clearance, empty-container return and fuel are sold per
+    // direction + route, so their yard dropdowns narrow exactly like base
+    // freight.
     (appliesTo === "OTHER" &&
-      ["CUSTOMS_CLEARANCE", "WITH_RETURN"].includes(String(values.trigger ?? "")))
+      ["CUSTOMS_CLEARANCE", "WITH_RETURN", "FUEL"].includes(
+        String(values.trigger ?? ""),
+      ))
   ) {
     const direction = String(values.tradeDirection ?? "");
     // Direction is what decides the countries, so offer nothing until it is set
     // rather than defaulting to one and letting it read as a real choice.
-    if (direction !== "IMPORT" && direction !== "EXPORT") return [];
-    const startsInEthiopia = direction === "EXPORT";
-    country = (end === "origin" ? startsInEthiopia : !startsInEthiopia)
-      ? "Ethiopia"
-      : "Djibouti";
+    if (direction === "DOMESTIC") {
+      // A fuel rate's intercity lane — stays inside Ethiopia.
+      country = "Ethiopia";
+    } else {
+      if (direction !== "IMPORT" && direction !== "EXPORT") return [];
+      const startsInEthiopia = direction === "EXPORT";
+      country = (end === "origin" ? startsInEthiopia : !startsInEthiopia)
+        ? "Ethiopia"
+        : "Djibouti";
+    }
   }
   if (!country) return [];
   return yards
diff --git a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts
index 22e1046e8..4e00a930b 100644
--- a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts
+++ b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts
@@ -181,6 +181,17 @@ const RATE_TRIGGERS = [
   { label: "Cancellation", value: "CANCELLATION" },
   { label: "Shipping line extra fee (PIL)", value: "PIL_EXTRA_FEE" },
   { label: "Customs clearance service fee (billed with the booking)", value: "CUSTOMS_CLEARANCE" },
+  { label: "Fuel (per lane + cargo type)", value: "FUEL" },
+];
+
+/**
+ * Fuel lanes: import/export like base freight, plus a domestic intercity lane
+ * (stored as DOMESTIC — matches the booking's own trade direction).
+ */
+const FUEL_TRADE_DIRECTIONS = [
+  { label: "Import", value: "IMPORT" },
+  { label: "Export", value: "EXPORT" },
+  { label: "Intercity", value: "DOMESTIC" },
 ];
 
 /**
@@ -205,7 +216,7 @@ const isBaseFreightRate = (values: Record<string, unknown>) =>
 const isRouteScopedRate = (values: Record<string, unknown>) =>
   isBaseFreightRate(values) ||
   (String(values.appliesTo ?? "") === "OTHER" &&
-    ["CUSTOMS_CLEARANCE", "WITH_RETURN"].includes(String(values.trigger ?? "")));
+    ["CUSTOMS_CLEARANCE", "WITH_RETURN", "FUEL"].includes(String(values.trigger ?? "")));
 
 const unitOption = (value: string) => ({ label: value.replace(/_/g, " "), value });
 
@@ -255,6 +266,9 @@ const unitsForShape = (
       case "LASHING":
         // Bulk-only cargo securing — per ton or per wagon.
         return ["PER_TON", "PER_WAGON"];
+      case "FUEL":
+        // Per wagon (wagons × rate) or per liter (base liters × rate, once).
+        return ["PER_WAGON", "PER_LITER"];
       case "CONSOLIDATION":
       case "SHIPPING_LINE":
       case "PIL_EXTRA_FEE":
@@ -371,6 +385,13 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
       },
       { name: "requiresDirectorApproval", label: "Requires director approval", type: "boolean" },
       { name: "hasLashing", label: "Charge lashing fee", type: "boolean" },
+      {
+        name: "hasFuel",
+        label: "Charge fuel fee",
+        type: "boolean",
+        description:
+          "Bookings of this cargo incur the fuel surcharge (configure the FUEL rate per lane under Rates).",
+      },
       { name: "isActive", label: "Active", type: "boolean" },
     ],
   },
@@ -834,7 +855,7 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         filters: {
           appliesTo: "OTHER",
           trigger:
-            "HAZARDOUS,OVERWEIGHT,REEFER,SHIPPING_LINE,CONSOLIDATION,LASHING,CANCELLATION,PIL_EXTRA_FEE",
+            "HAZARDOUS,OVERWEIGHT,REEFER,SHIPPING_LINE,CONSOLIDATION,LASHING,CANCELLATION,PIL_EXTRA_FEE,FUEL",
         },
       },
     ],
@@ -886,14 +907,17 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         type: "select",
         required: true,
         optionsFromValues: (v: Record<string, unknown>) =>
-          String(v.trigger ?? "") === "WITH_RETURN" &&
-          String(v.appliesTo ?? "") === "OTHER"
+          String(v.appliesTo ?? "") === "OTHER" &&
+          String(v.trigger ?? "") === "WITH_RETURN"
             ? TRADE_DIRECTIONS.filter((d) => d.value === "IMPORT")
-            : TRADE_DIRECTIONS.filter((d) => d.value !== "BOTH"),
+            : String(v.appliesTo ?? "") === "OTHER" &&
+                String(v.trigger ?? "") === "FUEL"
+              ? FUEL_TRADE_DIRECTIONS
+              : TRADE_DIRECTIONS.filter((d) => d.value !== "BOTH"),
         showIf: (v) =>
           ["BULK", "CONTAINER"].includes(String(v.appliesTo ?? "")) ||
           (String(v.appliesTo ?? "") === "OTHER" &&
-            ["CUSTOMS_CLEARANCE", "WITH_RETURN", "LASHING"].includes(
+            ["CUSTOMS_CLEARANCE", "WITH_RETURN", "LASHING", "FUEL"].includes(
               String(v.trigger ?? ""),
             )),
       },
@@ -939,6 +963,18 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
           v.trigger === "CUSTOMS_CLEARANCE" &&
           v.cargoKind === "BULK",
       },
+      // ── Cargo type — a fuel rate names the commodity it covers (different
+      // commodities price differently on the same lane) ──────────────────────
+      {
+        name: "cargoTypeId",
+        label: "Cargo type",
+        type: "select",
+        required: true,
+        placeholder: "Which cargo type this fuel rate covers",
+        description:
+          "Fuel is charged for bookings of this cargo type (needs “Charge fuel fee” enabled on the cargo type).",
+        showIf: (v) => v.appliesTo === "OTHER" && v.trigger === "FUEL",
+      },
       // ── Bulk cargo type — lashing is bulk-only; may narrow to one leaf
       // commodity (specific wins over the commodity-wide catch-all) ──────────
       {
@@ -1123,6 +1159,20 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
           String(v.trigger ?? "") !== "OVERWEIGHT" &&
           String(v.appliesTo ?? "") !== "LAST_MILE",
       },
+      // ── Base liters — per-liter fuel rates only ────────────────────────────
+      {
+        name: "baseLiters",
+        label: "Base (liters)",
+        type: "number",
+        required: true,
+        placeholder: "e.g. 100",
+        description:
+          "Liters the surcharge covers — price = base liters × rate value, charged once per booking.",
+        showIf: (v) =>
+          v.appliesTo === "OTHER" &&
+          v.trigger === "FUEL" &&
+          v.rateUnit === "PER_LITER",
+      },
     ],
   },
   {
diff --git a/apps/edr-freight-web/backoffice/src/services/rates.service.ts b/apps/edr-freight-web/backoffice/src/services/rates.service.ts
index b7e3dd377..c832b6f7e 100644
--- a/apps/edr-freight-web/backoffice/src/services/rates.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/rates.service.ts
@@ -11,6 +11,8 @@ export interface Rate {
   currency: string;
   rateValue: string;
   rateUnit: string;
+  /** PER_LITER fuel rates only: price = baseLiters × rateValue, once per booking. */
+  baseLiters?: string | null;
   status: string;
   proposedByStaffId: string;
   approvedByCeoId: string | null;

From 3dbda745dd67d2df905eea701836ad49752fc3dd Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 11:23:04 +0000
Subject: [PATCH 049/174] feat(contracts): lazily expire lapsed contracts and
 price fuel surcharge

---
 .../contracts/contract-booking.service.ts     | 39 +++++++++-------
 .../contracts/contract-pricing.service.ts     | 44 ++++++++++++++++++-
 .../modules/contracts/contracts.repository.ts | 21 +++++++++
 .../modules/contracts/contracts.service.ts    | 10 +++++
 .../ContractBookingWindowsSection.tsx         | 15 ++++++-
 5 files changed, 112 insertions(+), 17 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
index d5989f2ac..3d362d53f 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
@@ -157,13 +157,9 @@ export class ContractBookingService {
       actorPermissions != null &&
       hasFreightPermission(actorPermissions, FREIGHT_PERMS.contracts.createBooking);
 
+    await this.assertNotExpired(contract);
     const createdByRole = await this.assertGate(contract, isGlActor);
 
-    // Validity window must still be open.
-    if (contract.contractValidUntil && contract.contractValidUntil.getTime() < Date.now()) {
-      throw new BadRequestException('Contract validity has expired — no new bookings.');
-    }
-
     // ONE_TIME: a single shipment at a time. The slot frees only if the prior
     // booking reached a terminal state (e.g. payment expired without shipping),
     // letting the customer re-book within contract validity (doc §10.4).
@@ -441,12 +437,9 @@ export class ContractBookingService {
     // The customer initiates his own shipment instance on ONE_TIME contracts
     // (customs or self-clearance); GL may also initiate on a customs contract.
     // GENERAL customs instances come from a shipment request, not from here.
+    await this.assertNotExpired(contract);
     const createdByRole = await this.assertGate(contract, isGlActor, true);
 
-    if (contract.contractValidUntil && contract.contractValidUntil.getTime() < Date.now()) {
-      throw new BadRequestException('Contract validity has expired — no new bookings.');
-    }
-
     // ONE_TIME carries a single shipment at a time; a bare instance occupies the
     // slot from the moment it is initiated (it is not a terminal status). The
     // split chain is the one exception — a paid partial frees the slot and
@@ -545,9 +538,7 @@ export class ContractBookingService {
         'Shipment-request initiation applies only to general customs contracts.',
       );
     }
-    if (contract.contractValidUntil && contract.contractValidUntil.getTime() < Date.now()) {
-      throw new BadRequestException('Contract validity has expired — no new bookings.');
-    }
+    await this.assertNotExpired(contract);
 
     const route = await this.resolveRoute(contract, opts.contractRouteId);
 
@@ -681,9 +672,11 @@ export class ContractBookingService {
     if (!dto.scheduledDate) {
       throw new BadRequestException('A binding shipment day is required');
     }
-    if (contract.contractValidUntil && contract.contractValidUntil.getTime() < Date.now()) {
-      throw new BadRequestException('Contract validity has expired — no new bookings.');
-    }
+    // No expiry gate here on purpose: this booking was already initiated
+    // before the contract lapsed (createUnderContract/initiateUnderContract
+    // already checked expiry at start). Finishing an in-flight booking must
+    // proceed even if the contract expires meanwhile — only starting a NEW
+    // booking is blocked (see assertNotExpired).
 
     // Completion is booking time: the route's booking window must be open —
     // the same config-driven gate a direct one-time booking passes at create.
@@ -1019,6 +1012,22 @@ export class ContractBookingService {
    * Returns the role to stamp on the booking, or throws if the caller is not
    * allowed to create one for this contract's execution path.
    */
+  /**
+   * Blocks starting a NEW booking (create/initiate) once the contract has
+   * lapsed, and lazily flips the stored status to EXPIRED so it doesn't wait
+   * for the nightly sweep. Only for the "start something new" entry points —
+   * a booking already underway (completeUnderContract) must be allowed to
+   * finish even if the contract expires mid-flight.
+   */
+  private async assertNotExpired(contract: Contract): Promise<void> {
+    if (!isEffectivelyExpired(contract)) return;
+    if (contract.status !== 'EXPIRED') {
+      const flipped = await this.contractsRepository.expireIfLapsed(contract.id);
+      if (flipped) contract.status = 'EXPIRED';
+    }
+    throw new BadRequestException('Contract validity has expired — no new bookings.');
+  }
+
   private async assertGate(
     contract: Contract,
     isGlActor: boolean,
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts
index 924c1a72d..3f49b127f 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts
@@ -11,7 +11,14 @@ import { Contract } from './entities/contract.entity';
 export interface ContractUnitRateLineItem {
   code: string;
   label: string;
-  unit: 'per_container' | 'per_wagon' | 'per_ton' | 'per_item' | 'per_km' | 'flat';
+  unit:
+    | 'per_container'
+    | 'per_wagon'
+    | 'per_ton'
+    | 'per_item'
+    | 'per_km'
+    | 'per_liter'
+    | 'flat';
   unitPrice: number;
   containerSize?: string | null;
   conditionalOn?: string | null;
@@ -44,6 +51,8 @@ function toContractUnit(rateUnit: string): ContractUnitRateLineItem['unit'] {
       return 'per_wagon';
     case 'PER_CONTAINER':
       return 'per_container';
+    case 'PER_LITER':
+      return 'per_liter';
     default:
       return 'flat';
   }
@@ -276,6 +285,39 @@ export class ContractPricingService {
       }
     }
 
+    // Fuel surcharge — shown when the contract's commodity incurs fuel
+    // (cargoType.hasFuel), sold per lane + commodity. Billed at booking on the
+    // frozen/live rate (per wagon × wagons, or per liter × base liters, once);
+    // this line freezes the agreed unit price.
+    {
+      const scope = (contract.cargoScope ?? []).find((c) => c.cargoTypeId);
+      if (scope?.cargoType?.hasFuel && route) {
+        const fuel = liveRates.find(
+          (r) =>
+            r.trigger === 'FUEL' &&
+            r.currency === 'USD' &&
+            r.tradeDirection === contract.tradeDirection &&
+            r.originYardId === route.originYardId &&
+            r.destinationYardId === route.destinationYardId &&
+            r.cargoTypeId === scope.cargoTypeId,
+        );
+        if (fuel && Number(fuel.rateValue) > 0) {
+          const base = Number(fuel.baseLiters ?? 0);
+          lineItems.push({
+            code: 'FUEL_SURCHARGE',
+            label:
+              fuel.rateUnit === 'PER_LITER'
+                ? `Fuel surcharge (${scope.cargoType.cargoTypeName}, ${base} liters)`
+                : `Fuel surcharge (${scope.cargoType.cargoTypeName})`,
+            unit: toContractUnit(fuel.rateUnit),
+            unitPrice: convert(Number(fuel.rateValue)),
+            cargoTypeCode: scope.cargoType.code ?? null,
+            conditionalOn: 'has_fuel',
+          });
+        }
+      }
+    }
+
     // Empty-container return service — container contracts only, toggled on the
     // contract like hazard/reefer. Billed at booking per WITH_RETURN container.
     if (
diff --git a/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts b/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
index 2ab7e3d7e..3e76581a8 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
@@ -140,6 +140,27 @@ export class ContractsRepository extends BaseRepository<Contract> {
     return result.affected ?? 0;
   }
 
+  /**
+   * Same-row version of expireLapsedContracts, for lazy flips on read/booking
+   * paths — flips this one contract to EXPIRED if it's lapsed and not already
+   * terminal. No-op (returns false) if the contract isn't actually lapsed, so
+   * callers can call this unconditionally without a pre-check.
+   */
+  async expireIfLapsed(id: string): Promise<boolean> {
+    const result = await this.repository
+      .createQueryBuilder()
+      .update(Contract)
+      .set({ status: 'EXPIRED' })
+      .where('id = :id', { id })
+      .andWhere('deleted_at IS NULL')
+      .andWhere('status NOT IN (:...terminal)', { terminal: TERMINAL_CONTRACT_STATUSES })
+      .andWhere('contract_valid_until IS NOT NULL AND contract_valid_until < :now', {
+        now: new Date(),
+      })
+      .execute();
+    return (result.affected ?? 0) > 0;
+  }
+
   /**
    * Live contracts whose validity ends between `days` and `days + 1` days from
    * now — the slice the daily expiry-reminder cron warns about. The window is
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 6e170f126..c6379b4a6 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
@@ -811,6 +811,16 @@ export class ContractsService {
       throw new NotFoundException(`Contract ${id} not found`);
     }
 
+    // Lazy expiry flip: the nightly cron only sweeps once a day, so a
+    // contract can be past contract_valid_until for hours before it shows
+    // EXPIRED. Flip it here so the detail page never shows a stale status.
+    if (isEffectivelyExpired(contract) && contract.status !== 'EXPIRED') {
+      const flipped = await this.contractsRepository.expireIfLapsed(id);
+      if (flipped) {
+        contract.status = 'EXPIRED';
+      }
+    }
+
     if (contract.files && contract.files.length > 0) {
       contract.files = await Promise.all(
         contract.files.map(async (file: FileRecord) => {
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/ContractBookingWindowsSection.tsx b/apps/edr-freight-web/portal/src/pages/contracts/ContractBookingWindowsSection.tsx
index c4fa72977..73295cda0 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/ContractBookingWindowsSection.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/ContractBookingWindowsSection.tsx
@@ -211,6 +211,19 @@ function WindowCard({ w }: { w: MyBookingWindow }) {
                 </Text>
               </Fragment>
             ))}
+            {w.trainNumber ? (
+              <Text
+                fz={13}
+                fw={700}
+                style={{
+                  color: INK,
+                  flexShrink: 0,
+                  fontVariantNumeric: "tabular-nums",
+                }}
+              >
+                Train {w.trainNumber}
+              </Text>
+            ) : null}
           </Group>
 
           <Group gap={6} wrap="nowrap" mt={8}>
@@ -221,7 +234,7 @@ function WindowCard({ w }: { w: MyBookingWindow }) {
           </Group>
           {w.departureDate ? (
             <Text fz={12} style={{ color: MUTED }}>
-              Departs {fmtDay(w.departureDate)}
+              Departs {fmtDay(w.departureDate)}, {fmtTime(w.departureDate)}
             </Text>
           ) : null}
         </Box>

From f882104ed37691f840a195056380ee1772d5411a Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 11:23:10 +0000
Subject: [PATCH 050/174] fix(train-scheduling): move loose wagons and
 locomotives on train merge

---
 .../services/train-scheduling.service.ts      | 105 ++++++++++++++----
 .../utils/schedule-wagon-usage.util.spec.ts   |  17 +++
 .../utils/schedule-wagon-usage.util.ts        |  15 ++-
 .../TrainScheduleV2ListPage.tsx               |  31 ++----
 4 files changed, 123 insertions(+), 45 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index a740dc932..cdc43c5b2 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -330,6 +330,8 @@ const DEFAULT_TRAIN_LIMITS: Required<TrainLimitConfig> = {
 interface BookingWindowRow {
   schedule_id: string;
   reference: string | null;
+  /** Operational run number (e.g. 8001 import / 8002 export), typed by staff. */
+  train_number: string | null;
   contract_id: string | null;
   contract_kind: string | null;
   direction: string | null;
@@ -5872,6 +5874,7 @@ export class TrainSchedulingService {
         wagonSlots: schedule.trainSet?.wagons,
         storedWagonCount: schedule.trainSet?.wagonCount,
         scheduleBookings: schedule.scheduleBookings,
+        maxWagons: schedule.maxWagons,
       });
 
     return {
@@ -6847,6 +6850,7 @@ export class TrainSchedulingService {
       `SELECT DISTINCT ON (ts.id)
               ts.id AS schedule_id,
               ts.reference AS reference,
+              ts.train_number,
               cr.contract_id AS contract_id,
               c.contract_kind AS contract_kind,
               ts.direction,
@@ -6903,6 +6907,7 @@ export class TrainSchedulingService {
     const rows: Array<BookingWindowRow> = await this.dataSource.query(
       `SELECT DISTINCT ts.id AS schedule_id,
               ts.reference AS reference,
+              ts.train_number,
               cr.contract_id AS contract_id,
               c.contract_kind AS contract_kind,
               ts.direction,
@@ -6948,9 +6953,7 @@ export class TrainSchedulingService {
    */
   async listAllBookingWindows() {
     const rows: Array<
-      Omit<BookingWindowRow, 'contract_id' | 'contract_kind'> & {
-        train_number: string | null;
-      }
+      Omit<BookingWindowRow, 'contract_id' | 'contract_kind'>
     > = await this.dataSource.query(
       `SELECT ts.id AS schedule_id,
               ts.reference AS reference,
@@ -6980,14 +6983,13 @@ export class TrainSchedulingService {
           AND ts.scheduled_departure_date >= now()
         ORDER BY ts.scheduled_departure_date ASC NULLS LAST`,
     );
-    return rows.map((r) => ({
-      ...this.mapBookingWindowRow({
+    return rows.map((r) =>
+      this.mapBookingWindowRow({
         ...r,
         contract_id: null,
         contract_kind: null,
       }),
-      trainNumber: r.train_number,
-    }));
+    );
   }
 
   private mapBookingWindowRow(r: BookingWindowRow) {
@@ -7005,6 +7007,7 @@ export class TrainSchedulingService {
     return {
       scheduleId: r.schedule_id,
       reference: r.reference ?? null,
+      trainNumber: r.train_number ?? null,
       contractId: r.contract_id,
       contractKind: r.contract_kind,
       direction: r.direction,
@@ -9301,9 +9304,14 @@ export class TrainSchedulingService {
     }
 
     // Every schedule the target train is committed to, via its train sets.
+    // Locomotives come along: the merged train is pulled by the union of this
+    // schedule's locos and the target train's, so capacity checks need both.
     const targetSets = await this.dataSource
       .getRepository(TrainSet)
-      .find({ where: { trainId: targetTrainId } });
+      .find({
+        where: { trainId: targetTrainId },
+        relations: { locomotives: { locomotive: true }, locomotive: true },
+      });
     const targetSetIds = targetSets.map((s) => s.id);
     const targetSchedules = targetSetIds.length
       ? await this.dataSource.getRepository(TrainSchedule).find({
@@ -9346,6 +9354,24 @@ export class TrainSchedulingService {
       .getRepository(Wagon)
       .find({ where: { trainId: targetTrainId }, order: { wagonNumber: 'ASC' } });
 
+    // EVERY wagon physically on the source train moves with the merge — not
+    // just the ones coupled into this schedule's set. A wagon left behind
+    // would strand on the deactivated train. "Loose" = on the train but not
+    // backing a set slot; it joins the counts and the capacity math.
+    const sourceWagons = sourceTrainId
+      ? await this.dataSource
+          .getRepository(Wagon)
+          .find({ where: { trainId: sourceTrainId }, order: { wagonNumber: 'ASC' } })
+      : [];
+    const coupledPhysicalIds = new Set(
+      (schedule.trainSet?.wagons ?? [])
+        .map((w) => w.physicalWagonId)
+        .filter(Boolean),
+    );
+    const looseSourceWagons = sourceWagons.filter(
+      (w) => !coupledPhysicalIds.has(w.id),
+    );
+
     const movingBookings = absorbed
       ? await this.dataSource.getRepository(TrainScheduleBooking).find({
           where: { trainScheduleId: absorbed.id },
@@ -9357,10 +9383,12 @@ export class TrainSchedulingService {
       schedule,
       sourceTrainId,
       targetTrain,
+      targetSets,
       absorbed,
       affectedOthers,
       untouched,
       incomingWagons,
+      looseSourceWagons,
       movingBookings,
     };
   }
@@ -9382,14 +9410,20 @@ export class TrainSchedulingService {
       );
     }
 
-    // ── Capacity: the merged consist must fit this schedule's locomotives ────
+    // ── Capacity: the merged consist must fit the merged train's locomotives ─
+    // Existing side = coupled set slots PLUS loose wagons riding the source
+    // train without a slot — they all move, so they all count.
     const existingSlots = (schedule.trainSet?.wagons ?? []).map((w) => ({
       lengthMeters: Number(w.lengthMeters) || 0,
       tareWeightTons: Number(w.wagonType?.tareWeightTons) || 0,
       cargoTons: 0,
     }));
     const wagonTypeIds = [
-      ...new Set(incomingWagons.map((w) => w.wagonTypeId).filter(Boolean)),
+      ...new Set(
+        [...incomingWagons, ...plan.looseSourceWagons]
+          .map((w) => w.wagonTypeId)
+          .filter(Boolean),
+      ),
     ];
     const wagonTypes = wagonTypeIds.length
       ? await this.dataSource
@@ -9397,16 +9431,27 @@ export class TrainSchedulingService {
           .find({ where: { id: In(wagonTypeIds) } })
       : [];
     const typeById = new Map(wagonTypes.map((t) => [t.id, t]));
-    const incomingSlots = incomingWagons.map((w) => {
+    const slotFromWagon = (w: Wagon) => {
       const t = typeById.get(w.wagonTypeId);
       return {
         lengthMeters: Number(t?.lengthMeters) || 0,
         tareWeightTons: Number(t?.tareWeightTons) || 0,
         cargoTons: 0,
       };
-    });
+    };
+    const incomingSlots = incomingWagons.map(slotFromWagon);
+    const looseSlots = plan.looseSourceWagons.map(slotFromWagon);
 
-    const limits = trainSetLocomotiveLimits(schedule.trainSet);
+    // The merged train is pulled by the union of this schedule's locomotives
+    // and whatever already pulls the target train (its sets keep their locos).
+    // Pull weight adds up across the pool; length stays the tightest cap.
+    const locoPool = [
+      ...this.locomotivesOfTrainSet(schedule.trainSet),
+      ...plan.targetSets.flatMap((set) => this.locomotivesOfTrainSet(set)),
+    ];
+    const limits = combinedLocomotiveLimits([
+      ...new Map(locoPool.map((l) => [l.id, l])).values(),
+    ]);
     if (limits) {
       const rules = await this.dataSource
         .getRepository(TrainSchedulingGlobalRules)
@@ -9415,13 +9460,17 @@ export class TrainSchedulingService {
         maxTrainWeightTons: rules[0]?.maxTrainWeightTons ?? undefined,
         maxTrainLengthMeters: rules[0]?.maxTrainLengthMeters ?? undefined,
       });
-      const merged = [...existingSlots, ...incomingSlots];
-      // maxWagons is the schedule's own slot ceiling; fall back to the consist
-      // size when it is unset so the count axis never blocks spuriously.
+      const merged = [...existingSlots, ...looseSlots, ...incomingSlots];
+      // Merge is a physical consist move, so only the physical axes gate it:
+      // can this schedule's locomotives pull the merged weight and length.
+      // `schedule.maxWagons` is the booking-window planning ceiling — using it
+      // as a slot cap here blocked every merge into a bigger train (e.g. a
+      // 3-wagon plan absorbing a 47-wagon train). The commit raises the
+      // ceiling to the merged size instead.
       const violations = consistViolations(merged, {
         maxWeightTons: caps.maxWeightTons,
         maxLengthMeters: caps.maxLengthMeters,
-        maxWagonSlots: schedule.maxWagons || merged.length,
+        maxWagonSlots: merged.length,
       });
       blockers.push(...violations);
     }
@@ -9481,7 +9530,10 @@ export class TrainSchedulingService {
     const plan = await this.planMerge(scheduleId, targetTrainId);
     const blockers = await this.mergeBlockers(plan);
 
-    const existingCount = plan.schedule.trainSet?.wagons?.length ?? 0;
+    // Coupled slots plus loose wagons on the source train — everything moves.
+    const existingCount =
+      (plan.schedule.trainSet?.wagons?.length ?? 0) +
+      plan.looseSourceWagons.length;
     return {
       canMerge: blockers.length === 0,
       blockers,
@@ -9555,13 +9607,20 @@ export class TrainSchedulingService {
         trainId: targetTrain.id,
       });
 
-      // 2. The physical wagons follow the train.
+      // 2. The physical wagons follow the train — the target's stay put, and
+      //    EVERY wagon on the source train (coupled or loose) moves across so
+      //    nothing strands on the deactivated train.
       if (incomingWagons.length) {
         await manager.getRepository(Wagon).update(
           { id: In(incomingWagons.map((w) => w.id)) },
           { trainId: targetTrain.id },
         );
       }
+      if (sourceTrainId) {
+        await manager
+          .getRepository(Wagon)
+          .update({ trainId: sourceTrainId }, { trainId: targetTrain.id });
+      }
 
       // 3. Carry the target's train-set wagon rows into THIS consist, appended
       //    after the existing wagons. Sequence is provisional — staff reorder
@@ -9611,6 +9670,14 @@ export class TrainSchedulingService {
       await manager
         .getRepository(TrainSet)
         .update(trainSetId, { wagonCount: mergedCount });
+
+      // 8. Booking capacity follows the consist: raise (never lower) the
+      //    planning ceiling so the merged wagons are actually sellable.
+      if (mergedCount > (schedule.maxWagons ?? 0)) {
+        await manager
+          .getRepository(TrainSchedule)
+          .update(schedule.id, { maxWagons: mergedCount });
+      }
     });
 
     this.logger.log(
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.spec.ts
index 8fa9c1260..6507b8a8c 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.spec.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.spec.ts
@@ -68,6 +68,23 @@ describe('computeScheduleWagonUsage', () => {
     expect(usage.wagonsRemaining).toBe(0);
   });
 
+  it('sells against the planned ceiling, not the partially coupled consist', () => {
+    // S-2026-00003: planned 3 wagons, 2 coupled + allocated for a paid booking
+    // that reserved 2 — the list read "2/2 used, 0 bookable" while the detail
+    // page and the booking gate (remainingWagonsForLeg vs maxWagons) both said
+    // 1 wagon was still free. Wagons couple on demand; the ceiling is capacity.
+    const usage = computeScheduleWagonUsage({
+      wagonSlots: Array(2).fill(slot(true)),
+      storedWagonCount: 2,
+      scheduleBookings: [booking(2)],
+      maxWagons: 3,
+    });
+
+    expect(usage.wagonsUsed).toBe(2);
+    expect(usage.wagonsTotal).toBe(3);
+    expect(usage.wagonsRemaining).toBe(1);
+  });
+
   it('falls back to the stored counter when slot rows were not loaded', () => {
     const usage = computeScheduleWagonUsage({
       wagonSlots: [],
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.ts b/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.ts
index f48d60f9a..899e4c066 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/utils/schedule-wagon-usage.util.ts
@@ -20,11 +20,11 @@ export interface ScheduleBookingLike {
 export interface ScheduleWagonUsage {
   /** Coupled slots carrying at least one booking allocation. */
   wagonsUsed: number;
-  /** Coupled consist size — the denominator of `wagonsUsed`. */
+  /** Schedule capacity — the larger of coupled consist and planned ceiling. */
   wagonsTotal: number;
   /** Wagons claimed by bookings, including bookings that have not paid. */
   wagonsReserved: number;
-  /** Consist minus what bookings have claimed — what is still bookable. */
+  /** Capacity minus what bookings have claimed — what is still bookable. */
   wagonsRemaining: number;
 }
 
@@ -33,6 +33,8 @@ export function computeScheduleWagonUsage(input: {
   /** Stored counter; used only when the slot rows were not loaded. */
   storedWagonCount?: number | null;
   scheduleBookings?: ScheduleBookingLike[] | null;
+  /** Planned wagon ceiling (`maxWagons`) — what booking capacity is sold against. */
+  maxWagons?: number | null;
 }): ScheduleWagonUsage {
   const slots = input.wagonSlots ?? [];
 
@@ -42,7 +44,14 @@ export function computeScheduleWagonUsage(input: {
 
   // Prefer live slot rows; the stored counter drifts when a consist is edited
   // without a recompute, which is why the list and detail disagreed on totals.
-  const wagonsTotal = slots.length || (input.storedWagonCount ?? 0);
+  const coupled = slots.length || (input.storedWagonCount ?? 0);
+
+  // Wagons are coupled on demand as bookings are allocated, so a partially
+  // built consist does not cap what is bookable — the planned ceiling does
+  // (remainingWagonsForLeg sells against maxWagons). Without this, a schedule
+  // planned for 3 wagons with 2 coupled+allocated read "2/2 used, 0 bookable"
+  // while its detail page and the booking gate both said 1 wagon was free.
+  const wagonsTotal = Math.max(coupled, input.maxWagons ?? 0);
 
   // An unpaid booking still holds its wagons, so reserved space is NOT bookable.
   const wagonsReserved = (input.scheduleBookings ?? []).reduce(
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 9755e6bee..51899fc51 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
@@ -1019,14 +1019,11 @@ export default function TrainScheduleV2ListPage() {
 
 /**
  * The row's wagon chips, matching the detail page's wagon plan: used is slots
- * carrying a booking allocation (never the coupled consist size), and remaining
- * excludes wagons reserved by bookings that have not paid yet — that space is
- * claimed, so it is not bookable.
- *
- * Schedules whose train set has not been built yet have no consist to measure,
- * so both figures fall back to the schedule's planned `maxWagons` ceiling.
- * Without that fallback an unbuilt 37-wagon schedule reads "0 bookable" even
- * though every one of its wagons is still free.
+ * carrying a booking allocation, the denominator is the schedule's capacity
+ * (API-computed: the larger of coupled consist and planned `maxWagons`, since
+ * wagons are coupled on demand), and remaining excludes wagons reserved by
+ * bookings that have not paid yet — that space is claimed, so it is not
+ * bookable.
  */
 function WagonChips({ schedule }: { schedule: TrainScheduleListItem }) {
   // Pre-deploy API rows carry only wagonCount; fall back so the chip still
@@ -1034,17 +1031,7 @@ function WagonChips({ schedule }: { schedule: TrainScheduleListItem }) {
   const total = schedule.wagonsTotal ?? schedule.wagonCount;
   const used = schedule.wagonsUsed;
   const reserved = schedule.wagonsReserved ?? 0;
-
-  // Until the train set is built there is no consist to measure against, so
-  // `wagonsRemaining` (consist minus claimed) is 0 on every unbuilt schedule —
-  // which reads as "fully booked" when in fact nothing is booked at all. Before
-  // a consist exists, capacity is the planned ceiling minus what bookings have
-  // already claimed.
-  const planCeiling = schedule.maxWagons ?? 0;
-  const remaining =
-    total === 0 && planCeiling > 0
-      ? Math.max(0, planCeiling - Math.max(used ?? 0, reserved))
-      : schedule.wagonsRemaining;
+  const remaining = schedule.wagonsRemaining;
 
   if (used == null) {
     return <MetricChip value={total} label="wgn" subtle />;
@@ -1052,11 +1039,9 @@ function WagonChips({ schedule }: { schedule: TrainScheduleListItem }) {
 
   return (
     <>
-      {/* An unbuilt consist has no "used out of coupled" to show; the plan
-          ceiling is the only meaningful denominator at that point. */}
       <MetricChip
-        value={total === 0 && planCeiling > 0 ? `${used}/${planCeiling}` : `${used}/${total}`}
-        label={total === 0 && planCeiling > 0 ? "wgn planned" : "wgn used"}
+        value={`${used}/${total}`}
+        label={schedule.wagonCount === 0 ? "wgn planned" : "wgn used"}
       />
       {reserved > used ? (
         <MetricChip value={reserved} label="reserved" subtle />

From 08c8b52f85bb07adacd5b887ffe907aa262c2d87 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 11:23:19 +0000
Subject: [PATCH 051/174] feat(portal): show payer account note and train
 number on booking windows

---
 .../components/UpcomingWindowsSection.tsx     | 16 +++++++-
 .../components/BookingPaymentPanel.tsx        |  2 +
 .../components/PaymentMethodModal.tsx         |  5 +++
 .../bookings/payments/PayerAccountNote.tsx    | 39 +++++++++++++++++++
 .../portal/src/services/bookings.service.ts   |  2 +
 5 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 apps/edr-freight-web/portal/src/pages/bookings/payments/PayerAccountNote.tsx

diff --git a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/UpcomingWindowsSection.tsx b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/UpcomingWindowsSection.tsx
index c4bb03ed6..556a96282 100644
--- a/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/UpcomingWindowsSection.tsx
+++ b/apps/edr-freight-web/portal/src/pages/MyPortalPage/components/UpcomingWindowsSection.tsx
@@ -321,6 +321,19 @@ export const UpcomingWindowsSection = memo(function UpcomingWindowsSection({
                       </Text>
                     </Fragment>
                   ))}
+                  {w.trainNumber && (
+                    <Text
+                      fz={13}
+                      fw={700}
+                      style={{
+                        color: INK,
+                        flexShrink: 0,
+                        fontVariantNumeric: "tabular-nums",
+                      }}
+                    >
+                      Train {w.trainNumber}
+                    </Text>
+                  )}
                   {w.reference && (
                     <Text
                       fz={11}
@@ -338,7 +351,8 @@ export const UpcomingWindowsSection = memo(function UpcomingWindowsSection({
                 <Group gap={5} wrap="nowrap" mt={2}>
                   <CalendarClock size={12} color={MUTED} style={{ flexShrink: 0 }} />
                   <Text fz={12} style={{ color: MUTED }} truncate>
-                    {windowLabel(w)} · Departs {fmtDay(w.departureDate)}
+                    {windowLabel(w)} · Departs {fmtDay(w.departureDate)},{" "}
+                    {fmtTime(w.departureDate)}
                   </Text>
                 </Group>
                 {(() => {
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/BookingPaymentPanel.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/BookingPaymentPanel.tsx
index 710c6b40f..0f691d6ea 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/BookingPaymentPanel.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/BookingPaymentPanel.tsx
@@ -18,6 +18,7 @@ import { invoicesService, type PortalInvoice } from "@/services/invoices.service
 import { InvoiceStatusBadge, titleCase } from "@/pages/billing/invoice-ui";
 import { paymentStatusLabel } from "@/pages/bookings/booking-display";
 import { isUsdOfflineBooking } from "@/pages/bookings/payments/offline-payment";
+import { PayerAccountNote } from "@/pages/bookings/payments/PayerAccountNote";
 import { payWindowState } from "@/pages/bookings/payments/payment-drain";
 import { PaymentProcessingNotice } from "@/pages/bookings/payments/PaymentProcessingNotice";
 import { saveBlob } from "@/utils/download";
@@ -321,6 +322,7 @@ export function BookingPaymentPanel({
             onPay={offlineUsd ? undefined : onPay}
             paying={paying}
           />
+          {!paid && <PayerAccountNote />}
           {showConsolidationNote && (
             <Text mt={12} fz="12px" c="#9AA8B5" lh={1.5}>
               This shipment shares a wagon with a consolidation partner — both
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/PaymentMethodModal.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/PaymentMethodModal.tsx
index f4f1c7c3c..00c6bdd7c 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/PaymentMethodModal.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/PaymentMethodModal.tsx
@@ -13,6 +13,7 @@ import { Check, Landmark, ShieldCheck } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
 
 import type { InvoicePaymentFlow } from "@/hooks/useInvoicePayment";
+import { PayerAccountNote } from "@/pages/bookings/payments/PayerAccountNote";
 import type { PaymentMethod } from "@/services/payments.service";
 
 interface ProviderOption {
@@ -306,6 +307,8 @@ export function PaymentMethodModal({
             </Text>
           )}
 
+          <PayerAccountNote />
+
           <Text mt={14} fz="11.5px" c="#9AA8B5">
             This page updates automatically once CBE confirms your payment.
           </Text>
@@ -449,6 +452,8 @@ export function PaymentMethodModal({
             </Text>
           </Group>
         )}
+
+        <PayerAccountNote />
       </Box>
 
       {/* Provider options */}
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/payments/PayerAccountNote.tsx b/apps/edr-freight-web/portal/src/pages/bookings/payments/PayerAccountNote.tsx
new file mode 100644
index 000000000..73bd4962f
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/bookings/payments/PayerAccountNote.tsx
@@ -0,0 +1,39 @@
+import { Box, Text } from "@mantine/core";
+
+import useAuth from "@/hooks/useAuth";
+
+/**
+ * Red payer-identity warning shown wherever the customer is about to pay:
+ * the transfer must come from a bank account held in the company's registered
+ * name, otherwise Finance will not recognize the payment as paid.
+ */
+export function PayerAccountNote() {
+  const { company } = useAuth();
+  const name = company?.company?.name;
+
+  return (
+    <Box
+      mt={12}
+      p={12}
+      style={{
+        borderRadius: 10,
+        backgroundColor: "#FDEDEB",
+        border: "1px solid #F5C6C0",
+      }}
+    >
+      <Text fz="12.5px" fw={700} c="#C0392B" lh={1.55}>
+        Pay only from a bank account registered under your company name
+        {name ? (
+          <>
+            {" — "}
+            <Text span fw={800} c="#A93226">
+              {name}
+            </Text>
+          </>
+        ) : null}
+        . A payment sent from an account under any other name will not be
+        recognized as paid.
+      </Text>
+    </Box>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/services/bookings.service.ts b/apps/edr-freight-web/portal/src/services/bookings.service.ts
index cad07b0c6..b196ed968 100644
--- a/apps/edr-freight-web/portal/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/portal/src/services/bookings.service.ts
@@ -77,6 +77,8 @@ export interface MyBookingWindow {
   scheduleId: string;
   /** Train schedule reference (e.g. TS-2026-000123), shown on the window card. */
   reference: string | null;
+  /** Operational run number (e.g. 8001 import / 8002 export), when staff set one. */
+  trainNumber: string | null;
   /**
    * The customer's active contract on this lane, when they hold one — enables
    * "Book now" to target it. Null for lanes they have no contract on.

From 0f1bac8080599fe06e256a84fdc4dd52ed34623e Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 12 Aug 2026 11:35:36 +0000
Subject: [PATCH 052/174] feat(freight-api): add non-PII auth context to
 request log line

---
 .../src/common/request-log-context.spec.ts    | 57 ++++++++++++-
 .../src/logging/request-log.middleware.ts     | 84 +++++++++++++++++--
 2 files changed, 132 insertions(+), 9 deletions(-)

diff --git a/apps/edr-freight-api/src/common/request-log-context.spec.ts b/apps/edr-freight-api/src/common/request-log-context.spec.ts
index 403b1a137..e898cb930 100644
--- a/apps/edr-freight-api/src/common/request-log-context.spec.ts
+++ b/apps/edr-freight-api/src/common/request-log-context.spec.ts
@@ -65,10 +65,40 @@ describe("RequestLogMiddleware", () => {
       originalUrl: "/api/bookings/1/submit?dry=1",
       baseUrl: "/api/bookings",
       route: { path: "/:id/submit" },
-      headers: { "user-agent": "jest", "x-request-id": "req-42" },
+      headers: {
+        "user-agent": "jest",
+        "x-request-id": "req-42",
+        authorization: "Bearer tok",
+        "x-client-app": "freight-backoffice",
+        "current-project-id": "proj-3",
+      },
       ip: "10.0.0.1",
       query: { dry: "1" },
-      user: { id: "u-7" },
+      user: {
+        id: "u-7",
+        sessionId: "sess-9",
+        userType: "STAFF",
+        status: "ACTIVE",
+        username: "nati",
+        email: "nati@example.com",
+        phoneNumber: "0911000000",
+        name: { en: "Nati" },
+        roles: [{ key: "freight_operations" }],
+        permissions: [{ key: "a" }, { key: "b" }],
+        employee: {
+          id: "emp-1",
+          organizationId: "org-1",
+          unitId: "unit-2",
+          position: {
+            id: "pos-5",
+            key: "ops_officer",
+            employeePositionId: "ep-6",
+            isDelegate: true,
+            delegatorId: "pos-1",
+            positionType: { key: "operations" },
+          },
+        },
+      },
     };
     const res = {
       statusCode: 409,
@@ -105,6 +135,29 @@ describe("RequestLogMiddleware", () => {
       bookingId: "b-1",
       booking: { outcome: "REJECTED" },
     });
+    expect(JSON.parse(lines[0]).auth).toEqual({
+      authenticated: true,
+      hasBearer: true,
+      clientApp: "freight-backoffice",
+      userId: "u-7",
+      sessionId: "sess-9",
+      userType: "STAFF",
+      userStatus: "ACTIVE",
+      roles: ["freight_operations"],
+      permissionCount: 2,
+      employeeId: "emp-1",
+      organizationId: "org-1",
+      unitId: "unit-2",
+      positionId: "pos-5",
+      positionKey: "ops_officer",
+      positionType: "operations",
+      employeePositionId: "ep-6",
+      isDelegate: true,
+      delegatorId: "pos-1",
+      projectId: "proj-3",
+    });
+    // No personal data reaches the line, whatever the token carried.
+    expect(lines[0]).not.toMatch(/nati|example\.com|0911000000/);
     expect(res.setHeader).toHaveBeenCalledWith("x-request-id", "req-42");
     jest.restoreAllMocks();
   });
diff --git a/packages/api-common/src/logging/request-log.middleware.ts b/packages/api-common/src/logging/request-log.middleware.ts
index 5d9ead8b0..4144e72c8 100644
--- a/packages/api-common/src/logging/request-log.middleware.ts
+++ b/packages/api-common/src/logging/request-log.middleware.ts
@@ -20,7 +20,39 @@ interface LoggedRequest {
   headers: Record<string, string | string[] | undefined>;
   ip?: string;
   query?: Record<string, unknown>;
-  user?: Record<string, unknown> | null;
+  /** Set by the IAM JwtGuard AFTER this middleware runs — read at emit time. */
+  user?: AuthenticatedUser | null;
+  currentUnitId?: string;
+}
+
+/**
+ * The subset of `TCurrentUser` (@tria-plc/api-common) the log line reads.
+ * Everything here is an identifier, a key or a status — the personal fields on
+ * that type (name, email, username, phoneNumber) are deliberately absent so
+ * they cannot be picked up by accident.
+ */
+interface AuthenticatedUser {
+  id?: string;
+  sub?: string;
+  userId?: string;
+  sessionId?: string;
+  userType?: string;
+  status?: string;
+  roles?: { key?: string }[];
+  permissions?: unknown[];
+  employee?: {
+    id?: string;
+    organizationId?: string;
+    unitId?: string;
+    position?: {
+      id?: string;
+      key?: string;
+      employeePositionId?: string;
+      isDelegate?: boolean;
+      delegatorId?: string;
+      positionType?: { key?: string };
+    };
+  };
 }
 
 interface LoggedResponse {
@@ -35,13 +67,48 @@ const header = (req: LoggedRequest, name: string): string | undefined => {
   return Array.isArray(value) ? value[0] : value;
 };
 
-const userId = (req: LoggedRequest): string | undefined => {
+const userId = (req: LoggedRequest): string | undefined =>
+  req.user?.id ?? req.user?.sub ?? req.user?.userId;
+
+/**
+ * Who the caller was acting as — WITHOUT any personal data. Ids, role/position
+ * keys and statuses only: enough to answer "which desk did this", "was it a
+ * delegate", "which tenant", and to spot an authorization problem, with nothing
+ * that identifies the human behind the account beyond the opaque user id.
+ *
+ * `authenticated: false` with `hasBearer: true` is the signature of a rejected
+ * token (expired session, bad signature) as opposed to a missing one.
+ */
+const authContext = (req: LoggedRequest): Record<string, unknown> => {
   const user = req.user;
-  if (!user) return undefined;
-  const id = user.id ?? user.sub ?? user.userId;
-  return typeof id === "string" || typeof id === "number"
-    ? String(id)
-    : undefined;
+  const position = user?.employee?.position;
+  return {
+    authenticated: Boolean(user),
+    hasBearer: header(req, "authorization")?.startsWith("Bearer ") ?? false,
+    // Which frontend called — /auth/login rejects cross-audience credentials on it.
+    clientApp: header(req, "x-client-app"),
+    userId: userId(req),
+    sessionId: user?.sessionId,
+    userType: user?.userType,
+    userStatus: user?.status,
+    roles: user?.roles?.map((role) => role.key).filter(Boolean),
+    // Count only: the full grant list is hundreds of keys and would dwarf the line.
+    permissionCount: user?.permissions?.length,
+    employeeId: user?.employee?.id,
+    organizationId: user?.employee?.organizationId,
+    unitId: user?.employee?.unitId ?? req.currentUnitId,
+    positionId: position?.id,
+    positionKey: position?.key,
+    positionType: position?.positionType?.key,
+    employeePositionId: position?.employeePositionId,
+    // Acting on someone else's behalf — the first thing to check when a staff
+    // action lands under an unexpected desk.
+    isDelegate: position?.isDelegate,
+    delegatorId: position?.delegatorId,
+    // Tenant/scope headers the frontends send alongside the token.
+    projectId:
+      header(req, "current-project-id") ?? header(req, "x-current-project-id"),
+  };
 };
 
 /**
@@ -101,6 +168,9 @@ export class RequestLogMiddleware implements NestMiddleware {
           status,
           durationMs,
           userId: userId(req),
+          // Read at emit time on purpose: the guard populates req.user long
+          // after this middleware handed control on.
+          auth: authContext(req),
           ip: req.ip,
           userAgent: header(req, "user-agent"),
           query:

From 5a856027af0d8a92daa32e832ab1809fa0fb889f Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 12 Aug 2026 12:27:15 +0000
Subject: [PATCH 053/174] feat: add email and password

---
 .../components/profile/ChangeEmailCard.tsx    | 172 ++++++++++++++++++
 .../components/profile/ChangePasswordCard.tsx | 154 ++++++++++++++++
 .../backoffice/src/layout/TopBar.tsx          |   2 +-
 .../backoffice/src/pages/HomePage/Header.tsx  |   2 +-
 .../src/pages/dashboard/MyProfilePage.tsx     |   4 +
 .../components/common/Top.tsx                 |   2 +-
 .../src/services/account.service.ts           |  50 +++++
 .../backoffice/src/services/api.ts            |  29 +++
 8 files changed, 412 insertions(+), 3 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/profile/ChangeEmailCard.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/profile/ChangePasswordCard.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/services/account.service.ts

diff --git a/apps/edr-freight-web/backoffice/src/components/profile/ChangeEmailCard.tsx b/apps/edr-freight-web/backoffice/src/components/profile/ChangeEmailCard.tsx
new file mode 100644
index 000000000..650616049
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/profile/ChangeEmailCard.tsx
@@ -0,0 +1,172 @@
+import { useState } from "react";
+import { Mail, Loader2 } from "lucide-react";
+import { useMutation } from "@tanstack/react-query";
+import toast from "react-hot-toast";
+
+import { api } from "@/services/api";
+import { useAuth } from "@/auth/useAuth";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  Input,
+  Label,
+} from "@edr/ui-common";
+
+/**
+ * Lets the signed-in backoffice user change their own email. Goes through
+ * /me/contact/otp + /me/contact rather than the generic (unverified)
+ * /auth/update-profile route, so the new address is proven before it's
+ * written — see account.controller.ts on the API side.
+ */
+export function ChangeEmailCard() {
+  const { user } = useAuth();
+  const sendOtpMutation = useMutation(
+    api.account.sendContactOtp.mutationOptions(),
+  );
+  const updateContactMutation = useMutation(
+    api.account.updateContact.mutationOptions(),
+  );
+
+  const [open, setOpen] = useState(false);
+  const [step, setStep] = useState<"enterEmail" | "enterOtp">("enterEmail");
+  const [newEmail, setNewEmail] = useState("");
+  const [otp, setOtp] = useState("");
+  const [formError, setFormError] = useState("");
+
+  const closeDialog = () => {
+    setOpen(false);
+    setStep("enterEmail");
+    setNewEmail("");
+    setOtp("");
+    setFormError("");
+  };
+
+  const sendOtp = () => {
+    setFormError("");
+    if (!newEmail.trim()) {
+      setFormError("Enter the new email address.");
+      return;
+    }
+
+    sendOtpMutation.mutate(
+      { channel: "email", value: newEmail.trim() },
+      {
+        onSuccess: (result) => {
+          toast.success(`Verification code sent to ${result.sentTo}`);
+          setStep("enterOtp");
+        },
+      },
+    );
+  };
+
+  const confirmOtp = () => {
+    setFormError("");
+    if (!otp.trim()) {
+      setFormError("Enter the verification code.");
+      return;
+    }
+
+    updateContactMutation.mutate(
+      { channel: "email", value: newEmail.trim(), otp: otp.trim() },
+      {
+        onSuccess: () => {
+          toast.success("Email updated.");
+          closeDialog();
+          // Refetches the session so the new email shows everywhere — simplest
+          // way to refresh the cached user without a dedicated context method.
+          window.location.reload();
+        },
+      },
+    );
+  };
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2">
+          <Mail className="size-4" />
+          Email
+        </CardTitle>
+        <CardDescription>
+          {user?.email ? `Current email: ${user.email}` : "Change your account email."}
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Button variant="outline" size="sm" onClick={() => setOpen(true)}>
+          Change email
+        </Button>
+      </CardContent>
+
+      <Dialog open={open} onOpenChange={(next) => !next && closeDialog()}>
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Change email</DialogTitle>
+            <DialogDescription>
+              {step === "enterEmail"
+                ? "We'll send a verification code to the new address."
+                : `Enter the code sent to ${newEmail}.`}
+            </DialogDescription>
+          </DialogHeader>
+
+          {step === "enterEmail" ? (
+            <div className="space-y-2">
+              <Label htmlFor="newEmail">New email</Label>
+              <Input
+                id="newEmail"
+                type="email"
+                value={newEmail}
+                onChange={(e) => setNewEmail(e.target.value)}
+              />
+              {formError && <p className="text-sm text-destructive">{formError}</p>}
+            </div>
+          ) : (
+            <div className="space-y-2">
+              <Label htmlFor="otp">Verification code</Label>
+              <Input
+                id="otp"
+                value={otp}
+                onChange={(e) => setOtp(e.target.value)}
+              />
+              {formError && <p className="text-sm text-destructive">{formError}</p>}
+            </div>
+          )}
+
+          <DialogFooter>
+            <Button variant="outline" onClick={closeDialog}>
+              Cancel
+            </Button>
+            {step === "enterEmail" ? (
+              <Button disabled={sendOtpMutation.isPending} onClick={sendOtp}>
+                {sendOtpMutation.isPending ? (
+                  <Loader2 className="size-4 animate-spin" />
+                ) : (
+                  "Send code"
+                )}
+              </Button>
+            ) : (
+              <Button disabled={updateContactMutation.isPending} onClick={confirmOtp}>
+                {updateContactMutation.isPending ? (
+                  <Loader2 className="size-4 animate-spin" />
+                ) : (
+                  "Confirm"
+                )}
+              </Button>
+            )}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </Card>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/profile/ChangePasswordCard.tsx b/apps/edr-freight-web/backoffice/src/components/profile/ChangePasswordCard.tsx
new file mode 100644
index 000000000..fb5f9086e
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/profile/ChangePasswordCard.tsx
@@ -0,0 +1,154 @@
+import { useState } from "react";
+import { KeyRound, Loader2 } from "lucide-react";
+import { useMutation } from "@tanstack/react-query";
+import toast from "react-hot-toast";
+
+import { api } from "@/services/api";
+import { useAuth } from "@/auth/useAuth";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  Input,
+  Label,
+} from "@edr/ui-common";
+
+/**
+ * Lets the signed-in backoffice user change their own password. The account
+ * is logged out on success — the old token was issued under the old
+ * password, and this forces a clean re-login rather than trusting the
+ * server to keep the existing session valid.
+ */
+export function ChangePasswordCard() {
+  const { logout } = useAuth();
+  const changePasswordMutation = useMutation(
+    api.account.changePassword.mutationOptions(),
+  );
+
+  const [open, setOpen] = useState(false);
+  const [oldPassword, setOldPassword] = useState("");
+  const [newPassword, setNewPassword] = useState("");
+  const [confirmPassword, setConfirmPassword] = useState("");
+  const [formError, setFormError] = useState("");
+
+  const closeDialog = () => {
+    setOpen(false);
+    setOldPassword("");
+    setNewPassword("");
+    setConfirmPassword("");
+    setFormError("");
+  };
+
+  const submit = () => {
+    setFormError("");
+
+    if (!oldPassword || !newPassword || !confirmPassword) {
+      setFormError("All fields are required.");
+      return;
+    }
+    if (newPassword.length < 8) {
+      setFormError("New password must be at least 8 characters.");
+      return;
+    }
+    if (newPassword === oldPassword) {
+      setFormError("New password must be different from the current one.");
+      return;
+    }
+    if (newPassword !== confirmPassword) {
+      setFormError("New password and confirmation do not match.");
+      return;
+    }
+
+    changePasswordMutation.mutate(
+      { oldPassword, newPassword, confirmPassword },
+      {
+        onSuccess: () => {
+          toast.success("Password changed. Please sign in again.");
+          closeDialog();
+          setTimeout(logout, 1200);
+        },
+      },
+    );
+  };
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2">
+          <KeyRound className="size-4" />
+          Password
+        </CardTitle>
+        <CardDescription>Change the password for your account.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Button variant="outline" size="sm" onClick={() => setOpen(true)}>
+          Change password
+        </Button>
+      </CardContent>
+
+      <Dialog open={open} onOpenChange={(next) => !next && closeDialog()}>
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Change password</DialogTitle>
+            <DialogDescription>
+              You'll be signed out and asked to log in again once it's changed.
+            </DialogDescription>
+          </DialogHeader>
+          <div className="space-y-4">
+            <div className="space-y-2">
+              <Label htmlFor="oldPassword">Current password</Label>
+              <Input
+                id="oldPassword"
+                type="password"
+                value={oldPassword}
+                onChange={(e) => setOldPassword(e.target.value)}
+              />
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="newPassword">New password</Label>
+              <Input
+                id="newPassword"
+                type="password"
+                value={newPassword}
+                onChange={(e) => setNewPassword(e.target.value)}
+              />
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="confirmPassword">Confirm new password</Label>
+              <Input
+                id="confirmPassword"
+                type="password"
+                value={confirmPassword}
+                onChange={(e) => setConfirmPassword(e.target.value)}
+              />
+            </div>
+            {formError && <p className="text-sm text-destructive">{formError}</p>}
+          </div>
+          <DialogFooter>
+            <Button variant="outline" onClick={closeDialog}>
+              Cancel
+            </Button>
+            <Button disabled={changePasswordMutation.isPending} onClick={submit}>
+              {changePasswordMutation.isPending ? (
+                <Loader2 className="size-4 animate-spin" />
+              ) : (
+                "Change password"
+              )}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </Card>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/layout/TopBar.tsx b/apps/edr-freight-web/backoffice/src/layout/TopBar.tsx
index 708a5a3ca..c7bd1b197 100644
--- a/apps/edr-freight-web/backoffice/src/layout/TopBar.tsx
+++ b/apps/edr-freight-web/backoffice/src/layout/TopBar.tsx
@@ -319,7 +319,7 @@ export const TopBar = () => {
               {t("header.viewProfile")}
             </DropdownMenuItem>
             <DropdownMenuItem
-              onClick={() => navigate("/change-password")}
+              onClick={() => navigate("/dashboard/profile")}
               className="cursor-pointer hover:bg-primary-50 dark:hover:bg-primary-900/30 hover:text-primary-700 dark:hover:text-primary-400 py-2.5">
               <Key className="w-4 h-4 mr-3" />
               {t("header.changePassword")}
diff --git a/apps/edr-freight-web/backoffice/src/pages/HomePage/Header.tsx b/apps/edr-freight-web/backoffice/src/pages/HomePage/Header.tsx
index ed569a83d..46ddcfe7d 100644
--- a/apps/edr-freight-web/backoffice/src/pages/HomePage/Header.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/HomePage/Header.tsx
@@ -502,7 +502,7 @@ const Header = () => {
 
                   <DropdownMenuItem
                     className="flex items-center gap-3 px-3 py-2.5 text-sm text-gray-700 dark:text-gray-300 hover:bg-primary-50 dark:hover:bg-primary-900/30 hover:text-primary-700 dark:hover:text-primary-400 rounded-lg cursor-pointer transition-colors"
-                    onClick={() => navigate("/change-password")}
+                    onClick={() => navigate("/dashboard/profile")}
                   >
                     <Key className="w-4 h-4 text-primary-600 dark:text-primary-400" />
                     <span className="font-medium">
diff --git a/apps/edr-freight-web/backoffice/src/pages/dashboard/MyProfilePage.tsx b/apps/edr-freight-web/backoffice/src/pages/dashboard/MyProfilePage.tsx
index baf548d92..37f91909e 100644
--- a/apps/edr-freight-web/backoffice/src/pages/dashboard/MyProfilePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/dashboard/MyProfilePage.tsx
@@ -1,8 +1,12 @@
 import { MySignatureCard } from "@/components/profile/MySignatureCard";
+import { ChangePasswordCard } from "@/components/profile/ChangePasswordCard";
+import { ChangeEmailCard } from "@/components/profile/ChangeEmailCard";
 
 export default function MyProfilePage() {
   return (
     <div className="mx-auto w-full max-w-2xl space-y-6 p-4">
+      <ChangeEmailCard />
+      <ChangePasswordCard />
       <div id="signature">
         <MySignatureCard />
       </div>
diff --git a/apps/edr-freight-web/backoffice/src/record-management/components/common/Top.tsx b/apps/edr-freight-web/backoffice/src/record-management/components/common/Top.tsx
index ff7678856..4f58ae6b7 100644
--- a/apps/edr-freight-web/backoffice/src/record-management/components/common/Top.tsx
+++ b/apps/edr-freight-web/backoffice/src/record-management/components/common/Top.tsx
@@ -551,7 +551,7 @@ const Top: React.FC<HeaderProps> = ({
 
               <DropdownMenuItem
                 className="flex cursor-pointer items-center rounded-lg px-3 py-2.5 text-sm text-gray-700 transition-colors hover:bg-primary-50 dark:text-gray-200 dark:hover:bg-primary-900/20"
-                onClick={() => navigate("/change-password")}
+                onClick={() => navigate("/dashboard/profile")}
               >
                 <Key className="mr-2.5 h-4 w-4 text-primary-600 dark:text-primary-400" />
                 <span>{t("header.changePassword")}</span>
diff --git a/apps/edr-freight-web/backoffice/src/services/account.service.ts b/apps/edr-freight-web/backoffice/src/services/account.service.ts
new file mode 100644
index 000000000..40511bf79
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/services/account.service.ts
@@ -0,0 +1,50 @@
+import { api as client } from "../auth/http";
+import { unwrap } from "@/utils/endpoint";
+
+export type ContactChannel = "email" | "phone";
+
+export interface ChangePasswordPayload {
+  oldPassword: string;
+  newPassword: string;
+  confirmPassword: string;
+}
+
+export interface SendContactOtpPayload {
+  channel: ContactChannel;
+  /** The NEW email/phone to verify — the OTP is sent here, not to the current one. */
+  value: string;
+}
+
+export interface UpdateContactPayload extends SendContactOtpPayload {
+  otp: string;
+}
+
+export const accountService = {
+  /** PATCH /auth/change-password — generic IAM route, works for any user type. */
+  changePassword: async (payload: ChangePasswordPayload): Promise<void> => {
+    const response = await client.patch("/auth/change-password", payload);
+    unwrap(response.data);
+  },
+
+  /** POST /me/contact/otp — sends a code to the new email/phone to prove ownership. */
+  sendContactOtp: async (
+    payload: SendContactOtpPayload,
+  ): Promise<{ sentTo: string }> => {
+    const response = await client.post<{ sentTo: string }>(
+      "/me/contact/otp",
+      payload,
+    );
+    return unwrap(response.data);
+  },
+
+  /** PATCH /me/contact — verifies the OTP and writes the new email/phone. */
+  updateContact: async (
+    payload: UpdateContactPayload,
+  ): Promise<{ success: true; value: string }> => {
+    const response = await client.patch<{ success: true; value: string }>(
+      "/me/contact",
+      payload,
+    );
+    return unwrap(response.data);
+  },
+};
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 6c9c69788..2a1963f8d 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -136,6 +136,12 @@ import type {
   WarehouseZone,
 } from "@/types/warehouse";
 import { endpoint } from "@/utils/endpoint";
+import {
+  accountService,
+  type ChangePasswordPayload,
+  type SendContactOtpPayload,
+  type UpdateContactPayload,
+} from "./account.service";
 import {
   BookingListFilter,
   bookingsService,
@@ -2182,6 +2188,29 @@ export const api = {
     ),
   },
 
+  account: {
+    changePassword: endpoint<ChangePasswordPayload, void>(
+      "me",
+      "change-password",
+      (payload) => accountService.changePassword(payload),
+    ),
+
+    sendContactOtp: endpoint<SendContactOtpPayload, { sentTo: string }>(
+      "me",
+      "send-contact-otp",
+      (payload) => accountService.sendContactOtp(payload),
+    ),
+
+    updateContact: endpoint<
+      UpdateContactPayload,
+      { success: true; value: string }
+    >(
+      "me",
+      "update-contact",
+      (payload) => accountService.updateContact(payload),
+    ),
+  },
+
   signatures: {
     mySignature: endpoint<void, SavedSignature | null>(
       "me",

From dd39c2be7c220f0eac96b2d2d944815005a965fc Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 13:29:31 +0000
Subject: [PATCH 054/174] baseLiters

---
 .../services/rate-change-requests.service.spec.ts   | 13 +++++++++++++
 .../services/rate-change-requests.service.ts        |  4 ++++
 2 files changed, 17 insertions(+)

diff --git a/apps/edr-freight-api/src/modules/rule-engine/services/rate-change-requests.service.spec.ts b/apps/edr-freight-api/src/modules/rule-engine/services/rate-change-requests.service.spec.ts
index be7c8984c..f8617cd65 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/services/rate-change-requests.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/services/rate-change-requests.service.spec.ts
@@ -118,6 +118,19 @@ describe('RateChangeRequestsService', () => {
       expect(request.payload).toEqual({ destinationYardId: 'yard-c' });
     });
 
+    it('carries baseLiters — a switch to PER_LITER keeps its billing base', async () => {
+      const { service } = build({
+        rate: liveRate({ rateUnit: 'PER_WAGON', baseLiters: null }),
+      });
+
+      const request = await service.submit({
+        rateId: 'rate-1',
+        update: { rateUnit: 'PER_LITER', baseLiters: 3 },
+      });
+
+      expect(request.payload).toEqual({ rateUnit: 'PER_LITER', baseLiters: 3 });
+    });
+
     it('rejects a no-op — 100 posted against a live 100.0000 is not a change', async () => {
       const { service } = build();
       await expect(
diff --git a/apps/edr-freight-api/src/modules/rule-engine/services/rate-change-requests.service.ts b/apps/edr-freight-api/src/modules/rule-engine/services/rate-change-requests.service.ts
index 8cc97f343..8913c9ef9 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/services/rate-change-requests.service.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/services/rate-change-requests.service.ts
@@ -42,6 +42,10 @@ const DIFFABLE_FIELDS = [
   // LIVE last-mile rate would diff to "nothing changed".
   'minKm',
   'maxKm',
+  // PER_LITER fuel surcharge billing base. Missing here, a switch to PER_LITER
+  // dropped the submitted liters and validation failed with "needs a base
+  // liters amount" even though the payload carried one.
+  'baseLiters',
 ] as const;
 
 /**

From ff3cee12e316b759daa75aa67fcde5bc5c724cad Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 13:47:53 +0000
Subject: [PATCH 055/174] feat: fuel surcharge per lane and cargo type

---
 .../contract-rate-schedule.builder.ts         | 15 ++++++++++---
 .../contracts/contract-pricing.service.ts     | 17 ++++++++------
 .../rule-engine/rule-engine.service.spec.ts   |  9 +++++---
 .../rule-engine/rule-engine.service.ts        | 22 ++++++++++++-------
 4 files changed, 42 insertions(+), 21 deletions(-)

diff --git a/apps/edr-freight-api/src/contracts/contract-rate-schedule.builder.ts b/apps/edr-freight-api/src/contracts/contract-rate-schedule.builder.ts
index c644d6117..2f1991df2 100644
--- a/apps/edr-freight-api/src/contracts/contract-rate-schedule.builder.ts
+++ b/apps/edr-freight-api/src/contracts/contract-rate-schedule.builder.ts
@@ -193,17 +193,26 @@ export class ContractRateScheduleBuilder {
     return rate.tradeDirection === want;
   }
 
-  /** Fuel row — the lane matters, so it rides along in the charge label. */
+  /**
+   * Fuel row — the lane matters, so it rides along in the charge label.
+   * Per-liter collapses to one flat total (base liters × rate value); the
+   * customer only ever sees the final price.
+   */
   private fuelRow(rate: Rate): RateScheduleRow {
     const origin = rate.originYard?.label ?? rate.originYard?.code ?? '—';
     const destination =
       rate.destinationYard?.label ?? rate.destinationYard?.code ?? '—';
+    const perLiter = rate.rateUnit === 'PER_LITER';
     return {
       route: `Fuel surcharge (${origin} → ${destination})`,
       cargo: this.cargoLabel(rate),
       currency: rate.currency,
-      amount: this.formatAmount(rate.rateValue),
-      unit: this.unitLabel(rate.rateUnit),
+      amount: this.formatAmount(
+        perLiter
+          ? Number(rate.baseLiters ?? 0) * Number(rate.rateValue)
+          : rate.rateValue,
+      ),
+      unit: perLiter ? 'flat' : this.unitLabel(rate.rateUnit),
     };
   }
 
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts
index 3f49b127f..af0a149d7 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts
@@ -302,15 +302,18 @@ export class ContractPricingService {
             r.cargoTypeId === scope.cargoTypeId,
         );
         if (fuel && Number(fuel.rateValue) > 0) {
-          const base = Number(fuel.baseLiters ?? 0);
+          // Per-liter collapses to one flat total (base liters × rate value) —
+          // the customer only sees the final price, and booking pricing bills
+          // the same flat figure once (see RuleEngineService.fuelCharges).
+          const perLiter = fuel.rateUnit === 'PER_LITER';
+          const total = perLiter
+            ? Number(fuel.baseLiters ?? 0) * Number(fuel.rateValue)
+            : Number(fuel.rateValue);
           lineItems.push({
             code: 'FUEL_SURCHARGE',
-            label:
-              fuel.rateUnit === 'PER_LITER'
-                ? `Fuel surcharge (${scope.cargoType.cargoTypeName}, ${base} liters)`
-                : `Fuel surcharge (${scope.cargoType.cargoTypeName})`,
-            unit: toContractUnit(fuel.rateUnit),
-            unitPrice: convert(Number(fuel.rateValue)),
+            label: `Fuel surcharge (${scope.cargoType.cargoTypeName})`,
+            unit: perLiter ? 'flat' : toContractUnit(fuel.rateUnit),
+            unitPrice: convert(total),
             cargoTypeCode: scope.cargoType.code ?? null,
             conditionalOn: 'has_fuel',
           });
diff --git a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.spec.ts b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.spec.ts
index 440616298..281f2d1b2 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.spec.ts
@@ -475,13 +475,16 @@ describe('RuleEngineService — fuel surcharge (per lane + cargo type)', () => {
   const fuelMods = (result: Awaited<ReturnType<RuleEngineService['evaluate']>>) =>
     result.appliedModifiers.filter((m) => m.surchargeCode === 'FUEL_SURCHARGE');
 
-  it('PER_LITER bills base liters × rate value once, regardless of wagons', async () => {
+  it('PER_LITER collapses to one flat total (base liters × rate value), regardless of wagons', async () => {
     const result = await buildService([fuelPerLiter]).evaluate(fuelInput());
     const mods = fuelMods(result);
     expect(mods).toHaveLength(1);
-    expect(mods[0].triggerValue).toBe(100);
+    // Flat: the customer sees only the total, and a frozen contract snapshot
+    // (also stored flat) multiplies it by quantity 1 — never by the liters.
+    expect(mods[0].triggerValue).toBe(1);
+    expect(mods[0].unitPriceUsd).toBe(200);
     expect(mods[0].calculatedAmount).toBe(200);
-    expect(mods[0].billingUnit).toBe('PER_LITER');
+    expect(mods[0].billingUnit).toBe('FLAT');
   });
 
   it('PER_WAGON bills the wagons the cargo occupies', async () => {
diff --git a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
index a290aeb33..908d00ecc 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
@@ -648,9 +648,12 @@ export class RuleEngineService {
   /**
    * Fuel surcharge — fires when the booking's cargo type has hasFuel = true,
    * billed off the FUEL rate matching the booking's lane (trade direction +
-   * origin + destination) and cargo type. PER_LITER bills baseLiters ×
-   * rateValue once per booking; PER_WAGON bills the wagons the cargo occupies.
-   * No matching lane rate simply bills nothing — same leniency as lashing.
+   * origin + destination) and cargo type. PER_LITER collapses to one FLAT
+   * amount (baseLiters × rateValue, once per booking) — the customer only ever
+   * sees the total, and the frozen contract snapshot stores that same flat
+   * figure so the snapshot-override math bills it exactly once. PER_WAGON
+   * bills the wagons the cargo occupies. No matching lane rate simply bills
+   * nothing — same leniency as lashing.
    */
   private fuelCharges(
     input: BookingEvaluationInput,
@@ -673,9 +676,12 @@ export class RuleEngineService {
       0,
       Number(input.bulkWagons ?? 0) || Number(input.totalWagons ?? 0),
     );
-    const billedQty =
-      rate.rateUnit === 'PER_LITER' ? Number(rate.baseLiters ?? 0) : wagons;
-    const amount = billedQty * rateValue;
+    const perLiter = rate.rateUnit === 'PER_LITER';
+    const billedQty = perLiter ? 1 : wagons;
+    const unitPrice = perLiter
+      ? Number(rate.baseLiters ?? 0) * rateValue
+      : rateValue;
+    const amount = billedQty * unitPrice;
     if (!(amount > 0)) return modifiers;
     modifiers.push({
       rateId: rate.id,
@@ -683,8 +689,8 @@ export class RuleEngineService {
       triggerValue: billedQty,
       calculatedAmount: amount,
       currency: rate.currency,
-      unitPriceUsd: rateValue,
-      billingUnit: rate.rateUnit,
+      unitPriceUsd: unitPrice,
+      billingUnit: perLiter ? 'FLAT' : rate.rateUnit,
     });
     return modifiers;
   }

From 5c2afe3454a3fc2ff30eaa9174415e8c2b8cb8dd Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Wed, 12 Aug 2026 07:30:28 +0000
Subject: [PATCH 056/174] fix(notifications): guard emitNew/emitUnreadCount
 against no WS server

@WebSocketServer() only wires `server` once the WS adapter attaches to a
running HTTP listener. It never does under NestFactory.createApplicationContext
(scripts, one-off jobs) -- confirmed live tonight, when the EIMS self-test
registration's failure alert crashed with "Cannot read properties of null
(reading 'to')" instead of just logging that no socket was available.

The registration result itself was unaffected (postSigned already resolved,
the EimsApiException was correctly re-thrown), but the crash happened inside
an await'd call in the same chain -- in a context where it wasn't caught, it
would have masked whatever result the caller actually cared about.

Both push methods now skip and log at debug level when no server is attached,
since the notification row is already persisted by the time they're called --
a missing socket just means "no live push this time", not a reason to lose
the caller's own outcome. `server` drops its `!` non-null assertion to match.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../notifications.gateway.spec.ts             | 29 +++++++++++++++++++
 .../notifications.gateway.ts                  | 18 +++++++++++-
 2 files changed, 46 insertions(+), 1 deletion(-)
 create mode 100644 apps/edr-freight-api/src/modules/notification-inbox/notifications.gateway.spec.ts

diff --git a/apps/edr-freight-api/src/modules/notification-inbox/notifications.gateway.spec.ts b/apps/edr-freight-api/src/modules/notification-inbox/notifications.gateway.spec.ts
new file mode 100644
index 000000000..bc79d8acb
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/notification-inbox/notifications.gateway.spec.ts
@@ -0,0 +1,29 @@
+import { NotificationsGateway } from "./notifications.gateway";
+import { WsAuthService } from "./ws-auth.service";
+
+const gateway = () => new NotificationsGateway({} as WsAuthService);
+
+describe("NotificationsGateway", () => {
+  it("skips emitNew rather than throwing when no WebSocket server is attached", () => {
+    const g = gateway();
+    expect(() => g.emitNew("user-1", { id: "n-1" } as never, 3)).not.toThrow();
+  });
+
+  it("skips emitUnreadCount rather than throwing when no WebSocket server is attached", () => {
+    const g = gateway();
+    expect(() => g.emitUnreadCount("user-1", 3)).not.toThrow();
+  });
+
+  it("pushes to the user's room once a server is attached", () => {
+    const g = gateway();
+    const emit = jest.fn();
+    const to = jest.fn().mockReturnValue({ emit });
+    (g as unknown as { server: { to: typeof to } }).server = { to };
+
+    g.emitNew("user-1", { id: "n-1" } as never, 3);
+
+    expect(to).toHaveBeenCalledWith("user:user-1");
+    expect(emit).toHaveBeenCalledWith("notification:new", { id: "n-1" });
+    expect(emit).toHaveBeenCalledWith("notification:unread-count", 3);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/notification-inbox/notifications.gateway.ts b/apps/edr-freight-api/src/modules/notification-inbox/notifications.gateway.ts
index 0c4704170..4658dfac0 100644
--- a/apps/edr-freight-api/src/modules/notification-inbox/notifications.gateway.ts
+++ b/apps/edr-freight-api/src/modules/notification-inbox/notifications.gateway.ts
@@ -27,8 +27,10 @@ import { WsAuthService } from "./ws-auth.service";
 export class NotificationsGateway implements OnGatewayConnection {
   private readonly logger = new Logger(NotificationsGateway.name);
 
+  // Not `!`-asserted: Nest only wires this once the WS adapter attaches to a running HTTP
+  // listener, which does not happen under `NestFactory.createApplicationContext` — see `skip()`.
   @WebSocketServer()
-  private readonly server!: Server;
+  private readonly server?: Server;
 
   constructor(private readonly wsAuth: WsAuthService) {}
 
@@ -45,6 +47,7 @@ export class NotificationsGateway implements OnGatewayConnection {
 
   /** Push a freshly-created notification + the new unread count to a user. */
   emitNew(userId: string, notification: NotificationDto, unreadCount: number): void {
+    if (!this.server) return this.skip("emitNew");
     const room = this.server.to(this.room(userId));
     room.emit(NOTIFICATION_WS_EVENTS.NEW, notification);
     room.emit(NOTIFICATION_WS_EVENTS.UNREAD_COUNT, unreadCount);
@@ -52,11 +55,24 @@ export class NotificationsGateway implements OnGatewayConnection {
 
   /** Push only an updated unread count (e.g. after a read on another tab). */
   emitUnreadCount(userId: string, unreadCount: number): void {
+    if (!this.server) return this.skip("emitUnreadCount");
     this.server
       .to(this.room(userId))
       .emit(NOTIFICATION_WS_EVENTS.UNREAD_COUNT, unreadCount);
   }
 
+  /**
+   * `@WebSocketServer()` only wires `server` once the WS adapter attaches to a running HTTP
+   * listener — never under `NestFactory.createApplicationContext` (scripts, one-off jobs), and not
+   * for the brief window before `app.listen()` completes in a real boot either. The notification row
+   * is already persisted by this point (the caller writes it before pushing), so a missing socket
+   * server just means "no live push this time" — skip it rather than throw and lose the caller's
+   * own result (e.g. an EIMS registration outcome that already succeeded or failed for real).
+   */
+  private skip(method: string): void {
+    this.logger.debug(`${method}: no WebSocket server attached (non-HTTP context?) — push skipped`);
+  }
+
   private room(userId: string): string {
     return `user:${userId}`;
   }

From 8d53dc17ce997b52c7d5b8d703105c2290f660a0 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Wed, 12 Aug 2026 08:08:03 +0000
Subject: [PATCH 057/174] docs(eims): confirm signing algorithm and cert format
 against MoR's guide

Cross-checked our RSA-SHA512 signing and raw-bytes certificate encoding
against MoR's own "Guide to Generating and Using Certificate for E-Invoicing"
(supplied today). Both were previously documented as our best inference from
the Postman collection; the guide names SHA512withRSA explicitly (PKCS#1v1.5,
matching Node's createSign default) and its own worked example certificate is
byte-for-byte the same Subject:/Issuer: + 3-cert PEM chain text-file format
ours is. No behavior change -- the comment now says confirmed, not assumed.

Field order, section names, date format and the {request, signature,
certificate} envelope in the guide's worked example all match our mapper
exactly (order doesn't matter per the guide, but it's a further concordance
check). The one guide/live disagreement -- its example shows "NatureOfSupplies":
"Goods" where our actual 400 SCHEMA ERROR demanded lowercase "goods"/"service"
-- is left as-is: the live, machine-generated schema error outranks a static
doc example that may predate a schema change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/modules/eims/eims-signer.service.ts              | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/eims/eims-signer.service.ts b/apps/edr-freight-api/src/modules/eims/eims-signer.service.ts
index babec6b44..b91f306ab 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-signer.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-signer.service.ts
@@ -8,9 +8,14 @@ import { EimsSignedRequest } from "./eims.types";
  *
  *   1. compact `JSON.stringify` of the **inner** request object only,
  *   2. those exact UTF-8 bytes,
- *   3. RSA + SHA-512 (`SHA512withRSA`, PKCS#1 v1.5 — Node's default RSA padding),
+ *   3. RSA + SHA-512 (`SHA512withRSA`, PKCS#1 v1.5 — Node's default RSA padding). Confirmed, not
+ *      assumed: MoR's own "Guide to Generating and Using Certificate for E-Invoicing" names
+ *      `SHA512withRSA` explicitly, which is PKCS#1v1.5 in Java (PSS would be named
+ *      `SHA512withRSAandMGF1`) — the same padding `createSign("RSA-SHA512")` uses by default.
  *   4. base64 of the raw signature bytes (256 bytes for an RSA-2048 key),
- *   5. base64 of the certificate file's exact bytes.
+ *   5. base64 of the certificate file's exact bytes. Also confirmed by the same guide: its own
+ *      worked example certificate is the identical `Subject:`/`Issuer:` header + 3-cert PEM chain
+ *      text-file format ours is, base64'd with no re-encoding.
  *
  * The outer `{request, signature, certificate}` envelope is never itself signed, and the request
  * object is never mutated after serialization.

From 2d4da8110b2fe0bbbbba86ea41892e6b65861638 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Wed, 12 Aug 2026 14:08:28 +0000
Subject: [PATCH 058/174] eims integration master test complete

---
 apps/edr-freight-api/.env.example             |  13 +-
 .../edr-freight-api/src/config/eims.config.ts |  28 ++
 .../migrations/3450000000000-WidenEimsIrn.ts  |  33 +++
 .../3460000000000-AddEimsSignedQr.ts          |  20 ++
 .../3470000000000-EimsCancellation.ts         |  26 ++
 .../3480000000000-WidenPreviousIrn.ts         |  24 ++
 .../migrations/3490000000000-EimsReceipts.ts  |  34 +++
 .../modules/billing/billing.service.spec.ts   | 108 ++++++++
 .../src/modules/billing/billing.service.ts    |  77 ++++--
 .../invoice-document.service.spec.ts          |  46 ++++
 .../documents/invoice-document.service.ts     |  34 ++-
 .../billing/eims-invoice.mapper.spec.ts       |  22 +-
 .../modules/billing/eims-invoice.mapper.ts    |  16 +-
 .../billing/entities/invoice.entity.ts        |  36 ++-
 .../eims/dto/cancel-eims-registration.dto.ts  |  19 ++
 .../eims/dto/register-sales-receipt.dto.ts    |  88 ++++++
 .../dto/register-withholding-receipt.dto.ts   |  40 +++
 .../eims/dto/resolve-eims-registration.dto.ts |   4 +-
 .../eims/eims-cancellation.service.spec.ts    | 153 +++++++++++
 .../modules/eims/eims-cancellation.service.ts | 117 ++++++++
 .../modules/eims/eims-invoice-context.spec.ts | 118 ++++++++
 .../src/modules/eims/eims-invoice-context.ts  |  66 ++++-
 .../eims-invoice-registration.service.spec.ts | 109 +++++++-
 .../eims/eims-invoice-registration.service.ts | 128 +++++++--
 .../modules/eims/eims-invoice-view.util.ts    |  27 ++
 .../modules/eims/eims-invoice.controller.ts   |  55 +++-
 .../modules/eims/eims-receipt.service.spec.ts | 231 ++++++++++++++++
 .../src/modules/eims/eims-receipt.service.ts  | 259 ++++++++++++++++++
 .../src/modules/eims/eims-receipt.types.ts    |  97 +++++++
 .../modules/eims/eims-registration.types.ts   |  30 ++
 .../src/modules/eims/eims-test-fixtures.ts    |   6 +
 .../src/modules/eims/eims.module.ts           |  17 +-
 .../eims/entities/eims-receipt.entity.ts      |  68 +++++
 .../eims/entities/eims-system-state.entity.ts |   7 +-
 .../services/train-scheduling.service.ts      |  71 +++++
 .../src/seed/freight-permissions.registry.ts  |  24 +-
 .../backoffice/src/types/eims.ts              |  25 +-
 pnpm-lock.yaml                                | 167 +++++------
 38 files changed, 2270 insertions(+), 173 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3450000000000-WidenEimsIrn.ts
 create mode 100644 apps/edr-freight-api/src/migrations/3460000000000-AddEimsSignedQr.ts
 create mode 100644 apps/edr-freight-api/src/migrations/3470000000000-EimsCancellation.ts
 create mode 100644 apps/edr-freight-api/src/migrations/3480000000000-WidenPreviousIrn.ts
 create mode 100644 apps/edr-freight-api/src/migrations/3490000000000-EimsReceipts.ts
 create mode 100644 apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/eims/dto/cancel-eims-registration.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/eims/dto/register-sales-receipt.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/eims/dto/register-withholding-receipt.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/eims/eims-cancellation.service.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/eims/eims-cancellation.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/eims/eims-invoice-context.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/eims/eims-invoice-view.util.ts
 create mode 100644 apps/edr-freight-api/src/modules/eims/eims-receipt.service.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/eims/eims-receipt.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/eims/eims-receipt.types.ts
 create mode 100644 apps/edr-freight-api/src/modules/eims/entities/eims-receipt.entity.ts

diff --git a/apps/edr-freight-api/.env.example b/apps/edr-freight-api/.env.example
index 2c636eee4..5a145a0db 100644
--- a/apps/edr-freight-api/.env.example
+++ b/apps/edr-freight-api/.env.example
@@ -172,14 +172,23 @@ EIMS_SELLER_LOCALITY=
 # Tax treatment — REQUIRES FINANCE SIGN-OFF. The application models no tax at all
 # (invoice.taxAmount is always 0), so nothing here is defaulted: registration fails
 # locally, naming the missing variables, until these are set.
-# Required, and deliberately unset: the choice is a tax position, not a default.
+# Required, and deliberately unset here: the choice is a tax position, not a default.
 # MoR's enum (from its own 400): TOT10 TOT2 VAT15 VWHT TWHT VATEX VATWH WHOP2 WTHOI VAT0 VWTH
-# Pending finance confirmation of VAT0 (zero-rated) vs VATEX (exempt).
+# Finance confirmed 2026-08-12: VATEX (exempt) for EDR's freight business — set in .env.
 EIMS_TAX_CODE=
 EIMS_TAX_RATE_PERCENT=0
 EIMS_EXCISE_TAX_VALUE=0
 EIMS_INCOME_WITHHOLD_VALUE=0
 EIMS_TRANSACTION_WITHHOLD_VALUE=0
+# Per-chargeType override, for an invoice whose lines need different MoR tax treatment (e.g. a
+# zero-rated freight line next to a taxed accessorial) — IRC-P01 compliance-test material.
+# A charge type not listed here falls back to EIMS_TAX_CODE / EIMS_TAX_RATE_PERCENT above.
+# EIMS_TAX_CODE_BY_CHARGE_TYPE and EIMS_TAX_RATE_BY_CHARGE_TYPE must list the same charge types.
+EIMS_TAX_CODE_BY_CHARGE_TYPE=
+EIMS_TAX_RATE_BY_CHARGE_TYPE=
+# Same mechanism; charge types not listed fall back to EIMS_EXCISE_TAX_VALUE / 0 respectively.
+EIMS_EXCISE_BY_CHARGE_TYPE=
+EIMS_DISCOUNT_BY_CHARGE_TYPE=
 # Document classification and payment presentation.
 EIMS_TRANSACTION_TYPE=B2B
 # Lowercase constant: MoR's oneOf branches require exactly 'goods' or 'service'.
diff --git a/apps/edr-freight-api/src/config/eims.config.ts b/apps/edr-freight-api/src/config/eims.config.ts
index a8a929ca5..cf77072e0 100644
--- a/apps/edr-freight-api/src/config/eims.config.ts
+++ b/apps/edr-freight-api/src/config/eims.config.ts
@@ -89,8 +89,30 @@ export interface EimsInvoiceConfig {
   buyerRegionCodes: Record<string, string>;
   /** Same mechanism as `buyerRegionCodes`, for `EIMS_BUYER_WEREDA_CODES` ("Yeka=574"). */
   buyerWeredaCodes: Record<string, string>;
+  /**
+   * Per-`chargeType` tax treatment, e.g. `EIMS_TAX_CODE_BY_CHARGE_TYPE=RAIL_FREIGHT=VAT0` +
+   * `EIMS_TAX_RATE_BY_CHARGE_TYPE=RAIL_FREIGHT=0`. A charge type not listed here falls back to
+   * `taxCode`/`taxRatePercent`. Needed for an invoice whose lines carry different MoR tax
+   * treatment (e.g. zero-rated freight next to a taxed accessorial) — the flat `taxCode` above
+   * cannot express that. Values are raw strings; the context builder parses/validates them.
+   */
+  taxCodeByChargeType: Record<string, string>;
+  taxRateByChargeType: Record<string, string>;
+  /** Same mechanism, for `EIMS_EXCISE_BY_CHARGE_TYPE` / `EIMS_DISCOUNT_BY_CHARGE_TYPE`. Charge
+   *  types not listed fall back to `exciseTaxValue` / 0 respectively. */
+  exciseByChargeType: Record<string, string>;
+  discountByChargeType: Record<string, string>;
   cashierName: string | null;
   salesPersonName: string | null;
+  /**
+   * TEMPORARY / experimental — `EIMS_BUYER_ID_TYPE` + `EIMS_BUYER_ID_NUMBER`, applied to every
+   * buyer regardless of who they are. Only exists to test whether rule 7004 ("Id types should be
+   * one of NID, KID, SID, WID, PST, DLS, MRS") is satisfied by *any* IdType/IdNumber pair, ahead
+   * of MoR's answer on whether it's required for a TIN-only corporate buyer and which value fits.
+   * Wrong for a real, non-self buyer — remove once MoR answers and a real per-buyer field exists.
+   */
+  buyerIdType: string | null;
+  buyerIdNumber: string | null;
 }
 
 const REQUIRED_VARS = [
@@ -188,8 +210,14 @@ export default registerAs("eims", (): EimsConfig => {
       buyerCountryCode: process.env.EIMS_BUYER_COUNTRY_CODE || null,
       buyerRegionCodes: parseCodeMap(process.env.EIMS_BUYER_REGION_CODES),
       buyerWeredaCodes: parseCodeMap(process.env.EIMS_BUYER_WEREDA_CODES),
+      taxCodeByChargeType: parseCodeMap(process.env.EIMS_TAX_CODE_BY_CHARGE_TYPE),
+      taxRateByChargeType: parseCodeMap(process.env.EIMS_TAX_RATE_BY_CHARGE_TYPE),
+      exciseByChargeType: parseCodeMap(process.env.EIMS_EXCISE_BY_CHARGE_TYPE),
+      discountByChargeType: parseCodeMap(process.env.EIMS_DISCOUNT_BY_CHARGE_TYPE),
       cashierName: process.env.EIMS_CASHIER_NAME || null,
       salesPersonName: process.env.EIMS_SALESPERSON_NAME || null,
+      buyerIdType: process.env.EIMS_BUYER_ID_TYPE || null,
+      buyerIdNumber: process.env.EIMS_BUYER_ID_NUMBER || null,
     },
   };
 
diff --git a/apps/edr-freight-api/src/migrations/3450000000000-WidenEimsIrn.ts b/apps/edr-freight-api/src/migrations/3450000000000-WidenEimsIrn.ts
new file mode 100644
index 000000000..ec3faf9eb
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3450000000000-WidenEimsIrn.ts
@@ -0,0 +1,33 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * `eims_irn varchar(64)` was sized for a guess; the real value MoR returns is longer. Confirmed
+ * live 2026-08-12 — a genuine `POST /v1/register` acceptance came back as
+ * `test-aeedcbf496f0b63bb035ba3ca1dc674e3c81c980cafeb1c5038421999a23a215` (69 chars: a `test-`
+ * prefix + a 64-hex-char body), which overflowed the column and threw *after* MoR had already
+ * accepted the document — `settleSuccess` never committed, leaving the invoice stuck `SUBMITTING`
+ * and the system-wide reservation stuck in-flight with no block/alert (see
+ * `EimsInvoiceRegistrationService` for the accompanying code fix).
+ *
+ * Widened to `text` rather than a new fixed length: MoR has never documented an IRN format or
+ * length, and a `test-` prefix on a *production* endpoint suggests this may not even be MoR's
+ * real production shape — guessing another fixed bound risks the exact same failure again.
+ */
+export class WidenEimsIrn3450000000000 implements MigrationInterface {
+  name = "WidenEimsIrn3450000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+      ALTER COLUMN eims_irn TYPE text
+    `);
+  }
+
+  /** Only safe if nothing stored so far exceeds 64 chars — true only until this migration ran. */
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+      ALTER COLUMN eims_irn TYPE varchar(64)
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3460000000000-AddEimsSignedQr.ts b/apps/edr-freight-api/src/migrations/3460000000000-AddEimsSignedQr.ts
new file mode 100644
index 000000000..dedf2d05f
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3460000000000-AddEimsSignedQr.ts
@@ -0,0 +1,20 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/** `DocumentDetails`/register-response field `signedQR`, persisted alongside `eims_irn`. */
+export class AddEimsSignedQr3460000000000 implements MigrationInterface {
+  name = "AddEimsSignedQr3460000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+      ADD COLUMN IF NOT EXISTS eims_signed_qr text
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+      DROP COLUMN IF EXISTS eims_signed_qr
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3470000000000-EimsCancellation.ts b/apps/edr-freight-api/src/migrations/3470000000000-EimsCancellation.ts
new file mode 100644
index 000000000..7092e5518
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3470000000000-EimsCancellation.ts
@@ -0,0 +1,26 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/** Columns for `POST /v1/cancel` — see `EimsCancellationService`. */
+export class EimsCancellation3470000000000 implements MigrationInterface {
+  name = "EimsCancellation3470000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+      ADD COLUMN IF NOT EXISTS eims_cancelled_at timestamptz,
+      ADD COLUMN IF NOT EXISTS eims_cancellation_date varchar(64),
+      ADD COLUMN IF NOT EXISTS eims_cancellation_reason_code varchar(8),
+      ADD COLUMN IF NOT EXISTS eims_cancellation_remark text
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+      DROP COLUMN IF EXISTS eims_cancelled_at,
+      DROP COLUMN IF EXISTS eims_cancellation_date,
+      DROP COLUMN IF EXISTS eims_cancellation_reason_code,
+      DROP COLUMN IF EXISTS eims_cancellation_remark
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3480000000000-WidenPreviousIrn.ts b/apps/edr-freight-api/src/migrations/3480000000000-WidenPreviousIrn.ts
new file mode 100644
index 000000000..15a343f06
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3480000000000-WidenPreviousIrn.ts
@@ -0,0 +1,24 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Same bug as `3450000000000-WidenEimsIrn`, same fix: `previous_irn` stores a real MoR IRN too
+ * (fed into the next registration's `ReferenceDetails.PreviousIrn`) and would overflow the same
+ * varchar(64) on the next successful registration.
+ */
+export class WidenPreviousIrn3480000000000 implements MigrationInterface {
+  name = "WidenPreviousIrn3480000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.eims_system_state
+      ALTER COLUMN previous_irn TYPE text
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.eims_system_state
+      ALTER COLUMN previous_irn TYPE varchar(64)
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3490000000000-EimsReceipts.ts b/apps/edr-freight-api/src/migrations/3490000000000-EimsReceipts.ts
new file mode 100644
index 000000000..3d5ab02e9
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3490000000000-EimsReceipts.ts
@@ -0,0 +1,34 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/** `freight.eims_receipts` — see `EimsReceipt` entity. */
+export class EimsReceipts3490000000000 implements MigrationInterface {
+  name = "EimsReceipts3490000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.eims_receipts (
+        id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        invoice_id    uuid NOT NULL REFERENCES freight.invoices(id),
+        kind          varchar(16) NOT NULL,
+        status        varchar(20) NOT NULL DEFAULT 'NOT_SUBMITTED',
+        receipt_number varchar(64) NOT NULL,
+        rrn           text,
+        qr            text,
+        ack_status    varchar(8),
+        submitted_at  timestamptz,
+        last_error    jsonb,
+        request       jsonb,
+        created_at    timestamptz NOT NULL DEFAULT now(),
+        updated_at    timestamptz NOT NULL DEFAULT now(),
+        deleted_at    timestamptz
+      )
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_eims_receipts_invoice_id ON freight.eims_receipts (invoice_id)
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.eims_receipts`);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index 576c7b166..d9eef5a43 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -80,6 +80,7 @@ describe("BillingService.generateInvoice", () => {
       {} as never, // companies
       {} as never, // invoiceDocuments
       {} as never, // files
+      { get: () => undefined } as never, // config
     );
   });
 
@@ -142,6 +143,7 @@ describe("BillingService.markInvoiceAsPaid", () => {
       {} as never, // companies
       {} as never, // invoiceDocuments
       {} as never, // files
+      { get: () => undefined } as never, // config
     );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
@@ -196,6 +198,7 @@ describe("BillingService.markInvoiceAsPaid", () => {
       {} as never, // companies
       {} as never, // invoiceDocuments
       {} as never, // files
+      { get: () => undefined } as never, // config
     );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
@@ -240,6 +243,7 @@ describe("BillingService.settleByPaymentId", () => {
       {} as never, // companies
       {} as never, // invoiceDocuments
       {} as never, // files
+      { get: () => undefined } as never, // config
     );
     return { service, mg, events };
   }
@@ -352,6 +356,7 @@ describe("BillingService.recordPayment", () => {
       {} as never, // companies
       {} as never, // invoiceDocuments
       {} as never, // files
+      { get: () => undefined } as never, // config
     );
     return { service, mg, events };
   }
@@ -468,6 +473,7 @@ describe("BillingService.expirePayable — locked write runs in a transaction",
       {} as never,
       {} as never,
       {} as never,
+      {} as never, // config
     );
     return { service, defaultManager, txManager, transaction };
   };
@@ -540,6 +546,7 @@ describe("BillingService.issuePayable", () => {
       {} as never,
       {} as never,
       {} as never,
+      {} as never, // config
     );
     return { service, manager };
   };
@@ -630,6 +637,7 @@ describe("BillingService — CAC Bank (OTP debit)", () => {
       {} as never,
       {} as never,
       {} as never,
+      {} as never, // config
     );
     return { service, repo };
   };
@@ -712,6 +720,7 @@ describe("BillingService — CBE bill amounts carry cents, never rounded", () =>
       {} as never,
       {} as never,
       {} as never,
+      {} as never, // config
     );
     return { service, repo };
   };
@@ -740,3 +749,102 @@ describe("BillingService — CBE bill amounts carry cents, never rounded", () =>
     });
   });
 });
+
+describe("BillingService.document", () => {
+  const invoiceRow = (over: Record<string, unknown> = {}) => ({
+    id: "inv-1",
+    invoiceNumber: "INV-20260812-00001",
+    source: "booking",
+    sourceId: "booking-1",
+    status: Freight.InvoiceStatus.Pending,
+    type: "freight",
+    currency: "ETB",
+    subtotalAmount: 100,
+    taxAmount: 0,
+    totalAmount: 100,
+    paidAmount: 0,
+    balanceAmount: 100,
+    issuedAt: new Date(2026, 7, 12),
+    dueAt: new Date(2026, 7, 19),
+    eimsIrn: null,
+    eimsSignedQr: null,
+    company: { name: "ABC Trading PLC", tin: "0999930000", vatNumber: "123475885858" },
+    ...over,
+  });
+
+  const build = (invoice: Record<string, unknown>) => {
+    const render = jest.fn().mockResolvedValue({ filename: "x.pdf", buffer: Buffer.from("") });
+    const service = new BillingService(
+      {} as never,
+      { findById: jest.fn().mockResolvedValue(invoice) } as never,
+      { findAll: jest.fn().mockResolvedValue([]) } as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      { render } as never,
+      {} as never,
+      {
+        get: (key: string) =>
+          key === "eims"
+            ? { tin: "0053481357", invoice: { sellerVatNumber: "43256663343256663322" } }
+            : undefined,
+      } as never, // config
+    );
+    return { service, render };
+  };
+
+  it("adds no EIMS IRN row and no QR for an unregistered invoice", async () => {
+    const { service, render } = build(invoiceRow());
+
+    await service.document("inv-1");
+
+    const model = render.mock.calls[0][0];
+    expect(model.summary.find((r: { label: string }) => r.label === "EIMS IRN")).toBeUndefined();
+    expect(model.qrImageUrl).toBeNull();
+  });
+
+  it("shows the buyer's name, TIN and VAT number on every invoice", async () => {
+    const { service, render } = build(invoiceRow());
+
+    await service.document("inv-1");
+
+    const model = render.mock.calls[0][0];
+    expect(model.summary).toContainEqual({ label: "Buyer", value: "ABC Trading PLC" });
+    expect(model.summary).toContainEqual({ label: "Buyer TIN", value: "0999930000" });
+    expect(model.summary).toContainEqual({ label: "Buyer VAT No.", value: "123475885858" });
+  });
+
+  it("omits the VAT row when the buyer company has none", async () => {
+    const { service, render } = build(invoiceRow({ company: { name: "Acme", tin: "0011223344" } }));
+
+    await service.document("inv-1");
+
+    const model = render.mock.calls[0][0];
+    expect(model.summary.find((r: { label: string }) => r.label === "Buyer VAT No.")).toBeUndefined();
+  });
+
+  it("shows EDR's own seller TIN and VAT number from EIMS config", async () => {
+    const { service, render } = build(invoiceRow());
+
+    await service.document("inv-1");
+
+    const model = render.mock.calls[0][0];
+    expect(model.summary).toContainEqual({ label: "Seller TIN", value: "0053481357" });
+    expect(model.summary).toContainEqual({
+      label: "Seller VAT No.",
+      value: "43256663343256663322",
+    });
+  });
+
+  it("adds the EIMS IRN to the summary and renders the QR for a registered invoice", async () => {
+    const { service, render } = build(
+      invoiceRow({ eimsIrn: "IRN-123", eimsSignedQr: "signed-payload" }),
+    );
+
+    await service.document("inv-1");
+
+    const model = render.mock.calls[0][0];
+    expect(model.summary).toContainEqual({ label: "EIMS IRN", value: "IRN-123" });
+    expect(model.qrImageUrl).toBe("data:image/png;base64,signed-payload");
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 6c7e8455d..caa25fbaa 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -1,4 +1,5 @@
 import { Freight, PaymentReferenceType } from "@edr/types";
+import { ConfigService } from "@nestjs/config";
 import {
   BadRequestException,
   forwardRef,
@@ -12,6 +13,7 @@ import { logCtx } from "@edr/api-common";
 import { DataSource, EntityManager, In } from "typeorm";
 
 import { Booking } from "../bookings/entities/booking.entity";
+import { EimsConfig } from "../../config/eims.config";
 import { CompaniesService } from "../companies/companies.service";
 import { FilesService } from "../files/files.service";
 import { applyBookingRefDirectionScope } from "../user-trade-access/trade-scope.util";
@@ -161,6 +163,7 @@ export class BillingService {
     private readonly companies: CompaniesService,
     private readonly invoiceDocuments: InvoiceDocumentService,
     private readonly files: FilesService,
+    private readonly config: ConfigService,
   ) { }
 
   // ── Reads ──────────────────────────────────────────────────────────────────
@@ -384,7 +387,7 @@ export class BillingService {
   async document(id: string): Promise<{ filename: string; buffer: Buffer }> {
     const invoice = await this.findById(id);
     return this.invoiceDocuments.render(
-      this.toDocumentModel(invoice, "INVOICE"),
+      await this.toDocumentModel(invoice, "INVOICE"),
     );
   }
 
@@ -397,15 +400,24 @@ export class BillingService {
       );
     }
     return this.invoiceDocuments.render(
-      this.toDocumentModel(invoice, "RECEIPT"),
+      await this.toDocumentModel(invoice, "RECEIPT"),
     );
   }
 
+  /**
+   * `Invoice.eimsSignedQr` is already a base64 PNG straight from MoR — confirmed against the
+   * Postman collection's `register` response (`signedQR` decodes to a PNG magic-byte header),
+   * not a payload we encode ourselves. Wrapped in a data URL, nothing more.
+   */
+  private renderEimsQr(signedQr: string): string {
+    return `data:image/png;base64,${signedQr}`;
+  }
+
   /** Map a global invoice (+ lines) onto the source-agnostic document model. */
-  private toDocumentModel(
+  private async toDocumentModel(
     invoice: Invoice & { lines: InvoiceLine[] },
     kind: "INVOICE" | "RECEIPT",
-  ): InvoiceDocumentModel {
+  ): Promise<InvoiceDocumentModel> {
     const title = invoice.source
       ? invoice.source.charAt(0).toUpperCase() + invoice.source.slice(1)
       : "EDR";
@@ -423,6 +435,43 @@ export class BillingService {
     totals.push({ label: "Paid", amount: Number(invoice.paidAmount) });
     totals.push({ label: "Balance", amount: Number(invoice.balanceAmount) });
 
+    const summary: InvoiceDocumentModel["summary"] = [
+      // Buyer identity — was missing entirely; a MoR-registered invoice must show who it was
+      // filed against, not just the seller. VatNumber shown only when the company has one.
+      { label: "Buyer", value: invoice.company?.name ?? null },
+      { label: "Buyer TIN", value: invoice.company?.tin ?? null },
+      ...(invoice.company?.vatNumber
+        ? [{ label: "Buyer VAT No.", value: invoice.company.vatNumber }]
+        : []),
+      { label: "Status", value: invoice.status },
+      { label: "Type", value: invoice.type },
+      { label: "Reference", value: invoice.sourceId },
+      { label: "Currency", value: invoice.currency },
+      {
+        label: "Issued",
+        value: invoice.issuedAt
+          ? new Date(invoice.issuedAt).toLocaleDateString("en-GB")
+          : null,
+      },
+      {
+        label: "Due",
+        value: invoice.dueAt
+          ? new Date(invoice.dueAt).toLocaleDateString("en-GB")
+          : null,
+      },
+    ];
+
+    // Seller identity — EDR's own legal TIN/VAT live only in EIMS config (nowhere else in this
+    // codebase). Shown only when actually configured, same as the buyer VAT row.
+    const eimsCfg = this.config.get<EimsConfig>("eims");
+    if (eimsCfg?.tin) summary.push({ label: "Seller TIN", value: eimsCfg.tin });
+    if (eimsCfg?.invoice?.sellerVatNumber) {
+      summary.push({ label: "Seller VAT No.", value: eimsCfg.invoice.sellerVatNumber });
+    }
+
+    // MoR EIMS reference — only once actually registered, never a placeholder row.
+    if (invoice.eimsIrn) summary.push({ label: "EIMS IRN", value: invoice.eimsIrn });
+
     return {
       kind,
       title,
@@ -430,24 +479,7 @@ export class BillingService {
       issuedAt: invoice.issuedAt ?? invoice.createdAt,
       status: invoice.status,
       currency: invoice.currency,
-      summary: [
-        { label: "Status", value: invoice.status },
-        { label: "Type", value: invoice.type },
-        { label: "Reference", value: invoice.sourceId },
-        { label: "Currency", value: invoice.currency },
-        {
-          label: "Issued",
-          value: invoice.issuedAt
-            ? new Date(invoice.issuedAt).toLocaleDateString("en-GB")
-            : null,
-        },
-        {
-          label: "Due",
-          value: invoice.dueAt
-            ? new Date(invoice.dueAt).toLocaleDateString("en-GB")
-            : null,
-        },
-      ],
+      summary,
       categoryHeader: "Charge type",
       lines: invoice.lines.map((l) => ({
         description: l.description ?? l.chargeType,
@@ -458,6 +490,7 @@ export class BillingService {
         currency: l.currency,
       })),
       totals,
+      qrImageUrl: invoice.eimsSignedQr ? this.renderEimsQr(invoice.eimsSignedQr) : null,
     };
   }
 
diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
new file mode 100644
index 000000000..00e590e17
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
@@ -0,0 +1,46 @@
+import { InvoiceDocumentModel, InvoiceDocumentService } from "./invoice-document.service";
+
+const model = (over: Partial<InvoiceDocumentModel> = {}): InvoiceDocumentModel => ({
+  kind: "INVOICE",
+  title: "Freight",
+  documentNumber: "INV-20260812-00001",
+  issuedAt: new Date(2026, 7, 12),
+  status: "PENDING",
+  currency: "ETB",
+  summary: [{ label: "Status", value: "PENDING" }],
+  lines: [],
+  totals: [{ label: "Total", amount: 100, grand: true }],
+  ...over,
+});
+
+describe("InvoiceDocumentService.buildHtml — EIMS QR", () => {
+  const service = new InvoiceDocumentService({} as never, {} as never);
+
+  it("renders no QR block when qrImageUrl is unset", () => {
+    const html = service.buildHtml(model());
+    expect(html).not.toContain('class="qr"');
+  });
+
+  it("renders the QR image when qrImageUrl is set", () => {
+    const html = service.buildHtml(model({ qrImageUrl: "data:image/png;base64,QR" }));
+    expect(html).toContain('class="qr"');
+    expect(html).toContain('src="data:image/png;base64,QR"');
+  });
+
+  it("still shows the IRN text row via the ordinary summary grid", () => {
+    const html = service.buildHtml(
+      model({ summary: [{ label: "EIMS IRN", value: "IRN-123" }] }),
+    );
+    expect(html).toContain("EIMS IRN");
+    expect(html).toContain("IRN-123");
+  });
+
+  it("widens the summary's right margin only when a QR is present, to clear the QR block", () => {
+    // "summary-with-qr" also appears in the always-present <style> rule, so the check has to be
+    // the actual div's class attribute, not a bare substring match.
+    expect(service.buildHtml(model())).not.toContain('class="summary summary-with-qr"');
+    expect(service.buildHtml(model({ qrImageUrl: "data:image/png;base64,QR" }))).toContain(
+      'class="summary summary-with-qr"',
+    );
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
index 268e94ad9..d83b7e2f0 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
@@ -62,6 +62,12 @@ export interface InvoiceDocumentModel {
    * explicitly only to override that default for one document.
    */
   stampImageUrl?: string | null;
+  /**
+   * MoR EIMS verification QR (data URL, pre-rendered by the caller from `Invoice.eimsSignedQr` —
+   * see that column's comment). Set only once an invoice is actually registered; the IRN text
+   * itself goes through the ordinary `summary` rows, not a dedicated field.
+   */
+  qrImageUrl?: string | null;
 }
 
 /**
@@ -96,9 +102,11 @@ export class InvoiceDocumentService {
         // summary grid, line-item table, totals) from the model — not a flat
         // plain-text dump — so it still reads as a proper invoice document.
         // ponytail: still draws the plain vector seal, not the uploaded stamp
-        // image — embedding a raster image needs a new PDF XObject primitive
-        // in styled-pdf.util.ts. Upgrade when the Chromium-less path needs to
-        // carry the real stamp too; today it's a rare degraded fallback.
+        // image, and omits the EIMS QR entirely — embedding a raster image
+        // needs a new PDF XObject primitive in styled-pdf.util.ts. Upgrade
+        // when the Chromium-less path needs to carry the real stamp/QR too;
+        // today it's a rare degraded fallback. The IRN text itself still
+        // comes through (buildFallbackPdf renders model.summary same as HTML).
         fallback: () => this.buildFallbackPdf(resolvedModel),
       }),
     };
@@ -243,6 +251,10 @@ export class InvoiceDocumentService {
     const sealInner = sealMarkup(model.stampImageUrl, sealText);
     const sealCssClass = sealClass(model.stampImageUrl);
 
+    const qrMarkup = model.qrImageUrl
+      ? `<div class="qr"><img src="${esc(model.qrImageUrl)}" alt="EIMS verification QR" /><span>Scan to verify (MoR EIMS)</span></div>`
+      : "";
+
     const summaryRows = model.summary
       .map((row) => `<div><span>${esc(row.label)}</span>${esc(row.value)}</div>`)
       .join("");
@@ -281,8 +293,19 @@ export class InvoiceDocumentService {
     .meta strong { display: block; color: #0f172a; font-size: 17px; margin-top: 5px; }
     .seal { position: absolute; right: 28px; top: 118px; width: 116px; height: 116px; border: 4px double #0f766e; border-radius: 999px; color: #0f766e; display: flex; align-items: center; justify-content: center; text-align: center; font-weight: 800; font-size: 18px; transform: rotate(-14deg); opacity: .82; }
     ${sealImageCss()}
+    .qr { position: absolute; right: 160px; top: 118px; width: 90px; text-align: center; }
+    .qr img { width: 90px; height: 90px; }
+    .qr span { display: block; font-size: 7px; color: #64748b; margin-top: 3px; }
     .summary { display: grid; grid-template-columns: 1fr 1fr; gap: 12px 28px; margin: 24px 150px 16px 0; font-size: 13px; }
-    .summary div { border-bottom: 1px solid #e2e8f0; padding: 7px 0; }
+    /* The QR block (right:160px, width:90px) sits further inward than the seal alone did — the
+       150px margin above only ever cleared the seal, so a QR-bearing invoice needs more room. */
+    .summary.summary-with-qr { margin-right: 270px; }
+    /* min-width: 0 overrides Grid's default min-width:auto on grid items — without it, a long
+       unbroken value (a 20-digit VAT number) forces its column wider to fit un-wrapped rather than
+       honouring overflow-wrap, which is what actually let text bleed into the seal/QR overlay
+       (confirmed by isolating the two: margin-right alone already positioned the box correctly;
+       the text itself was still escaping the box's own right edge until this was added). */
+    .summary div { border-bottom: 1px solid #e2e8f0; padding: 7px 0; overflow-wrap: break-word; min-width: 0; }
     .summary span { color: #64748b; display: block; font-size: 11px; margin-bottom: 3px; }
     table { width: 100%; border-collapse: collapse; margin-top: 18px; }
     th { text-align: left; background: #f8fafc; color: #475569; }
@@ -309,7 +332,8 @@ export class InvoiceDocumentService {
       </div>
     </div>
     <div class="${sealCssClass}">${sealInner}</div>
-    <div class="summary">${summaryRows}</div>
+    ${qrMarkup}
+    <div class="summary${model.qrImageUrl ? " summary-with-qr" : ""}">${summaryRows}</div>
     <table>
       <thead>
         <tr>
diff --git a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts
index fa0876310..927e2efec 100644
--- a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts
@@ -55,7 +55,7 @@ const context = (over: Partial<EimsMapperContext> = {}): EimsMapperContext => ({
   salesPersonName: null,
   transactionType: "B2B",
   payment: { mode: "CASH", term: "IMMIDIATE" },
-  taxForLine: () => ({ code: "VAT15", ratePercent: 15, exciseTaxValue: 0 }),
+  taxForLine: () => ({ code: "VAT15", ratePercent: 15, exciseTaxValue: 0, discount: 0 }),
   natureOfSupplies: "Service",
   unitDefault: "PCS",
   incomeWithholdValue: 0,
@@ -115,8 +115,8 @@ describe("toEimsInvoice", () => {
       context({
         taxForLine: (line) =>
           line.chargeType === "RAIL_FREIGHT"
-            ? { code: "VAT15", ratePercent: 15, exciseTaxValue: 0 }
-            : { code: "EXEMPT", ratePercent: 0, exciseTaxValue: 50 },
+            ? { code: "VAT15", ratePercent: 15, exciseTaxValue: 0, discount: 0 }
+            : { code: "EXEMPT", ratePercent: 0, exciseTaxValue: 50, discount: 25 },
       }),
     );
 
@@ -130,6 +130,7 @@ describe("toEimsInvoice", () => {
       TaxCode: "VAT15",
       TaxAmount: 1500,
       ExciseTaxValue: 0,
+      Discount: 0,
       TotalLineAmount: 11500,
       Unit: "PCS",
       NatureOfSupplies: "service",
@@ -141,6 +142,9 @@ describe("toEimsInvoice", () => {
       TaxCode: "EXEMPT",
       TaxAmount: 0,
       ExciseTaxValue: 50,
+      // Discount is carried on the line but does not (yet) reduce TotalLineAmount — see the
+      // EimsLineTax.discount comment in eims-invoice.mapper.ts.
+      Discount: 25,
       TotalLineAmount: 1050,
       Unit: "CTR",
     });
@@ -187,7 +191,17 @@ describe("toEimsInvoice", () => {
       toEimsInvoice(
         invoice(),
         seller,
-        context({ taxForLine: () => ({ code: "", ratePercent: 15, exciseTaxValue: 0 }) }),
+        context({ taxForLine: () => ({ code: "", ratePercent: 15, exciseTaxValue: 0, discount: 0 }) }),
+      ),
+    ).toThrow(/unresolved tax treatment for line 1/);
+
+    expect(() =>
+      toEimsInvoice(
+        invoice(),
+        seller,
+        context({
+          taxForLine: () => ({ code: "VAT15", ratePercent: 15, exciseTaxValue: 0, discount: NaN }),
+        }),
       ),
     ).toThrow(/unresolved tax treatment for line 1/);
   });
diff --git a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
index 0c4b40829..fb7f2f145 100644
--- a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
+++ b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
@@ -183,6 +183,12 @@ export interface EimsLineTax {
   code: string;
   ratePercent: number;
   exciseTaxValue: number;
+  /**
+   * Line-level `Discount`. Its effect on `TotalLineAmount` has never been observed live (every
+   * prior test ran it at 0), so the total below still sums PreTax + Tax + Excise only — do not
+   * start subtracting this without a confirmed MoR example.
+   */
+  discount: number;
 }
 
 export interface EimsMapperContext {
@@ -336,7 +342,13 @@ export function toEimsInvoice(
   const ItemList: EimsInvoiceItem[] = invoice.lines.map((line, index) => {
     const lineNumber = index + 1;
     const tax = context.taxForLine(line, lineNumber);
-    if (!tax || !tax.code || !Number.isFinite(tax.ratePercent) || !Number.isFinite(tax.exciseTaxValue)) {
+    if (
+      !tax ||
+      !tax.code ||
+      !Number.isFinite(tax.ratePercent) ||
+      !Number.isFinite(tax.exciseTaxValue) ||
+      !Number.isFinite(tax.discount)
+    ) {
       throw new Error(
         `EIMS mapping: unresolved tax treatment for line ${lineNumber} (${line.chargeType}) ` +
           `on invoice ${invoice.invoiceNumber}`,
@@ -349,7 +361,7 @@ export function toEimsInvoice(
     const unit = typeof line.metadata?.unit === "string" ? line.metadata.unit : context.unitDefault;
 
     return {
-      Discount: 0,
+      Discount: round2(tax.discount),
       ExciseTaxValue,
       HarmonizationCode: null,
       NatureOfSupplies: natureOfSupplies,
diff --git a/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts b/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
index 411d15ebe..d6bee3eae 100644
--- a/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
+++ b/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
@@ -111,10 +111,22 @@ export class Invoice extends BaseEntity {
   @Column({ name: "eims_status", type: "varchar", length: 20, default: "NOT_SUBMITTED" })
   eimsStatus!: EimsInvoiceStatus;
 
-  /** Invoice Reference Number returned by EIMS. Unique across invoices (partial index). */
-  @Column({ name: "eims_irn", type: "varchar", length: 64, nullable: true })
+  /**
+   * Invoice Reference Number returned by EIMS. Unique across invoices (partial index). `text`,
+   * not a fixed varchar — MoR has never documented an IRN format/length, and a real live value
+   * (a `test-` prefix + 64 hex chars, 69 chars total) already overflowed a prior varchar(64).
+   */
+  @Column({ name: "eims_irn", type: "text", nullable: true })
   eimsIrn?: string | null;
 
+  /**
+   * `signedQR` from the register response — a base64 PNG image, already rendered by MoR (confirmed
+   * against the Postman collection's saved response: decodes to a PNG magic-byte header). Stored
+   * verbatim; `BillingService.renderEimsQr` only wraps it in a `data:image/png;base64,` URL.
+   */
+  @Column({ name: "eims_signed_qr", type: "text", nullable: true })
+  eimsSignedQr?: string | null;
+
   /** The numeric `DocumentDetails.DocumentNumber` filed for this invoice. */
   @Column({ name: "eims_document_number", type: "varchar", length: 16, nullable: true })
   eimsDocumentNumber?: string | null;
@@ -133,4 +145,24 @@ export class Invoice extends BaseEntity {
   /** Sanitized last failure: the gateway's own error fields only, never our signed envelope. */
   @Column({ name: "eims_last_error", type: "jsonb", nullable: true })
   eimsLastError?: EimsInvoiceError | null;
+
+  /**
+   * `POST /v1/cancel` — set together, only once `eimsStatus` reaches CANCELLED.
+   * `eimsCancelledAt` is our own server time (same convention as `eimsSubmittedAt`);
+   * `eimsCancellationDate` is MoR's own confirmation string, stored verbatim like `eimsAckDate` —
+   * its format (`"Sun Dec 22 21:55:03 EAT 2024"`, a Java `Date#toString()`) is not reliably
+   * `Date.parse`-able (the `EAT` zone abbreviation is non-standard), so it is never parsed.
+   */
+  @Column({ name: "eims_cancelled_at", type: "timestamptz", nullable: true })
+  eimsCancelledAt?: Date | null;
+
+  @Column({ name: "eims_cancellation_date", type: "varchar", length: 64, nullable: true })
+  eimsCancellationDate?: string | null;
+
+  /** Numeric string per the collection docs, e.g. "1" (Duplicate), "6" (Calculation Error). */
+  @Column({ name: "eims_cancellation_reason_code", type: "varchar", length: 8, nullable: true })
+  eimsCancellationReasonCode?: string | null;
+
+  @Column({ name: "eims_cancellation_remark", type: "text", nullable: true })
+  eimsCancellationRemark?: string | null;
 }
diff --git a/apps/edr-freight-api/src/modules/eims/dto/cancel-eims-registration.dto.ts b/apps/edr-freight-api/src/modules/eims/dto/cancel-eims-registration.dto.ts
new file mode 100644
index 000000000..c1ad0c0a1
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/dto/cancel-eims-registration.dto.ts
@@ -0,0 +1,19 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { IsOptional, IsString, Length } from "class-validator";
+
+/** `POST /v1/cancel` body — `ReasonCode`/`Remark` are the collection's own field names. */
+export class CancelEimsRegistrationDto {
+  @ApiProperty({
+    description: 'Numeric reason code, e.g. "1" (Duplicate), "6" (Calculation Error).',
+    example: "1",
+  })
+  @IsString()
+  @Length(1, 8)
+  reasonCode!: string;
+
+  @ApiPropertyOptional({ description: "Free-text cancellation note.", example: "Duplicate submission" })
+  @IsOptional()
+  @IsString()
+  @Length(0, 500)
+  remark?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/eims/dto/register-sales-receipt.dto.ts b/apps/edr-freight-api/src/modules/eims/dto/register-sales-receipt.dto.ts
new file mode 100644
index 000000000..70681f814
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/dto/register-sales-receipt.dto.ts
@@ -0,0 +1,88 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { IsIn, IsNumber, IsOptional, IsString, Length } from "class-validator";
+
+import { EIMS_MODE_OF_PAYMENT, EimsModeOfPayment } from "../eims-receipt.types";
+
+/**
+ * `POST /v1/receipt/sales` — invoice/amounts/currency/IRN are derived from the invoice; everything
+ * here is what this codebase has no source of truth for, so it is asked of the caller rather than
+ * guessed (payment method, collector, provider references — none of it is modelled on `Invoice`).
+ */
+export class RegisterSalesReceiptDto {
+  @ApiProperty({ enum: EIMS_MODE_OF_PAYMENT, description: "MoR's confirmed ModeOfPayment enum." })
+  @IsIn(EIMS_MODE_OF_PAYMENT)
+  modeOfPayment!: EimsModeOfPayment;
+
+  @ApiPropertyOptional({ description: 'Defaults to "Payment received".' })
+  @IsOptional()
+  @IsString()
+  reason?: string;
+
+  @ApiPropertyOptional({ description: "Overrides the amount collected; defaults to the invoice's paidAmount." })
+  @IsOptional()
+  @IsNumber()
+  collectedAmount?: number;
+
+  @ApiPropertyOptional({ description: "ETB, USD or CAD. Defaults to the invoice's currency." })
+  @IsOptional()
+  @IsString()
+  currency?: string;
+
+  @ApiPropertyOptional({ description: "Required when currency is not ETB." })
+  @IsOptional()
+  @IsNumber()
+  exchangeRate?: number;
+
+  @ApiPropertyOptional({ description: 'Defaults to "FULL" if the invoice balance is 0, else "PARTIAL".' })
+  @IsOptional()
+  @IsString()
+  paymentCoverage?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  @Length(0, 200)
+  collectorName?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  @Length(0, 200)
+  paymentServiceProvider?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  @Length(0, 200)
+  otherPaymentServiceProviderName?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  @Length(0, 100)
+  accountNumber?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  @Length(0, 100)
+  transactionNumber?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  @Length(0, 100)
+  chequeNumber?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  @Length(0, 100)
+  cpoNumber?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  @Length(0, 100)
+  documentNumber?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/eims/dto/register-withholding-receipt.dto.ts b/apps/edr-freight-api/src/modules/eims/dto/register-withholding-receipt.dto.ts
new file mode 100644
index 000000000..d82f2aa70
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/dto/register-withholding-receipt.dto.ts
@@ -0,0 +1,40 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { IsNumber, IsOptional, IsString, Length } from "class-validator";
+
+/**
+ * `POST /v1/receipt/withholding`. `type`/`preTaxAmount`/`withholdingAmount` are real money/tax
+ * values this codebase has no computed source for (the same "no tax model" gap the invoice mapper
+ * documents) — required from the caller rather than defaulted or derived.
+ */
+export class RegisterWithholdingReceiptDto {
+  @ApiProperty({
+    description: 'WithholdDetail.Type. Only "TWHT" has been observed; not restricted to it.',
+    example: "TWHT",
+  })
+  @IsString()
+  @Length(1, 16)
+  type!: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsNumber()
+  rate?: number;
+
+  @ApiProperty({ description: "Amount the withholding is calculated against." })
+  @IsNumber()
+  preTaxAmount!: number;
+
+  @ApiProperty({ description: "The withheld amount itself." })
+  @IsNumber()
+  withholdingAmount!: number;
+
+  @ApiPropertyOptional({ description: 'Defaults to "Withholding".' })
+  @IsOptional()
+  @IsString()
+  reason?: string;
+
+  @ApiPropertyOptional({ description: "Required when the invoice currency is not ETB." })
+  @IsOptional()
+  @IsNumber()
+  exchangeRate?: number;
+}
diff --git a/apps/edr-freight-api/src/modules/eims/dto/resolve-eims-registration.dto.ts b/apps/edr-freight-api/src/modules/eims/dto/resolve-eims-registration.dto.ts
index 66896fd18..f66e71e16 100644
--- a/apps/edr-freight-api/src/modules/eims/dto/resolve-eims-registration.dto.ts
+++ b/apps/edr-freight-api/src/modules/eims/dto/resolve-eims-registration.dto.ts
@@ -10,9 +10,11 @@ export class ResolveEimsRegistrationDto {
     description: "IRN confirmed in the MoR portal. Records the registration and resumes the chain.",
     example: "9fe9bbbece6ab76c112b617534e6aac7aa8b819d5be79f4d3d088ed2e887b2e0",
   })
+  // Not capped at 64: eims_irn is `text` now — a real IRN already overflowed a former
+  // varchar(64) (69 chars). This bound is a sanity ceiling, not a confirmed MoR format.
   @IsOptional()
   @IsString()
-  @Length(1, 64)
+  @Length(1, 500)
   irn?: string;
 
   @ApiPropertyOptional({
diff --git a/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.spec.ts
new file mode 100644
index 000000000..ab5ea2548
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.spec.ts
@@ -0,0 +1,153 @@
+import { BadRequestException } from "@nestjs/common";
+import { DataSource } from "typeorm";
+
+import { Invoice } from "../billing/entities/invoice.entity";
+import { NotificationsService } from "../notifications/notifications.service";
+import { EimsCancellationService } from "./eims-cancellation.service";
+import { EimsClientService } from "./eims-client.service";
+import { EimsApiException } from "./eims.errors";
+import { EimsInvoiceStatus } from "./eims-registration.types";
+
+const INVOICE_ID = "11111111-1111-4111-8111-111111111111";
+const IRN = "9fe9bbbece6ab76c112b617534e6aac7aa8b819d5be79f4d3d088ed2e887b2e0";
+
+const invoiceRow = (over: Partial<Invoice> = {}): Invoice =>
+  ({
+    id: INVOICE_ID,
+    invoiceNumber: "INV-20260807-00042",
+    companyId: "company-1",
+    eimsStatus: EimsInvoiceStatus.Registered,
+    eimsIrn: IRN,
+    eimsCancelledAt: null,
+    eimsCancellationDate: null,
+    eimsCancellationReasonCode: null,
+    eimsCancellationRemark: null,
+    ...over,
+  }) as unknown as Invoice;
+
+/** In-memory stand-in, same shape as the registration spec's FakeDb but with only what cancel needs. */
+class FakeDb {
+  invoices = new Map<string, Invoice>();
+  companyContact: { phone: string | null; email: string | null } | null = null;
+
+  constructor(invoices: Invoice[]) {
+    for (const inv of invoices) this.invoices.set(inv.id, inv);
+  }
+
+  private manager = {
+    createQueryBuilder: (entity: unknown) => {
+      let id: string | undefined;
+      const builder = {
+        setLock: () => builder,
+        where: (_clause: string, params: Record<string, string>) => {
+          id = params.invoiceId;
+          return builder;
+        },
+        getOne: async () => (entity === Invoice ? (this.invoices.get(id!) ?? null) : null),
+      };
+      return builder;
+    },
+    findOne: async (_entity: unknown, options: { where: { id: string } }) =>
+      this.invoices.get(options.where.id) ?? null,
+    update: async (_entity: unknown, id: string, patch: Record<string, unknown>) => {
+      Object.assign(this.invoices.get(id)!, patch);
+    },
+  };
+
+  asDataSource(): DataSource {
+    return {
+      manager: this.manager,
+      query: async () => (this.companyContact ? [this.companyContact] : []),
+      transaction: async (body: (m: unknown) => Promise<unknown>) => body(this.manager),
+    } as unknown as DataSource;
+  }
+}
+
+const build = (db: FakeDb, postBearer: jest.Mock, directSend: jest.Mock = jest.fn().mockResolvedValue(undefined)) =>
+  new EimsCancellationService(
+    db.asDataSource(),
+    { postBearer } as unknown as EimsClientService,
+    { directSend } as unknown as NotificationsService,
+  );
+
+describe("EimsCancellationService.cancelInvoiceWithEims", () => {
+  it("cancels a registered invoice and persists MoR's confirmation", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postBearer = jest
+      .fn()
+      .mockResolvedValue({ statusCode: 200, message: "Success", body: { cancellationDate: "Sun Dec 22 21:55:03 EAT 2024" } });
+
+    const view = await build(db, postBearer).cancelInvoiceWithEims(INVOICE_ID, "1", "Duplicate");
+
+    expect(postBearer).toHaveBeenCalledWith("/v1/cancel", { Irn: IRN, ReasonCode: "1", Remark: "Duplicate" });
+    expect(view.eimsStatus).toBe(EimsInvoiceStatus.Cancelled);
+    expect(view.eimsCancellationDate).toBe("Sun Dec 22 21:55:03 EAT 2024");
+    expect(view.eimsCancellationReasonCode).toBe("1");
+    expect(view.eimsCancellationRemark).toBe("Duplicate");
+    expect(db.invoices.get(INVOICE_ID)?.eimsCancelledAt).toBeInstanceOf(Date);
+  });
+
+  it("defaults Remark to an empty string, matching the collection's request shape", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postBearer = jest.fn().mockResolvedValue({ statusCode: 200, body: { cancellationDate: "x" } });
+
+    await build(db, postBearer).cancelInvoiceWithEims(INVOICE_ID, "1");
+
+    expect(postBearer).toHaveBeenCalledWith("/v1/cancel", { Irn: IRN, ReasonCode: "1", Remark: "" });
+  });
+
+  it("is idempotent — an already-cancelled invoice returns unchanged, no HTTP call", async () => {
+    const db = new FakeDb([invoiceRow({ eimsStatus: EimsInvoiceStatus.Cancelled })]);
+    const postBearer = jest.fn();
+
+    const view = await build(db, postBearer).cancelInvoiceWithEims(INVOICE_ID, "1");
+
+    expect(postBearer).not.toHaveBeenCalled();
+    expect(view.eimsStatus).toBe(EimsInvoiceStatus.Cancelled);
+  });
+
+  it("refuses to cancel an invoice that was never registered", async () => {
+    const db = new FakeDb([invoiceRow({ eimsStatus: EimsInvoiceStatus.NotSubmitted, eimsIrn: null })]);
+    const postBearer = jest.fn();
+
+    await expect(build(db, postBearer).cancelInvoiceWithEims(INVOICE_ID, "1")).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+    expect(postBearer).not.toHaveBeenCalled();
+  });
+
+  it("propagates a MoR rejection and leaves the invoice REGISTERED", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postBearer = jest
+      .fn()
+      .mockRejectedValue(new EimsApiException("RULE_VALIDATION", "EIMS cancel failed (406)", 406));
+
+    await expect(build(db, postBearer).cancelInvoiceWithEims(INVOICE_ID, "1")).rejects.toBeInstanceOf(
+      EimsApiException,
+    );
+    expect(db.invoices.get(INVOICE_ID)?.eimsStatus).toBe(EimsInvoiceStatus.Registered);
+  });
+
+  it("notifies the buyer company on success, without blocking the result", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    db.companyContact = { phone: "+251911000000", email: "buyer@abc.et" };
+    const directSend = jest.fn().mockResolvedValue(undefined);
+    const postBearer = jest.fn().mockResolvedValue({ statusCode: 200, body: { cancellationDate: "x" } });
+
+    const view = await build(db, postBearer, directSend).cancelInvoiceWithEims(INVOICE_ID, "1");
+
+    expect(view.eimsStatus).toBe(EimsInvoiceStatus.Cancelled);
+    expect(directSend).toHaveBeenCalledWith("sms", "+251911000000", expect.stringContaining("cancelled"));
+  });
+
+  it("does not fail cancellation when the buyer notification itself fails", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    db.companyContact = { phone: "+251911000000", email: null };
+    const directSend = jest.fn().mockRejectedValue(new Error("sms provider down"));
+    const postBearer = jest.fn().mockResolvedValue({ statusCode: 200, body: { cancellationDate: "x" } });
+
+    const view = await build(db, postBearer, directSend).cancelInvoiceWithEims(INVOICE_ID, "1");
+
+    expect(view.eimsStatus).toBe(EimsInvoiceStatus.Cancelled);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.ts b/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.ts
new file mode 100644
index 000000000..83ff16704
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.ts
@@ -0,0 +1,117 @@
+import { BadRequestException, Injectable, Logger, NotFoundException } from "@nestjs/common";
+import { InjectDataSource } from "@nestjs/typeorm";
+import { DataSource, EntityManager } from "typeorm";
+
+import { Invoice } from "../billing/entities/invoice.entity";
+import { NotificationsService } from "../notifications/notifications.service";
+import { sendCompanyChannels } from "../notifications/notify-company.util";
+import { EimsClientService } from "./eims-client.service";
+import { EimsCancelRequest, EimsCancelResponse, EimsInvoiceStatus, EimsInvoiceStatusView } from "./eims-registration.types";
+import { toEimsInvoiceStatusView } from "./eims-invoice-view.util";
+
+/**
+ * `POST /v1/cancel` for one already-registered invoice.
+ *
+ * Simpler than registration: cancellation carries no `InvoiceCounter`/`DocumentNumber`, so none of
+ * `EimsSystemState`'s reservation machinery applies, and — unlike registration — a retried cancel
+ * is safe: the collection's bulk-cancel example shows MoR itself rejects a second cancel with
+ * "IRN already Canceled.", so there is no double-filing risk the way an unacknowledged register
+ * call has. That is what makes the simpler shape below correct: no system-wide block, no in-flight
+ * marker, just a lock-check-unlock before the call and a fresh lock-check-write after it.
+ *
+ * ponytail: the eligibility check (TX1) and the write (TX2) are not one atomic operation, so two
+ * concurrent cancels on the same invoice could both pass TX1 and both call MoR — wasted, but safe,
+ * per the paragraph above. Upgrade to a single locked reservation (like registration's) only if
+ * MoR's cancel endpoint turns out not to be idempotent after all.
+ *
+ * Bearer-authenticated but unsigned (`postBearer`), same as `/v1/verify` — the collection's saved
+ * `/v1/cancel` request carries no `{request,signature,certificate}` envelope.
+ */
+@Injectable()
+export class EimsCancellationService {
+  private readonly logger = new Logger(EimsCancellationService.name);
+
+  constructor(
+    @InjectDataSource() private readonly dataSource: DataSource,
+    private readonly client: EimsClientService,
+    private readonly notifications: NotificationsService,
+  ) {}
+
+  /**
+   * Idempotent: an already-cancelled invoice returns unchanged, no HTTP call. Refuses an invoice
+   * that was never registered — there is no IRN to cancel.
+   */
+  async cancelInvoiceWithEims(
+    invoiceId: string,
+    reasonCode: string,
+    remark?: string,
+  ): Promise<EimsInvoiceStatusView> {
+    const eligible = await this.dataSource.transaction(async (manager) => {
+      const invoice = await this.lockInvoice(manager, invoiceId);
+      if (invoice.eimsStatus === EimsInvoiceStatus.Cancelled) return null;
+      if (!invoice.eimsIrn) {
+        throw new BadRequestException({
+          code: "EIMS_NOT_REGISTERED",
+          message: `Invoice ${invoice.invoiceNumber} was never registered with EIMS — nothing to cancel.`,
+        });
+      }
+      return invoice;
+    });
+    if (!eligible) return this.getEimsCancellationStatus(invoiceId);
+
+    const request: EimsCancelRequest = { Irn: eligible.eimsIrn!, ReasonCode: reasonCode, Remark: remark ?? "" };
+    // Outside any transaction — no DB lock is held across the wire.
+    const response = await this.client.postBearer<EimsCancelRequest, EimsCancelResponse>(
+      "/v1/cancel",
+      request,
+    );
+    const cancellationDate = response?.body?.cancellationDate ?? null;
+
+    await this.dataSource.transaction(async (manager) => {
+      const invoice = await this.lockInvoice(manager, invoiceId);
+      // Re-checked under lock: a concurrent call may have already recorded this cancellation.
+      if (invoice.eimsStatus === EimsInvoiceStatus.Cancelled) return;
+      await manager.update(Invoice, invoiceId, {
+        eimsStatus: EimsInvoiceStatus.Cancelled,
+        eimsCancelledAt: new Date(),
+        eimsCancellationDate: cancellationDate,
+        eimsCancellationReasonCode: reasonCode,
+        eimsCancellationRemark: remark ?? null,
+      });
+    });
+    this.logger.log(`Invoice ${eligible.invoiceNumber} cancelled with EIMS (IRN ${eligible.eimsIrn})`);
+
+    await this.notifyBuyer(eligible);
+    return this.getEimsCancellationStatus(invoiceId);
+  }
+
+  async getEimsCancellationStatus(invoiceId: string): Promise<EimsInvoiceStatusView> {
+    const invoice = await this.dataSource.manager.findOne(Invoice, { where: { id: invoiceId } });
+    if (!invoice) throw new NotFoundException(`Invoice ${invoiceId} not found`);
+    return toEimsInvoiceStatusView(invoice);
+  }
+
+  /** Best-effort — a notification failure must never mask a cancellation that already succeeded. */
+  private async notifyBuyer(invoice: Invoice): Promise<void> {
+    try {
+      await sendCompanyChannels(
+        this.dataSource,
+        this.notifications,
+        invoice.companyId,
+        `Invoice ${invoice.invoiceNumber} has been cancelled with MoR EIMS.`,
+      );
+    } catch (err) {
+      this.logger.warn(`EIMS buyer notification failed for invoice ${invoice.id}: ${(err as Error).message}`);
+    }
+  }
+
+  private async lockInvoice(manager: EntityManager, invoiceId: string): Promise<Invoice> {
+    const invoice = await manager
+      .createQueryBuilder(Invoice, "invoice")
+      .setLock("pessimistic_write")
+      .where("invoice.id = :invoiceId", { invoiceId })
+      .getOne();
+    if (!invoice) throw new NotFoundException(`Invoice ${invoiceId} not found`);
+    return invoice;
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-context.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-context.spec.ts
new file mode 100644
index 000000000..251f71cbd
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-context.spec.ts
@@ -0,0 +1,118 @@
+import { assertEimsInvoiceConfig, buildEimsContext } from "./eims-invoice-context";
+import { eimsConfig } from "./eims-test-fixtures";
+
+const SESSION = { systemNumber: "B0360154BA", systemType: "SYS" };
+
+describe("assertEimsInvoiceConfig — charge-type overrides", () => {
+  it("passes when EIMS_TAX_CODE_BY_CHARGE_TYPE and _RATE_ list the same charge types", () => {
+    expect(() =>
+      assertEimsInvoiceConfig(
+        eimsConfig({
+          invoice: {
+            ...eimsConfig().invoice,
+            taxCodeByChargeType: { RAIL_FREIGHT: "VAT0" },
+            taxRateByChargeType: { RAIL_FREIGHT: "0" },
+          },
+        }),
+      ),
+    ).not.toThrow();
+  });
+
+  it("throws when a charge type has a code but no rate, or a rate but no code", () => {
+    expect(() =>
+      assertEimsInvoiceConfig(
+        eimsConfig({
+          invoice: {
+            ...eimsConfig().invoice,
+            taxCodeByChargeType: { RAIL_FREIGHT: "VAT0" },
+            taxRateByChargeType: {},
+          },
+        }),
+      ),
+    ).toThrow(/mismatched: RAIL_FREIGHT/);
+
+    expect(() =>
+      assertEimsInvoiceConfig(
+        eimsConfig({
+          invoice: {
+            ...eimsConfig().invoice,
+            taxCodeByChargeType: {},
+            taxRateByChargeType: { RAIL_FREIGHT: "0" },
+          },
+        }),
+      ),
+    ).toThrow(/mismatched: RAIL_FREIGHT/);
+  });
+
+  it("throws when a rate/excise/discount override is not a number", () => {
+    expect(() =>
+      assertEimsInvoiceConfig(
+        eimsConfig({
+          invoice: {
+            ...eimsConfig().invoice,
+            taxCodeByChargeType: { RAIL_FREIGHT: "VAT0" },
+            taxRateByChargeType: { RAIL_FREIGHT: "not-a-number" },
+          },
+        }),
+      ),
+    ).toThrow(/EIMS_TAX_RATE_BY_CHARGE_TYPE\[RAIL_FREIGHT\]/);
+
+    expect(() =>
+      assertEimsInvoiceConfig(
+        eimsConfig({ invoice: { ...eimsConfig().invoice, discountByChargeType: { X: "abc" } } }),
+      ),
+    ).toThrow(/EIMS_DISCOUNT_BY_CHARGE_TYPE\[X\]/);
+  });
+});
+
+describe("buildEimsContext — taxForLine", () => {
+  const input = { documentNumber: "24", invoiceCounter: 7, previousIrn: "", session: SESSION };
+  const line = (chargeType: string) => ({ chargeType, quantity: 1, unitRate: 100, amount: 100 });
+
+  it("uses the per-chargeType override when one is configured", () => {
+    const context = buildEimsContext(
+      eimsConfig({
+        invoice: {
+          ...eimsConfig().invoice,
+          taxCode: "VAT15",
+          taxRatePercent: 15,
+          taxCodeByChargeType: { RAIL_FREIGHT: "VAT0" },
+          taxRateByChargeType: { RAIL_FREIGHT: "0" },
+          exciseByChargeType: { RAIL_FREIGHT: "5" },
+          discountByChargeType: { RAIL_FREIGHT: "10" },
+        },
+      }),
+      input,
+    );
+
+    expect(context.taxForLine(line("RAIL_FREIGHT"), 1)).toEqual({
+      code: "VAT0",
+      ratePercent: 0,
+      exciseTaxValue: 5,
+      discount: 10,
+    });
+  });
+
+  it("falls back to the invoice-wide default for a charge type with no override", () => {
+    const context = buildEimsContext(
+      eimsConfig({
+        invoice: {
+          ...eimsConfig().invoice,
+          taxCode: "VAT15",
+          taxRatePercent: 15,
+          exciseTaxValue: 0,
+          taxCodeByChargeType: { RAIL_FREIGHT: "VAT0" },
+          taxRateByChargeType: { RAIL_FREIGHT: "0" },
+        },
+      }),
+      input,
+    );
+
+    expect(context.taxForLine(line("HANDLING"), 1)).toEqual({
+      code: "VAT15",
+      ratePercent: 15,
+      exciseTaxValue: 0,
+      discount: 0,
+    });
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts
index 4e7a82069..8e7be0197 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts
@@ -59,6 +59,47 @@ export function assertEimsInvoiceConfig(config: EimsConfig): void {
   }
 
   assertSellerFormats(config.invoice);
+  assertChargeTypeOverrides(config.invoice);
+}
+
+/**
+ * Per-`chargeType` tax overrides must be internally consistent before anything is filed:
+ * `EIMS_TAX_CODE_BY_CHARGE_TYPE` and `EIMS_TAX_RATE_BY_CHARGE_TYPE` must name the same charge
+ * types (a code with no rate, or vice versa, is a half-finished override), and every rate/excise/
+ * discount value must parse as a number — checked once here rather than once per line at
+ * registration time.
+ */
+function assertChargeTypeOverrides(invoice: EimsConfig["invoice"]): void {
+  const codeKeys = Object.keys(invoice.taxCodeByChargeType);
+  const rateKeys = Object.keys(invoice.taxRateByChargeType);
+  const mismatched = [...new Set([...codeKeys, ...rateKeys])].filter(
+    (k) => !(codeKeys.includes(k) && rateKeys.includes(k)),
+  );
+  if (mismatched.length > 0) {
+    throw new BadRequestException({
+      code: "EIMS_INVOICE_CONFIG_INVALID",
+      message:
+        `EIMS_TAX_CODE_BY_CHARGE_TYPE and EIMS_TAX_RATE_BY_CHARGE_TYPE must list the same charge ` +
+        `types; mismatched: ${mismatched.join(", ")}`,
+    });
+  }
+
+  const numericMaps: { env: string; map: Record<string, string> }[] = [
+    { env: "EIMS_TAX_RATE_BY_CHARGE_TYPE", map: invoice.taxRateByChargeType },
+    { env: "EIMS_EXCISE_BY_CHARGE_TYPE", map: invoice.exciseByChargeType },
+    { env: "EIMS_DISCOUNT_BY_CHARGE_TYPE", map: invoice.discountByChargeType },
+  ];
+  const badNumbers = numericMaps.flatMap(({ env, map }) =>
+    Object.entries(map)
+      .filter(([, value]) => !Number.isFinite(Number(value)))
+      .map(([chargeType]) => `${env}[${chargeType}]`),
+  );
+  if (badNumbers.length > 0) {
+    throw new BadRequestException({
+      code: "EIMS_INVOICE_CONFIG_INVALID",
+      message: `EIMS charge-type overrides must be numbers: ${badNumbers.join(", ")}`,
+    });
+  }
 }
 
 /**
@@ -135,9 +176,25 @@ export function buildEimsContext(config: EimsConfig, input: EimsContextInput): E
     salesPersonName: invoice.salesPersonName,
     transactionType: invoice.transactionType,
     payment: { mode: invoice.paymentMode, term: invoice.paymentTerm },
-    // One treatment for every line today. The mapper resolves tax per line, so a future
-    // charge-type-specific rule slots in here without touching the mapper.
-    taxForLine: (_line: EimsMapperLine) => ({ code: taxCode, ratePercent, exciseTaxValue }),
+    // Per-`chargeType` override when one is configured (validated symmetric in
+    // assertChargeTypeOverrides), else the single invoice-wide default.
+    taxForLine: (line: EimsMapperLine) => {
+      const { chargeType } = line;
+      const code = invoice.taxCodeByChargeType[chargeType] ?? taxCode;
+      const rate =
+        chargeType in invoice.taxRateByChargeType
+          ? Number(invoice.taxRateByChargeType[chargeType])
+          : ratePercent;
+      const excise =
+        chargeType in invoice.exciseByChargeType
+          ? Number(invoice.exciseByChargeType[chargeType])
+          : exciseTaxValue;
+      const discount =
+        chargeType in invoice.discountByChargeType
+          ? Number(invoice.discountByChargeType[chargeType])
+          : 0;
+      return { code, ratePercent: rate, exciseTaxValue: excise, discount };
+    },
     natureOfSupplies: invoice.natureOfSupplies,
     unitDefault: invoice.unitDefault,
     incomeWithholdValue: invoice.incomeWithholdValue!,
@@ -145,6 +202,9 @@ export function buildEimsContext(config: EimsConfig, input: EimsContextInput): E
     buyerCountryCode: invoice.buyerCountryCode,
     buyerRegionCodes: invoice.buyerRegionCodes,
     buyerWeredaCodes: invoice.buyerWeredaCodes,
+    // TEMPORARY — see EimsInvoiceConfig.buyerIdType.
+    buyerIdType: invoice.buyerIdType,
+    buyerIdNumber: invoice.buyerIdNumber,
     exchangeRate: input.exchangeRate ?? null,
   };
 }
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
index 66e27da6b..8c2a33cfc 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
@@ -7,6 +7,7 @@ import { Invoice } from "../billing/entities/invoice.entity";
 import { EimsInvoiceRequest } from "../billing/eims-invoice.mapper";
 import { eimsInvoiceConfig } from "./eims-test-fixtures";
 import { NotificationInboxService } from "../notification-inbox/notification-inbox.service";
+import { NotificationsService } from "../notifications/notifications.service";
 import { EimsAuthService } from "./eims-auth.service";
 import { EimsClientService } from "./eims-client.service";
 import { EimsApiException } from "./eims.errors";
@@ -85,6 +86,8 @@ class FakeDb {
   state: EimsSystemState | null = null;
   /** Runs before every transaction body, to simulate a concurrent writer. */
   onTransaction: (() => void) | null = null;
+  /** `sendCompanyChannels`'s contact lookup, when a test needs it non-empty. */
+  companyContact: { phone: string | null; email: string | null } | null = null;
 
   constructor(invoices: Invoice[], state?: Partial<EimsSystemState>) {
     for (const inv of invoices) this.invoices.set(inv.id, inv);
@@ -133,10 +136,13 @@ class FakeDb {
     return {
       manager: this.manager,
       getRepository: this.manager.getRepository,
-      query: async (sql: string) =>
-        sql.includes("eims_system_state")
-          ? [{ in_flight_invoice_id: this.state?.inFlightInvoiceId ?? null }]
-          : LINES,
+      query: async (sql: string) => {
+        if (sql.includes("eims_system_state")) {
+          return [{ in_flight_invoice_id: this.state?.inFlightInvoiceId ?? null }];
+        }
+        if (sql.includes("freight.companies")) return this.companyContact ? [this.companyContact] : [];
+        return LINES;
+      },
       transaction: async (body: (m: unknown) => Promise<unknown>) => {
         this.onTransaction?.();
         return body(this.manager);
@@ -155,6 +161,7 @@ const build = (
   postBearer: jest.Mock = jest.fn(),
   getSessionContext: jest.Mock | undefined = undefined,
   notify: jest.Mock = jest.fn().mockResolvedValue(undefined),
+  directSend: jest.Mock = jest.fn().mockResolvedValue(undefined),
 ) =>
   new EimsInvoiceRegistrationService(
     db.asDataSource(),
@@ -164,6 +171,7 @@ const build = (
       getSessionContext: getSessionContext ?? jest.fn().mockResolvedValue(SESSION),
     } as unknown as EimsAuthService,
     { notify } as unknown as NotificationInboxService,
+    { directSend } as unknown as NotificationsService,
   );
 
 /**
@@ -196,8 +204,11 @@ const verifyResponse = (over: Record<string, unknown> = {}) => ({
   },
 });
 
-const okResponse = (irn = IRN) =>
-  ({ statusCode: 200, message: "SUCCESS", body: { irn, ackDate: "2026-08-07T09:05:03Z[Etc/UTC]" } });
+const okResponse = (irn = IRN, over: Record<string, unknown> = {}) => ({
+  statusCode: 200,
+  message: "SUCCESS",
+  body: { irn, ackDate: "2026-08-07T09:05:03Z[Etc/UTC]", ...over },
+});
 
 const apiError = (kind: string, status?: number) =>
   new EimsApiException(kind as never, `EIMS register failed (${status ?? "-"})`, status);
@@ -226,6 +237,51 @@ describe("EimsInvoiceRegistrationService.registerInvoiceWithEims", () => {
     });
   });
 
+  it("persists signedQR alongside the IRN", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postSigned = jest.fn().mockResolvedValue(okResponse(IRN, { signedQR: "signed-qr-payload" }));
+
+    const view = await build(db, postSigned).registerInvoiceWithEims(INVOICE_ID);
+
+    expect(view.eimsSignedQr).toBe("signed-qr-payload");
+    expect(db.invoices.get(INVOICE_ID)?.eimsSignedQr).toBe("signed-qr-payload");
+  });
+
+  it("leaves eimsSignedQr null when the gateway does not return one", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postSigned = jest.fn().mockResolvedValue(okResponse());
+
+    const view = await build(db, postSigned).registerInvoiceWithEims(INVOICE_ID);
+
+    expect(view.eimsSignedQr).toBeNull();
+  });
+
+  it("notifies the buyer company on a successful registration, without blocking the result", async () => {
+    const db = new FakeDb([invoiceRow({ companyId: "company-1" } as Partial<Invoice>)]);
+    db.companyContact = { phone: "+251911000000", email: "buyer@abc.et" };
+    const directSend = jest.fn().mockResolvedValue(undefined);
+    const postSigned = jest.fn().mockResolvedValue(okResponse());
+
+    const view = await build(db, postSigned, config(), jest.fn(), undefined, undefined, directSend)
+      .registerInvoiceWithEims(INVOICE_ID);
+
+    expect(view.eimsStatus).toBe(EimsInvoiceStatus.Registered);
+    expect(directSend).toHaveBeenCalledWith("sms", "+251911000000", expect.stringContaining(IRN));
+    expect(directSend).toHaveBeenCalledWith("email", "buyer@abc.et", expect.stringContaining(IRN));
+  });
+
+  it("does not fail registration when the buyer notification itself fails", async () => {
+    const db = new FakeDb([invoiceRow({ companyId: "company-1" } as Partial<Invoice>)]);
+    db.companyContact = { phone: "+251911000000", email: null };
+    const directSend = jest.fn().mockRejectedValue(new Error("sms provider down"));
+    const postSigned = jest.fn().mockResolvedValue(okResponse());
+
+    const view = await build(db, postSigned, config(), jest.fn(), undefined, undefined, directSend)
+      .registerInvoiceWithEims(INVOICE_ID);
+
+    expect(view.eimsStatus).toBe(EimsInvoiceStatus.Registered);
+  });
+
   it("sends the exact reserved counter and previous IRN to the mapper", async () => {
     const db = new FakeDb([invoiceRow()], { nextInvoiceCounter: 42, previousIrn: "PRIOR-IRN" });
     const postSigned = jest.fn().mockResolvedValue(okResponse());
@@ -408,7 +464,7 @@ describe("EimsInvoiceRegistrationService.registerInvoiceWithEims", () => {
     expect(postSigned).toHaveBeenCalledTimes(1);
   });
 
-  it("returns the counter after a refusal, but keeps it after an ambiguous result", async () => {
+  it("returns both the counter and the document number after a refusal, keeps both after an ambiguous result", async () => {
     const db = new FakeDb([invoiceRow(), invoiceRow({ id: OTHER_INVOICE_ID })]);
     const postSigned = jest
       .fn()
@@ -421,14 +477,47 @@ describe("EimsInvoiceRegistrationService.registerInvoiceWithEims", () => {
     );
     await service.registerInvoiceWithEims(OTHER_INVOICE_ID);
 
-    // The two numbers move differently, because MoR constrains them differently: the counter must
-    // not skip (it returns), the document number must not repeat (it is burned).
+    // A deterministic rejection rolls both numbers back — MoR's expected-next-value for either
+    // sequence only advances on acceptance (rule 7001 for DocumentNumber, same as InvoiceCounter).
     const first = postSigned.mock.calls[0][1] as EimsInvoiceRequest;
     const second = postSigned.mock.calls[1][1] as EimsInvoiceRequest;
     expect(first.SourceSystem.InvoiceCounter).toBe(7);
     expect(second.SourceSystem.InvoiceCounter).toBe(7);
     expect(first.DocumentDetails.DocumentNumber).toBe("5");
-    expect(second.DocumentDetails.DocumentNumber).toBe("6");
+    expect(second.DocumentDetails.DocumentNumber).toBe("5");
+  });
+
+  it("blocks and alerts with the real IRN when MoR accepts but persisting it locally fails", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const notify = jest.fn().mockResolvedValue(undefined);
+    const postSigned = jest.fn().mockResolvedValue(okResponse());
+
+    // 1st/2nd calls are the reserve() updates; the 3rd is settleSuccess's invoice update — the one
+    // that actually failed live (eims_irn too narrow for the real value MoR returned).
+    let call = 0;
+    const manager = (db as unknown as { manager: { update: jest.Mock } }).manager;
+    const realUpdate = manager.update;
+    manager.update = jest.fn(async (entity: unknown, id: string, patch: Record<string, unknown>) => {
+      call++;
+      if (call === 3) throw new Error("value too long for type character varying(64)");
+      return realUpdate(entity, id, patch);
+    });
+
+    await expect(
+      build(db, postSigned, config(), jest.fn(), undefined, notify).registerInvoiceWithEims(
+        INVOICE_ID,
+      ),
+    ).rejects.toThrow(/value too long/);
+
+    // The IRN is never lost, even though the normal success path never committed.
+    expect(db.state?.blockedReason).toContain(IRN);
+    expect(db.state?.blockedReason).toContain("ACCEPTED");
+    expect(db.invoices.get(INVOICE_ID)?.eimsStatus).toBe(EimsInvoiceStatus.Submitting);
+
+    expect(notify).toHaveBeenCalledTimes(1);
+    const sent = notify.mock.calls[0][0];
+    expect(sent.priority).toBe("HIGH");
+    expect(sent.body).toContain(IRN);
   });
 });
 
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
index 64854bf53..d4928a15b 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
@@ -19,6 +19,9 @@ import {
 } from "../billing/eims-invoice.mapper";
 import { NotificationAudience, NotificationPriority, NotificationType } from "@edr/types";
 import { NotificationInboxService } from "../notification-inbox/notification-inbox.service";
+import { NotificationsService } from "../notifications/notifications.service";
+import { sendCompanyChannels } from "../notifications/notify-company.util";
+import { toEimsInvoiceStatusView } from "./eims-invoice-view.util";
 import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
 import { EimsAuthService } from "./eims-auth.service";
 import { EimsClientService } from "./eims-client.service";
@@ -78,6 +81,7 @@ export class EimsInvoiceRegistrationService {
     private readonly client: EimsClientService,
     private readonly auth: EimsAuthService,
     private readonly inbox: NotificationInboxService,
+    private readonly notifications: NotificationsService,
   ) {}
 
   private get cfg(): EimsConfig {
@@ -115,17 +119,28 @@ export class EimsInvoiceRegistrationService {
 
     let irn: string;
     let ackDate: string | undefined;
+    let signedQR: string | undefined;
     try {
       // Deliberately outside every transaction — no DB lock is held across the wire.
       const result = await this.submit(request);
       irn = result.irn;
       ackDate = result.ackDate;
+      signedQR = result.signedQR;
     } catch (err) {
       await this.settleFailure(invoiceId, reservation, err);
       throw err;
     }
 
-    await this.settleSuccess(invoiceId, reservation, irn, ackDate);
+    try {
+      await this.settleSuccess(invoiceId, reservation, irn, ackDate, signedQR);
+    } catch (err) {
+      // MoR already accepted this document — unlike settleFailure's targets, this is not
+      // ambiguous, it is a *known* IRN we simply failed to persist (confirmed live 2026-08-12: a
+      // column too narrow for a real IRN). Losing it here would be worse than the persistence
+      // bug itself, so it goes straight into the block reason and the alert, not just a log line.
+      await this.blockOnKnownIrnPersistFailure(invoiceId, reservation, irn, ackDate, err);
+      throw err;
+    }
     this.logger.log(
       `Invoice ${invoice.invoiceNumber} registered with EIMS (counter ${reservation.invoiceCounter})`,
     );
@@ -373,13 +388,19 @@ export class EimsInvoiceRegistrationService {
     reservation: Reservation,
     irn: string,
     ackDate?: string,
+    signedQR?: string,
   ): Promise<void> {
+    let companyId: string | undefined;
+    let invoiceNumber = invoiceId;
     await this.dataSource.transaction(async (manager) => {
-      await this.lockInvoice(manager, invoiceId);
+      const invoice = await this.lockInvoice(manager, invoiceId);
+      companyId = invoice.companyId;
+      invoiceNumber = invoice.invoiceNumber;
       await manager.update(Invoice, invoiceId, {
         eimsStatus: EimsInvoiceStatus.Registered,
         eimsIrn: irn,
         eimsAckDate: ackDate ?? null,
+        eimsSignedQr: signedQR ?? null,
         eimsLastError: null,
       });
       await manager.update(EimsSystemState, reservation.stateId, {
@@ -390,20 +411,39 @@ export class EimsInvoiceRegistrationService {
         blockedReason: null,
       });
     });
+
+    // Best-effort, outside the transaction: MoR checklist ADD-N001 wants the buyer notified of a
+    // registration event. Never lets a notification failure mask a filing that already succeeded.
+    if (companyId) {
+      try {
+        await sendCompanyChannels(
+          this.dataSource,
+          this.notifications,
+          companyId,
+          `Invoice ${invoiceNumber} has been registered with MoR EIMS. Reference (IRN): ${irn}`,
+        );
+      } catch (err) {
+        this.logger.warn(`EIMS buyer notification failed for invoice ${invoiceId}: ${(err as Error).message}`);
+      }
+    }
   }
 
   /**
-   * TX2b. A deterministic rejection releases the reservation **and returns the counter**; an
+   * TX2b. A deterministic rejection releases the reservation **and returns both numbers**; an
    * ambiguous result keeps both and blocks the system number, because `PreviousIrn` is now unknown
    * for every later document.
    *
-   * The two numbers move differently, because MoR constrains them differently:
+   * Both `InvoiceCounter` and `DocumentNumber` roll back together on a deterministic rejection —
+   * MoR's own expected-next-value only advances on acceptance, for both fields:
    *
-   *  - `InvoiceCounter` must not **skip** — "Invoice counter is not correct. expected : 1". A
-   *    document MoR definitively refused was never counted there, so ours must not advance either.
-   *  - `DocumentNumber` must not **repeat** — the documented rule is "Document number is not
-   *    unique". It is therefore spent by the attempt itself and never handed back, even for a
-   *    refusal.
+   *  - `InvoiceCounter`: "Invoice counter is not correct. expected : 1".
+   *  - `DocumentNumber`: "Document number error. Document number is not in correct sequence
+   *    expected : 1" (rule 7001) — confirmed live 2026-08-12. An earlier design burned
+   *    `DocumentNumber` forward on every attempt, reasoning from a separate "Document number is
+   *    not unique" rejection; that turned out to describe the same constraint from the other side
+   *    (MoR rejects both reuse *and* skipping ahead of its true next value), and burning forward on
+   *    every rejection permanently drifted past what MoR would ever accept again — confirmed live
+   *    when two rejected self-test attempts deadlocked the sequence until a manual DB reset.
    *
    * An ambiguous result keeps both: MoR may have counted and stored the document.
    */
@@ -434,9 +474,9 @@ export class EimsInvoiceRegistrationService {
         reservation.stateId,
         deterministic
           ? {
-              // Counter returns (MoR never counted a refused document); the document number does
-              // not (MoR requires it to be unique, so it is burned by the attempt).
+              // Both return: MoR never counted a refused document against either sequence.
               nextInvoiceCounter: reservation.invoiceCounter,
+              nextDocumentNumber: Number(reservation.documentNumber),
               inFlightInvoiceId: null,
               inFlightCounter: null,
               inFlightDocumentNumber: null,
@@ -455,6 +495,53 @@ export class EimsInvoiceRegistrationService {
     await this.alertStaff(invoiceId, status, lastError, deterministic);
   }
 
+  /**
+   * MoR accepted the document (a real IRN came back) but recording that locally failed — the
+   * reservation is still held from TX1, so the system-wide block goes on regardless of *why*
+   * `settleSuccess` failed. The IRN and ack date are written straight into `blockedReason` so a
+   * human resolving this never has to dig through logs for the one thing that must not be lost.
+   */
+  private async blockOnKnownIrnPersistFailure(
+    invoiceId: string,
+    reservation: Reservation,
+    irn: string,
+    ackDate: string | undefined,
+    err: unknown,
+  ): Promise<void> {
+    const reason =
+      `Invoice ${invoiceId} was ACCEPTED by EIMS (IRN ${irn}${ackDate ? `, ack ${ackDate}` : ""}) ` +
+      `but recording it locally failed: ${(err as Error)?.message ?? "unknown error"}. Resolve with ` +
+      `POST /invoices/${invoiceId}/eims/resolve using this IRN once the underlying issue is fixed — ` +
+      "do not resubmit, the document already exists at MoR.";
+
+    try {
+      await this.dataSource.manager.update(EimsSystemState, reservation.stateId, { blockedReason: reason });
+    } catch (updateErr) {
+      // Even the block itself failed to write — last resort is the log, since there is nothing
+      // left to retry into.
+      this.logger.error(`Could not record EIMS block for invoice ${invoiceId}: ${reason}`, updateErr as Error);
+      return;
+    }
+
+    this.logger.error(reason);
+    // Not alertStaff(): its canned copy for a non-deterministic result always says "the IRN is
+    // unknown", which is false here — the whole point of this path is that the IRN *is* known.
+    try {
+      await this.inbox.notify({
+        recipients: { permissionKeys: [FREIGHT_PERMS.invoices.eimsResolve] },
+        audience: NotificationAudience.BACKOFFICE,
+        type: NotificationType.GENERIC,
+        priority: NotificationPriority.HIGH,
+        title: "EIMS accepted an invoice but it was not recorded — all further filing is blocked",
+        body: reason,
+        link: `/dashboard/invoices/${invoiceId}`,
+        data: { invoiceId, eimsStatus: EimsInvoiceStatus.Unknown, irn, action: "EIMS_PERSIST_FAILED" },
+      });
+    } catch (notifyErr) {
+      this.logger.warn(`EIMS staff alert failed for invoice ${invoiceId}: ${(notifyErr as Error).message}`);
+    }
+  }
+
   /**
    * Tell the people who can act about a failed filing.
    *
@@ -492,7 +579,9 @@ export class EimsInvoiceRegistrationService {
   // ── internals ────────────────────────────────────────────────────────────────────────────────
 
   /** A non-empty IRN is the only success signal; anything else is a failed registration. */
-  private async submit(request: EimsInvoiceRequest): Promise<{ irn: string; ackDate?: string }> {
+  private async submit(
+    request: EimsInvoiceRequest,
+  ): Promise<{ irn: string; ackDate?: string; signedQR?: string }> {
     const response = await this.client.postSigned<EimsInvoiceRequest, EimsRegisterResponse>(
       "/v1/register",
       request,
@@ -506,7 +595,7 @@ export class EimsInvoiceRegistrationService {
         response?.statusCode,
       );
     }
-    return { irn, ackDate: response.body?.ackDate };
+    return { irn, ackDate: response.body?.ackDate, signedQR: response.body?.signedQR };
   }
 
   private async lockInvoice(manager: EntityManager, invoiceId: string): Promise<Invoice> {
@@ -572,17 +661,6 @@ export class EimsInvoiceRegistrationService {
   }
 
   private toView(invoice: Invoice): EimsInvoiceStatusView {
-    const counter = invoice.eimsInvoiceCounter;
-    return {
-      invoiceId: invoice.id,
-      invoiceNumber: invoice.invoiceNumber,
-      eimsStatus: invoice.eimsStatus ?? EimsInvoiceStatus.NotSubmitted,
-      eimsIrn: invoice.eimsIrn ?? null,
-      eimsDocumentNumber: invoice.eimsDocumentNumber ?? null,
-      eimsInvoiceCounter: counter === null || counter === undefined ? null : Number(counter),
-      eimsSubmittedAt: invoice.eimsSubmittedAt ?? null,
-      eimsAckDate: invoice.eimsAckDate ?? null,
-      eimsLastError: invoice.eimsLastError ?? null,
-    };
+    return toEimsInvoiceStatusView(invoice);
   }
 }
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-view.util.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-view.util.ts
new file mode 100644
index 000000000..f04be0873
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-view.util.ts
@@ -0,0 +1,27 @@
+import { Invoice } from "../billing/entities/invoice.entity";
+import { EimsInvoiceStatus, EimsInvoiceStatusView } from "./eims-registration.types";
+
+/**
+ * `Invoice` → `EimsInvoiceStatusView`, shared by every service that mutates EIMS state on an
+ * invoice (registration, cancellation, receipts) — one place defines what "the current EIMS
+ * status of an invoice" means to a caller.
+ */
+export function toEimsInvoiceStatusView(invoice: Invoice): EimsInvoiceStatusView {
+  const counter = invoice.eimsInvoiceCounter;
+  return {
+    invoiceId: invoice.id,
+    invoiceNumber: invoice.invoiceNumber,
+    eimsStatus: invoice.eimsStatus ?? EimsInvoiceStatus.NotSubmitted,
+    eimsIrn: invoice.eimsIrn ?? null,
+    eimsDocumentNumber: invoice.eimsDocumentNumber ?? null,
+    eimsInvoiceCounter: counter === null || counter === undefined ? null : Number(counter),
+    eimsSubmittedAt: invoice.eimsSubmittedAt ?? null,
+    eimsAckDate: invoice.eimsAckDate ?? null,
+    eimsLastError: invoice.eimsLastError ?? null,
+    eimsSignedQr: invoice.eimsSignedQr ?? null,
+    eimsCancelledAt: invoice.eimsCancelledAt ?? null,
+    eimsCancellationDate: invoice.eimsCancellationDate ?? null,
+    eimsCancellationReasonCode: invoice.eimsCancellationReasonCode ?? null,
+    eimsCancellationRemark: invoice.eimsCancellationRemark ?? null,
+  };
+}
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts
index f47cfe9d9..5db756329 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts
@@ -3,8 +3,13 @@ import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
 
 import { BookingStaff } from "../../common/booking-guards";
 import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
+import { CancelEimsRegistrationDto } from "./dto/cancel-eims-registration.dto";
+import { RegisterSalesReceiptDto } from "./dto/register-sales-receipt.dto";
+import { RegisterWithholdingReceiptDto } from "./dto/register-withholding-receipt.dto";
 import { ResolveEimsRegistrationDto } from "./dto/resolve-eims-registration.dto";
+import { EimsCancellationService } from "./eims-cancellation.service";
 import { EimsInvoiceRegistrationService } from "./eims-invoice-registration.service";
+import { EimsReceiptService } from "./eims-receipt.service";
 
 /**
  * Manual EIMS actions on an existing invoice.
@@ -13,10 +18,12 @@ import { EimsInvoiceRegistrationService } from "./eims-invoice-registration.serv
  * normal production path — they exist for controlled testing and exceptional operations. Automatic
  * submission after an invoice is issued is a separate phase; nothing here is called by it.
  *
- * `eims_register` and `eims_resolve` are intentionally left out of every role preset and assigned
- * to named admins instead. They are also separate permissions: resolving clears the system-wide
- * chain block and can record an IRN against an invoice, which is a supervisor action, not an
- * operational one. Only `eims/status` rides on the ordinary `invoices:view`.
+ * `eims_register`, `eims_resolve`, `eims_cancel` and `eims_receipt_register` are intentionally left
+ * out of every role preset and assigned to named admins instead. They are also separate
+ * permissions: resolving clears the system-wide chain block and can record an IRN against an
+ * invoice, cancelling is its own irreversible-at-MoR action, and filing a receipt is a third —
+ * none follows from the right to register. Only `eims/status` and `eims/receipts` ride on the
+ * ordinary `invoices:view`.
  *
  * Filing gets its own permission (`invoices:eims_register`) rather than riding on an existing key:
  * registration is irreversible at MoR, so it must not follow from the right to download a PDF.
@@ -27,7 +34,11 @@ import { EimsInvoiceRegistrationService } from "./eims-invoice-registration.serv
 @ApiBearerAuth()
 @Controller("invoices")
 export class EimsInvoiceController {
-  constructor(private readonly registration: EimsInvoiceRegistrationService) {}
+  constructor(
+    private readonly registration: EimsInvoiceRegistrationService,
+    private readonly cancellation: EimsCancellationService,
+    private readonly receipts: EimsReceiptService,
+  ) {}
 
   @Post(":id/eims/register")
   @BookingStaff(FREIGHT_PERMS.invoices.eimsRegister)
@@ -65,4 +76,38 @@ export class EimsInvoiceController {
   status(@Param("id", ParseUUIDPipe) id: string) {
     return this.registration.getEimsStatus(id);
   }
+
+  @Post(":id/eims/cancel")
+  @BookingStaff(FREIGHT_PERMS.invoices.eimsCancel)
+  @ApiOperation({
+    summary:
+      "Cancel the invoice's registered EIMS document. Idempotent — an already-cancelled invoice is returned unchanged.",
+  })
+  cancel(@Param("id", ParseUUIDPipe) id: string, @Body() dto: CancelEimsRegistrationDto) {
+    return this.cancellation.cancelInvoiceWithEims(id, dto.reasonCode, dto.remark);
+  }
+
+  @Post(":id/eims/receipt/sales")
+  @BookingStaff(FREIGHT_PERMS.invoices.eimsReceiptRegister)
+  @ApiOperation({ summary: "Register a sales receipt with MoR EIMS against a registered invoice" })
+  registerSalesReceipt(@Param("id", ParseUUIDPipe) id: string, @Body() dto: RegisterSalesReceiptDto) {
+    return this.receipts.registerSalesReceipt(id, dto);
+  }
+
+  @Post(":id/eims/receipt/withholding")
+  @BookingStaff(FREIGHT_PERMS.invoices.eimsReceiptRegister)
+  @ApiOperation({ summary: "Register a withholding receipt with MoR EIMS against a registered invoice" })
+  registerWithholdingReceipt(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: RegisterWithholdingReceiptDto,
+  ) {
+    return this.receipts.registerWithholdingReceipt(id, dto);
+  }
+
+  @Get(":id/eims/receipts")
+  @BookingStaff(FREIGHT_PERMS.invoices.view)
+  @ApiOperation({ summary: "List every EIMS receipt filed against this invoice, newest first" })
+  listReceipts(@Param("id", ParseUUIDPipe) id: string) {
+    return this.receipts.listReceipts(id);
+  }
 }
diff --git a/apps/edr-freight-api/src/modules/eims/eims-receipt.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-receipt.service.spec.ts
new file mode 100644
index 000000000..b9b59cc27
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/eims-receipt.service.spec.ts
@@ -0,0 +1,231 @@
+import { BadRequestException } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { DataSource } from "typeorm";
+
+import { EimsConfig } from "../../config/eims.config";
+import { Invoice } from "../billing/entities/invoice.entity";
+import { NotificationsService } from "../notifications/notifications.service";
+import { EimsAuthService } from "./eims-auth.service";
+import { EimsClientService } from "./eims-client.service";
+import { EimsApiException } from "./eims.errors";
+import { EimsReceiptStatus } from "./entities/eims-receipt.entity";
+import { EimsReceiptService } from "./eims-receipt.service";
+
+const INVOICE_ID = "11111111-1111-4111-8111-111111111111";
+const IRN = "9fe9bbbece6ab76c112b617534e6aac7aa8b819d5be79f4d3d088ed2e887b2e0";
+const SESSION = { systemNumber: "B0360154BA", systemType: "SYS" };
+
+const invoiceRow = (over: Partial<Invoice> = {}): Invoice =>
+  ({
+    id: INVOICE_ID,
+    invoiceNumber: "INV-20260807-00042",
+    companyId: "company-1",
+    currency: "ETB",
+    totalAmount: "10000.00",
+    paidAmount: "10000.00",
+    balanceAmount: "0.00",
+    eimsIrn: IRN,
+    ...over,
+  }) as unknown as Invoice;
+
+/** In-memory stand-in: Invoice lookups + EimsReceipt save/update/find. */
+class FakeDb {
+  invoices = new Map<string, Invoice>();
+  receipts = new Map<string, Record<string, unknown>>();
+  companyContact: { phone: string | null; email: string | null } | null = null;
+  private seq = 0;
+
+  constructor(invoices: Invoice[]) {
+    for (const inv of invoices) this.invoices.set(inv.id, inv);
+  }
+
+  private manager = {
+    findOne: async (entity: unknown, options: { where: { id: string } }) =>
+      entity === Invoice
+        ? (this.invoices.get(options.where.id) ?? null)
+        : (this.receipts.get(options.where.id) ?? null),
+    find: async (_entity: unknown, options: { where: { invoiceId: string } }) =>
+      [...this.receipts.values()].filter((r) => r.invoiceId === options.where.invoiceId),
+    save: async (_entity: unknown, data: Record<string, unknown>) => {
+      const id = `receipt-${++this.seq}`;
+      const row = { id, ...data };
+      this.receipts.set(id, row);
+      return row;
+    },
+    update: async (_entity: unknown, id: string, patch: Record<string, unknown>) => {
+      Object.assign(this.receipts.get(id)!, patch);
+    },
+  };
+
+  asDataSource(): DataSource {
+    return {
+      manager: this.manager,
+      query: async () => (this.companyContact ? [this.companyContact] : []),
+    } as unknown as DataSource;
+  }
+}
+
+const config = (): EimsConfig => ({ tin: "0053481357" }) as EimsConfig;
+
+const build = (
+  db: FakeDb,
+  postBearer: jest.Mock,
+  directSend: jest.Mock = jest.fn().mockResolvedValue(undefined),
+) =>
+  new EimsReceiptService(
+    db.asDataSource(),
+    { get: () => config() } as unknown as ConfigService,
+    { postBearer } as unknown as EimsClientService,
+    { getSessionContext: jest.fn().mockResolvedValue(SESSION) } as unknown as EimsAuthService,
+    { directSend } as unknown as NotificationsService,
+  );
+
+const okResponse = (over: Record<string, unknown> = {}) => ({
+  statusCode: 200,
+  message: "Success",
+  body: { status: "A", rrn: "rrn-value", qr: "iVBORw0KGgo...", ...over },
+});
+
+describe("EimsReceiptService.registerSalesReceipt", () => {
+  it("registers a sales receipt and persists the RRN/QR", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postBearer = jest.fn().mockResolvedValue(okResponse());
+
+    const receipt = await build(db, postBearer).registerSalesReceipt(INVOICE_ID, {
+      modeOfPayment: "CASH",
+    } as never);
+
+    expect(postBearer).toHaveBeenCalledTimes(1);
+    expect(postBearer.mock.calls[0][0]).toBe("/v1/receipt/sales");
+    const request = postBearer.mock.calls[0][1];
+    expect(request.SellerTIN).toBe("0053481357");
+    expect(request.SourceSystemNumber).toBe("B0360154BA");
+    expect(request.Invoices[0].InvoiceIRN).toBe(IRN);
+    expect(request.TransactionDetails.ModeOfPayment).toBe("CASH");
+    expect(receipt.status).toBe(EimsReceiptStatus.Registered);
+    expect(receipt.rrn).toBe("rrn-value");
+    expect(receipt.qr).toBe("iVBORw0KGgo...");
+  });
+
+  it("defaults PaymentCoverage to FULL when the invoice balance is 0, PARTIAL otherwise", async () => {
+    const db = new FakeDb([invoiceRow({ balanceAmount: 500 })]);
+    const postBearer = jest.fn().mockResolvedValue(okResponse());
+
+    await build(db, postBearer).registerSalesReceipt(INVOICE_ID, { modeOfPayment: "CASH" } as never);
+
+    expect(postBearer.mock.calls[0][1].Invoices[0].PaymentCoverage).toBe("PARTIAL");
+  });
+
+  it("rejects an unconfirmed receipt currency locally, with zero HTTP calls", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postBearer = jest.fn();
+
+    await expect(
+      build(db, postBearer).registerSalesReceipt(INVOICE_ID, {
+        modeOfPayment: "CASH",
+        currency: "GBP",
+      } as never),
+    ).rejects.toBeInstanceOf(BadRequestException);
+    expect(postBearer).not.toHaveBeenCalled();
+  });
+
+  it("refuses to file a receipt against an unregistered invoice", async () => {
+    const db = new FakeDb([invoiceRow({ eimsIrn: null })]);
+    const postBearer = jest.fn();
+
+    await expect(
+      build(db, postBearer).registerSalesReceipt(INVOICE_ID, { modeOfPayment: "CASH" } as never),
+    ).rejects.toBeInstanceOf(BadRequestException);
+    expect(postBearer).not.toHaveBeenCalled();
+  });
+
+  it("marks the receipt FAILED on a deterministic rejection and rethrows", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postBearer = jest
+      .fn()
+      .mockRejectedValue(new EimsApiException("RULE_VALIDATION", "EIMS receipt failed (406)", 406));
+
+    await expect(
+      build(db, postBearer).registerSalesReceipt(INVOICE_ID, { modeOfPayment: "CASH" } as never),
+    ).rejects.toBeInstanceOf(EimsApiException);
+    const [receipt] = [...db.receipts.values()];
+    expect(receipt.status).toBe(EimsReceiptStatus.Failed);
+  });
+
+  it("marks the receipt UNKNOWN on an ambiguous failure (never auto-retried)", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postBearer = jest.fn().mockRejectedValue(new EimsApiException("TIMEOUT", "EIMS receipt timed out"));
+
+    await expect(
+      build(db, postBearer).registerSalesReceipt(INVOICE_ID, { modeOfPayment: "CASH" } as never),
+    ).rejects.toBeInstanceOf(EimsApiException);
+    const [receipt] = [...db.receipts.values()];
+    expect(receipt.status).toBe(EimsReceiptStatus.Unknown);
+  });
+
+  it("notifies the buyer company on success, without blocking the result", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    db.companyContact = { phone: "+251911000000", email: "buyer@abc.et" };
+    const directSend = jest.fn().mockResolvedValue(undefined);
+    const postBearer = jest.fn().mockResolvedValue(okResponse());
+
+    const receipt = await build(db, postBearer, directSend).registerSalesReceipt(INVOICE_ID, {
+      modeOfPayment: "CASH",
+    } as never);
+
+    expect(receipt.status).toBe(EimsReceiptStatus.Registered);
+    expect(directSend).toHaveBeenCalledWith("sms", "+251911000000", expect.stringContaining("sales"));
+  });
+});
+
+describe("EimsReceiptService.registerWithholdingReceipt", () => {
+  it("registers a withholding receipt and persists the RRN", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postBearer = jest.fn().mockResolvedValue(okResponse());
+
+    const receipt = await build(db, postBearer).registerWithholdingReceipt(INVOICE_ID, {
+      type: "TWHT",
+      preTaxAmount: 6000,
+      withholdingAmount: 120,
+    } as never);
+
+    expect(postBearer.mock.calls[0][0]).toBe("/v1/receipt/withholding");
+    const request = postBearer.mock.calls[0][1];
+    expect(request.InvoiceDetail.InvoiceIRN).toBe(IRN);
+    expect(request.WithholdDetail).toMatchObject({ Type: "TWHT", PreTaxAmount: 6000, WithholdingAmount: 120 });
+    expect(receipt.status).toBe(EimsReceiptStatus.Registered);
+    expect(receipt.rrn).toBe("rrn-value");
+  });
+
+  it("requires an exchangeRate for a non-ETB invoice", async () => {
+    const db = new FakeDb([invoiceRow({ currency: "USD" })]);
+    const postBearer = jest.fn();
+
+    await expect(
+      build(db, postBearer).registerWithholdingReceipt(INVOICE_ID, {
+        type: "TWHT",
+        preTaxAmount: 6000,
+        withholdingAmount: 120,
+      } as never),
+    ).rejects.toBeInstanceOf(BadRequestException);
+    expect(postBearer).not.toHaveBeenCalled();
+  });
+});
+
+describe("EimsReceiptService.listReceipts", () => {
+  it("returns every receipt filed against the invoice", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postBearer = jest.fn().mockResolvedValue(okResponse());
+    const service = build(db, postBearer);
+
+    await service.registerSalesReceipt(INVOICE_ID, { modeOfPayment: "CASH" } as never);
+    await service.registerWithholdingReceipt(INVOICE_ID, {
+      type: "TWHT",
+      preTaxAmount: 100,
+      withholdingAmount: 2,
+    } as never);
+
+    const list = await service.listReceipts(INVOICE_ID);
+    expect(list).toHaveLength(2);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/eims/eims-receipt.service.ts b/apps/edr-freight-api/src/modules/eims/eims-receipt.service.ts
new file mode 100644
index 000000000..96876f4d6
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/eims-receipt.service.ts
@@ -0,0 +1,259 @@
+import { BadRequestException, Injectable, Logger, NotFoundException } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { InjectDataSource } from "@nestjs/typeorm";
+import { DataSource } from "typeorm";
+import type { QueryDeepPartialEntity } from "typeorm/query-builder/QueryPartialEntity.js";
+
+import { EimsConfig } from "../../config/eims.config";
+import { Invoice } from "../billing/entities/invoice.entity";
+import { NotificationsService } from "../notifications/notifications.service";
+import { sendCompanyChannels } from "../notifications/notify-company.util";
+import { EimsAuthService } from "./eims-auth.service";
+import { EimsClientService } from "./eims-client.service";
+import { EimsApiException } from "./eims.errors";
+import { EimsReceipt, EimsReceiptKind, EimsReceiptStatus } from "./entities/eims-receipt.entity";
+import { RegisterSalesReceiptDto } from "./dto/register-sales-receipt.dto";
+import { RegisterWithholdingReceiptDto } from "./dto/register-withholding-receipt.dto";
+import {
+  EimsReceiptResponse,
+  EimsSalesReceiptRequest,
+  EimsWithholdReceiptRequest,
+} from "./eims-receipt.types";
+import { EimsInvoiceError } from "./eims-registration.types";
+
+/** `ReceiptCurrency` / withholding `InvoiceDetail.Currency` — confirmed by a live rule error. */
+const EIMS_RECEIPT_CURRENCIES = ["ETB", "USD", "CAD"] as const;
+
+/** Failure kinds where MoR gave a complete answer — the receipt definitively did not register. */
+const DETERMINISTIC_KINDS = new Set(["SCHEMA_VALIDATION", "RULE_VALIDATION", "AUTH", "FORBIDDEN"]);
+
+/**
+ * `POST /v1/receipt/sales` and `POST /v1/receipt/withholding`, both against an already-registered
+ * invoice.
+ *
+ * No counter/reservation machinery: the collection shows no MoR-enforced ordering on
+ * `ReceiptCounter` the way `InvoiceCounter` has a documented "expected: N" rule, so — unlike
+ * registration — there is no shared sequence to protect. Each attempt is its own `EimsReceipt` row:
+ * created before the HTTP call (so a crash mid-flight leaves an UNKNOWN row instead of nothing),
+ * settled after it. An ambiguous outcome is never auto-retried — receipts have no evidenced
+ * double-submission guard the way `/v1/cancel` does ("IRN already Canceled."), so the same caution
+ * applies as an unacknowledged registration: a human must check the MoR portal first.
+ *
+ * Several request fields have no confirmed source in this codebase (payment method, collector,
+ * withholding rate/amount) and are never guessed — see the two DTOs.
+ */
+@Injectable()
+export class EimsReceiptService {
+  private readonly logger = new Logger(EimsReceiptService.name);
+
+  constructor(
+    @InjectDataSource() private readonly dataSource: DataSource,
+    private readonly config: ConfigService,
+    private readonly client: EimsClientService,
+    private readonly auth: EimsAuthService,
+    private readonly notifications: NotificationsService,
+  ) {}
+
+  private get cfg(): EimsConfig {
+    return this.config.get<EimsConfig>("eims")!;
+  }
+
+  async registerSalesReceipt(invoiceId: string, dto: RegisterSalesReceiptDto): Promise<EimsReceipt> {
+    const invoice = await this.loadRegisteredInvoice(invoiceId);
+    const currency = dto.currency ?? invoice.currency;
+    this.assertReceiptCurrency(currency);
+
+    const session = await this.auth.getSessionContext();
+    const receiptNumber = this.generateReceiptNumber(invoice);
+    const collectedAmount = dto.collectedAmount ?? Number(invoice.paidAmount);
+    const balance = Number(invoice.balanceAmount);
+
+    const request: EimsSalesReceiptRequest = {
+      ReceiptNumber: receiptNumber,
+      ReceiptType: "Sales Receipts",
+      Reason: dto.reason ?? "Payment received",
+      // ISO-8601 UTC — the collection's saved example uses a "+03:00" offset instead; no schema
+      // error for this field was ever observed to confirm which form MoR actually requires.
+      ReceiptDate: new Date().toISOString(),
+      ReceiptCounter: String(Date.now()),
+      ManualReceiptNumber: receiptNumber,
+      SourceSystemType: session.systemType,
+      SourceSystemNumber: session.systemNumber,
+      ReceiptCurrency: currency,
+      ExchangeRate: dto.exchangeRate ?? null,
+      CollectedAmount: collectedAmount,
+      SellerTIN: this.cfg.tin,
+      Invoices: [
+        {
+          InvoiceIRN: invoice.eimsIrn!,
+          PaymentCoverage: dto.paymentCoverage ?? (balance <= 0 ? "FULL" : "PARTIAL"),
+          InvoicePaidAmount: collectedAmount,
+          DiscountAmount: null,
+          RemainingAmount: balance,
+          TotalAmount: Number(invoice.totalAmount),
+        },
+      ],
+      TransactionDetails: {
+        ModeOfPayment: dto.modeOfPayment,
+        ChequeNumber: dto.chequeNumber ?? null,
+        CPONumber: dto.cpoNumber ?? null,
+        DocumentNumber: dto.documentNumber ?? null,
+        CollectorName: dto.collectorName ?? null,
+        PaymentServiceProvider: dto.paymentServiceProvider ?? null,
+        OtherPaymentServiceProviderName: dto.otherPaymentServiceProviderName ?? null,
+        AccountNumber: dto.accountNumber ?? null,
+        TransactionNumber: dto.transactionNumber ?? null,
+      },
+    };
+
+    return this.submit(invoice, "SALES", receiptNumber, request, "/v1/receipt/sales");
+  }
+
+  async registerWithholdingReceipt(
+    invoiceId: string,
+    dto: RegisterWithholdingReceiptDto,
+  ): Promise<EimsReceipt> {
+    const invoice = await this.loadRegisteredInvoice(invoiceId);
+    if (invoice.currency !== "ETB" && dto.exchangeRate == null) {
+      throw new BadRequestException({
+        code: "EIMS_EXCHANGE_RATE_REQUIRED",
+        message: `Invoice ${invoice.invoiceNumber} is in ${invoice.currency} and needs an exchangeRate`,
+      });
+    }
+
+    const session = await this.auth.getSessionContext();
+    const receiptNumber = this.generateReceiptNumber(invoice);
+
+    const request: EimsWithholdReceiptRequest = {
+      ReceiptNumber: receiptNumber,
+      Reason: dto.reason ?? "Withholding",
+      ReceiptCounter: String(Date.now()),
+      ManualReceiptNumber: receiptNumber,
+      SourceSystemType: session.systemType,
+      SourceSystemNumber: session.systemNumber,
+      InvoiceDetail: {
+        InvoiceIRN: invoice.eimsIrn!,
+        Currency: invoice.currency,
+        ExchangeRate: dto.exchangeRate ?? null,
+      },
+      WithholdDetail: {
+        Type: dto.type,
+        Rate: dto.rate ?? null,
+        PreTaxAmount: dto.preTaxAmount,
+        WithholdingAmount: dto.withholdingAmount,
+      },
+    };
+
+    return this.submit(invoice, "WITHHOLDING", receiptNumber, request, "/v1/receipt/withholding");
+  }
+
+  async listReceipts(invoiceId: string): Promise<EimsReceipt[]> {
+    return this.dataSource.manager.find(EimsReceipt, {
+      where: { invoiceId },
+      order: { createdAt: "DESC" },
+    });
+  }
+
+  // ── internals ────────────────────────────────────────────────────────────────────────────────
+
+  private async submit(
+    invoice: Invoice,
+    kind: EimsReceiptKind,
+    receiptNumber: string,
+    request: EimsSalesReceiptRequest | EimsWithholdReceiptRequest,
+    path: "/v1/receipt/sales" | "/v1/receipt/withholding",
+  ): Promise<EimsReceipt> {
+    // Committed before the HTTP call — a crash mid-flight leaves an UNKNOWN row, not nothing.
+    const receipt = await this.dataSource.manager.save(EimsReceipt, {
+      invoiceId: invoice.id,
+      kind,
+      status: EimsReceiptStatus.Submitting,
+      receiptNumber,
+      submittedAt: new Date(),
+      request: request as unknown as Record<string, unknown>,
+    });
+
+    try {
+      const response = await this.client.postBearer<
+        EimsSalesReceiptRequest | EimsWithholdReceiptRequest,
+        EimsReceiptResponse
+      >(path, request);
+      const rrn = response?.body?.rrn;
+      if (!rrn) {
+        throw new EimsApiException(
+          "SCHEMA_VALIDATION",
+          "EIMS receipt registration returned no rrn",
+          response?.statusCode,
+        );
+      }
+      await this.dataSource.manager.update(EimsReceipt, receipt.id, {
+        status: EimsReceiptStatus.Registered,
+        rrn,
+        qr: response.body?.qr ?? null,
+        ackStatus: response.body?.status ?? null,
+      });
+      this.logger.log(`${kind} receipt ${receiptNumber} registered for invoice ${invoice.invoiceNumber} (RRN ${rrn})`);
+      await this.notifyBuyer(invoice, kind, receiptNumber);
+    } catch (err) {
+      const api = err instanceof EimsApiException ? err : null;
+      const deterministic = api ? DETERMINISTIC_KINDS.has(api.kind) : false;
+      const lastError: EimsInvoiceError = {
+        kind: api?.kind ?? "UNKNOWN",
+        message: (err as Error)?.message ?? "unknown error",
+        httpStatus: api?.httpStatus,
+        details: api?.details,
+        at: new Date().toISOString(),
+      };
+      await this.dataSource.manager.update(EimsReceipt, receipt.id, {
+        status: deterministic ? EimsReceiptStatus.Failed : EimsReceiptStatus.Unknown,
+        lastError,
+      } as QueryDeepPartialEntity<EimsReceipt>);
+      this.logger.error(
+        `${kind} receipt ${receiptNumber} for invoice ${invoice.invoiceNumber} ${deterministic ? "FAILED" : "UNKNOWN"}: ${lastError.message}`,
+      );
+      throw err;
+    }
+
+    const saved = await this.dataSource.manager.findOne(EimsReceipt, { where: { id: receipt.id } });
+    return saved!;
+  }
+
+  private async notifyBuyer(invoice: Invoice, kind: EimsReceiptKind, receiptNumber: string): Promise<void> {
+    try {
+      await sendCompanyChannels(
+        this.dataSource,
+        this.notifications,
+        invoice.companyId,
+        `A ${kind === "SALES" ? "sales" : "withholding"} receipt (${receiptNumber}) has been registered ` +
+          `with MoR EIMS for invoice ${invoice.invoiceNumber}.`,
+      );
+    } catch (err) {
+      this.logger.warn(`EIMS receipt buyer notification failed for invoice ${invoice.id}: ${(err as Error).message}`);
+    }
+  }
+
+  private async loadRegisteredInvoice(invoiceId: string): Promise<Invoice> {
+    const invoice = await this.dataSource.manager.findOne(Invoice, { where: { id: invoiceId } });
+    if (!invoice) throw new NotFoundException(`Invoice ${invoiceId} not found`);
+    if (!invoice.eimsIrn) {
+      throw new BadRequestException({
+        code: "EIMS_NOT_REGISTERED",
+        message: `Invoice ${invoice.invoiceNumber} was never registered with EIMS — no IRN to file a receipt against.`,
+      });
+    }
+    return invoice;
+  }
+
+  private assertReceiptCurrency(currency: string): void {
+    if (!EIMS_RECEIPT_CURRENCIES.includes(currency as (typeof EIMS_RECEIPT_CURRENCIES)[number])) {
+      throw new BadRequestException({
+        code: "EIMS_RECEIPT_CURRENCY_INVALID",
+        message: `EIMS receipt currency must be one of ${EIMS_RECEIPT_CURRENCIES.join(", ")}, got "${currency}"`,
+      });
+    }
+  }
+
+  private generateReceiptNumber(invoice: Invoice): string {
+    return `REC-${invoice.invoiceNumber}-${Date.now()}`;
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/eims/eims-receipt.types.ts b/apps/edr-freight-api/src/modules/eims/eims-receipt.types.ts
new file mode 100644
index 000000000..f49600259
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/eims-receipt.types.ts
@@ -0,0 +1,97 @@
+/**
+ * Wire types for `POST /v1/receipt/sales` and `POST /v1/receipt/withholding`, taken verbatim from
+ * the Postman collection's saved requests/responses. Bearer-authenticated but unsigned — no
+ * `{request,signature,certificate}` envelope in the collection's saved bodies, same as `/v1/verify`
+ * and `/v1/cancel`.
+ */
+
+/** One entry of `Invoices[]` on a sales receipt. */
+export interface EimsSalesReceiptInvoice {
+  InvoiceIRN: string;
+  PaymentCoverage: string;
+  InvoicePaidAmount: number;
+  DiscountAmount: number | null;
+  RemainingAmount: number | null;
+  TotalAmount: number;
+}
+
+/**
+ * `ModeOfPayment` enum confirmed by a live schema error: exactly these eight values, verbatim
+ * spelling and casing (including the two multi-word ones).
+ */
+export const EIMS_MODE_OF_PAYMENT = [
+  "CASH",
+  "CHEQUE",
+  "CPO",
+  "Local Bank Transfer",
+  "SWIFT",
+  "Wire Transfer",
+  "Letter of Credit",
+  "Card",
+] as const;
+export type EimsModeOfPayment = (typeof EIMS_MODE_OF_PAYMENT)[number];
+
+export interface EimsSalesReceiptTransactionDetails {
+  ModeOfPayment: EimsModeOfPayment;
+  ChequeNumber: string | null;
+  CPONumber: string | null;
+  DocumentNumber: string | null;
+  CollectorName: string | null;
+  PaymentServiceProvider: string | null;
+  OtherPaymentServiceProviderName: string | null;
+  AccountNumber: string | null;
+  TransactionNumber: string | null;
+}
+
+export interface EimsSalesReceiptRequest {
+  ReceiptNumber: string;
+  ReceiptType: string;
+  Reason: string;
+  ReceiptDate: string;
+  ReceiptCounter: string;
+  ManualReceiptNumber: string;
+  SourceSystemType: string;
+  SourceSystemNumber: string;
+  /** Confirmed enum via a live rule error: "Currency should be ETB, USD, CAD". */
+  ReceiptCurrency: string;
+  ExchangeRate: number | null;
+  CollectedAmount: number;
+  SellerTIN: string;
+  Invoices: EimsSalesReceiptInvoice[];
+  TransactionDetails: EimsSalesReceiptTransactionDetails;
+}
+
+export interface EimsWithholdReceiptRequest {
+  ReceiptNumber: string;
+  Reason: string;
+  ReceiptCounter: string;
+  ManualReceiptNumber: string;
+  SourceSystemType: string;
+  SourceSystemNumber: string;
+  InvoiceDetail: {
+    InvoiceIRN: string;
+    Currency: string;
+    ExchangeRate: number | null;
+  };
+  WithholdDetail: {
+    /** Only "TWHT" has ever been observed; not restricted to it, since no fuller enum is confirmed. */
+    Type: string;
+    Rate: number | null;
+    PreTaxAmount: number;
+    WithholdingAmount: number;
+  };
+}
+
+/** Success body — identical shape for both receipt endpoints. */
+export interface EimsReceiptResponseBody {
+  status: string;
+  rrn: string;
+  /** Base64 PNG, same convention as the register response's `signedQR`. */
+  qr: string;
+}
+
+export interface EimsReceiptResponse {
+  statusCode?: number;
+  message?: string;
+  body?: EimsReceiptResponseBody;
+}
diff --git a/apps/edr-freight-api/src/modules/eims/eims-registration.types.ts b/apps/edr-freight-api/src/modules/eims/eims-registration.types.ts
index c4d9f3842..8094d0e74 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-registration.types.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-registration.types.ts
@@ -13,6 +13,8 @@ export enum EimsInvoiceStatus {
   Registered = "REGISTERED",
   Failed = "FAILED",
   Unknown = "UNKNOWN",
+  /** Successfully cancelled at MoR via `POST /v1/cancel`. Terminal — never re-registered. */
+  Cancelled = "CANCELLED",
 }
 
 /** `body` of a successful `POST /v1/register`, as observed in the collection. */
@@ -65,6 +67,28 @@ export interface EimsVerifyResponse {
   body?: EimsVerifyResponseBody;
 }
 
+/**
+ * `POST /v1/cancel` — bearer-authenticated but unsigned, same shape as `/v1/verify` (no
+ * `{request,signature,certificate}` envelope in the collection's saved request).
+ */
+export interface EimsCancelRequest {
+  Irn: string;
+  /** Numeric code as a string, e.g. "1" (Duplicate), "6" (Calculation Error) per the collection docs. */
+  ReasonCode: string;
+  Remark: string;
+}
+
+/** Success body: `{ cancellationDate: "Sun Dec 22 21:55:03 EAT 2024" }` — a Java Date#toString(), not ISO. Stored verbatim, like `eimsAckDate`. */
+export interface EimsCancelResponseBody {
+  cancellationDate: string;
+}
+
+export interface EimsCancelResponse {
+  statusCode?: number;
+  message?: string;
+  body?: EimsCancelResponseBody;
+}
+
 /** Persisted failure detail. Carries the gateway's own error fields only — never our envelope. */
 export interface EimsInvoiceError {
   kind: string;
@@ -86,4 +110,10 @@ export interface EimsInvoiceStatusView {
   eimsSubmittedAt: Date | null;
   eimsAckDate: string | null;
   eimsLastError: EimsInvoiceError | null;
+  /** Raw base64 PNG from MoR, already rendered on their side — see `Invoice.eimsSignedQr`. */
+  eimsSignedQr: string | null;
+  eimsCancelledAt: Date | null;
+  eimsCancellationDate: string | null;
+  eimsCancellationReasonCode: string | null;
+  eimsCancellationRemark: string | null;
 }
diff --git a/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts b/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts
index edd079b51..93df29da2 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts
@@ -35,8 +35,14 @@ export const eimsInvoiceConfig = (over: Partial<EimsInvoiceConfig> = {}): EimsIn
   buyerCountryCode: null,
   buyerRegionCodes: { "Addis Ababa": "13" },
   buyerWeredaCodes: { Yeka: "99" }, // test-only, not a real MoR code
+  taxCodeByChargeType: {},
+  taxRateByChargeType: {},
+  exciseByChargeType: {},
+  discountByChargeType: {},
   cashierName: null,
   salesPersonName: null,
+  buyerIdType: null,
+  buyerIdNumber: null,
   ...over,
 });
 
diff --git a/apps/edr-freight-api/src/modules/eims/eims.module.ts b/apps/edr-freight-api/src/modules/eims/eims.module.ts
index 53d3d4090..7aa59b3ef 100644
--- a/apps/edr-freight-api/src/modules/eims/eims.module.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims.module.ts
@@ -4,13 +4,17 @@ import { TypeOrmModule } from "@nestjs/typeorm";
 
 import { Invoice } from "../billing/entities/invoice.entity";
 import { NotificationInboxModule } from "../notification-inbox/notification-inbox.module";
+import { NotificationsModule } from "../notifications/notifications.module";
 import { EimsAuthService } from "./eims-auth.service";
 import { EimsAutoSubmitService } from "./eims-auto-submit.service";
+import { EimsCancellationService } from "./eims-cancellation.service";
 import { EimsClientService } from "./eims-client.service";
 import { EimsCredentialsProvider } from "./eims-credentials.provider";
 import { EimsInvoiceController } from "./eims-invoice.controller";
 import { EimsInvoiceRegistrationService } from "./eims-invoice-registration.service";
+import { EimsReceiptService } from "./eims-receipt.service";
 import { EimsSignerService } from "./eims-signer.service";
+import { EimsReceipt } from "./entities/eims-receipt.entity";
 import { EimsSystemState } from "./entities/eims-system-state.entity";
 
 /**
@@ -22,8 +26,9 @@ import { EimsSystemState } from "./entities/eims-system-state.entity";
 @Module({
   imports: [
     HttpModule.register({ timeout: Number(process.env.EIMS_HTTP_TIMEOUT_MS) || 30_000 }),
-    TypeOrmModule.forFeature([EimsSystemState, Invoice]),
+    TypeOrmModule.forFeature([EimsSystemState, Invoice, EimsReceipt]),
     NotificationInboxModule,
+    NotificationsModule,
   ],
   controllers: [EimsInvoiceController],
   providers: [
@@ -33,7 +38,15 @@ import { EimsSystemState } from "./entities/eims-system-state.entity";
     EimsClientService,
     EimsInvoiceRegistrationService,
     EimsAutoSubmitService,
+    EimsCancellationService,
+    EimsReceiptService,
+  ],
+  exports: [
+    EimsAuthService,
+    EimsClientService,
+    EimsInvoiceRegistrationService,
+    EimsCancellationService,
+    EimsReceiptService,
   ],
-  exports: [EimsAuthService, EimsClientService, EimsInvoiceRegistrationService],
 })
 export class EimsModule {}
diff --git a/apps/edr-freight-api/src/modules/eims/entities/eims-receipt.entity.ts b/apps/edr-freight-api/src/modules/eims/entities/eims-receipt.entity.ts
new file mode 100644
index 000000000..a785a42c2
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/entities/eims-receipt.entity.ts
@@ -0,0 +1,68 @@
+import { BaseEntity } from "@edr/api-common";
+import { Column, Entity, Index, JoinColumn, ManyToOne } from "typeorm";
+
+import { Invoice } from "../../billing/entities/invoice.entity";
+import { EimsInvoiceError } from "../eims-registration.types";
+
+export type EimsReceiptKind = "SALES" | "WITHHOLDING";
+
+/** Same shape as `EimsInvoiceStatus`, for a receipt instead of an invoice. */
+export enum EimsReceiptStatus {
+  NotSubmitted = "NOT_SUBMITTED",
+  Submitting = "SUBMITTING",
+  Registered = "REGISTERED",
+  Failed = "FAILED",
+  Unknown = "UNKNOWN",
+}
+
+/**
+ * One `POST /v1/receipt/sales` or `POST /v1/receipt/withholding` attempt, linked to the invoice it
+ * was filed against. An invoice can have more than one receipt (partial payments), so this is its
+ * own table rather than columns on `Invoice`.
+ *
+ * No counter/sequence reservation the way invoice registration has: the collection's `/v1/receipt/*`
+ * examples show no MoR-enforced ordering rule on `ReceiptCounter` (unlike `InvoiceCounter`'s
+ * documented "expected: N"), so this is a plain row per attempt.
+ */
+@Entity({ schema: "freight", name: "eims_receipts" })
+@Index(["invoiceId"])
+export class EimsReceipt extends BaseEntity {
+  @Column({ name: "invoice_id", type: "uuid" })
+  invoiceId!: string;
+
+  @ManyToOne(() => Invoice)
+  @JoinColumn({ name: "invoice_id" })
+  invoice?: Invoice;
+
+  @Column({ name: "kind", type: "varchar", length: 16 })
+  kind!: EimsReceiptKind;
+
+  @Column({ name: "status", type: "varchar", length: 20, default: "NOT_SUBMITTED" })
+  status!: EimsReceiptStatus;
+
+  /** Our own generated `ReceiptNumber` / `ManualReceiptNumber` (both sent equal — see the service). */
+  @Column({ name: "receipt_number", type: "varchar", length: 64 })
+  receiptNumber!: string;
+
+  /** MoR's Receipt Reference Number, returned only on success. */
+  @Column({ name: "rrn", type: "text", nullable: true })
+  rrn?: string | null;
+
+  /** Base64 PNG from MoR, same convention as `Invoice.eimsSignedQr` — embed directly. */
+  @Column({ name: "qr", type: "text", nullable: true })
+  qr?: string | null;
+
+  /** MoR's own `"A"` (active) / `"F"` (failed) status marker, stored verbatim. */
+  @Column({ name: "ack_status", type: "varchar", length: 8, nullable: true })
+  ackStatus?: string | null;
+
+  @Column({ name: "submitted_at", type: "timestamptz", nullable: true })
+  submittedAt?: Date | null;
+
+  @Column({ name: "last_error", type: "jsonb", nullable: true })
+  lastError?: EimsInvoiceError | null;
+
+  /** The exact request body sent — receipts are bearer-only/unsigned, so nothing secret is in it. */
+  @Column({ name: "request", type: "jsonb", nullable: true })
+  request?: Record<string, unknown> | null;
+}
diff --git a/apps/edr-freight-api/src/modules/eims/entities/eims-system-state.entity.ts b/apps/edr-freight-api/src/modules/eims/entities/eims-system-state.entity.ts
index a21057042..328aa8d0f 100644
--- a/apps/edr-freight-api/src/modules/eims/entities/eims-system-state.entity.ts
+++ b/apps/edr-freight-api/src/modules/eims/entities/eims-system-state.entity.ts
@@ -30,8 +30,11 @@ export class EimsSystemState extends BaseEntity {
   @Column({ name: "in_flight_document_number", type: "bigint", nullable: true })
   inFlightDocumentNumber?: number | null;
 
-  /** IRN of the last successful registration; null until the first one succeeds. */
-  @Column({ name: "previous_irn", type: "varchar", length: 64, nullable: true })
+  /**
+   * IRN of the last successful registration; null until the first one succeeds. `text`, not a
+   * fixed varchar — same reasoning as `Invoice.eimsIrn`: a real IRN already overflowed varchar(64).
+   */
+  @Column({ name: "previous_irn", type: "text", nullable: true })
   previousIrn?: string | null;
 
   /**
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index cdc43c5b2..fc9395ffb 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -129,6 +129,7 @@ import {
   perEdgeConsistUsage,
   validateContainerPlacements,
   validateMixedTrainLimitsPerEdge,
+  MAX_TEU_SLOTS_PER_WAGON,
   type ContainerPlacementInput,
   type WagonPlanSlot,
 } from '../utils/wagon-plan.util';
@@ -2930,6 +2931,10 @@ export class TrainSchedulingService {
     // dispatch pre-check keeps reporting these bookings as unloaded).
     const wagonAssignedIds = await this.getWagonAssignedBookingIds(scheduleId);
     if (wagonAssignedIds.size) {
+      // Re-check the 1×40ft/2×20ft-per-wagon packing rule right before loading
+      // is confirmed — allocation time already enforces it, but a wagon swap or
+      // an edited allocation since then could have broken it unnoticed.
+      await this.assertWagonContainerCapacity(scheduleId);
       // Export cargo must be received at the warehouse with a GRN before it can
       // be confirmed loaded — an allocation is not proof the goods are in hand.
       if (this.isExportSchedule(schedule)) {
@@ -3397,6 +3402,72 @@ export class TrainSchedulingService {
     }
   }
 
+  /**
+   * Re-check the 1×40ft / 2×20ft-per-wagon packing rule at loading confirmation
+   * time. `validateContainerPlacements` already enforces this the moment a
+   * booking is allocated to a wagon, but nothing re-checks it afterwards — a
+   * wagon swap, an edited allocation, or a container item added out-of-band
+   * between allocation and loading could still leave a wagon over its 2-TEU
+   * capacity undetected until the train is already loaded. This closes that gap
+   * by summing the TEU actually persisted per wagon (40ft = 2 TEU, 20ft = 1 TEU,
+   * same size resolution as the marshalling document) right before loading is
+   * confirmed.
+   */
+  private async assertWagonContainerCapacity(scheduleId: string): Promise<void> {
+    const rows: Array<{ sequenceNo: number; wagonNumber: string | null; teuUsed: string }> =
+      await this.dataSource.query(
+        `SELECT tsw.sequence_no AS "sequenceNo",
+                pw.wagon_number AS "wagonNumber",
+                SUM(
+                  CASE COALESCE(ct.size_ft, bct.size_ft)
+                    WHEN 40 THEN 2
+                    WHEN 20 THEN 1
+                    ELSE
+                      CASE
+                        WHEN bc.container_size ILIKE '%40%' THEN 2
+                        WHEN bc.container_size ILIKE '%20%' THEN 1
+                        ELSE 0
+                      END
+                  END
+                ) AS "teuUsed"
+           FROM freight.train_set_wagons tsw
+           JOIN freight.wagon_booking_allocations wba
+             ON wba.train_set_wagon_id = tsw.id AND wba.deleted_at IS NULL
+           JOIN freight.wagon_allocation_container_items wci
+             ON wci.wagon_booking_allocation_id = wba.id AND wci.deleted_at IS NULL
+           LEFT JOIN freight.container_types ct ON ct.id = wci.container_type_id
+           LEFT JOIN freight.booking_container bc ON bc.id = wci.booking_container_id
+           LEFT JOIN freight.container_types bct ON bct.id = bc.container_type_id
+           LEFT JOIN freight.wagons pw ON pw.id = tsw.physical_wagon_id
+          WHERE tsw.train_set_id = (
+                  SELECT train_set_id FROM freight.train_schedules WHERE id = $1
+                )
+            AND tsw.deleted_at IS NULL
+          GROUP BY tsw.id, tsw.sequence_no, pw.wagon_number
+         HAVING SUM(
+                  CASE COALESCE(ct.size_ft, bct.size_ft)
+                    WHEN 40 THEN 2
+                    WHEN 20 THEN 1
+                    ELSE
+                      CASE
+                        WHEN bc.container_size ILIKE '%40%' THEN 2
+                        WHEN bc.container_size ILIKE '%20%' THEN 1
+                        ELSE 0
+                      END
+                  END
+                ) > $2`,
+        [scheduleId, MAX_TEU_SLOTS_PER_WAGON],
+      );
+    if (rows.length) {
+      const labels = rows
+        .map((r) => `wagon #${r.sequenceNo}${r.wagonNumber ? ` (${r.wagonNumber})` : ''}`)
+        .join(', ');
+      throw new BadRequestException(
+        `These wagons exceed capacity (max 1×40ft or 2×20ft per wagon) — fix the container placement before confirming loading: ${labels}.`,
+      );
+    }
+  }
+
   private buildImportLoadListHtml(loadList: Awaited<ReturnType<TrainSchedulingService['generateImportLoadList']>>): string {
     const esc = (value: unknown) =>
       String(value ?? '-')
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index f0b719d63..cdbffd961 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -482,6 +482,20 @@ export const FINANCE_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:invoices:eims_resolve",
     "Resolve a blocked MoR EIMS submission",
   ),
+  // Cancellation is a separate irreversible-at-MoR action from registration — its own grant,
+  // same reasoning as eims_register.
+  perm(
+    "d2b00001-0001-4000-8000-000000000008",
+    "edr_freight_app:invoices:eims_cancel",
+    "Cancel a registered invoice with MoR EIMS",
+  ),
+  // Covers both sales and withholding receipts — same risk profile (filing a document with
+  // MoR), no reason to split further.
+  perm(
+    "d2b00001-0001-4000-8000-000000000009",
+    "edr_freight_app:invoices:eims_receipt_register",
+    "Register a sales or withholding receipt with MoR EIMS",
+  ),
   // USD bookings are paid by bank transfer; Finance uploads the slip and settles
   // the invoice. Moves money state, so it is its own grant, not part of view.
   perm(
@@ -1707,6 +1721,8 @@ export const FREIGHT_PERMS = {
     export: "edr_freight_app:invoices:export",
     eimsRegister: "edr_freight_app:invoices:eims_register",
     eimsResolve: "edr_freight_app:invoices:eims_resolve",
+    eimsCancel: "edr_freight_app:invoices:eims_cancel",
+    eimsReceiptRegister: "edr_freight_app:invoices:eims_receipt_register",
     confirmOffline: "edr_freight_app:invoices:confirm_offline",
   },
   firstMile: {
@@ -2225,10 +2241,10 @@ export const ROLE_PERMISSION_PRESETS = {
     FREIGHT_PERMS.bookings.view,
     FREIGHT_PERMS.invoices.view,
     FREIGHT_PERMS.invoices.export,
-    // Deliberately NOT granted here: invoices:eims_register and invoices:eims_resolve.
-    // Invoices are filed with MoR by the workflow, not by a person, so filing is not a
-    // Finance job function — the endpoints exist for controlled testing and exceptional
-    // operations, and are assigned to named admins rather than a role preset.
+    // Deliberately NOT granted here: invoices:eims_register, eims_resolve, eims_cancel,
+    // eims_receipt_register. Invoices are filed with MoR by the workflow, not by a person, so
+    // filing is not a Finance job function — the endpoints exist for controlled testing and
+    // exceptional operations, and are assigned to named admins rather than a role preset.
     FREIGHT_PERMS.payments.view,
     FREIGHT_PERMS.bookings.wagonCancellationView,
   ],
diff --git a/apps/edr-freight-web/backoffice/src/types/eims.ts b/apps/edr-freight-web/backoffice/src/types/eims.ts
index 5b5a3e93d..c7c2e088f 100644
--- a/apps/edr-freight-web/backoffice/src/types/eims.ts
+++ b/apps/edr-freight-web/backoffice/src/types/eims.ts
@@ -9,7 +9,8 @@ export type EimsInvoiceStatus =
   | "SUBMITTING"
   | "REGISTERED"
   | "FAILED"
-  | "UNKNOWN";
+  | "UNKNOWN"
+  | "CANCELLED";
 
 /** Sanitized gateway failure: MoR's own error fields, never our signed envelope. */
 export interface EimsInvoiceError {
@@ -30,6 +31,28 @@ export interface EimsInvoiceStatusView {
   /** MoR returns a Java ZonedDateTime string, stored verbatim — display as-is. */
   eimsAckDate: string | null;
   eimsLastError: EimsInvoiceError | null;
+  /** Base64 PNG from MoR, already rendered on their side — embed as `data:image/png;base64,...`. */
+  eimsSignedQr: string | null;
+  eimsCancelledAt: string | null;
+  /** MoR's own confirmation string (a Java `Date#toString()`), stored verbatim — display as-is. */
+  eimsCancellationDate: string | null;
+  eimsCancellationReasonCode: string | null;
+  eimsCancellationRemark: string | null;
+}
+
+/** One `EimsReceipt` row — mirrors `entities/eims-receipt.entity.ts`. */
+export interface EimsReceiptView {
+  id: string;
+  invoiceId: string;
+  kind: "SALES" | "WITHHOLDING";
+  status: EimsInvoiceStatus;
+  receiptNumber: string;
+  rrn: string | null;
+  /** Base64 PNG, same convention as `eimsSignedQr`. */
+  qr: string | null;
+  ackStatus: string | null;
+  submittedAt: string | null;
+  lastError: EimsInvoiceError | null;
 }
 
 /** `POST /v1/verify` response, echoed back from the gateway. */
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1538a044a..b0a9a550e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -237,16 +237,16 @@ importers:
         version: 18.0.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@hookform/resolvers':
         specifier: ^5.4.0
-        version: 5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@3.25.76)
+        version: 5.4.0(react-hook-form@7.77.0(react@19.2.6))
       '@mantine/core':
         specifier: ^9.3.0
-        version: 9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@mantine/dates':
         specifier: ^9.3.0
-        version: 9.3.2(@mantine/core@9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@9.3.2(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 9.3.2(@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@9.3.0(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@mantine/hooks':
         specifier: ^9.3.0
-        version: 9.3.2(react@19.2.6)
+        version: 9.3.0(react@19.2.6)
       '@mdxeditor/editor':
         specifier: ^4.2.0
         version: 4.2.0(@codemirror/language@6.12.4)(@lezer/highlight@1.2.3)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.9.3)(yjs@13.6.32)
@@ -354,7 +354,7 @@ importers:
         version: 6.3.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tinymce@8.6.0)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(e4483b467c1e4b1b4b359f6670e164a6)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)
       '@types/three':
         specifier: ^0.185.3
         version: 0.185.3
@@ -586,13 +586,13 @@ importers:
         version: 5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@4.4.3)
       '@mantine/core':
         specifier: ^9.3.0
-        version: 9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@mantine/dates':
         specifier: ^9.3.0
-        version: 9.3.2(@mantine/core@9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@9.3.2(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 9.3.2(@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@9.3.0(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@mantine/hooks':
         specifier: ^9.3.0
-        version: 9.3.2(react@19.2.6)
+        version: 9.3.0(react@19.2.6)
       '@posthog/react':
         specifier: ^1.10.3
         version: 1.10.3(@types/react@18.3.31)(posthog-js@1.400.1)(react@19.2.6)
@@ -601,7 +601,7 @@ importers:
         version: 5.101.0(react@19.2.6)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(ea394f4c73a62db876565d0b255299aa)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)
       '@vis.gl/react-google-maps':
         specifier: ^1.8.3
         version: 1.8.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -1442,7 +1442,7 @@ importers:
         version: link:../types
       '@mantine/core':
         specifier: ^9.3.0
-        version: 9.3.2(@mantine/hooks@9.3.2(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 9.3.0(@mantine/hooks@9.3.0(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@tanstack/react-table':
         specifier: ^8.21.3
         version: 8.21.3(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
@@ -2282,6 +2282,11 @@ packages:
     peerDependencies:
       react-hook-form: ^7.0.0
 
+  '@hookform/resolvers@5.4.0':
+    resolution: {integrity: sha512-EIsqr/t/qbinPIhGjMdtvutIN1Kk4uwbROE9/UQ93CAVGR7GkA7Y92+fX80OzXi/OB67jVFYwKGO1WzkxmkFZw==}
+    peerDependencies:
+      react-hook-form: ^7.55.0
+
   '@hookform/resolvers@5.6.0':
     resolution: {integrity: sha512-qtgE4NUK/WQFPq8aDe+GOhr0/UiUSKT0m9ta9SMnDS5ZE63yC850ShAGz1lxtwO+dBjhUKvUxmHwkp4eN7/kBQ==}
     peerDependencies:
@@ -2919,6 +2924,13 @@ packages:
       react: ^18.x || ^19.x
       react-dom: ^18.x || ^19.x
 
+  '@mantine/core@9.3.0':
+    resolution: {integrity: sha512-mHVCm61YVW9ipy9eHiKMqsRUm3TkOErbdw7zHs0HRw5g403nf7tSTqNGvaYE+aX1Py874qMkrUzeQfj4bjiiBA==}
+    peerDependencies:
+      '@mantine/hooks': 9.3.0
+      react: ^19.2.0
+      react-dom: ^19.2.0
+
   '@mantine/core@9.3.2':
     resolution: {integrity: sha512-Upy/Z9Sj2eW2dGrFgUy/2kISVsxMTBYTDfP2TFdsIA3PdPSBkdqfSOPX/ug3d3F3a4bnwQSqcO6+aPEpBIh8dg==}
     peerDependencies:
@@ -2949,6 +2961,11 @@ packages:
     peerDependencies:
       react: ^18.x || ^19.x
 
+  '@mantine/hooks@9.3.0':
+    resolution: {integrity: sha512-QoSr9WI4WsKWrM3qFYYizHUn3+n+CVcFMYe4sdlnmFPStvs6BacPODKJSbFlYl73Z20t82JIy0eKqt4noHQI2g==}
+    peerDependencies:
+      react: ^19.2.0
+
   '@mantine/hooks@9.3.2':
     resolution: {integrity: sha512-jOjpUe0x1A/k3XUiu2/aaSCasXRI5ZKZOucm3ypwsvm9F2u8C1xzwBvagrzlbNZwJRF5vNYIJtCaT7NunPyc0A==}
     peerDependencies:
@@ -5213,6 +5230,9 @@ packages:
   '@types/jquery@3.5.34':
     resolution: {integrity: sha512-3m3939S3erqmTLJANS/uy0B6V7BorKx7RorcGZVjZ62dF5PAGbKEDZK1CuLtKombJkFA2T1jl8LAIIs7IV6gBQ==}
 
+  '@types/jquery@4.0.1':
+    resolution: {integrity: sha512-9a59A/tycXgYuPABcp6/3spSShn0NT2UOM4EfHvMumjYi4lJWTsK5SZWjhx3yRm9IHGCeWXdV2YfNsrWrft/CA==}
+
   '@types/js-cookie@3.0.6':
     resolution: {integrity: sha512-wkw9yd1kEXOPnvEeEV1Go1MmxtBJL0RR79aOTAApecWFVu7w0NNXNqhcWgvw2YgZDYadliXkl14pa3WXw5jlCQ==}
 
@@ -9057,6 +9077,10 @@ packages:
     resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==}
     hasBin: true
 
+  js-yaml@4.2.0:
+    resolution: {integrity: sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==}
+    hasBin: true
+
   js-yaml@4.3.0:
     resolution: {integrity: sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==}
     hasBin: true
@@ -13945,7 +13969,7 @@ snapshots:
       globals: 13.24.0
       ignore: 5.3.2
       import-fresh: 3.3.1
-      js-yaml: 4.3.0
+      js-yaml: 4.2.0
       minimatch: 3.1.5
       strip-json-comments: 3.1.1
     transitivePeerDependencies:
@@ -14078,19 +14102,10 @@ snapshots:
     dependencies:
       react-hook-form: 7.77.0(react@18.3.1)
 
-  '@hookform/resolvers@5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@3.25.76)':
+  '@hookform/resolvers@5.4.0(react-hook-form@7.77.0(react@19.2.6))':
     dependencies:
       '@standard-schema/utils': 0.3.0
       react-hook-form: 7.77.0(react@19.2.6)
-    optionalDependencies:
-      '@sinclair/typebox': 0.27.10
-      '@standard-schema/spec': 1.1.0
-      ajv: 8.20.0
-      ajv-formats: 2.1.1(ajv@8.20.0)
-      class-transformer: 0.5.1
-      class-validator: 0.14.4
-      effect: 3.21.0
-      zod: 3.25.76
 
   '@hookform/resolvers@5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@4.4.3)':
     dependencies:
@@ -14873,10 +14888,10 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
-  '@mantine/core@9.3.2(@mantine/hooks@9.3.2(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@18.3.1))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@floating-ui/react': 0.27.19(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@mantine/hooks': 9.3.2(react@18.3.1)
+      '@mantine/hooks': 9.3.0(react@18.3.1)
       clsx: 2.1.1
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
@@ -14886,6 +14901,19 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
+  '@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@floating-ui/react': 0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@mantine/hooks': 9.3.0(react@19.2.6)
+      clsx: 2.1.1
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+      react-number-format: 5.4.5(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@19.2.6)
+      type-fest: 5.7.0
+    transitivePeerDependencies:
+      - '@types/react'
+
   '@mantine/core@9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@floating-ui/react': 0.27.19(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -14908,6 +14936,15 @@ snapshots:
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
 
+  '@mantine/dates@9.3.2(@mantine/core@9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@9.3.0(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+    dependencies:
+      '@mantine/core': 9.3.0(@mantine/hooks@9.3.0(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@mantine/hooks': 9.3.0(react@19.2.6)
+      clsx: 2.1.1
+      dayjs: 1.11.21
+      react: 19.2.6
+      react-dom: 19.2.6(react@19.2.6)
+
   '@mantine/dates@9.3.2(@mantine/core@9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@9.3.2(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@mantine/core': 9.3.2(@mantine/hooks@9.3.2(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -14921,10 +14958,14 @@ snapshots:
     dependencies:
       react: 19.2.6
 
-  '@mantine/hooks@9.3.2(react@18.3.1)':
+  '@mantine/hooks@9.3.0(react@18.3.1)':
     dependencies:
       react: 18.3.1
 
+  '@mantine/hooks@9.3.0(react@19.2.6)':
+    dependencies:
+      react: 19.2.6
+
   '@mantine/hooks@9.3.2(react@19.2.6)':
     dependencies:
       react: 19.2.6
@@ -17919,11 +17960,11 @@ snapshots:
       - '@faker-js/faker'
       - supports-color
 
-  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(e4483b467c1e4b1b4b359f6670e164a6)':
+  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)':
     dependencies:
       '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
       '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
-      '@hookform/resolvers': 5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@3.25.76)
+      '@hookform/resolvers': 5.4.0(react-hook-form@7.77.0(react@19.2.6))
       '@lottiefiles/react-lottie-player': 3.6.0(react@19.2.6)
       '@mantine/charts': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(recharts@3.8.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)(redux@5.0.1))
       '@mantine/core': 7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -18026,29 +18067,11 @@ snapshots:
       - '@mui/icons-material'
       - '@mui/material'
       - '@mui/x-date-pickers'
-      - '@sinclair/typebox'
-      - '@standard-schema/spec'
       - '@types/prop-types'
       - '@types/react'
       - '@types/react-dom'
-      - '@typeschema/main'
-      - '@vinejs/vine'
-      - ajv
-      - ajv-errors
-      - ajv-formats
-      - arktype
-      - ata-validator
       - bufferutil
-      - class-transformer
-      - class-validator
-      - computed-types
       - debug
-      - effect
-      - fluentvalidation-ts
-      - fp-ts
-      - io-ts
-      - joi
-      - nope-validator
       - pdfjs-dist
       - prop-types
       - react-is
@@ -18056,21 +18079,16 @@ snapshots:
       - redux
       - rolldown
       - rollup
-      - superstruct
       - supports-color
-      - typanion
       - typescript
       - utf-8-validate
-      - valibot
-      - vest
       - vite
-      - yup
 
-  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(ea394f4c73a62db876565d0b255299aa)':
+  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)':
     dependencies:
       '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
       '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
-      '@hookform/resolvers': 5.6.0(@sinclair/typebox@0.27.10)(@standard-schema/spec@1.1.0)(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(class-transformer@0.5.1)(class-validator@0.14.4)(effect@3.21.0)(react-hook-form@7.77.0(react@19.2.6))(zod@3.25.76)
+      '@hookform/resolvers': 5.4.0(react-hook-form@7.77.0(react@19.2.6))
       '@lottiefiles/react-lottie-player': 3.6.0(react@19.2.6)
       '@mantine/charts': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(recharts@3.8.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)(redux@5.0.1))
       '@mantine/core': 7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -18173,29 +18191,11 @@ snapshots:
       - '@mui/icons-material'
       - '@mui/material'
       - '@mui/x-date-pickers'
-      - '@sinclair/typebox'
-      - '@standard-schema/spec'
       - '@types/prop-types'
       - '@types/react'
       - '@types/react-dom'
-      - '@typeschema/main'
-      - '@vinejs/vine'
-      - ajv
-      - ajv-errors
-      - ajv-formats
-      - arktype
-      - ata-validator
       - bufferutil
-      - class-transformer
-      - class-validator
-      - computed-types
       - debug
-      - effect
-      - fluentvalidation-ts
-      - fp-ts
-      - io-ts
-      - joi
-      - nope-validator
       - pdfjs-dist
       - prop-types
       - react-is
@@ -18203,15 +18203,10 @@ snapshots:
       - redux
       - rolldown
       - rollup
-      - superstruct
       - supports-color
-      - typanion
       - typescript
       - utf-8-validate
-      - valibot
-      - vest
       - vite
-      - yup
 
   '@ts-morph/common@0.27.0':
     dependencies:
@@ -18411,6 +18406,8 @@ snapshots:
     dependencies:
       '@types/sizzle': 2.3.10
 
+  '@types/jquery@4.0.1': {}
+
   '@types/js-cookie@3.0.6': {}
 
   '@types/json-schema@7.0.15': {}
@@ -18549,7 +18546,7 @@ snapshots:
 
   '@types/tinymce@4.6.9':
     dependencies:
-      '@types/jquery': 3.5.34
+      '@types/jquery': 4.0.1
 
   '@types/tmp@0.2.6': {}
 
@@ -20155,7 +20152,7 @@ snapshots:
   cosmiconfig@8.3.6(typescript@5.9.3):
     dependencies:
       import-fresh: 3.3.1
-      js-yaml: 4.3.0
+      js-yaml: 4.2.0
       parse-json: 5.2.0
       path-type: 4.0.0
     optionalDependencies:
@@ -20165,7 +20162,7 @@ snapshots:
     dependencies:
       env-paths: 2.2.1
       import-fresh: 3.3.1
-      js-yaml: 4.3.0
+      js-yaml: 4.2.0
       parse-json: 5.2.0
     optionalDependencies:
       typescript: 5.9.3
@@ -20888,7 +20885,7 @@ snapshots:
       '@typescript-eslint/parser': 8.60.1(eslint@8.57.1)(typescript@5.9.3)
       eslint: 8.57.1
       eslint-import-resolver-node: 0.3.10
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@8.57.1)
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1)
       eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.1)
       eslint-plugin-jsx-a11y: 6.10.2(eslint@8.57.1)
       eslint-plugin-react: 7.37.5(eslint@8.57.1)
@@ -20912,7 +20909,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0)(eslint@8.57.1):
+  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
       debug: 4.4.3(supports-color@8.1.1)
@@ -20927,14 +20924,14 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-module-utils@2.13.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.1):
+  eslint-module-utils@2.13.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1):
     dependencies:
       debug: 3.2.7(supports-color@8.1.1)
     optionalDependencies:
       '@typescript-eslint/parser': 8.60.1(eslint@8.57.1)(typescript@5.9.3)
       eslint: 8.57.1
       eslint-import-resolver-node: 0.3.10
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@8.57.1)
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1)
     transitivePeerDependencies:
       - supports-color
 
@@ -20949,7 +20946,7 @@ snapshots:
       doctrine: 2.1.0
       eslint: 8.57.1
       eslint-import-resolver-node: 0.3.10
-      eslint-module-utils: 2.13.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.1)
+      eslint-module-utils: 2.13.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1))(eslint@8.57.1)
       hasown: 2.0.4
       is-core-module: 2.16.2
       is-glob: 4.0.3
@@ -21061,7 +21058,7 @@ snapshots:
       imurmurhash: 0.1.4
       is-glob: 4.0.3
       is-path-inside: 3.0.3
-      js-yaml: 4.3.0
+      js-yaml: 4.2.0
       json-stable-stringify-without-jsonify: 1.0.1
       levn: 0.4.1
       lodash.merge: 4.6.2
@@ -22896,6 +22893,10 @@ snapshots:
     dependencies:
       argparse: 2.0.1
 
+  js-yaml@4.2.0:
+    dependencies:
+      argparse: 2.0.1
+
   js-yaml@4.3.0:
     dependencies:
       argparse: 2.0.1

From e37f1e0807b1f1c9b8a0278b307e8cfd5482af93 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 12 Aug 2026 17:19:06 +0000
Subject: [PATCH 059/174] fix issue

---
 apps/edr-freight-api/src/app.module.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index 3bab613fb..1efe750fc 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -112,6 +112,7 @@ import { LastMileRequestsModule } from "./modules/last-mile-requests/last-mile-r
 import { InterchangeDocumentsModule } from "./modules/interchange-documents/interchange-documents.module";
 import { ImportOperationsModule } from "./modules/import-operations/import-operations.module";
 import { AiModule } from "./modules/ai/ai.module";
+import { AuditModule } from "./modules/audit/audit.module";
 import { RequestLogMiddleware } from "@edr/api-common";
 import { LoginAudienceMiddleware } from "./modules/auth/login-audience.middleware";
 import { PositionTypePermissionsCache } from "./common/position-type-permissions.cache";
@@ -244,6 +245,7 @@ if (!process.env.APPLICATION_NAME) {
     EimsModule,
     FleetHistoryModule,
     AiModule,
+    AuditModule,
   ],
   providers: [
     EdrOrgSeeder,

From 9aae132dd4a3dc7fc9c89839b7b0d4abc7840af4 Mon Sep 17 00:00:00 2001
From: marshalyordanos <marshalyordanosseifu@gmail.com>
Date: Thu, 13 Aug 2026 08:54:20 +0300
Subject: [PATCH 060/174] feat: add shipping line companies management

- Implement ShippingLineCompaniesService for registering and managing shipping line companies.
- Create ResendActivationAction component for resending activation links to shipping lines.
- Develop ShippingLineCompaniesPage for listing and registering shipping lines with validation.
- Introduce shippingLineCompanies.service for API interactions related to shipping lines.
- Define types for shipping line companies, including registration and pagination.
- Add placeholder pages for shipping line portal, including home, bookings, help, invoices, and settings.
---
 apps/edr-freight-api/src/app.module.ts        |   2 +
 .../3440000000000-ShippingLineCompany.ts      |  78 ++++
 .../src/modules/audit/audit-endpoints.ts      |   7 +-
 .../modules/auth/customer-reset.service.ts    |  82 +++-
 .../modules/auth/forgot-password.service.ts   |  39 +-
 .../src/modules/auth/freight-auth.module.ts   |   3 +
 .../modules/companies/companies.controller.ts |  27 +-
 .../src/modules/companies/companies.module.ts |   4 +
 .../dto/account-info-response.dto.ts          |  66 +++
 .../dto/create-shipping-line.dto.ts           |  68 +++
 .../dto/shipping-line-response.dto.ts         |  64 +++
 .../entities/shipping-line-company.entity.ts  |  64 +++
 .../shipping-line-companies.controller.ts     |  95 ++++
 .../shipping-line-companies.module.ts         |  24 ++
 .../shipping-line-companies.repository.ts     |  61 +++
 .../shipping-line-companies.service.spec.ts   | 233 ++++++++++
 .../shipping-line-companies.service.ts        | 223 ++++++++++
 .../src/seed/freight-permissions.registry.ts  |  31 ++
 apps/edr-freight-web/backoffice/src/App.tsx   |   9 +
 .../components/layout/sidebar-sections.tsx    |   6 +
 .../shipping-lines/ResendActivationAction.tsx | 168 ++++++++
 .../backoffice/src/constants/QUERY_KEYS.ts    |   8 +
 .../backoffice/src/constants/URLS.ts          |  11 +
 .../backoffice/src/lib/permissions.ts         |   6 +
 .../ShippingLineCompaniesPage.tsx             | 405 ++++++++++++++++++
 .../backoffice/src/services/api.ts            |  44 ++
 .../services/shippingLineCompanies.service.ts |  54 +++
 .../src/types/shippingLineCompany.ts          |  50 +++
 apps/edr-freight-web/portal/src/App.tsx       | 301 +++++++++----
 .../portal/src/components/AppLayout.tsx       |  53 ++-
 .../onboarding/OnboardingResumeBanner.tsx     |  10 +-
 .../portal/src/hooks/useAuth.ts               |  35 +-
 .../portal/src/pages/accounts/LoginPage.tsx   |  21 +-
 .../pages/accounts/ResetPasswordLinkPage.tsx  |  62 ++-
 .../ShippingLineBookingsPage.tsx              |  17 +
 .../shipping-line/ShippingLineHelpPage.tsx    |  18 +
 .../shipping-line/ShippingLineHomePage.tsx    |  17 +
 .../ShippingLineInvoicesPage.tsx              |  13 +
 .../shipping-line/ShippingLinePlaceholder.tsx |  40 ++
 .../ShippingLineSettingsPage.tsx              |  17 +
 .../portal/src/pages/shipping-line/index.ts   |   5 +
 .../portal/src/services/companies.service.ts  |  39 +-
 42 files changed, 2463 insertions(+), 117 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3440000000000-ShippingLineCompany.ts
 create mode 100644 apps/edr-freight-api/src/modules/companies/dto/account-info-response.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/dto/create-shipping-line.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/dto/shipping-line-response.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/entities/shipping-line-company.entity.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.controller.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.repository.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.service.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.service.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/shipping-lines/ResendActivationAction.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCompaniesPage.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/services/shippingLineCompanies.service.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/types/shippingLineCompany.ts
 create mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineHelpPage.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineHomePage.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineInvoicesPage.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLinePlaceholder.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineSettingsPage.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/index.ts

diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index 1efe750fc..4c4b9efe8 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -40,6 +40,7 @@ import { TrainSchedulesModule } from "./modules/train-schedules/train-schedules.
 import { TrainSchedulingModule } from "./modules/train-scheduling/train-scheduling.module";
 import { SchedulingRescheduleModule } from "./modules/scheduling-reschedule/scheduling-reschedule.module";
 import { CompaniesModule } from "./modules/companies/companies.module";
+import { ShippingLineCompaniesModule } from "./modules/shipping-lines/shipping-line-companies.module";
 import { TrackingModule } from "./modules/tracking/tracking.module";
 import { BillingModule } from "./modules/billing/billing.module";
 import { NotificationsModule } from "./modules/notifications/notifications.module";
@@ -200,6 +201,7 @@ if (!process.env.APPLICATION_NAME) {
     TrainSchedulingModule,
     SchedulingRescheduleModule,
     CompaniesModule,
+    ShippingLineCompaniesModule,
     TrackingModule,
     BillingModule,
     NotificationsModule,
diff --git a/apps/edr-freight-api/src/migrations/3440000000000-ShippingLineCompany.ts b/apps/edr-freight-api/src/migrations/3440000000000-ShippingLineCompany.ts
new file mode 100644
index 000000000..91e78ab14
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3440000000000-ShippingLineCompany.ts
@@ -0,0 +1,78 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Shipping lines — carriers registered by backoffice staff who sign in to the
+ * portal directly.
+ *
+ * Separate from `freight.companies` on purpose: a shipping line has no TIN,
+ * business licence, eTrade record, operational profile or onboarding state, so
+ * it shares none of the customer columns. `user_id` sits on the company row
+ * itself because the company IS the account — there is no contact-person row.
+ *
+ * No FK on `user_id`: `iam.users` belongs to the IAM service's schema, which
+ * this API reads but never owns.
+ */
+export class ShippingLineCompany3440000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      DO $$ BEGIN
+        CREATE TYPE freight.shipping_line_companies_status_enum
+          AS ENUM ('active', 'suspended');
+      EXCEPTION WHEN duplicate_object THEN NULL;
+      END $$
+    `);
+
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.shipping_line_companies (
+        id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        user_id       uuid NOT NULL,
+        name          varchar(200) NOT NULL,
+        scac_code     varchar(4),
+        imo_number    varchar(20),
+        bic_code      varchar(20),
+        email         varchar(150) NOT NULL,
+        phone_number  varchar(30),
+        status        freight.shipping_line_companies_status_enum
+                        NOT NULL DEFAULT 'active',
+        created_at    timestamptz NOT NULL DEFAULT now(),
+        updated_at    timestamptz NOT NULL DEFAULT now(),
+        deleted_at    timestamptz
+      )
+    `);
+
+    // One login per shipping line. Partial so a soft-deleted row frees its
+    // account for re-registration rather than blocking it forever.
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS "UQ_shipping_line_companies_user"
+        ON freight.shipping_line_companies (user_id)
+        WHERE deleted_at IS NULL
+    `);
+
+    // SCAC identifies the carrier globally — two live lines cannot share one.
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS "UQ_shipping_line_companies_scac"
+        ON freight.shipping_line_companies (scac_code)
+        WHERE scac_code IS NOT NULL AND deleted_at IS NULL
+    `);
+
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS "UQ_shipping_line_companies_email"
+        ON freight.shipping_line_companies (lower(email))
+        WHERE deleted_at IS NULL
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_shipping_line_companies_status"
+        ON freight.shipping_line_companies (status)
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DROP TABLE IF EXISTS freight.shipping_line_companies`,
+    );
+    await queryRunner.query(
+      `DROP TYPE IF EXISTS freight.shipping_line_companies_status_enum`,
+    );
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts b/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
index 0526636ff..d46f63a7d 100644
--- a/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
+++ b/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
@@ -432,11 +432,16 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/service-types/:id/move-order": ["Move a service type up or down in display order", "POST", "Service Type"],
   "POST /api/service-types/reorder": ["Bulk reorder service types by ID list", "POST", "Service Type"],
 
-  // Shipping Line
+  // Shipping Line (rule-engine lookup list — a code/label bookings reference,
+  // not an account)
   "POST /api/shipping-lines": ["Create a shipping line", "POST", "Shipping Line"],
   "PATCH /api/shipping-lines/:id": ["Update a shipping line", "PATCH", "Shipping Line"],
   "DELETE /api/shipping-lines/:id": ["Soft-delete a shipping line", "DELETE", "Shipping Line"],
 
+  // Shipping Line Company (carrier with a portal login, registered by staff)
+  "POST /api/shipping-line-companies": ["Register a shipping line company and send its activation link", "POST", "Shipping Line Company"],
+  "POST /api/shipping-line-companies/:id/resend-activation": ["Resend a shipping line company's activation link", "POST", "Shipping Line Company"],
+
   // Signature
   "PUT /api/me/signature": ["Create or update the reusable saved signature", "PUT", "Signature"],
 
diff --git a/apps/edr-freight-api/src/modules/auth/customer-reset.service.ts b/apps/edr-freight-api/src/modules/auth/customer-reset.service.ts
index 4eb6ecc31..b00fd588e 100644
--- a/apps/edr-freight-api/src/modules/auth/customer-reset.service.ts
+++ b/apps/edr-freight-api/src/modules/auth/customer-reset.service.ts
@@ -1,6 +1,7 @@
 import { Injectable, Logger } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { InjectRepository } from "@nestjs/typeorm";
+import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
 import { Repository } from "typeorm";
 
 import { ExternalProfile } from "../companies/entities/external-profile.entity";
@@ -86,7 +87,66 @@ export class CustomerResetService {
     const resolved = await this.resolvePrimaryContactUser(companyId);
     if (!resolved) return null;
 
-    const { user, userId } = resolved;
+    return this.sendResetLinkToUser(resolved.userId, channel, {
+      scope: `company ${companyId}`,
+    });
+  }
+
+  /**
+   * Mint and deliver a reset link to a specific IAM account.
+   *
+   * The delivery half of {@link sendResetLinkToCustomer}, split out so callers
+   * that resolve their target differently can reuse it: a customer is found via
+   * the company's primary contact, while a shipping line has no contact row at
+   * all and resolves straight off its own record. Everything below the lookup —
+   * active-account gating, the domestic-SMS rule, mint-before-send, the
+   * undelivered-link diagnostic — is identical for both and must stay that way.
+   *
+   * `scope` only labels the log line with whatever the caller resolved from.
+   *
+   * `allowWithoutCredential` relaxes the lookup for first-time activation:
+   * the default gate requires an existing active credential (so a reset cannot
+   * revive a suspended account), but an account that has never set a password
+   * has no credential row yet and would be excluded from its own activation
+   * link. Callers pass it only when the account is expected to be
+   * password-less — see ShippingLineCompaniesService.
+   */
+  async sendResetLinkToUser(
+    userId: string,
+    channel: ResetChannel,
+    options?: { scope?: string; allowWithoutCredential?: boolean },
+  ): Promise<SentResetLink | null> {
+    const user = options?.allowWithoutCredential
+      ? await this.forgotPasswordService.resolveActivatableUserById(userId)
+      : await this.forgotPasswordService.resolveActiveUserById(userId);
+
+    if (!user?.id) {
+      this.logger.warn(
+        `User ${userId} is not an active account${
+          options?.allowWithoutCredential
+            ? ""
+            : " (or has no active credential — pass allowWithoutCredential for first-time activation)"
+        }`,
+      );
+      return null;
+    }
+
+    return this.deliverResetLink(user, user.id, channel, options?.scope);
+  }
+
+  /**
+   * Shared tail: target selection → SMS reachability → mint → send → report.
+   * Callers have already resolved `user` to an active account.
+   */
+  private async deliverResetLink(
+    user: User,
+    userId: string,
+    channel: ResetChannel,
+    scope?: string,
+  ): Promise<SentResetLink | null> {
+    this.logger.log(
+      `Staff-triggered shipping line ${"link"}`,
+    );
     const target = this.forgotPasswordService.targetFor(user, channel);
     if (!target) return null;
 
@@ -110,6 +170,9 @@ export class CustomerResetService {
     );
     const link = this.buildResetLink(ticket.userId, ticket.verificationCode);
     const expiresAt = new Date(Date.now() + RESET_LINK_TTL_MS);
+this.logger.log(
+      `Staff-triggered shipping line ${link}`,
+    );
 
     const { queued } = target.email
       ? await this.emailClient.sendEmail({
@@ -127,7 +190,22 @@ export class CustomerResetService {
         });
 
     this.logger.log(
-      `Staff-triggered ${channel} reset link sent to user ${userId} (company ${companyId}) queued=${queued}`,
+      `Staff-triggered shipping line ${channel} reset link sent to user ${userId}${
+        scope ? ` (${scope})` : ""
+      } queued=${queued}`,
+    );
+
+    // SECURITY: logs a live password-reset credential in cleartext. Anyone with
+    // read access to the log stream can set the password for the account named
+    // on the same line — including on sends that succeeded, not just failures.
+    // Kept deliberately: log aggregation is the debugging path for flaky
+    // email/SMS here, the same tradeoff otp.service.ts makes for OTP codes. If
+    // that is ever revisited, gate this on an env flag rather than deleting it,
+    // so dev keeps its workflow.
+    this.logger.warn(
+      `reset-link.cleartext channel=${channel} user=${userId}${
+        scope ? ` (${scope})` : ""
+      } link=${link}`,
     );
 
     if (!queued) {
diff --git a/apps/edr-freight-api/src/modules/auth/forgot-password.service.ts b/apps/edr-freight-api/src/modules/auth/forgot-password.service.ts
index a3dbf1061..a2afdbbbc 100644
--- a/apps/edr-freight-api/src/modules/auth/forgot-password.service.ts
+++ b/apps/edr-freight-api/src/modules/auth/forgot-password.service.ts
@@ -89,6 +89,28 @@ export class ForgotPasswordService {
       .getOne();
   }
 
+  /**
+   * Active account by id, WITHOUT requiring an existing credential.
+   *
+   * {@link activeUserQuery} inner-joins an active `user_credentials` row, which
+   * is right for a *reset*: it stops a staff-triggered link from reactivating a
+   * suspended account. But an account that has never set a password has no
+   * credential row yet, so that join excludes exactly the accounts a first-time
+   * *activation* link is for — shipping lines are created deliberately without
+   * one (see ShippingLineCompaniesService.register).
+   *
+   * The `isActive` gate is kept; only the credential requirement is dropped.
+   */
+  async resolveActivatableUserById(userId: string): Promise<User | null> {
+    if (!userId) return null;
+    return await this.userRepository
+      .createQueryBuilder("u")
+      .where("u.isActive = true")
+      .andWhere("u.id = :userId", { userId })
+      .orderBy("u.createdAt", "DESC")
+      .getOne();
+  }
+
   /**
    * Base query for accounts eligible to reset. `.where()` is claimed here so
    * callers must use `.andWhere()` — TypeORM's `.where()` resets the clause,
@@ -233,9 +255,22 @@ export class ForgotPasswordService {
       "This password-reset link is invalid or has expired. Request a new one.",
     );
 
-    const user = await this.resolveActiveUserById(userId);
+    // Credential-less on purpose: this resolves links for *setting* a password,
+    // which includes first-time activation of an account that has never had one
+    // (shipping lines are created without a credential row). Requiring one here
+    // rejected a perfectly valid activation link before its token was ever
+    // checked. The ticket checks below are what actually authorise the reset.
+    const user = await this.resolveActivatableUserById(userId);
     const identifier = user && this.identifierFor(user);
-    if (!user || !identifier) throw invalid;
+    if (!user || !identifier) {
+      // Logged because the early return above bypasses the rejection warning
+      // below — without this, an account that fails the lookup produces no
+      // diagnostic at all and looks identical to a bad token.
+      this.logger.warn(
+        `Reset link rejected for user ${userId} — no active account or no usable identifier`,
+      );
+      throw invalid;
+    }
 
     const verification = await this.dataSource
       .getRepository(UserVerification)
diff --git a/apps/edr-freight-api/src/modules/auth/freight-auth.module.ts b/apps/edr-freight-api/src/modules/auth/freight-auth.module.ts
index ff8f803b9..557e50fb3 100644
--- a/apps/edr-freight-api/src/modules/auth/freight-auth.module.ts
+++ b/apps/edr-freight-api/src/modules/auth/freight-auth.module.ts
@@ -51,5 +51,8 @@ import { ListUsersService } from './list-users.service';
     ForgotPasswordService,
     CustomerResetService,
   ],
+  // Shipping-line registration mints activation links through the same
+  // staff-triggered reset path customers use.
+  exports: [CustomerResetService],
 })
 export class FreightAuthModule {}
diff --git a/apps/edr-freight-api/src/modules/companies/companies.controller.ts b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
index d35400f1a..175533c6d 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.controller.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
@@ -52,6 +52,11 @@ import {
 } from "./entities/company-profile.entity";
 import { ResponseExternalProfileDto } from "./dto/response-external-profile.dto";
 import { CompanyInfoResponseDto } from "./dto/company-info-response.dto";
+import {
+  AccountInfoResponse,
+  ShippingLineInfoResponseDto,
+} from "./dto/account-info-response.dto";
+import { ShippingLineCompaniesService } from "../shipping-lines/shipping-line-companies.service";
 import { UpdateProfileDto } from "./dto/update-profile.dto";
 import { ProfileResponseDto } from "./dto/profile-response.dto";
 import { DashboardSummaryResponseDto } from "./dto/dashboard-summary-response.dto";
@@ -96,6 +101,7 @@ export class CompaniesController {
   constructor(
     private readonly companiesService: CompaniesService,
     private readonly filesService: FilesService,
+    private readonly shippingLineCompaniesService: ShippingLineCompaniesService,
   ) { }
 
   /**
@@ -119,16 +125,31 @@ export class CompaniesController {
 
   @Get("getInfo")
   @PortalCustomer()
-  @ApiOperation({ summary: "Get company info for the current user" })
+  @ApiOperation({
+    summary: "Get account info for the current user (customer or shipping line)",
+  })
   async getInfo(
     @CurrentUser() user: CurrentIamUser,
-  ): Promise<CompanyInfoResponseDto> {
+  ): Promise<AccountInfoResponse> {
+    // A shipping line has no company and no external profile, so the customer
+    // lookup below would 404. Checked first, and reported with an explicit
+    // `accountKind` so the portal can skip onboarding for shipping lines
+    // without inferring it from a missing company.
+    const shippingLine = await this.shippingLineCompaniesService.findByUserId(
+      user.id,
+    );
+    if (shippingLine) {
+      return new ShippingLineInfoResponseDto(shippingLine);
+    }
+
     const { profile, company } =
       await this.companiesService.getCompanyInfoByUserId(user.id);
     const review = await this.companiesService.getOpenChangeRequestForCompany(
       company.id,
     );
-    return new CompanyInfoResponseDto(profile, company, review);
+    return Object.assign(new CompanyInfoResponseDto(profile, company, review), {
+      accountKind: "customer" as const,
+    });
   }
 
   @Get("profile")
diff --git a/apps/edr-freight-api/src/modules/companies/companies.module.ts b/apps/edr-freight-api/src/modules/companies/companies.module.ts
index f0a443ba8..aa0a00dff 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.module.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.module.ts
@@ -17,6 +17,7 @@ import { CompanyProfile } from "./entities/company-profile.entity";
 import { CompanyChangeRequest } from "./entities/company-change-request.entity";
 import { CompanyRevision } from "./entities/company-revision.entity";
 import { Booking } from "../bookings/entities/booking.entity";
+import { ShippingLineCompaniesModule } from "../shipping-lines/shipping-line-companies.module";
 import { CompanyProfileRepository } from "./company-profile.repository";
 import { CompanyChangeRequestRepository } from "./company-change-request.repository";
 import { CompanyRevisionRepository } from "./company-revision.repository";
@@ -44,6 +45,9 @@ import { VerifaydaModule } from "../verifayda/verifayda.module";
     forwardRef(() => NotificationInboxModule),
     // Fayda identity verification for the company's owner and PoA.
     VerifaydaModule,
+    // `GET /companies/getInfo` serves both portal audiences: it must recognise a
+    // shipping-line session, which has no company row to look up.
+    ShippingLineCompaniesModule,
   ],
   controllers: [CompaniesController],
   providers: [
diff --git a/apps/edr-freight-api/src/modules/companies/dto/account-info-response.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/account-info-response.dto.ts
new file mode 100644
index 000000000..ab680f8f3
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/companies/dto/account-info-response.dto.ts
@@ -0,0 +1,66 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+
+import { ShippingLineCompany } from "../../shipping-lines/entities/shipping-line-company.entity";
+import { CompanyInfoResponseDto } from "./company-info-response.dto";
+
+/**
+ * What kind of account is signed in to the portal.
+ *
+ * The portal keys its onboarding gate off this rather than off "is `company`
+ * missing?": a failed or slow company fetch also leaves `company` empty, and
+ * treating that as "no onboarding needed" would let customers skip onboarding
+ * whenever the request failed. A shipping line is identified positively, and
+ * anything else defaults to `customer`.
+ */
+export type AccountKind = "customer" | "shipping_line";
+
+/** The signed-in shipping line. No company, no profile, no onboarding. */
+export class ShippingLineInfoResponseDto {
+  @ApiProperty({ enum: ["shipping_line"] })
+  accountKind: "shipping_line" = "shipping_line";
+
+  @ApiProperty()
+  id: string;
+
+  @ApiProperty()
+  name: string;
+
+  @ApiProperty()
+  email: string;
+
+  @ApiPropertyOptional()
+  phoneNumber?: string | null;
+
+  @ApiPropertyOptional()
+  scacCode?: string | null;
+
+  @ApiProperty()
+  status: string;
+
+  /**
+   * Always null. Present so the portal can read `company` / `profile` off either
+   * payload shape without narrowing the union first — the fields a customer
+   * session carries simply have no shipping-line equivalent.
+   */
+  @ApiProperty({ nullable: true })
+  company: null = null;
+
+  @ApiProperty({ nullable: true })
+  profile: null = null;
+
+  @ApiProperty({ nullable: true })
+  review: null = null;
+
+  constructor(entity: ShippingLineCompany) {
+    this.id = entity.id;
+    this.name = entity.name;
+    this.email = entity.email;
+    this.phoneNumber = entity.phoneNumber ?? null;
+    this.scacCode = entity.scacCode ?? null;
+    this.status = entity.status;
+  }
+}
+
+export type AccountInfoResponse =
+  | (CompanyInfoResponseDto & { accountKind: "customer" })
+  | ShippingLineInfoResponseDto;
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/dto/create-shipping-line.dto.ts b/apps/edr-freight-api/src/modules/shipping-lines/dto/create-shipping-line.dto.ts
new file mode 100644
index 000000000..5f89c916c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/dto/create-shipping-line.dto.ts
@@ -0,0 +1,68 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import {
+  IsEmail,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  Matches,
+  MaxLength,
+} from "class-validator";
+
+import { IsValidPhone } from "../../../common/validators/is-phone-number.validator";
+
+export class CreateShippingLineDto {
+  @ApiProperty({ example: "Ethiopian Shipping Lines" })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(200)
+  name!: string;
+
+  /**
+   * Becomes the IAM account's email — the activation link is sent here, so it
+   * is required even though the customer equivalent is optional.
+   */
+  @ApiProperty({ example: "ops@esl.com.et" })
+  @IsEmail()
+  @MaxLength(150)
+  email!: string;
+
+  @ApiPropertyOptional({ example: "+251911223344" })
+  @IsOptional()
+  @IsString()
+  @MaxLength(30)
+  @IsValidPhone()
+  phoneNumber?: string;
+
+  @ApiPropertyOptional({
+    example: "ESLK",
+    description: "Standard Carrier Alpha Code — 2-4 letters",
+  })
+  @IsOptional()
+  @IsString()
+  @Matches(/^[A-Za-z]{2,4}$/, {
+    message: "SCAC must be 2-4 letters",
+  })
+  scacCode?: string;
+
+  @ApiPropertyOptional({ example: "IMO9074729" })
+  @IsOptional()
+  @IsString()
+  @MaxLength(20)
+  imoNumber?: string;
+
+  @ApiPropertyOptional({ example: "ESLU" })
+  @IsOptional()
+  @IsString()
+  @MaxLength(20)
+  bicCode?: string;
+
+  /**
+   * Login name. Optional — defaults to the email, which is what the line will
+   * naturally try first.
+   */
+  @ApiPropertyOptional({ example: "esl-ops" })
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  username?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/dto/shipping-line-response.dto.ts b/apps/edr-freight-api/src/modules/shipping-lines/dto/shipping-line-response.dto.ts
new file mode 100644
index 000000000..051c3af28
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/dto/shipping-line-response.dto.ts
@@ -0,0 +1,64 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+
+import {
+  ShippingLineCompany,
+  ShippingLineStatus,
+} from "../entities/shipping-line-company.entity";
+
+export class ShippingLineResponseDto {
+  @ApiProperty()
+  id: string;
+
+  @ApiProperty()
+  name: string;
+
+  @ApiProperty()
+  email: string;
+
+  @ApiPropertyOptional()
+  phoneNumber?: string | null;
+
+  @ApiPropertyOptional()
+  scacCode?: string | null;
+
+  @ApiPropertyOptional()
+  imoNumber?: string | null;
+
+  @ApiPropertyOptional()
+  bicCode?: string | null;
+
+  @ApiProperty({ enum: ShippingLineStatus })
+  status: ShippingLineStatus;
+
+  @ApiProperty()
+  createdAt: Date;
+
+  constructor(entity: ShippingLineCompany) {
+    this.id = entity.id;
+    this.name = entity.name;
+    this.email = entity.email;
+    this.phoneNumber = entity.phoneNumber ?? null;
+    this.scacCode = entity.scacCode ?? null;
+    this.imoNumber = entity.imoNumber ?? null;
+    this.bicCode = entity.bicCode ?? null;
+    this.status = entity.status;
+    this.createdAt = entity.createdAt;
+  }
+}
+
+export class RegisterShippingLineResponseDto {
+  @ApiProperty({ type: ShippingLineResponseDto })
+  shippingLine: ShippingLineResponseDto;
+
+  @ApiPropertyOptional({
+    description:
+      "Masked destination the activation link was sent to, or null if delivery failed.",
+    example: "o**@esl.com.et",
+  })
+  activationSentTo: string | null;
+
+  constructor(shippingLine: ShippingLineCompany, activationSentTo: string | null) {
+    this.shippingLine = new ShippingLineResponseDto(shippingLine);
+    this.activationSentTo = activationSentTo;
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/entities/shipping-line-company.entity.ts b/apps/edr-freight-api/src/modules/shipping-lines/entities/shipping-line-company.entity.ts
new file mode 100644
index 000000000..fac8c00a6
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/entities/shipping-line-company.entity.ts
@@ -0,0 +1,64 @@
+import { BaseEntity } from "@edr/api-common";
+import { Column, Entity, Index } from "typeorm";
+
+export enum ShippingLineStatus {
+  Active = "active",
+  Suspended = "suspended",
+}
+
+/**
+ * A shipping line — a carrier that books rail capacity directly, registered by
+ * backoffice staff rather than self-signing up.
+ *
+ * Deliberately NOT a {@link Company} of a new {@link CompanyType}: a shipping
+ * line carries none of what `companies` exists to hold — no TIN, no business
+ * licence, no eTrade authenticity lookup, no operational `company_profiles`, no
+ * onboarding wizard state. Modelling it there would mean making all of that
+ * nullable for one row shape that never uses it.
+ *
+ * The company IS the account: there is no contact-person row (customers get one
+ * via `external_profiles`), so `user_id` lives here and the login credentials
+ * are the company's own. That is also why the password-reset flow resolves a
+ * shipping line straight off this table instead of through a primary contact.
+ */
+@Entity({ schema: "freight", name: "shipping_line_companies" })
+@Index(["status"])
+export class ShippingLineCompany extends BaseEntity {
+  /**
+   * The IAM account (`iam.users`, userType `individual`) that signs in as this
+   * shipping line. No FK: `iam` is a separate schema owned by the IAM service,
+   * and the rest of the codebase reaches it by query rather than by relation.
+   */
+  @Column({ name: "user_id", type: "uuid", unique: true })
+  userId!: string;
+
+  @Column({ name: "name", type: "varchar", length: 200 })
+  name!: string;
+
+  /** Standard Carrier Alpha Code — 2-4 letters identifying the carrier. */
+  @Column({ name: "scac_code", type: "varchar", length: 4, nullable: true })
+  scacCode?: string | null;
+
+  /** IMO number of the vessel operator. */
+  @Column({ name: "imo_number", type: "varchar", length: 20, nullable: true })
+  imoNumber?: string | null;
+
+  /** BIC code — the container prefix the line's equipment is registered under. */
+  @Column({ name: "bic_code", type: "varchar", length: 20, nullable: true })
+  bicCode?: string | null;
+
+  /** Mirrors the IAM account's email; the activation link is sent here. */
+  @Column({ name: "email", type: "varchar", length: 150 })
+  email!: string;
+
+  @Column({ name: "phone_number", type: "varchar", length: 30, nullable: true })
+  phoneNumber?: string | null;
+
+  @Column({
+    name: "status",
+    type: "enum",
+    enum: ShippingLineStatus,
+    default: ShippingLineStatus.Active,
+  })
+  status!: ShippingLineStatus;
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.controller.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.controller.ts
new file mode 100644
index 000000000..15ba673a3
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.controller.ts
@@ -0,0 +1,95 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  ParseUUIDPipe,
+  Post,
+  Query,
+} from "@nestjs/common";
+import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
+
+import { BookingStaff } from "../../common/booking-guards";
+import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
+import { BackofficeResetPasswordDto } from "../auth/dto/forgot-password.dto";
+import { CreateShippingLineDto } from "./dto/create-shipping-line.dto";
+import {
+  RegisterShippingLineResponseDto,
+  ShippingLineResponseDto,
+} from "./dto/shipping-line-response.dto";
+import { ShippingLineCompaniesService } from "./shipping-line-companies.service";
+
+/**
+ * Shipping line *companies* — carriers with a portal login, registered by staff
+ * (there is no self-signup). The line receives a single-use activation link and
+ * sets its own password, so staff never see or handle a credential.
+ *
+ * Distinct from `freight.shipping_lines` behind `/shipping-lines`
+ * (rule-engine): that is a pricing lookup list — a code/label a booking points
+ * at via `shipping_line_id` — with no account, no user and no login. Same words,
+ * different concept, hence the separate route.
+ */
+@ApiTags("shipping-line-companies")
+@Controller("shipping-line-companies")
+@ApiBearerAuth()
+export class ShippingLineCompaniesController {
+  constructor(private readonly shippingLineCompaniesService: ShippingLineCompaniesService) {}
+
+  @Post()
+  @BookingStaff(FREIGHT_PERMS.shippingLines.create)
+  @ApiOperation({
+    summary: "Register a shipping line and send its activation link",
+  })
+  async register(
+    @Body() dto: CreateShippingLineDto,
+  ): Promise<RegisterShippingLineResponseDto> {
+    const { shippingLine, activationSentTo } =
+      await this.shippingLineCompaniesService.register(dto);
+    return new RegisterShippingLineResponseDto(shippingLine, activationSentTo);
+  }
+
+  @Get()
+  @BookingStaff(FREIGHT_PERMS.shippingLines.view)
+  @ApiOperation({ summary: "List shipping lines (paginated)" })
+  async list(
+    @Query("page") page?: string,
+    @Query("limit") limit?: string,
+  ): Promise<{
+    items: ShippingLineResponseDto[];
+    total: number;
+    page: number;
+    limit: number;
+  }> {
+    const result = await this.shippingLineCompaniesService.list(
+      page ? Number(page) : undefined,
+      limit ? Number(limit) : undefined,
+    );
+    return {
+      ...result,
+      items: result.items.map((item) => new ShippingLineResponseDto(item)),
+    };
+  }
+
+  @Get(":id")
+  @BookingStaff(FREIGHT_PERMS.shippingLines.view)
+  @ApiOperation({ summary: "Get a shipping line by id" })
+  async findOne(
+    @Param("id", ParseUUIDPipe) id: string,
+  ): Promise<ShippingLineResponseDto> {
+    return new ShippingLineResponseDto(
+      await this.shippingLineCompaniesService.findById(id),
+    );
+  }
+
+  @Post(":id/resend-activation")
+  @BookingStaff(FREIGHT_PERMS.shippingLines.resetPassword)
+  @ApiOperation({
+    summary: "Resend a shipping line's activation / password-reset link",
+  })
+  async resendActivation(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: BackofficeResetPasswordDto,
+  ) {
+    return this.shippingLineCompaniesService.resendActivation(id, dto.channel);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts
new file mode 100644
index 000000000..81d5b9cdf
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts
@@ -0,0 +1,24 @@
+import { Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+
+import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
+
+import { FreightAuthModule } from "../auth/freight-auth.module";
+import { OtpModule } from "../otp/otp.module";
+import { ShippingLineCompany } from "./entities/shipping-line-company.entity";
+import { ShippingLineCompaniesController } from "./shipping-line-companies.controller";
+import { ShippingLineCompaniesRepository } from "./shipping-line-companies.repository";
+import { ShippingLineCompaniesService } from "./shipping-line-companies.service";
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([ShippingLineCompany, User]),
+    // CustomerResetService — activation links reuse the staff-triggered reset path.
+    FreightAuthModule,
+    OtpModule,
+  ],
+  controllers: [ShippingLineCompaniesController],
+  providers: [ShippingLineCompaniesService, ShippingLineCompaniesRepository],
+  exports: [ShippingLineCompaniesService],
+})
+export class ShippingLineCompaniesModule {}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.repository.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.repository.ts
new file mode 100644
index 000000000..997550172
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.repository.ts
@@ -0,0 +1,61 @@
+import { BaseRepository } from "@edr/api-common";
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { EntityManager, Repository } from "typeorm";
+
+import { ShippingLineCompany } from "./entities/shipping-line-company.entity";
+
+@Injectable()
+export class ShippingLineCompaniesRepository extends BaseRepository<ShippingLineCompany> {
+  constructor(
+    @InjectRepository(ShippingLineCompany)
+    private readonly shippingLineRepo: Repository<ShippingLineCompany>,
+  ) {
+    super(shippingLineRepo);
+  }
+
+  findByUserId(userId: string): Promise<ShippingLineCompany | null> {
+    return this.shippingLineRepo.findOne({ where: { userId } });
+  }
+
+  /** Case-insensitive, matching the `lower(email)` unique index. */
+  async existsByEmail(email: string): Promise<boolean> {
+    const count = await this.shippingLineRepo
+      .createQueryBuilder("sl")
+      .where("lower(sl.email) = lower(:email)", { email })
+      .getCount();
+    return count > 0;
+  }
+
+  async existsByScac(scacCode: string): Promise<boolean> {
+    const count = await this.shippingLineRepo
+      .createQueryBuilder("sl")
+      .where("upper(sl.scacCode) = upper(:scacCode)", { scacCode })
+      .getCount();
+    return count > 0;
+  }
+
+  findAllPaginated(
+    skip: number,
+    take: number,
+  ): Promise<[ShippingLineCompany[], number]> {
+    return this.shippingLineRepo.findAndCount({
+      order: { createdAt: "DESC" },
+      skip,
+      take,
+    });
+  }
+
+  /**
+   * Insert inside a caller-supplied transaction, so the shipping-line row and
+   * the IAM user it points at commit together — a row referencing a user that
+   * was rolled back (or vice versa) is an account nobody can sign in to.
+   */
+  createInTransaction(
+    manager: EntityManager,
+    data: Partial<ShippingLineCompany>,
+  ): Promise<ShippingLineCompany> {
+    const repo = manager.getRepository(ShippingLineCompany);
+    return repo.save(repo.create(data));
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.service.spec.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.service.spec.ts
new file mode 100644
index 000000000..d9d429dc9
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.service.spec.ts
@@ -0,0 +1,233 @@
+import { ConflictException } from "@nestjs/common";
+import {
+  EUserStatus,
+  EUserType,
+} from "@tria-plc/api-common/utils/enums/user.enum";
+
+import { ResetChannel } from "../auth/dto/forgot-password.dto";
+import { ShippingLineCompaniesService } from "./shipping-line-companies.service";
+
+/**
+ * Registration is the whole feature: an IAM account and a carrier record
+ * created together, then an activation link the line uses to set its own
+ * password. These lock the parts that would silently break the login.
+ */
+describe("ShippingLineCompaniesService.register", () => {
+  const savedUser = { id: "user-1" };
+
+  let shippingLinesRepo: {
+    existsByEmail: jest.Mock;
+    existsByScac: jest.Mock;
+    createInTransaction: jest.Mock;
+    findById: jest.Mock;
+    findByUserId: jest.Mock;
+  };
+  let userRepository: { findOne: jest.Mock };
+  let customerResetService: { sendResetLinkToUser: jest.Mock };
+  let dataSource: { transaction: jest.Mock };
+  let userRepoInTx: { create: jest.Mock; save: jest.Mock };
+  let service: ShippingLineCompaniesService;
+
+  const dto = {
+    name: "Ethiopian Shipping Lines",
+    email: "Ops@ESL.com.et",
+    phoneNumber: "+251911223344",
+    scacCode: "eslk",
+  };
+
+  beforeEach(() => {
+    userRepoInTx = {
+      create: jest.fn((v) => v),
+      save: jest.fn().mockResolvedValue(savedUser),
+    };
+
+    shippingLinesRepo = {
+      existsByEmail: jest.fn().mockResolvedValue(false),
+      existsByScac: jest.fn().mockResolvedValue(false),
+      createInTransaction: jest
+        .fn()
+        .mockImplementation((_m, data) => ({ id: "sl-1", ...data })),
+      findById: jest.fn(),
+      findByUserId: jest.fn(),
+    };
+    userRepository = { findOne: jest.fn().mockResolvedValue(null) };
+    customerResetService = {
+      sendResetLinkToUser: jest
+        .fn()
+        .mockResolvedValue({ maskedTarget: "o**@esl.com.et", channel: "email" }),
+    };
+    dataSource = {
+      transaction: jest.fn(async (cb) =>
+        cb({ getRepository: () => userRepoInTx }),
+      ),
+    };
+
+    service = new ShippingLineCompaniesService(
+      shippingLinesRepo as never,
+      userRepository as never,
+      customerResetService as never,
+      dataSource as never,
+    );
+  });
+
+  it("creates the IAM account with no password set", async () => {
+    await service.register(dto as never);
+
+    const created = userRepoInTx.create.mock.calls[0][0];
+    expect(created).toMatchObject({
+      userType: EUserType.INDIVIDUAL,
+      isActive: true,
+      status: EUserStatus.ACCEPTED,
+      // The line sets its own password from the activation link. Employee
+      // creation seeds a shared default here; a shipping line must not get one.
+      hasSetPassword: false,
+    });
+  });
+
+  it("never writes a credential row", async () => {
+    await service.register(dto as never);
+
+    // Only the User repository is touched inside the transaction — a
+    // UserCredential insert would mean the account has a password nobody chose.
+    for (const call of userRepoInTx.save.mock.calls) {
+      expect(call[0]).not.toHaveProperty("password");
+    }
+  });
+
+  it("normalises email and SCAC before storing", async () => {
+    const result = await service.register(dto as never);
+
+    expect(result.shippingLine).toMatchObject({
+      email: "ops@esl.com.et",
+      scacCode: "ESLK",
+    });
+  });
+
+  it("creates the account and the record in one transaction", async () => {
+    await service.register(dto as never);
+
+    expect(dataSource.transaction).toHaveBeenCalledTimes(1);
+    expect(shippingLinesRepo.createInTransaction).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ userId: "user-1" }),
+    );
+  });
+
+  it("sends the activation link outside the transaction, after commit", async () => {
+    const order: string[] = [];
+    dataSource.transaction.mockImplementation(async (cb: never) => {
+      order.push("tx");
+      return (cb as unknown as (m: unknown) => Promise<unknown>)({
+        getRepository: () => userRepoInTx,
+      });
+    });
+    customerResetService.sendResetLinkToUser.mockImplementation(async () => {
+      order.push("send");
+      return { maskedTarget: "o**@esl.com.et", channel: "email" };
+    });
+
+    await service.register(dto as never);
+
+    expect(order[0]).toBe("tx");
+    expect(order).toContain("send");
+  });
+
+  it("emails the link, and also texts it when the number is domestic", async () => {
+    await service.register(dto as never);
+
+    const channels = customerResetService.sendResetLinkToUser.mock.calls.map(
+      (c) => c[1],
+    );
+    expect(channels).toContain(ResetChannel.Email);
+    expect(channels).toContain(ResetChannel.Phone);
+  });
+
+  it("emails only when the number is foreign — the SMS gateway is domestic-only", async () => {
+    await service.register({ ...dto, phoneNumber: "+441234567890" } as never);
+
+    const channels = customerResetService.sendResetLinkToUser.mock.calls.map(
+      (c) => c[1],
+    );
+    expect(channels).toEqual([ResetChannel.Email]);
+  });
+
+  it("keeps the registration when the activation link fails to send", async () => {
+    customerResetService.sendResetLinkToUser.mockResolvedValue(null);
+
+    const result = await service.register(dto as never);
+
+    // The account is valid without the link and the link is resendable —
+    // a delivery failure must not roll back the registration.
+    expect(result.shippingLine).toMatchObject({ id: "sl-1" });
+    expect(result.activationSentTo).toBeNull();
+  });
+
+  it("refuses a duplicate email", async () => {
+    shippingLinesRepo.existsByEmail.mockResolvedValue(true);
+
+    await expect(service.register(dto as never)).rejects.toBeInstanceOf(
+      ConflictException,
+    );
+    expect(dataSource.transaction).not.toHaveBeenCalled();
+  });
+
+  it("refuses a duplicate SCAC", async () => {
+    shippingLinesRepo.existsByScac.mockResolvedValue(true);
+
+    await expect(service.register(dto as never)).rejects.toBeInstanceOf(
+      ConflictException,
+    );
+    expect(dataSource.transaction).not.toHaveBeenCalled();
+  });
+
+  it("refuses credentials already belonging to another account", async () => {
+    // Reusing an existing IAM user would let one login resolve to both a
+    // customer and a shipping line.
+    userRepository.findOne.mockResolvedValue({ id: "existing" });
+
+    await expect(service.register(dto as never)).rejects.toBeInstanceOf(
+      ConflictException,
+    );
+    expect(dataSource.transaction).not.toHaveBeenCalled();
+  });
+
+  it("defaults the username to the email", async () => {
+    await service.register(dto as never);
+
+    expect(userRepoInTx.create.mock.calls[0][0]).toMatchObject({
+      username: "ops@esl.com.et",
+    });
+  });
+
+  /**
+   * The default reset lookup inner-joins an active `user_credentials` row so a
+   * reset cannot revive a suspended account. A shipping line has no credential
+   * until it uses the activation link, so without this flag the account is
+   * excluded from its own activation — the link is never minted, never logged,
+   * and resend answers 404.
+   */
+  it("requests the credential-less lookup for every activation send", async () => {
+    await service.register(dto as never);
+
+    expect(customerResetService.sendResetLinkToUser).toHaveBeenCalled();
+    for (const call of customerResetService.sendResetLinkToUser.mock.calls) {
+      expect(call[2]).toMatchObject({ allowWithoutCredential: true });
+    }
+  });
+
+  it("requests the credential-less lookup when resending", async () => {
+    shippingLinesRepo.findById.mockResolvedValue({
+      id: "sl-1",
+      userId: "user-1",
+      phoneNumber: "+251911223344",
+    });
+
+    await service.resendActivation("sl-1", ResetChannel.Email);
+
+    expect(customerResetService.sendResetLinkToUser).toHaveBeenCalledWith(
+      "user-1",
+      ResetChannel.Email,
+      expect.objectContaining({ allowWithoutCredential: true }),
+    );
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.service.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.service.ts
new file mode 100644
index 000000000..16b2836e1
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.service.ts
@@ -0,0 +1,223 @@
+import {
+  BadRequestException,
+  ConflictException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import {
+  EUserStatus,
+  EUserType,
+} from "@tria-plc/api-common/utils/enums/user.enum";
+// Subpath import (not the package root) so ts-jest can resolve it when this
+// file lands in a spec's compile graph — same reason as backoffice.service.ts.
+import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
+import { DataSource, Repository } from "typeorm";
+
+import { CustomerResetService } from "../auth/customer-reset.service";
+import { ResetChannel } from "../auth/dto/forgot-password.dto";
+import { isDomesticPhone } from "../otp/otp.service";
+import { CreateShippingLineDto } from "./dto/create-shipping-line.dto";
+import { ShippingLineCompany } from "./entities/shipping-line-company.entity";
+import { ShippingLineCompaniesRepository } from "./shipping-line-companies.repository";
+
+export interface RegisteredShippingLine {
+  shippingLine: ShippingLineCompany;
+  /** Masked destination of the activation link, or null if none was sent. */
+  activationSentTo: string | null;
+  activationChannel: ResetChannel | null;
+}
+
+@Injectable()
+export class ShippingLineCompaniesService {
+  private readonly logger = new Logger(ShippingLineCompaniesService.name);
+
+  constructor(
+    private readonly shippingLineCompaniesRepo: ShippingLineCompaniesRepository,
+    @InjectRepository(User)
+    private readonly userRepository: Repository<User>,
+    private readonly customerResetService: CustomerResetService,
+    private readonly dataSource: DataSource,
+  ) {}
+
+  /**
+   * Register a shipping line: create its IAM account and its record together,
+   * then send an activation link so the line sets its own password.
+   *
+   * The IAM mechanics follow `BackofficeService.createOrganizationUser` — same
+   * entities, same transaction shape — with one deliberate difference: no
+   * `UserCredential` row is written and `hasSetPassword` stays false. Staff
+   * creating an employee seed a shared default password; a shipping line must
+   * come through the activation link instead, so no credential exists until the
+   * line sets one.
+   */
+  async register(dto: CreateShippingLineDto): Promise<RegisteredShippingLine> {
+    const email = dto.email.trim().toLowerCase();
+    const username = (dto.username?.trim() || email).toLowerCase();
+    const phoneNumber = dto.phoneNumber?.trim() || undefined;
+    const scacCode = dto.scacCode?.trim().toUpperCase();
+
+    if (await this.shippingLineCompaniesRepo.existsByEmail(email)) {
+      throw new ConflictException(
+        `A shipping line with email ${email} already exists`,
+      );
+    }
+
+    if (scacCode && (await this.shippingLineCompaniesRepo.existsByScac(scacCode))) {
+      throw new ConflictException(
+        `A shipping line with SCAC ${scacCode} already exists`,
+      );
+    }
+
+    // An existing IAM account means these credentials already belong to a
+    // customer or an employee. Reusing it would let one login resolve to two
+    // different account kinds, so this is refused rather than merged — unlike
+    // employee creation, which legitimately re-uses a person's existing user.
+    const existingUser = await this.userRepository.findOne({
+      where: [{ email }, { username }],
+      select: { id: true },
+    });
+    if (existingUser) {
+      throw new ConflictException(
+        "email_or_username_already_in_use",
+      );
+    }
+
+    const shippingLine = await this.dataSource.transaction(async (manager) => {
+      const userRepo = manager.getRepository(User);
+      const user = await userRepo.save(
+        userRepo.create({
+          email,
+          username,
+          phoneNumber,
+          name: { en: dto.name.trim() },
+          userType: EUserType.INDIVIDUAL,
+          isActive: true,
+          // No credential row is written: the account has no password until the
+          // activation link is used. `hasSetPassword` must stay false or the
+          // portal treats the account as ready to sign in with a password that
+          // does not exist.
+          hasSetPassword: false,
+          status: EUserStatus.ACCEPTED,
+        }),
+      );
+
+      return this.shippingLineCompaniesRepo.createInTransaction(manager, {
+        userId: user.id as string,
+        name: dto.name.trim(),
+        email,
+        phoneNumber: phoneNumber ?? null,
+        scacCode: scacCode ?? null,
+        imoNumber: dto.imoNumber?.trim() || null,
+        bicCode: dto.bicCode?.trim() || null,
+      });
+    });
+
+    // Outside the transaction on purpose: a delivery failure must not roll back
+    // a registered line. The link is resendable, and the account is already
+    // valid without it.
+    const activation = await this.sendActivationLink(shippingLine);
+
+    return {
+      shippingLine,
+      activationSentTo: activation?.maskedTarget ?? null,
+      activationChannel: activation?.channel ?? null,
+    };
+  }
+
+  /**
+   * Send the activation link on registration.
+   *
+   * Email always goes out — it is required at registration and is the only
+   * channel guaranteed to reach a foreign-registered line. SMS is sent in
+   * addition when the number is domestic, since the gateway silently drops
+   * anything else (see `CustomerResetService`). Two links are two independent
+   * single-use tickets; whichever the line opens first works.
+   *
+   * Reports the email send, as that is the one that is always attempted.
+   */
+  async sendActivationLink(shippingLine: ShippingLineCompany) {
+    const scope = `shipping line ${shippingLine.id}`;
+
+    const emailed = await this.customerResetService.sendResetLinkToUser(
+      shippingLine.userId,
+      ResetChannel.Email,
+      { scope, allowWithoutCredential: true },
+    );
+
+    if (!emailed) {
+      this.logger.error(
+        `Activation email not sent for shipping line ${shippingLine.id} — no reachable address`,
+      );
+    }
+
+    if (shippingLine.phoneNumber && isDomesticPhone(shippingLine.phoneNumber)) {
+      const texted = await this.customerResetService.sendResetLinkToUser(
+        shippingLine.userId,
+        ResetChannel.Phone,
+        { scope, allowWithoutCredential: true },
+      );
+      if (!texted) {
+        this.logger.warn(
+          `Activation SMS not sent for shipping line ${shippingLine.id}`,
+        );
+      }
+    }
+
+    return emailed;
+  }
+
+  async resendActivation(id: string, channel: ResetChannel) {
+    const shippingLine = await this.shippingLineCompaniesRepo.findById(id);
+    if (!shippingLine) {
+      throw new NotFoundException("Shipping line not found");
+    }
+
+    if (
+      channel === ResetChannel.Phone &&
+      (!shippingLine.phoneNumber || !isDomesticPhone(shippingLine.phoneNumber))
+    ) {
+      throw new BadRequestException(
+        "This shipping line has no domestic phone number — the SMS gateway cannot reach it",
+      );
+    }
+
+    const sent = await this.customerResetService.sendResetLinkToUser(
+      shippingLine.userId,
+      channel,
+      { scope: `shipping line ${shippingLine.id}`, allowWithoutCredential: true },
+    );
+
+    if (!sent) {
+      throw new NotFoundException(
+        `No active account with ${
+          channel === ResetChannel.Email ? "an email address" : "a phone number"
+        } for this shipping line`,
+      );
+    }
+
+    return sent;
+  }
+
+  async findById(id: string): Promise<ShippingLineCompany> {
+    const shippingLine = await this.shippingLineCompaniesRepo.findById(id);
+    if (!shippingLine) {
+      throw new NotFoundException("Shipping line not found");
+    }
+    return shippingLine;
+  }
+
+  /** The shipping line signed in as `userId`, or null for any other account. */
+  findByUserId(userId: string): Promise<ShippingLineCompany | null> {
+    return this.shippingLineCompaniesRepo.findByUserId(userId);
+  }
+
+  async list(page = 1, limit = 20) {
+    const [items, total] = await this.shippingLineCompaniesRepo.findAllPaginated(
+      (page - 1) * limit,
+      limit,
+    );
+    return { items, total, page, limit };
+  }
+}
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index f0b719d63..6c891d830 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -450,6 +450,30 @@ export const CUSTOMER_PERMISSIONS: FreightPermissionSeed[] = [
   ),
 ];
 
+// C2. Shipping lines — carriers registered by staff (no self-signup).
+export const SHIPPING_LINE_PERMISSIONS: FreightPermissionSeed[] = [
+  perm(
+    "d1a00002-0001-4000-8000-000000000001",
+    "edr_freight_app:shipping_lines:view",
+    "View shipping lines",
+  ),
+  perm(
+    "d1a00002-0001-4000-8000-000000000002",
+    "edr_freight_app:shipping_lines:create",
+    "Register shipping line",
+  ),
+  perm(
+    "d1a00002-0001-4000-8000-000000000003",
+    "edr_freight_app:shipping_lines:update",
+    "Update shipping line",
+  ),
+  perm(
+    "d1a00002-0001-4000-8000-000000000004",
+    "edr_freight_app:shipping_lines:reset-password",
+    "Resend shipping line activation link",
+  ),
+];
+
 // D. Finance — payments + invoices
 export const FINANCE_PERMISSIONS: FreightPermissionSeed[] = [
   perm(
@@ -1493,6 +1517,7 @@ export const NOTIFICATION_PERMISSIONS: FreightPermissionSeed[] = [
 
 export const ADVANCED_BACKOFFICE_PERMISSIONS: FreightPermissionSeed[] = [
   ...CUSTOMER_PERMISSIONS,
+  ...SHIPPING_LINE_PERMISSIONS,
   ...FINANCE_PERMISSIONS,
   ...MILE_PERMISSIONS,
   ...FLEET_RAIL_PERMISSIONS,
@@ -1699,6 +1724,12 @@ export const FREIGHT_PERMS = {
     // Notification selector, not a route guard — see NOTIFICATION_PERMISSIONS.
     getNotification: "edr_freight_app:customers:get_notification",
   },
+  shippingLines: {
+    view: "edr_freight_app:shipping_lines:view",
+    create: "edr_freight_app:shipping_lines:create",
+    update: "edr_freight_app:shipping_lines:update",
+    resetPassword: "edr_freight_app:shipping_lines:reset-password",
+  },
   payments: {
     view: "edr_freight_app:payments:view",
   },
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index 64f91da72..58bca3738 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -34,6 +34,7 @@ import DocumentClearanceDetailPage from "./pages/bookings/DocumentClearanceDetai
 import DocumentClearanceListPage from "./pages/bookings/DocumentClearanceListPage";
 import CustomerDetailPage from "./pages/customers/CustomerDetailPage";
 import CustomersPage from "./pages/customers/CustomersPage";
+import ShippingLineCompaniesPage from "./pages/shipping-lines/ShippingLineCompaniesPage";
 import InvoiceDetailPage from "./pages/invoices/InvoiceDetailPage";
 import InvoicesPage from "./pages/invoices/InvoicesPage";
 import UsdPaymentsPage from "./pages/invoices/UsdPaymentsPage";
@@ -242,6 +243,14 @@ const App = () => {
             </RequirePermission>
           }
         />
+        <Route
+          path="shipping-lines"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.shippingLines.view}>
+              <ShippingLineCompaniesPage />
+            </RequirePermission>
+          }
+        />
         <Route
           path="invoices"
           element={
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 95608b6db..bf82a87d1 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -73,6 +73,12 @@ export const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[]
         icon: <Building2 />,
         permission: FREIGHT_PERMS.customers.view,
       },
+      {
+        label: "Shipping Lines",
+        href: "/dashboard/shipping-lines",
+        icon: <Ship />,
+        permission: FREIGHT_PERMS.shippingLines.view,
+      },
       {
         label: "Contracts",
         href: "/dashboard/contract-requests",
diff --git a/apps/edr-freight-web/backoffice/src/components/shipping-lines/ResendActivationAction.tsx b/apps/edr-freight-web/backoffice/src/components/shipping-lines/ResendActivationAction.tsx
new file mode 100644
index 000000000..ae271a57b
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/shipping-lines/ResendActivationAction.tsx
@@ -0,0 +1,168 @@
+import {
+  ActionIcon,
+  Alert,
+  Button,
+  Modal,
+  Radio,
+  Stack,
+  Text,
+  Tooltip,
+} from "@mantine/core";
+import { useMutation } from "@tanstack/react-query";
+import { Send } from "lucide-react";
+import { useState } from "react";
+
+import { useAuth } from "@/auth/useAuth";
+import { useToast } from "@/hooks/use-toast";
+import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
+import { api } from "@/services/api";
+import type {
+  ResetChannel,
+  ShippingLineCompany,
+} from "@/types/shippingLineCompany";
+
+/**
+ * Whether the SMS gateway can actually reach this number.
+ *
+ * The carrier integration is domestic-only: anything else is queued and
+ * silently lost, so a foreign number counts as unavailable rather than as a
+ * send that quietly fails. Mirrors `isDomesticPhone` in the API's otp.service.
+ */
+function isDomesticPhone(rawPhone: string): boolean {
+  const digits = rawPhone.trim().replace(/[^\d+]/g, "");
+  const normalized = digits.startsWith("+")
+    ? digits
+    : /^251\d{9}$/.test(digits)
+      ? `+${digits}`
+      : /^9\d{8}$|^7\d{8}$/.test(digits.replace(/^0+/, ""))
+        ? `+251${digits.replace(/^0+/, "")}`
+        : digits;
+  return /^\+2519\d{8}$/.test(normalized);
+}
+
+export interface ResendActivationActionProps {
+  shippingLine: Pick<ShippingLineCompany, "id" | "name" | "email" | "phoneNumber">;
+}
+
+/**
+ * Resend a shipping line's activation link.
+ *
+ * The same single-use link registration sends: the carrier opens it and picks
+ * their own password, so no credential is ever shown to or handled by staff.
+ * Needed whenever the original send failed, expired (24h), or never arrived.
+ */
+export default function ResendActivationAction({
+  shippingLine,
+}: ResendActivationActionProps) {
+  const { user } = useAuth();
+  const { toast } = useToast();
+  const [opened, setOpened] = useState(false);
+  const [channel, setChannel] = useState<ResetChannel>("email");
+
+  const allowed = hasPermission(user, FREIGHT_PERMS.shippingLines.resetPassword);
+
+  const { mutate, isPending } = useMutation(
+    api.shippingLineCompanies.resendActivation.mutationOptions({
+      onSuccess: (result) => {
+        setOpened(false);
+        toast({
+          title: "Activation link sent",
+          description: `The shipping line can set their password using the link sent to ${result.maskedTarget}. It expires in 24 hours.`,
+        });
+      },
+      onError: (error) => {
+        toast({
+          title: "Could not send activation link",
+          description: error.message,
+          variant: "destructive",
+        });
+      },
+    }),
+  );
+
+  if (!allowed) return null;
+
+  const phoneUsable =
+    !!shippingLine.phoneNumber && isDomesticPhone(shippingLine.phoneNumber);
+  const channelMissing = channel === "phone" && !phoneUsable;
+
+  return (
+    <>
+      <Tooltip label="Resend activation link" withArrow>
+        <ActionIcon
+          variant="subtle"
+          color="gray"
+          aria-label={`Resend activation link to ${shippingLine.name}`}
+          onClick={(event) => {
+            // The row itself is not clickable today, but stop here anyway so
+            // adding a detail-page navigation later cannot swallow this click.
+            event.stopPropagation();
+            setOpened(true);
+          }}
+        >
+          <Send size={16} />
+        </ActionIcon>
+      </Tooltip>
+
+      <Modal
+        opened={opened}
+        onClose={() => setOpened(false)}
+        title="Resend activation link"
+        centered
+      >
+        <Stack gap="md">
+          <Text size="sm" c="dimmed">
+            We&apos;ll send a single-use link to {shippingLine.name}. They choose
+            their own password — you will not see it. The link expires in 24
+            hours, and sending a new one invalidates nothing they haven&apos;t
+            already used.
+          </Text>
+
+          <Radio.Group
+            value={channel}
+            onChange={(v) => setChannel(v as ResetChannel)}
+            label="Send the link via"
+          >
+            <Stack gap="xs" mt="xs">
+              <Radio
+                value="email"
+                label="Email"
+                description={shippingLine.email}
+              />
+              <Radio
+                value="phone"
+                label="SMS"
+                disabled={!phoneUsable}
+                description={
+                  !shippingLine.phoneNumber
+                    ? "No phone number on this account"
+                    : !phoneUsable
+                      ? `${shippingLine.phoneNumber} — foreign number, SMS unavailable; use email`
+                      : shippingLine.phoneNumber
+                }
+              />
+            </Stack>
+          </Radio.Group>
+
+          {channelMissing ? (
+            <Alert color="yellow" variant="light" p="sm">
+              <Text size="sm">
+                This account has no number the SMS gateway can reach. Send the
+                link by email instead.
+              </Text>
+            </Alert>
+          ) : null}
+
+          <Button
+            color="edr-green"
+            loading={isPending}
+            disabled={channelMissing}
+            onClick={() => mutate({ id: shippingLine.id, channel })}
+          >
+            Send activation link
+          </Button>
+        </Stack>
+      </Modal>
+    </>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
index b681a2909..f42702826 100644
--- a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
@@ -28,6 +28,14 @@ export const QUERY_KEYS = {
     byCode: (code: string) => ["dropdown-settings", "by-code", code] as const,
   },
 
+  SHIPPING_LINE_COMPANIES: {
+    ROOT: ["shipping-line-companies"] as const,
+    list: (page: number, limit: number) =>
+      ["shipping-line-companies", "list", page, limit] as const,
+    byId: (id: string) =>
+      ["shipping-line-companies", "detail", id] as const,
+  },
+
   CUSTOMERS: {
     ROOT: ["customers"] as const,
     stats: ["customers", "stats"] as const,
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index d3566645e..f9bd29feb 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -77,6 +77,17 @@ export const URL_CONSTANTS = {
     BOOKINGS: (id: string | number) => `/customers/${id}/bookings`,
   },
 
+  /**
+   * Carriers with a portal login. Distinct from `/shipping-lines`, which is the
+   * rule-engine's pricing lookup list (a code/label bookings reference).
+   */
+  SHIPPING_LINE_COMPANIES: {
+    BASE: "/shipping-line-companies",
+    BY_ID: (id: string) => `/shipping-line-companies/${id}`,
+    RESEND_ACTIVATION: (id: string) =>
+      `/shipping-line-companies/${id}/resend-activation`,
+  },
+
   COMPANIES: {
     BASE: "/companies",
     STATS: "/companies/stats",
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index c69aa5d1b..ade07a511 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -123,6 +123,12 @@ export const FREIGHT_PERMS = {
     verify: "edr_freight_app:customers:verify",
     resetPassword: "edr_freight_app:customers:reset-password",
   },
+  shippingLines: {
+    view: "edr_freight_app:shipping_lines:view",
+    create: "edr_freight_app:shipping_lines:create",
+    update: "edr_freight_app:shipping_lines:update",
+    resetPassword: "edr_freight_app:shipping_lines:reset-password",
+  },
   payments: {
     view: "edr_freight_app:payments:view",
   },
diff --git a/apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCompaniesPage.tsx b/apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCompaniesPage.tsx
new file mode 100644
index 000000000..d8e0bb0d6
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCompaniesPage.tsx
@@ -0,0 +1,405 @@
+import {
+  Alert,
+  Badge,
+  Box,
+  Button,
+  Card,
+  Group,
+  Modal,
+  Stack,
+  Text,
+  TextInput,
+} from "@mantine/core";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { Info, Mail, Phone, Plus, Ship } from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { useAuth } from "@/auth/useAuth";
+import { PageContainer, PageHeader } from "@/components/page";
+import ResendActivationAction from "@/components/shipping-lines/ResendActivationAction";
+import { useToast } from "@/hooks/use-toast";
+import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
+import { api } from "@/services/api";
+import type { ShippingLineCompany } from "@/types/shippingLineCompany";
+import {
+  DataTable,
+  DataTableFooter,
+  usePagination,
+  type ColumnDef,
+} from "@edr/ui-common";
+
+/** SCAC is 2-4 letters; the API enforces the same rule. */
+const SCAC_PATTERN = /^[A-Za-z]{2,4}$/;
+
+interface FormValues {
+  name: string;
+  email: string;
+  phoneNumber: string;
+  scacCode: string;
+  imoNumber: string;
+  bicCode: string;
+}
+
+const EMPTY_FORM: FormValues = {
+  name: "",
+  email: "",
+  phoneNumber: "",
+  scacCode: "",
+  imoNumber: "",
+  bicCode: "",
+};
+
+const formatDate = (iso: string) =>
+  new Date(iso).toLocaleDateString(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+
+/**
+ * Shipping line companies — carriers with their own portal login.
+ *
+ * Registration is staff-only: there is no self-signup. Staff never set a
+ * password; the system emails (and texts, when the number is domestic) a
+ * single-use activation link that the carrier uses to choose their own.
+ */
+export default function ShippingLineCompaniesPage() {
+  const { user } = useAuth();
+  const { toast } = useToast();
+  const { pagination, setPagination } = usePagination({ pageSize: 10 });
+  const [registerOpen, setRegisterOpen] = useState(false);
+
+  const canCreate = hasPermission(user, FREIGHT_PERMS.shippingLines.create);
+
+  const { data, isLoading, isError, error, refetch } = useQuery(
+    api.shippingLineCompanies.list.queryOptions({
+      input: {
+        page: pagination.pageIndex + 1,
+        limit: pagination.pageSize,
+      },
+    }),
+  );
+
+  const rows = data?.items ?? [];
+  const total = data?.total ?? 0;
+  const pageCount = Math.max(1, Math.ceil(total / pagination.pageSize));
+
+  const [values, setValues] = useState<FormValues>(EMPTY_FORM);
+  const [touched, setTouched] = useState(false);
+
+  const setField = (field: keyof FormValues) => (value: string) =>
+    setValues((prev) => ({ ...prev, [field]: value }));
+
+  // Mirrors the API's own validation, so the obvious mistakes are caught before
+  // a round trip. The server still enforces all of it.
+  const errors = {
+    name: values.name.trim() ? null : "Company name is required",
+    // Required, unlike a customer's: the activation link is sent here, so an
+    // account without one could never be signed in to.
+    email: /^\S+@\S+\.\S+$/.test(values.email.trim())
+      ? null
+      : "A valid email is required",
+    scacCode:
+      !values.scacCode.trim() || SCAC_PATTERN.test(values.scacCode.trim())
+        ? null
+        : "SCAC must be 2-4 letters",
+  };
+  const isValid = !errors.name && !errors.email && !errors.scacCode;
+
+  const closeRegister = () => {
+    setRegisterOpen(false);
+    setValues(EMPTY_FORM);
+    setTouched(false);
+  };
+
+  const { mutate: register, isPending: isRegistering } = useMutation(
+    api.shippingLineCompanies.register.mutationOptions({
+      onSuccess: (result) => {
+        closeRegister();
+        toast({
+          title: "Shipping line registered",
+          description: result.activationSentTo
+            ? `An activation link was sent to ${result.activationSentTo}. It expires in 24 hours.`
+            : // The account exists and is valid — only delivery failed, and the
+              // link can be resent, so this is a warning rather than an error.
+              "The account was created, but the activation link could not be sent. Use “Resend activation” to try again.",
+          variant: result.activationSentTo ? undefined : "destructive",
+        });
+      },
+      onError: (err) => {
+        toast({
+          title: "Could not register shipping line",
+          description: err.message,
+          variant: "destructive",
+        });
+      },
+    }),
+  );
+
+  const columns: ColumnDef<ShippingLineCompany>[] = useMemo(
+    () => [
+      {
+        id: "name",
+        header: "Shipping line",
+        cell: ({ row }) => {
+          const sl = row.original;
+          return (
+            <Group gap="sm" wrap="nowrap">
+              <Box
+                className="flex size-9 shrink-0 items-center justify-center rounded-lg"
+                style={{
+                  background: "var(--mantine-color-edr-green-1)",
+                  color: "var(--mantine-color-edr-green-7)",
+                }}
+              >
+                <Ship size={18} strokeWidth={1.9} />
+              </Box>
+              <div style={{ minWidth: 0 }}>
+                <Text fw={600} c="edr-text" truncate>
+                  {sl.name}
+                </Text>
+                {sl.scacCode ? (
+                  <Text size="xs" c="dimmed">
+                    SCAC {sl.scacCode}
+                  </Text>
+                ) : null}
+              </div>
+            </Group>
+          );
+        },
+      },
+      {
+        id: "contact",
+        header: "Contact",
+        cell: ({ row }) => {
+          const sl = row.original;
+          return (
+            <Stack gap={2}>
+              <Group gap={6} wrap="nowrap">
+                <Mail size={13} className="shrink-0 text-gray-400" />
+                <Text size="sm" truncate>
+                  {sl.email}
+                </Text>
+              </Group>
+              {sl.phoneNumber ? (
+                <Group gap={6} wrap="nowrap">
+                  <Phone size={13} className="shrink-0 text-gray-400" />
+                  <Text size="sm" c="dimmed">
+                    {sl.phoneNumber}
+                  </Text>
+                </Group>
+              ) : null}
+            </Stack>
+          );
+        },
+      },
+      {
+        id: "identifiers",
+        header: "Identifiers",
+        cell: ({ row }) => {
+          const { imoNumber, bicCode } = row.original;
+          if (!imoNumber && !bicCode) {
+            return (
+              <Text size="sm" c="dimmed">
+                —
+              </Text>
+            );
+          }
+          return (
+            <Stack gap={2}>
+              {imoNumber ? <Text size="sm">IMO {imoNumber}</Text> : null}
+              {bicCode ? (
+                <Text size="sm" c="dimmed">
+                  BIC {bicCode}
+                </Text>
+              ) : null}
+            </Stack>
+          );
+        },
+      },
+      {
+        id: "status",
+        header: "Status",
+        cell: ({ row }) => (
+          <Badge
+            variant="light"
+            color={row.original.status === "active" ? "green" : "red"}
+          >
+            {row.original.status === "active" ? "Active" : "Suspended"}
+          </Badge>
+        ),
+      },
+      {
+        id: "createdAt",
+        header: "Registered",
+        cell: ({ row }) => (
+          <Text size="sm" c="dimmed">
+            {formatDate(row.original.createdAt)}
+          </Text>
+        ),
+      },
+      {
+        id: "actions",
+        header: "",
+        cell: ({ row }) => (
+          <Group gap={4} justify="flex-end" wrap="nowrap">
+            <ResendActivationAction shippingLine={row.original} />
+          </Group>
+        ),
+      },
+    ],
+    [],
+  );
+
+  return (
+    <PageContainer>
+      <Stack gap="lg">
+        <PageHeader
+          title="Shipping Lines"
+          subtitle="Carriers with their own portal access. Registered by staff — there is no self-signup."
+          action={
+            canCreate ? (
+              <Button
+                leftSection={<Plus size={16} />}
+                onClick={() => setRegisterOpen(true)}
+              >
+                Register shipping line
+              </Button>
+            ) : null
+          }
+        />
+
+        <Card withBorder padding={0} radius="md">
+          <DataTable
+            columns={columns}
+            data={rows}
+            status={isLoading ? "loading" : isError ? "error" : "success"}
+            emptyMessage="No shipping lines registered yet."
+            error={
+              isError
+                ? {
+                    message: error?.message ?? "Failed to load shipping lines.",
+                    onRetry: () => void refetch(),
+                  }
+                : undefined
+            }
+            pagination={{
+              pageIndex: pagination.pageIndex,
+              pageSize: pagination.pageSize,
+              pageCount,
+              totalCount: total,
+            }}
+            tableOptions={{
+              state: { pagination },
+              onPaginationChange: setPagination,
+              manualPagination: true,
+              pageCount,
+            }}
+            containerClassName="border-0 shadow-none bg-transparent"
+            footer={DataTableFooter}
+          />
+        </Card>
+      </Stack>
+
+      <Modal
+        opened={registerOpen}
+        onClose={closeRegister}
+        title="Register shipping line"
+        centered
+      >
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            setTouched(true);
+            if (!isValid) return;
+            register({
+              name: values.name.trim(),
+              email: values.email.trim(),
+              phoneNumber: values.phoneNumber.trim() || undefined,
+              scacCode: values.scacCode.trim() || undefined,
+              imoNumber: values.imoNumber.trim() || undefined,
+              bicCode: values.bicCode.trim() || undefined,
+            });
+          }}
+        >
+          <Stack gap="md">
+            <Alert
+              icon={<Info size={16} />}
+              color="blue"
+              variant="light"
+              p="sm"
+            >
+              <Text size="sm">
+                No password is set here. The shipping line receives a single-use
+                activation link and chooses their own.
+              </Text>
+            </Alert>
+
+            <TextInput
+              label="Company name"
+              placeholder="Ethiopian Shipping Lines"
+              withAsterisk
+              value={values.name}
+              onChange={(e) => setField("name")(e.currentTarget.value)}
+              error={touched ? errors.name : null}
+            />
+
+            <TextInput
+              label="Email"
+              placeholder="ops@example.com"
+              description="The activation link is sent here."
+              withAsterisk
+              value={values.email}
+              onChange={(e) => setField("email")(e.currentTarget.value)}
+              error={touched ? errors.email : null}
+            />
+
+            <TextInput
+              label="Phone number"
+              placeholder="+251911223344"
+              description="Ethiopian numbers also receive the link by SMS."
+              value={values.phoneNumber}
+              onChange={(e) => setField("phoneNumber")(e.currentTarget.value)}
+            />
+
+            <Group grow align="flex-start">
+              <TextInput
+                label="SCAC"
+                placeholder="ESLK"
+                value={values.scacCode}
+                onChange={(e) => setField("scacCode")(e.currentTarget.value)}
+                error={touched ? errors.scacCode : null}
+              />
+              <TextInput
+                label="IMO number"
+                placeholder="IMO9074729"
+                value={values.imoNumber}
+                onChange={(e) => setField("imoNumber")(e.currentTarget.value)}
+              />
+            </Group>
+
+            <TextInput
+              label="BIC code"
+              placeholder="ESLU"
+              value={values.bicCode}
+              onChange={(e) => setField("bicCode")(e.currentTarget.value)}
+            />
+
+            <Group justify="flex-end" gap="sm" mt="xs">
+              <Button
+                variant="default"
+                onClick={closeRegister}
+                disabled={isRegistering}
+              >
+                Cancel
+              </Button>
+              <Button type="submit" loading={isRegistering}>
+                Register &amp; send link
+              </Button>
+            </Group>
+          </Stack>
+        </form>
+      </Modal>
+    </PageContainer>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 6c9c69788..bbab2b253 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -44,6 +44,12 @@ import type {
   PaginatedOfflineUsdInvoices,
 } from "@/types/invoice";
 import type { IOverviewDashboard, OverviewRange } from "@/types/overview";
+import type {
+  CreateShippingLineCompanyDto,
+  PaginatedShippingLineCompanies,
+  RegisterShippingLineCompanyResult,
+  ShippingLineCompany,
+} from "@/types/shippingLineCompany";
 import {
   RuleEngineListResult,
   RuleEngineRecord,
@@ -150,6 +156,7 @@ import {
 import { containerTypesService } from "./container-types.service";
 import { containerService, type Container } from "./containerService";
 import { customersService } from "./customers.service";
+import { shippingLineCompaniesService } from "./shippingLineCompanies.service";
 import { eimsService } from "./eims.service";
 import type { EimsInvoiceStatusView, EimsVerifyResult } from "@/types/eims";
 import { invoicesService } from "./invoices.service";
@@ -2763,6 +2770,43 @@ export const api = {
     ),
   },
 
+  shippingLineCompanies: {
+    list: endpoint<{ page: number; limit: number }, PaginatedShippingLineCompanies>(
+      "shippingLineCompanies",
+      "list",
+      ({ page, limit }) => shippingLineCompaniesService.list(page, limit),
+      ({ page, limit }) => QUERY_KEYS.SHIPPING_LINE_COMPANIES.list(page, limit),
+    ),
+
+    getById: endpoint<{ id: string }, ShippingLineCompany>(
+      "shippingLineCompanies",
+      "getById",
+      ({ id }) => shippingLineCompaniesService.getById(id),
+      ({ id }) => QUERY_KEYS.SHIPPING_LINE_COMPANIES.byId(id),
+    ),
+
+    register: endpoint<
+      CreateShippingLineCompanyDto,
+      RegisterShippingLineCompanyResult
+    >(
+      "shippingLineCompanies",
+      "register",
+      (dto) => shippingLineCompaniesService.register(dto),
+      undefined,
+      () => [QUERY_KEYS.SHIPPING_LINE_COMPANIES.ROOT],
+    ),
+
+    resendActivation: endpoint<
+      { id: string; channel: ResetChannel },
+      ResetPasswordResult
+    >(
+      "shippingLineCompanies",
+      "resendActivation",
+      ({ id, channel }) =>
+        shippingLineCompaniesService.resendActivation(id, channel),
+    ),
+  },
+
   customers: {
     stats: endpoint<Record<string, never>, CompanyStats>(
       "customers",
diff --git a/apps/edr-freight-web/backoffice/src/services/shippingLineCompanies.service.ts b/apps/edr-freight-web/backoffice/src/services/shippingLineCompanies.service.ts
new file mode 100644
index 000000000..82e97140f
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/services/shippingLineCompanies.service.ts
@@ -0,0 +1,54 @@
+import { api as apiClient } from "@/auth/http";
+import { URL_CONSTANTS } from "@/constants/URLS";
+import type {
+  CreateShippingLineCompanyDto,
+  PaginatedShippingLineCompanies,
+  RegisterShippingLineCompanyResult,
+  ResetChannel,
+  ResetPasswordResult,
+  ShippingLineCompany,
+} from "@/types/shippingLineCompany";
+
+export const shippingLineCompaniesService = {
+  list(page = 1, limit = 20): Promise<PaginatedShippingLineCompanies> {
+    return apiClient
+      .get<PaginatedShippingLineCompanies>(
+        URL_CONSTANTS.SHIPPING_LINE_COMPANIES.BASE,
+        { params: { page, limit } },
+      )
+      .then((r) => r.data);
+  },
+
+  getById(id: string): Promise<ShippingLineCompany> {
+    return apiClient
+      .get<ShippingLineCompany>(URL_CONSTANTS.SHIPPING_LINE_COMPANIES.BY_ID(id))
+      .then((r) => r.data);
+  },
+
+  /**
+   * Creates the carrier's account and record, then sends an activation link.
+   * Staff never set or see a password — the line chooses its own from the link.
+   */
+  register(
+    dto: CreateShippingLineCompanyDto,
+  ): Promise<RegisterShippingLineCompanyResult> {
+    return apiClient
+      .post<RegisterShippingLineCompanyResult>(
+        URL_CONSTANTS.SHIPPING_LINE_COMPANIES.BASE,
+        dto,
+      )
+      .then((r) => r.data);
+  },
+
+  resendActivation(
+    id: string,
+    channel: ResetChannel,
+  ): Promise<ResetPasswordResult> {
+    return apiClient
+      .post<ResetPasswordResult>(
+        URL_CONSTANTS.SHIPPING_LINE_COMPANIES.RESEND_ACTIVATION(id),
+        { channel },
+      )
+      .then((r) => r.data);
+  },
+};
diff --git a/apps/edr-freight-web/backoffice/src/types/shippingLineCompany.ts b/apps/edr-freight-web/backoffice/src/types/shippingLineCompany.ts
new file mode 100644
index 000000000..9feb5c627
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/types/shippingLineCompany.ts
@@ -0,0 +1,50 @@
+import type { ResetChannel, ResetPasswordResult } from "./customer";
+
+export type ShippingLineStatus = "active" | "suspended";
+
+/**
+ * A carrier with its own portal login, registered by staff.
+ *
+ * Not to be confused with the rule-engine's `ShippingLine` (types/rule-engine):
+ * that is a pricing lookup — a code/label a booking points at — with no account
+ * and no login. This one is the account.
+ */
+export interface ShippingLineCompany {
+  id: string;
+  name: string;
+  email: string;
+  phoneNumber: string | null;
+  scacCode: string | null;
+  imoNumber: string | null;
+  bicCode: string | null;
+  status: ShippingLineStatus;
+  createdAt: string;
+}
+
+export interface CreateShippingLineCompanyDto {
+  name: string;
+  email: string;
+  phoneNumber?: string;
+  scacCode?: string;
+  imoNumber?: string;
+  bicCode?: string;
+  username?: string;
+}
+
+export interface RegisterShippingLineCompanyResult {
+  shippingLine: ShippingLineCompany;
+  /**
+   * Masked destination the activation link went to, or null when delivery
+   * failed. The registration still succeeded — the link is resendable.
+   */
+  activationSentTo: string | null;
+}
+
+export interface PaginatedShippingLineCompanies {
+  items: ShippingLineCompany[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+export type { ResetChannel, ResetPasswordResult };
diff --git a/apps/edr-freight-web/portal/src/App.tsx b/apps/edr-freight-web/portal/src/App.tsx
index a8f616976..e47ec9faf 100644
--- a/apps/edr-freight-web/portal/src/App.tsx
+++ b/apps/edr-freight-web/portal/src/App.tsx
@@ -59,6 +59,13 @@ import CheckPaymentPage from "./pages/payments/CheckPaymentPage";
 import PaymentFailurePage from "./pages/payments/PaymentFailurePage";
 import FaydaCallbackPage from "./pages/FaydaCallbackPage";
 import PaymentSuccessPage from "./pages/payments/PaymentSuccessPage";
+import {
+  ShippingLineBookingsPage,
+  ShippingLineHelpPage,
+  ShippingLineHomePage,
+  ShippingLineInvoicesPage,
+  ShippingLineSettingsPage,
+} from "./pages/shipping-line";
 import FaqPage from "./pages/support/FaqPage";
 import HelpPage from "./pages/support/HelpPage";
 import PrivacyPolicyPage from "./pages/support/PrivacyPolicyPage";
@@ -129,12 +136,20 @@ function isOnboardingAllowedPath(pathname: string): boolean {
  * can be dismissed to use those pages. Visiting any other page bounces back to
  * home and re-opens the wizard. New users (no company yet) are treated the same
  * as users who haven't completed onboarding.
+ *
+ * Shipping lines are exempt: staff register them with their details already
+ * captured, so there is nothing for them to onboard — they go straight to home.
  */
 function OnboardingGate() {
-  const { company, onboardingCompleted } = useAuth();
+  const { company, onboardingCompleted, isShippingLine } = useAuth();
   const location = useLocation();
 
-  const needsOnboarding = !company || !onboardingCompleted;
+  // Keyed off a positive shipping-line identification, never off "no company":
+  // that is also true mid-fetch and on error, which would let customers slip
+  // past onboarding whenever the request failed.
+  const needsOnboarding = isShippingLine
+    ? false
+    : !company || !onboardingCompleted;
   const allowedHere = isOnboardingAllowedPath(location.pathname);
 
   // Open by default while onboarding is pending (covers the login case).
@@ -176,21 +191,69 @@ function OnboardingGate() {
   );
 }
 
+/**
+ * Customer-only routes. A shipping line that lands on one (an old link, a
+ * bookmark, a hand-typed URL) is sent to its own home rather than shown a
+ * contract/company-shaped page that has no meaning for it.
+ */
+function RequireCustomer() {
+  const { isShippingLine, customerQuery } = useAuth();
+
+  // RequireCompany already awaits this query, but guard anyway: a refetch can
+  // flip `isPending` back on, and redirecting on a half-loaded account would
+  // throw the user into the wrong app.
+  if (customerQuery.isPending) return <FullScreenSpinner />;
+  if (isShippingLine) return <Navigate to="/shipping-line" replace />;
+  return <Outlet />;
+}
+
+/** The mirror of RequireCustomer: shipping-line routes, closed to customers. */
+function RequireShippingLine() {
+  const { isShippingLine, customerQuery } = useAuth();
+
+  if (customerQuery.isPending) return <FullScreenSpinner />;
+  if (!isShippingLine) return <Navigate to="/portal" replace />;
+  return <Outlet />;
+}
+
+/**
+ * Where a signed-in account belongs. Shipping lines and customers have separate
+ * apps, so every "you're already logged in" redirect has to pick between them.
+ * Waits for the company query: `isShippingLine` is false while that request is
+ * still in flight, which would land a shipping line on the customer home first.
+ */
+function useHomeRoute(): { ready: boolean; href: string } {
+  const { isShippingLine, customerQuery } = useAuth();
+
+  return {
+    ready: !customerQuery.isPending,
+    href: isShippingLine ? "/shipping-line" : "/portal",
+  };
+}
+
 /** Keeps authenticated users off the login/signup pages. */
 function RedirectIfAuthed() {
   const { isPending, isAuthenticated } = useAuth();
+  const home = useHomeRoute();
 
   if (isPending) return <FullScreenSpinner />;
-  if (isAuthenticated) return <Navigate to="/portal" replace />;
+  if (isAuthenticated) {
+    if (!home.ready) return <FullScreenSpinner />;
+    return <Navigate to={home.href} replace />;
+  }
   return <Outlet />;
 }
 
 /** Landing page for visitors; authenticated users go straight to the portal. */
 function LandingRoute() {
   const { isPending, isAuthenticated } = useAuth();
+  const home = useHomeRoute();
 
   if (isPending) return <FullScreenSpinner />;
-  if (isAuthenticated) return <Navigate to="/portal" replace />;
+  if (isAuthenticated) {
+    if (!home.ready) return <FullScreenSpinner />;
+    return <Navigate to={home.href} replace />;
+  }
   return <EDRFreightLandingPage />;
 }
 
@@ -230,6 +293,37 @@ const sidebarItems: SidebarItem[] = [
   },
 ];
 
+/**
+ * Sidebar for shipping lines. Intentionally its own list rather than a filtered
+ * view of `sidebarItems`: shipping lines have no contracts, and their Home /
+ * Bookings / Invoices pages are different pages at different routes.
+ */
+const shippingLineSidebarItems: SidebarItem[] = [
+  { label: "Home", href: "/shipping-line", icon: <Home size={18} /> },
+  {
+    label: "Bookings",
+    href: "/shipping-line/bookings",
+    icon: <Package size={18} />,
+  },
+  {
+    label: "Invoices",
+    href: "/shipping-line/invoices",
+    icon: <Receipt size={18} />,
+  },
+  {
+    section: "Account",
+    label: "Settings",
+    href: "/shipping-line/settings",
+    icon: <Settings size={18} />,
+  },
+  {
+    section: "Account",
+    label: "Help & Support",
+    href: "/shipping-line/help",
+    icon: <LifeBuoy size={18} />,
+  },
+];
+
 const App = () => {
   const navigate = useNavigate();
   const location = useLocation();
@@ -310,81 +404,134 @@ const App = () => {
 
         <Route element={<RequireAuth />}>
           <Route element={<RequireCompany />}>
-            <Route
-              element={
-                <AppLayout
-                  title="EDR Freight"
-                  sidebarItems={sidebarItems}
-                  activeHref={location.pathname}
-                  onNavigate={navigate}
-                  userName={displayName}
-                  userEmail={userEmail}
-                  companyProfiles={companyProfiles}
-                  companyType={companyType}
-                  onCreateProfile={createProfile}
-                  onReapplyProfile={reapplyProfile}
-                >
-                  <OnboardingGate />
-                </AppLayout>
-              }
-            >
-              <Route path="/portal" element={<MyPortalPage />} />
-              {/* Bookings are created against a contract, but the full list is
+            {/* Shipping-line app. Its own layout and sidebar, and its own pages
+              at their own routes — nothing here is shared with the customer
+              branch below beyond the shell component itself. Contracts are
+              absent by design: shipping lines request bookings directly. */}
+            <Route element={<RequireShippingLine />}>
+              <Route
+                element={
+                  <AppLayout
+                    title="EDR Freight"
+                    sidebarItems={shippingLineSidebarItems}
+                    activeHref={location.pathname}
+                    onNavigate={navigate}
+                    userName={displayName}
+                    userEmail={userEmail}
+                  >
+                    <Outlet />
+                  </AppLayout>
+                }
+              >
+                <Route
+                  path="/shipping-line"
+                  element={<ShippingLineHomePage />}
+                />
+                <Route
+                  path="/shipping-line/bookings"
+                  element={<ShippingLineBookingsPage />}
+                />
+                <Route
+                  path="/shipping-line/invoices"
+                  element={<ShippingLineInvoicesPage />}
+                />
+                <Route
+                  path="/shipping-line/settings"
+                  element={<ShippingLineSettingsPage />}
+                />
+                <Route
+                  path="/shipping-line/help"
+                  element={<ShippingLineHelpPage />}
+                />
+                {/* Old shared links land on the shipping-line equivalents. */}
+                <Route
+                  path="/settings"
+                  element={<Navigate to="/shipping-line/settings" replace />}
+                />
+              </Route>
+            </Route>
+
+            {/* Customer app — unchanged. */}
+            <Route element={<RequireCustomer />}>
+              <Route
+                element={
+                  <AppLayout
+                    title="EDR Freight"
+                    sidebarItems={sidebarItems}
+                    activeHref={location.pathname}
+                    onNavigate={navigate}
+                    userName={displayName}
+                    userEmail={userEmail}
+                    companyProfiles={companyProfiles}
+                    companyType={companyType}
+                    onCreateProfile={createProfile}
+                    onReapplyProfile={reapplyProfile}
+                  >
+                    <OnboardingGate />
+                  </AppLayout>
+                }
+              >
+                <Route path="/portal" element={<MyPortalPage />} />
+                {/* Bookings are created against a contract, but the full list is
                 browsable here. New-booking entry still routes via a contract. */}
-              <Route path="/bookings" element={<BookingsListPage />} />
-              <Route
-                path="/bookings/new"
-                element={<Navigate to="/contracts/new" replace />}
-              />
-              <Route path="/bookings/:id/edit" element={<EditBookingPage />} />
-              <Route path="/bookings/:id" element={<BookingDetailPage />} />
-              <Route
-                path="/bookings/:id/last-mile-confirm"
-                element={<LastMileConfirmPage />}
-              />
-              <Route
-                path="/bookings/:id/last-mile-contract"
-                element={<LastMileContractPage />}
-              />
-              <Route
-                path="/bookings/:id/contract"
-                element={<BookingContractPage />}
-              />
-              <Route path="/contracts" element={<ContractsList />} />
-              <Route path="/contracts/new" element={<NewContractPage />} />
-              <Route
-                path="/contracts/:id/edit"
-                element={<NewContractPage mode="edit" />}
-              />
-              <Route
-                path="/contracts/:id/shipment-requests/new"
-                element={<NewShipmentRequestPage />}
-              />
-              <Route
-                path="/contracts/:id/bookings/new"
-                element={<NewShipmentPage />}
-              />
-              {/* Completion of an initiated (bare) booking after per-booking
+                <Route path="/bookings" element={<BookingsListPage />} />
+                <Route
+                  path="/bookings/new"
+                  element={<Navigate to="/contracts/new" replace />}
+                />
+                <Route
+                  path="/bookings/:id/edit"
+                  element={<EditBookingPage />}
+                />
+                <Route path="/bookings/:id" element={<BookingDetailPage />} />
+                <Route
+                  path="/bookings/:id/last-mile-confirm"
+                  element={<LastMileConfirmPage />}
+                />
+                <Route
+                  path="/bookings/:id/last-mile-contract"
+                  element={<LastMileContractPage />}
+                />
+                <Route
+                  path="/bookings/:id/contract"
+                  element={<BookingContractPage />}
+                />
+                <Route path="/contracts" element={<ContractsList />} />
+                <Route path="/contracts/new" element={<NewContractPage />} />
+                <Route
+                  path="/contracts/:id/edit"
+                  element={<NewContractPage mode="edit" />}
+                />
+                <Route
+                  path="/contracts/:id/shipment-requests/new"
+                  element={<NewShipmentRequestPage />}
+                />
+                <Route
+                  path="/contracts/:id/bookings/new"
+                  element={<NewShipmentPage />}
+                />
+                {/* Completion of an initiated (bare) booking after per-booking
                 clearance — same form, submits to the complete endpoint. */}
-              <Route
-                path="/contracts/:id/bookings/:bookingId/complete"
-                element={<NewShipmentPage />}
-              />
-              <Route
-                path="/contracts/:id/view"
-                element={<ContractViewPage />}
-              />
-              <Route path="/contracts/:id" element={<ContractDetailPage />} />
-              <Route path="/tracking" element={<TrackingPage />} />
-              <Route path="/billing" element={<InvoicesList />} />
-              <Route path="/billing/:id" element={<InvoiceDetailPage />} />
-              {/* Profile was merged into Settings — keep old links working. */}
-              <Route
-                path="/profile"
-                element={<Navigate to="/settings" replace />}
-              />
-              <Route path="/signature" element={<MySignaturePage />} />
-              <Route path="/settings" element={<SettingsPage />} />
+                <Route
+                  path="/contracts/:id/bookings/:bookingId/complete"
+                  element={<NewShipmentPage />}
+                />
+                <Route
+                  path="/contracts/:id/view"
+                  element={<ContractViewPage />}
+                />
+                <Route path="/contracts/:id" element={<ContractDetailPage />} />
+                <Route path="/tracking" element={<TrackingPage />} />
+                <Route path="/billing" element={<InvoicesList />} />
+                <Route path="/billing/:id" element={<InvoiceDetailPage />} />
+                {/* Profile was merged into Settings — keep old links working. */}
+                <Route
+                  path="/profile"
+                  element={<Navigate to="/settings" replace />}
+                />
+                <Route path="/signature" element={<MySignaturePage />} />
+                <Route path="/settings" element={<SettingsPage />} />
+              </Route>
             </Route>
           </Route>
         </Route>
diff --git a/apps/edr-freight-web/portal/src/components/AppLayout.tsx b/apps/edr-freight-web/portal/src/components/AppLayout.tsx
index 126c1fe2c..c5c7a0c31 100644
--- a/apps/edr-freight-web/portal/src/components/AppLayout.tsx
+++ b/apps/edr-freight-web/portal/src/components/AppLayout.tsx
@@ -107,23 +107,20 @@ function getActivePage(
   activePath: string,
 ): { label: string } | null {
   const path = activePath.toLowerCase();
-  for (const item of items) {
-    if (
-      path === item.href.toLowerCase() ||
-      path.startsWith(item.href.toLowerCase() + "/")
-    ) {
-      return { label: item.label };
-    }
-    if (item.children) {
-      const childMatch = item.children.find(
-        (c) =>
-          path === c.href.toLowerCase() ||
-          path.startsWith(c.href.toLowerCase() + "/"),
-      );
-      if (childMatch) return { label: childMatch.label };
-    }
-  }
-  return null;
+
+  // Longest match wins, for the same reason as the sidebar's isItemActive:
+  // a nested href like "/shipping-line/bookings" must beat its "/shipping-line"
+  // parent, which a first-match-wins scan would report as "Home".
+  const best = items
+    .flatMap((item) => [item, ...(item.children ?? [])])
+    .filter(
+      (item) =>
+        path === item.href.toLowerCase() ||
+        path.startsWith(item.href.toLowerCase() + "/"),
+    )
+    .sort((a, b) => b.href.length - a.href.length)[0];
+
+  return best ? { label: best.label } : null;
 }
 
 const navClassNames = (active: boolean) => {
@@ -262,9 +259,19 @@ export function AppLayout({
   const serviceLabel = (m: ServiceType) => PROFILE_TYPE_LABELS[m] ?? m;
   const isSuspendedAppeal = reapplyStatus === "suspended";
 
+  // Longest matching href wins. A plain prefix test would light up every
+  // ancestor: with a "/shipping-line" home item alongside "/shipping-line/
+  // bookings", Home would stay highlighted on every page beneath it. Exact
+  // matches still win outright, so customer routes are unaffected — their
+  // sidebar hrefs are siblings, never nested inside one another.
+  const bestMatchHref = sidebarItems
+    .flatMap((item) => [item, ...(item.children ?? [])])
+    .map((item) => item.href.toLowerCase())
+    .filter((href) => activePath === href || activePath.startsWith(href + "/"))
+    .sort((a, b) => b.length - a.length)[0];
+
   const isItemActive = (item: SidebarItem) =>
-    activePath === item.href.toLowerCase() ||
-    activePath.startsWith(item.href.toLowerCase() + "/");
+    bestMatchHref === item.href.toLowerCase();
 
   return (
     <AppShell
@@ -371,7 +378,9 @@ export function AppLayout({
                           onClick={() =>
                             openServiceModal(p.type as ServiceType, p)
                           }
-                          leftSection={<RefreshCw size={15} strokeWidth={1.8} />}
+                          leftSection={
+                            <RefreshCw size={15} strokeWidth={1.8} />
+                          }
                         >
                           {serviceLabel(p.type as ServiceType)}
                         </Menu.Item>
@@ -893,7 +902,9 @@ export function AppLayout({
             </Alert>
           )}
           <FileInput
-            label={reapplyId ? "Business license (optional)" : "Business license"}
+            label={
+              reapplyId ? "Business license (optional)" : "Business license"
+            }
             multiple
             clearable
             accept="application/pdf,image/png,image/jpeg"
diff --git a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingResumeBanner.tsx b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingResumeBanner.tsx
index 27b9eec43..696f62484 100644
--- a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingResumeBanner.tsx
+++ b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingResumeBanner.tsx
@@ -162,7 +162,15 @@ export default function OnboardingResumeBanner({
  * Self-hides when there's nothing outstanding.
  */
 export function AccountReviewBanner() {
-  const { company, companyStatus, reviewStatus, reviewNote } = useAuth();
+  const { company, companyStatus, reviewStatus, reviewNote, isShippingLine } =
+    useAuth();
+
+  // Shipping lines have no company approval, no operational profiles and no
+  // profile-edit review — every branch below is about customer state they do
+  // not have. Bail explicitly rather than relying on each check happening to
+  // fall through.
+  if (isShippingLine) return null;
+
   const profiles = company?.company?.companyProfiles ?? [];
   const pending = profiles.filter((p) => p.status === "pending");
   const approved = profiles.filter((p) => p.status === "active");
diff --git a/apps/edr-freight-web/portal/src/hooks/useAuth.ts b/apps/edr-freight-web/portal/src/hooks/useAuth.ts
index 3573750a9..a6e647918 100644
--- a/apps/edr-freight-web/portal/src/hooks/useAuth.ts
+++ b/apps/edr-freight-web/portal/src/hooks/useAuth.ts
@@ -1,6 +1,12 @@
 import { api } from "@/services/api";
-import type { ProfileTypeValue } from "@/services/companies.service";
-import { companiesService } from "@/services/companies.service";
+import type {
+  CompanyInfoResponse,
+  ProfileTypeValue,
+} from "@/services/companies.service";
+import {
+  companiesService,
+  isShippingLineAccount,
+} from "@/services/companies.service";
 import type {
   LoginPayload,
   LoginResponse,
@@ -158,7 +164,21 @@ const useAuth = () => {
     }
   };
 
-  const companyInfo = isAuthenticated ? (companyQuery.data ?? null) : null;
+  const accountInfo = isAuthenticated ? (companyQuery.data ?? null) : null;
+
+  /**
+   * Shipping lines share the portal with customers but have no company, no
+   * external profile and no onboarding. Identified positively from the
+   * backend's discriminator — never from "company is missing", which is also
+   * true while the fetch is in flight or after it fails.
+   */
+  const isShippingLine = isShippingLineAccount(accountInfo);
+  const shippingLine = isShippingLine ? accountInfo : null;
+
+  // Every customer-shaped field below is null/empty for a shipping line.
+  const companyInfo = isShippingLine
+    ? null
+    : (accountInfo as CompanyInfoResponse | null);
   const companyType = companyInfo?.company?.type ?? null;
   const companyStatus = companyInfo?.company?.status ?? null;
   // A company can create bookings only once an admin has approved it (active).
@@ -259,8 +279,11 @@ const useAuth = () => {
     isPending,
     isAuthenticated,
     user: isAuthenticated ? (authQuery.data ?? null) : null,
-    company: isAuthenticated ? (companyQuery.data ?? null) : null,
-    customer: isAuthenticated ? (companyQuery.data ?? null) : null,
+    // The whole getInfo payload, not the `company` field within it (historical
+    // name). Null for a shipping line: consumers read `.company` / `.profile`
+    // off it, and a shipping line has neither.
+    company: companyInfo,
+    customer: companyInfo,
     canBook,
     hasActiveProfile,
     hasPendingProfile,
@@ -272,6 +295,8 @@ const useAuth = () => {
     isUnderReview,
     onboardingCompleted,
     onboardingStep,
+    isShippingLine,
+    shippingLine,
     createProfile,
     reapplyProfile,
     login,
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/LoginPage.tsx b/apps/edr-freight-web/portal/src/pages/accounts/LoginPage.tsx
index 7e8e512dd..746d1648c 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/LoginPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/LoginPage.tsx
@@ -1,6 +1,6 @@
 import { type FormEvent, useState } from "react";
 import { Alert, Button, PasswordInput, Stack, TextInput } from "@mantine/core";
-import { AlertCircle } from "lucide-react";
+import { AlertCircle, CheckCircle2 } from "lucide-react";
 import { Link, useLocation, useNavigate } from "react-router-dom";
 
 import useAuth from "@/hooks/useAuth";
@@ -19,6 +19,10 @@ export default function LoginPage() {
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
 
+  const passwordWasReset =
+    (location.state as { passwordReset?: boolean } | null)?.passwordReset ===
+    true;
+
   const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
     event.preventDefault();
     setError(null);
@@ -56,6 +60,21 @@ export default function LoginPage() {
         </div>
 
         <Stack gap="md">
+          {/*
+            Set by the reset flows on their way here. Without it the account
+            holder lands on a bare sign-in form with no sign the reset worked —
+            and the link is single-use, so there is no way back to check.
+          */}
+          {passwordWasReset ? (
+            <Alert
+              color="green"
+              variant="light"
+              icon={<CheckCircle2 size={18} />}
+            >
+              Your password has been updated. Sign in with your new password.
+            </Alert>
+          ) : null}
+
           <TextInput
             label="Email or Phone"
             placeholder="name@company.com or 09XXXXXXXX"
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/ResetPasswordLinkPage.tsx b/apps/edr-freight-web/portal/src/pages/accounts/ResetPasswordLinkPage.tsx
index 4776287ae..7b3bae7c9 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/ResetPasswordLinkPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/ResetPasswordLinkPage.tsx
@@ -1,6 +1,6 @@
 import { type FormEvent, useEffect, useState } from "react";
 import { Alert, Button, Loader, PasswordInput, Stack } from "@mantine/core";
-import { AlertCircle, KeyRound } from "lucide-react";
+import { AlertCircle, CheckCircle2, KeyRound, LogIn } from "lucide-react";
 import { Link, useNavigate, useSearchParams } from "react-router-dom";
 
 import AuthShell from "@/components/auth/AuthShell";
@@ -33,6 +33,7 @@ export default function ResetPasswordLinkPage() {
   const [confirmPassword, setConfirmPassword] = useState("");
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [succeeded, setSucceeded] = useState(false);
 
   useEffect(() => {
     if (!userId || !token) {
@@ -82,7 +83,12 @@ export default function ResetPasswordLinkPage() {
         newPassword: password,
         confirmPassword,
       });
-      navigate("/login", { replace: true, state: { passwordReset: true } });
+      // Confirm in place rather than bouncing to /login: the old redirect
+      // passed `passwordReset: true` in route state that no page ever read, so
+      // the account holder landed on a bare sign-in form with no sign the reset
+      // had worked — and the link is single-use, so there is no way back to
+      // check.
+      setSucceeded(true);
     } catch (err) {
       setError(extractApiError(err).message);
     } finally {
@@ -90,6 +96,58 @@ export default function ResetPasswordLinkPage() {
     }
   };
 
+  // Password set — the link is now spent, so this is the last thing the account
+  // holder sees. It replaces the whole form rather than sitting above it.
+  if (succeeded) {
+    return (
+      <AuthShell
+        tagline="Password updated"
+        taglineBody="Your EDR Freight account is ready to use."
+      >
+        <div className="flex w-full flex-col">
+          <div className="mb-1 flex justify-center">
+            <span className="flex h-14 w-14 items-center justify-center rounded-full bg-green-100 text-green-600">
+              <CheckCircle2 size={30} strokeWidth={2.2} />
+            </span>
+          </div>
+
+          <div className="mb-6 mt-4 space-y-2 text-center">
+            <h1 className="text-xl font-bold tracking-tight text-gray-900 sm:text-2xl">
+              You&apos;re all set
+            </h1>
+            <p className="text-sm leading-relaxed text-gray-500">
+              Your password has been updated
+              {account?.maskedIdentifier ? ` for ${account.maskedIdentifier}` : ""}.
+              Sign in with your new password to continue.
+            </p>
+          </div>
+
+          <Stack gap="md">
+            <Button
+              color="edr-green"
+              size="md"
+              fullWidth
+              leftSection={<LogIn size={18} />}
+              onClick={() =>
+                navigate("/login", {
+                  replace: true,
+                  state: { passwordReset: true },
+                })
+              }
+            >
+              Go to sign in
+            </Button>
+
+            <p className="text-center text-xs leading-relaxed text-gray-400">
+              For your security, this reset link has now been used and will not
+              work again.
+            </p>
+          </Stack>
+        </div>
+      </AuthShell>
+    );
+  }
+
   return (
     <AuthShell
       tagline="Set a new password"
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
new file mode 100644
index 000000000..e949e54fa
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
@@ -0,0 +1,17 @@
+import { Package } from "lucide-react";
+import ShippingLinePlaceholder from "./ShippingLinePlaceholder";
+
+/**
+ * Shipping-line bookings. Contracts do not apply to shipping lines, so a
+ * booking is requested directly here rather than being created against a
+ * contract the way the customer flow does it.
+ */
+export default function ShippingLineBookingsPage() {
+  return (
+    <ShippingLinePlaceholder
+      title="Bookings"
+      description="Request and track your booking requests."
+      icon={<Package size={28} className="text-slate-300" />}
+    />
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineHelpPage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineHelpPage.tsx
new file mode 100644
index 000000000..84b605345
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineHelpPage.tsx
@@ -0,0 +1,18 @@
+import { LifeBuoy } from "lucide-react";
+import ShippingLinePlaceholder from "./ShippingLinePlaceholder";
+
+/**
+ * Shipping-line help & support. Separate from the customer `/help` page, which
+ * is public (the auth screens link to it) and carries its own doc chrome; this
+ * one lives inside the shipping-line app layout and will hold guidance written
+ * for shipping lines.
+ */
+export default function ShippingLineHelpPage() {
+  return (
+    <ShippingLinePlaceholder
+      title="Help & Support"
+      description="Guides and support for shipping lines."
+      icon={<LifeBuoy size={28} className="text-slate-300" />}
+    />
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineHomePage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineHomePage.tsx
new file mode 100644
index 000000000..12a789ea7
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineHomePage.tsx
@@ -0,0 +1,17 @@
+import { Home } from "lucide-react";
+import ShippingLinePlaceholder from "./ShippingLinePlaceholder";
+
+/**
+ * Shipping-line home / dashboard. Deliberately separate from the customer
+ * dashboard (`MyPortalPage`): shipping lines have no company, no operational
+ * profiles and no contracts, so almost none of that page's data applies.
+ */
+export default function ShippingLineHomePage() {
+  return (
+    <ShippingLinePlaceholder
+      title="Home"
+      description="Overview of your shipping-line activity."
+      icon={<Home size={28} className="text-slate-300" />}
+    />
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineInvoicesPage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineInvoicesPage.tsx
new file mode 100644
index 000000000..8c0a4cb4a
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineInvoicesPage.tsx
@@ -0,0 +1,13 @@
+import { Receipt } from "lucide-react";
+import ShippingLinePlaceholder from "./ShippingLinePlaceholder";
+
+/** Shipping-line payments / invoices. */
+export default function ShippingLineInvoicesPage() {
+  return (
+    <ShippingLinePlaceholder
+      title="Payments"
+      description="Your invoices and payment history."
+      icon={<Receipt size={28} className="text-slate-300" />}
+    />
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLinePlaceholder.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLinePlaceholder.tsx
new file mode 100644
index 000000000..20d647474
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLinePlaceholder.tsx
@@ -0,0 +1,40 @@
+import { Card, Stack, Text, Title } from "@mantine/core";
+import type { ReactNode } from "react";
+
+export interface ShippingLinePlaceholderProps {
+  title: string;
+  description: string;
+  icon?: ReactNode;
+}
+
+/**
+ * Shell for the shipping-line pages while they are still being built out.
+ * Each page owns its own file so it can be filled in independently; this only
+ * supplies the shared empty-state chrome and is meant to be deleted from a page
+ * once that page has real content.
+ */
+export default function ShippingLinePlaceholder({
+  title,
+  description,
+  icon,
+}: ShippingLinePlaceholderProps) {
+  return (
+    <Stack gap="lg" p={{ base: 16, sm: 24, lg: 32 }}>
+      <Stack gap={4}>
+        <Title order={2}>{title}</Title>
+        <Text c="dimmed" size="sm">
+          {description}
+        </Text>
+      </Stack>
+
+      <Card withBorder radius="md" py={64}>
+        <Stack align="center" gap="xs">
+          {icon}
+          <Text c="dimmed" size="sm">
+            Nothing here yet — this page is still being built.
+          </Text>
+        </Stack>
+      </Card>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineSettingsPage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineSettingsPage.tsx
new file mode 100644
index 000000000..9e2081e58
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineSettingsPage.tsx
@@ -0,0 +1,17 @@
+import { Settings } from "lucide-react";
+import ShippingLinePlaceholder from "./ShippingLinePlaceholder";
+
+/**
+ * Shipping-line settings. Separate from the customer `SettingsPage`, which is
+ * built around company profiles, business licenses and contact-person review —
+ * none of which a shipping line has.
+ */
+export default function ShippingLineSettingsPage() {
+  return (
+    <ShippingLinePlaceholder
+      title="Settings"
+      description="Manage your account and preferences."
+      icon={<Settings size={28} className="text-slate-300" />}
+    />
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/index.ts b/apps/edr-freight-web/portal/src/pages/shipping-line/index.ts
new file mode 100644
index 000000000..cb679c8cd
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/index.ts
@@ -0,0 +1,5 @@
+export { default as ShippingLineHomePage } from "./ShippingLineHomePage";
+export { default as ShippingLineBookingsPage } from "./ShippingLineBookingsPage";
+export { default as ShippingLineInvoicesPage } from "./ShippingLineInvoicesPage";
+export { default as ShippingLineSettingsPage } from "./ShippingLineSettingsPage";
+export { default as ShippingLineHelpPage } from "./ShippingLineHelpPage";
diff --git a/apps/edr-freight-web/portal/src/services/companies.service.ts b/apps/edr-freight-web/portal/src/services/companies.service.ts
index 4c1b93713..eda9d7e3d 100644
--- a/apps/edr-freight-web/portal/src/services/companies.service.ts
+++ b/apps/edr-freight-web/portal/src/services/companies.service.ts
@@ -89,7 +89,18 @@ export interface CompanyProfileResponse {
   updatedAt: string;
 }
 
+/**
+ * Which kind of account is signed in.
+ *
+ * Read this instead of inferring from a missing `company`: a failed or
+ * in-flight company fetch also leaves `company` empty, and treating that as
+ * "shipping line" would skip onboarding for customers whenever the request
+ * failed. Absent (older responses) means `customer`.
+ */
+export type AccountKind = "customer" | "shipping_line";
+
 export interface CompanyInfoResponse {
+  accountKind?: AccountKind;
   profile: ExternalProfileResponse;
   company: CompanyResponse;
   /**
@@ -104,6 +115,30 @@ export interface CompanyInfoResponse {
   } | null;
 }
 
+/**
+ * A signed-in shipping line. It has no company, no external profile and no
+ * onboarding — the carrier record itself is the account.
+ */
+export interface ShippingLineInfoResponse {
+  accountKind: "shipping_line";
+  id: string;
+  name: string;
+  email: string;
+  phoneNumber: string | null;
+  scacCode: string | null;
+  status: string;
+  company: null;
+  profile: null;
+  review: null;
+}
+
+/** `GET /companies/getInfo` serves both portal audiences. */
+export type AccountInfoResponse = CompanyInfoResponse | ShippingLineInfoResponse;
+
+export const isShippingLineAccount = (
+  info: AccountInfoResponse | null | undefined,
+): info is ShippingLineInfoResponse => info?.accountKind === "shipping_line";
+
 /** A staged profile-edit review request (portal view). */
 export interface ChangeRequestResponse {
   id: string;
@@ -249,9 +284,9 @@ export interface DashboardSummary {
 }
 
 export const companiesService = {
-  getInfo: async (): Promise<CompanyInfoResponse | null> => {
+  getInfo: async (): Promise<AccountInfoResponse | null> => {
     try {
-      const response = await client.get<ApiResponse<CompanyInfoResponse>>(
+      const response = await client.get<ApiResponse<AccountInfoResponse>>(
         URL_CONSTANTS.COMPANIES_API.GET_INFO,
       );
       return unwrap(response.data);

From d261d6ea7c8b5aaa0e75fefe283647b0a2190e6c Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 06:54:54 +0000
Subject: [PATCH 061/174] style: inter module integration

---
 .../src/modules/billing/billing.service.ts    |   27 +
 .../modules/bookings/bookings.repository.ts   |    6 +
 .../src/modules/bookings/bookings.service.ts  |    1 +
 .../bookings/dto/filter-booking.dto.ts        |    5 +
 .../bookings/detail/BookingCompanyCard.tsx    |   74 +-
 .../bookings/detail/BookingContractCard.tsx   |   49 +
 .../detail/BookingContractSummaryCard.tsx     |   27 -
 .../detail/BookingMileServicesCard.tsx        |   39 +-
 .../bookings/detail/BookingRequestHero.tsx    |  258 ----
 .../src/components/bookings/detail/index.ts   |    3 +-
 .../contracts/BookingRequestStatusBadge.tsx   |   16 +
 .../detail/ContractDetailTabCards.tsx         |   31 +-
 .../contracts/detail/RequestDetailCards.tsx   |  138 +--
 .../customers/ResetPasswordAction.tsx         |  151 ---
 .../src/components/customers/index.ts         |    4 -
 .../src/components/detail/EntityLink.tsx      |   63 +
 .../src/components/detail/Field.tsx           |   59 +
 .../components/detail/LinkedEntityCard.tsx    |   67 ++
 .../backoffice/src/components/detail/index.ts |   14 +
 .../src/components/page/PageHeader.tsx        |    2 +-
 .../trainScheduling/LegCapacityPanel.tsx      |   13 +-
 .../ScheduleWorkspacePanel.tsx                |   21 +-
 .../trainScheduling/WagonPlanGrid.tsx         |   10 +-
 .../backoffice/src/constants/QUERY_KEYS.ts    |    2 +
 .../bookings/BookingRequestDetailPage.tsx     |  353 ++++--
 .../bookings/DocumentClearanceDetailPage.tsx  |  326 ++---
 .../contracts/ContractClearanceDetailPage.tsx |  289 ++---
 .../contracts/ContractRequestDetailPage.tsx   | 1063 ++++++++++-------
 .../pages/contracts/GlClearanceDetailPage.tsx |   87 +-
 .../contracts/ShipmentRequestDetailPage.tsx   |   13 +-
 .../pages/customers/CustomerDetailPage.tsx    |   87 +-
 .../src/pages/invoices/InvoiceDetailPage.tsx  |  321 +++--
 .../TrainScheduleV2DetailPage.tsx             |  508 ++++----
 .../src/services/bookings.service.ts          |    3 +
 packages/types/src/freight/index.ts           |   11 +-
 35 files changed, 2104 insertions(+), 2037 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingContractCard.tsx
 delete mode 100644 apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingContractSummaryCard.tsx
 delete mode 100644 apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingRequestHero.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/contracts/BookingRequestStatusBadge.tsx
 delete mode 100644 apps/edr-freight-web/backoffice/src/components/customers/ResetPasswordAction.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/detail/EntityLink.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/detail/Field.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/detail/LinkedEntityCard.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/detail/index.ts

diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index caa25fbaa..513d8f9e5 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -413,6 +413,32 @@ export class BillingService {
     return `data:image/png;base64,${signedQr}`;
   }
 
+  /** Route + wagon count summary rows for a booking-sourced invoice; empty for every other source. */
+  private async bookingSummaryRows(
+    invoice: Invoice,
+  ): Promise<InvoiceDocumentModel["summary"]> {
+    if (invoice.source !== Freight.InvoiceSource.Booking) return [];
+    const booking = await this.dataSource.getRepository(Booking).findOne({
+      where: { id: invoice.sourceId },
+      relations: { originYard: true, destinationYard: true },
+    });
+    if (!booking) return [];
+    return [
+      {
+        label: "Route",
+        value:
+          booking.originYard && booking.destinationYard
+            ? `${booking.originYard.label} → ${booking.destinationYard.label}`
+            : null,
+      },
+      {
+        label: "Wagons",
+        value:
+          booking.wagonsRequired != null ? String(booking.wagonsRequired) : null,
+      },
+    ];
+  }
+
   /** Map a global invoice (+ lines) onto the source-agnostic document model. */
   private async toDocumentModel(
     invoice: Invoice & { lines: InvoiceLine[] },
@@ -446,6 +472,7 @@ export class BillingService {
       { label: "Status", value: invoice.status },
       { label: "Type", value: invoice.type },
       { label: "Reference", value: invoice.sourceId },
+      ...(await this.bookingSummaryRows(invoice)),
       { label: "Currency", value: invoice.currency },
       {
         label: "Issued",
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
index 2b1463a95..ea1523882 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
@@ -59,6 +59,7 @@ export interface BookingListFilterOptions {
   assignedToSchedule?: 'true' | 'false';
   companyId?: string;
   companyProfileId?: string;
+  contractId?: string;
   contractType?: string;
   serviceTypeId?: string;
   cargoTypeId?: string;
@@ -936,6 +937,11 @@ export class BookingsRepository extends BaseRepository<Booking> {
         companyProfileId: options.companyProfileId,
       });
     }
+    if (options.contractId) {
+      qb.andWhere('booking.contract_id = :contractId', {
+        contractId: options.contractId,
+      });
+    }
     if (options.contractType) {
       qb.andWhere('booking.contract_type = :contractType', {
         contractType: options.contractType,
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
index 6c3f14ecb..4f26c4415 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
@@ -1805,6 +1805,7 @@ export class BookingsService {
       // ANDs both, so cross-company access is impossible.
       companyId: forceCompanyId ?? filter.companyId,
       companyProfileId: forceCompanyProfileId ?? filter.companyProfileId,
+      contractId: filter.contractId,
       tradeDirections,
       contractType: filter.contractType,
       serviceTypeId: filter.serviceTypeId,
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts
index 2d3297af8..43d489bac 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts
@@ -47,6 +47,11 @@ export class FilterBookingDto {
   @IsUUID()
   companyProfileId?: string;
 
+  @ApiPropertyOptional({ format: 'uuid', description: 'Filter bookings drawn down under this contract' })
+  @IsOptional()
+  @IsUUID()
+  contractId?: string;
+
   @ApiPropertyOptional()
   @IsOptional()
   contractType?: string;
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCompanyCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCompanyCard.tsx
index 06fafc099..92df02ab6 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCompanyCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCompanyCard.tsx
@@ -1,44 +1,16 @@
-import type { LucideIcon } from "lucide-react";
-import {
-  Building2,
-  FileCheck,
-  Mail,
-  MapPin,
-  Phone,
-  User,
-} from "lucide-react";
-import { Group, Stack, Text, Divider } from "@mantine/core";
+import { Building2, FileCheck, Mail, MapPin, Phone, User } from "lucide-react";
+import { Text } from "@mantine/core";
 
 import type { BookingDetail } from "@/types/booking";
+import { LinkedEntityCard } from "@/components/detail";
+import type { FieldRowProps } from "@/components/detail";
 import { SectionCard } from "./SectionCard";
 
-interface InfoRowProps {
-  icon: LucideIcon;
-  label: string;
-  value?: string | null;
-}
-
-function InfoRow({ icon: Icon, label, value }: InfoRowProps) {
-  return (
-    <Group justify="space-between" wrap="nowrap" py={6} gap="md">
-      <Group gap="xs" wrap="nowrap">
-        <Icon size={15} color="var(--mantine-color-gray-5)" />
-        <Text size="sm" c="dimmed">
-          {label}
-        </Text>
-      </Group>
-      <Text size="sm" fw={600} ta="right" style={{ minWidth: 0 }} truncate>
-        {value || "—"}
-      </Text>
-    </Group>
-  );
-}
-
 export interface BookingCompanyCardProps {
   booking: BookingDetail;
 }
 
-/** Customer (company) information for the booking. */
+/** Customer (company) quick info for the booking, linking to its detail page. */
 export function BookingCompanyCard({ booking }: BookingCompanyCardProps) {
   const company = booking.company;
 
@@ -46,11 +18,9 @@ export function BookingCompanyCard({ booking }: BookingCompanyCardProps) {
   if (!company && booking.isGovernment) {
     return (
       <SectionCard icon={Building2} title="Customer" accent="blue">
-        <InfoRow
-          icon={Building2}
-          label="Government"
-          value={booking.governmentInstitution}
-        />
+        <Text size="sm" fw={600}>
+          {booking.governmentInstitution ?? "Government"}
+        </Text>
       </SectionCard>
     );
   }
@@ -67,36 +37,24 @@ export function BookingCompanyCard({ booking }: BookingCompanyCardProps) {
 
   const companyName = company.companyName ?? company.name ?? company.label;
 
-  const rows: InfoRowProps[] = [
+  const rows: FieldRowProps[] = [
     { icon: FileCheck, label: "TIN", value: company.tin },
     { icon: Mail, label: "Email", value: company.email },
     { icon: Phone, label: "Phone", value: company.phone },
     { icon: MapPin, label: "Address", value: company.address },
     { icon: User, label: "Contact person", value: company.contactPersonName },
     { icon: Phone, label: "Contact phone", value: company.contactPersonPhone },
-  ].filter((r) => r.value);
+  ];
 
   return (
-    <SectionCard
+    <LinkedEntityCard
       icon={Building2}
       title="Customer"
-      subtitle={companyName}
+      name={companyName ?? "Unnamed company"}
+      to={company.id ? `/dashboard/customers/${company.id}` : null}
       accent="blue"
-    >
-      <Stack gap={0}>
-        {rows.length === 0 ? (
-          <Text size="sm" c="dimmed">
-            No additional company details available.
-          </Text>
-        ) : (
-          rows.map((row, index) => (
-            <div key={row.label}>
-              {index > 0 && <Divider color="var(--mantine-color-gray-2)" />}
-              <InfoRow {...row} />
-            </div>
-          ))
-        )}
-      </Stack>
-    </SectionCard>
+      rows={rows}
+      emptyMessage="No additional company details available."
+    />
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingContractCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingContractCard.tsx
new file mode 100644
index 000000000..f5fc3bf2a
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingContractCard.tsx
@@ -0,0 +1,49 @@
+import { Anchor as AnchorIcon } from "lucide-react";
+import { Code } from "@mantine/core";
+
+import type { BookingDetail } from "@/types/booking";
+import { LinkedEntityCard } from "@/components/detail";
+import type { FieldRowProps } from "@/components/detail";
+
+export interface BookingContractCardProps {
+  booking: BookingDetail;
+}
+
+/** Parent contract quick info for the booking, linking to its detail page. */
+export function BookingContractCard({ booking }: BookingContractCardProps) {
+  if (!booking.contractId || !booking.contractReference) return null;
+
+  const rows: FieldRowProps[] = [
+    {
+      label: "Kind",
+      value: booking.contractKind === "GENERAL" ? "General" : "One-time",
+    },
+  ];
+
+  return (
+    <LinkedEntityCard
+      icon={AnchorIcon}
+      title="Contract"
+      name={booking.contractReference}
+      to={`/dashboard/contract-requests/${booking.contractId}`}
+      accent="teal"
+      rows={rows}
+      footer={
+        booking.contractSummary ? (
+          <Code
+            block
+            mt={4}
+            style={{
+              maxHeight: 220,
+              overflow: "auto",
+              whiteSpace: "pre-wrap",
+              background: "var(--mantine-color-gray-0)",
+            }}
+          >
+            {booking.contractSummary}
+          </Code>
+        ) : undefined
+      }
+    />
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingContractSummaryCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingContractSummaryCard.tsx
deleted file mode 100644
index 1e86a7d2a..000000000
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingContractSummaryCard.tsx
+++ /dev/null
@@ -1,27 +0,0 @@
-import { Anchor } from "lucide-react";
-import { Code } from "@mantine/core";
-
-import { SectionCard } from "./SectionCard";
-
-export interface BookingContractSummaryCardProps {
-  summary: string;
-}
-
-/** Generated contract terms, shown verbatim. */
-export function BookingContractSummaryCard({ summary }: BookingContractSummaryCardProps) {
-  return (
-    <SectionCard icon={Anchor} title="Contract summary" accent="teal">
-      <Code
-        block
-        style={{
-          maxHeight: 256,
-          overflow: "auto",
-          whiteSpace: "pre-wrap",
-          background: "var(--mantine-color-gray-0)",
-        }}
-      >
-        {summary}
-      </Code>
-    </SectionCard>
-  );
-}
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingMileServicesCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingMileServicesCard.tsx
index 3236e5cae..3cebeacc5 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingMileServicesCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingMileServicesCard.tsx
@@ -1,5 +1,6 @@
+import type { ReactNode } from "react";
 import { Truck } from "lucide-react";
-import { SimpleGrid } from "@mantine/core";
+import { SimpleGrid, Stack } from "@mantine/core";
 
 import type { BookingDetail } from "@/types/booking";
 
@@ -8,24 +9,40 @@ import { MetricTile } from "./MetricTile";
 
 export interface BookingMileServicesCardProps {
   booking: BookingDetail;
+  /** Export handover-mode control — how the cargo reaches the train. Lives
+   * here because it's the other "how does the cargo physically travel" fact;
+   * shown even when no mile address is set, since EXPORT bookings still need
+   * the choice made. */
+  handoverSection?: ReactNode;
 }
 
-/** First / last mile addresses. Renders nothing when neither is present. */
-export function BookingMileServicesCard({ booking }: BookingMileServicesCardProps) {
-  if (!booking.firstMilePickupAddress && !booking.lastMileDeliveryAddress) {
+/** First / last mile addresses, plus the export handover control. Renders
+ * nothing when none of the three are present. */
+export function BookingMileServicesCard({
+  booking,
+  handoverSection,
+}: BookingMileServicesCardProps) {
+  const hasAddresses =
+    Boolean(booking.firstMilePickupAddress) || Boolean(booking.lastMileDeliveryAddress);
+  if (!hasAddresses && !handoverSection) {
     return null;
   }
 
   return (
     <SectionCard icon={Truck} title="Mile services" accent="grape">
-      <SimpleGrid cols={{ base: 1, md: 2 }} spacing="sm">
-        {booking.firstMilePickupAddress && (
-          <MetricTile label="First mile pickup" value={booking.firstMilePickupAddress} />
+      <Stack gap="md">
+        {hasAddresses && (
+          <SimpleGrid cols={{ base: 1, md: 2 }} spacing="sm">
+            {booking.firstMilePickupAddress && (
+              <MetricTile label="First mile pickup" value={booking.firstMilePickupAddress} />
+            )}
+            {booking.lastMileDeliveryAddress && (
+              <MetricTile label="Last mile delivery" value={booking.lastMileDeliveryAddress} />
+            )}
+          </SimpleGrid>
         )}
-        {booking.lastMileDeliveryAddress && (
-          <MetricTile label="Last mile delivery" value={booking.lastMileDeliveryAddress} />
-        )}
-      </SimpleGrid>
+        {handoverSection}
+      </Stack>
     </SectionCard>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingRequestHero.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingRequestHero.tsx
deleted file mode 100644
index ed9802150..000000000
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingRequestHero.tsx
+++ /dev/null
@@ -1,258 +0,0 @@
-import type { ReactNode } from "react";
-import {
-  ArrowLeft,
-  Building2,
-  Calendar,
-  Clock,
-  Container as ContainerIcon,
-  Flame,
-  RefreshCw,
-  Wallet,
-  Weight,
-} from "lucide-react";
-import {
-  Button,
-  Group,
-  Paper,
-  Stack,
-  Text,
-  ThemeIcon,
-  Title,
-} from "@mantine/core";
-import type { LucideIcon } from "lucide-react";
-
-import type { BookingDetail } from "@/types/booking";
-import { cargoTonsAndItems } from "@/utils/cargoWeight";
-import { BookingStatusBadge } from "@/components/bookings/BookingStatusBadge";
-import { BookingPriorityBadge } from "@/components/bookings/BookingPriorityBadge";
-import { ContractReferenceLink } from "@/components/bookings/ContractReferenceLink";
-import { SchedulingStatusBadge } from "@/components/trainScheduling/ScheduleStatusBadge";
-import { NextStepBanner } from "@/components/bookings/NextStepBanner";
-
-import { formatDate } from "./booking-detail.styles";
-
-export interface BookingRequestHeroProps {
-  booking: BookingDetail;
-  customerLabel: string;
-  onBack: () => void;
-  onRefresh: () => void;
-  isFetching?: boolean;
-}
-
-/** Top hero for the request detail page: identity, status, next step, key figures. */
-export function BookingRequestHero({
-  booking,
-  customerLabel,
-  onBack,
-  onRefresh,
-  isFetching,
-}: BookingRequestHeroProps) {
-  const amount = Number(booking.totalAmount);
-  const containers = booking.bookingContainers ?? [];
-  const containerCount = containers.reduce(
-    (sum, c) => sum + Number(c.quantity ?? 0),
-    0,
-  );
-  const { tons: weight, items: itemCount } = cargoTonsAndItems(booking);
-
-  return (
-    <Paper
-      radius="xl"
-      p="xl"
-      style={{ position: "relative", overflow: "hidden" }}
-    >
-      <Stack gap="lg" style={{ position: "relative" }}>
-        <Group justify="space-between" align="flex-start" wrap="wrap">
-          <Button
-            variant="default"
-            size="compact-sm"
-            radius="lg"
-            leftSection={<ArrowLeft size={16} />}
-            onClick={onBack}
-          >
-            Back to list
-          </Button>
-          <Button
-            variant="light"
-            color="edr-green"
-            size="compact-sm"
-            radius="lg"
-            leftSection={<RefreshCw size={15} />}
-            loading={isFetching}
-            onClick={onRefresh}
-          >
-            Refresh
-          </Button>
-        </Group>
-
-        <Group justify="space-between" align="flex-start" wrap="wrap" gap="lg">
-          <Stack gap="sm" style={{ flex: 1, minWidth: 0 }}>
-            <Text
-              size="xs"
-              fw={700}
-              tt="uppercase"
-              style={{ letterSpacing: 1, color: "#B26C09" }}
-            >
-              Booking reference
-            </Text>
-            <Group gap="sm" align="center" wrap="wrap">
-              <Stack gap={2} miw={0}>
-                <Title order={2} fw={700} style={{ letterSpacing: "-0.4px" }}>
-                  {booking.reference}
-                </Title>
-                <ContractReferenceLink
-                  contractId={booking.contractId}
-                  contractReference={booking.contractReference}
-                />
-              </Stack>
-              <BookingStatusBadge status={booking.status} />
-              <BookingPriorityBadge score={booking.priorityScore} />
-              {booking.schedulingStatus ? (
-                <SchedulingStatusBadge status={booking.schedulingStatus} />
-              ) : null}
-            </Group>
-
-            {booking.holdExpiresAt && booking.schedulingStatus === "HOLDING" ? (
-              <Text size="xs" c="orange.7">
-                Hold expires {new Date(booking.holdExpiresAt).toLocaleString()}
-              </Text>
-            ) : null}
-
-            <Group gap="lg" mt={4}>
-              <MetaItem icon={Building2} text={customerLabel} strong />
-              <MetaItem
-                icon={Calendar}
-                text={`Scheduled ${booking.scheduledDate}`}
-              />
-              <MetaItem
-                icon={Clock}
-                text={`Created ${formatDate(booking.createdAt)}`}
-              />
-            </Group>
-          </Stack>
-        </Group>
-
-        {booking.nextStep ? (
-          <Paper
-            radius="lg"
-            p={4}
-            maw={640}
-            style={{
-              background: "var(--mantine-color-gray-0)",
-              border: "1px solid var(--mantine-color-gray-2)",
-            }}
-          >
-            <NextStepBanner nextStep={booking.nextStep} />
-          </Paper>
-        ) : null}
-
-        <Group grow gap="md" align="stretch" wrap="wrap">
-          <HeroTile
-            icon={Wallet}
-            label="Total value"
-            value={`${booking.paymentCurrency} ${amount.toLocaleString(
-              undefined,
-              {
-                minimumFractionDigits: 2,
-              },
-            )}`}
-            hint={booking.paymentStatus}
-            accent="edr-green"
-          />
-          <HeroTile
-            icon={Weight}
-            label="Cargo weight"
-            value={`${weight} T`}
-            hint={itemCount != null ? `${itemCount} items` : "VGM total"}
-            accent="blue"
-          />
-          <HeroTile
-            icon={ContainerIcon}
-            label="Containers"
-            value={containerCount || "—"}
-            hint={`${containers.length} line${containers.length === 1 ? "" : "s"}`}
-            accent="teal"
-          />
-          <HeroTile
-            icon={Flame}
-            label="Priority score"
-            value={booking.priorityScore ?? 0}
-            hint={booking.tradeDirection}
-            accent="orange"
-          />
-        </Group>
-      </Stack>
-    </Paper>
-  );
-}
-
-function MetaItem({
-  icon: Icon,
-  text,
-  strong,
-}: {
-  icon: LucideIcon;
-  text: ReactNode;
-  strong?: boolean;
-}) {
-  return (
-    <Group gap={6} wrap="nowrap">
-      <Icon size={14} color="var(--mantine-color-gray-5)" />
-      <Text size="sm" fw={strong ? 600 : 400} c={strong ? "dark" : "dimmed"}>
-        {text}
-      </Text>
-    </Group>
-  );
-}
-
-function HeroTile({
-  icon: Icon,
-  label,
-  value,
-  hint,
-  accent = "edr-green",
-}: {
-  icon: LucideIcon;
-  label: string;
-  value: ReactNode;
-  hint?: ReactNode;
-  accent?: string;
-}) {
-  return (
-    <Paper
-      p="md"
-      radius="lg"
-      style={{
-        flex: "1 1 160px",
-        minWidth: 150,
-        background: "var(--mantine-color-gray-0)",
-        border: "1px solid var(--mantine-color-gray-2)",
-      }}
-    >
-      <Group gap="sm" wrap="nowrap" align="flex-start">
-        <ThemeIcon size={36} radius="md" variant="light" color={accent}>
-          <Icon size={18} />
-        </ThemeIcon>
-        <Stack gap={2} style={{ minWidth: 0 }}>
-          <Text
-            size="xs"
-            fw={600}
-            tt="uppercase"
-            c="dimmed"
-            style={{ letterSpacing: 0.4 }}
-          >
-            {label}
-          </Text>
-          <Text fw={700} size="lg" lh={1.1} style={{ whiteSpace: "nowrap" }}>
-            {value}
-          </Text>
-          {hint ? (
-            <Text size="xs" c="dimmed" truncate>
-              {hint}
-            </Text>
-          ) : null}
-        </Stack>
-      </Group>
-    </Paper>
-  );
-}
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/index.ts b/apps/edr-freight-web/backoffice/src/components/bookings/detail/index.ts
index b0b024977..23f9b2bd8 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/index.ts
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/index.ts
@@ -16,10 +16,9 @@ export * from "./BookingPaymentCard";
 export * from "./BookingPaymentCountdownCard";
 export * from "./BookingFactsCard";
 export * from "./BookingDocumentsCard";
-export * from "./BookingRequestHero";
 export * from "./BookingRouteServiceCard";
 export * from "./BookingMileServicesCard";
 export * from "./BookingCargoCard";
-export * from "./BookingContractSummaryCard";
+export * from "./BookingContractCard";
 export * from "./BookingCompanyCard";
 export * from "./BookingSchedulingWindowCard";
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/BookingRequestStatusBadge.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/BookingRequestStatusBadge.tsx
new file mode 100644
index 000000000..dc742df4f
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/BookingRequestStatusBadge.tsx
@@ -0,0 +1,16 @@
+import { Badge } from "@mantine/core";
+
+const STATUS_COLOR: Record<string, string> = {
+  PENDING: "edr-green",
+  ACCEPTED: "blue",
+  REJECTED: "red",
+};
+
+/** Status of a customer-submitted shipment (booking) request against a contract. */
+export function BookingRequestStatusBadge({ status }: { status: string }) {
+  return (
+    <Badge variant="light" radius="sm" color={STATUS_COLOR[status] ?? "gray"}>
+      {status}
+    </Badge>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/detail/ContractDetailTabCards.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/detail/ContractDetailTabCards.tsx
index d29e045c4..5d875d98e 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/detail/ContractDetailTabCards.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/detail/ContractDetailTabCards.tsx
@@ -30,6 +30,7 @@ import { clearanceWorkflowFileLabel } from "@edr/types";
 
 import { SectionCard } from "@/components/bookings/detail/SectionCard";
 import { detailStyles } from "@/components/bookings/detail/booking-detail.styles";
+import { LinkedEntityCard } from "@/components/detail";
 import { customersService } from "@/services/customers.service";
 
 type ContractFile = NonNullable<Freight.IContract["files"]>[number];
@@ -141,25 +142,23 @@ export function ContractCustomerCard({
 
   return (
     <Stack gap="lg">
-      <SectionCard
+      <LinkedEntityCard
         icon={Building2}
         title="Customer"
-        subtitle={company.name}
+        name={company.name ?? "Unnamed company"}
+        to={`/dashboard/customers/${company.id}`}
         accent="blue"
-      >
-        <InfoRows
-          rows={[
-            { icon: FileCheck, label: "TIN", value: company.tin },
-            { icon: Hash, label: "VAT number", value: company.vatNumber },
-            { icon: ShieldCheck, label: "FAN number", value: company.fanNumber },
-            { icon: Globe, label: "Country", value: company.country },
-            { icon: Mail, label: "Email", value: company.email },
-            { icon: Phone, label: "Phone", value: company.phone },
-            { icon: MapPin, label: "Address", value: company.address },
-            { icon: Globe, label: "Website", value: company.website },
-          ]}
-        />
-      </SectionCard>
+        rows={[
+          { icon: FileCheck, label: "TIN", value: company.tin },
+          { icon: Hash, label: "VAT number", value: company.vatNumber },
+          { icon: ShieldCheck, label: "FAN number", value: company.fanNumber },
+          { icon: Globe, label: "Country", value: company.country },
+          { icon: Mail, label: "Email", value: company.email },
+          { icon: Phone, label: "Phone", value: company.phone },
+          { icon: MapPin, label: "Address", value: company.address },
+          { icon: Globe, label: "Website", value: company.website },
+        ]}
+      />
 
       <SectionCard icon={User} title="Contact person" accent="teal">
         <InfoRows
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/detail/RequestDetailCards.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/detail/RequestDetailCards.tsx
index d8c5f819a..1469e06e3 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/detail/RequestDetailCards.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/detail/RequestDetailCards.tsx
@@ -12,56 +12,14 @@ import {
   User,
   Warehouse,
 } from "lucide-react";
-import { Badge, Box, Divider, Group, Stack, Text } from "@mantine/core";
+import { Badge, Box, Group, Stack, Text } from "@mantine/core";
 import type { Freight } from "@edr/types";
 
 import { SectionCard } from "@/components/bookings/detail/SectionCard";
+import { LinkedEntityCard } from "@/components/detail";
 
 type ReqContract = NonNullable<Freight.IBookingRequest["contract"]>;
 
-interface InfoRowProps {
-  icon: LucideIcon;
-  label: string;
-  value?: string | null;
-}
-
-function InfoRow({ icon: Icon, label, value }: InfoRowProps) {
-  return (
-    <Group justify="space-between" wrap="nowrap" py={6} gap="md">
-      <Group gap="xs" wrap="nowrap">
-        <Icon size={15} color="var(--mantine-color-gray-5)" />
-        <Text size="sm" c="dimmed">
-          {label}
-        </Text>
-      </Group>
-      <Text size="sm" fw={600} ta="right" style={{ minWidth: 0 }} truncate>
-        {value || "—"}
-      </Text>
-    </Group>
-  );
-}
-
-function InfoRows({ rows }: { rows: InfoRowProps[] }) {
-  const visible = rows.filter((r) => r.value);
-  if (visible.length === 0) {
-    return (
-      <Text size="sm" c="dimmed">
-        No details available.
-      </Text>
-    );
-  }
-  return (
-    <Stack gap={0}>
-      {visible.map((row, i) => (
-        <div key={row.label}>
-          {i > 0 && <Divider color="var(--mantine-color-gray-2)" />}
-          <InfoRow {...row} />
-        </div>
-      ))}
-    </Stack>
-  );
-}
-
 /** Customer (company) on the request's contract. */
 export function RequestCustomerCard({ contract }: { contract?: ReqContract | null }) {
   const company = contract?.company;
@@ -75,23 +33,21 @@ export function RequestCustomerCard({ contract }: { contract?: ReqContract | nul
     );
   }
   return (
-    <SectionCard
+    <LinkedEntityCard
       icon={Building2}
       title="Customer"
-      subtitle={company.name ?? undefined}
+      name={company.name ?? "Unnamed company"}
+      to={company.id ? `/dashboard/customers/${company.id}` : null}
       accent="blue"
-    >
-      <InfoRows
-        rows={[
-          { icon: FileCheck, label: "TIN", value: company.tin },
-          { icon: Mail, label: "Email", value: company.email },
-          { icon: Phone, label: "Phone", value: company.phone },
-          { icon: MapPin, label: "Address", value: company.address },
-          { icon: User, label: "Contact", value: company.contactPersonName },
-          { icon: Phone, label: "Contact phone", value: company.contactPersonPhone },
-        ]}
-      />
-    </SectionCard>
+      rows={[
+        { icon: FileCheck, label: "TIN", value: company.tin },
+        { icon: Mail, label: "Email", value: company.email },
+        { icon: Phone, label: "Phone", value: company.phone },
+        { icon: MapPin, label: "Address", value: company.address },
+        { icon: User, label: "Contact", value: company.contactPersonName },
+        { icon: Phone, label: "Contact phone", value: company.contactPersonPhone },
+      ]}
+    />
   );
 }
 
@@ -119,43 +75,41 @@ export function RequestContractSummaryCard({
 }) {
   if (!contract) return null;
   return (
-    <SectionCard
+    <LinkedEntityCard
       icon={FileText}
       title="Contract"
-      subtitle={contract.reference}
+      name={contract.reference}
+      to={`/dashboard/contract-requests/${contract.id}`}
       accent="grape"
-    >
-      <InfoRows
-        rows={[
-          {
-            icon: FileText,
-            label: "Kind",
-            value: contract.contractKind === "GENERAL" ? "General" : "One-time",
-          },
-          {
-            icon: Package,
-            label: "Cargo",
-            value: contract.freightType === "CONTAINER" ? "Container" : "Bulk",
-          },
-          { icon: Ship, label: "Trade", value: titleCase(contract.tradeDirection) },
-          { icon: FileCheck, label: "Currency", value: contract.paymentCurrency },
-          {
-            icon: FileCheck,
-            label: "Customs",
-            value: contract.customsClearingEnabled
-              ? "Included (Global Logistics)"
-              : "Not included",
-          },
-          {
-            icon: FileText,
-            label: "Valid until",
-            value: contract.contractValidUntil
-              ? fmtDate(contract.contractValidUntil)
-              : "Not active yet",
-          },
-        ]}
-      />
-    </SectionCard>
+      rows={[
+        {
+          icon: FileText,
+          label: "Kind",
+          value: contract.contractKind === "GENERAL" ? "General" : "One-time",
+        },
+        {
+          icon: Package,
+          label: "Cargo",
+          value: contract.freightType === "CONTAINER" ? "Container" : "Bulk",
+        },
+        { icon: Ship, label: "Trade", value: titleCase(contract.tradeDirection) },
+        { icon: FileCheck, label: "Currency", value: contract.paymentCurrency },
+        {
+          icon: FileCheck,
+          label: "Customs",
+          value: contract.customsClearingEnabled
+            ? "Included (Global Logistics)"
+            : "Not included",
+        },
+        {
+          icon: FileText,
+          label: "Valid until",
+          value: contract.contractValidUntil
+            ? fmtDate(contract.contractValidUntil)
+            : "Not active yet",
+        },
+      ]}
+    />
   );
 }
 
diff --git a/apps/edr-freight-web/backoffice/src/components/customers/ResetPasswordAction.tsx b/apps/edr-freight-web/backoffice/src/components/customers/ResetPasswordAction.tsx
deleted file mode 100644
index f0e9b266a..000000000
--- a/apps/edr-freight-web/backoffice/src/components/customers/ResetPasswordAction.tsx
+++ /dev/null
@@ -1,151 +0,0 @@
-import { Alert, Button, Loader, Modal, Radio, Stack, Text } from "@mantine/core";
-import { useMutation, useQuery } from "@tanstack/react-query";
-import { KeyRound } from "lucide-react";
-import { useState } from "react";
-
-import { useAuth } from "@/auth/useAuth";
-import { useToast } from "@/hooks/use-toast";
-import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
-import { api } from "@/services/api";
-import type { Company, ResetChannel } from "@/types/customer";
-
-export interface ResetPasswordActionProps {
-  company: Pick<Company, "id">;
-}
-
-/**
- * Staff-triggered password reset. Sends a single-use link to the customer's
- * primary contact; the customer opens it and picks their own new password. No
- * credential is ever shown to or handled by staff.
- */
-export default function ResetPasswordAction({
-  company,
-}: ResetPasswordActionProps) {
-  const { user } = useAuth();
-  const { toast } = useToast();
-  const [opened, setOpened] = useState(false);
-  const [channel, setChannel] = useState<ResetChannel>("phone");
-
-  const allowed = hasPermission(user, FREIGHT_PERMS.customers.resetPassword);
-
-  // The destination is the primary contact's IAM account, not the company
-  // record — those are different fields and routinely hold different values, so
-  // showing `company.phone` here would tell staff the wrong number. Only fetched
-  // once the modal is open.
-  const targetQuery = useQuery(
-    api.customers.resetTarget.queryOptions({
-      input: { companyId: company.id },
-      enabled: allowed && opened,
-    }),
-  );
-  const target = targetQuery.data;
-
-  const { mutate, isPending } = useMutation(
-    api.customers.resetPassword.mutationOptions({
-      onSuccess: (result) => {
-        setOpened(false);
-        toast({
-          title: "Reset link sent",
-          description: `The customer can set a new password using the link sent to ${result.maskedTarget}. It expires in 24 hours.`,
-        });
-      },
-      onError: (error) => {
-        toast({
-          title: "Could not send reset link",
-          description: error.message,
-          variant: "destructive",
-        });
-      },
-    }),
-  );
-
-  if (!allowed) return null;
-
-  // SMS is domestic-only: a foreign number counts as unavailable, same as a
-  // missing one, so staff can't send a link that will never arrive.
-  const phoneUsable = !!target?.phone && target.phoneIsDomestic !== false;
-  const channelMissing =
-    !!target && (channel === "email" ? !target.email : !phoneUsable);
-
-  return (
-    <>
-      <Button
-        variant="default"
-        leftSection={<KeyRound size={16} />}
-        onClick={() => setOpened(true)}
-      >
-        Reset password
-      </Button>
-
-      <Modal
-        opened={opened}
-        onClose={() => setOpened(false)}
-        title="Send a password-reset link"
-        centered
-      >
-        <Stack gap="md">
-          <Text size="sm" c="dimmed">
-            We&apos;ll send a single-use link to this customer&apos;s primary
-            contact. They choose their own new password — you will not see it.
-            The link expires in 24 hours.
-          </Text>
-
-          {targetQuery.isLoading ? (
-            <Stack align="center" py="md">
-              <Loader size="sm" />
-            </Stack>
-          ) : targetQuery.isError ? (
-            <Alert color="red" variant="light">
-              {targetQuery.error.message}
-            </Alert>
-          ) : target ? (
-            <>
-              <Radio.Group
-                value={channel}
-                onChange={(v) => setChannel(v as ResetChannel)}
-                label={`Send the link to ${target.name || "the primary contact"} via`}
-              >
-                <Stack gap="xs" mt="xs">
-                  <Radio
-                    value="phone"
-                    label="SMS"
-                    disabled={!phoneUsable}
-                    description={
-                      !target.phone
-                        ? "No phone number on this account"
-                        : target.phoneIsDomestic === false
-                          ? `${target.phone} — foreign number, SMS unavailable; use email`
-                          : target.phone
-                    }
-                  />
-                  <Radio
-                    value="email"
-                    label="Email"
-                    disabled={!target.email}
-                    description={
-                      target.email ?? "No email address on this account"
-                    }
-                  />
-                </Stack>
-              </Radio.Group>
-
-              <Text size="xs" c="dimmed">
-                These are the primary contact&apos;s own login details, which may
-                differ from the company contact details on the profile.
-              </Text>
-
-              <Button
-                color="edr-green"
-                loading={isPending}
-                disabled={channelMissing}
-                onClick={() => mutate({ companyId: company.id, channel })}
-              >
-                Send reset link
-              </Button>
-            </>
-          ) : null}
-        </Stack>
-      </Modal>
-    </>
-  );
-}
diff --git a/apps/edr-freight-web/backoffice/src/components/customers/index.ts b/apps/edr-freight-web/backoffice/src/components/customers/index.ts
index daeb11311..6f869173c 100644
--- a/apps/edr-freight-web/backoffice/src/components/customers/index.ts
+++ b/apps/edr-freight-web/backoffice/src/components/customers/index.ts
@@ -19,10 +19,6 @@ export {
   RequestDocumentChangeModal,
   type RequestDocumentChangeModalProps,
 } from "./RequestDocumentChangeModal";
-export {
-  default as ResetPasswordAction,
-  type ResetPasswordActionProps,
-} from "./ResetPasswordAction";
 export { formatBytes, formatDate, formatMoney, humanize } from "./format";
 export {
   PersonCard,
diff --git a/apps/edr-freight-web/backoffice/src/components/detail/EntityLink.tsx b/apps/edr-freight-web/backoffice/src/components/detail/EntityLink.tsx
new file mode 100644
index 000000000..497c59d6c
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/detail/EntityLink.tsx
@@ -0,0 +1,63 @@
+import type { ReactNode } from "react";
+import type { LucideIcon } from "lucide-react";
+import { ArrowUpRight } from "lucide-react";
+import { Anchor, Group, Text } from "@mantine/core";
+import { Link } from "react-router-dom";
+
+export interface EntityLinkProps {
+  /** Route to the related record's detail page. Renders nothing if falsy — a
+   * link with no id would be a dead one (e.g. a government booking with no
+   * company). */
+  to?: string | null;
+  label: ReactNode;
+  icon?: LucideIcon;
+  /** Monospace label — for references/codes (e.g. "CT-2024-0117"). */
+  mono?: boolean;
+  size?: "xs" | "sm" | "md";
+  fw?: number;
+  className?: string;
+}
+
+/**
+ * Inline link to another record's detail page, with a small "go to" glyph so
+ * it reads as navigation rather than plain emphasis. `stopPropagation` matters
+ * wherever this sits inside a clickable table row (booking/invoice rows
+ * navigate on click) — without it a nested link races the row handler.
+ */
+export function EntityLink({
+  to,
+  label,
+  icon: Icon,
+  mono,
+  size = "sm",
+  fw = 600,
+  className,
+}: EntityLinkProps) {
+  if (!to) {
+    return (
+      <Text size={size} fw={fw} c="dimmed" ff={mono ? "monospace" : undefined}>
+        {label}
+      </Text>
+    );
+  }
+
+  return (
+    <Anchor
+      component={Link}
+      to={to}
+      onClick={(e) => e.stopPropagation()}
+      underline="hover"
+      c="edr-green"
+      fw={fw}
+      fz={size}
+      ff={mono ? "monospace" : undefined}
+      className={className}
+    >
+      <Group gap={4} wrap="nowrap" component="span" style={{ display: "inline-flex" }}>
+        {Icon ? <Icon size={14} /> : null}
+        <span>{label}</span>
+        <ArrowUpRight size={13} style={{ flexShrink: 0 }} />
+      </Group>
+    </Anchor>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/detail/Field.tsx b/apps/edr-freight-web/backoffice/src/components/detail/Field.tsx
new file mode 100644
index 000000000..7300005b9
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/detail/Field.tsx
@@ -0,0 +1,59 @@
+import type { ReactNode } from "react";
+import type { LucideIcon } from "lucide-react";
+import { Group, Stack, Text } from "@mantine/core";
+
+export interface FieldProps {
+  label: string;
+  value?: ReactNode;
+}
+
+/**
+ * Stacked label-over-value pair — uppercase dimmed label, value below. Used in
+ * grids of facts (e.g. an invoice summary, a contract's key figures).
+ */
+export function Field({ label, value }: FieldProps) {
+  const isEmpty = value === undefined || value === null || value === "";
+  return (
+    <Stack gap={2}>
+      <Text
+        size="xs"
+        fw={600}
+        c="edr-muted"
+        tt="uppercase"
+        style={{ letterSpacing: "0.04em" }}
+      >
+        {label}
+      </Text>
+      <Text size="sm" c="edr-text">
+        {isEmpty ? "—" : value}
+      </Text>
+    </Stack>
+  );
+}
+
+export interface FieldRowProps {
+  icon?: LucideIcon;
+  label: string;
+  value?: ReactNode;
+}
+
+/**
+ * Left icon+label / right bold value row, divider-separated when stacked in a
+ * list. Used inside quick-info cards (see `LinkedEntityCard`).
+ */
+export function FieldRow({ icon: Icon, label, value }: FieldRowProps) {
+  const isEmpty = value === undefined || value === null || value === "";
+  return (
+    <Group justify="space-between" wrap="nowrap" py={6} gap="md">
+      <Group gap="xs" wrap="nowrap">
+        {Icon ? <Icon size={15} color="var(--mantine-color-gray-5)" /> : null}
+        <Text size="sm" c="dimmed">
+          {label}
+        </Text>
+      </Group>
+      <Text size="sm" fw={600} ta="right" style={{ minWidth: 0 }} truncate>
+        {isEmpty ? "—" : value}
+      </Text>
+    </Group>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/detail/LinkedEntityCard.tsx b/apps/edr-freight-web/backoffice/src/components/detail/LinkedEntityCard.tsx
new file mode 100644
index 000000000..931932fb5
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/detail/LinkedEntityCard.tsx
@@ -0,0 +1,67 @@
+import type { ReactNode } from "react";
+import type { LucideIcon } from "lucide-react";
+import { Divider, Stack, Text } from "@mantine/core";
+
+import { SectionCard } from "@/components/bookings/detail/SectionCard";
+import { FieldRow, type FieldRowProps } from "./Field";
+import { EntityLink } from "./EntityLink";
+
+export interface LinkedEntityCardProps {
+  icon: LucideIcon;
+  /** Card title, e.g. "Customer" or "Contract". */
+  title: string;
+  /** The entity's own name/reference, rendered as the linked subtitle. */
+  name: ReactNode;
+  /** Route to the entity's detail page. Omit when there's nothing to link to
+   * (e.g. a government booking with no company) — the name renders as plain
+   * dimmed text instead of a dead link. */
+  to?: string | null;
+  accent?: string;
+  /** Quick-info rows shown below the linked name — empty ones are dropped. */
+  rows?: FieldRowProps[];
+  /** Extra content under the rows (e.g. a summary paragraph, an action). */
+  footer?: ReactNode;
+  /** Shown instead of rows/footer when there's nothing to display at all. */
+  emptyMessage?: string;
+}
+
+/**
+ * "Customer at a glance" / "Contract at a glance" card for a detail page's
+ * sticky rail: a linked title plus a handful of quick-info rows, so the
+ * related record's essentials are visible without navigating away.
+ */
+export function LinkedEntityCard({
+  icon,
+  title,
+  name,
+  to,
+  accent = "blue",
+  rows = [],
+  footer,
+  emptyMessage,
+}: LinkedEntityCardProps) {
+  const visibleRows = rows.filter((r) => r.value !== undefined && r.value !== null && r.value !== "");
+
+  return (
+    <SectionCard icon={icon} title={title} accent={accent}>
+      <Stack gap={4}>
+        <EntityLink to={to} label={name} size="sm" fw={700} />
+        {visibleRows.length > 0 ? (
+          <Stack gap={0} mt={4}>
+            {visibleRows.map((row, index) => (
+              <div key={row.label}>
+                {index > 0 && <Divider color="var(--mantine-color-gray-2)" />}
+                <FieldRow {...row} />
+              </div>
+            ))}
+          </Stack>
+        ) : emptyMessage ? (
+          <Text size="sm" c="dimmed" mt={4}>
+            {emptyMessage}
+          </Text>
+        ) : null}
+        {footer}
+      </Stack>
+    </SectionCard>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/detail/index.ts b/apps/edr-freight-web/backoffice/src/components/detail/index.ts
new file mode 100644
index 000000000..15e379099
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/detail/index.ts
@@ -0,0 +1,14 @@
+export { Field, FieldRow } from "./Field";
+export type { FieldProps, FieldRowProps } from "./Field";
+export { EntityLink } from "./EntityLink";
+export type { EntityLinkProps } from "./EntityLink";
+export { LinkedEntityCard } from "./LinkedEntityCard";
+export type { LinkedEntityCardProps } from "./LinkedEntityCard";
+
+// Re-exported so pages under this restructure have one import path for both
+// the new quick-info primitives and the existing section-card shell. Imported
+// from the file directly (not the bookings/detail barrel) — that barrel also
+// re-exports cards that import from this module, and going through it would
+// create a circular import.
+export { SectionCard } from "@/components/bookings/detail/SectionCard";
+export type { SectionCardProps } from "@/components/bookings/detail/SectionCard";
diff --git a/apps/edr-freight-web/backoffice/src/components/page/PageHeader.tsx b/apps/edr-freight-web/backoffice/src/components/page/PageHeader.tsx
index 087567585..803d3f5f7 100644
--- a/apps/edr-freight-web/backoffice/src/components/page/PageHeader.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/page/PageHeader.tsx
@@ -7,7 +7,7 @@ import Breadcrumbs, { type BreadcrumbItem } from "@/components/ui/Breadcrumbs";
 
 export interface PageHeaderProps {
   title: string;
-  subtitle?: string;
+  subtitle?: ReactNode;
   /** Breadcrumb trail — pass only on nested pages (details, sub-resources). */
   breadcrumbs?: BreadcrumbItem[];
   /** Route to return to; renders a back arrow before the title. */
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/LegCapacityPanel.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/LegCapacityPanel.tsx
index c98a020a5..c006c9e03 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/LegCapacityPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/LegCapacityPanel.tsx
@@ -14,6 +14,7 @@ import {
 } from "@mantine/core";
 import { ChevronDown, ChevronRight, Info, Train, Weight } from "lucide-react";
 
+import { EntityLink } from "@/components/detail";
 import type { TrainScheduleDetail } from "@/types/trainScheduling";
 
 /**
@@ -254,15 +255,19 @@ export function LegCapacityPanel({ schedule }: { schedule: TrainScheduleDetail }
                                     {e.bookings.map((b) => (
                                       <Table.Tr key={b.bookingId}>
                                         <Table.Td w="50%">
-                                          <Text size="sm" fw={500} style={{ whiteSpace: "nowrap" }}>
-                                            {b.reference}
+                                          <Group gap={4} wrap="nowrap" style={{ whiteSpace: "nowrap" }}>
+                                            <EntityLink
+                                              to={`/dashboard/booking-requests/${b.bookingId}`}
+                                              label={b.reference}
+                                              size="sm"
+                                              fw={500}
+                                            />
                                             {b.route ? (
                                               <Text span size="xs" c="dimmed">
-                                                {" "}
                                                 ({b.route})
                                               </Text>
                                             ) : null}
-                                          </Text>
+                                          </Group>
                                         </Table.Td>
                                         <Table.Td w="25%">
                                           <Group gap={4} wrap="nowrap">
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleWorkspacePanel.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleWorkspacePanel.tsx
index de954742e..47b94d69b 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleWorkspacePanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleWorkspacePanel.tsx
@@ -36,6 +36,7 @@ import {
 import { CountdownTimer } from "@edr/ui-common";
 
 import { BookingStatusBadge } from "@/components/bookings/BookingStatusBadge";
+import { EntityLink } from "@/components/detail";
 import { api } from "@/services/api";
 import { useToast } from "@/hooks/use-toast";
 import type {
@@ -601,6 +602,7 @@ export function ScheduleWorkspacePanel({
             {pool.map((b) => (
               <BookingCard
                 key={b.id}
+                bookingId={b.id}
                 reference={b.reference}
                 customer={b.customer}
                 weightTons={b.weightTons}
@@ -711,6 +713,7 @@ export function ScheduleWorkspacePanel({
                     return (
                       <BookingCard
                         key={b.id}
+                        bookingId={b.id}
                         reference={ref}
                         customer={b.customer}
                         weightTons={b.weightTons}
@@ -985,6 +988,7 @@ function PanelColumn({
 }
 
 function BookingCard({
+  bookingId,
   reference,
   customer,
   weightTons,
@@ -996,6 +1000,8 @@ function BookingCard({
   leg,
   right,
 }: {
+  /** When set, the reference links to the booking's detail page. */
+  bookingId?: string;
   reference: string;
   customer?: string | null;
   weightTons?: number | null;
@@ -1030,9 +1036,18 @@ function BookingCard({
       <Group justify="space-between" align="center" wrap="nowrap" gap="sm">
         <Stack gap={3} style={{ minWidth: 0 }}>
           <Group gap={8} align="center" wrap="nowrap">
-            <Text size="sm" fw={700} truncate>
-              {reference}
-            </Text>
+            {bookingId ? (
+              <EntityLink
+                to={`/dashboard/booking-requests/${bookingId}`}
+                label={reference}
+                size="sm"
+                fw={700}
+              />
+            ) : (
+              <Text size="sm" fw={700} truncate>
+                {reference}
+              </Text>
+            )}
             {status ? <BookingStatusBadge status={status} /> : null}
             {intercity ? (
               <Tooltip
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/WagonPlanGrid.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/WagonPlanGrid.tsx
index 73297884d..5dc5f09ca 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/WagonPlanGrid.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/WagonPlanGrid.tsx
@@ -1,5 +1,6 @@
 import { Badge, Card, Group, Progress, SimpleGrid, Stack, Text, ThemeIcon } from "@mantine/core";
 import { Box, Package } from "lucide-react";
+import { EntityLink } from "@/components/detail";
 import type { TrainScheduleWagonAllocation, WagonPlanRow } from "@/types/trainScheduling";
 
 type WagonSlot = (WagonPlanRow & {
@@ -159,9 +160,12 @@ export function WagonPlanGrid({
                       <Card key={`${alloc.bookingId}-${index}`} padding="xs" radius="md" bg="gray.0">
                         <Stack gap={2}>
                           <Group justify="space-between" gap="xs">
-                            <Text size="xs" fw={500} lineClamp={1}>
-                              {alloc.bookingReference ?? alloc.bookingId}
-                            </Text>
+                            <EntityLink
+                              to={`/dashboard/booking-requests/${alloc.bookingId}`}
+                              label={alloc.bookingReference ?? alloc.bookingId}
+                              size="xs"
+                              fw={500}
+                            />
                             {label === "BULK" ? (
                               <Text size="xs" c="dimmed">
                                 {alloc.allocatedWeightTons}T cargo
diff --git a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
index b681a2909..1ee429bad 100644
--- a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
@@ -81,6 +81,8 @@ export const QUERY_KEYS = {
       ["contracts", "clearance-history", region ?? "ET"] as const,
     milestones: (id: string) => ["contracts", "milestones", id] as const,
     capacity: (id: string) => ["contracts", "capacity", id] as const,
+    bookingRequests: (id: string) =>
+      ["contracts", "booking-requests", id] as const,
     bookingMilestones: (bookingId: string) =>
       ["contracts", "booking-milestones", bookingId] as const,
     bookingIncidents: (bookingId: string) =>
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
index d64b07a45..fdade7980 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
@@ -2,43 +2,56 @@ import { useNavigate, useParams, useSearchParams } from "react-router-dom";
 import toast from "react-hot-toast";
 import {
   ArrowLeft,
+  Container as ContainerIcon,
   FileSignature,
   FileText,
+  Flame,
   FolderOpen,
   Layers,
   LayoutGrid,
   Milestone,
+  MoreHorizontal,
   Package,
+  RefreshCw,
   Truck,
+  Wallet,
+  Weight,
 } from "lucide-react";
 import {
-  Container,
-  Stack,
-  Grid,
+  ActionIcon,
+  Box,
+  Button,
   Center,
+  Container,
+  Grid,
+  Group,
   Loader,
+  Menu,
+  Paper,
+  SegmentedControl,
+  Stack,
   Tabs,
   Text,
-  Paper,
-  Button,
-  Box,
-  SegmentedControl,
 } from "@mantine/core";
 
-import { PageContainer } from "@/components/page";
-import Breadcrumbs from "@/components/ui/Breadcrumbs";
+import { PageContainer, PageHeader, KpiStrip } from "@/components/page";
+import type { KpiItem } from "@/components/page";
+import { EntityLink } from "@/components/detail";
 import { BookingActionsToolbar } from "@/components/bookings/BookingActionsToolbar";
 import { BookingPricingSummary } from "@/components/bookings/BookingPricingSummary";
 import { BookingWorkflowStepper } from "@/components/bookings/BookingWorkflowStepper";
+import { BookingStatusBadge } from "@/components/bookings/BookingStatusBadge";
+import { BookingPriorityBadge } from "@/components/bookings/BookingPriorityBadge";
+import { NextStepBanner } from "@/components/bookings/NextStepBanner";
+import { SchedulingStatusBadge } from "@/components/trainScheduling/ScheduleStatusBadge";
 import { ConsolidationWaitingBanner } from "@/components/bookings/detail/ConsolidationWaitingBanner";
 import {
   detailStyles,
-  BookingRequestHero,
   BookingRouteServiceCard,
   BookingMileServicesCard,
   BookingCargoCard,
   BookingCompanyCard,
-  BookingContractSummaryCard,
+  BookingContractCard,
   BookingContainerUnitsCard,
   BookingSchedulingWindowCard,
   BookingDocumentsPanel,
@@ -48,6 +61,7 @@ import {
 import { WarehouseInfoCard } from "@/components/warehouses";
 import { getStatusMeta } from "@/features/bookings/booking-status.config";
 import { toBookingListRow } from "@/features/bookings/mapBookingListRow";
+import { cargoTonsAndItems } from "@/utils/cargoWeight";
 import type { BookingDetail } from "@/types/booking";
 import {
   useBookingDetail,
@@ -133,7 +147,6 @@ export default function BookingRequestDetailPage() {
     );
   }
 
-  const row = toBookingListRow(booking);
   const statusMeta = getStatusMeta(booking.status);
   // Clearance review + finalize now lives solely on the Operations "Clearance
   // Documents" hub (/dashboard/contracts/clearance-documents → detail page), so
@@ -159,23 +172,176 @@ export default function BookingRequestDetailPage() {
     setSearchParams(next, { replace: true });
   };
 
+  const company = booking.company;
+  const customerName = toBookingListRow(booking).customerLabel;
+
+  const amount = Number(booking.totalAmount);
+  const containers = booking.bookingContainers ?? [];
+  const containerCount = containers.reduce(
+    (sum, c) => sum + Number(c.quantity ?? 0),
+    0,
+  );
+  const { tons: weight, items: itemCount } = cargoTonsAndItems(booking);
+
+  const kpis: KpiItem[] = [
+    {
+      label: "Total value",
+      value: `${booking.paymentCurrency} ${amount.toLocaleString(undefined, { minimumFractionDigits: 2 })}`,
+      hint: booking.paymentStatus,
+      icon: Wallet,
+      color: "edr-green",
+    },
+    {
+      label: "Cargo weight",
+      value: `${weight} T`,
+      hint: itemCount != null ? `${itemCount} items` : "VGM total",
+      icon: Weight,
+      color: "blue",
+    },
+    {
+      label: "Containers",
+      value: containerCount || "—",
+      hint: `${containers.length} line${containers.length === 1 ? "" : "s"}`,
+      icon: ContainerIcon,
+      color: "teal",
+    },
+    {
+      label: "Priority score",
+      value: booking.priorityScore ?? 0,
+      hint: booking.tradeDirection,
+      icon: Flame,
+      color: "orange",
+    },
+  ];
+
+  const hasSignableContract = booking.isGovernment && booking.contractSummary;
+
   return (
     <PageContainer>
-      <Breadcrumbs
-        items={[
+      <PageHeader
+        breadcrumbs={[
           { label: "Booking requests", href: "/dashboard/booking-requests" },
           { label: booking.reference },
         ]}
+        backTo="/dashboard/booking-requests"
+        title={booking.reference}
+        meta={
+          <Group gap={6} wrap="wrap">
+            <BookingStatusBadge status={booking.status} />
+            <BookingPriorityBadge score={booking.priorityScore} />
+            {booking.schedulingStatus ? (
+              <SchedulingStatusBadge status={booking.schedulingStatus} />
+            ) : null}
+          </Group>
+        }
+        subtitle={
+          <Group gap={6} wrap="wrap">
+            <EntityLink
+              to={company?.id ? `/dashboard/customers/${company.id}` : null}
+              label={customerName ?? "—"}
+            />
+            <Text size="sm" c="dimmed">
+              · Scheduled {booking.scheduledDate}
+            </Text>
+          </Group>
+        }
+        action={
+          <Group gap="sm" wrap="nowrap">
+            <ActionIcon
+              variant="light"
+              color="edr-green"
+              size="lg"
+              radius="md"
+              loading={isFetching}
+              aria-label="Refresh"
+              onClick={() => refetch()}
+            >
+              <RefreshCw size={16} />
+            </ActionIcon>
+            <Menu position="bottom-end" width={260} withinPortal>
+              <Menu.Target>
+                <ActionIcon
+                  variant="default"
+                  size="lg"
+                  radius="md"
+                  aria-label="More actions"
+                >
+                  <MoreHorizontal size={16} />
+                </ActionIcon>
+              </Menu.Target>
+              <Menu.Dropdown>
+                {hasSignableContract && (
+                  <Menu.Item
+                    leftSection={<FileSignature size={15} />}
+                    onClick={() =>
+                      navigate(`/dashboard/booking-requests/${booking.id}/contract`)
+                    }
+                  >
+                    View / sign contract
+                  </Menu.Item>
+                )}
+                <Menu.Item
+                  leftSection={<FileText size={15} />}
+                  onClick={async () => {
+                    try {
+                      const blob =
+                        await bookingsService.downloadCarriageAcceptanceSheet(
+                          booking.id,
+                        );
+                      const url = URL.createObjectURL(blob);
+                      const a = document.createElement("a");
+                      a.href = url;
+                      a.download = `carriage-acceptance-${booking.reference}.pdf`;
+                      a.click();
+                      URL.revokeObjectURL(url);
+                    } catch (error) {
+                      toast.error(
+                        error instanceof Error
+                          ? error.message
+                          : "Carriage acceptance sheet is not available yet",
+                      );
+                    }
+                  }}
+                >
+                  Carriage acceptance sheet
+                </Menu.Item>
+                {booking.customsClearingEnabled && (
+                  <Menu.Item
+                    leftSection={<Milestone size={15} />}
+                    onClick={() =>
+                      navigate(`/dashboard/bookings/${booking.id}/clearance`)
+                    }
+                  >
+                    View document clearance
+                  </Menu.Item>
+                )}
+              </Menu.Dropdown>
+            </Menu>
+          </Group>
+        }
       />
 
       <Stack gap="lg">
-        <BookingRequestHero
-          booking={booking}
-          customerLabel={row.customerLabel}
-          onBack={() => navigate("/dashboard/booking-requests")}
-          onRefresh={() => refetch()}
-          isFetching={isFetching}
-        />
+        <KpiStrip items={kpis} />
+
+        {booking.holdExpiresAt && booking.schedulingStatus === "HOLDING" ? (
+          <Text size="xs" c="orange.7">
+            Hold expires {new Date(booking.holdExpiresAt).toLocaleString()}
+          </Text>
+        ) : null}
+
+        {booking.nextStep ? (
+          <Paper
+            radius="lg"
+            p={4}
+            style={{
+              background: "var(--mantine-color-gray-0)",
+              border: "1px solid var(--mantine-color-gray-2)",
+            }}
+          >
+            <NextStepBanner nextStep={booking.nextStep} />
+          </Paper>
+        ) : null}
 
         <BookingWorkflowStepper
           status={booking.status}
@@ -223,7 +389,7 @@ export default function BookingRequestDetailPage() {
                 </Tabs.List>
 
                 <Tabs.Panel value="overview">
-                  <OverviewPanel booking={booking} row={row} />
+                  <OverviewPanel booking={booking} onRefetch={refetch} />
                 </Tabs.Panel>
                 {isGeneralContract && (
                   <Tabs.Panel value="orders">
@@ -247,6 +413,7 @@ export default function BookingRequestDetailPage() {
             <Box style={{ position: "sticky", top: 24 }}>
               <Stack gap="lg">
                 <BookingCompanyCard booking={booking} />
+                <BookingContractCard booking={booking} />
                 <BookingPricingSummary booking={booking} />
                 <Box id="warehouse-payments">
                   <WarehouseInfoCard
@@ -265,97 +432,6 @@ export default function BookingRequestDetailPage() {
                   booking={booking}
                   mutations={mutations}
                 />
-                {booking.tradeDirection === "EXPORT" && (
-                  <Paper withBorder radius="md" p="sm">
-                    <Stack gap={6}>
-                      <Text size="sm" fw={600}>
-                        How the cargo reaches the train
-                      </Text>
-                      <SegmentedControl
-                        fullWidth
-                        size="xs"
-                        value={booking.exportHandoverMode ?? "WAREHOUSE"}
-                        data={[
-                          { value: "WAREHOUSE", label: "Warehouse then train" },
-                          { value: "DIRECT_TO_TRAIN", label: "Direct truck to train" },
-                        ]}
-                        onChange={async (value) => {
-                          try {
-                            await bookingsService.setExportHandoverMode(
-                              booking.id,
-                              value as "DIRECT_TO_TRAIN" | "WAREHOUSE",
-                            );
-                            await refetch();
-                          } catch (error) {
-                            toast.error(
-                              error instanceof Error
-                                ? error.message
-                                : "Could not change the handover mode",
-                            );
-                          }
-                        }}
-                      />
-                      <Text size="xs" c="dimmed">
-                        {booking.exportHandoverMode === "DIRECT_TO_TRAIN"
-                          ? "No warehouse receipt and no GRN — the carriage acceptance sheet is the handover document."
-                          : "Cargo is received at the warehouse and issued a GRN before loading."}
-                      </Text>
-                    </Stack>
-                  </Paper>
-                )}
-                {booking.isGovernment && booking.contractSummary && (
-                  <Button
-                    fullWidth
-                    variant="default"
-                    leftSection={<FileSignature size={16} />}
-                    onClick={() =>
-                      navigate(
-                        `/dashboard/booking-requests/${booking.id}/contract`,
-                      )
-                    }
-                  >
-                    View / sign contract
-                  </Button>
-                )}
-                <Button
-                  fullWidth
-                  variant="default"
-                  leftSection={<FileText size={16} />}
-                  onClick={async () => {
-                    try {
-                      const blob =
-                        await bookingsService.downloadCarriageAcceptanceSheet(
-                          booking.id,
-                        );
-                      const url = URL.createObjectURL(blob);
-                      const a = document.createElement("a");
-                      a.href = url;
-                      a.download = `carriage-acceptance-${booking.reference}.pdf`;
-                      a.click();
-                      URL.revokeObjectURL(url);
-                    } catch (error) {
-                      toast.error(
-                        error instanceof Error
-                          ? error.message
-                          : "Carriage acceptance sheet is not available yet",
-                      );
-                    }
-                  }}
-                >
-                  Carriage acceptance sheet
-                </Button>
-                {booking.customsClearingEnabled && (
-                  <Button
-                    fullWidth
-                    variant="default"
-                    leftSection={<Milestone size={16} />}
-                    onClick={() =>
-                      navigate(`/dashboard/bookings/${booking.id}/clearance`)
-                    }
-                  >
-                    View document clearance
-                  </Button>
-                )}
               </Stack>
             </Box>
           </Grid.Col>
@@ -368,11 +444,13 @@ export default function BookingRequestDetailPage() {
 /** The booking's primary detail cards — route, services, cargo, containers. */
 function OverviewPanel({
   booking,
-  row,
+  onRefetch,
 }: {
   booking: BookingDetail;
-  row: ReturnType<typeof toBookingListRow>;
+  onRefetch: () => void;
 }) {
+  const row = toBookingListRow(booking);
+
   return (
     <Stack gap="lg">
       <BookingRouteServiceCard
@@ -380,12 +458,49 @@ function OverviewPanel({
         originLabel={row.originLabel}
         destinationLabel={row.destinationLabel}
       />
-      <BookingMileServicesCard booking={booking} />
+      <BookingMileServicesCard
+        booking={booking}
+        handoverSection={
+          booking.tradeDirection === "EXPORT" ? (
+            <Stack gap={6}>
+              <Text size="sm" fw={600}>
+                How the cargo reaches the train
+              </Text>
+              <SegmentedControl
+                fullWidth
+                size="xs"
+                value={booking.exportHandoverMode ?? "WAREHOUSE"}
+                data={[
+                  { value: "WAREHOUSE", label: "Warehouse then train" },
+                  { value: "DIRECT_TO_TRAIN", label: "Direct truck to train" },
+                ]}
+                onChange={async (value) => {
+                  try {
+                    await bookingsService.setExportHandoverMode(
+                      booking.id,
+                      value as "DIRECT_TO_TRAIN" | "WAREHOUSE",
+                    );
+                    onRefetch();
+                  } catch (error) {
+                    toast.error(
+                      error instanceof Error
+                        ? error.message
+                        : "Could not change the handover mode",
+                    );
+                  }
+                }}
+              />
+              <Text size="xs" c="dimmed">
+                {booking.exportHandoverMode === "DIRECT_TO_TRAIN"
+                  ? "No warehouse receipt and no GRN — the carriage acceptance sheet is the handover document."
+                  : "Cargo is received at the warehouse and issued a GRN before loading."}
+              </Text>
+            </Stack>
+          ) : null
+        }
+      />
       <BookingCargoCard booking={booking} />
       <BookingContainerUnitsCard booking={booking} />
-      {booking.contractSummary && (
-        <BookingContractSummaryCard summary={booking.contractSummary} />
-      )}
     </Stack>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
index dd7513a42..1ed0dd470 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
@@ -10,11 +10,9 @@ import {
   Group,
   Loader,
   Paper,
-  Progress,
   RingProgress,
   Stack,
   Text,
-  ThemeIcon,
 } from "@mantine/core";
 import {
   AlertCircle,
@@ -29,9 +27,13 @@ import {
 import type { Freight } from "@edr/types";
 
 import { ClearanceOpsTabs } from "@/components/contracts/ClearanceOpsTabs";
-import { PageContainer } from "@/components/page/PageContainer";
-import { PageHeader } from "@/components/page/PageHeader";
-import { SectionCard } from "@/components/bookings/detail";
+import { PageContainer, PageHeader, KpiStrip } from "@/components/page";
+import type { KpiItem } from "@/components/page";
+import {
+  SectionCard,
+  BookingCompanyCard,
+  BookingContractCard,
+} from "@/components/bookings/detail";
 import { ClearanceReviewSection } from "@/components/bookings/detail/ClearanceReviewSection";
 import { ClearancePhaseStepper } from "@/components/contracts/ClearancePhaseStepper";
 import { PhasedClearanceActionPanel } from "@/components/contracts/PhasedClearanceActionPanel";
@@ -171,6 +173,18 @@ export default function DocumentClearanceDetailPage() {
     );
   }
 
+  const direction = booking?.tradeDirection ?? "—";
+  const origin = booking?.originYard?.label ?? booking?.originYard?.code ?? "Origin";
+  const destination =
+    booking?.destinationYard?.label ?? booking?.destinationYard?.code ?? "Destination";
+
+  const kpis: KpiItem[] = [
+    { label: "Approved", value: stats.approved, icon: CheckCircle2, color: "edr-green" },
+    { label: "Queried", value: stats.queried, icon: AlertCircle, color: "red" },
+    { label: "Pending", value: stats.pending, icon: Clock, color: "gray" },
+    { label: "Review progress", value: `${stats.pct}%`, icon: PackageCheck, color: "blue" },
+  ];
+
   return (
     <PageContainer>
       <Stack gap="lg">
@@ -182,25 +196,46 @@ export default function DocumentClearanceDetailPage() {
             { label: reference },
           ]}
           meta={
-            clearance.allApproved ? (
-              <Badge
-                variant="light"
-                color="edr-green"
-                radius="sm"
-                leftSection={<CheckCircle2 size={13} />}
-              >
-                All approved
+            <Group gap={6} wrap="wrap">
+              <Badge variant="light" color={direction === "IMPORT" ? "edr-green" : "gray"} radius="sm">
+                {direction}
               </Badge>
-            ) : (
-              <Badge
-                variant="light"
-                color="gray"
-                radius="sm"
-                leftSection={<Clock size={13} />}
-              >
-                Review pending
-              </Badge>
-            )
+              {clearance.includesCustoms ? (
+                <Badge variant="light" color="edr-green" radius="sm" leftSection={<ShieldCheck size={12} />}>
+                  Customs
+                </Badge>
+              ) : null}
+              {clearance.allApproved ? (
+                <Badge
+                  variant="light"
+                  color="edr-green"
+                  radius="sm"
+                  leftSection={<CheckCircle2 size={13} />}
+                >
+                  All approved
+                </Badge>
+              ) : (
+                <Badge
+                  variant="light"
+                  color="gray"
+                  radius="sm"
+                  leftSection={<Clock size={13} />}
+                >
+                  Review pending
+                </Badge>
+              )}
+            </Group>
+          }
+          subtitle={
+            <Group gap={8} wrap="nowrap">
+              <Text size="sm" c="dimmed" fw={600}>
+                {origin}
+              </Text>
+              <ArrowRight size={14} className="shrink-0 text-muted-foreground" />
+              <Text size="sm" c="dimmed" fw={600}>
+                {destination}
+              </Text>
+            </Group>
           }
           action={
             canCompleteBooking ? (
@@ -233,12 +268,16 @@ export default function DocumentClearanceDetailPage() {
           }
         />
 
-        <ClearanceHero
-          booking={booking}
-          clearance={clearance}
-          stats={stats}
-          requestedLines={requestedLines}
-        />
+        <KpiStrip items={kpis} />
+
+        {requestedLines ? (
+          <Group gap={10} align="center" wrap="wrap">
+            <Text size="xs" fw={700} tt="uppercase" c="dimmed" lts="0.05em">
+              Requested cargo
+            </Text>
+            <RequestedCargoChips lines={requestedLines} size="sm" />
+          </Group>
+        ) : null}
 
         {isPhasedGeneral ? (
           <Paper withBorder radius="md" p="lg">
@@ -273,67 +312,54 @@ export default function DocumentClearanceDetailPage() {
               </Grid.Col>
 
               <Grid.Col span={{ base: 12, lg: isPhasedGeneral ? 5 : 4 }}>
-                {isPhasedGeneral ? (
-                  <PhasedClearanceActionPanel
-                    bookingId={id!}
-                    clearance={clearance}
-                    tradeDirection={booking?.tradeDirection ?? "IMPORT"}
-                    workflowFiles={workflowFiles}
-                    roleMode="ET"
-                    // A bare initiated instance still has no cargo/price — the
-                    // stepper's "Create booking" step must read as NOT-yet-created
-                    // so it never claims the booking is done before GL completes it.
-                    bookingCreated={Number(booking?.totalAmount ?? 0) > 0}
-                    bookingMilestones={bookingMilestones ?? []}
-                    onChanged={() => void refetch()}
-                    onViewFile={view}
-                    onDownloadFile={(f) => void downloadBookingFile(f.id, f.name)}
-                  />
-                ) : (
-                  <Box style={{ position: "sticky", top: 24 }}>
-                    <SectionCard
-                      icon={PackageCheck}
-                      title="Review progress"
-                      accent="edr-green"
-                    >
-                      <Stack align="center" gap="sm">
-                        <RingProgress
-                          size={140}
-                          thickness={12}
-                          roundCaps
-                          sections={[{ value: stats.pct, color: "edr-green" }]}
-                          label={
-                            <Stack gap={0} align="center">
-                              <Text fw={800} fz={26} lh={1}>
-                                {stats.pct}%
-                              </Text>
-                              <Text size="xs" c="dimmed">
-                                approved
-                              </Text>
-                            </Stack>
-                          }
-                        />
-                        <Group gap="lg" justify="center">
-                          <ProgressStat
-                            color="edr-green"
-                            label="Approved"
-                            value={stats.approved}
+                <Box style={{ position: "sticky", top: 24 }}>
+                  <Stack gap="lg">
+                    {booking ? <BookingCompanyCard booking={booking} /> : null}
+                    {booking ? <BookingContractCard booking={booking} /> : null}
+                    {isPhasedGeneral ? (
+                      <PhasedClearanceActionPanel
+                        bookingId={id!}
+                        clearance={clearance}
+                        tradeDirection={booking?.tradeDirection ?? "IMPORT"}
+                        workflowFiles={workflowFiles}
+                        roleMode="ET"
+                        // A bare initiated instance still has no cargo/price — the
+                        // stepper's "Create booking" step must read as NOT-yet-created
+                        // so it never claims the booking is done before GL completes it.
+                        bookingCreated={Number(booking?.totalAmount ?? 0) > 0}
+                        bookingMilestones={bookingMilestones ?? []}
+                        onChanged={() => void refetch()}
+                        onViewFile={view}
+                        onDownloadFile={(f) => void downloadBookingFile(f.id, f.name)}
+                      />
+                    ) : (
+                      <SectionCard
+                        icon={PackageCheck}
+                        title="Review progress"
+                        accent="edr-green"
+                      >
+                        <Stack align="center" gap="sm">
+                          <RingProgress
+                            size={140}
+                            thickness={12}
+                            roundCaps
+                            sections={[{ value: stats.pct, color: "edr-green" }]}
+                            label={
+                              <Stack gap={0} align="center">
+                                <Text fw={800} fz={26} lh={1}>
+                                  {stats.pct}%
+                                </Text>
+                                <Text size="xs" c="dimmed">
+                                  approved
+                                </Text>
+                              </Stack>
+                            }
                           />
-                          <ProgressStat
-                            color="red"
-                            label="Queried"
-                            value={stats.queried}
-                          />
-                          <ProgressStat
-                            color="gray"
-                            label="Pending"
-                            value={stats.pending}
-                          />
-                        </Group>
-                      </Stack>
-                    </SectionCard>
-                  </Box>
-                )}
+                        </Stack>
+                      </SectionCard>
+                    )}
+                  </Stack>
+                </Box>
               </Grid.Col>
             </Grid>
           }
@@ -347,125 +373,3 @@ export default function DocumentClearanceDetailPage() {
     </PageContainer>
   );
 }
-
-function ClearanceHero({
-  booking,
-  clearance,
-  stats,
-  requestedLines,
-}: {
-  booking: ReturnType<typeof useBookingDetail>["data"];
-  clearance: Freight.ClearanceView;
-  stats: { pct: number; approved: number; total: number };
-  requestedLines?: Freight.RequestedShipmentLines | null;
-}) {
-  const direction = booking?.tradeDirection ?? "—";
-  const origin =
-    booking?.originYard?.label ?? booking?.originYard?.code ?? "Origin";
-  const destination =
-    booking?.destinationYard?.label ??
-    booking?.destinationYard?.code ??
-    "Destination";
-
-  return (
-    <Paper withBorder radius="md" p="lg">
-      <Group justify="space-between" align="flex-start" wrap="wrap" gap="lg">
-        <Group gap="md" wrap="nowrap" style={{ minWidth: 0 }}>
-          <ThemeIcon variant="light" color="edr-green" radius="md" size={52}>
-            <ShieldCheck size={26} />
-          </ThemeIcon>
-          <Box style={{ minWidth: 0 }}>
-            <Group gap={8} wrap="nowrap">
-              <Text fw={800} fz={20} c="edr-text" truncate>
-                {booking?.reference ?? "Clearance"}
-              </Text>
-              <Badge
-                size="sm"
-                variant="light"
-                color={direction === "IMPORT" ? "edr-green" : "gray"}
-                radius="sm"
-              >
-                {direction}
-              </Badge>
-              {clearance.includesCustoms ? (
-                <Badge
-                  size="sm"
-                  variant="light"
-                  color="edr-green"
-                  radius="sm"
-                  leftSection={<ShieldCheck size={12} />}
-                >
-                  Customs
-                </Badge>
-              ) : null}
-            </Group>
-            <Group gap={8} mt={6} wrap="nowrap">
-              <Text size="sm" fw={600} truncate maw={160}>
-                {origin}
-              </Text>
-              <ArrowRight size={15} className="shrink-0 text-muted-foreground" />
-              <Text size="sm" fw={600} truncate maw={160}>
-                {destination}
-              </Text>
-            </Group>
-          </Box>
-        </Group>
-
-        <Box style={{ minWidth: 200, flex: 1, maxWidth: 320 }}>
-          <Group justify="space-between" mb={6}>
-            <Text size="xs" c="dimmed" fw={600}>
-              Document review
-            </Text>
-            <Text size="xs" c="dimmed">
-              {stats.approved}/{stats.total}
-            </Text>
-          </Group>
-          <Progress value={stats.pct} color="edr-green" radius="xl" size="md" />
-        </Box>
-      </Group>
-
-      {requestedLines ? (
-        <>
-          <Box my="md" h={1} bg="var(--mantine-color-default-border)" />
-          <Group gap={10} align="center" wrap="wrap">
-            <Text size="xs" fw={700} tt="uppercase" c="dimmed" lts="0.05em">
-              Requested cargo
-            </Text>
-            <RequestedCargoChips lines={requestedLines} size="sm" />
-          </Group>
-        </>
-      ) : null}
-    </Paper>
-  );
-}
-
-function ProgressStat({
-  color,
-  label,
-  value,
-}: {
-  color: string;
-  label: string;
-  value: number;
-}) {
-  return (
-    <Stack gap={2} align="center">
-      <Text fw={700} fz={18} c="edr-text">
-        {value}
-      </Text>
-      <Group gap={4} wrap="nowrap">
-        <Box
-          style={{
-            width: 7,
-            height: 7,
-            borderRadius: 999,
-            background: `var(--mantine-color-${color}-6)`,
-          }}
-        />
-        <Text fz="11px" c="dimmed">
-          {label}
-        </Text>
-      </Group>
-    </Stack>
-  );
-}
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceDetailPage.tsx
index b49eb419c..dacae6cea 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceDetailPage.tsx
@@ -10,12 +10,9 @@ import {
   Grid,
   Group,
   Loader,
-  Paper,
-  Progress,
   RingProgress,
   Stack,
   Text,
-  ThemeIcon,
 } from "@mantine/core";
 import {
   AlertCircle,
@@ -37,9 +34,11 @@ import {
 
 import { BookingChangesRequestedAlert } from "@/components/contracts/BookingChangesRequestedAlert";
 import { ClearanceOpsTabs } from "@/components/contracts/ClearanceOpsTabs";
-import { PageContainer } from "@/components/page/PageContainer";
-import { PageHeader } from "@/components/page/PageHeader";
+import { PageContainer, PageHeader, KpiStrip } from "@/components/page";
+import type { KpiItem } from "@/components/page";
+import { EntityLink } from "@/components/detail";
 import { SectionCard } from "@/components/bookings/detail/SectionCard";
+import { RequestCustomerCard } from "@/components/contracts/detail/RequestDetailCards";
 import { ContractClearanceReviewSection } from "@/components/contracts/ContractClearanceReviewSection";
 import { GlUpcomingWindowsSection } from "@/components/contracts/GlUpcomingWindowsSection";
 import { PhasedClearanceActionPanel } from "@/components/contracts/PhasedClearanceActionPanel";
@@ -196,6 +195,29 @@ export default function ContractClearanceDetailPage() {
 
   const workflowFiles = clearance.workflowFiles ?? [];
 
+  const direction = contract?.tradeDirection ?? "—";
+  const customs =
+    contract?.serviceType?.includesCustoms ??
+    contract?.customsClearingEnabled ??
+    false;
+  const routes = [...(contract?.routes ?? [])].sort(
+    (a, b) => a.sortOrder - b.sortOrder,
+  );
+  const origin =
+    routes[0]?.originYard?.label ?? routes[0]?.originYard?.code ?? "Origin";
+  const lastRoute = routes[routes.length - 1] ?? routes[0];
+  const destination =
+    lastRoute?.destinationYard?.label ??
+    lastRoute?.destinationYard?.code ??
+    "Destination";
+
+  const kpis: KpiItem[] = [
+    { label: "Approved", value: stats.approved, icon: CheckCircle2, color: "edr-green" },
+    { label: "Queried", value: stats.queried, icon: AlertCircle, color: "red" },
+    { label: "Pending", value: stats.pending, icon: Clock, color: "gray" },
+    { label: "Review progress", value: `${stats.pct}%`, icon: PackageCheck, color: "blue" },
+  ];
+
   return (
     <PageContainer>
       <Stack gap="lg">
@@ -206,57 +228,81 @@ export default function ContractClearanceDetailPage() {
             { label: hubLabel, href: hubHref },
             { label: reference },
           ]}
+          subtitle={
+            <Group gap={8} wrap="nowrap">
+              {id ? (
+                <EntityLink to={`/dashboard/contract-requests/${id}`} label="Contract details" />
+              ) : null}
+              <Text size="sm" c="dimmed">
+                · {origin}
+              </Text>
+              <ArrowRight size={14} className="shrink-0 text-muted-foreground" />
+              <Text size="sm" c="dimmed">
+                {destination}
+              </Text>
+            </Group>
+          }
           meta={
-            bookingExpired ? (
-              <Badge
-                variant="light"
-                color="orange"
-                radius="sm"
-                leftSection={<RefreshCw size={13} />}
-              >
-                Payment expired — rebook
+            <Group gap={6} wrap="wrap">
+              <Badge variant="light" color={direction === "IMPORT" ? "edr-green" : "gray"} radius="sm">
+                {directionLabel(direction)}
               </Badge>
-            ) : bookingAlreadyCreated ? (
-              <Badge
-                variant="light"
-                color="blue"
-                radius="sm"
-                leftSection={<PackageCheck size={13} />}
-              >
-                Booking created
-              </Badge>
-            ) : ready ? (
-              <Badge
-                variant="light"
-                color="edr-green"
-                radius="sm"
-                leftSection={<PackageCheck size={13} />}
-              >
-                Ready — create booking
-              </Badge>
-            ) : clearance.allApproved ? (
-              <Badge
-                variant="light"
-                color="edr-green"
-                radius="sm"
-                leftSection={<CheckCircle2 size={13} />}
-              >
-                All approved
-              </Badge>
-            ) : (
-              <Badge
-                variant="light"
-                color="gray"
-                radius="sm"
-                leftSection={<Clock size={13} />}
-              >
-                Review pending
-              </Badge>
-            )
+              {customs ? (
+                <Badge variant="light" color="edr-green" radius="sm" leftSection={<ShieldCheck size={12} />}>
+                  Customs
+                </Badge>
+              ) : null}
+              {bookingExpired ? (
+                <Badge
+                  variant="light"
+                  color="orange"
+                  radius="sm"
+                  leftSection={<RefreshCw size={13} />}
+                >
+                  Payment expired — rebook
+                </Badge>
+              ) : bookingAlreadyCreated ? (
+                <Badge
+                  variant="light"
+                  color="blue"
+                  radius="sm"
+                  leftSection={<PackageCheck size={13} />}
+                >
+                  Booking created
+                </Badge>
+              ) : ready ? (
+                <Badge
+                  variant="light"
+                  color="edr-green"
+                  radius="sm"
+                  leftSection={<PackageCheck size={13} />}
+                >
+                  Ready — create booking
+                </Badge>
+              ) : clearance.allApproved ? (
+                <Badge
+                  variant="light"
+                  color="edr-green"
+                  radius="sm"
+                  leftSection={<CheckCircle2 size={13} />}
+                >
+                  All approved
+                </Badge>
+              ) : (
+                <Badge
+                  variant="light"
+                  color="gray"
+                  radius="sm"
+                  leftSection={<Clock size={13} />}
+                >
+                  Review pending
+                </Badge>
+              )}
+            </Group>
           }
         />
 
-        <ClearanceHero contract={contract} stats={stats} />
+        <KpiStrip items={kpis} />
 
         {/* Windows on this contract's routes/direction only — tells GL ET when
             it can actually create the booking without checking the schedule board. */}
@@ -383,6 +429,7 @@ export default function ContractClearanceDetailPage() {
 
               <Grid.Col span={{ base: 12, lg: 5 }}>
                 <Stack gap="md">
+                  <RequestCustomerCard contract={contract} />
                   {phasedCustoms ? (
                     <PhasedClearanceActionPanel
                       contractId={id!}
@@ -425,23 +472,6 @@ export default function ContractClearanceDetailPage() {
                               </Stack>
                             }
                           />
-                          <Group gap="lg" justify="center">
-                            <ProgressStat
-                              color="edr-green"
-                              label="Approved"
-                              value={stats.approved}
-                            />
-                            <ProgressStat
-                              color="red"
-                              label="Queried"
-                              value={stats.queried}
-                            />
-                            <ProgressStat
-                              color="gray"
-                              label="Pending"
-                              value={stats.pending}
-                            />
-                          </Group>
                         </Stack>
                       </SectionCard>
                     </Box>
@@ -457,126 +487,3 @@ export default function ContractClearanceDetailPage() {
   );
 }
 
-function ClearanceHero({
-  contract,
-  stats,
-}: {
-  contract: ReturnType<typeof useContractDetail>["data"];
-  stats: { pct: number; approved: number; total: number };
-}) {
-  const direction = contract?.tradeDirection ?? "—";
-  const serviceName = contract?.serviceType?.serviceName ?? null;
-  const customs =
-    contract?.serviceType?.includesCustoms ??
-    contract?.customsClearingEnabled ??
-    false;
-  const routes = [...(contract?.routes ?? [])].sort(
-    (a, b) => a.sortOrder - b.sortOrder,
-  );
-  const origin =
-    routes[0]?.originYard?.label ?? routes[0]?.originYard?.code ?? "Origin";
-  const last = routes[routes.length - 1] ?? routes[0];
-  const destination =
-    last?.destinationYard?.label ??
-    last?.destinationYard?.code ??
-    "Destination";
-
-  return (
-    <Paper withBorder radius="md" p="lg">
-      <Group justify="space-between" align="flex-start" wrap="wrap" gap="lg">
-        <Group gap="md" wrap="nowrap" style={{ minWidth: 0 }}>
-          <ThemeIcon variant="light" color="edr-green" radius="md" size={52}>
-            <ShieldCheck size={26} />
-          </ThemeIcon>
-          <Box style={{ minWidth: 0 }}>
-            <Group gap={8} wrap="nowrap">
-              <Text fw={800} fz={20} c="edr-text" truncate>
-                {contract?.reference ?? "Clearance"}
-              </Text>
-              <Badge
-                size="sm"
-                variant="light"
-                color={direction === "IMPORT" ? "edr-green" : "gray"}
-                radius="sm"
-              >
-                {directionLabel(direction)}
-              </Badge>
-              {customs ? (
-                <Badge
-                  size="sm"
-                  variant="light"
-                  color="edr-green"
-                  radius="sm"
-                  leftSection={<ShieldCheck size={12} />}
-                >
-                  Customs
-                </Badge>
-              ) : (
-                <Badge size="sm" variant="light" color="gray" radius="sm">
-                  No customs
-                </Badge>
-              )}
-            </Group>
-            {serviceName && (
-              <Text size="sm" fw={600} c="edr-text" mt={6} truncate maw={280}>
-                {serviceName}
-              </Text>
-            )}
-            <Group gap={8} mt={6} wrap="nowrap">
-              <Text size="sm" fw={600} truncate maw={160}>
-                {origin}
-              </Text>
-              <ArrowRight size={15} className="shrink-0 text-muted-foreground" />
-              <Text size="sm" fw={600} truncate maw={160}>
-                {destination}
-              </Text>
-            </Group>
-          </Box>
-        </Group>
-
-        <Box style={{ minWidth: 200, flex: 1, maxWidth: 320 }}>
-          <Group justify="space-between" mb={6}>
-            <Text size="xs" c="dimmed" fw={600}>
-              Document review
-            </Text>
-            <Text size="xs" c="dimmed">
-              {stats.approved}/{stats.total}
-            </Text>
-          </Group>
-          <Progress value={stats.pct} color="edr-green" radius="xl" size="md" />
-        </Box>
-      </Group>
-    </Paper>
-  );
-}
-
-function ProgressStat({
-  color,
-  label,
-  value,
-}: {
-  color: string;
-  label: string;
-  value: number;
-}) {
-  return (
-    <Stack gap={2} align="center">
-      <Text fw={700} fz={18} c="edr-text">
-        {value}
-      </Text>
-      <Group gap={4} wrap="nowrap">
-        <Box
-          style={{
-            width: 7,
-            height: 7,
-            borderRadius: 999,
-            background: `var(--mantine-color-${color}-6)`,
-          }}
-        />
-        <Text fz="11px" c="dimmed">
-          {label}
-        </Text>
-      </Group>
-    </Stack>
-  );
-}
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestDetailPage.tsx
index 8c0ef7b5c..5cb33c62a 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestDetailPage.tsx
@@ -6,9 +6,8 @@ import {
   ArrowLeft,
   ArrowRight,
   Box as BoxIcon,
-  Building2,
-  Calendar,
   CalendarClock,
+  ClipboardList,
   Download,
   FileSignature,
   FileText,
@@ -18,15 +17,16 @@ import {
   Info,
   LayoutGrid,
   Milestone,
+  MoreHorizontal,
   Package,
   Receipt,
   RefreshCw,
   Route as RouteIcon,
-  ShieldCheck,
   Snowflake,
-  Users,
+  Wallet,
 } from "lucide-react";
 import {
+  ActionIcon,
   Alert,
   Badge,
   Box,
@@ -36,21 +36,22 @@ import {
   Grid,
   Group,
   Loader,
+  Menu,
   Paper,
   SimpleGrid,
   Stack,
   Tabs,
   Text,
-  Title,
 } from "@mantine/core";
 
 import toast from "react-hot-toast";
 
-import "@/components/overview/overview.css";
-import { PageContainer } from "@/components/page";
-import Breadcrumbs from "@/components/ui/Breadcrumbs";
+import { PageContainer, PageHeader, KpiStrip } from "@/components/page";
+import type { KpiItem } from "@/components/page";
+import { EntityLink } from "@/components/detail";
 import { SectionCard } from "@/components/bookings/detail/SectionCard";
 import { detailStyles } from "@/components/bookings/detail/booking-detail.styles";
+import { TableCard } from "@/components/customers";
 import {
   ContractCourtBadge,
   ContractStatusBadge,
@@ -60,14 +61,18 @@ import { ContractActionsToolbar } from "@/components/contracts/ContractActionsTo
 import { ContractApprovalStepsCard } from "@/components/contracts/ContractApprovalStepsCard";
 import { HazardDeclarationPanel } from "@/components/contracts/HazardDeclarationPanel";
 import { ClearanceWorkflowFilesPanel } from "@/components/contracts/ClearanceWorkflowFilesPanel";
+import { BookingRequestStatusBadge } from "@/components/contracts/BookingRequestStatusBadge";
 import { ContractRevisionTimeline } from "@/components/contracts/ContractRevisionTimeline";
 import { ContractMilestonesTimeline } from "@/components/contracts/ContractMilestonesTimeline";
 import {
   ContractCustomerCard,
   ContractDocumentsCard,
 } from "@/components/contracts/detail/ContractDetailTabCards";
+import { BookingStatusBadge } from "@/components/bookings/BookingStatusBadge";
 import { getContractStatusMeta } from "@/features/contracts/contract-status.config";
+import { toBookingListRow } from "@/features/bookings/mapBookingListRow";
 import { useFileViewer } from "@/hooks/useFileViewer";
+import { useBookingList } from "@/hooks/bookings/useBookings";
 import {
   useContractDetail,
   useContractMutations,
@@ -75,11 +80,14 @@ import {
 import { contractsService } from "@/services/contracts.service";
 import { api } from "@/services/api";
 import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
+import { formatMoney } from "@/components/customers";
 import {
   downloadBookingFile,
   fetchViewableFile,
 } from "@/services/files.service";
 import type { CustomerDocument } from "@/types/customer";
+import type { BookingDetail } from "@/types/booking";
+import { DataTable, type ColumnDef } from "@edr/ui-common";
 import type { Freight } from "@edr/types";
 
 // Clearance phase — actionable (docs approve / query / finalize on the hub).
@@ -147,11 +155,11 @@ export default function ContractRequestDetailPage() {
   const [searchParams, setSearchParams] = useSearchParams();
   const { view, viewer } = useFileViewer();
   const requestedTab = searchParams.get("tab");
-  const setTab = (tab: string) =>
+  const setTab = (tab: string | null) =>
     setSearchParams(
       (prev) => {
         const next = new URLSearchParams(prev);
-        if (tab === "details") next.delete("tab");
+        if (!tab || tab === "details") next.delete("tab");
         else next.set("tab", tab);
         return next;
       },
@@ -212,6 +220,18 @@ export default function ContractRequestDetailPage() {
       }) satisfies NonNullable<Freight.IContract["files"]>[number],
   );
 
+  // Bookings drawn down under this contract, and the customer's raw shipment
+  // requests against it — the two halves of "what has this contract produced".
+  const { data: contractBookings, isLoading: bookingsLoading } = useBookingList(
+    { contractId: id, pageSize: 100 },
+    Boolean(id),
+  );
+  const bookingRequestsQuery = useQuery({
+    queryKey: QUERY_KEYS.CONTRACTS.bookingRequests(id ?? ""),
+    queryFn: () => contractsService.listBookingRequests(id!),
+    enabled: Boolean(id),
+  });
+
   const downloadContractPdf = async () => {
     if (!contract?.id) return;
     try {
@@ -313,12 +333,12 @@ export default function ContractRequestDetailPage() {
       contract.status === "SIGNED_CUSTOMER") &&
     Boolean(contract.contractGeneratedAt);
   // Resolve the active tab from the URL, falling back to details when the
-  // requested tab isn't available for this contract (e.g. clearance pre-phase).
+  // requested tab isn't available for this contract.
   const currentTab =
-    requestedTab === "documents"
-      ? "documents"
-      : requestedTab === "customer"
-        ? "customer"
+    requestedTab === "shipments"
+      ? "shipments"
+      : requestedTab === "documents"
+        ? "documents"
         : requestedTab === "history"
           ? "history"
           : "details";
@@ -327,98 +347,111 @@ export default function ContractRequestDetailPage() {
     ? (contract.governmentInstitution ?? "Government")
     : (contract.company?.name ?? "—");
 
+  const kpis: KpiItem[] = [
+    {
+      label: "Shipments",
+      value: contract.activeBookingCount ?? 0,
+      hint: "active",
+      icon: Package,
+      color: "edr-green",
+    },
+    {
+      label: "Valid until",
+      value: contract.contractValidUntil ? formatDate(contract.contractValidUntil) : "—",
+      icon: CalendarClock,
+      color: "blue",
+    },
+    {
+      label: "Routes",
+      value: routes.length,
+      icon: RouteIcon,
+      color: "teal",
+    },
+    {
+      label: "Currency",
+      value: contract.paymentCurrency,
+      icon: Wallet,
+      color: "orange",
+    },
+  ];
+
   return (
     <PageContainer>
-      <Breadcrumbs
-        items={[
+      <PageHeader
+        breadcrumbs={[
           { label: "Contract requests", href: "/dashboard/contract-requests" },
           { label: contract.reference },
         ]}
-      />
-
-      <Stack gap="lg">
-        {/* Hero */}
-        <Paper radius="xl" p="xl" style={{ position: "relative", overflow: "hidden" }}>
-          <Stack gap="lg">
-            <Group justify="space-between" align="flex-start" wrap="wrap">
-              <Button
-                variant="default"
-                size="compact-sm"
-                radius="lg"
-                leftSection={<ArrowLeft size={16} />}
-                onClick={() => navigate("/dashboard/contract-requests")}
-              >
-                Back to list
-              </Button>
-              <Button
-                variant="light"
-                color="edr-green"
-                size="compact-sm"
-                radius="lg"
-                leftSection={<RefreshCw size={15} />}
-                loading={isFetching}
-                onClick={() => refetch()}
-              >
-                Refresh
-              </Button>
-            </Group>
-
-            <Stack gap="sm">
-              <Text
-                size="xs"
-                fw={700}
-                tt="uppercase"
-                style={{ letterSpacing: 1, color: "#B26C09" }}
-              >
-                Contract reference
-              </Text>
-              <Group gap="sm" align="center" wrap="wrap">
-                <Title order={2} fw={700} style={{ letterSpacing: "-0.4px" }}>
-                  {contract.reference}
-                </Title>
-                <ContractStatusBadge
-                  status={contract.status}
-                  isRenewal={Boolean(contract.renewalOfId)}
-                />
-                <ContractCourtBadge status={contract.status} />
-                <Badge variant="light" color="gray" radius="sm" tt="uppercase">
-                  {contract.contractKind === "GENERAL" ? "General" : "One-time"}
-                </Badge>
-              </Group>
-              <Group gap="lg" mt={4}>
-                <MetaItem icon={Building2} text={customerLabel} />
-                <MetaItem
-                  icon={Calendar}
-                  text={`Created ${formatDate(contract.createdAt)}`}
-                />
-                {contract.contractValidUntil ? (
-                  <MetaItem
-                    icon={CalendarClock}
-                    // Validity is accepted to the minute — show the time.
-                    text={`Valid until ${formatDateTime(contract.contractValidUntil)}`}
-                  />
-                ) : null}
-              </Group>
-              {hasContractDocument && (
-                <Group gap="sm" mt="sm">
+        backTo="/dashboard/contract-requests"
+        title={contract.reference}
+        meta={
+          <Group gap={6} wrap="wrap">
+            <ContractStatusBadge
+              status={contract.status}
+              isRenewal={Boolean(contract.renewalOfId)}
+            />
+            <ContractCourtBadge status={contract.status} />
+            <Badge variant="light" color="gray" radius="sm" tt="uppercase">
+              {contract.contractKind === "GENERAL" ? "General" : "One-time"}
+            </Badge>
+          </Group>
+        }
+        subtitle={
+          <Group gap={6} wrap="wrap">
+            <EntityLink
+              to={
+                !contract.isGovernment && contract.companyId
+                  ? `/dashboard/customers/${contract.companyId}`
+                  : null
+              }
+              label={customerLabel}
+            />
+            <Text size="sm" c="dimmed">
+              · Created {formatDate(contract.createdAt)}
+              {contract.contractValidUntil
+                ? ` · Valid until ${formatDateTime(contract.contractValidUntil)}`
+                : ""}
+            </Text>
+          </Group>
+        }
+        action={
+          <Group gap="sm" wrap="nowrap">
+            <ActionIcon
+              variant="light"
+              color="edr-green"
+              size="lg"
+              radius="md"
+              loading={isFetching}
+              aria-label="Refresh"
+              onClick={() => refetch()}
+            >
+              <RefreshCw size={16} />
+            </ActionIcon>
+            {hasContractDocument && (
+              <Menu position="bottom-end" width={240} withinPortal>
+                <Menu.Target>
+                  <ActionIcon
+                    variant="default"
+                    size="lg"
+                    radius="md"
+                    aria-label="More actions"
+                  >
+                    <MoreHorizontal size={16} />
+                  </ActionIcon>
+                </Menu.Target>
+                <Menu.Dropdown>
                   {canViewSign && (
-                    <Button
-                      color="edr-green"
-                      size="compact-sm"
-                      radius="lg"
+                    <Menu.Item
                       leftSection={<FileSignature size={15} />}
                       onClick={() =>
                         navigate(`/dashboard/contract-requests/${contract.id}/view`)
                       }
                     >
                       View &amp; sign contract
-                    </Button>
+                    </Menu.Item>
                   )}
                   {contractPdf && (
-                    <Button
-                      variant="default"
-                      size="compact-sm"
-                      radius="lg"
+                    <Menu.Item
                       leftSection={<FileText size={15} />}
                       onClick={() =>
                         void fetchViewableFile(contractPdf.id, contractPdf.name).then(
@@ -427,22 +460,23 @@ export default function ContractRequestDetailPage() {
                       }
                     >
                       View contract
-                    </Button>
+                    </Menu.Item>
                   )}
-                  <Button
-                    variant="default"
-                    size="compact-sm"
-                    radius="lg"
+                  <Menu.Item
                     leftSection={<Download size={15} />}
                     onClick={() => void downloadContractPdf()}
                   >
                     Download PDF
-                  </Button>
-                </Group>
-              )}
-            </Stack>
-          </Stack>
-        </Paper>
+                  </Menu.Item>
+                </Menu.Dropdown>
+              </Menu>
+            )}
+          </Group>
+        }
+      />
+
+      <Stack gap="lg">
+        <KpiStrip items={kpis} />
 
         <ContractWorkflowStepper
           status={contract.status}
@@ -505,71 +539,375 @@ export default function ContractRequestDetailPage() {
           </Alert>
         ) : null}
 
-        <Tabs
-          value={currentTab}
-          onChange={(v) => setTab(v ?? "details")}
-          variant="pills"
-          color="edr-green"
-          classNames={{ list: "ov-tablist", tab: "ov-tab" }}
-        >
-          <Tabs.List>
-            <Tabs.Tab value="details" leftSection={<LayoutGrid size={16} />}>
-              Details
-            </Tabs.Tab>
-            <Tabs.Tab
-              value="documents"
-              leftSection={<Files size={16} />}
-              rightSection={
-                contractDocuments.length + profileDocuments.length > 0 ? (
-                  <Badge size="xs" variant="light" color="gray" radius="sm">
-                    {contractDocuments.length + profileDocuments.length}
-                  </Badge>
-                ) : null
-              }
-            >
-              Documents
-            </Tabs.Tab>
-            <Tabs.Tab value="customer" leftSection={<Users size={16} />}>
-              Customer
-            </Tabs.Tab>
-            <Tabs.Tab value="history" leftSection={<History size={16} />}>
-              History
-            </Tabs.Tab>
-          </Tabs.List>
-        </Tabs>
-
         <Grid gap="lg">
           {/* LEFT — primary content */}
           <Grid.Col span={{ base: 12, lg: 8 }}>
-            {currentTab === "documents" ? (
-              <Stack gap="lg">
-                <ContractDocumentsCard
-                  files={contractDocuments}
-                  onView={handleViewFile}
-                  onDownload={handleDownloadFile}
-                />
-                <ContractDocumentsCard
-                  files={profileDocuments}
-                  title="Customer profile documents"
-                  emptyText={
-                    profileDocumentsQuery.isLoading
-                      ? "Loading customer documents…"
-                      : "No profile documents on file for this customer."
+            <Tabs
+              value={currentTab}
+              onChange={setTab}
+              variant="pills"
+              color="edr-green"
+              keepMounted={false}
+            >
+              <Tabs.List mb="lg">
+                <Tabs.Tab value="details" leftSection={<LayoutGrid size={16} />}>
+                  Details
+                </Tabs.Tab>
+                <Tabs.Tab value="shipments" leftSection={<Package size={16} />}>
+                  Shipments
+                </Tabs.Tab>
+                <Tabs.Tab
+                  value="documents"
+                  leftSection={<Files size={16} />}
+                  rightSection={
+                    contractDocuments.length + profileDocuments.length > 0 ? (
+                      <Badge size="xs" variant="light" color="gray" radius="sm">
+                        {contractDocuments.length + profileDocuments.length}
+                      </Badge>
+                    ) : null
                   }
-                  onView={handleViewFile}
-                  onDownload={handleDownloadFile}
-                />
-                {(clearanceView?.workflowFiles?.length ?? 0) > 0 ? (
-                  <ClearanceWorkflowFilesPanel
-                    files={clearanceView!.workflowFiles!}
-                    title="Customs workflow documents"
-                    onView={view}
-                    onDownload={(f) => void handleDownloadFile({ id: f.id, name: f.name } as never)}
+                >
+                  Documents
+                </Tabs.Tab>
+                <Tabs.Tab value="history" leftSection={<History size={16} />}>
+                  History
+                </Tabs.Tab>
+              </Tabs.List>
+
+              <Tabs.Panel value="details">
+                <Stack gap="lg">
+                  <SectionCard
+                    icon={Info}
+                    title="Contract information"
+                    subtitle="Full commercial and operational detail for this contract."
+                  >
+                    <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="lg">
+                      <InfoRow
+                        label="Service type"
+                        value={contract.serviceType?.serviceName ?? "—"}
+                      />
+                      <InfoRow
+                        label="Payment currency"
+                        value={contract.paymentCurrency ?? "—"}
+                      />
+                      <InfoRow
+                        label="Customs clearing"
+                        value={
+                          contract.customsClearingEnabled
+                            ? "Included automatically"
+                            : contract.customsClearingAgent
+                              ? `Customer's agent — ${contract.customsClearingAgent}`
+                              : "Not included"
+                        }
+                      />
+                      {contract.equipmentReturn ? (
+                        <InfoRow
+                          label="Equipment return"
+                          value={
+                            contract.equipmentReturn === "WITH_RETURN"
+                              ? "With return"
+                              : "Without return"
+                          }
+                        />
+                      ) : null}
+                      <InfoRow
+                        label="Contract type"
+                        value={contract.contractType ?? "Standard"}
+                      />
+                      {contract.contractValidityDays != null ? (
+                        <InfoRow
+                          label="Validity period"
+                          value={`${contract.contractValidityDays} days`}
+                        />
+                      ) : null}
+                      {contract.estimatedShipmentDate ? (
+                        <InfoRow
+                          label="Estimated shipment date"
+                          value={formatDate(contract.estimatedShipmentDate)}
+                        />
+                      ) : null}
+                      {contract.firstMilePickupAddress ? (
+                        <InfoRow
+                          label="First-mile pickup"
+                          value={contract.firstMilePickupAddress}
+                        />
+                      ) : null}
+                      {contract.lastMileDeliveryAddress ? (
+                        <InfoRow
+                          label="Last-mile delivery"
+                          value={contract.lastMileDeliveryAddress}
+                        />
+                      ) : null}
+                    </SimpleGrid>
+                    {contract.financialTerms ? (
+                      <Box
+                        mt="md"
+                        pt="md"
+                        style={{ borderTop: "1px solid var(--mantine-color-gray-2)" }}
+                      >
+                        <Text
+                          size="xs"
+                          c="dimmed"
+                          fw={600}
+                          tt="uppercase"
+                          mb={4}
+                          style={{ letterSpacing: 0.3 }}
+                        >
+                          Financial terms
+                        </Text>
+                        <Text size="sm" style={{ whiteSpace: "pre-wrap" }}>
+                          {contract.financialTerms}
+                        </Text>
+                      </Box>
+                    ) : null}
+                  </SectionCard>
+
+                  <SectionCard icon={RouteIcon} title="Routes">
+                    {routes.length === 0 ? (
+                      <Text size="sm" c="dimmed">
+                        No routes on this contract.
+                      </Text>
+                    ) : (
+                      <Stack gap="sm">
+                        {routes.map((r) => (
+                          <Group
+                            key={r.id}
+                            justify="space-between"
+                            wrap="nowrap"
+                            px="sm"
+                            py="xs"
+                            style={{
+                              borderRadius: 8,
+                              border: "1px solid var(--mantine-color-gray-2)",
+                            }}
+                          >
+                            <Group gap={8} wrap="nowrap" style={{ minWidth: 0 }}>
+                              <Text size="sm" fw={600} truncate maw={160}>
+                                {r.originYard?.label ??
+                                  r.originYard?.code ??
+                                  "Origin"}
+                              </Text>
+                              <ArrowRight
+                                size={15}
+                                className="shrink-0 text-muted-foreground"
+                              />
+                              <Text size="sm" fw={600} truncate maw={160}>
+                                {r.destinationYard?.label ??
+                                  r.destinationYard?.code ??
+                                  "Destination"}
+                              </Text>
+                            </Group>
+                            {r.km != null ? (
+                              <Badge variant="light" color="gray" radius="sm">
+                                {r.km} km
+                              </Badge>
+                            ) : null}
+                          </Group>
+                        ))}
+                      </Stack>
+                    )}
+                  </SectionCard>
+
+                  <SectionCard icon={Package} title="Cargo scope">
+                    <Group gap="sm" mb="md">
+                      <Badge variant="light" color="gray" radius="sm" tt="uppercase">
+                        {directionLabel(contract.tradeDirection)}
+                      </Badge>
+                      <Badge variant="light" color="gray" radius="sm" tt="uppercase">
+                        {contract.freightType}
+                      </Badge>
+                      {contract.isHazardous ? (
+                        <Badge
+                          variant="light"
+                          color="orange"
+                          radius="sm"
+                          leftSection={<Flame size={12} />}
+                        >
+                          Hazardous
+                        </Badge>
+                      ) : null}
+                      {contract.isReefer ? (
+                        <Badge
+                          variant="light"
+                          color="cyan"
+                          radius="sm"
+                          leftSection={<Snowflake size={12} />}
+                        >
+                          Reefer
+                        </Badge>
+                      ) : null}
+                    </Group>
+                    {contract.isHazardous ? (
+                      <Box mb="md">
+                        <HazardDeclarationPanel contract={contract} />
+                      </Box>
+                    ) : null}
+                    {(contract.cargoScope ?? []).length === 0 ? (
+                      <Text size="sm" c="dimmed">
+                        No cargo scope lines.
+                      </Text>
+                    ) : (
+                      <Stack gap="sm">
+                        {(contract.cargoScope ?? []).map((s) => {
+                          const isContainer = Boolean(s.containerSize);
+                          // Bulk lines carry their commodity detail (name + unit);
+                          // container lines carry the size (20ft / 40ft).
+                          const title = isContainer
+                            ? `${s.containerSize} container`
+                            : (s.cargoType?.cargoTypeName ??
+                              s.cargoFreeText ??
+                              s.cargoType?.code ??
+                              "Bulk cargo");
+                          // quantityCap unit: containers for a size line, else the
+                          // cargo type's unit of measure (tons / items / …), default tons.
+                          const capUnit = isContainer
+                            ? "containers"
+                            : (s.cargoType?.unitOfMeasure?.toLowerCase() ?? "tons");
+                          return (
+                            <Group key={s.id} gap={8} wrap="nowrap" align="flex-start">
+                              <BoxIcon
+                                size={15}
+                                color="var(--mantine-color-edr-green-6)"
+                                style={{ marginTop: 2, flexShrink: 0 }}
+                              />
+                              <div>
+                                <Text size="sm" fw={500}>
+                                  {title}
+                                </Text>
+                                <Group gap={6} mt={2}>
+                                  <Badge
+                                    variant="light"
+                                    color={isContainer ? "blue" : "grape"}
+                                    radius="sm"
+                                    size="xs"
+                                    tt="uppercase"
+                                  >
+                                    {isContainer ? "Container" : "Bulk"}
+                                  </Badge>
+                                  {s.cargoType?.code ? (
+                                    <Text size="xs" c="dimmed">
+                                      Code: {s.cargoType.code}
+                                    </Text>
+                                  ) : null}
+                                  <Text size="xs" c="dimmed">
+                                    {s.quantityCap != null
+                                      ? `Cap: ${s.quantityCap} ${capUnit}`
+                                      : "Cap: uncapped"}
+                                  </Text>
+                                </Group>
+                              </div>
+                            </Group>
+                          );
+                        })}
+                      </Stack>
+                    )}
+                  </SectionCard>
+
+                  {contract.pricingBreakdown?.lineItems?.length ? (
+                    <SectionCard icon={Receipt} title="Unit rates">
+                      <Stack gap="xs">
+                        {contract.pricingBreakdown.lineItems.map((li) => (
+                          <Group
+                            key={li.code}
+                            justify="space-between"
+                            wrap="nowrap"
+                          >
+                            <Text size="sm" truncate>
+                              {li.label}
+                              {li.containerSize ? ` · ${li.containerSize}` : ""}
+                            </Text>
+                            <Text size="sm" fw={600}>
+                              {contract.pricingBreakdown?.currency} {li.unitPrice} /{" "}
+                              {li.unit}
+                            </Text>
+                          </Group>
+                        ))}
+                      </Stack>
+                    </SectionCard>
+                  ) : null}
+
+                  {contract.contractSummary ? (
+                    <SectionCard icon={FileText} title="Contract summary">
+                      <Text size="sm" style={{ whiteSpace: "pre-wrap" }}>
+                        {contract.contractSummary}
+                      </Text>
+                    </SectionCard>
+                  ) : null}
+                </Stack>
+              </Tabs.Panel>
+
+              <Tabs.Panel value="shipments">
+                <Stack gap="lg">
+                  <SectionCard
+                    icon={Package}
+                    title="Bookings"
+                    subtitle="Shipments drawn down under this contract."
+                  >
+                    <TableCard minWidth={760}>
+                      <DataTable
+                        columns={bookingColumns}
+                        data={contractBookings?.items ?? []}
+                        status={bookingsLoading ? "loading" : "success"}
+                        emptyMessage="No bookings under this contract yet."
+                        containerClassName="border-0 shadow-none bg-transparent"
+                        onRowClick={(row) =>
+                          navigate(`/dashboard/booking-requests/${row.id}`)
+                        }
+                      />
+                    </TableCard>
+                  </SectionCard>
+
+                  <SectionCard
+                    icon={ClipboardList}
+                    title="Shipment requests"
+                    subtitle="Customer-submitted requests against this contract, before they become a booking."
+                  >
+                    <TableCard minWidth={640}>
+                      <DataTable
+                        columns={requestColumns}
+                        data={bookingRequestsQuery.data ?? []}
+                        status={bookingRequestsQuery.isLoading ? "loading" : "success"}
+                        emptyMessage="No shipment requests on this contract yet."
+                        containerClassName="border-0 shadow-none bg-transparent"
+                        onRowClick={(row) =>
+                          navigate(`/dashboard/shipment-requests/${row.id}`)
+                        }
+                      />
+                    </TableCard>
+                  </SectionCard>
+                </Stack>
+              </Tabs.Panel>
+
+              <Tabs.Panel value="documents">
+                <Stack gap="lg">
+                  <ContractDocumentsCard
+                    files={contractDocuments}
+                    onView={handleViewFile}
+                    onDownload={handleDownloadFile}
                   />
-                ) : null}
-              </Stack>
-            ) : currentTab === "history" ? (
-              <Stack gap="lg">
+                  <ContractDocumentsCard
+                    files={profileDocuments}
+                    title="Customer profile documents"
+                    emptyText={
+                      profileDocumentsQuery.isLoading
+                        ? "Loading customer documents…"
+                        : "No profile documents on file for this customer."
+                    }
+                    onView={handleViewFile}
+                    onDownload={handleDownloadFile}
+                  />
+                  {(clearanceView?.workflowFiles?.length ?? 0) > 0 ? (
+                    <ClearanceWorkflowFilesPanel
+                      files={clearanceView!.workflowFiles!}
+                      title="Customs workflow documents"
+                      onView={view}
+                      onDownload={(f) => void handleDownloadFile({ id: f.id, name: f.name } as never)}
+                    />
+                  ) : null}
+                </Stack>
+              </Tabs.Panel>
+
+              <Tabs.Panel value="history">
                 <SectionCard
                   icon={Milestone}
                   title="Key milestones"
@@ -577,291 +915,24 @@ export default function ContractRequestDetailPage() {
                 >
                   <ContractMilestonesTimeline contract={contract} />
                 </SectionCard>
-                <SectionCard
-                  icon={History}
-                  title="Change history"
-                  subtitle="Every recorded edit to this contract — who changed what, and when."
-                >
-                  <ContractRevisionTimeline contractId={contract.id} bare />
-                </SectionCard>
-              </Stack>
-            ) : currentTab === "customer" ? (
-              <ContractCustomerCard contract={contract} />
-            ) : (
-            <Stack gap="lg">
-              <SectionCard
-                icon={Info}
-                title="Contract information"
-                subtitle="Full commercial and operational detail for this contract."
-              >
-                <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="lg">
-                  <InfoRow
-                    label="Service type"
-                    value={contract.serviceType?.serviceName ?? "—"}
-                  />
-                  <InfoRow
-                    label="Payment currency"
-                    value={contract.paymentCurrency ?? "—"}
-                  />
-                  <InfoRow
-                    label="Customs clearing"
-                    value={
-                      contract.customsClearingEnabled
-                        ? "Included automatically"
-                        : contract.customsClearingAgent
-                          ? `Customer's agent — ${contract.customsClearingAgent}`
-                          : "Not included"
-                    }
-                  />
-                  {contract.equipmentReturn ? (
-                    <InfoRow
-                      label="Equipment return"
-                      value={
-                        contract.equipmentReturn === "WITH_RETURN"
-                          ? "With return"
-                          : "Without return"
-                      }
-                    />
-                  ) : null}
-                  <InfoRow
-                    label="Contract type"
-                    value={contract.contractType ?? "Standard"}
-                  />
-                  {contract.contractValidityDays != null ? (
-                    <InfoRow
-                      label="Validity period"
-                      value={`${contract.contractValidityDays} days`}
-                    />
-                  ) : null}
-                  {contract.estimatedShipmentDate ? (
-                    <InfoRow
-                      label="Estimated shipment date"
-                      value={formatDate(contract.estimatedShipmentDate)}
-                    />
-                  ) : null}
-                  {contract.firstMilePickupAddress ? (
-                    <InfoRow
-                      label="First-mile pickup"
-                      value={contract.firstMilePickupAddress}
-                    />
-                  ) : null}
-                  {contract.lastMileDeliveryAddress ? (
-                    <InfoRow
-                      label="Last-mile delivery"
-                      value={contract.lastMileDeliveryAddress}
-                    />
-                  ) : null}
-                </SimpleGrid>
-                {contract.financialTerms ? (
-                  <Box
-                    mt="md"
-                    pt="md"
-                    style={{ borderTop: "1px solid var(--mantine-color-gray-2)" }}
+                <Box mt="lg">
+                  <SectionCard
+                    icon={History}
+                    title="Change history"
+                    subtitle="Every recorded edit to this contract — who changed what, and when."
                   >
-                    <Text
-                      size="xs"
-                      c="dimmed"
-                      fw={600}
-                      tt="uppercase"
-                      mb={4}
-                      style={{ letterSpacing: 0.3 }}
-                    >
-                      Financial terms
-                    </Text>
-                    <Text size="sm" style={{ whiteSpace: "pre-wrap" }}>
-                      {contract.financialTerms}
-                    </Text>
-                  </Box>
-                ) : null}
-              </SectionCard>
-
-              <SectionCard
-                icon={ShieldCheck}
-                title="Approval & signing timeline"
-                subtitle="Every dated step in this contract's approval chain, plus signatures — the same record kept in the sidebar, always visible here."
-              >
-                <ContractMilestonesTimeline contract={contract} />
-              </SectionCard>
-
-              <SectionCard icon={RouteIcon} title="Routes">
-                {routes.length === 0 ? (
-                  <Text size="sm" c="dimmed">
-                    No routes on this contract.
-                  </Text>
-                ) : (
-                  <Stack gap="sm">
-                    {routes.map((r) => (
-                      <Group
-                        key={r.id}
-                        justify="space-between"
-                        wrap="nowrap"
-                        px="sm"
-                        py="xs"
-                        style={{
-                          borderRadius: 8,
-                          border: "1px solid var(--mantine-color-gray-2)",
-                        }}
-                      >
-                        <Group gap={8} wrap="nowrap" style={{ minWidth: 0 }}>
-                          <Text size="sm" fw={600} truncate maw={160}>
-                            {r.originYard?.label ??
-                              r.originYard?.code ??
-                              "Origin"}
-                          </Text>
-                          <ArrowRight
-                            size={15}
-                            className="shrink-0 text-muted-foreground"
-                          />
-                          <Text size="sm" fw={600} truncate maw={160}>
-                            {r.destinationYard?.label ??
-                              r.destinationYard?.code ??
-                              "Destination"}
-                          </Text>
-                        </Group>
-                        {r.km != null ? (
-                          <Badge variant="light" color="gray" radius="sm">
-                            {r.km} km
-                          </Badge>
-                        ) : null}
-                      </Group>
-                    ))}
-                  </Stack>
-                )}
-              </SectionCard>
-
-              <SectionCard icon={Package} title="Cargo scope">
-                <Group gap="sm" mb="md">
-                  <Badge variant="light" color="gray" radius="sm" tt="uppercase">
-                    {directionLabel(contract.tradeDirection)}
-                  </Badge>
-                  <Badge variant="light" color="gray" radius="sm" tt="uppercase">
-                    {contract.freightType}
-                  </Badge>
-                  {contract.isHazardous ? (
-                    <Badge
-                      variant="light"
-                      color="orange"
-                      radius="sm"
-                      leftSection={<Flame size={12} />}
-                    >
-                      Hazardous
-                    </Badge>
-                  ) : null}
-                  {contract.isReefer ? (
-                    <Badge
-                      variant="light"
-                      color="cyan"
-                      radius="sm"
-                      leftSection={<Snowflake size={12} />}
-                    >
-                      Reefer
-                    </Badge>
-                  ) : null}
-                </Group>
-                {contract.isHazardous ? (
-                  <Box mb="md">
-                    <HazardDeclarationPanel contract={contract} />
-                  </Box>
-                ) : null}
-                {(contract.cargoScope ?? []).length === 0 ? (
-                  <Text size="sm" c="dimmed">
-                    No cargo scope lines.
-                  </Text>
-                ) : (
-                  <Stack gap="sm">
-                    {(contract.cargoScope ?? []).map((s) => {
-                      const isContainer = Boolean(s.containerSize);
-                      // Bulk lines carry their commodity detail (name + unit);
-                      // container lines carry the size (20ft / 40ft).
-                      const title = isContainer
-                        ? `${s.containerSize} container`
-                        : (s.cargoType?.cargoTypeName ??
-                          s.cargoFreeText ??
-                          s.cargoType?.code ??
-                          "Bulk cargo");
-                      // quantityCap unit: containers for a size line, else the
-                      // cargo type's unit of measure (tons / items / …), default tons.
-                      const capUnit = isContainer
-                        ? "containers"
-                        : (s.cargoType?.unitOfMeasure?.toLowerCase() ?? "tons");
-                      return (
-                        <Group key={s.id} gap={8} wrap="nowrap" align="flex-start">
-                          <BoxIcon
-                            size={15}
-                            color="var(--mantine-color-edr-green-6)"
-                            style={{ marginTop: 2, flexShrink: 0 }}
-                          />
-                          <div>
-                            <Text size="sm" fw={500}>
-                              {title}
-                            </Text>
-                            <Group gap={6} mt={2}>
-                              <Badge
-                                variant="light"
-                                color={isContainer ? "blue" : "grape"}
-                                radius="sm"
-                                size="xs"
-                                tt="uppercase"
-                              >
-                                {isContainer ? "Container" : "Bulk"}
-                              </Badge>
-                              {s.cargoType?.code ? (
-                                <Text size="xs" c="dimmed">
-                                  Code: {s.cargoType.code}
-                                </Text>
-                              ) : null}
-                              <Text size="xs" c="dimmed">
-                                {s.quantityCap != null
-                                  ? `Cap: ${s.quantityCap} ${capUnit}`
-                                  : "Cap: uncapped"}
-                              </Text>
-                            </Group>
-                          </div>
-                        </Group>
-                      );
-                    })}
-                  </Stack>
-                )}
-              </SectionCard>
-
-              {contract.pricingBreakdown?.lineItems?.length ? (
-                <SectionCard icon={Receipt} title="Unit rates">
-                  <Stack gap="xs">
-                    {contract.pricingBreakdown.lineItems.map((li) => (
-                      <Group
-                        key={li.code}
-                        justify="space-between"
-                        wrap="nowrap"
-                      >
-                        <Text size="sm" truncate>
-                          {li.label}
-                          {li.containerSize ? ` · ${li.containerSize}` : ""}
-                        </Text>
-                        <Text size="sm" fw={600}>
-                          {contract.pricingBreakdown?.currency} {li.unitPrice} /{" "}
-                          {li.unit}
-                        </Text>
-                      </Group>
-                    ))}
-                  </Stack>
-                </SectionCard>
-              ) : null}
-
-              {contract.contractSummary ? (
-                <SectionCard icon={FileText} title="Contract summary">
-                  <Text size="sm" style={{ whiteSpace: "pre-wrap" }}>
-                    {contract.contractSummary}
-                  </Text>
-                </SectionCard>
-              ) : null}
-            </Stack>
-            )}
+                    <ContractRevisionTimeline contractId={contract.id} bare />
+                  </SectionCard>
+                </Box>
+              </Tabs.Panel>
+            </Tabs>
           </Grid.Col>
 
           {/* RIGHT — sticky action rail */}
           <Grid.Col span={{ base: 12, lg: 4 }}>
             <Box style={{ position: "sticky", top: 24 }}>
               <Stack gap="lg">
+                <ContractCustomerCard contract={contract} />
                 <ContractActionsToolbar
                   contract={contract}
                   mutations={mutations}
@@ -891,6 +962,97 @@ export default function ContractRequestDetailPage() {
   );
 }
 
+const bookingColumns: ColumnDef<BookingDetail>[] = [
+  {
+    id: "reference",
+    header: "Booking",
+    cell: ({ row }) => (
+      <Text size="sm" fw={600} c="edr-text">
+        {row.original.reference}
+      </Text>
+    ),
+  },
+  {
+    id: "route",
+    header: "Route",
+    cell: ({ row }) => {
+      const r = toBookingListRow(row.original);
+      return (
+        <Group gap={6} wrap="nowrap">
+          <Text size="sm" c="edr-text">
+            {r.originLabel}
+          </Text>
+          <ArrowRight size={14} className="shrink-0 text-muted-foreground" />
+          <Text size="sm" c="edr-text">
+            {r.destinationLabel}
+          </Text>
+        </Group>
+      );
+    },
+  },
+  {
+    id: "status",
+    header: "Status",
+    cell: ({ row }) => <BookingStatusBadge status={row.original.status} />,
+  },
+  {
+    id: "amount",
+    header: "Amount",
+    meta: { headerClassName: "text-right", cellClassName: "text-right" },
+    cell: ({ row }) => (
+      <Text size="sm" fw={600} c="edr-text">
+        {formatMoney(Number(row.original.totalAmount), row.original.paymentCurrency)}
+      </Text>
+    ),
+  },
+  {
+    id: "createdAt",
+    header: "Created",
+    meta: { headerClassName: "text-right", cellClassName: "text-right" },
+    cell: ({ row }) => (
+      <Text size="sm" c="dimmed">
+        {formatDate(row.original.createdAt)}
+      </Text>
+    ),
+  },
+];
+
+const requestColumns: ColumnDef<Freight.IBookingRequest>[] = [
+  {
+    id: "reference",
+    header: "Request",
+    cell: ({ row }) => (
+      <Text size="sm" fw={600} c="edr-text">
+        {row.original.reference}
+      </Text>
+    ),
+  },
+  {
+    id: "status",
+    header: "Status",
+    cell: ({ row }) => <BookingRequestStatusBadge status={row.original.status} />,
+  },
+  {
+    id: "scheduledDate",
+    header: "Requested for",
+    cell: ({ row }) => (
+      <Text size="sm" c="dimmed">
+        {row.original.scheduledDate ? formatDate(row.original.scheduledDate) : "—"}
+      </Text>
+    ),
+  },
+  {
+    id: "createdAt",
+    header: "Submitted",
+    meta: { headerClassName: "text-right", cellClassName: "text-right" },
+    cell: ({ row }) => (
+      <Text size="sm" c="dimmed">
+        {formatDate(row.original.createdAt)}
+      </Text>
+    ),
+  },
+];
+
 function InfoRow({ label, value }: { label: string; value: string }) {
   return (
     <div>
@@ -909,20 +1071,3 @@ function InfoRow({ label, value }: { label: string; value: string }) {
     </div>
   );
 }
-
-function MetaItem({
-  icon: Icon,
-  text,
-}: {
-  icon: typeof Building2;
-  text: string;
-}) {
-  return (
-    <Group gap={6} wrap="nowrap">
-      <Icon size={14} color="var(--mantine-color-gray-5)" />
-      <Text size="sm" fw={600} c="dark">
-        {text}
-      </Text>
-    </Group>
-  );
-}
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/GlClearanceDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/GlClearanceDetailPage.tsx
index a501cd50a..76e0ff4ad 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/GlClearanceDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/GlClearanceDetailPage.tsx
@@ -29,9 +29,10 @@ import { useAuth } from "@/auth/useAuth";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import type { BookingDetail } from "@/types/booking";
 
-import { PageContainer } from "@/components/page/PageContainer";
-import { PageHeader } from "@/components/page/PageHeader";
+import { PageContainer, PageHeader } from "@/components/page";
+import { EntityLink } from "@/components/detail";
 import { ClearanceReviewSection } from "@/components/bookings/detail/ClearanceReviewSection";
+import { BookingCompanyCard } from "@/components/bookings/detail/BookingCompanyCard";
 import { ContractClearanceReviewSection } from "@/components/contracts/ContractClearanceReviewSection";
 import { ClearanceWorkflowFilesPanel } from "@/components/contracts/ClearanceWorkflowFilesPanel";
 import { GlExchangePanel } from "@/components/contracts/GlExchangePanel";
@@ -42,6 +43,7 @@ import {
 import { PhasedClearanceActionPanel } from "@/components/contracts/PhasedClearanceActionPanel";
 import { TransitAssigneePanel } from "@/components/contracts/TransitAssigneePanel";
 import { SectionCard } from "@/components/bookings/detail/SectionCard";
+import { RequestCustomerCard } from "@/components/contracts/detail/RequestDetailCards";
 import { IncidentReportCard } from "@/components/contracts/gl-actions/IncidentReportCard";
 import { findWorkflowFile } from "@/components/contracts/PhasedUploadedFileRow";
 import { useFileViewer } from "@/hooks/useFileViewer";
@@ -56,6 +58,7 @@ type GlClearanceDetail =
       reference: string;
       tradeDirection: string;
       clearance: Freight.ContractClearanceView;
+      contract: Freight.IContract;
     }
   | {
       kind: "booking";
@@ -79,6 +82,7 @@ async function loadGlClearanceDetail(id: string): Promise<GlClearanceDetail> {
       reference: contract.reference,
       tradeDirection: contract.tradeDirection,
       clearance,
+      contract,
     };
   } catch {
     const [clearance, booking] = await Promise.all([
@@ -181,6 +185,16 @@ export default function GlClearanceDetailPage() {
             { label: "GL Djibouti Clearance", href: backTo },
             { label: data.reference },
           ]}
+          subtitle={
+            <EntityLink
+              to={
+                data.kind === "contract"
+                  ? `/dashboard/contract-requests/${id}`
+                  : `/dashboard/booking-requests/${id}`
+              }
+              label={data.kind === "contract" ? "Contract details" : "Booking details"}
+            />
+          }
           meta={
             <Badge variant="light" color={isImport ? "edr-green" : "gray"} radius="sm">
               {directionLabel(data.tradeDirection)}
@@ -278,37 +292,44 @@ export default function GlClearanceDetailPage() {
               </Grid.Col>
 
               <Grid.Col span={{ base: 12, lg: 5 }}>
-                <PhasedClearanceActionPanel
-                  contractId={data.kind === "contract" ? id : undefined}
-                  bookingId={data.kind === "booking" ? id : linkedBookingId}
-                  // For a per-booking instance, "created" means COMPLETED (has
-                  // cargo/price), not merely that a booking row exists — a bare
-                  // instance is not yet a real booking. Contract-level clearance
-                  // keeps its linked-booking signal.
-                  bookingCreated={
-                    data.kind === "booking"
-                      ? bookingCompleted
-                      : Boolean(linkedBookingId)
-                  }
-                  bookingMilestones={
-                    data.kind === "booking"
-                      ? (data.clearance.milestones ?? [])
-                      : (bookingMilestones ?? [])
-                  }
-                  clearance={data.clearance}
-                  tradeDirection={data.tradeDirection}
-                  workflowFiles={workflowFiles}
-                  roleMode="DJ"
-                  useUploadModals
-                  onUploadDoRequest={() => setUploadKind("do")}
-                  onUploadRoRequest={() => setUploadKind("ro")}
-                  onChanged={() => {
-                    void refetch();
-                    refetchBookingMilestonesIfLinked();
-                  }}
-                  onViewFile={view}
-                  onDownloadFile={(f) => void downloadBookingFile(f.id, f.name)}
-                />
+                <Stack gap="md">
+                  {data.kind === "contract" ? (
+                    <RequestCustomerCard contract={data.contract} />
+                  ) : (
+                    <BookingCompanyCard booking={data.booking} />
+                  )}
+                  <PhasedClearanceActionPanel
+                    contractId={data.kind === "contract" ? id : undefined}
+                    bookingId={data.kind === "booking" ? id : linkedBookingId}
+                    // For a per-booking instance, "created" means COMPLETED (has
+                    // cargo/price), not merely that a booking row exists — a bare
+                    // instance is not yet a real booking. Contract-level clearance
+                    // keeps its linked-booking signal.
+                    bookingCreated={
+                      data.kind === "booking"
+                        ? bookingCompleted
+                        : Boolean(linkedBookingId)
+                    }
+                    bookingMilestones={
+                      data.kind === "booking"
+                        ? (data.clearance.milestones ?? [])
+                        : (bookingMilestones ?? [])
+                    }
+                    clearance={data.clearance}
+                    tradeDirection={data.tradeDirection}
+                    workflowFiles={workflowFiles}
+                    roleMode="DJ"
+                    useUploadModals
+                    onUploadDoRequest={() => setUploadKind("do")}
+                    onUploadRoRequest={() => setUploadKind("ro")}
+                    onChanged={() => {
+                      void refetch();
+                      refetchBookingMilestonesIfLinked();
+                    }}
+                    onViewFile={view}
+                    onDownloadFile={(f) => void downloadBookingFile(f.id, f.name)}
+                  />
+                </Stack>
               </Grid.Col>
             </Grid>
           </Tabs.Panel>
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ShipmentRequestDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ShipmentRequestDetailPage.tsx
index 89237af1f..54d0fb419 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ShipmentRequestDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ShipmentRequestDetailPage.tsx
@@ -25,6 +25,7 @@ import type { Freight } from "@edr/types";
 import { PageContainer } from "@/components/page/PageContainer";
 import { PageHeader } from "@/components/page/PageHeader";
 import { SectionCard } from "@/components/bookings/detail/SectionCard";
+import { EntityLink } from "@/components/detail";
 import {
   RequestCustomerCard,
   RequestContractSummaryCard,
@@ -113,7 +114,17 @@ export default function ShipmentRequestDetailPage() {
       <Stack gap="lg">
         <PageHeader
           title={`Shipment request ${request.reference}`}
-          subtitle={`On contract ${contractRef}`}
+          subtitle={
+            <Group gap={6} wrap="wrap">
+              <Text size="sm" c="dimmed">
+                On contract
+              </Text>
+              <EntityLink
+                to={`/dashboard/contract-requests/${request.contractId}`}
+                label={contractRef}
+              />
+            </Group>
+          }
           backTo="/dashboard/shipment-requests"
           breadcrumbs={[
             { label: "Shipment Requests", href: "/dashboard/shipment-requests" },
diff --git a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
index 73f6a618b..7107ae7a5 100644
--- a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
@@ -24,6 +24,7 @@ import {
   Contact,
   Download,
   Eye,
+  FileSignature,
   FileText,
   History,
   Hourglass,
@@ -55,7 +56,6 @@ import {
   ProfileStatusBadge,
   ProfileTypeBadge,
   RequestDocumentChangeModal,
-  ResetPasswordAction,
   TableCard,
   formatBytes,
   formatDate,
@@ -63,6 +63,8 @@ import {
   humanize,
 } from "@/components/customers";
 import { KpiStrip, PageContainer, PageHeader } from "@/components/page";
+import { ContractStatusBadge } from "@/components/contracts/ContractStatusBadge";
+import { useContractList } from "@/hooks/contracts/useContracts";
 import { useAuth } from "@/auth/useAuth";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import {
@@ -85,6 +87,7 @@ import {
   usePagination,
   type ColumnDef,
 } from "@edr/ui-common";
+import type { Freight } from "@edr/types";
 
 /** Plain-text summary of the company's eTrade-sourced record, downloaded client-side (eTrade returns data, not a document). */
 function downloadTinRecord(company: Company) {
@@ -170,6 +173,7 @@ export default function CustomerDetailPage() {
       enabled: Boolean(id),
     }),
   );
+  const contractsQuery = useContractList({ companyId: id, pageSize: 100 }, Boolean(id));
 
   const { pagination: invoicePagination, setPagination: setInvoicePagination } =
     usePagination({
@@ -191,6 +195,7 @@ export default function CustomerDetailPage() {
   );
 
   const bookings = Array.isArray(bookingsQuery.data) ? bookingsQuery.data : [];
+  const contracts = contractsQuery.data?.items ?? [];
   const documents = Array.isArray(documentsQuery.data)
     ? documentsQuery.data
     : [];
@@ -402,6 +407,59 @@ export default function CustomerDetailPage() {
     [],
   );
 
+  const contractColumns: ColumnDef<Freight.IContract>[] = useMemo(
+    () => [
+      {
+        id: "reference",
+        header: "Contract",
+        cell: ({ row }) => (
+          <Text size="sm" fw={600} c="edr-text">
+            {row.original.reference}
+          </Text>
+        ),
+      },
+      {
+        id: "kind",
+        header: "Kind",
+        cell: ({ row }) => (
+          <Text size="sm" c="dimmed">
+            {row.original.contractKind === "GENERAL" ? "General" : "One-time"}
+          </Text>
+        ),
+      },
+      {
+        id: "status",
+        header: "Status",
+        cell: ({ row }) => (
+          <ContractStatusBadge
+            status={row.original.status}
+            isRenewal={Boolean(row.original.renewalOfId)}
+          />
+        ),
+      },
+      {
+        id: "validUntil",
+        header: "Valid until",
+        cell: ({ row }) => (
+          <Text size="sm" c="dimmed">
+            {formatDate(row.original.contractValidUntil)}
+          </Text>
+        ),
+      },
+      {
+        id: "createdAt",
+        header: "Created",
+        meta: { headerClassName: "text-right", cellClassName: "text-right" },
+        cell: ({ row }) => (
+          <Text size="sm" c="dimmed">
+            {formatDate(row.original.createdAt)}
+          </Text>
+        ),
+      },
+    ],
+    [],
+  );
+
   const documentColumns: ColumnDef<CustomerDocument>[] = useMemo(
     () => [
       {
@@ -709,7 +767,6 @@ export default function CustomerDetailPage() {
             <ChangeRequestPendingBadge companyId={company.id} />
           </Group>
         }
-        action={<ResetPasswordAction company={company} />}
       />
 
       <Tabs defaultValue="overview">
@@ -720,6 +777,9 @@ export default function CustomerDetailPage() {
           <Tabs.Tab value="bookings" leftSection={<Package size={16} />}>
             Bookings
           </Tabs.Tab>
+          <Tabs.Tab value="contracts" leftSection={<FileSignature size={16} />}>
+            Contracts
+          </Tabs.Tab>
           <Tabs.Tab value="documents" leftSection={<FileText size={16} />}>
             Documents
           </Tabs.Tab>
@@ -1187,6 +1247,7 @@ export default function CustomerDetailPage() {
               status={tableStatus(bookingsQuery)}
               emptyMessage="No bookings for this customer."
               containerClassName="border-0 shadow-none bg-transparent"
+              onRowClick={(row) => navigate(`/dashboard/booking-requests/${row.id}`)}
               error={
                 bookingsQuery.isError
                   ? {
@@ -1199,6 +1260,28 @@ export default function CustomerDetailPage() {
           </TableCard>
         </Tabs.Panel>
 
+        {/* CONTRACTS */}
+        <Tabs.Panel value="contracts" pt="lg">
+          <TableCard minWidth={860}>
+            <DataTable
+              columns={contractColumns}
+              data={contracts}
+              status={tableStatus(contractsQuery)}
+              emptyMessage="No contracts for this customer."
+              containerClassName="border-0 shadow-none bg-transparent"
+              onRowClick={(row) => navigate(`/dashboard/contract-requests/${row.id}`)}
+              error={
+                contractsQuery.isError
+                  ? {
+                      message: "Failed to load contracts.",
+                      onRetry: () => void contractsQuery.refetch(),
+                    }
+                  : undefined
+              }
+            />
+          </TableCard>
+        </Tabs.Panel>
+
         {/* DOCUMENTS */}
         <Tabs.Panel value="documents" pt="lg">
           <Stack gap="lg">
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoiceDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoiceDetailPage.tsx
index 3188509c8..ef7f9d086 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoiceDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoiceDetailPage.tsx
@@ -1,9 +1,11 @@
+import type { ReactNode } from "react";
 import {
   ActionIcon,
   Button,
   Card,
   Center,
   Container,
+  Grid,
   Group,
   Loader,
   SimpleGrid,
@@ -12,7 +14,7 @@ import {
   Text,
 } from "@mantine/core";
 import { useQuery } from "@tanstack/react-query";
-import { ArrowLeft, Download } from "lucide-react";
+import { ArrowLeft, Building2, Download, FileText } from "lucide-react";
 import { useAuth } from "@/auth/useAuth";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import { EimsFilingCard } from "@/components/invoices/EimsFilingCard";
@@ -26,8 +28,11 @@ import {
   humanize,
 } from "@/components/customers";
 import { PageContainer, PageHeader } from "@/components/page";
+import { LinkedEntityCard, type FieldRowProps } from "@/components/detail";
+import { useBookingDetail } from "@/hooks/bookings/useBookings";
 import { api } from "@/services/api";
 import { invoicesService } from "@/services/invoices.service";
+import type { Invoice } from "@/types/invoice";
 
 function openPdfBlob(blob: Blob, filename: string) {
   const url = URL.createObjectURL(blob);
@@ -43,7 +48,17 @@ function openPdfBlob(blob: Blob, filename: string) {
   setTimeout(() => URL.revokeObjectURL(url), 60_000);
 }
 
-function InfoField({ label, value }: { label: string; value?: string | null }) {
+function InfoField({
+  label,
+  value,
+}: {
+  label: string;
+  value?: ReactNode;
+}) {
+  const isEmpty =
+    value === undefined ||
+    value === null ||
+    (typeof value === "string" && !value.trim());
   return (
     <Stack gap={2}>
       <Text
@@ -56,12 +71,75 @@ function InfoField({ label, value }: { label: string; value?: string | null }) {
         {label}
       </Text>
       <Text size="sm" c="edr-text">
-        {value && value.trim() ? value : "—"}
+        {isEmpty ? "—" : value}
       </Text>
     </Stack>
   );
 }
 
+/** Billed-to company, with its contact/registration details as quick-info rows. */
+function RecipientCard({ invoice }: { invoice: Invoice }) {
+  const company = invoice.company;
+  const rows: FieldRowProps[] = [
+    { label: "Profile", value: invoice.companyProfile?.reference },
+    { label: "TIN", value: company?.tin },
+    { label: "VAT No.", value: company?.vatNumber },
+    { label: "Phone", value: company?.phone },
+    { label: "Email", value: company?.email },
+    { label: "Address", value: company?.address },
+  ];
+  return (
+    <LinkedEntityCard
+      icon={Building2}
+      title="Recipient"
+      name={company?.name ?? "Unnamed company"}
+      to={invoice.companyId ? `/dashboard/customers/${invoice.companyId}` : null}
+      rows={rows}
+      emptyMessage="No additional recipient details available."
+    />
+  );
+}
+
+/** What the invoice was raised for — a booking's route/wagons when the
+ *  source is a booking; otherwise just the source type and its raw id
+ *  (warehouse/demurrage/first-mile/last-mile ids don't link anywhere). */
+function SourceCard({ invoice }: { invoice: Invoice }) {
+  const isBooking = invoice.source === "booking";
+  const { data: booking } = useBookingDetail(
+    isBooking ? invoice.sourceId : undefined,
+  );
+
+  if (!isBooking) {
+    return (
+      <LinkedEntityCard
+        icon={FileText}
+        title="Source"
+        name={humanize(invoice.source)}
+        rows={[{ label: "Reference", value: invoice.sourceId }]}
+      />
+    );
+  }
+
+  const route =
+    booking?.originYard && booking?.destinationYard
+      ? `${booking.originYard.label} → ${booking.destinationYard.label}`
+      : undefined;
+
+  return (
+    <LinkedEntityCard
+      icon={FileText}
+      title="Source"
+      name={booking?.reference ?? invoice.sourceId}
+      to={`/dashboard/booking-requests/${invoice.sourceId}`}
+      rows={[
+        { label: "Type", value: humanize(invoice.type) },
+        { label: "Route", value: route },
+        { label: "Wagons", value: booking?.wagonsRequired ?? undefined },
+      ]}
+    />
+  );
+}
+
 export default function InvoiceDetailPage() {
   const { user } = useAuth();
   const canExport = hasPermission(user, FREIGHT_PERMS.invoices.export);
@@ -121,7 +199,7 @@ export default function InvoiceDetailPage() {
         ]}
         backTo="/dashboard/invoices"
         title={invoice.invoiceNumber}
-        subtitle={`${humanize(invoice.source)} · ${invoice.sourceId}`}
+        subtitle={humanize(invoice.source)}
         meta={<InvoiceStatusBadge status={invoice.status} />}
         action={
           <ActionIcon
@@ -138,125 +216,130 @@ export default function InvoiceDetailPage() {
         }
       />
 
-      <Stack gap="lg">
-        <Card>
+      <Grid gap="lg">
+        <Grid.Col span={{ base: 12, lg: 8 }}>
           <Stack gap="lg">
-            <Text fw={600} c="edr-text">
-              Summary
-            </Text>
-            <SimpleGrid cols={{ base: 1, sm: 2, lg: 4 }} spacing="lg">
-              <InfoField label="Billed to" value={invoice.company?.name} />
-              <InfoField
-                label="Profile"
-                value={invoice.companyProfile?.reference}
-              />
-              <InfoField label="Type" value={humanize(invoice.type)} />
-              <InfoField label="Currency" value={invoice.currency} />
-              <InfoField label="Issued" value={formatDate(invoice.issuedAt)} />
-              <InfoField label="Due" value={formatDate(invoice.dueAt)} />
-              <InfoField
-                label="Total"
-                value={formatMoney(invoice.totalAmount, invoice.currency)}
-              />
-              <InfoField
-                label="Balance"
-                value={formatMoney(invoice.balanceAmount, invoice.currency)}
-              />
-            </SimpleGrid>
+            <Card>
+              <Stack gap="lg">
+                <Text fw={600} c="edr-text">
+                  Amounts
+                </Text>
+                <SimpleGrid cols={{ base: 1, sm: 2, lg: 4 }} spacing="lg">
+                  <InfoField label="Currency" value={invoice.currency} />
+                  <InfoField label="Issued" value={formatDate(invoice.issuedAt)} />
+                  <InfoField label="Due" value={formatDate(invoice.dueAt)} />
+                  <InfoField
+                    label="Total"
+                    value={formatMoney(invoice.totalAmount, invoice.currency)}
+                  />
+                  <InfoField
+                    label="Balance"
+                    value={formatMoney(invoice.balanceAmount, invoice.currency)}
+                  />
+                </SimpleGrid>
+              </Stack>
+            </Card>
+
+            <EimsFilingCard invoiceId={invoice.id} />
+
+            <Card>
+              <Stack gap="md">
+                <Text fw={600} c="edr-text">
+                  Line items
+                </Text>
+                <Table striped withRowBorders={false} verticalSpacing="xs">
+                  <Table.Thead>
+                    <Table.Tr>
+                      <Table.Th>Description</Table.Th>
+                      <Table.Th>Charge type</Table.Th>
+                      <Table.Th ta="right">Quantity</Table.Th>
+                      <Table.Th ta="right">Unit rate</Table.Th>
+                      <Table.Th ta="right">Amount</Table.Th>
+                    </Table.Tr>
+                  </Table.Thead>
+                  <Table.Tbody>
+                    {(invoice.lines ?? []).map((line) => (
+                      <Table.Tr key={line.id}>
+                        <Table.Td>{line.description ?? line.chargeType}</Table.Td>
+                        <Table.Td>
+                          <Text size="sm" c="dimmed">
+                            {humanize(line.chargeType)}
+                          </Text>
+                        </Table.Td>
+                        <Table.Td ta="right">{line.quantity}</Table.Td>
+                        <Table.Td ta="right">
+                          {formatMoney(line.unitRate, line.currency)}
+                        </Table.Td>
+                        <Table.Td ta="right">
+                          {formatMoney(line.amount, line.currency)}
+                        </Table.Td>
+                      </Table.Tr>
+                    ))}
+                    {(invoice.lines ?? []).length === 0 && (
+                      <Table.Tr>
+                        <Table.Td colSpan={5}>
+                          <Text size="sm" c="dimmed" ta="center" py="md">
+                            No line items.
+                          </Text>
+                        </Table.Td>
+                      </Table.Tr>
+                    )}
+                  </Table.Tbody>
+                </Table>
+
+                <Group
+                  justify="flex-end"
+                  gap="xl"
+                  pt="sm"
+                  style={{
+                    borderTop: "1px solid var(--mantine-color-edr-border-0)",
+                  }}
+                >
+                  <Stack gap={2} align="flex-end">
+                    <Text size="xs" c="edr-muted">
+                      Subtotal
+                    </Text>
+                    <Text size="sm">
+                      {formatMoney(invoice.subtotalAmount, invoice.currency)}
+                    </Text>
+                  </Stack>
+                  <Stack gap={2} align="flex-end">
+                    <Text size="xs" c="edr-muted">
+                      Tax
+                    </Text>
+                    <Text size="sm">
+                      {formatMoney(invoice.taxAmount, invoice.currency)}
+                    </Text>
+                  </Stack>
+                  <Stack gap={2} align="flex-end">
+                    <Text size="xs" c="edr-muted">
+                      Paid
+                    </Text>
+                    <Text size="sm">
+                      {formatMoney(invoice.paidAmount, invoice.currency)}
+                    </Text>
+                  </Stack>
+                  <Stack gap={2} align="flex-end">
+                    <Text size="xs" fw={700}>
+                      Total
+                    </Text>
+                    <Text size="sm" fw={700}>
+                      {formatMoney(invoice.totalAmount, invoice.currency)}
+                    </Text>
+                  </Stack>
+                </Group>
+              </Stack>
+            </Card>
           </Stack>
-        </Card>
+        </Grid.Col>
 
-        <EimsFilingCard invoiceId={invoice.id} />
-
-        <Card>
-          <Stack gap="md">
-            <Text fw={600} c="edr-text">
-              Line items
-            </Text>
-            <Table striped withRowBorders={false} verticalSpacing="xs">
-              <Table.Thead>
-                <Table.Tr>
-                  <Table.Th>Description</Table.Th>
-                  <Table.Th>Charge type</Table.Th>
-                  <Table.Th ta="right">Quantity</Table.Th>
-                  <Table.Th ta="right">Unit rate</Table.Th>
-                  <Table.Th ta="right">Amount</Table.Th>
-                </Table.Tr>
-              </Table.Thead>
-              <Table.Tbody>
-                {(invoice.lines ?? []).map((line) => (
-                  <Table.Tr key={line.id}>
-                    <Table.Td>{line.description ?? line.chargeType}</Table.Td>
-                    <Table.Td>
-                      <Text size="sm" c="dimmed">
-                        {humanize(line.chargeType)}
-                      </Text>
-                    </Table.Td>
-                    <Table.Td ta="right">{line.quantity}</Table.Td>
-                    <Table.Td ta="right">
-                      {formatMoney(line.unitRate, line.currency)}
-                    </Table.Td>
-                    <Table.Td ta="right">
-                      {formatMoney(line.amount, line.currency)}
-                    </Table.Td>
-                  </Table.Tr>
-                ))}
-                {(invoice.lines ?? []).length === 0 && (
-                  <Table.Tr>
-                    <Table.Td colSpan={5}>
-                      <Text size="sm" c="dimmed" ta="center" py="md">
-                        No line items.
-                      </Text>
-                    </Table.Td>
-                  </Table.Tr>
-                )}
-              </Table.Tbody>
-            </Table>
-
-            <Group
-              justify="flex-end"
-              gap="xl"
-              pt="sm"
-              style={{
-                borderTop: "1px solid var(--mantine-color-edr-border-0)",
-              }}
-            >
-              <Stack gap={2} align="flex-end">
-                <Text size="xs" c="edr-muted">
-                  Subtotal
-                </Text>
-                <Text size="sm">
-                  {formatMoney(invoice.subtotalAmount, invoice.currency)}
-                </Text>
-              </Stack>
-              <Stack gap={2} align="flex-end">
-                <Text size="xs" c="edr-muted">
-                  Tax
-                </Text>
-                <Text size="sm">
-                  {formatMoney(invoice.taxAmount, invoice.currency)}
-                </Text>
-              </Stack>
-              <Stack gap={2} align="flex-end">
-                <Text size="xs" c="edr-muted">
-                  Paid
-                </Text>
-                <Text size="sm">
-                  {formatMoney(invoice.paidAmount, invoice.currency)}
-                </Text>
-              </Stack>
-              <Stack gap={2} align="flex-end">
-                <Text size="xs" fw={700}>
-                  Total
-                </Text>
-                <Text size="sm" fw={700}>
-                  {formatMoney(invoice.totalAmount, invoice.currency)}
-                </Text>
-              </Stack>
-            </Group>
+        <Grid.Col span={{ base: 12, lg: 4 }}>
+          <Stack gap="lg">
+            <RecipientCard invoice={invoice} />
+            <SourceCard invoice={invoice} />
           </Stack>
-        </Card>
-      </Stack>
+        </Grid.Col>
+      </Grid>
     </PageContainer>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
index cf6c37e80..acfc3c375 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
@@ -1,4 +1,5 @@
 import {
+  ActionIcon,
   Alert,
   Badge,
   Box,
@@ -7,6 +8,7 @@ import {
   Group,
   List,
   Loader,
+  Menu,
   Modal,
   Paper,
   RingProgress,
@@ -19,7 +21,6 @@ import {
 import { isAxiosError } from "axios";
 import {
   AlertTriangle,
-  ArrowLeft,
   CalendarClock,
   CheckCircle2,
   Clock,
@@ -29,6 +30,7 @@ import {
   FileText,
   History as HistoryIcon,
   LayoutGrid,
+  MoreHorizontal,
   Navigation,
   Package,
   PackageCheck,
@@ -42,7 +44,7 @@ import {
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Link, useParams } from "react-router-dom";
 
-import { KpiStrip, PageContainer } from "@/components/page";
+import { KpiStrip, PageContainer, PageHeader } from "@/components/page";
 import { useAuth } from "@/auth/useAuth";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import {
@@ -886,284 +888,248 @@ export default function TrainScheduleV2DetailPage() {
 
   return (
     <PageContainer>
-      <Button
-        component={Link}
-        to="/dashboard/operations/train-scheduling-v2"
-        variant="subtle"
-        color="gray"
-        size="compact-sm"
-        leftSection={<ArrowLeft size={16} />}
-        w="fit-content"
-      >
-        Back to schedules
-      </Button>
-
-      <Paper
-        radius="xl"
-        p="xl"
-        style={{ position: "relative", overflow: "hidden" }}
-      >
-        <Stack gap="lg" style={{ position: "relative" }}>
-          <Group justify="space-between" align="flex-start" wrap="wrap">
-            <Group gap="md" align="flex-start" wrap="nowrap">
-              <ThemeIcon size={56} radius="lg" variant="light" color="#F2A516">
-                <Train size={28} />
-              </ThemeIcon>
-              <Stack gap={6}>
-                <Group gap="sm" align="center" wrap="wrap">
-                  {schedule.reference ? (
-                    <Badge
-                      variant="filled"
-                      color="edr-green"
-                      radius="sm"
-                      style={{ fontWeight: 700, fontFamily: "monospace" }}
-                    >
-                      {schedule.reference}
-                    </Badge>
-                  ) : null}
-                  <Title order={2} fw={700} style={{ color: "#0f172a" }}>
-                    {schedule.route?.name ?? "Train schedule"}
-                  </Title>
-                  {schedule.train?.trainName ? (
-                    <Text fw={700} style={{ color: "#0f172a" }}>
-                      {schedule.train.trainName}
-                    </Text>
-                  ) : null}
-                  {schedule.train ? (
-                    <Text size="xs" c="dimmed" ff="monospace">
-                      Train {schedule.train.code}
-                    </Text>
-                  ) : null}
-                </Group>
-
-                {/* Voyage (train) number and trade direction — the two things
-                    operations identify a run by, so they read at a glance
-                    rather than as small badges among the rest. */}
-                <Group gap="lg" align="center" wrap="wrap">
-                  {schedule.trainNumber ? (
-                    <Box>
-                      <Text size="xs" c="dimmed" fw={600} tt="uppercase" lh={1.2}>
-                        Train No.
-                      </Text>
-                      <Text
-                        ff="monospace"
-                        fw={800}
-                        lh={1.1}
-                        style={{ fontSize: 32, color: "#0f172a" }}
-                      >
-                        {schedule.trainNumber}
-                      </Text>
-                    </Box>
-                  ) : null}
-                  {schedule.voyageNumber ? (
-                    <Box>
-                      <Text size="xs" c="dimmed" fw={600} tt="uppercase" lh={1.2}>
-                        Voyage No.
-                      </Text>
-                      <Text
-                        ff="monospace"
-                        fw={800}
-                        lh={1.1}
-                        style={{ fontSize: 32, color: "#0f172a" }}
-                      >
-                        {schedule.voyageNumber}
-                      </Text>
-                    </Box>
-                  ) : null}
-                  {/* Merging rewrites the consist, so it is offered only while
-                      the departure can still be edited. */}
-                  {canEditBookings ? (
-                    <Button
-                      variant="light"
-                      size="compact-sm"
-                      leftSection={<Merge size={14} />}
-                      onClick={() => setMergeModalOpen(true)}
-                    >
-                      Merge
-                    </Button>
-                  ) : null}
-                  {schedule.direction ? (
-                    <Box>
-                      <Text size="xs" c="dimmed" fw={600} tt="uppercase" lh={1.2}>
-                        Direction
-                      </Text>
-                      <Text
-                        fw={800}
-                        lh={1.1}
-                        tt="uppercase"
-                        style={{
-                          fontSize: 32,
-                          letterSpacing: 0.5,
-                          color:
-                            schedule.direction === "IMPORT"
-                              ? "#2E5B96"
-                              : schedule.direction === "EXPORT"
-                                ? "#0A6F4D"
-                                : "#0f172a",
-                        }}
-                      >
-                        {schedule.direction}
-                      </Text>
-                    </Box>
-                  ) : null}
-                </Group>
-                {(schedule.stops?.length ?? 0) >= 3 ||
-                (schedule.bookings ?? []).some(
-                  (b) => b.tradeDirection === "DOMESTIC",
-                ) ? (
-                  <SegmentOccupancyStrip
-                    stops={schedule.stops ?? []}
-                    bookings={schedule.bookings ?? []}
-                    maxWagons={schedule.maxWagons}
-                    maxGrossTons={schedule.maxGrossWeightTons}
+      <PageHeader
+        title={schedule.route?.name ?? "Train schedule"}
+        backTo="/dashboard/operations/train-scheduling-v2"
+        breadcrumbs={[
+          {
+            label: "Train schedules",
+            href: "/dashboard/operations/train-scheduling-v2",
+          },
+          { label: schedule.reference ?? "Schedule" },
+        ]}
+        subtitle={
+          schedule.train ? (
+            <Text size="sm" c="dimmed">
+              {schedule.train.trainName ?? `Train ${schedule.train.code}`}
+              {schedule.train.trainName ? ` · Train ${schedule.train.code}` : ""}
+            </Text>
+          ) : undefined
+        }
+        meta={
+          <Group gap={6} wrap="wrap">
+            {schedule.reference ? (
+              <Badge
+                variant="filled"
+                color="edr-green"
+                radius="sm"
+                style={{ fontWeight: 700, fontFamily: "monospace" }}
+              >
+                {schedule.reference}
+              </Badge>
+            ) : null}
+            <FreightTypeBadge freightType={schedule.freightType} />
+            <StatusPill status={schedule.status} />
+            {gatepassApplies && gatepassSecured ? (
+              <Badge
+                variant="light"
+                color="edr-green"
+                radius="sm"
+                leftSection={<CheckCircle2 size={12} />}
+              >
+                Gate pass secured
+              </Badge>
+            ) : null}
+            {previewResult ? (
+              <Badge
+                radius="sm"
+                variant="light"
+                color={previewResult.valid ? "edr-green" : "red"}
+                leftSection={
+                  <Box
+                    w={8}
+                    h={8}
+                    style={{
+                      borderRadius: 999,
+                      background: previewResult.valid
+                        ? "var(--mantine-color-edr-green-6)"
+                        : "var(--mantine-color-red-6)",
+                    }}
                   />
-                ) : (
-                  <Box maw={340}>
-                    <RouteCorridor
-                      origin={
-                        schedule.originStation?.label ?? schedule.originStation?.code
-                      }
-                      destination={
-                        schedule.destinationStation?.label ??
-                        schedule.destinationStation?.code
-                      }
-                    />
-                  </Box>
-                )}
-                <Group gap="sm" align="center">
-                  <FreightTypeBadge freightType={schedule.freightType} />
-                  <StatusPill status={schedule.status} />
-                </Group>
-              </Stack>
-            </Group>
-            <Group gap="sm">
-              {(schedule.trainSet?.wagons?.length ?? 0) > 0 ? (
-                <Button
-                  variant="gradient"
-                  gradient={{ from: "#0f172a", to: "#334155" }}
-                  radius="lg"
-                  size="sm"
-                  leftSection={<Eye size={16} />}
-                  onClick={() => setVisualization3DOpen(true)}
-                >
-                  3D Visualization
-                </Button>
-              ) : null}
-              {canPrintMarshalling ? (
-                <Button
-                  variant="light"
-                  color="edr-green"
-                  radius="lg"
-                  size="sm"
-                  leftSection={<FileText size={16} />}
-                  loading={downloadMarshalling.isPending}
-                  onClick={() => void openMarshallingDocument()}
-                >
-                  Marshalling PDF
-                </Button>
-              ) : null}
-              {["DISPATCHED", "ARRIVED"].includes(schedule.status) ? (
-                <Button
-                  variant="light"
-                  color="edr-green"
-                  radius="lg"
-                  size="sm"
-                  leftSection={<FileText size={16} />}
-                  loading={downloadMarshalling.isPending}
-                  onClick={() =>
-                    void openMarshallingDocument({
-                      title: "Intercity marshalling ready",
-                      variant: "INTERCITY",
-                    })
-                  }
-                >
-                  Intercity Marshalling
-                </Button>
-              ) : null}
-              {["DISPATCHED", "ARRIVED"].includes(schedule.status) ? (
-                <Button
-                  component={Link}
-                  to={`/dashboard/operations/train-scheduling-v2/${scheduleId}/track`}
-                  color="edr-green"
-                  radius="lg"
-                  size="sm"
-                  leftSection={<Navigation size={16} />}
-                >
-                  Track train
-                </Button>
-              ) : null}
-              {schedule.windowPhase === "PRE_WINDOW" ? (
-                <Button
-                  variant="light"
-                  color="edr-green"
-                  radius="lg"
-                  size="sm"
-                  leftSection={<Clock size={16} />}
-                  onClick={() => setWindowSettingsOpen(true)}
-                >
-                  Window settings
-                </Button>
-              ) : null}
-              {["DRAFT", "SCHEDULED"].includes(schedule.status) ? (
-                <Button
-                  variant="default"
-                  radius="lg"
-                  size="sm"
-                  onClick={() => setMaintenanceOpen(true)}
-                >
-                  Reschedule train
-                </Button>
-              ) : null}
-              {gatepassApplies ? (
-                gatepassSecured ? (
-                  <Button
-                    variant="light"
-                    color="edr-green"
-                    radius="lg"
-                    size="sm"
-                    leftSection={<CheckCircle2 size={16} />}
-                    disabled
+                }
+              >
+                Preview {previewResult.valid ? "valid" : "has issues"}
+              </Badge>
+            ) : null}
+          </Group>
+        }
+        action={
+          <Group gap="sm" wrap="nowrap">
+            {/* Merging rewrites the consist, so it is offered only while
+                the departure can still be edited. */}
+            {canEditBookings ? (
+              <Button
+                variant="light"
+                size="compact-sm"
+                leftSection={<Merge size={14} />}
+                onClick={() => setMergeModalOpen(true)}
+              >
+                Merge
+              </Button>
+            ) : null}
+            {(schedule.trainSet?.wagons?.length ?? 0) > 0 ? (
+              <Button
+                variant="gradient"
+                gradient={{ from: "#0f172a", to: "#334155" }}
+                radius="lg"
+                size="compact-sm"
+                leftSection={<Eye size={16} />}
+                onClick={() => setVisualization3DOpen(true)}
+              >
+                3D Visualization
+              </Button>
+            ) : null}
+            <Menu position="bottom-end" width={240} withinPortal>
+              <Menu.Target>
+                <ActionIcon variant="default" size="lg" radius="md" aria-label="More actions">
+                  <MoreHorizontal size={16} />
+                </ActionIcon>
+              </Menu.Target>
+              <Menu.Dropdown>
+                {canPrintMarshalling ? (
+                  <Menu.Item
+                    leftSection={<FileText size={15} />}
+                    disabled={downloadMarshalling.isPending}
+                    onClick={() => void openMarshallingDocument()}
                   >
-                    Gate pass secured
-                  </Button>
-                ) : (
-                  <Button
-                    color="edr-green"
-                    radius="lg"
-                    size="sm"
-                    leftSection={<FileText size={16} />}
-                    loading={secureGatepass.isPending}
+                    Marshalling PDF
+                  </Menu.Item>
+                ) : null}
+                {["DISPATCHED", "ARRIVED"].includes(schedule.status) ? (
+                  <Menu.Item
+                    leftSection={<FileText size={15} />}
+                    disabled={downloadMarshalling.isPending}
+                    onClick={() =>
+                      void openMarshallingDocument({
+                        title: "Intercity marshalling ready",
+                        variant: "INTERCITY",
+                      })
+                    }
+                  >
+                    Intercity Marshalling
+                  </Menu.Item>
+                ) : null}
+                {["DISPATCHED", "ARRIVED"].includes(schedule.status) ? (
+                  <Menu.Item
+                    component={Link}
+                    to={`/dashboard/operations/train-scheduling-v2/${scheduleId}/track`}
+                    leftSection={<Navigation size={15} />}
+                  >
+                    Track train
+                  </Menu.Item>
+                ) : null}
+                {schedule.windowPhase === "PRE_WINDOW" ? (
+                  <Menu.Item
+                    leftSection={<Clock size={15} />}
+                    onClick={() => setWindowSettingsOpen(true)}
+                  >
+                    Window settings
+                  </Menu.Item>
+                ) : null}
+                {["DRAFT", "SCHEDULED"].includes(schedule.status) ? (
+                  <Menu.Item onClick={() => setMaintenanceOpen(true)}>
+                    Reschedule train
+                  </Menu.Item>
+                ) : null}
+                {gatepassApplies && !gatepassSecured ? (
+                  <Menu.Item
+                    leftSection={<FileText size={15} />}
+                    disabled={secureGatepass.isPending}
                     onClick={() => secureGatepass.mutate()}
                   >
                     Secure gate pass
-                  </Button>
-                )
-              ) : null}
-            </Group>
+                  </Menu.Item>
+                ) : null}
+              </Menu.Dropdown>
+            </Menu>
           </Group>
+        }
+      />
 
-          {previewResult ? (
-            <Badge
-              size="lg"
-              radius="sm"
-              variant="light"
-              color={previewResult.valid ? "edr-green" : "red"}
-              leftSection={
-                <Box
-                  w={8}
-                  h={8}
+      {/* Ops signage: Train No. / Voyage No. / Direction read at a glance from
+          across the room, so these stay large rather than folding into the
+          numeric KpiStrip below. */}
+      <Paper radius="xl" p="lg">
+        <Stack gap="md">
+          <Group gap="lg" align="center" wrap="wrap">
+            {schedule.trainNumber ? (
+              <Box>
+                <Text size="xs" c="dimmed" fw={600} tt="uppercase" lh={1.2}>
+                  Train No.
+                </Text>
+                <Text
+                  ff="monospace"
+                  fw={800}
+                  lh={1.1}
+                  style={{ fontSize: 32, color: "#0f172a" }}
+                >
+                  {schedule.trainNumber}
+                </Text>
+              </Box>
+            ) : null}
+            {schedule.voyageNumber ? (
+              <Box>
+                <Text size="xs" c="dimmed" fw={600} tt="uppercase" lh={1.2}>
+                  Voyage No.
+                </Text>
+                <Text
+                  ff="monospace"
+                  fw={800}
+                  lh={1.1}
+                  style={{ fontSize: 32, color: "#0f172a" }}
+                >
+                  {schedule.voyageNumber}
+                </Text>
+              </Box>
+            ) : null}
+            {schedule.direction ? (
+              <Box>
+                <Text size="xs" c="dimmed" fw={600} tt="uppercase" lh={1.2}>
+                  Direction
+                </Text>
+                <Text
+                  fw={800}
+                  lh={1.1}
+                  tt="uppercase"
                   style={{
-                    borderRadius: 999,
-                    background: previewResult.valid
-                      ? "var(--mantine-color-edr-green-6)"
-                      : "var(--mantine-color-red-6)",
+                    fontSize: 32,
+                    letterSpacing: 0.5,
+                    color:
+                      schedule.direction === "IMPORT"
+                        ? "#2E5B96"
+                        : schedule.direction === "EXPORT"
+                          ? "#0A6F4D"
+                          : "#0f172a",
                   }}
-                />
-              }
-            >
-              Preview {previewResult.valid ? "valid" : "has issues"}
-            </Badge>
-          ) : null}
+                >
+                  {schedule.direction}
+                </Text>
+              </Box>
+            ) : null}
+          </Group>
+          {(schedule.stops?.length ?? 0) >= 3 ||
+          (schedule.bookings ?? []).some(
+            (b) => b.tradeDirection === "DOMESTIC",
+          ) ? (
+            <SegmentOccupancyStrip
+              stops={schedule.stops ?? []}
+              bookings={schedule.bookings ?? []}
+              maxWagons={schedule.maxWagons}
+              maxGrossTons={schedule.maxGrossWeightTons}
+            />
+          ) : (
+            <Box maw={340}>
+              <RouteCorridor
+                origin={
+                  schedule.originStation?.label ?? schedule.originStation?.code
+                }
+                destination={
+                  schedule.destinationStation?.label ??
+                  schedule.destinationStation?.code
+                }
+              />
+            </Box>
+          )}
         </Stack>
       </Paper>
 
diff --git a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
index b49a11f83..6a86dba7d 100644
--- a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
@@ -16,6 +16,8 @@ export interface BookingListFilter {
   tab?: string;
   // customerId?: string;
   companyId?: string;
+  /** Bookings drawn down under this contract (contract detail's Shipments tab). */
+  contractId?: string;
   freightType?: string;
   /** ONE_TIME | GENERAL_CONTRACT — the booking-kind tab filter. */
   bookingType?: string;
@@ -169,6 +171,7 @@ export const bookingsService = {
       if (filter.schedulingStatuses) params.schedulingStatuses = filter.schedulingStatuses;
       if (filter.assignedToSchedule) params.assignedToSchedule = filter.assignedToSchedule;
       if (filter.companyId) params.companyId = filter.companyId;
+      if (filter.contractId) params.contractId = filter.contractId;
       if (filter.freightType) params.freightType = filter.freightType;
       if (filter.bookingType) params.bookingType = filter.bookingType;
       if (filter.tradeDirection) params.tradeDirection = filter.tradeDirection;
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index 68f48e187..2c9800836 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -930,10 +930,19 @@ export interface ClearanceView {
   importReleaseGranted?: boolean;
 }
 
-/** Company an invoice is billed to (minimal projection). */
+/**
+ * Company an invoice is billed to. `findById` returns the full `Company`
+ * relation, not a stripped projection — these extra fields are what the
+ * backoffice invoice detail page's recipient card shows.
+ */
 export interface IInvoiceCompany {
   id: string;
   name: string;
+  tin?: string | null;
+  vatNumber?: string | null;
+  phone?: string | null;
+  email?: string | null;
+  address?: string | null;
 }
 
 /** Company profile (importer/exporter/forwarder/…) an invoice is billed to. */

From 08804c84e993d52614f429dd159355b2b5fc7648 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 07:52:10 +0000
Subject: [PATCH 062/174] feat(freight-api): seed a permission per report

Each report key (REPORT_KEYS) mints its own edr_freight_app:reports:<key>:view
permission, derived the same way rule-engine resource permissions are.
reports:view stays the section master key; STAFF_DASHBOARD_KEYS grants every
report key alongside it so existing presets don't regress on reseed.
---
 .../src/seed/freight-permissions.registry.ts  | 38 +++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index cdbffd961..7470ed2b5 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -47,6 +47,36 @@ const perm = (id: string, key: string, en: string): FreightPermissionSeed => ({
   applicationKey: EDR_FREIGHT_APP_KEY,
 });
 
+/**
+ * One entry per report definition (see modules/reports/definitions). Each
+ * gets its own permission, gated behind the `reports:view` master key that
+ * opens the Reports section itself.
+ * Keep new keys at the END: reportPermId derives ids from list index, so a
+ * mid-list insert would shift ids already seeded for later keys.
+ */
+export const REPORT_KEYS = [
+  "bookings-list",
+  "revenue-by-customer",
+  "aging-receivables",
+  "contract-utilization",
+] as const;
+
+export type ReportKey = (typeof REPORT_KEYS)[number];
+
+export const reportPermissionKey = (key: ReportKey): string =>
+  `edr_freight_app:reports:${key.replace(/-/g, "_")}:view`;
+
+const reportPermId = (index: number): string =>
+  `a4f00002-0001-4000-8000-${(index + 1).toString(16).padStart(12, "0")}`;
+
+const titleCase = (slug: string): string =>
+  slug.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+
+export const REPORT_PERMISSIONS: FreightPermissionSeed[] = REPORT_KEYS.map(
+  (key, index) =>
+    perm(reportPermId(index), reportPermissionKey(key), `Report: ${titleCase(key)}`),
+);
+
 export const BOOKING_PERMISSIONS: FreightPermissionSeed[] = [
   perm(
     "a1000001-0001-4000-8000-000000000001",
@@ -1506,6 +1536,7 @@ export const NOTIFICATION_PERMISSIONS: FreightPermissionSeed[] = [
 ];
 
 export const ADVANCED_BACKOFFICE_PERMISSIONS: FreightPermissionSeed[] = [
+  ...REPORT_PERMISSIONS,
   ...CUSTOMER_PERMISSIONS,
   ...FINANCE_PERMISSIONS,
   ...MILE_PERMISSIONS,
@@ -1987,6 +2018,7 @@ export const FREIGHT_PERMS = {
   },
   reports: {
     view: "edr_freight_app:reports:view",
+    report: (key: ReportKey): string => reportPermissionKey(key),
   },
   staff: {
     users: {
@@ -2131,11 +2163,17 @@ const FLEET_GRANULAR_KEYS: string[] = [
   FREIGHT_PERMS.consignments.create,
 ];
 
+const allReportKeys = (): string[] => REPORT_KEYS.map((k) => reportPermissionKey(k));
+
 // Everyone who works the booking desk also opens the overview dashboard and
 // the canned reports — granted alongside bookings:view in every preset below.
+// Each report also carries its own key (see REPORT_PERMISSIONS); spreading
+// allReportKeys() here keeps every existing preset seeing every report, same
+// as when reports:view alone gated the whole section.
 const STAFF_DASHBOARD_KEYS: string[] = [
   FREIGHT_PERMS.overview.view,
   FREIGHT_PERMS.reports.view,
+  ...allReportKeys(),
 ];
 
 // Notification desks — recipient selectors, not access. A preset gets a desk

From b7583df426cfacd694b215fbb8d08e91495ae290 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 07:52:20 +0000
Subject: [PATCH 063/174] feat(freight-api): replace canned reports with a
 generic report engine

Nuke the 17 hand-written raw-SQL reports (no pagination, hard LIMITs) and
the reports module built around them. Replace with a resolver contract:
a report declares columns/filters/permission and a TypeORM QueryBuilder;
ReportRunnerService applies filtering, a whitelisted sort, offset/limit
paging, and a COUNT(*) FROM (query) wrapper for the total (getCount() is
wrong for GROUP BY). ReportExportService re-runs the same resolver
unpaginated for xlsx (exceljs) and pdf (existing PdfRenderService, now
landscape-capable) exports.

Ships with 4 reports: bookings-list, revenue-by-customer,
aging-receivables, contract-utilization. Catalog + per-report permission
checks live in the controller; adding a report is one new definitions/
file plus a REPORT_KEYS entry, no frontend change.
---
 apps/edr-freight-api/package.json             |   1 +
 .../billing/documents/pdf-render.service.ts   |   3 +
 .../definitions/aging-receivables.report.ts   |  87 +++
 .../definitions/bookings-list.report.ts       | 129 ++++
 .../contract-utilization.report.ts            | 121 ++++
 .../definitions/revenue-by-customer.report.ts |  91 +++
 .../modules/reports/dto/report-query.dto.ts   |  54 --
 .../modules/reports/dto/report-result.dto.ts  |  24 -
 .../modules/reports/report-export.service.ts  | 114 +++
 .../src/modules/reports/report-queries.ts     | 669 ------------------
 .../modules/reports/report-runner.service.ts  | 141 ++++
 .../modules/reports/report.registry.spec.ts   |  41 ++
 .../src/modules/reports/report.registry.ts    |  24 +
 .../src/modules/reports/report.types.ts       |  95 +++
 .../src/modules/reports/reports.controller.ts |  84 ++-
 .../src/modules/reports/reports.module.ts     |   9 +-
 .../src/modules/reports/reports.repository.ts |  14 -
 .../src/modules/reports/reports.service.ts    |  46 --
 pnpm-lock.yaml                                | 285 ++------
 19 files changed, 976 insertions(+), 1056 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/aging-receivables.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/bookings-list.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/contract-utilization.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/revenue-by-customer.report.ts
 delete mode 100644 apps/edr-freight-api/src/modules/reports/dto/report-query.dto.ts
 delete mode 100644 apps/edr-freight-api/src/modules/reports/dto/report-result.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/report-export.service.ts
 delete mode 100644 apps/edr-freight-api/src/modules/reports/report-queries.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/report-runner.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/report.registry.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/report.registry.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/report.types.ts
 delete mode 100644 apps/edr-freight-api/src/modules/reports/reports.repository.ts
 delete mode 100644 apps/edr-freight-api/src/modules/reports/reports.service.ts

diff --git a/apps/edr-freight-api/package.json b/apps/edr-freight-api/package.json
index f3ba897a0..e10e5dcb7 100644
--- a/apps/edr-freight-api/package.json
+++ b/apps/edr-freight-api/package.json
@@ -69,6 +69,7 @@
     "cross-env": "^10.1.0",
     "dotenv": "^17.4.2",
     "dotenv-cli": "^11.0.0",
+    "exceljs": "^4.4.0",
     "handlebars": "^4.7.9",
     "jose": "^5.10.0",
     "libphonenumber-js": "^1.13.6",
diff --git a/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts b/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts
index 447bc2516..e8c3de792 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts
@@ -18,6 +18,8 @@ const PDF_PRINT_STYLES = `
 export interface PdfRenderOptions {
   /** Label used in logs to identify the document kind. */
   label?: string;
+  /** Landscape A4 instead of the default portrait — wide tables need it. */
+  landscape?: boolean;
   /**
    * Degraded renderer used when Chromium is unavailable. Receives the
    * print-prepared HTML and must return a valid PDF buffer (≥ 2KB, `%PDF-`
@@ -59,6 +61,7 @@ export class PdfRenderService {
 
         const pdf = await page.pdf({
           format: "A4",
+          landscape: opts.landscape ?? false,
           printBackground: true,
           margin: { top: "16mm", bottom: "18mm", left: "14mm", right: "14mm" },
         });
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/aging-receivables.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/aging-receivables.report.ts
new file mode 100644
index 000000000..d5709508c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/aging-receivables.report.ts
@@ -0,0 +1,87 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { Company } from '../../companies/entities/company.entity';
+import { Invoice } from '../../billing/entities/invoice.entity';
+import { applyBookingRefDirectionScope } from '../../user-trade-access/trade-scope.util';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+const OPEN_STATUSES = ['ISSUED', 'PENDING', 'PARTIALLY_PAID', 'OVERDUE'];
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params, directions } = ctx;
+  // "As of" — invoices due after this instant aren't overdue yet. Defaults
+  // to now() in SQL when the filter is unset (see the COALESCE below).
+  const asOf = (params.asOf as string | null) ?? null;
+
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Invoice, 'i')
+    .innerJoin(Company, 'c', 'c.id = i.company_id')
+    .where('i.deleted_at IS NULL')
+    .andWhere('i.status IN (:...openStatuses)', { openStatuses: OPEN_STATUSES })
+    .andWhere('i.balance_amount > 0')
+    .setParameter('asOf', asOf);
+
+  // ACL: invoices.source_id is a varchar pointer at the originating booking.
+  // Rows not pointing at a booking (e.g. warehouse fee invoices) stay visible.
+  return applyBookingRefDirectionScope(qb, 'i.source_id', directions);
+}
+
+export const agingReceivablesReport: ReportDefinition = {
+  key: 'aging-receivables',
+  title: 'Aging Receivables',
+  description: 'Outstanding customer balances bucketed by days overdue',
+  group: 'Finance',
+  filters: [{ key: 'asOf', label: 'As of', type: 'date' }],
+  columns: [
+    { key: 'customer', label: 'Customer', type: 'string', sortable: true, sortExpr: 'c.name' },
+    { key: 'invoices', label: 'Invoices', type: 'number' },
+    { key: 'outstanding', label: 'Outstanding', type: 'money', sortable: true },
+    { key: 'current', label: 'Current', type: 'money' },
+    { key: 'overdue0to30', label: '0-30d', type: 'money' },
+    { key: 'overdue31to60', label: '31-60d', type: 'money' },
+    { key: 'overdue61to90', label: '61-90d', type: 'money' },
+    { key: 'overdue90plus', label: '90d+', type: 'money' },
+  ],
+  defaultSort: { key: 'outstanding', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('c.name', 'customer')
+      .addSelect('COUNT(*)::int', 'invoices')
+      .addSelect('ROUND(SUM(i.balance_amount))::float8', 'outstanding')
+      .addSelect(
+        `ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at >= COALESCE(:asOf::timestamptz, now())), 0))::float8`,
+        'current',
+      )
+      .addSelect(
+        `ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at < COALESCE(:asOf::timestamptz, now())
+          AND i.due_at >= COALESCE(:asOf::timestamptz, now()) - interval '30 days'), 0))::float8`,
+        'overdue0to30',
+      )
+      .addSelect(
+        `ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at < COALESCE(:asOf::timestamptz, now()) - interval '30 days'
+          AND i.due_at >= COALESCE(:asOf::timestamptz, now()) - interval '60 days'), 0))::float8`,
+        'overdue31to60',
+      )
+      .addSelect(
+        `ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at < COALESCE(:asOf::timestamptz, now()) - interval '60 days'
+          AND i.due_at >= COALESCE(:asOf::timestamptz, now()) - interval '90 days'), 0))::float8`,
+        'overdue61to90',
+      )
+      .addSelect(
+        `ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at < COALESCE(:asOf::timestamptz, now()) - interval '90 days'), 0))::float8`,
+        'overdue90plus',
+      )
+      .groupBy('c.name');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('ROUND(COALESCE(SUM(i.balance_amount), 0))::float8', 'outstanding')
+      .addSelect('COUNT(DISTINCT c.id)::int', 'customers')
+      .getRawOne();
+    return [
+      { label: 'Outstanding', value: Number(row?.outstanding ?? 0), unit: 'ETB' },
+      { label: 'Customers with balance', value: Number(row?.customers ?? 0) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/bookings-list.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/bookings-list.report.ts
new file mode 100644
index 000000000..ca476cea3
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/bookings-list.report.ts
@@ -0,0 +1,129 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { Booking } from '../../bookings/entities/booking.entity';
+import { CargoType } from '../../rule-engine/entities/cargo-type.entity';
+import { Yard } from '../../rule-engine/entities/yard.entity';
+import { Company } from '../../companies/entities/company.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+// For PER_ITEM bulk bookings cargo_total_weight_vgm holds an item COUNT, and
+// the real tonnage lives in bulk_total_weight_tons — hence the COALESCE order
+// (same guard as the retired report-queries.ts).
+const TONS = 'COALESCE(b.bulk_total_weight_tons, b.cargo_total_weight_vgm)';
+// adjusted_total_amount silently overrides total_amount when set.
+const REVENUE = 'COALESCE(b.adjusted_total_amount, b.total_amount)';
+// GENERAL contract_kind rows are umbrella contracts, not shipments; counting
+// them double-counts every child booking.
+const NOT_UMBRELLA = "(b.contract_kind IS NULL OR b.contract_kind <> 'GENERAL')";
+const DEAD_STATUSES = ['DRAFT', 'CANCELLED', 'REJECTED', 'EXPIRED'];
+
+function applyFilters(
+  ctx: ReportContext,
+  qb: SelectQueryBuilder<ObjectLiteral>,
+): SelectQueryBuilder<ObjectLiteral> {
+  const { params, directions } = ctx;
+  qb.where(`b.deleted_at IS NULL AND ${NOT_UMBRELLA}`);
+  if (params.dateFrom) qb.andWhere('b.created_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('b.created_at < :dateTo', { dateTo: params.dateTo });
+  if (params.direction) qb.andWhere('b.trade_direction = :direction', { direction: params.direction });
+  if (params.freightType) qb.andWhere('b.freight_type = :freightType', { freightType: params.freightType });
+  const statuses = params.statuses as string[] | null;
+  if (statuses) {
+    qb.andWhere('b.status IN (:...statuses)', { statuses });
+  } else {
+    qb.andWhere('b.status NOT IN (:...deadStatuses)', { deadStatuses: DEAD_STATUSES });
+  }
+  if (params.search) {
+    qb.andWhere('(b.reference ILIKE :search OR c.name ILIKE :search)', {
+      search: `%${params.search}%`,
+    });
+  }
+  if (directions !== null) {
+    qb.andWhere(directions.length ? 'b.trade_direction IN (:...directions)' : '1 = 0', {
+      directions,
+    });
+  }
+  return qb;
+}
+
+export const bookingsListReport: ReportDefinition = {
+  key: 'bookings-list',
+  title: 'Bookings',
+  description: 'Every booking with customer, route, cargo and revenue',
+  group: 'Commercial',
+  filters: [
+    { key: 'date', label: 'Created', type: 'daterange' },
+    {
+      key: 'direction',
+      label: 'Direction',
+      type: 'select',
+      options: [
+        { value: 'IMPORT', label: 'Import' },
+        { value: 'EXPORT', label: 'Export' },
+        { value: 'DOMESTIC', label: 'Domestic' },
+      ],
+    },
+    {
+      key: 'freightType',
+      label: 'Freight type',
+      type: 'select',
+      options: [
+        { value: 'CONTAINER', label: 'Container' },
+        { value: 'BULK', label: 'Bulk' },
+      ],
+    },
+    { key: 'statuses', label: 'Status', type: 'multiselect' },
+    { key: 'search', label: 'Search reference or customer', type: 'text' },
+  ],
+  columns: [
+    { key: 'reference', label: 'Reference', type: 'string', sortable: true, sortExpr: 'b.reference' },
+    { key: 'created', label: 'Created', type: 'date', sortable: true, sortExpr: 'b.created_at' },
+    { key: 'customer', label: 'Customer', type: 'string', sortable: true, sortExpr: 'c.name' },
+    { key: 'status', label: 'Status', type: 'string', sortable: true, sortExpr: 'b.status' },
+    { key: 'direction', label: 'Direction', type: 'string' },
+    { key: 'origin', label: 'Origin', type: 'string' },
+    { key: 'destination', label: 'Destination', type: 'string' },
+    { key: 'cargo', label: 'Cargo', type: 'string' },
+    { key: 'tons', label: 'Tonnage', type: 'tons', sortable: true },
+    { key: 'amount', label: 'Amount', type: 'money', sortable: true },
+  ],
+  defaultSort: { key: 'created', dir: 'DESC' },
+  query(ctx) {
+    const qb = ctx.ds
+      .createQueryBuilder()
+      .select('b.reference', 'reference')
+      .addSelect(`to_char(b.created_at, 'YYYY-MM-DD')`, 'created')
+      .addSelect('c.name', 'customer')
+      .addSelect('b.status', 'status')
+      .addSelect('b.trade_direction', 'direction')
+      .addSelect('o.label', 'origin')
+      .addSelect('d.label', 'destination')
+      .addSelect('COALESCE(cty.cargo_type_name, b.cargo_free_text)', 'cargo')
+      .addSelect(`ROUND(${TONS})::float8`, 'tons')
+      .addSelect(`ROUND(${REVENUE})::float8`, 'amount')
+      .from(Booking, 'b')
+      .innerJoin(Company, 'c', 'c.id = b.company_id')
+      .innerJoin(Yard, 'o', 'o.id = b.origin_yard_id')
+      .innerJoin(Yard, 'd', 'd.id = b.destination_yard_id')
+      .leftJoin(CargoType, 'cty', 'cty.id = b.cargo_type_id');
+    return applyFilters(ctx, qb);
+  },
+  async summary(ctx) {
+    const qb = applyFilters(
+      ctx,
+      ctx.ds
+        .createQueryBuilder()
+        .select('COUNT(*)::int', 'bookings')
+        .addSelect(`ROUND(COALESCE(SUM(${TONS}), 0))::float8`, 'tons')
+        .addSelect(`ROUND(COALESCE(SUM(${REVENUE}), 0))::float8`, 'revenue')
+        .from(Booking, 'b')
+        .innerJoin(Company, 'c', 'c.id = b.company_id'),
+    );
+    const row = await qb.getRawOne();
+    return [
+      { label: 'Bookings', value: Number(row?.bookings ?? 0) },
+      { label: 'Tonnage', value: Number(row?.tons ?? 0), unit: 't' },
+      { label: 'Revenue', value: Number(row?.revenue ?? 0), unit: 'ETB' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/contract-utilization.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/contract-utilization.report.ts
new file mode 100644
index 000000000..03f98d306
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/contract-utilization.report.ts
@@ -0,0 +1,121 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { Company } from '../../companies/entities/company.entity';
+import { Contract } from '../../contracts/entities/contract.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+const TONS = 'COALESCE(b.bulk_total_weight_tons, b.cargo_total_weight_vgm)';
+const DEAD_STATUSES = ['DRAFT', 'CANCELLED', 'REJECTED', 'EXPIRED'];
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params, directions } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Contract, 'ct')
+    .leftJoin(Company, 'c', 'c.id = ct.company_id')
+    .leftJoin(
+      (sub) =>
+        sub
+          .select('s.contract_id', 'contract_id')
+          .addSelect('COALESCE(SUM(s.quantity_cap), 0)', 'committed')
+          .from('freight.contract_cargo_scope', 's')
+          .where('s.deleted_at IS NULL')
+          .groupBy('s.contract_id'),
+      'cap',
+      'cap.contract_id = ct.id',
+    )
+    .leftJoin(
+      (sub) =>
+        sub
+          .select('b.contract_id', 'contract_id')
+          .addSelect(`COALESCE(SUM(${TONS}), 0)`, 'tons')
+          .addSelect('COUNT(*)::int', 'cnt')
+          .from('freight.bookings', 'b')
+          .where('b.deleted_at IS NULL')
+          .andWhere('b.status NOT IN (:...deadStatuses)', { deadStatuses: DEAD_STATUSES })
+          .groupBy('b.contract_id'),
+      'booked',
+      'booked.contract_id = ct.id',
+    )
+    .where('ct.deleted_at IS NULL')
+    .andWhere("ct.status <> 'DRAFT'");
+
+  if (params.dateFrom) {
+    qb.andWhere(
+      "(ct.contract_valid_until IS NULL OR ct.contract_valid_until >= :dateFrom::timestamptz)",
+      { dateFrom: params.dateFrom },
+    );
+  }
+  if (params.dateTo) {
+    qb.andWhere('ct.contract_valid_from < :dateTo::timestamptz', { dateTo: params.dateTo });
+  }
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('ct.status IN (:...statuses)', { statuses });
+  if (params.contractId) {
+    qb.andWhere('ct.id = :contractId', { contractId: params.contractId });
+  }
+  if (directions !== null) {
+    qb.andWhere(directions.length ? 'ct.trade_direction IN (:...directions)' : '1 = 0', {
+      directions,
+    });
+  }
+  return qb;
+}
+
+export const contractUtilizationReport: ReportDefinition = {
+  key: 'contract-utilization',
+  title: 'Contract Utilization',
+  description: 'Committed volume vs. booked tonnage per contract',
+  group: 'Commercial',
+  idKey: { key: 'contractId', label: 'Contract' },
+  filters: [
+    { key: 'date', label: 'Active during', type: 'daterange' },
+    { key: 'statuses', label: 'Status', type: 'multiselect' },
+  ],
+  columns: [
+    { key: 'reference', label: 'Reference', type: 'string', sortable: true, sortExpr: 'ct.reference' },
+    { key: 'customer', label: 'Customer', type: 'string', sortable: true, sortExpr: 'c.name' },
+    { key: 'status', label: 'Status', type: 'string' },
+    { key: 'kind', label: 'Kind', type: 'string' },
+    { key: 'validFrom', label: 'Valid from', type: 'date' },
+    { key: 'validUntil', label: 'Valid until', type: 'date' },
+    { key: 'committed', label: 'Committed', type: 'tons' },
+    { key: 'bookedTons', label: 'Booked', type: 'tons', sortable: true },
+    { key: 'bookings', label: 'Bookings', type: 'number' },
+    { key: 'utilizationPct', label: 'Utilization', type: 'percent', sortable: true },
+  ],
+  defaultSort: { key: 'utilizationPct', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('ct.reference', 'reference')
+      .addSelect('c.name', 'customer')
+      .addSelect('ct.status', 'status')
+      .addSelect('ct.contract_kind', 'kind')
+      .addSelect(`to_char(ct.contract_valid_from, 'YYYY-MM-DD')`, 'validFrom')
+      .addSelect(`to_char(ct.contract_valid_until, 'YYYY-MM-DD')`, 'validUntil')
+      .addSelect('COALESCE(cap.committed, 0)::float8', 'committed')
+      .addSelect('COALESCE(booked.tons, 0)::float8', 'bookedTons')
+      .addSelect('COALESCE(booked.cnt, 0)', 'bookings')
+      .addSelect(
+        `CASE WHEN COALESCE(cap.committed, 0) > 0
+              THEN ROUND(COALESCE(booked.tons, 0) / cap.committed * 100)::float8 END`,
+        'utilizationPct',
+      );
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'contracts')
+      .addSelect('COALESCE(SUM(booked.tons), 0)::float8', 'bookedTons')
+      .addSelect(
+        `AVG(CASE WHEN COALESCE(cap.committed, 0) > 0
+              THEN booked.tons / cap.committed * 100 END)::float8`,
+        'avgUtilization',
+      )
+      .getRawOne();
+    return [
+      { label: 'Contracts', value: Number(row?.contracts ?? 0) },
+      { label: 'Booked tonnage', value: Number(row?.bookedTons ?? 0), unit: 't' },
+      { label: 'Avg utilization', value: Math.round(Number(row?.avgUtilization ?? 0)), unit: '%' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/revenue-by-customer.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/revenue-by-customer.report.ts
new file mode 100644
index 000000000..31b9951b8
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/revenue-by-customer.report.ts
@@ -0,0 +1,91 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { Booking } from '../../bookings/entities/booking.entity';
+import { Company } from '../../companies/entities/company.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+const TONS = 'COALESCE(b.bulk_total_weight_tons, b.cargo_total_weight_vgm)';
+const REVENUE = 'COALESCE(b.adjusted_total_amount, b.total_amount)';
+const NOT_UMBRELLA = "(b.contract_kind IS NULL OR b.contract_kind <> 'GENERAL')";
+const DEAD_STATUSES = ['DRAFT', 'CANCELLED', 'REJECTED', 'EXPIRED'];
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params, directions } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Booking, 'b')
+    .innerJoin(Company, 'c', 'c.id = b.company_id')
+    .where(`b.deleted_at IS NULL AND ${NOT_UMBRELLA}`);
+
+  if (params.dateFrom) qb.andWhere('b.created_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('b.created_at < :dateTo', { dateTo: params.dateTo });
+  if (params.direction) qb.andWhere('b.trade_direction = :direction', { direction: params.direction });
+  if (params.freightType) qb.andWhere('b.freight_type = :freightType', { freightType: params.freightType });
+  const statuses = params.statuses as string[] | null;
+  if (statuses) {
+    qb.andWhere('b.status IN (:...statuses)', { statuses });
+  } else {
+    qb.andWhere('b.status NOT IN (:...deadStatuses)', { deadStatuses: DEAD_STATUSES });
+  }
+  if (directions !== null) {
+    qb.andWhere(directions.length ? 'b.trade_direction IN (:...directions)' : '1 = 0', {
+      directions,
+    });
+  }
+  return qb;
+}
+
+export const revenueByCustomerReport: ReportDefinition = {
+  key: 'revenue-by-customer',
+  title: 'Revenue by Customer',
+  description: 'Ranked customers by booking revenue',
+  group: 'Commercial',
+  filters: [
+    { key: 'date', label: 'Created', type: 'daterange' },
+    {
+      key: 'direction',
+      label: 'Direction',
+      type: 'select',
+      options: [
+        { value: 'IMPORT', label: 'Import' },
+        { value: 'EXPORT', label: 'Export' },
+        { value: 'DOMESTIC', label: 'Domestic' },
+      ],
+    },
+    {
+      key: 'freightType',
+      label: 'Freight type',
+      type: 'select',
+      options: [
+        { value: 'CONTAINER', label: 'Container' },
+        { value: 'BULK', label: 'Bulk' },
+      ],
+    },
+    { key: 'statuses', label: 'Status', type: 'multiselect' },
+  ],
+  columns: [
+    { key: 'customer', label: 'Customer', type: 'string', sortable: true, sortExpr: 'c.name' },
+    { key: 'bookings', label: 'Bookings', type: 'number', sortable: true },
+    { key: 'tons', label: 'Tonnage', type: 'tons', sortable: true },
+    { key: 'revenue', label: 'Revenue', type: 'money', sortable: true },
+  ],
+  defaultSort: { key: 'revenue', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('c.name', 'customer')
+      .addSelect('COUNT(*)::int', 'bookings')
+      .addSelect(`ROUND(COALESCE(SUM(${TONS}), 0))::float8`, 'tons')
+      .addSelect(`ROUND(COALESCE(SUM(${REVENUE}), 0))::float8`, 'revenue')
+      .groupBy('c.name');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(DISTINCT c.name)::int', 'customers')
+      .addSelect(`ROUND(COALESCE(SUM(${REVENUE}), 0))::float8`, 'revenue')
+      .getRawOne();
+    return [
+      { label: 'Customers', value: Number(row?.customers ?? 0) },
+      { label: 'Revenue', value: Number(row?.revenue ?? 0), unit: 'ETB' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/dto/report-query.dto.ts b/apps/edr-freight-api/src/modules/reports/dto/report-query.dto.ts
deleted file mode 100644
index 82b1a76ef..000000000
--- a/apps/edr-freight-api/src/modules/reports/dto/report-query.dto.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-import { ApiPropertyOptional } from '@nestjs/swagger';
-import { IsIn, IsOptional, IsString } from 'class-validator';
-
-export class ReportQueryDto {
-  @ApiPropertyOptional({ description: 'Inclusive start date (YYYY-MM-DD). Default: 30 days ago.' })
-  @IsOptional()
-  @IsString()
-  dateFrom?: string;
-
-  @ApiPropertyOptional({ description: 'Inclusive end date (YYYY-MM-DD). Default: today.' })
-  @IsOptional()
-  @IsString()
-  dateTo?: string;
-
-  @ApiPropertyOptional({ enum: ['day', 'week', 'month'], default: 'day' })
-  @IsOptional()
-  @IsIn(['day', 'week', 'month'])
-  granularity?: 'day' | 'week' | 'month';
-
-  @ApiPropertyOptional({ description: 'Comma-separated company UUIDs' })
-  @IsOptional()
-  @IsString()
-  companyIds?: string;
-
-  @ApiPropertyOptional({ description: 'Comma-separated route UUIDs' })
-  @IsOptional()
-  @IsString()
-  routeIds?: string;
-
-  @ApiPropertyOptional({ description: 'Comma-separated yard UUIDs (matches origin or destination)' })
-  @IsOptional()
-  @IsString()
-  yardIds?: string;
-
-  @ApiPropertyOptional({ description: 'Comma-separated cargo type UUIDs' })
-  @IsOptional()
-  @IsString()
-  cargoTypeIds?: string;
-
-  @ApiPropertyOptional({ description: 'Comma-separated status values (report-specific)' })
-  @IsOptional()
-  @IsString()
-  statuses?: string;
-
-  @ApiPropertyOptional({ description: 'Trade direction filter' })
-  @IsOptional()
-  @IsString()
-  direction?: string;
-
-  @ApiPropertyOptional({ enum: ['CONTAINER', 'BULK'] })
-  @IsOptional()
-  @IsIn(['CONTAINER', 'BULK'])
-  freightType?: string;
-}
diff --git a/apps/edr-freight-api/src/modules/reports/dto/report-result.dto.ts b/apps/edr-freight-api/src/modules/reports/dto/report-result.dto.ts
deleted file mode 100644
index cc1c215af..000000000
--- a/apps/edr-freight-api/src/modules/reports/dto/report-result.dto.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-
-export class ReportKpiDto {
-  @ApiProperty()
-  label!: string;
-
-  @ApiProperty()
-  value!: number;
-
-  @ApiPropertyOptional()
-  unit?: string;
-}
-
-export class ReportResultDto {
-  @ApiProperty({ type: [ReportKpiDto] })
-  kpis!: ReportKpiDto[];
-
-  @ApiProperty({
-    type: 'array',
-    items: { type: 'object', additionalProperties: true },
-    description: 'Report rows; columns vary per report key',
-  })
-  rows!: Record<string, unknown>[];
-}
diff --git a/apps/edr-freight-api/src/modules/reports/report-export.service.ts b/apps/edr-freight-api/src/modules/reports/report-export.service.ts
new file mode 100644
index 000000000..f07317134
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/report-export.service.ts
@@ -0,0 +1,114 @@
+import { Injectable } from '@nestjs/common';
+import ExcelJS from 'exceljs';
+
+import { PdfRenderService } from '../billing/documents/pdf-render.service';
+import { ReportColumn, ReportDefinition, ReportKpi } from './report.types';
+
+// ponytail: in-memory Workbook, cap below. Switch to ExcelJS's streaming
+// WorkbookWriter if a report ever needs to outgrow XLSX_ROW_CAP.
+export const XLSX_ROW_CAP = 50_000;
+// ponytail: HTML→PDF render cost grows with row count; larger exports must
+// use XLSX instead.
+export const PDF_ROW_CAP = 5_000;
+
+const NUMBER_FORMAT: Partial<Record<ReportColumn['type'], string>> = {
+  money: '#,##0.00',
+  tons: '#,##0.0',
+  percent: '0"%"',
+  number: '#,##0',
+};
+
+function formatCell(value: unknown, type: ReportColumn['type']): string {
+  if (value === null || value === undefined) return '';
+  if (type === 'money' || type === 'number') {
+    return Number(value).toLocaleString('en-US', { maximumFractionDigits: 2 });
+  }
+  if (type === 'tons') return `${Number(value).toLocaleString('en-US')} t`;
+  if (type === 'percent') return `${value}%`;
+  return String(value);
+}
+
+@Injectable()
+export class ReportExportService {
+  constructor(private readonly pdfRender: PdfRenderService) {}
+
+  async toXlsx(
+    def: ReportDefinition,
+    rows: Record<string, unknown>[],
+    kpis: ReportKpi[],
+  ): Promise<Buffer> {
+    const workbook = new ExcelJS.Workbook();
+    const sheet = workbook.addWorksheet(def.title.slice(0, 31));
+
+    if (kpis.length) {
+      sheet.addRow(kpis.map((k) => `${k.label}: ${k.value.toLocaleString()}${k.unit ? ` ${k.unit}` : ''}`));
+      sheet.addRow([]);
+    }
+
+    const headerRow = sheet.addRow(def.columns.map((c) => c.label));
+    headerRow.font = { bold: true };
+
+    for (const row of rows) {
+      sheet.addRow(def.columns.map((c) => row[c.key] ?? null));
+    }
+
+    def.columns.forEach((col, i) => {
+      const format = NUMBER_FORMAT[col.type];
+      const excelCol = sheet.getColumn(i + 1);
+      excelCol.width = Math.max(col.label.length + 2, 12);
+      if (format) excelCol.numFmt = format;
+    });
+
+    const buffer = await workbook.xlsx.writeBuffer();
+    return Buffer.from(buffer);
+  }
+
+  async toPdf(
+    def: ReportDefinition,
+    rows: Record<string, unknown>[],
+    kpis: ReportKpi[],
+  ): Promise<Buffer> {
+    const html = this.buildHtml(def, rows, kpis);
+    return this.pdfRender.htmlToPdfBuffer(html, { label: `report:${def.key}`, landscape: true });
+  }
+
+  private buildHtml(
+    def: ReportDefinition,
+    rows: Record<string, unknown>[],
+    kpis: ReportKpi[],
+  ): string {
+    const esc = (v: unknown) =>
+      String(v ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+    const kpiHtml = kpis.length
+      ? `<div style="display:flex;gap:24px;margin-bottom:16px">${kpis
+          .map(
+            (k) =>
+              `<div><div style="font-size:11px;color:#666">${esc(k.label)}</div><div style="font-size:16px;font-weight:600">${k.value.toLocaleString()}${k.unit ? ` ${esc(k.unit)}` : ''}</div></div>`,
+          )
+          .join('')}</div>`
+      : '';
+
+    const head = def.columns.map((c) => `<th>${esc(c.label)}</th>`).join('');
+    const body = rows
+      .map(
+        (row) =>
+          `<tr>${def.columns.map((c) => `<td>${esc(formatCell(row[c.key], c.type))}</td>`).join('')}</tr>`,
+      )
+      .join('');
+
+    return `<!doctype html><html><head><meta charset="utf-8"><style>
+      body { font-family: Arial, sans-serif; font-size: 10px; color: #111; }
+      h1 { font-size: 16px; margin-bottom: 4px; }
+      p.desc { color: #666; margin-top: 0 0 12px; }
+      table { width: 100%; border-collapse: collapse; }
+      th, td { border: 1px solid #ddd; padding: 4px 6px; text-align: left; }
+      th { background: #f3f3f3; }
+    </style></head><body>
+      <h1>${esc(def.title)}</h1>
+      <p class="desc">${esc(def.description)}</p>
+      ${kpiHtml}
+      <table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>
+    </body></html>`;
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/reports/report-queries.ts b/apps/edr-freight-api/src/modules/reports/report-queries.ts
deleted file mode 100644
index 9e4a6f617..000000000
--- a/apps/edr-freight-api/src/modules/reports/report-queries.ts
+++ /dev/null
@@ -1,669 +0,0 @@
-import { DataSource } from 'typeorm';
-
-export interface ReportFilters {
-  /** ISO timestamp, inclusive lower bound. null = no lower bound (all time). */
-  dateFrom: string | null;
-  /** ISO timestamp, exclusive upper bound. null = no upper bound. */
-  dateTo: string | null;
-  granularity: 'day' | 'week' | 'month';
-  companyIds: string[] | null;
-  routeIds: string[] | null;
-  yardIds: string[] | null;
-  cargoTypeIds: string[] | null;
-  statuses: string[] | null;
-  /** Trade-scope-resolved directions. null = unrestricted, [] = show nothing. */
-  directions: string[] | null;
-  freightType: string | null;
-}
-
-export interface ReportKpi {
-  label: string;
-  value: number;
-  unit?: string;
-}
-
-export interface ReportResult {
-  kpis: ReportKpi[];
-  rows: Record<string, unknown>[];
-}
-
-type ReportQuery = (ds: DataSource, f: ReportFilters) => Promise<ReportResult>;
-
-// For PER_ITEM bulk bookings cargo_total_weight_vgm holds an item COUNT, and
-// the real tonnage lives in bulk_total_weight_tons — hence the COALESCE order.
-const TONS = 'COALESCE(b.bulk_total_weight_tons, b.cargo_total_weight_vgm)';
-// adjusted_total_amount silently overrides total_amount when set.
-const REVENUE = 'COALESCE(b.adjusted_total_amount, b.total_amount)';
-// GENERAL contract_kind rows are umbrella contracts, not shipments; counting
-// them double-counts every child booking (same guard as overview.repository).
-const NOT_UMBRELLA = "(b.contract_kind IS NULL OR b.contract_kind <> 'GENERAL')";
-const DEAD_STATUSES = "'DRAFT','CANCELLED','REJECTED','EXPIRED'";
-
-const num = (v: unknown): number => (v === null || v === undefined ? 0 : Number(v));
-const sum = (rows: Record<string, unknown>[], col: string): number =>
-  rows.reduce((acc, r) => acc + num(r[col]), 0);
-
-/**
- * Shared WHERE for booking-based reports (alias `b`).
- * Params occupy $1..$8 in this fixed order; report SQL continues at $9.
- */
-function bookingWhere(f: ReportFilters): { where: string; params: unknown[] } {
-  return {
-    where: `
-      b.deleted_at IS NULL
-      AND ${NOT_UMBRELLA}
-      AND ($1::timestamptz IS NULL OR b.created_at >= $1)
-      AND ($2::timestamptz IS NULL OR b.created_at < $2)
-      AND ($3::uuid[] IS NULL OR b.company_id = ANY($3))
-      AND ($4::uuid[] IS NULL OR b.cargo_type_id = ANY($4))
-      AND ($5::text[] IS NULL OR b.trade_direction = ANY($5))
-      AND ($6::text IS NULL OR b.freight_type = $6)
-      AND (CASE WHEN $7::text[] IS NULL
-            THEN b.status NOT IN (${DEAD_STATUSES})
-            ELSE b.status = ANY($7) END)
-      AND ($8::uuid[] IS NULL OR b.origin_yard_id = ANY($8) OR b.destination_yard_id = ANY($8))`,
-    params: [
-      f.dateFrom,
-      f.dateTo,
-      f.companyIds,
-      f.cargoTypeIds,
-      f.directions,
-      f.freightType,
-      f.statuses,
-      f.yardIds,
-    ],
-  };
-}
-
-/**
- * Direction scope for rows that reference a booking through a varchar id
- * column (invoices.source_id, payments.ref_id). Rows not pointing at a
- * booking stay visible — they carry no direction to scope by.
- * (Positional-param port of trade-scope.util's bookingRefScopeSql.)
- */
-const refDirScope = (refColumn: string, param: string): string => `
-  (${param}::text[] IS NULL OR NOT EXISTS (
-    SELECT 1 FROM freight.bookings sb
-    WHERE sb.id::text = ${refColumn} AND NOT (sb.trade_direction = ANY(${param}))))`;
-
-const bookingsTrend: ReportQuery = async (ds, f) => {
-  const { where, params } = bookingWhere(f);
-  const rows = await ds.query(
-    `SELECT to_char(date_trunc($9, b.created_at), 'YYYY-MM-DD') AS period,
-            COUNT(*)::int AS bookings,
-            ROUND(COALESCE(SUM(${TONS}), 0))::float8 AS tons,
-            ROUND(COALESCE(SUM(${REVENUE}), 0))::float8 AS revenue
-     FROM freight.bookings b
-     WHERE ${where}
-     GROUP BY 1 ORDER BY 1`,
-    [...params, f.granularity],
-  );
-  return {
-    kpis: [
-      { label: 'Bookings', value: sum(rows, 'bookings') },
-      { label: 'Tonnage', value: sum(rows, 'tons'), unit: 't' },
-      { label: 'Revenue', value: sum(rows, 'revenue'), unit: 'ETB' },
-    ],
-    rows,
-  };
-};
-
-const revenueByCustomer: ReportQuery = async (ds, f) => {
-  const { where, params } = bookingWhere(f);
-  const rows = await ds.query(
-    `SELECT c.name AS customer,
-            COUNT(*)::int AS bookings,
-            ROUND(COALESCE(SUM(${TONS}), 0))::float8 AS tons,
-            ROUND(COALESCE(SUM(${REVENUE}), 0))::float8 AS revenue
-     FROM freight.bookings b
-     JOIN freight.companies c ON c.id = b.company_id
-     WHERE ${where}
-     GROUP BY c.name ORDER BY revenue DESC LIMIT 100`,
-    params,
-  );
-  const total = sum(rows, 'revenue');
-  return {
-    kpis: [
-      { label: 'Customers', value: rows.length },
-      { label: 'Revenue', value: total, unit: 'ETB' },
-      {
-        label: 'Top customer share',
-        value: total > 0 ? Math.round((num(rows[0]?.revenue) / total) * 100) : 0,
-        unit: '%',
-      },
-    ],
-    rows,
-  };
-};
-
-const revenueByLane: ReportQuery = async (ds, f) => {
-  const { where, params } = bookingWhere(f);
-  const rows = await ds.query(
-    `SELECT o.label AS origin, d.label AS destination,
-            COUNT(*)::int AS bookings,
-            ROUND(COALESCE(SUM(${TONS}), 0))::float8 AS tons,
-            ROUND(COALESCE(SUM(${REVENUE}), 0))::float8 AS revenue
-     FROM freight.bookings b
-     JOIN freight.yards o ON o.id = b.origin_yard_id
-     JOIN freight.yards d ON d.id = b.destination_yard_id
-     WHERE ${where}
-     GROUP BY 1, 2 ORDER BY revenue DESC LIMIT 100`,
-    params,
-  );
-  return {
-    kpis: [
-      { label: 'Lanes', value: rows.length },
-      { label: 'Tonnage', value: sum(rows, 'tons'), unit: 't' },
-      { label: 'Revenue', value: sum(rows, 'revenue'), unit: 'ETB' },
-    ],
-    rows,
-  };
-};
-
-const contractUtilization: ReportQuery = async (ds, f) => {
-  const rows = await ds.query(
-    `SELECT ct.reference, c.name AS customer, ct.status, ct.contract_kind AS kind,
-            to_char(ct.contract_valid_from, 'YYYY-MM-DD') AS valid_from,
-            to_char(ct.contract_valid_until, 'YYYY-MM-DD') AS valid_until,
-            cap.committed::float8 AS committed,
-            booked.tons::float8 AS booked_tons,
-            booked.cnt AS bookings,
-            CASE WHEN cap.committed > 0
-                 THEN ROUND(booked.tons / cap.committed * 100)::float8 END AS utilization_pct
-     FROM freight.contracts ct
-     LEFT JOIN freight.companies c ON c.id = ct.company_id
-     LEFT JOIN LATERAL (
-       SELECT COALESCE(SUM(s.quantity_cap), 0) AS committed
-       FROM freight.contract_cargo_scope s
-       WHERE s.contract_id = ct.id AND s.deleted_at IS NULL) cap ON true
-     LEFT JOIN LATERAL (
-       SELECT COALESCE(SUM(${TONS}), 0) AS tons, COUNT(*)::int AS cnt
-       FROM freight.bookings b
-       WHERE b.contract_id = ct.id AND b.deleted_at IS NULL
-         AND b.status NOT IN (${DEAD_STATUSES})) booked ON true
-     WHERE ct.deleted_at IS NULL
-       AND ct.status NOT IN ('DRAFT')
-       AND ct.contract_valid_from < COALESCE($2::timestamptz, 'infinity')
-       AND (ct.contract_valid_until IS NULL
-            OR ct.contract_valid_until >= COALESCE($1::timestamptz, '-infinity'))
-       AND ($3::uuid[] IS NULL OR ct.company_id = ANY($3))
-       AND ($4::text[] IS NULL OR ct.trade_direction = ANY($4))
-       AND ($5::text[] IS NULL OR ct.status = ANY($5))
-     ORDER BY utilization_pct DESC NULLS LAST LIMIT 200`,
-    [f.dateFrom, f.dateTo, f.companyIds, f.directions, f.statuses],
-  );
-  const capped = rows.filter((r: Record<string, unknown>) => num(r.committed) > 0);
-  return {
-    kpis: [
-      { label: 'Contracts', value: rows.length },
-      {
-        label: 'Avg utilization',
-        value: capped.length
-          ? Math.round(sum(capped, 'utilization_pct') / capped.length)
-          : 0,
-        unit: '%',
-      },
-      { label: 'Booked tonnage', value: sum(rows, 'booked_tons'), unit: 't' },
-    ],
-    rows,
-  };
-};
-
-// ponytail: 60-min departure grace is a constant; make it a query param if ops
-// ever wants a configurable threshold.
-const trainOnTime: ReportQuery = async (ds, f) => {
-  const rows = await ds.query(
-    `SELECT o.label AS origin, d.label AS destination,
-            COUNT(*)::int AS trips,
-            COUNT(*) FILTER (WHERE ts.actual_departure_at IS NOT NULL)::int AS departed,
-            ROUND(AVG(EXTRACT(EPOCH FROM (ts.actual_departure_at - ts.scheduled_departure_date)) / 60)
-              FILTER (WHERE ts.actual_departure_at IS NOT NULL))::float8 AS avg_dep_delay_min,
-            ROUND(AVG(EXTRACT(EPOCH FROM (ts.actual_arrival_at - ts.scheduled_arrival_date)) / 60)
-              FILTER (WHERE ts.actual_arrival_at IS NOT NULL
-                        AND ts.scheduled_arrival_date IS NOT NULL))::float8 AS avg_arr_delay_min,
-            ROUND(100.0 * COUNT(*) FILTER (WHERE ts.actual_departure_at
-                                             <= ts.scheduled_departure_date + interval '60 minutes')
-              / NULLIF(COUNT(*) FILTER (WHERE ts.actual_departure_at IS NOT NULL), 0))::float8 AS on_time_pct
-     FROM freight.train_schedules ts
-     JOIN freight.yards o ON o.id = ts.origin_station_id
-     JOIN freight.yards d ON d.id = ts.destination_station_id
-     WHERE ts.deleted_at IS NULL
-       AND ts.status IN ('DISPATCHED', 'ARRIVED')
-       AND ($1::timestamptz IS NULL OR ts.scheduled_departure_date >= $1)
-       AND ($2::timestamptz IS NULL OR ts.scheduled_departure_date < $2)
-       AND ($3::uuid[] IS NULL OR ts.route_id = ANY($3))
-       AND ($4::text[] IS NULL OR ts.direction = ANY($4))
-       AND ($5::uuid[] IS NULL OR ts.origin_station_id = ANY($5) OR ts.destination_station_id = ANY($5))
-     GROUP BY 1, 2 ORDER BY trips DESC`,
-    [f.dateFrom, f.dateTo, f.routeIds, f.directions, f.yardIds],
-  );
-  const departed = sum(rows, 'departed');
-  const weighted = rows.reduce(
-    (acc: number, r: Record<string, unknown>) =>
-      acc + (num(r.on_time_pct) * num(r.departed)) / 100,
-    0,
-  );
-  return {
-    kpis: [
-      { label: 'Trips', value: sum(rows, 'trips') },
-      {
-        label: 'On-time departures',
-        value: departed > 0 ? Math.round((weighted / departed) * 100) : 0,
-        unit: '%',
-      },
-      {
-        label: 'Avg departure delay',
-        value: rows.length ? Math.round(sum(rows, 'avg_dep_delay_min') / rows.length) : 0,
-        unit: 'min',
-      },
-    ],
-    rows,
-  };
-};
-
-const scheduleFillRate: ReportQuery = async (ds, f) => {
-  const rows = await ds.query(
-    `SELECT ts.train_number, ts.reference,
-            to_char(ts.scheduled_departure_date, 'YYYY-MM-DD') AS departure,
-            o.label AS origin, d.label AS destination, ts.direction, ts.status,
-            ts.max_wagons, tset.wagon_count,
-            ROUND(w.cap_tons)::float8 AS capacity_tons,
-            ROUND(w.booked_tons)::float8 AS booked_tons,
-            CASE WHEN w.cap_tons > 0
-                 THEN ROUND(w.booked_tons / w.cap_tons * 100)::float8 END AS fill_pct
-     FROM freight.train_schedules ts
-     JOIN freight.yards o ON o.id = ts.origin_station_id
-     JOIN freight.yards d ON d.id = ts.destination_station_id
-     LEFT JOIN freight.train_sets tset ON tset.id = ts.train_set_id
-     LEFT JOIN LATERAL (
-       SELECT COALESCE(SUM(tw.capacity_tons), 0) AS cap_tons,
-              COALESCE(SUM(tw.assigned_weight_tons), 0) AS booked_tons
-       FROM freight.train_set_wagons tw
-       WHERE tw.train_set_id = ts.train_set_id AND tw.deleted_at IS NULL) w ON true
-     WHERE ts.deleted_at IS NULL
-       AND ts.status <> 'CANCELLED'
-       AND ($1::timestamptz IS NULL OR ts.scheduled_departure_date >= $1)
-       AND ($2::timestamptz IS NULL OR ts.scheduled_departure_date < $2)
-       AND ($3::uuid[] IS NULL OR ts.route_id = ANY($3))
-       AND ($4::text[] IS NULL OR ts.direction = ANY($4))
-       AND ($5::uuid[] IS NULL OR ts.origin_station_id = ANY($5) OR ts.destination_station_id = ANY($5))
-     ORDER BY ts.scheduled_departure_date DESC LIMIT 200`,
-    [f.dateFrom, f.dateTo, f.routeIds, f.directions, f.yardIds],
-  );
-  const withCap = rows.filter((r: Record<string, unknown>) => num(r.capacity_tons) > 0);
-  const capTons = sum(withCap, 'capacity_tons');
-  return {
-    kpis: [
-      { label: 'Schedules', value: rows.length },
-      {
-        label: 'Avg fill rate',
-        value: capTons > 0 ? Math.round((sum(withCap, 'booked_tons') / capTons) * 100) : 0,
-        unit: '%',
-      },
-      { label: 'Booked tonnage', value: sum(rows, 'booked_tons'), unit: 't' },
-    ],
-    rows,
-  };
-};
-
-const tripsPerRoute: ReportQuery = async (ds, f) => {
-  const rows = await ds.query(
-    `SELECT o.label AS origin, d.label AS destination, ts.direction,
-            COUNT(*)::int AS trips,
-            ROUND(COALESCE(SUM(w.booked_tons), 0))::float8 AS tons_hauled,
-            ROUND(COALESCE(AVG(w.booked_tons), 0))::float8 AS avg_tons_per_trip
-     FROM freight.train_schedules ts
-     JOIN freight.yards o ON o.id = ts.origin_station_id
-     JOIN freight.yards d ON d.id = ts.destination_station_id
-     LEFT JOIN LATERAL (
-       SELECT COALESCE(SUM(tw.assigned_weight_tons), 0) AS booked_tons
-       FROM freight.train_set_wagons tw
-       WHERE tw.train_set_id = ts.train_set_id AND tw.deleted_at IS NULL) w ON true
-     WHERE ts.deleted_at IS NULL
-       AND ts.status IN ('DISPATCHED', 'ARRIVED')
-       AND ($1::timestamptz IS NULL OR ts.scheduled_departure_date >= $1)
-       AND ($2::timestamptz IS NULL OR ts.scheduled_departure_date < $2)
-       AND ($3::uuid[] IS NULL OR ts.route_id = ANY($3))
-       AND ($4::text[] IS NULL OR ts.direction = ANY($4))
-       AND ($5::uuid[] IS NULL OR ts.origin_station_id = ANY($5) OR ts.destination_station_id = ANY($5))
-     GROUP BY 1, 2, 3 ORDER BY trips DESC`,
-    [f.dateFrom, f.dateTo, f.routeIds, f.directions, f.yardIds],
-  );
-  return {
-    kpis: [
-      { label: 'Trips', value: sum(rows, 'trips') },
-      { label: 'Routes served', value: rows.length },
-      { label: 'Tonnage hauled', value: sum(rows, 'tons_hauled'), unit: 't' },
-    ],
-    rows,
-  };
-};
-
-const invoicedVsCollected: ReportQuery = async (ds, f) => {
-  const rows = await ds.query(
-    `SELECT to_char(date_trunc($5, COALESCE(i.issued_at, i.created_at)), 'YYYY-MM-DD') AS period,
-            COUNT(*)::int AS invoices,
-            ROUND(SUM(i.total_amount))::float8 AS invoiced,
-            ROUND(SUM(i.paid_amount))::float8 AS collected,
-            ROUND(SUM(i.balance_amount))::float8 AS outstanding
-     FROM freight.invoices i
-     WHERE i.deleted_at IS NULL
-       AND i.status NOT IN ('DRAFT', 'CANCELLED')
-       AND ($1::timestamptz IS NULL OR COALESCE(i.issued_at, i.created_at) >= $1)
-       AND ($2::timestamptz IS NULL OR COALESCE(i.issued_at, i.created_at) < $2)
-       AND ($3::uuid[] IS NULL OR i.company_id = ANY($3))
-       AND ${refDirScope('i.source_id', '$4')}
-     GROUP BY 1 ORDER BY 1`,
-    [f.dateFrom, f.dateTo, f.companyIds, f.directions, f.granularity],
-  );
-  const invoiced = sum(rows, 'invoiced');
-  const collected = sum(rows, 'collected');
-  return {
-    kpis: [
-      { label: 'Invoiced', value: invoiced, unit: 'ETB' },
-      { label: 'Collected', value: collected, unit: 'ETB' },
-      {
-        label: 'Collection rate',
-        value: invoiced > 0 ? Math.round((collected / invoiced) * 100) : 0,
-        unit: '%',
-      },
-      { label: 'Outstanding', value: sum(rows, 'outstanding'), unit: 'ETB' },
-    ],
-    rows,
-  };
-};
-
-// Aging is an as-of snapshot: dateTo is the as-of moment (default now),
-// dateFrom is ignored.
-const agingReceivables: ReportQuery = async (ds, f) => {
-  const rows = await ds.query(
-    `SELECT c.name AS customer,
-            COUNT(*)::int AS invoices,
-            ROUND(SUM(i.balance_amount))::float8 AS outstanding,
-            ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at >= COALESCE($1::timestamptz, now())), 0))::float8 AS current,
-            ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at < COALESCE($1::timestamptz, now())
-              AND i.due_at >= COALESCE($1::timestamptz, now()) - interval '30 days'), 0))::float8 AS overdue_0_30,
-            ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at < COALESCE($1::timestamptz, now()) - interval '30 days'
-              AND i.due_at >= COALESCE($1::timestamptz, now()) - interval '60 days'), 0))::float8 AS overdue_31_60,
-            ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at < COALESCE($1::timestamptz, now()) - interval '60 days'
-              AND i.due_at >= COALESCE($1::timestamptz, now()) - interval '90 days'), 0))::float8 AS overdue_61_90,
-            ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at < COALESCE($1::timestamptz, now()) - interval '90 days'), 0))::float8 AS overdue_90_plus
-     FROM freight.invoices i
-     JOIN freight.companies c ON c.id = i.company_id
-     WHERE i.deleted_at IS NULL
-       AND i.status IN ('ISSUED', 'PENDING', 'PARTIALLY_PAID', 'OVERDUE')
-       AND i.balance_amount > 0
-       AND ($1::timestamptz IS NULL OR i.created_at < $1)
-       AND ($2::uuid[] IS NULL OR i.company_id = ANY($2))
-       AND ${refDirScope('i.source_id', '$3')}
-     GROUP BY 1 ORDER BY outstanding DESC LIMIT 200`,
-    [f.dateTo, f.companyIds, f.directions],
-  );
-  const outstanding = sum(rows, 'outstanding');
-  return {
-    kpis: [
-      { label: 'Outstanding', value: outstanding, unit: 'ETB' },
-      { label: 'Overdue', value: outstanding - sum(rows, 'current'), unit: 'ETB' },
-      { label: 'Customers with balance', value: rows.length },
-    ],
-    rows,
-  };
-};
-
-const revenueByPaymentMethod: ReportQuery = async (ds, f) => {
-  // payments.status values are lowercase-hyphenated ('success'), unlike every
-  // other status enum in the schema. No deleted_at on this table.
-  const rows = await ds.query(
-    `SELECT p.method::text AS method,
-            COUNT(*)::int AS payments,
-            ROUND(SUM(p.amount))::float8 AS amount
-     FROM freight.payments p
-     WHERE p.status = 'success'
-       AND ($1::timestamptz IS NULL OR p.created_at >= $1)
-       AND ($2::timestamptz IS NULL OR p.created_at < $2)
-       AND ${refDirScope('p.ref_id', '$3')}
-     GROUP BY 1 ORDER BY amount DESC`,
-    [f.dateFrom, f.dateTo, f.directions],
-  );
-  const total = sum(rows, 'amount');
-  return {
-    kpis: [
-      { label: 'Collected', value: total, unit: 'ETB' },
-      { label: 'Payments', value: sum(rows, 'payments') },
-      {
-        label: 'Top method share',
-        value: total > 0 ? Math.round((num(rows[0]?.amount) / total) * 100) : 0,
-        unit: '%',
-      },
-    ],
-    rows,
-  };
-};
-
-// ---------------------------------------------------------------------------
-// Record-level list exports. Same engine, raw rows instead of aggregates.
-// ponytail: flat LIMIT 5000 per list — stream/paginate the export if a table
-// ever outgrows that.
-const LIST_LIMIT = 5000;
-
-const bookingsList: ReportQuery = async (ds, f) => {
-  const { where, params } = bookingWhere(f);
-  const rows = await ds.query(
-    `SELECT b.reference,
-            to_char(b.created_at, 'YYYY-MM-DD') AS created,
-            c.name AS customer, b.status, b.freight_type,
-            b.trade_direction AS direction,
-            o.label AS origin, d.label AS destination,
-            COALESCE(cty.cargo_type_name, b.cargo_free_text) AS cargo,
-            ROUND(${TONS})::float8 AS tons,
-            ROUND(${REVENUE})::float8 AS amount,
-            b.payment_status, b.scheduling_status
-     FROM freight.bookings b
-     JOIN freight.companies c ON c.id = b.company_id
-     JOIN freight.yards o ON o.id = b.origin_yard_id
-     JOIN freight.yards d ON d.id = b.destination_yard_id
-     LEFT JOIN freight.cargo_types cty ON cty.id = b.cargo_type_id
-     WHERE ${where}
-     ORDER BY b.created_at DESC LIMIT ${LIST_LIMIT}`,
-    params,
-  );
-  return {
-    kpis: [
-      { label: 'Bookings', value: rows.length },
-      { label: 'Tonnage', value: sum(rows, 'tons'), unit: 't' },
-      { label: 'Amount', value: sum(rows, 'amount'), unit: 'ETB' },
-    ],
-    rows,
-  };
-};
-
-const contractsList: ReportQuery = async (ds, f) => {
-  const rows = await ds.query(
-    `SELECT ct.reference, c.name AS customer, ct.contract_kind AS kind,
-            ct.status, ct.trade_direction AS direction, ct.freight_type,
-            to_char(ct.contract_valid_from, 'YYYY-MM-DD') AS valid_from,
-            to_char(ct.contract_valid_until, 'YYYY-MM-DD') AS valid_until,
-            to_char(ct.created_at, 'YYYY-MM-DD') AS created
-     FROM freight.contracts ct
-     LEFT JOIN freight.companies c ON c.id = ct.company_id
-     WHERE ct.deleted_at IS NULL
-       AND ($1::timestamptz IS NULL OR ct.created_at >= $1)
-       AND ($2::timestamptz IS NULL OR ct.created_at < $2)
-       AND ($3::uuid[] IS NULL OR ct.company_id = ANY($3))
-       AND ($4::text[] IS NULL OR ct.trade_direction = ANY($4))
-       AND ($5::text[] IS NULL OR ct.status = ANY($5))
-     ORDER BY ct.created_at DESC LIMIT ${LIST_LIMIT}`,
-    [f.dateFrom, f.dateTo, f.companyIds, f.directions, f.statuses],
-  );
-  const active = rows.filter((r: Record<string, unknown>) =>
-    ['CONTRACT_ACTIVE', 'ACTIVE_SHIPMENT_IN_PROGRESS'].includes(String(r.status)),
-  ).length;
-  return {
-    kpis: [
-      { label: 'Contracts', value: rows.length },
-      { label: 'Active', value: active },
-    ],
-    rows,
-  };
-};
-
-const schedulesList: ReportQuery = async (ds, f) => {
-  const rows = await ds.query(
-    `SELECT ts.train_number, ts.reference, ts.direction, ts.status,
-            o.label AS origin, d.label AS destination,
-            to_char(ts.scheduled_departure_date, 'YYYY-MM-DD HH24:MI') AS scheduled_departure,
-            to_char(ts.actual_departure_at, 'YYYY-MM-DD HH24:MI') AS actual_departure,
-            to_char(ts.scheduled_arrival_date, 'YYYY-MM-DD HH24:MI') AS scheduled_arrival,
-            to_char(ts.actual_arrival_at, 'YYYY-MM-DD HH24:MI') AS actual_arrival,
-            ts.max_wagons, tset.wagon_count
-     FROM freight.train_schedules ts
-     JOIN freight.yards o ON o.id = ts.origin_station_id
-     JOIN freight.yards d ON d.id = ts.destination_station_id
-     LEFT JOIN freight.train_sets tset ON tset.id = ts.train_set_id
-     WHERE ts.deleted_at IS NULL
-       AND ($1::timestamptz IS NULL OR ts.scheduled_departure_date >= $1)
-       AND ($2::timestamptz IS NULL OR ts.scheduled_departure_date < $2)
-       AND ($3::text[] IS NULL OR ts.direction = ANY($3))
-       AND ($4::text[] IS NULL OR ts.status = ANY($4))
-       AND ($5::uuid[] IS NULL OR ts.origin_station_id = ANY($5) OR ts.destination_station_id = ANY($5))
-     ORDER BY ts.scheduled_departure_date DESC LIMIT ${LIST_LIMIT}`,
-    [f.dateFrom, f.dateTo, f.directions, f.statuses, f.yardIds],
-  );
-  const count = (s: string) =>
-    rows.filter((r: Record<string, unknown>) => r.status === s).length;
-  return {
-    kpis: [
-      { label: 'Schedules', value: rows.length },
-      { label: 'Dispatched', value: count('DISPATCHED') },
-      { label: 'Arrived', value: count('ARRIVED') },
-    ],
-    rows,
-  };
-};
-
-const fleetWagons: ReportQuery = async (ds, f) => {
-  const rows = await ds.query(
-    `SELECT w.wagon_number, wt.name AS type,
-            wt.capacity_tons::float8 AS capacity_tons,
-            w.status, y.label AS current_yard
-     FROM freight.wagons w
-     JOIN freight.wagon_types wt ON wt.id = w.wagon_type_id
-     LEFT JOIN freight.yards y ON y.id = w.current_yard_id
-     WHERE w.deleted_at IS NULL
-       AND ($1::text[] IS NULL OR w.status = ANY($1))
-       AND ($2::uuid[] IS NULL OR w.current_yard_id = ANY($2))
-     ORDER BY w.wagon_number LIMIT ${LIST_LIMIT}`,
-    [f.statuses, f.yardIds],
-  );
-  const count = (s: string) =>
-    rows.filter((r: Record<string, unknown>) => r.status === s).length;
-  return {
-    kpis: [
-      { label: 'Wagons', value: rows.length },
-      { label: 'Available', value: count('AVAILABLE') },
-      { label: 'Assigned', value: count('ASSIGNED') },
-      { label: 'Maintenance', value: count('MAINTENANCE') },
-    ],
-    rows,
-  };
-};
-
-const fleetLocomotives: ReportQuery = async (ds, f) => {
-  const rows = await ds.query(
-    `SELECT l.code, l.name, l.locomotive_type,
-            l.max_pull_weight_tons::float8 AS max_pull_tons,
-            l.status, y.label AS current_yard
-     FROM freight.locomotives l
-     LEFT JOIN freight.yards y ON y.id = l.current_yard_id
-     WHERE l.deleted_at IS NULL
-       AND ($1::text[] IS NULL OR l.status = ANY($1))
-       AND ($2::uuid[] IS NULL OR l.current_yard_id = ANY($2))
-     ORDER BY l.code LIMIT ${LIST_LIMIT}`,
-    [f.statuses, f.yardIds],
-  );
-  const available = rows.filter(
-    (r: Record<string, unknown>) => r.status === 'AVAILABLE',
-  ).length;
-  return {
-    kpis: [
-      { label: 'Locomotives', value: rows.length },
-      { label: 'Available', value: available },
-    ],
-    rows,
-  };
-};
-
-const customersList: ReportQuery = async (ds, f) => {
-  const rows = await ds.query(
-    `SELECT c.name, c.type, c.kind, c.status, c.tin,
-            to_char(c.approved_at, 'YYYY-MM-DD') AS approved,
-            to_char(c.created_at, 'YYYY-MM-DD') AS created
-     FROM freight.companies c
-     WHERE c.deleted_at IS NULL
-       AND ($1::timestamptz IS NULL OR c.created_at >= $1)
-       AND ($2::timestamptz IS NULL OR c.created_at < $2)
-       AND ($3::text[] IS NULL OR c.status = ANY($3))
-     ORDER BY c.created_at DESC LIMIT ${LIST_LIMIT}`,
-    [f.dateFrom, f.dateTo, f.statuses],
-  );
-  const active = rows.filter(
-    (r: Record<string, unknown>) => r.status === 'active',
-  ).length;
-  return {
-    kpis: [
-      { label: 'Customers', value: rows.length },
-      { label: 'Active', value: active },
-    ],
-    rows,
-  };
-};
-
-const paymentsList: ReportQuery = async (ds, f) => {
-  // No deleted_at on freight.payments; statuses are lowercase-hyphenated.
-  const rows = await ds.query(
-    `SELECT to_char(p.created_at, 'YYYY-MM-DD HH24:MI') AS created,
-            p.method::text AS method, p.status::text AS status,
-            p.currency::text AS currency,
-            ROUND(p.amount)::float8 AS amount,
-            p.transaction_id, p.merchant_order_id,
-            to_char(p.paid_at, 'YYYY-MM-DD') AS paid
-     FROM freight.payments p
-     WHERE ($1::timestamptz IS NULL OR p.created_at >= $1)
-       AND ($2::timestamptz IS NULL OR p.created_at < $2)
-       AND ($3::text[] IS NULL OR p.status::text = ANY($3))
-       AND ${refDirScope('p.ref_id', '$4')}
-     ORDER BY p.created_at DESC LIMIT ${LIST_LIMIT}`,
-    [f.dateFrom, f.dateTo, f.statuses, f.directions],
-  );
-  const success = rows.filter(
-    (r: Record<string, unknown>) => r.status === 'success',
-  );
-  return {
-    kpis: [
-      { label: 'Payments', value: rows.length },
-      { label: 'Successful', value: success.length },
-      { label: 'Collected', value: sum(success, 'amount'), unit: 'ETB' },
-    ],
-    rows,
-  };
-};
-
-export const REPORT_QUERIES: Record<string, ReportQuery> = {
-  'bookings-list': bookingsList,
-  'contracts-list': contractsList,
-  'schedules-list': schedulesList,
-  'fleet-wagons': fleetWagons,
-  'fleet-locomotives': fleetLocomotives,
-  'customers-list': customersList,
-  'payments-list': paymentsList,
-  'bookings-trend': bookingsTrend,
-  'revenue-by-customer': revenueByCustomer,
-  'revenue-by-lane': revenueByLane,
-  'contract-utilization': contractUtilization,
-  'train-on-time': trainOnTime,
-  'schedule-fill-rate': scheduleFillRate,
-  'trips-per-route': tripsPerRoute,
-  'invoiced-vs-collected': invoicedVsCollected,
-  'aging-receivables': agingReceivables,
-  'revenue-by-payment-method': revenueByPaymentMethod,
-};
diff --git a/apps/edr-freight-api/src/modules/reports/report-runner.service.ts b/apps/edr-freight-api/src/modules/reports/report-runner.service.ts
new file mode 100644
index 000000000..5df9ba2e1
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/report-runner.service.ts
@@ -0,0 +1,141 @@
+import { BadRequestException, Injectable } from '@nestjs/common';
+import { InjectDataSource } from '@nestjs/typeorm';
+import { DataSource } from 'typeorm';
+
+import {
+  buildPaginationMeta,
+  normalizePagination,
+} from '../../common/utils/pagination.util';
+import { applyBookingRefDirectionScope } from '../user-trade-access/trade-scope.util';
+import { ReportDefinition, ReportRunResult } from './report.types';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Raw query params, minus the pagination/sort keys the runner owns. */
+export type RawReportQuery = Record<string, string | undefined>;
+
+/**
+ * Coerce raw query strings into typed filter params per the report's own
+ * filter declarations. Unknown filter keys are ignored — `forbidNonWhitelisted`
+ * can't police a per-report bag, so extras are just dropped, not rejected.
+ */
+function coerceParams(
+  def: ReportDefinition,
+  raw: RawReportQuery,
+): Record<string, unknown> {
+  const params: Record<string, unknown> = {};
+  for (const filter of def.filters) {
+    if (filter.type === 'daterange') {
+      const from = raw[`${filter.key}From`];
+      const to = raw[`${filter.key}To`];
+      params[`${filter.key}From`] = from ? new Date(from).toISOString() : null;
+      // Inclusive end date, exclusive bound in SQL.
+      params[`${filter.key}To`] = to
+        ? new Date(new Date(to).getTime() + DAY_MS).toISOString()
+        : null;
+    } else if (filter.type === 'multiselect') {
+      const csv = raw[filter.key];
+      const items = csv?.split(',').map((s) => s.trim()).filter(Boolean) ?? [];
+      params[filter.key] = items.length ? items : null;
+    } else {
+      params[filter.key] = raw[filter.key]?.trim() || null;
+    }
+  }
+  // idKey, when the report declares one, is a plain string param.
+  if (def.idKey) {
+    params[def.idKey.key] = raw[def.idKey.key]?.trim() || null;
+  }
+  return params;
+}
+
+/** Resolve a client-requested sort column against the report's own whitelist. */
+function resolveSort(
+  def: ReportDefinition,
+  sortBy?: string,
+  sortOrder?: string,
+): { key: string; expr: string; dir: 'ASC' | 'DESC' } | null {
+  const dir = sortOrder?.toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
+  const requested = sortBy && def.columns.find((c) => c.key === sortBy && c.sortable);
+  if (requested) {
+    return { key: requested.key, expr: requested.sortExpr ?? requested.key, dir };
+  }
+  if (!def.defaultSort) return null;
+  const fallback = def.columns.find((c) => c.key === def.defaultSort!.key);
+  if (!fallback) return null;
+  return {
+    key: fallback.key,
+    expr: fallback.sortExpr ?? fallback.key,
+    dir: def.defaultSort.dir,
+  };
+}
+
+@Injectable()
+export class ReportRunnerService {
+  constructor(@InjectDataSource() private readonly ds: DataSource) {}
+
+  async run(
+    def: ReportDefinition,
+    raw: RawReportQuery,
+    directions: string[] | null,
+  ): Promise<ReportRunResult> {
+    const params = coerceParams(def, raw);
+    const ctx = { ds: this.ds, params, directions };
+
+    const qb = def.query(ctx);
+    const sort = resolveSort(def, raw.sortBy, raw.sortOrder);
+    if (sort) qb.orderBy(sort.expr, sort.dir);
+
+    const { page: pageNum, pageSize, skip, take } = normalizePagination({
+      page: raw.page ? Number(raw.page) : undefined,
+      pageSize: raw.pageSize ? Number(raw.pageSize) : undefined,
+    });
+
+    const [sql, sqlParams] = qb.getQueryAndParameters();
+    // getCount() re-derives its own (wrong) select list for GROUP BY queries —
+    // wrapping the real query as a subquery counts exactly what will be paged.
+    const countRow = await this.ds.query(
+      `SELECT COUNT(*)::int AS c FROM (${sql}) report_count`,
+      sqlParams,
+    );
+    const total = Number(countRow[0]?.c ?? 0);
+
+    // .offset()/.limit(), not .skip()/.take() — skip/take route raw & grouped
+    // selects through TypeORM's DISTINCT-id subquery path, which is wrong here.
+    const items = await qb.offset(skip).limit(take).getRawMany();
+
+    const kpis = def.summary ? await def.summary(ctx) : [];
+
+    return {
+      columns: def.columns,
+      items,
+      meta: buildPaginationMeta(total, pageNum, pageSize),
+      kpis,
+    };
+  }
+
+  /** Same query, no paging — used by the export path. */
+  async runAll(
+    def: ReportDefinition,
+    raw: RawReportQuery,
+    directions: string[] | null,
+    limit: number,
+  ): Promise<{ columns: typeof def.columns; items: Record<string, unknown>[]; kpis: ReportRunResult['kpis'] }> {
+    const params = coerceParams(def, raw);
+    const ctx = { ds: this.ds, params, directions };
+    const qb = def.query(ctx);
+    const sort = resolveSort(def, undefined, undefined);
+    if (sort) qb.orderBy(sort.expr, sort.dir);
+    const items = await qb.limit(limit).getRawMany();
+    if (items.length >= limit) {
+      throw new BadRequestException(
+        `Export exceeds the ${limit}-row cap for this format. Narrow the filters.`,
+      );
+    }
+    const kpis = def.summary ? await def.summary(ctx) : [];
+    return { columns: def.columns, items, kpis };
+  }
+}
+
+// Re-exported so definitions can scope ACL columns without importing the
+// trade-scope module directly.
+export { applyBookingRefDirectionScope };
diff --git a/apps/edr-freight-api/src/modules/reports/report.registry.spec.ts b/apps/edr-freight-api/src/modules/reports/report.registry.spec.ts
new file mode 100644
index 000000000..84bbfb27a
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/report.registry.spec.ts
@@ -0,0 +1,41 @@
+import { REPORT_KEYS } from '../../seed/freight-permissions.registry';
+import { REPORTS, getReport } from './report.registry';
+
+describe('REPORTS', () => {
+  it('has exactly one definition per seeded REPORT_KEYS entry', () => {
+    const defKeys = REPORTS.map((r) => r.key).sort();
+    expect(defKeys).toEqual([...REPORT_KEYS].sort());
+  });
+
+  it('has no duplicate keys', () => {
+    const keys = REPORTS.map((r) => r.key);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  it('resolves every key via getReport', () => {
+    for (const key of REPORT_KEYS) {
+      expect(getReport(key)?.key).toBe(key);
+    }
+  });
+
+  it('every sortable column and defaultSort point at a real column key', () => {
+    for (const def of REPORTS) {
+      const columnKeys = new Set(def.columns.map((c) => c.key));
+      if (def.defaultSort) {
+        expect(columnKeys.has(def.defaultSort.key)).toBe(true);
+      }
+      // Every column marked sortable must have a resolvable key (itself, since
+      // the runner falls back to `key` when `sortExpr` is absent).
+      for (const col of def.columns.filter((c) => c.sortable)) {
+        expect(col.key.length).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  it('idKey, when declared, is not also listed as a user-facing filter', () => {
+    for (const def of REPORTS) {
+      if (!def.idKey) continue;
+      expect(def.filters.some((f) => f.key === def.idKey!.key)).toBe(false);
+    }
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/reports/report.registry.ts b/apps/edr-freight-api/src/modules/reports/report.registry.ts
new file mode 100644
index 000000000..26474d025
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/report.registry.ts
@@ -0,0 +1,24 @@
+import { ReportKey } from '../../seed/freight-permissions.registry';
+import { bookingsListReport } from './definitions/bookings-list.report';
+import { revenueByCustomerReport } from './definitions/revenue-by-customer.report';
+import { agingReceivablesReport } from './definitions/aging-receivables.report';
+import { contractUtilizationReport } from './definitions/contract-utilization.report';
+import { ReportDefinition } from './report.types';
+
+/**
+ * Every report the platform knows about. Adding one = a new file under
+ * definitions/ + a key in REPORT_KEYS (freight-permissions.registry.ts) +
+ * an entry here. Nothing else — no frontend edit, no route, no sidebar edit.
+ */
+export const REPORTS: ReportDefinition[] = [
+  bookingsListReport,
+  revenueByCustomerReport,
+  agingReceivablesReport,
+  contractUtilizationReport,
+];
+
+const BY_KEY = new Map<ReportKey, ReportDefinition>(REPORTS.map((r) => [r.key, r]));
+
+export function getReport(key: string): ReportDefinition | undefined {
+  return BY_KEY.get(key as ReportKey);
+}
diff --git a/apps/edr-freight-api/src/modules/reports/report.types.ts b/apps/edr-freight-api/src/modules/reports/report.types.ts
new file mode 100644
index 000000000..85b73040c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/report.types.ts
@@ -0,0 +1,95 @@
+import { DataSource, ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { ReportKey } from '../../seed/freight-permissions.registry';
+
+export type { ReportKey };
+
+export type ReportColumnType =
+  | 'string'
+  | 'number'
+  | 'money'
+  | 'tons'
+  | 'percent'
+  | 'date';
+
+export interface ReportColumn {
+  key: string;
+  label: string;
+  type: ReportColumnType;
+  sortable?: boolean;
+  /** SQL to ORDER BY when this column is sorted, if different from `key`. */
+  sortExpr?: string;
+}
+
+export type ReportFilterType = 'daterange' | 'date' | 'select' | 'multiselect' | 'text';
+
+export interface ReportFilterOption {
+  value: string;
+  label: string;
+}
+
+export interface ReportFilterDef {
+  key: string;
+  label: string;
+  type: ReportFilterType;
+  /** Static option list for select/multiselect. */
+  options?: ReportFilterOption[];
+}
+
+export interface ReportKpi {
+  label: string;
+  value: number;
+  unit?: string;
+}
+
+/**
+ * Optional entity scope a report can be embedded against — e.g. a
+ * contract-utilization report shown on a single contract's detail page.
+ * Purely descriptive; `query()` reads the resolved value off `ctx.params`
+ * like any other filter.
+ */
+export interface ReportIdKey {
+  key: string;
+  label: string;
+}
+
+export interface ReportContext {
+  ds: DataSource;
+  /** Filter values, already coerced against `def.filters` (CSV → array, etc). */
+  params: Record<string, unknown>;
+  /** Trade-scope-resolved directions. null = unrestricted, [] = show nothing. */
+  directions: string[] | null;
+}
+
+export interface ReportDefinition {
+  key: ReportKey;
+  title: string;
+  description: string;
+  group: 'Commercial' | 'Operations' | 'Finance';
+  idKey?: ReportIdKey;
+  filters: ReportFilterDef[];
+  columns: ReportColumn[];
+  defaultSort?: { key: string; dir: 'ASC' | 'DESC' };
+  query(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral>;
+  /** KPIs over the same filtered set; shown above the table and in exports. */
+  summary?(ctx: ReportContext): Promise<ReportKpi[]>;
+}
+
+/** Catalog shape served by GET /reports — metadata only, no rows. */
+export type ReportCatalogEntry = Omit<ReportDefinition, 'query' | 'summary'> & {
+  hasSummary: boolean;
+};
+
+export interface ReportRunResult {
+  columns: ReportColumn[];
+  items: Record<string, unknown>[];
+  meta: {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+  };
+  kpis: ReportKpi[];
+}
diff --git a/apps/edr-freight-api/src/modules/reports/reports.controller.ts b/apps/edr-freight-api/src/modules/reports/reports.controller.ts
index dc64773d8..49d0307eb 100644
--- a/apps/edr-freight-api/src/modules/reports/reports.controller.ts
+++ b/apps/edr-freight-api/src/modules/reports/reports.controller.ts
@@ -1,34 +1,90 @@
-import { Controller, Get, Param, Query } from '@nestjs/common';
-import { ApiBearerAuth, ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { Controller, Get, NotFoundException, Param, Query, Res } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
 import { CurrentUser } from '@edr/api-common';
+import type { Response } from 'express';
 import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
 
 import { BookingStaff } from '../../common/booking-guards';
-import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
+import { assertFreightPermission, hasFreightPermission } from '../../common/freight-permission.util';
+import { FREIGHT_PERMS, reportPermissionKey } from '../../seed/freight-permissions.registry';
 import { UserTradeAccessService } from '../user-trade-access/user-trade-access.service';
-import { ReportQueryDto } from './dto/report-query.dto';
-import { ReportResultDto } from './dto/report-result.dto';
-import { ReportsService } from './reports.service';
+import { PDF_ROW_CAP, ReportExportService, XLSX_ROW_CAP } from './report-export.service';
+import { RawReportQuery, ReportRunnerService } from './report-runner.service';
+import { REPORTS, getReport } from './report.registry';
+import { ReportCatalogEntry, ReportDefinition } from './report.types';
+
+const toCatalogEntry = (def: ReportDefinition): ReportCatalogEntry => {
+  const { query: _query, summary, ...meta } = def;
+  return { ...meta, hasSummary: Boolean(summary) };
+};
 
 @ApiTags('Reports')
 @ApiBearerAuth()
 @Controller('reports')
+@BookingStaff(FREIGHT_PERMS.reports.view)
 export class ReportsController {
   constructor(
-    private readonly reportsService: ReportsService,
+    private readonly runner: ReportRunnerService,
+    private readonly exportService: ReportExportService,
     private readonly userTradeAccessService: UserTradeAccessService,
   ) {}
 
+  @Get()
+  @ApiOperation({ summary: 'List reports the caller has permission to run' })
+  async catalog(@CurrentUser() user: TCurrentUser): Promise<ReportCatalogEntry[]> {
+    return REPORTS.filter((def) => hasFreightPermission(user, reportPermissionKey(def.key))).map(
+      toCatalogEntry,
+    );
+  }
+
   @Get(':key')
-  @BookingStaff(FREIGHT_PERMS.reports.view)
-  @ApiOperation({ summary: 'Run a canned report by key with optional filters' })
-  @ApiOkResponse({ type: ReportResultDto })
+  @ApiOperation({ summary: 'Run a report by key, paginated/sorted/filtered' })
   async run(
     @Param('key') key: string,
-    @Query() query: ReportQueryDto,
+    @Query() query: RawReportQuery,
     @CurrentUser() user: TCurrentUser,
-  ): Promise<ReportResultDto> {
-    const allowed = await this.userTradeAccessService.resolveAllowedDirections(user);
-    return this.reportsService.run(key, query, allowed);
+  ) {
+    const def = this.resolve(key, user);
+    const directions = await this.userTradeAccessService.resolveAllowedDirections(user);
+    return this.runner.run(def, query, directions);
+  }
+
+  @Get(':key/export')
+  @ApiOperation({ summary: 'Export a report to xlsx or pdf' })
+  async export(
+    @Param('key') key: string,
+    @Query() query: RawReportQuery & { format?: string },
+    @CurrentUser() user: TCurrentUser,
+    @Res() res: Response,
+  ): Promise<void> {
+    const def = this.resolve(key, user);
+    const directions = await this.userTradeAccessService.resolveAllowedDirections(user);
+    const format = query.format === 'pdf' ? 'pdf' : 'xlsx';
+    const cap = format === 'pdf' ? PDF_ROW_CAP : XLSX_ROW_CAP;
+
+    const { items, kpis } = await this.runner.runAll(def, query, directions, cap);
+    const buffer =
+      format === 'pdf'
+        ? await this.exportService.toPdf(def, items, kpis)
+        : await this.exportService.toXlsx(def, items, kpis);
+
+    const filename = `${def.key}.${format === 'pdf' ? 'pdf' : 'xlsx'}`;
+    res.setHeader('Content-Disposition', `attachment; filename="${filename}"`);
+    res.setHeader(
+      'Content-Type',
+      format === 'pdf'
+        ? 'application/pdf'
+        : 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    );
+    res.send(buffer);
+  }
+
+  private resolve(key: string, user: TCurrentUser): ReportDefinition {
+    const def = getReport(key);
+    if (!def) throw new NotFoundException(`Unknown report: ${key}`);
+    // Exact-match on purpose — unlike FreightPermissionGuard's :view/:read
+    // fallback, a report's own key is the only thing that opens it.
+    assertFreightPermission(user, reportPermissionKey(def.key));
+    return def;
   }
 }
diff --git a/apps/edr-freight-api/src/modules/reports/reports.module.ts b/apps/edr-freight-api/src/modules/reports/reports.module.ts
index a7fe792a5..2f98e9e04 100644
--- a/apps/edr-freight-api/src/modules/reports/reports.module.ts
+++ b/apps/edr-freight-api/src/modules/reports/reports.module.ts
@@ -1,13 +1,14 @@
 import { Module } from '@nestjs/common';
 
+import { DocumentsModule } from '../billing/documents/documents.module';
 import { UserTradeAccessModule } from '../user-trade-access/user-trade-access.module';
+import { ReportExportService } from './report-export.service';
+import { ReportRunnerService } from './report-runner.service';
 import { ReportsController } from './reports.controller';
-import { ReportsRepository } from './reports.repository';
-import { ReportsService } from './reports.service';
 
 @Module({
-  imports: [UserTradeAccessModule],
+  imports: [UserTradeAccessModule, DocumentsModule],
   controllers: [ReportsController],
-  providers: [ReportsService, ReportsRepository],
+  providers: [ReportRunnerService, ReportExportService],
 })
 export class ReportsModule {}
diff --git a/apps/edr-freight-api/src/modules/reports/reports.repository.ts b/apps/edr-freight-api/src/modules/reports/reports.repository.ts
deleted file mode 100644
index 65f154b22..000000000
--- a/apps/edr-freight-api/src/modules/reports/reports.repository.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { Injectable } from '@nestjs/common';
-import { InjectDataSource } from '@nestjs/typeorm';
-import { DataSource } from 'typeorm';
-
-import { REPORT_QUERIES, ReportFilters, ReportResult } from './report-queries';
-
-@Injectable()
-export class ReportsRepository {
-  constructor(@InjectDataSource() private readonly dataSource: DataSource) {}
-
-  run(key: keyof typeof REPORT_QUERIES, filters: ReportFilters): Promise<ReportResult> {
-    return REPORT_QUERIES[key](this.dataSource, filters);
-  }
-}
diff --git a/apps/edr-freight-api/src/modules/reports/reports.service.ts b/apps/edr-freight-api/src/modules/reports/reports.service.ts
deleted file mode 100644
index 04e6e9a60..000000000
--- a/apps/edr-freight-api/src/modules/reports/reports.service.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import { Injectable, NotFoundException } from '@nestjs/common';
-
-import { scopedDirections } from '../user-trade-access/trade-scope.util';
-import { ReportQueryDto } from './dto/report-query.dto';
-import { REPORT_QUERIES, ReportFilters, ReportResult } from './report-queries';
-import { ReportsRepository } from './reports.repository';
-import type { Freight } from '@edr/types';
-
-const DAY_MS = 24 * 60 * 60 * 1000;
-
-const list = (csv?: string): string[] | null => {
-  const items = csv?.split(',').map((s) => s.trim()).filter(Boolean) ?? [];
-  return items.length ? items : null;
-};
-
-@Injectable()
-export class ReportsService {
-  constructor(private readonly repository: ReportsRepository) {}
-
-  run(
-    key: string,
-    dto: ReportQueryDto,
-    allowedDirections: Freight.ScheduleTradeDirection[] | null,
-  ): Promise<ReportResult> {
-    if (!(key in REPORT_QUERIES)) {
-      throw new NotFoundException(`Unknown report: ${key}`);
-    }
-    // No default range: absent dates mean all time, so exports cover everything.
-    const to = dto.dateTo ? new Date(dto.dateTo) : null;
-    const from = dto.dateFrom ? new Date(dto.dateFrom) : null;
-    const filters: ReportFilters = {
-      dateFrom: from ? from.toISOString() : null,
-      // dateTo is inclusive in the API; queries treat the bound as exclusive.
-      dateTo: to ? new Date(to.getTime() + DAY_MS).toISOString() : null,
-      granularity: dto.granularity ?? 'day',
-      companyIds: list(dto.companyIds),
-      routeIds: list(dto.routeIds),
-      yardIds: list(dto.yardIds),
-      cargoTypeIds: list(dto.cargoTypeIds),
-      statuses: list(dto.statuses),
-      directions: scopedDirections(allowedDirections, dto.direction),
-      freightType: dto.freightType ?? null,
-    };
-    return this.repository.run(key, filters);
-  }
-}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index b0a9a550e..8e8768819 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -126,6 +126,9 @@ importers:
       dotenv-cli:
         specifier: ^11.0.0
         version: 11.0.0
+      exceljs:
+        specifier: ^4.4.0
+        version: 4.4.0
       handlebars:
         specifier: ^4.7.9
         version: 4.7.9
@@ -601,7 +604,7 @@ importers:
         version: 5.101.0(react@19.2.6)
       '@tria-plc/iamui':
         specifier: file:../../../local-packages/tria-plc-iamui-0.1.1.tgz
-        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)
+        version: file:local-packages/tria-plc-iamui-0.1.1.tgz(0ce39b7e349029277dcd938d06eeb0f7)
       '@vis.gl/react-google-maps':
         specifier: ^1.8.3
         version: 1.8.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -13056,11 +13059,11 @@ snapshots:
       '@babel/helpers': 7.29.7
       '@babel/parser': 7.29.7
       '@babel/template': 7.29.7
-      '@babel/traverse': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
       '@babel/types': 7.29.7
       '@jridgewell/remapping': 2.3.5
       convert-source-map: 2.0.0
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       gensync: 1.0.0-beta.2
       json5: 2.2.3
       semver: 6.3.1
@@ -13095,7 +13098,7 @@ snapshots:
       '@babel/helper-optimise-call-expression': 7.29.7
       '@babel/helper-replace-supers': 7.29.7(@babel/core@7.29.7)
       '@babel/helper-skip-transparent-expression-wrappers': 7.29.7
-      '@babel/traverse': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
       semver: 6.3.1
     transitivePeerDependencies:
       - supports-color
@@ -13104,14 +13107,7 @@ snapshots:
 
   '@babel/helper-member-expression-to-functions@7.29.7':
     dependencies:
-      '@babel/traverse': 7.29.7
-      '@babel/types': 7.29.7
-    transitivePeerDependencies:
-      - supports-color
-
-  '@babel/helper-module-imports@7.29.7':
-    dependencies:
-      '@babel/traverse': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
       '@babel/types': 7.29.7
     transitivePeerDependencies:
       - supports-color
@@ -13126,9 +13122,9 @@ snapshots:
   '@babel/helper-module-transforms@7.29.7(@babel/core@7.29.7)':
     dependencies:
       '@babel/core': 7.29.7
-      '@babel/helper-module-imports': 7.29.7
+      '@babel/helper-module-imports': 7.29.7(supports-color@5.5.0)
       '@babel/helper-validator-identifier': 7.29.7
-      '@babel/traverse': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
@@ -13143,13 +13139,13 @@ snapshots:
       '@babel/core': 7.29.7
       '@babel/helper-member-expression-to-functions': 7.29.7
       '@babel/helper-optimise-call-expression': 7.29.7
-      '@babel/traverse': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
   '@babel/helper-skip-transparent-expression-wrappers@7.29.7':
     dependencies:
-      '@babel/traverse': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@5.5.0)
       '@babel/types': 7.29.7
     transitivePeerDependencies:
       - supports-color
@@ -13302,18 +13298,6 @@ snapshots:
       '@babel/parser': 7.29.7
       '@babel/types': 7.29.7
 
-  '@babel/traverse@7.29.7':
-    dependencies:
-      '@babel/code-frame': 7.29.7
-      '@babel/generator': 7.29.7
-      '@babel/helper-globals': 7.29.7
-      '@babel/parser': 7.29.7
-      '@babel/template': 7.29.7
-      '@babel/types': 7.29.7
-      debug: 4.4.3(supports-color@8.1.1)
-    transitivePeerDependencies:
-      - supports-color
-
   '@babel/traverse@7.29.7(supports-color@5.5.0)':
     dependencies:
       '@babel/code-frame': 7.29.7
@@ -13798,7 +13782,7 @@ snapshots:
 
   '@emotion/babel-plugin@11.13.5':
     dependencies:
-      '@babel/helper-module-imports': 7.29.7
+      '@babel/helper-module-imports': 7.29.7(supports-color@5.5.0)
       '@babel/runtime': 7.29.7
       '@emotion/hash': 0.9.2
       '@emotion/memoize': 0.9.0
@@ -13964,7 +13948,7 @@ snapshots:
   '@eslint/eslintrc@2.1.4':
     dependencies:
       ajv: 6.15.0
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       espree: 9.6.1
       globals: 13.24.0
       ignore: 5.3.2
@@ -14124,7 +14108,7 @@ snapshots:
   '@humanwhocodes/config-array@0.13.0':
     dependencies:
       '@humanwhocodes/object-schema': 2.0.3
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       minimatch: 3.1.5
     transitivePeerDependencies:
       - supports-color
@@ -15723,7 +15707,7 @@ snapshots:
 
   '@puppeteer/browsers@2.13.2':
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       extract-zip: 2.0.1
       progress: 2.0.3
       proxy-agent: 6.5.0
@@ -17797,7 +17781,7 @@ snapshots:
 
   '@tokenizer/inflate@0.4.1':
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       token-types: 6.1.2
     transitivePeerDependencies:
       - supports-color
@@ -18084,130 +18068,6 @@ snapshots:
       - utf-8-validate
       - vite
 
-  '@tria-plc/iamui@file:local-packages/tria-plc-iamui-0.1.1.tgz(a5d0bdee55164ae56064fb273b530e00)':
-    dependencies:
-      '@emotion/react': 11.14.0(@types/react@18.3.31)(react@19.2.6)
-      '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@18.3.31)(react@19.2.6))(@types/react@18.3.31)(react@19.2.6)
-      '@hookform/resolvers': 5.4.0(react-hook-form@7.77.0(react@19.2.6))
-      '@lottiefiles/react-lottie-player': 3.6.0(react@19.2.6)
-      '@mantine/charts': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(recharts@3.8.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)(redux@5.0.1))
-      '@mantine/core': 7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@mantine/dates': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@mantine/hooks': 7.17.8(react@19.2.6)
-      '@mantine/notifications': 7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-accordion': 1.2.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-alert-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-avatar': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-checkbox': 1.3.4(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-collapsible': 1.1.13(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-context-menu': 2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-dialog': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-dropdown-menu': 2.1.17(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-hover-card': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-label': 2.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-navigation-menu': 1.2.15(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-popover': 1.1.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-progress': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-radio-group': 1.4.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-scroll-area': 1.2.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-select': 2.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-separator': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-slot': 1.2.5(@types/react@18.3.31)(react@19.2.6)
-      '@radix-ui/react-switch': 1.3.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-tabs': 1.1.14(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-toast': 1.2.16(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@radix-ui/react-tooltip': 1.2.9(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@react-pdf-viewer/core': 3.12.0(pdfjs-dist@5.4.296)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@react-pdf-viewer/default-layout': 3.12.0(pdfjs-dist@5.4.296)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@react-pdf/renderer': 4.5.1(react@19.2.6)
-      '@reduxjs/toolkit': 2.12.0(react-redux@9.3.0(@types/react@18.3.31)(react@19.2.6)(redux@5.0.1))(react@19.2.6)
-      '@tabler/icons-react': 3.44.0(react@19.2.6)
-      '@tailwindcss/vite': 4.3.0(vite@5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0))
-      '@tanstack/react-query': 5.101.0(react@19.2.6)
-      '@tanstack/react-query-devtools': 5.101.0(@tanstack/react-query@5.101.0(react@19.2.6))(react@19.2.6)
-      '@tanstack/react-table': 8.21.3(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@tinymce/tinymce-react': 6.3.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(tinymce@7.9.3)
-      '@types/dompurify': 3.2.0
-      '@types/node': 24.13.1
-      '@types/tinymce': 4.6.9
-      axios: 1.17.0
-      class-variance-authority: 0.7.1
-      clsx: 2.1.1
-      cmdk: 1.1.1(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      date-fns: 3.6.0
-      dayjs: 1.11.21
-      dompurify: 3.4.8
-      ethiopian-calendar-date-converter: 2.1.6
-      ethiopian-calendar-new: 1.1.0
-      file-type: 18.7.0
-      framer-motion: 12.40.0(@emotion/is-prop-valid@1.4.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      html2canvas: 1.4.1
-      i18next: 25.10.10(typescript@5.9.3)
-      i18next-browser-languagedetector: 8.2.1
-      jquery: 3.7.1
-      js-cookie: 3.0.8
-      jspdf: 3.0.4
-      lodash: 4.18.1
-      lucide-react: 0.513.0(react@19.2.6)
-      mantine-react-table: 2.0.0-beta.9(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/dates@7.17.8(@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.6))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6))(@mantine/hooks@7.17.8(react@19.2.6))(@tabler/icons-react@3.44.0(react@19.2.6))(clsx@2.1.1)(dayjs@1.11.21)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      mui-ethiopian-datepicker: 0.3.2(4b3af212eafdf0059f009b005d7e343d)
-      next-themes: 0.4.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      path: 0.12.7
-      pdf-lib: 1.17.1
-      qs: 6.15.2
-      react: 19.2.6
-      react-cookie: 8.1.2(@types/react@18.3.31)(react@19.2.6)
-      react-css-nocode-editor: 1.0.13(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)
-      react-day-picker: 8.10.2(date-fns@3.6.0)(react@19.2.6)
-      react-dom: 19.2.6(react@19.2.6)
-      react-dropzone: 14.4.1(react@19.2.6)
-      react-hook-form: 7.77.0(react@19.2.6)
-      react-i18next: 15.7.4(i18next@25.10.10(typescript@5.9.3))(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(typescript@5.9.3)
-      react-icons: 5.6.0(react@19.2.6)
-      react-image-crop: 11.0.10(react@19.2.6)
-      react-intersection-observer: 9.16.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      react-pdf: 10.4.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      react-pdf-html: 2.1.5(@react-pdf/renderer@4.5.1(react@19.2.6))(react@19.2.6)
-      react-redux: 9.3.0(@types/react@18.3.31)(react@19.2.6)(redux@5.0.1)
-      react-resizable-panels: 3.0.6(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      react-router-dom: 7.17.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      react-signature-canvas: 1.1.0-alpha.2(@types/prop-types@15.7.15)(@types/react@18.3.31)(prop-types@15.8.1)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      recharts: 3.8.1(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)(redux@5.0.1)
-      rollup-plugin-visualizer: 7.0.1(rollup@4.61.1)
-      socket.io-client: 4.8.3
-      sonner: 2.0.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      tailwind-merge: 3.6.0
-      tailwind-scrollbar-hide: 4.0.0(tailwindcss@4.3.0)
-      tailwindcss: 4.3.0
-      tailwindcss-animate: 1.0.7(tailwindcss@4.3.0)
-      tinymce: 7.9.3
-      url: 0.11.4
-      vaul: 1.1.2(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      xlsx: 0.18.5
-      zod: 3.25.76
-    transitivePeerDependencies:
-      - '@babel/core'
-      - '@emotion/is-prop-valid'
-      - '@mui/icons-material'
-      - '@mui/material'
-      - '@mui/x-date-pickers'
-      - '@types/prop-types'
-      - '@types/react'
-      - '@types/react-dom'
-      - bufferutil
-      - debug
-      - pdfjs-dist
-      - prop-types
-      - react-is
-      - react-native
-      - redux
-      - rolldown
-      - rollup
-      - supports-color
-      - typescript
-      - utf-8-validate
-      - vite
-
   '@ts-morph/common@0.27.0':
     dependencies:
       fast-glob: 3.3.3
@@ -18605,7 +18465,7 @@ snapshots:
       '@typescript-eslint/types': 8.60.1
       '@typescript-eslint/typescript-estree': 8.60.1(typescript@5.9.3)
       '@typescript-eslint/visitor-keys': 8.60.1
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       eslint: 8.57.1
       typescript: 5.9.3
     transitivePeerDependencies:
@@ -18615,7 +18475,7 @@ snapshots:
     dependencies:
       '@typescript-eslint/tsconfig-utils': 8.60.1(typescript@5.9.3)
       '@typescript-eslint/types': 8.60.1
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       typescript: 5.9.3
     transitivePeerDependencies:
       - supports-color
@@ -18634,7 +18494,7 @@ snapshots:
       '@typescript-eslint/types': 8.60.1
       '@typescript-eslint/typescript-estree': 8.60.1(typescript@5.9.3)
       '@typescript-eslint/utils': 8.60.1(eslint@8.57.1)(typescript@5.9.3)
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       eslint: 8.57.1
       ts-api-utils: 2.5.0(typescript@5.9.3)
       typescript: 5.9.3
@@ -18649,7 +18509,7 @@ snapshots:
       '@typescript-eslint/tsconfig-utils': 8.60.1(typescript@5.9.3)
       '@typescript-eslint/types': 8.60.1
       '@typescript-eslint/visitor-keys': 8.60.1
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       minimatch: 10.2.5
       semver: 7.8.2
       tinyglobby: 0.2.17
@@ -18938,7 +18798,7 @@ snapshots:
 
   agent-base@6.0.2:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
@@ -19447,16 +19307,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  babel-plugin-styled-components@2.3.0(styled-components@5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6))(supports-color@5.5.0):
-    dependencies:
-      '@babel/helper-annotate-as-pure': 7.29.7
-      '@babel/helper-module-imports': 7.29.7(supports-color@5.5.0)
-      '@babel/plugin-syntax-jsx': 7.29.7(@babel/core@7.29.7)
-      picomatch: 4.0.4
-      styled-components: 5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)
-    transitivePeerDependencies:
-      - supports-color
-
   babel-polyfill@6.26.0:
     dependencies:
       babel-runtime: 6.26.0
@@ -19612,7 +19462,7 @@ snapshots:
     dependencies:
       bytes: 3.1.2
       content-type: 1.0.5
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       http-errors: 2.0.1
       iconv-lite: 0.7.2
       on-finished: 2.4.1
@@ -20661,7 +20511,7 @@ snapshots:
   engine.io-client@6.6.5:
     dependencies:
       '@socket.io/component-emitter': 3.1.2
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       engine.io-parser: 5.2.3
       ws: 8.20.1
       xmlhttprequest-ssl: 2.1.2
@@ -20681,7 +20531,7 @@ snapshots:
       base64id: 2.0.0
       cookie: 0.7.2
       cors: 2.8.6
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       engine.io-parser: 5.2.3
       ws: 8.21.0
     transitivePeerDependencies:
@@ -20912,7 +20762,7 @@ snapshots:
   eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.60.1(eslint@8.57.1)(typescript@5.9.3))(eslint@8.57.1))(eslint@8.57.1):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       eslint: 8.57.1
       get-tsconfig: 4.14.0
       is-bun-module: 2.0.0
@@ -21040,7 +20890,7 @@ snapshots:
       ajv: 6.15.0
       chalk: 4.1.2
       cross-spawn: 7.0.6
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       doctrine: 3.0.0
       escape-string-regexp: 4.0.0
       eslint-scope: 7.2.2
@@ -21277,7 +21127,7 @@ snapshots:
       content-type: 1.0.5
       cookie: 0.7.2
       cookie-signature: 1.2.2
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       depd: 2.0.0
       encodeurl: 2.0.0
       escape-html: 1.0.3
@@ -21330,7 +21180,7 @@ snapshots:
 
   extract-zip@2.0.1:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       get-stream: 5.2.0
       yauzl: 2.10.0
     optionalDependencies:
@@ -21485,7 +21335,7 @@ snapshots:
 
   finalhandler@2.1.1:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       encodeurl: 2.0.0
       escape-html: 1.0.3
       on-finished: 2.4.1
@@ -21733,7 +21583,7 @@ snapshots:
     dependencies:
       basic-ftp: 5.3.1
       data-uri-to-buffer: 6.0.2
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
@@ -22042,7 +21892,7 @@ snapshots:
   http-proxy-agent@7.0.2:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
@@ -22055,14 +21905,14 @@ snapshots:
   https-proxy-agent@5.0.1:
     dependencies:
       agent-base: 6.0.2
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
   https-proxy-agent@7.0.6:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
@@ -22502,7 +22352,7 @@ snapshots:
 
   istanbul-lib-source-maps@4.0.1:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       istanbul-lib-coverage: 3.2.2
       source-map: 0.6.1
     transitivePeerDependencies:
@@ -23162,7 +23012,7 @@ snapshots:
     dependencies:
       chalk: 5.6.2
       commander: 13.1.0
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       execa: 8.0.1
       lilconfig: 3.1.3
       listr2: 8.3.3
@@ -23849,7 +23699,7 @@ snapshots:
   micromark@4.0.2:
     dependencies:
       '@types/debug': 4.1.13
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       decode-named-character-reference: 1.3.0
       devlop: 1.1.0
       micromark-core-commonmark: 2.0.3
@@ -24375,7 +24225,7 @@ snapshots:
     dependencies:
       '@tootallnate/quickjs-emscripten': 0.23.0
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       get-uri: 6.0.5
       http-proxy-agent: 7.0.2
       https-proxy-agent: 7.0.6
@@ -24725,7 +24575,7 @@ snapshots:
   proxy-agent@6.5.0:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       http-proxy-agent: 7.0.2
       https-proxy-agent: 7.0.6
       lru-cache: 7.18.3
@@ -24754,7 +24604,7 @@ snapshots:
     dependencies:
       '@puppeteer/browsers': 2.13.2
       chromium-bidi: 14.0.0(devtools-protocol@0.0.1608973)
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       devtools-protocol: 0.0.1608973
       typed-query-selector: 2.12.2
       webdriver-bidi-protocol: 0.4.1
@@ -25007,15 +24857,6 @@ snapshots:
       - '@babel/core'
       - react-is
 
-  react-css-nocode-editor@1.0.13(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6):
-    dependencies:
-      react: 19.2.6
-      react-dom: 19.2.6(react@19.2.6)
-      styled-components: 5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6)
-    transitivePeerDependencies:
-      - '@babel/core'
-      - react-is
-
   react-day-picker@8.10.2(date-fns@3.6.0)(react@19.2.6):
     dependencies:
       date-fns: 3.6.0
@@ -25626,7 +25467,7 @@ snapshots:
 
   router@2.2.0:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       depd: 2.0.0
       is-promise: 4.0.0
       parseurl: 1.3.3
@@ -25748,7 +25589,7 @@ snapshots:
 
   send@1.2.1:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       encodeurl: 2.0.0
       escape-html: 1.0.3
       etag: 1.8.1
@@ -25964,7 +25805,7 @@ snapshots:
 
   socket.io-adapter@2.5.8:
     dependencies:
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       ws: 8.21.0
     transitivePeerDependencies:
       - bufferutil
@@ -25974,7 +25815,7 @@ snapshots:
   socket.io-client@4.8.3:
     dependencies:
       '@socket.io/component-emitter': 3.1.2
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       engine.io-client: 6.6.5
       socket.io-parser: 4.2.6
     transitivePeerDependencies:
@@ -25985,7 +25826,7 @@ snapshots:
   socket.io-parser@4.2.6:
     dependencies:
       '@socket.io/component-emitter': 3.1.2
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
     transitivePeerDependencies:
       - supports-color
 
@@ -25994,7 +25835,7 @@ snapshots:
       accepts: 1.3.8
       base64id: 2.0.0
       cors: 2.8.6
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       engine.io: 6.6.9
       socket.io-adapter: 2.5.8
       socket.io-parser: 4.2.6
@@ -26006,7 +25847,7 @@ snapshots:
   socks-proxy-agent@8.0.5:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       socks: 2.8.9
     transitivePeerDependencies:
       - supports-color
@@ -26301,24 +26142,6 @@ snapshots:
     transitivePeerDependencies:
       - '@babel/core'
 
-  styled-components@5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6):
-    dependencies:
-      '@babel/helper-module-imports': 7.29.7(supports-color@5.5.0)
-      '@babel/traverse': 7.29.7(supports-color@5.5.0)
-      '@emotion/is-prop-valid': 1.4.0
-      '@emotion/stylis': 0.8.5
-      '@emotion/unitless': 0.7.5
-      babel-plugin-styled-components: 2.3.0(styled-components@5.3.11(react-dom@19.2.6(react@19.2.6))(react-is@19.2.7)(react@19.2.6))(supports-color@5.5.0)
-      css-to-react-native: 3.2.0
-      hoist-non-react-statics: 3.3.2
-      react: 19.2.6
-      react-dom: 19.2.6(react@19.2.6)
-      react-is: 19.2.7
-      shallowequal: 1.1.0
-      supports-color: 5.5.0
-    transitivePeerDependencies:
-      - '@babel/core'
-
   styled-jsx@5.1.1(babel-plugin-macros@3.1.0)(react@18.3.1):
     dependencies:
       client-only: 0.0.1
@@ -26344,7 +26167,7 @@ snapshots:
     dependencies:
       component-emitter: 1.3.1
       cookiejar: 2.1.4
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       fast-safe-stringify: 2.1.1
       form-data: 4.0.5
       formidable: 3.5.4
@@ -26857,7 +26680,7 @@ snapshots:
       app-root-path: 3.1.0
       buffer: 6.0.3
       dayjs: 1.11.21
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       dedent: 1.7.2(babel-plugin-macros@3.1.0)
       dotenv: 16.6.1
       glob: 10.5.0
@@ -26881,7 +26704,7 @@ snapshots:
       app-root-path: 3.1.0
       buffer: 6.0.3
       dayjs: 1.11.21
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       dedent: 1.7.2(babel-plugin-macros@3.1.0)
       dotenv: 16.6.1
       glob: 10.5.0
@@ -27242,7 +27065,7 @@ snapshots:
   vite-node@2.1.9(@types/node@22.20.1)(lightningcss@1.32.0)(terser@5.48.0):
     dependencies:
       cac: 6.7.14
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       es-module-lexer: 1.7.0
       pathe: 1.1.2
       vite: 5.4.21(@types/node@22.20.1)(lightningcss@1.32.0)(terser@5.48.0)
@@ -27260,7 +27083,7 @@ snapshots:
   vite-node@2.1.9(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0):
     dependencies:
       cac: 6.7.14
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       es-module-lexer: 1.7.0
       pathe: 1.1.2
       vite: 5.4.21(@types/node@24.13.1)(lightningcss@1.32.0)(terser@5.48.0)
@@ -27307,7 +27130,7 @@ snapshots:
       '@vitest/spy': 2.1.9
       '@vitest/utils': 2.1.9
       chai: 5.3.3
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       expect-type: 1.3.0
       magic-string: 0.30.21
       pathe: 1.1.2
@@ -27343,7 +27166,7 @@ snapshots:
       '@vitest/spy': 2.1.9
       '@vitest/utils': 2.1.9
       chai: 5.3.3
-      debug: 4.4.3(supports-color@8.1.1)
+      debug: 4.4.3(supports-color@5.5.0)
       expect-type: 1.3.0
       magic-string: 0.30.21
       pathe: 1.1.2

From 081b9945cb3bc8731f46b7413bc9e0272f7a8724 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 07:52:29 +0000
Subject: [PATCH 064/174] feat(freight-backoffice): render reports from the
 server-driven catalog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drop reportConfigs.ts (per-report FE config duplicating the backend) and
the chart-drawing ReportPage. Replace with ReportView: one engine that
renders any report the GET /reports catalog describes — filters, KPI
strip, sortable/paginated DataTable, xlsx/pdf export via blob download.
ReportSection embeds a report inline on any page, scoped by idKey, and
renders nothing if the caller lacks that report's permission.

Sidebar Reports submenu is now built from the live catalog
(sidebar-sections.tsx + App.tsx) instead of a hand-listed key — no FE
edit needed to add or hide a report.
---
 apps/edr-freight-web/backoffice/src/App.tsx   |  16 +-
 .../components/layout/sidebar-sections.tsx    |   8 +-
 .../src/components/reports/ReportFilters.tsx  | 115 +++++
 .../src/components/reports/ReportSection.tsx  |  39 ++
 .../src/components/reports/ReportView.tsx     | 212 +++++++++
 .../src/components/reports/report-format.ts   |  42 ++
 .../backoffice/src/constants/URLS.ts          |   2 +
 .../src/pages/reports/ReportPage.tsx          | 440 +----------------
 .../src/pages/reports/ReportsHubPage.tsx      | 193 ++------
 .../src/pages/reports/reportConfigs.ts        | 445 ------------------
 .../backoffice/src/services/api.ts            |   7 +-
 .../src/services/reports.service.ts           |  29 +-
 .../backoffice/src/types/reports.ts           |  88 +++-
 13 files changed, 586 insertions(+), 1050 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/reports/ReportFilters.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/reports/ReportSection.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/reports/report-format.ts
 delete mode 100644 apps/edr-freight-web/backoffice/src/pages/reports/reportConfigs.ts

diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index 64f91da72..94ad11f1b 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -1,4 +1,5 @@
-import { useEffect } from "react";
+import { useEffect, useMemo } from "react";
+import { useQuery } from "@tanstack/react-query";
 import {
   Navigate,
   Outlet,
@@ -10,6 +11,7 @@ import {
 } from "react-router-dom";
 
 import { FreightDashboardLayout, type SidebarItem } from "@/components/layout";
+import { api } from "@/services/api";
 import { useAuth } from "./auth/useAuth";
 import LoadingScreen from "./components/LoadingScreen";
 import LoginPage from "./pages/auth/LoginPage";
@@ -139,8 +141,18 @@ const DashboardShell = () => {
 
   const demoItems: SidebarItem[] = [];
 
+  const { data: reportCatalog } = useQuery(api.reports.catalog.queryOptions());
+  const reportItems: SidebarItem[] = useMemo(
+    () =>
+      (reportCatalog ?? []).map((report) => ({
+        label: report.title,
+        href: `/dashboard/reports/${report.key}`,
+      })),
+    [reportCatalog],
+  );
+
   const sidebarSections = filterSidebarByPermission(
-    buildSidebarSections(demoItems),
+    buildSidebarSections(demoItems, reportItems),
     user,
   );
   const displayName = user?.name?.en || user?.username || user?.email || "User";
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 95608b6db..4548dc134 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -51,7 +51,10 @@ import { getCategorySidebarChildren } from "@/pages/ruleEngine/config/resources"
  * a user's first reachable route without importing the route tree (App.tsx
  * imports RequirePermission, which imports landing — that would cycle).
  */
-export const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[] => [
+export const buildSidebarSections = (
+  demoItems: SidebarItem[],
+  reportItems: SidebarItem[] = [],
+): SidebarSection[] => [
   {
     title: "Main menu",
     items: [
@@ -66,6 +69,9 @@ export const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[]
         href: "/dashboard/reports",
         icon: <BarChart3 />,
         permission: FREIGHT_PERMS.reports.view,
+        // Populated from the live GET /reports catalog (already permission-
+        // filtered server-side) — no report key is ever hand-listed here.
+        ...(reportItems.length ? { children: reportItems } : {}),
       },
       {
         label: "Customers",
diff --git a/apps/edr-freight-web/backoffice/src/components/reports/ReportFilters.tsx b/apps/edr-freight-web/backoffice/src/components/reports/ReportFilters.tsx
new file mode 100644
index 000000000..9412d4db8
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/reports/ReportFilters.tsx
@@ -0,0 +1,115 @@
+import { Group, MultiSelect, Select, TextInput } from "@mantine/core";
+import { DateInput } from "@mantine/dates";
+import { Search } from "lucide-react";
+
+import type { ReportFilterDef } from "@/types/reports";
+
+export interface ReportFilterValues {
+  [param: string]: string | undefined;
+}
+
+interface ReportFiltersProps {
+  filters: ReportFilterDef[];
+  values: ReportFilterValues;
+  onChange: (values: ReportFilterValues) => void;
+}
+
+const toDate = (value: string | undefined): Date | null => (value ? new Date(value) : null);
+const fromDate = (value: string | null): string | undefined => value ?? undefined;
+
+/** Renders one widget per report-declared filter and reports raw param values back up. */
+export function ReportFilters({ filters, values, onChange }: ReportFiltersProps) {
+  if (!filters.length) return null;
+
+  const set = (patch: ReportFilterValues) => onChange({ ...values, ...patch });
+
+  return (
+    <Group gap="sm" wrap="wrap">
+      {filters.map((filter) => {
+        switch (filter.type) {
+          case "daterange":
+            return (
+              <Group key={filter.key} gap="xs" wrap="nowrap">
+                <DateInput
+                  placeholder={`${filter.label} from`}
+                  value={toDate(values[`${filter.key}From`])}
+                  onChange={(d) => set({ [`${filter.key}From`]: fromDate(d) })}
+                  radius="md"
+                  size="sm"
+                  clearable
+                  w={150}
+                />
+                <DateInput
+                  placeholder={`${filter.label} to`}
+                  value={toDate(values[`${filter.key}To`])}
+                  onChange={(d) => set({ [`${filter.key}To`]: fromDate(d) })}
+                  radius="md"
+                  size="sm"
+                  clearable
+                  w={150}
+                />
+              </Group>
+            );
+          case "date":
+            return (
+              <DateInput
+                key={filter.key}
+                placeholder={filter.label}
+                value={toDate(values[filter.key])}
+                onChange={(d) => set({ [filter.key]: fromDate(d) })}
+                radius="md"
+                size="sm"
+                clearable
+                w={150}
+              />
+            );
+          case "select":
+            return (
+              <Select
+                key={filter.key}
+                placeholder={filter.label}
+                data={filter.options ?? []}
+                value={values[filter.key] ?? null}
+                onChange={(v) => set({ [filter.key]: v ?? undefined })}
+                radius="md"
+                size="sm"
+                clearable
+                w={170}
+              />
+            );
+          case "multiselect":
+            return (
+              <MultiSelect
+                key={filter.key}
+                placeholder={filter.label}
+                data={filter.options ?? []}
+                value={values[filter.key]?.split(",").filter(Boolean) ?? []}
+                onChange={(v) => set({ [filter.key]: v.length ? v.join(",") : undefined })}
+                radius="md"
+                size="sm"
+                clearable
+                w={200}
+              />
+            );
+          case "text":
+            return (
+              <TextInput
+                key={filter.key}
+                placeholder={filter.label}
+                leftSection={<Search size={16} />}
+                value={values[filter.key] ?? ""}
+                onChange={(e) => set({ [filter.key]: e.target.value || undefined })}
+                radius="md"
+                size="sm"
+                w={220}
+              />
+            );
+          default:
+            return null;
+        }
+      })}
+    </Group>
+  );
+}
+
+export default ReportFilters;
diff --git a/apps/edr-freight-web/backoffice/src/components/reports/ReportSection.tsx b/apps/edr-freight-web/backoffice/src/components/reports/ReportSection.tsx
new file mode 100644
index 000000000..99c6d30c3
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/reports/ReportSection.tsx
@@ -0,0 +1,39 @@
+import { Stack, Text, Title } from "@mantine/core";
+import { useQuery } from "@tanstack/react-query";
+
+import { api } from "@/services/api";
+
+import { ReportView } from "./ReportView";
+
+interface ReportSectionProps {
+  reportKey: string;
+  /** Scopes the report to one entity, e.g. the contract this page is showing. */
+  idKeyValue?: string;
+}
+
+/**
+ * Drops a report inline on any page — a contract detail page embedding
+ * `contract-utilization`, for instance. Renders nothing while the catalog is
+ * loading or if the caller lacks the report's permission, so pages can embed
+ * it unconditionally without their own permission check.
+ */
+export function ReportSection({ reportKey, idKeyValue }: ReportSectionProps) {
+  const { data: catalog } = useQuery(api.reports.catalog.queryOptions());
+  const def = catalog?.find((r) => r.key === reportKey);
+
+  if (!def) return null;
+
+  return (
+    <Stack gap="xs">
+      <div>
+        <Title order={4}>{def.title}</Title>
+        <Text size="sm" c="dimmed">
+          {def.description}
+        </Text>
+      </div>
+      <ReportView reportKey={reportKey} idKeyValue={idKeyValue} />
+    </Stack>
+  );
+}
+
+export default ReportSection;
diff --git a/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx b/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx
new file mode 100644
index 000000000..0e28cd5fe
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx
@@ -0,0 +1,212 @@
+import { ActionIcon, Alert, Box, Card, Group, Stack, Text, Tooltip, UnstyledButton } from "@mantine/core";
+import { useDebouncedValue } from "@mantine/hooks";
+import { useQuery } from "@tanstack/react-query";
+import type { Column, SortingState } from "@tanstack/react-table";
+import { ArrowDown, ArrowUp, ArrowUpDown, FileSpreadsheet, FileText, RefreshCw } from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { KpiStrip } from "@/components/page/KpiStrip";
+import { api } from "@/services/api";
+import { reportsService } from "@/services/reports.service";
+import type { ReportRunParams } from "@/types/reports";
+import { DataTable, DataTableFooter, usePagination, type ColumnDef } from "@edr/ui-common";
+
+import { ReportFilters, type ReportFilterValues } from "./ReportFilters";
+import { formatKpiValue, formatReportCell } from "./report-format";
+
+function SortableHeader({ label, column }: { label: string; column: Column<Record<string, unknown>, unknown> }) {
+  const sorted = column.getIsSorted();
+  const Icon = sorted === "asc" ? ArrowUp : sorted === "desc" ? ArrowDown : ArrowUpDown;
+  return (
+    <UnstyledButton
+      onClick={column.getToggleSortingHandler()}
+      style={{ display: "flex", alignItems: "center", gap: 4 }}
+    >
+      <Text size="sm" fw={600} c="edr-text">
+        {label}
+      </Text>
+      <Icon size={13} opacity={sorted ? 1 : 0.4} />
+    </UnstyledButton>
+  );
+}
+
+interface ReportViewProps {
+  reportKey: string;
+  /** Scopes the report to one entity when embedded (e.g. a contract detail page). */
+  idKeyValue?: string;
+}
+
+/** Triggers a browser save for a blob without leaving the SPA. */
+function saveBlob(blob: Blob, filename: string) {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+/**
+ * The report engine: one component renders any report the catalog describes —
+ * filters, KPI strip, sortable/paginated table, xlsx/pdf export. Adding a
+ * report never touches this file.
+ */
+export function ReportView({ reportKey, idKeyValue }: ReportViewProps) {
+  const { data: catalog } = useQuery(api.reports.catalog.queryOptions());
+  const def = catalog?.find((r) => r.key === reportKey);
+
+  const { pagination, setPagination } = usePagination({ pageSize: 20 });
+  const [sorting, setSorting] = useState<SortingState>([]);
+  const [filterValues, setFilterValues] = useState<ReportFilterValues>({});
+  const [debouncedFilters] = useDebouncedValue(filterValues, 300);
+  const [exporting, setExporting] = useState<"xlsx" | "pdf" | null>(null);
+
+  const runParams: ReportRunParams | undefined = useMemo(() => {
+    if (!def) return undefined;
+    const sort = sorting[0];
+    return {
+      key: def.key,
+      page: pagination.pageIndex + 1,
+      pageSize: pagination.pageSize,
+      sortBy: sort?.id,
+      sortOrder: sort ? (sort.desc ? "DESC" : "ASC") : undefined,
+      ...debouncedFilters,
+      ...(def.idKey && idKeyValue ? { [def.idKey.key]: idKeyValue } : {}),
+    };
+  }, [def, pagination, sorting, debouncedFilters, idKeyValue]);
+
+  const { data, isLoading, isError, isFetching, refetch } = useQuery({
+    ...api.reports.run.queryOptions({ input: runParams as ReportRunParams }),
+    enabled: Boolean(runParams),
+  });
+
+  const total = data?.meta.total ?? 0;
+  const pageCount = Math.max(1, Math.ceil(total / pagination.pageSize));
+
+  const columns: ColumnDef<Record<string, unknown>>[] = useMemo(
+    () =>
+      (def?.columns ?? []).map((col) => ({
+        id: col.key,
+        accessorKey: col.key,
+        header: col.sortable
+          ? ({ column }) => <SortableHeader label={col.label} column={column} />
+          : col.label,
+        enableSorting: col.sortable,
+        cell: ({ row }) => (
+          <Text size="sm" c="edr-text">
+            {formatReportCell(row.original[col.key], col.type)}
+          </Text>
+        ),
+      })),
+    [def?.columns],
+  );
+
+  const handleExport = async (format: "xlsx" | "pdf") => {
+    if (!def) return;
+    setExporting(format);
+    try {
+      const { key: _key, page: _page, pageSize: _pageSize, ...filters } = runParams ?? {};
+      const blob = await reportsService.download(def.key, format, filters);
+      saveBlob(blob, `${def.key}.${format}`);
+    } finally {
+      setExporting(null);
+    }
+  };
+
+  if (!def) {
+    return catalog ? (
+      <Alert color="red">You don't have access to this report.</Alert>
+    ) : null;
+  }
+
+  return (
+    <Stack gap="md">
+      {data?.kpis.length ? (
+        <KpiStrip
+          loading={isLoading}
+          items={data.kpis.map((k) => ({ label: k.label, value: formatKpiValue(k.value, k.unit) }))}
+        />
+      ) : null}
+
+      <Card p={0}>
+        <Stack gap={0}>
+          <Box px="md" pt="md" pb="sm">
+            <Group justify="space-between" gap="md" wrap="wrap">
+              <ReportFilters
+                filters={def.filters}
+                values={filterValues}
+                onChange={(v) => {
+                  setFilterValues(v);
+                  setPagination((prev) => ({ ...prev, pageIndex: 0 }));
+                }}
+              />
+              <Group gap="xs">
+                <Tooltip label="Export to Excel">
+                  <ActionIcon
+                    variant="default"
+                    radius="md"
+                    loading={exporting === "xlsx"}
+                    onClick={() => void handleExport("xlsx")}
+                    aria-label="Export to Excel"
+                  >
+                    <FileSpreadsheet size={16} />
+                  </ActionIcon>
+                </Tooltip>
+                <Tooltip label="Export to PDF">
+                  <ActionIcon
+                    variant="default"
+                    radius="md"
+                    loading={exporting === "pdf"}
+                    onClick={() => void handleExport("pdf")}
+                    aria-label="Export to PDF"
+                  >
+                    <FileText size={16} />
+                  </ActionIcon>
+                </Tooltip>
+                <Tooltip label="Refresh">
+                  <ActionIcon
+                    variant="default"
+                    radius="md"
+                    loading={isFetching}
+                    onClick={() => void refetch()}
+                    aria-label="Refresh"
+                  >
+                    <RefreshCw size={16} />
+                  </ActionIcon>
+                </Tooltip>
+              </Group>
+            </Group>
+          </Box>
+
+          <Box style={{ overflowX: "auto" }} w="100%">
+            <DataTable
+              columns={columns}
+              data={data?.items ?? []}
+              status={isLoading ? "loading" : isError ? "error" : "success"}
+              emptyMessage="No data for the selected filters."
+              error={isError ? { message: "Failed to load report.", onRetry: () => void refetch() } : undefined}
+              pagination={{
+                pageIndex: pagination.pageIndex,
+                pageSize: pagination.pageSize,
+                pageCount,
+                totalCount: total,
+              }}
+              tableOptions={{
+                state: { sorting },
+                onSortingChange: setSorting,
+                onPaginationChange: setPagination,
+                manualPagination: true,
+                manualSorting: true,
+                pageCount,
+              }}
+              containerClassName="border-0 shadow-none bg-transparent"
+              footer={DataTableFooter}
+            />
+          </Box>
+        </Stack>
+      </Card>
+    </Stack>
+  );
+}
+
+export default ReportView;
diff --git a/apps/edr-freight-web/backoffice/src/components/reports/report-format.ts b/apps/edr-freight-web/backoffice/src/components/reports/report-format.ts
new file mode 100644
index 000000000..d9b174ef1
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/reports/report-format.ts
@@ -0,0 +1,42 @@
+import type { ReportColumnType } from "@/types/reports";
+
+/** Cell formatting shared by the on-screen table and (indirectly) exports. */
+export function formatReportCell(value: unknown, type: ReportColumnType): string {
+  if (value === null || value === undefined || value === "") return "—";
+  switch (type) {
+    case "money":
+      return new Intl.NumberFormat(undefined, {
+        style: "currency",
+        currency: "ETB",
+        maximumFractionDigits: 2,
+      }).format(Number(value));
+    case "tons":
+      return `${Number(value).toLocaleString()} t`;
+    case "percent":
+      return `${value}%`;
+    case "number":
+      return Number(value).toLocaleString();
+    case "date": {
+      const d = new Date(String(value));
+      return Number.isNaN(d.getTime())
+        ? String(value)
+        : d.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" });
+    }
+    default:
+      return String(value);
+  }
+}
+
+export function formatKpiValue(value: number, unit?: string): string {
+  const formatted = value.toLocaleString(undefined, { maximumFractionDigits: 1 });
+  if (unit === "ETB") {
+    return new Intl.NumberFormat(undefined, {
+      style: "currency",
+      currency: "ETB",
+      maximumFractionDigits: 0,
+    }).format(value);
+  }
+  if (unit === "%") return `${formatted}%`;
+  if (unit === "t") return `${formatted} t`;
+  return formatted;
+}
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index d3566645e..ba74f3206 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -128,7 +128,9 @@ export const URL_CONSTANTS = {
   },
 
   REPORTS: {
+    CATALOG: "/reports",
     RUN: (key: string) => `/reports/${key}`,
+    EXPORT: (key: string) => `/reports/${key}/export`,
   },
 
   OVERVIEW: {
diff --git a/apps/edr-freight-web/backoffice/src/pages/reports/ReportPage.tsx b/apps/edr-freight-web/backoffice/src/pages/reports/ReportPage.tsx
index 71a270a78..0869adb4e 100644
--- a/apps/edr-freight-web/backoffice/src/pages/reports/ReportPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/reports/ReportPage.tsx
@@ -1,445 +1,23 @@
-import {
-  Button,
-  Card,
-  Group,
-  MultiSelect,
-  Select,
-  Text,
-} from "@mantine/core";
-import { DateInput } from "@mantine/dates";
-import { keepPreviousData, useQuery } from "@tanstack/react-query";
-import {
-  DataTable,
-  DataTableFooter,
-  usePagination,
-  type ColumnDef,
-} from "@edr/ui-common";
-import { Download, FileSpreadsheet, Printer, RotateCcw } from "lucide-react";
-import { useMemo } from "react";
-import { useParams, useSearchParams, Link } from "react-router-dom";
-import {
-  Area,
-  AreaChart,
-  Bar,
-  BarChart,
-  CartesianGrid,
-  Legend,
-  Line,
-  LineChart,
-  ResponsiveContainer,
-  Tooltip,
-  XAxis,
-  YAxis,
-} from "recharts";
-import * as XLSX from "xlsx";
-import { ALL_TRADE_DIRECTIONS, TRADE_DIRECTION_LABELS } from "@edr/types";
+import { useQuery } from "@tanstack/react-query";
+import { useParams } from "react-router-dom";
 
-import { KpiStrip, PageContainer, PageHeader } from "@/components/page";
-import { overviewChartColors } from "@/components/overview/overview.styles";
+import { ReportView } from "@/components/reports/ReportView";
+import { PageContainer, PageHeader } from "@/components/page";
 import { api } from "@/services/api";
-import type { ReportQueryInput, ReportRow } from "@/types/reports";
-import {
-  REPORT_CONFIG_BY_KEY,
-  type ReportColumn,
-  type ReportConfig,
-} from "./reportConfigs";
-
-const compact = new Intl.NumberFormat("en", { notation: "compact" });
-
-const UNIT_SUFFIX = { ETB: " ETB", t: " t", "%": "%", min: " min" } as const;
-
-function formatCell(value: unknown, col: ReportColumn): string {
-  if (value === null || value === undefined || value === "") return "—";
-  if (col.unit || col.numeric) {
-    const n = Number(value);
-    if (!Number.isNaN(n)) {
-      return `${n.toLocaleString()}${col.unit ? UNIT_SUFFIX[col.unit] : ""}`;
-    }
-  }
-  return String(value);
-}
-
-const toDate = (s: string | null): Date | null => (s ? new Date(s) : null);
-// Mantine DateInput onChange emits a date string (or null).
-const toParam = (d: Date | string | null): string | null => {
-  if (!d) return null;
-  return typeof d === "string" ? d.slice(0, 10) : d.toISOString().slice(0, 10);
-};
-
-function downloadBlob(content: BlobPart, type: string, filename: string) {
-  const url = URL.createObjectURL(new Blob([content], { type }));
-  const a = document.createElement("a");
-  a.href = url;
-  a.download = filename;
-  a.click();
-  URL.revokeObjectURL(url);
-}
-
-function exportCsv(config: ReportConfig, rows: ReportRow[]) {
-  const esc = (v: unknown) => `"${String(v ?? "").replace(/"/g, '""')}"`;
-  const lines = [
-    config.columns.map((c) => esc(c.label)).join(","),
-    ...rows.map((r) => config.columns.map((c) => esc(r[c.key])).join(",")),
-  ];
-  downloadBlob(lines.join("\n"), "text/csv;charset=utf-8", `${config.key}.csv`);
-}
-
-function exportXlsx(config: ReportConfig, rows: ReportRow[]) {
-  const sheetRows = rows.map((r) =>
-    Object.fromEntries(config.columns.map((c) => [c.label, r[c.key] ?? ""])),
-  );
-  const wb = XLSX.utils.book_new();
-  XLSX.utils.book_append_sheet(
-    wb,
-    XLSX.utils.json_to_sheet(sheetRows),
-    config.title.slice(0, 31),
-  );
-  XLSX.writeFile(wb, `${config.key}.xlsx`);
-}
-
-function ReportChartView({
-  config,
-  rows,
-}: {
-  config: ReportConfig;
-  rows: ReportRow[];
-}) {
-  const chart = config.chart;
-  const data = useMemo(() => {
-    if (!chart) return [];
-    const sliced = chart.topN ? rows.slice(0, chart.topN) : rows;
-    // xKey "a+b" concatenates columns (e.g. origin+destination → "A → B").
-    const keys = chart.xKey.split("+");
-    return sliced.map((r) => ({
-      ...r,
-      __x:
-        keys.length > 1
-          ? keys.map((k) => String(r[k] ?? "")).join(" → ")
-          : String(r[chart.xKey] ?? ""),
-    }));
-  }, [chart, rows]);
-
-  if (!chart) return null;
-  if (data.length === 0) {
-    return (
-      <Card withBorder shadow="sm">
-        <Text c="dimmed" ta="center" py="xl">
-          No data for the selected filters
-        </Text>
-      </Card>
-    );
-  }
-
-  const ChartComponent =
-    chart.type === "bar" ? BarChart : chart.type === "line" ? LineChart : AreaChart;
-
-  return (
-    <Card withBorder shadow="sm">
-      <ResponsiveContainer width="100%" height={280}>
-        <ChartComponent data={data} margin={{ top: 8, right: 8, left: 8, bottom: 0 }}>
-          <CartesianGrid strokeDasharray="3 3" stroke="#e5e7eb" />
-          <XAxis dataKey="__x" tick={{ fontSize: 12 }} interval="preserveStartEnd" />
-          <YAxis
-            tick={{ fontSize: 12 }}
-            tickFormatter={(v: number) => compact.format(v)}
-            width={56}
-          />
-          <Tooltip formatter={(value) => Number(value ?? 0).toLocaleString()} />
-          {chart.series.length > 1 ? <Legend /> : null}
-          {chart.series.map((s, i) => {
-            const color =
-              overviewChartColors.pipeline[i % overviewChartColors.pipeline.length];
-            if (chart.type === "bar") {
-              return (
-                <Bar key={s.key} dataKey={s.key} name={s.label} fill={color} radius={[4, 4, 0, 0]} />
-              );
-            }
-            if (chart.type === "line") {
-              return (
-                <Line
-                  key={s.key}
-                  type="monotone"
-                  dataKey={s.key}
-                  name={s.label}
-                  stroke={color}
-                  strokeWidth={2}
-                  dot={false}
-                />
-              );
-            }
-            return (
-              <Area
-                key={s.key}
-                type="monotone"
-                dataKey={s.key}
-                name={s.label}
-                stroke={color}
-                fill={color}
-                fillOpacity={0.15}
-                strokeWidth={2}
-              />
-            );
-          })}
-        </ChartComponent>
-      </ResponsiveContainer>
-    </Card>
-  );
-}
 
 export default function ReportPage() {
   const { reportKey = "" } = useParams<{ reportKey: string }>();
-  const config = REPORT_CONFIG_BY_KEY.get(reportKey);
-  const [params, setParams] = useSearchParams();
-  const { pagination, setPagination } = usePagination({ pageSize: 20 });
-
-  const setParam = (name: string, value: string | null) => {
-    setParams(
-      (prev) => {
-        if (value) prev.set(name, value);
-        else prev.delete(name);
-        return prev;
-      },
-      { replace: true },
-    );
-    setPagination((p) => ({ ...p, pageIndex: 0 }));
-  };
-
-  const input: ReportQueryInput = {
-    key: reportKey,
-    dateFrom: params.get("dateFrom") ?? undefined,
-    dateTo: params.get("dateTo") ?? undefined,
-    granularity:
-      (params.get("granularity") as ReportQueryInput["granularity"]) ?? undefined,
-    yardIds: params.get("yardIds") ?? undefined,
-    statuses: params.get("statuses") ?? undefined,
-    direction: params.get("direction") ?? undefined,
-    freightType: params.get("freightType") ?? undefined,
-  };
-
-  const reportQuery = useQuery(
-    api.reports.run.queryOptions({
-      input,
-      placeholderData: keepPreviousData,
-      staleTime: 30_000,
-      enabled: Boolean(config),
-    }),
-  );
-
-  const yardsQuery = useQuery(
-    api.routes.yards.queryOptions({
-      staleTime: 5 * 60_000,
-      enabled: Boolean(config?.filters.includes("yards")),
-    }),
-  );
-
-  if (!config) {
-    return (
-      <PageContainer>
-        <PageHeader title="Unknown report" backTo="/dashboard/reports" />
-        <Text>
-          This report does not exist. <Link to="/dashboard/reports">Back to reports</Link>
-        </Text>
-      </PageContainer>
-    );
-  }
-
-  const rows = reportQuery.data?.rows ?? [];
-  const kpis = reportQuery.data?.kpis ?? [];
-  const pageCount = Math.max(1, Math.ceil(rows.length / pagination.pageSize));
-
-  const columns: ColumnDef<ReportRow, unknown>[] = config.columns.map((col) => ({
-    accessorKey: col.key,
-    header: col.label,
-    cell: (info) => formatCell(info.getValue(), col),
-  }));
-
-  const tableStatus = reportQuery.isLoading
-    ? "loading"
-    : reportQuery.isError
-      ? "error"
-      : "success";
+  const { data: catalog } = useQuery(api.reports.catalog.queryOptions());
+  const def = catalog?.find((r) => r.key === reportKey);
 
   return (
     <PageContainer>
       <PageHeader
-        title={config.title}
-        subtitle={config.description}
+        title={def?.title ?? "Report"}
+        subtitle={def?.description}
         backTo="/dashboard/reports"
-        action={
-          <Group gap="xs">
-            <Button
-              variant="default"
-              size="xs"
-              leftSection={<Download size={14} />}
-              onClick={() => exportCsv(config, rows)}
-              disabled={rows.length === 0}
-            >
-              CSV
-            </Button>
-            <Button
-              variant="default"
-              size="xs"
-              leftSection={<FileSpreadsheet size={14} />}
-              onClick={() => exportXlsx(config, rows)}
-              disabled={rows.length === 0}
-            >
-              Excel
-            </Button>
-            <Button
-              variant="default"
-              size="xs"
-              leftSection={<Printer size={14} />}
-              onClick={() => window.print()}
-            >
-              Print
-            </Button>
-          </Group>
-        }
-      />
-
-      <Card withBorder shadow="sm">
-        <Group gap="sm" align="flex-end" wrap="wrap">
-          <DateInput
-            label="From"
-            size="xs"
-            clearable
-            value={toDate(params.get("dateFrom"))}
-            maxDate={toDate(params.get("dateTo")) ?? undefined}
-            onChange={(d) => setParam("dateFrom", toParam(d))}
-            placeholder="All time"
-          />
-          <DateInput
-            label="To"
-            size="xs"
-            clearable
-            value={toDate(params.get("dateTo"))}
-            minDate={toDate(params.get("dateFrom")) ?? undefined}
-            onChange={(d) => setParam("dateTo", toParam(d))}
-            placeholder="All time"
-          />
-          {config.filters.includes("granularity") ? (
-            <Select
-              label="Group by"
-              size="xs"
-              data={[
-                { value: "day", label: "Day" },
-                { value: "week", label: "Week" },
-                { value: "month", label: "Month" },
-              ]}
-              value={params.get("granularity") ?? "day"}
-              onChange={(v) => setParam("granularity", v)}
-              allowDeselect={false}
-            />
-          ) : null}
-          {config.filters.includes("yards") ? (
-            <MultiSelect
-              label="Yards"
-              size="xs"
-              searchable
-              clearable
-              w={220}
-              data={(yardsQuery.data ?? []).map((y) => ({
-                value: y.id,
-                label: y.label,
-              }))}
-              value={params.get("yardIds")?.split(",").filter(Boolean) ?? []}
-              onChange={(v) => setParam("yardIds", v.length ? v.join(",") : null)}
-              placeholder="All yards"
-            />
-          ) : null}
-          {config.filters.includes("direction") ? (
-            <Select
-              label="Direction"
-              size="xs"
-              clearable
-              data={ALL_TRADE_DIRECTIONS.map((d) => ({
-                value: d,
-                label: TRADE_DIRECTION_LABELS[d],
-              }))}
-              value={params.get("direction")}
-              onChange={(v) => setParam("direction", v)}
-              placeholder="All"
-            />
-          ) : null}
-          {config.filters.includes("freightType") ? (
-            <Select
-              label="Freight type"
-              size="xs"
-              clearable
-              data={["CONTAINER", "BULK"]}
-              value={params.get("freightType")}
-              onChange={(v) => setParam("freightType", v)}
-              placeholder="All"
-            />
-          ) : null}
-          {config.filters.includes("statuses") && config.statusOptions ? (
-            <MultiSelect
-              label="Status"
-              size="xs"
-              searchable
-              clearable
-              w={220}
-              data={config.statusOptions}
-              value={params.get("statuses")?.split(",").filter(Boolean) ?? []}
-              onChange={(v) => setParam("statuses", v.length ? v.join(",") : null)}
-              placeholder="Default (active)"
-            />
-          ) : null}
-          <Button
-            variant="subtle"
-            size="xs"
-            leftSection={<RotateCcw size={14} />}
-            onClick={() => setParams({}, { replace: true })}
-          >
-            Reset
-          </Button>
-        </Group>
-      </Card>
-
-      <KpiStrip
-        loading={reportQuery.isLoading}
-        items={kpis.map((k) => ({
-          label: k.label,
-          value: k.value.toLocaleString(),
-          hint: k.unit,
-        }))}
-      />
-
-      <ReportChartView config={config} rows={rows} />
-
-      <DataTable
-        columns={columns}
-        data={rows}
-        status={tableStatus}
-        emptyMessage="No data for the selected filters"
-        error={
-          reportQuery.isError
-            ? {
-                message: "Failed to load report",
-                onRetry: () => void reportQuery.refetch(),
-              }
-            : undefined
-        }
-        pagination={{
-          pageIndex: pagination.pageIndex,
-          pageSize: pagination.pageSize,
-          pageCount,
-          totalCount: rows.length,
-        }}
-        tableOptions={{
-          manualPagination: false,
-          state: { pagination },
-          onPaginationChange: setPagination,
-          autoResetPageIndex: false,
-        }}
-        footer={({ table, pagination: p }) => (
-          <DataTableFooter
-            table={table}
-            pagination={p}
-            options={{ labels: { items: "rows" } }}
-          />
-        )}
       />
+      <ReportView reportKey={reportKey} />
     </PageContainer>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/reports/ReportsHubPage.tsx b/apps/edr-freight-web/backoffice/src/pages/reports/ReportsHubPage.tsx
index f8f6f161d..172afca82 100644
--- a/apps/edr-freight-web/backoffice/src/pages/reports/ReportsHubPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/reports/ReportsHubPage.tsx
@@ -1,159 +1,64 @@
-import {
-  ActionIcon,
-  Badge,
-  Card,
-  Group,
-  SimpleGrid,
-  Stack,
-  Text,
-  TextInput,
-  Title,
-} from "@mantine/core";
-import { Search, Star } from "lucide-react";
-import { useMemo, useState } from "react";
+import { Alert, Card, SimpleGrid, Skeleton, Stack, Text, Title } from "@mantine/core";
+import { useQuery } from "@tanstack/react-query";
 import { useNavigate } from "react-router-dom";
 
 import { PageContainer, PageHeader } from "@/components/page";
-import {
-  REPORT_CONFIGS,
-  REPORT_DOMAINS,
-  type ReportConfig,
-} from "./reportConfigs";
+import { api } from "@/services/api";
+import type { ReportCatalogEntry } from "@/types/reports";
 
-const FAVORITES_KEY = "reports.favorites";
-
-const loadFavorites = (): string[] => {
-  try {
-    return JSON.parse(localStorage.getItem(FAVORITES_KEY) ?? "[]");
-  } catch {
-    return [];
-  }
-};
-
-function ReportCard({
-  config,
-  favorite,
-  onToggleFavorite,
-}: {
-  config: ReportConfig;
-  favorite: boolean;
-  onToggleFavorite: () => void;
-}) {
-  const navigate = useNavigate();
-  return (
-    <Card
-      withBorder
-      shadow="sm"
-      className="cursor-pointer transition-colors hover:bg-gray-50"
-      onClick={() => navigate(`/dashboard/reports/${config.key}`)}
-    >
-      <Group justify="space-between" align="flex-start" wrap="nowrap">
-        <div style={{ minWidth: 0 }}>
-          <Text fw={600} truncate>
-            {config.title}
-          </Text>
-          <Text size="sm" c="dimmed" lineClamp={2}>
-            {config.description}
-          </Text>
-        </div>
-        <ActionIcon
-          variant="subtle"
-          color={favorite ? "yellow" : "gray"}
-          aria-label={favorite ? "Remove from favorites" : "Add to favorites"}
-          onClick={(e) => {
-            e.stopPropagation();
-            onToggleFavorite();
-          }}
-        >
-          <Star size={16} fill={favorite ? "currentColor" : "none"} />
-        </ActionIcon>
-      </Group>
-      <Badge mt="sm" size="sm" variant="light">
-        {config.domain}
-      </Badge>
-    </Card>
-  );
-}
+const GROUP_ORDER: ReportCatalogEntry["group"][] = ["Commercial", "Operations", "Finance"];
 
 export default function ReportsHubPage() {
-  const [search, setSearch] = useState("");
-  const [favorites, setFavorites] = useState<string[]>(loadFavorites);
+  const navigate = useNavigate();
+  const { data: catalog, isLoading, isError } = useQuery(api.reports.catalog.queryOptions());
 
-  const toggleFavorite = (key: string) => {
-    setFavorites((prev) => {
-      const next = prev.includes(key)
-        ? prev.filter((k) => k !== key)
-        : [...prev, key];
-      localStorage.setItem(FAVORITES_KEY, JSON.stringify(next));
-      return next;
-    });
-  };
-
-  const visible = useMemo(() => {
-    const q = search.trim().toLowerCase();
-    if (!q) return REPORT_CONFIGS;
-    return REPORT_CONFIGS.filter(
-      (c) =>
-        c.title.toLowerCase().includes(q) ||
-        c.description.toLowerCase().includes(q),
-    );
-  }, [search]);
-
-  const pinned = visible.filter((c) => favorites.includes(c.key));
-
-  const renderGrid = (configs: ReportConfig[]) => (
-    <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="md">
-      {configs.map((c) => (
-        <ReportCard
-          key={c.key}
-          config={c}
-          favorite={favorites.includes(c.key)}
-          onToggleFavorite={() => toggleFavorite(c.key)}
-        />
-      ))}
-    </SimpleGrid>
-  );
+  const groups = GROUP_ORDER.map((group) => ({
+    group,
+    reports: (catalog ?? []).filter((r) => r.group === group),
+  })).filter((g) => g.reports.length);
 
   return (
     <PageContainer>
-      <PageHeader
-        title="Reports"
-        subtitle="Operational, commercial and financial reporting"
-        action={
-          <TextInput
-            size="xs"
-            w={240}
-            leftSection={<Search size={14} />}
-            placeholder="Search reports…"
-            value={search}
-            onChange={(e) => setSearch(e.currentTarget.value)}
-          />
-        }
-      />
+      <PageHeader title="Reports" subtitle="Every report you have access to, grouped by area." />
 
-      {pinned.length ? (
-        <Stack gap="sm">
-          <Title order={4}>Favorites</Title>
-          {renderGrid(pinned)}
+      {isError ? <Alert color="red">Failed to load the report catalog.</Alert> : null}
+
+      {isLoading ? (
+        <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="md">
+          {Array.from({ length: 6 }).map((_, i) => (
+            <Skeleton key={i} height={96} radius="md" />
+          ))}
+        </SimpleGrid>
+      ) : null}
+
+      {!isLoading && !isError && !groups.length ? (
+        <Text c="dimmed">You don't have access to any reports yet.</Text>
+      ) : null}
+
+      {groups.map(({ group, reports }) => (
+        <Stack key={group} gap="sm">
+          <Title order={4}>{group}</Title>
+          <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="md">
+            {reports.map((report) => (
+              <Card
+                key={report.key}
+                withBorder
+                radius="md"
+                p="md"
+                className="cursor-pointer transition-colors hover:bg-gray-50"
+                onClick={() => navigate(`/dashboard/reports/${report.key}`)}
+              >
+                <Text fw={600} c="edr-text">
+                  {report.title}
+                </Text>
+                <Text size="sm" c="dimmed" mt={4}>
+                  {report.description}
+                </Text>
+              </Card>
+            ))}
+          </SimpleGrid>
         </Stack>
-      ) : null}
-
-      {REPORT_DOMAINS.map((domain) => {
-        const configs = visible.filter((c) => c.domain === domain);
-        if (!configs.length) return null;
-        return (
-          <Stack key={domain} gap="sm">
-            <Title order={4}>{domain}</Title>
-            {renderGrid(configs)}
-          </Stack>
-        );
-      })}
-
-      {visible.length === 0 ? (
-        <Text c="dimmed" ta="center" py="xl">
-          No reports match “{search}”
-        </Text>
-      ) : null}
+      ))}
     </PageContainer>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/reports/reportConfigs.ts b/apps/edr-freight-web/backoffice/src/pages/reports/reportConfigs.ts
deleted file mode 100644
index ced916fbb..000000000
--- a/apps/edr-freight-web/backoffice/src/pages/reports/reportConfigs.ts
+++ /dev/null
@@ -1,445 +0,0 @@
-import { BookingStatus } from "@edr/types";
-
-export type ReportDomain = "Commercial" | "Operations" | "Finance" | "Data";
-
-export type ReportColumnUnit = "ETB" | "t" | "%" | "min";
-
-export interface ReportColumn {
-  key: string;
-  label: string;
-  /** Numeric unit — formats the cell (thousands separators, suffix). */
-  unit?: ReportColumnUnit;
-  numeric?: boolean;
-}
-
-export interface ReportChart {
-  type: "area" | "line" | "bar";
-  xKey: string;
-  series: { key: string; label: string }[];
-  /** Chart only the first N rows (rows arrive sorted by the backend). */
-  topN?: number;
-}
-
-export type ReportFilterKey =
-  | "granularity"
-  | "yards"
-  | "direction"
-  | "freightType"
-  | "statuses";
-
-export interface ReportConfig {
-  key: string;
-  title: string;
-  description: string;
-  domain: ReportDomain;
-  filters: ReportFilterKey[];
-  /** Options for the `statuses` filter, when enabled. */
-  statusOptions?: string[];
-  chart?: ReportChart;
-  columns: ReportColumn[];
-}
-
-// Full enum from @edr/types; Set dedupes the deprecated AwaitingPayment alias.
-const BOOKING_STATUSES = [...new Set(Object.values(BookingStatus))];
-
-// Full list mirroring CONTRACT_STATUSES in contract.entity.ts (no shared enum
-// in @edr/types yet).
-const CONTRACT_STATUSES = [
-  "DRAFT",
-  "SUBMITTED",
-  "PRICE_CHANGED_PENDING_CONFIRM",
-  "CHANGES_REQUESTED",
-  "PENDING_APPROVAL",
-  "APPROVED",
-  "APPROVED_PENDING_SIGNATURE",
-  "CONTRACT_READY",
-  "SIGNED_CUSTOMER",
-  "FULLY_EXECUTED",
-  "CONTRACT_ACTIVE",
-  "AWAITING_CLEARANCE_DOCUMENTS",
-  "CLEARANCE_UNDER_REVIEW",
-  "CLEARANCE_READY_FOR_BOOKING",
-  "ACTIVE_SHIPMENT_IN_PROGRESS",
-  "SUSPENDED",
-  "CONTRACT_CLOSED",
-  "EXPIRED",
-  "REJECTED",
-  "CANCELLED",
-  "RENEWAL_DRAFT",
-  "RENEWAL_SUBMITTED",
-  "RENEWAL_PENDING_APPROVAL",
-  "AMENDMENTS_PROPOSED",
-  "ARCHIVED",
-];
-
-const INVOICE_STATUSES = [
-  "ISSUED",
-  "PENDING",
-  "PAYMENT_PROCESSING",
-  "PARTIALLY_PAID",
-  "PAID",
-  "OVERDUE",
-  "REFUNDED",
-];
-
-export const REPORT_CONFIGS: ReportConfig[] = [
-  {
-    key: "bookings-trend",
-    title: "Bookings Trend",
-    description: "Booking volume, tonnage and revenue over time",
-    domain: "Commercial",
-    filters: ["granularity", "yards", "direction", "freightType", "statuses"],
-    statusOptions: BOOKING_STATUSES,
-    chart: {
-      type: "area",
-      xKey: "period",
-      series: [{ key: "revenue", label: "Revenue (ETB)" }],
-    },
-    columns: [
-      { key: "period", label: "Period" },
-      { key: "bookings", label: "Bookings", numeric: true },
-      { key: "tons", label: "Tonnage", unit: "t" },
-      { key: "revenue", label: "Revenue", unit: "ETB" },
-    ],
-  },
-  {
-    key: "revenue-by-customer",
-    title: "Revenue by Customer",
-    description: "Ranked customers by booking revenue",
-    domain: "Commercial",
-    filters: ["yards", "direction", "freightType", "statuses"],
-    statusOptions: BOOKING_STATUSES,
-    chart: {
-      type: "bar",
-      xKey: "customer",
-      series: [{ key: "revenue", label: "Revenue (ETB)" }],
-      topN: 10,
-    },
-    columns: [
-      { key: "customer", label: "Customer" },
-      { key: "bookings", label: "Bookings", numeric: true },
-      { key: "tons", label: "Tonnage", unit: "t" },
-      { key: "revenue", label: "Revenue", unit: "ETB" },
-    ],
-  },
-  {
-    key: "revenue-by-lane",
-    title: "Revenue by Lane",
-    description: "Origin → destination lanes by tonnage and revenue",
-    domain: "Commercial",
-    filters: ["direction", "freightType", "statuses"],
-    statusOptions: BOOKING_STATUSES,
-    chart: {
-      type: "bar",
-      xKey: "origin+destination",
-      series: [{ key: "revenue", label: "Revenue (ETB)" }],
-      topN: 10,
-    },
-    columns: [
-      { key: "origin", label: "Origin" },
-      { key: "destination", label: "Destination" },
-      { key: "bookings", label: "Bookings", numeric: true },
-      { key: "tons", label: "Tonnage", unit: "t" },
-      { key: "revenue", label: "Revenue", unit: "ETB" },
-    ],
-  },
-  {
-    key: "contract-utilization",
-    title: "Contract Utilization",
-    description: "Committed scope caps vs booked tonnage per contract",
-    domain: "Commercial",
-    filters: ["direction", "statuses"],
-    statusOptions: CONTRACT_STATUSES,
-    columns: [
-      { key: "reference", label: "Contract" },
-      { key: "customer", label: "Customer" },
-      { key: "status", label: "Status" },
-      { key: "kind", label: "Kind" },
-      { key: "valid_from", label: "Valid from" },
-      { key: "valid_until", label: "Valid until" },
-      { key: "committed", label: "Committed", unit: "t" },
-      { key: "booked_tons", label: "Booked", unit: "t" },
-      { key: "bookings", label: "Bookings", numeric: true },
-      { key: "utilization_pct", label: "Utilization", unit: "%" },
-    ],
-  },
-  {
-    key: "train-on-time",
-    title: "Train On-Time Performance",
-    description: "Departure punctuality and delays by lane (60-min grace)",
-    domain: "Operations",
-    filters: ["yards", "direction"],
-    chart: {
-      type: "bar",
-      xKey: "origin+destination",
-      series: [{ key: "on_time_pct", label: "On-time %" }],
-      topN: 15,
-    },
-    columns: [
-      { key: "origin", label: "Origin" },
-      { key: "destination", label: "Destination" },
-      { key: "trips", label: "Trips", numeric: true },
-      { key: "departed", label: "Departed", numeric: true },
-      { key: "avg_dep_delay_min", label: "Avg dep. delay", unit: "min" },
-      { key: "avg_arr_delay_min", label: "Avg arr. delay", unit: "min" },
-      { key: "on_time_pct", label: "On-time", unit: "%" },
-    ],
-  },
-  {
-    key: "schedule-fill-rate",
-    title: "Schedule Fill Rate",
-    description: "Booked tonnage vs wagon capacity per train schedule",
-    domain: "Operations",
-    filters: ["yards", "direction"],
-    chart: {
-      type: "line",
-      xKey: "departure",
-      series: [{ key: "fill_pct", label: "Fill %" }],
-    },
-    columns: [
-      { key: "train_number", label: "Train" },
-      { key: "departure", label: "Departure" },
-      { key: "origin", label: "Origin" },
-      { key: "destination", label: "Destination" },
-      { key: "direction", label: "Direction" },
-      { key: "status", label: "Status" },
-      { key: "wagon_count", label: "Wagons", numeric: true },
-      { key: "capacity_tons", label: "Capacity", unit: "t" },
-      { key: "booked_tons", label: "Booked", unit: "t" },
-      { key: "fill_pct", label: "Fill", unit: "%" },
-    ],
-  },
-  {
-    key: "trips-per-route",
-    title: "Trips per Route",
-    description: "Completed trips and tonnage hauled per lane",
-    domain: "Operations",
-    filters: ["yards", "direction"],
-    chart: {
-      type: "bar",
-      xKey: "origin+destination",
-      series: [{ key: "trips", label: "Trips" }],
-      topN: 15,
-    },
-    columns: [
-      { key: "origin", label: "Origin" },
-      { key: "destination", label: "Destination" },
-      { key: "direction", label: "Direction" },
-      { key: "trips", label: "Trips", numeric: true },
-      { key: "tons_hauled", label: "Tonnage hauled", unit: "t" },
-      { key: "avg_tons_per_trip", label: "Avg per trip", unit: "t" },
-    ],
-  },
-  {
-    key: "invoiced-vs-collected",
-    title: "Invoiced vs Collected",
-    description: "Billing issued vs payments received over time",
-    domain: "Finance",
-    filters: ["granularity", "direction"],
-    chart: {
-      type: "line",
-      xKey: "period",
-      series: [
-        { key: "invoiced", label: "Invoiced (ETB)" },
-        { key: "collected", label: "Collected (ETB)" },
-      ],
-    },
-    columns: [
-      { key: "period", label: "Period" },
-      { key: "invoices", label: "Invoices", numeric: true },
-      { key: "invoiced", label: "Invoiced", unit: "ETB" },
-      { key: "collected", label: "Collected", unit: "ETB" },
-      { key: "outstanding", label: "Outstanding", unit: "ETB" },
-    ],
-  },
-  {
-    key: "aging-receivables",
-    title: "Aging Receivables",
-    description: "Outstanding invoice balances by age bucket per customer",
-    domain: "Finance",
-    filters: ["direction", "statuses"],
-    statusOptions: INVOICE_STATUSES,
-    chart: {
-      type: "bar",
-      xKey: "customer",
-      series: [{ key: "outstanding", label: "Outstanding (ETB)" }],
-      topN: 10,
-    },
-    columns: [
-      { key: "customer", label: "Customer" },
-      { key: "invoices", label: "Invoices", numeric: true },
-      { key: "outstanding", label: "Outstanding", unit: "ETB" },
-      { key: "current", label: "Current", unit: "ETB" },
-      { key: "overdue_0_30", label: "0–30d", unit: "ETB" },
-      { key: "overdue_31_60", label: "31–60d", unit: "ETB" },
-      { key: "overdue_61_90", label: "61–90d", unit: "ETB" },
-      { key: "overdue_90_plus", label: "90d+", unit: "ETB" },
-    ],
-  },
-  {
-    key: "revenue-by-payment-method",
-    title: "Revenue by Payment Method",
-    description: "Successful payments broken down by method",
-    domain: "Finance",
-    filters: ["direction"],
-    chart: {
-      type: "bar",
-      xKey: "method",
-      series: [{ key: "amount", label: "Amount (ETB)" }],
-    },
-    columns: [
-      { key: "method", label: "Method" },
-      { key: "payments", label: "Payments", numeric: true },
-      { key: "amount", label: "Amount", unit: "ETB" },
-    ],
-  },
-  // --- Record-level list exports (Data domain) — filtered or full dumps ---
-  {
-    key: "bookings-list",
-    title: "Bookings Export",
-    description: "Booking records with customer, lane, cargo, amounts",
-    domain: "Data",
-    filters: ["yards", "direction", "freightType", "statuses"],
-    statusOptions: BOOKING_STATUSES,
-    columns: [
-      { key: "reference", label: "Reference" },
-      { key: "created", label: "Created" },
-      { key: "customer", label: "Customer" },
-      { key: "status", label: "Status" },
-      { key: "freight_type", label: "Freight" },
-      { key: "direction", label: "Direction" },
-      { key: "origin", label: "Origin" },
-      { key: "destination", label: "Destination" },
-      { key: "cargo", label: "Cargo" },
-      { key: "tons", label: "Tonnage", unit: "t" },
-      { key: "amount", label: "Amount", unit: "ETB" },
-      { key: "payment_status", label: "Payment" },
-      { key: "scheduling_status", label: "Scheduling" },
-    ],
-  },
-  {
-    key: "contracts-list",
-    title: "Contracts Export",
-    description: "Contract records with validity, status, customer",
-    domain: "Data",
-    filters: ["direction", "statuses"],
-    statusOptions: CONTRACT_STATUSES,
-    columns: [
-      { key: "reference", label: "Reference" },
-      { key: "customer", label: "Customer" },
-      { key: "kind", label: "Kind" },
-      { key: "status", label: "Status" },
-      { key: "direction", label: "Direction" },
-      { key: "freight_type", label: "Freight" },
-      { key: "valid_from", label: "Valid from" },
-      { key: "valid_until", label: "Valid until" },
-      { key: "created", label: "Created" },
-    ],
-  },
-  {
-    key: "schedules-list",
-    title: "Train Schedules Export",
-    description: "Schedule records with planned vs actual times",
-    domain: "Data",
-    filters: ["yards", "direction", "statuses"],
-    statusOptions: ["DRAFT", "SCHEDULED", "DISPATCHED", "ARRIVED", "CANCELLED"],
-    columns: [
-      { key: "train_number", label: "Train" },
-      { key: "reference", label: "Reference" },
-      { key: "direction", label: "Direction" },
-      { key: "status", label: "Status" },
-      { key: "origin", label: "Origin" },
-      { key: "destination", label: "Destination" },
-      { key: "scheduled_departure", label: "Sched. departure" },
-      { key: "actual_departure", label: "Actual departure" },
-      { key: "scheduled_arrival", label: "Sched. arrival" },
-      { key: "actual_arrival", label: "Actual arrival" },
-      { key: "max_wagons", label: "Max wagons", numeric: true },
-      { key: "wagon_count", label: "Wagons", numeric: true },
-    ],
-  },
-  {
-    key: "fleet-wagons",
-    title: "Wagons Export",
-    description: "Wagon fleet with type, capacity, status, location",
-    domain: "Data",
-    filters: ["yards", "statuses"],
-    statusOptions: ["AVAILABLE", "ASSIGNED", "MAINTENANCE"],
-    columns: [
-      { key: "wagon_number", label: "Wagon" },
-      { key: "type", label: "Type" },
-      { key: "capacity_tons", label: "Capacity", unit: "t" },
-      { key: "status", label: "Status" },
-      { key: "current_yard", label: "Current yard" },
-    ],
-  },
-  {
-    key: "fleet-locomotives",
-    title: "Locomotives Export",
-    description: "Locomotive fleet with type, pull capacity, status",
-    domain: "Data",
-    filters: ["yards", "statuses"],
-    statusOptions: ["AVAILABLE", "OUT_OF_SERVICE"],
-    columns: [
-      { key: "code", label: "Code" },
-      { key: "name", label: "Name" },
-      { key: "locomotive_type", label: "Type" },
-      { key: "max_pull_tons", label: "Max pull", unit: "t" },
-      { key: "status", label: "Status" },
-      { key: "current_yard", label: "Current yard" },
-    ],
-  },
-  {
-    key: "customers-list",
-    title: "Customers Export",
-    description: "Company records with type, status, TIN",
-    domain: "Data",
-    filters: ["statuses"],
-    statusOptions: ["pending", "active"],
-    columns: [
-      { key: "name", label: "Name" },
-      { key: "type", label: "Type" },
-      { key: "kind", label: "Kind" },
-      { key: "status", label: "Status" },
-      { key: "tin", label: "TIN" },
-      { key: "approved", label: "Approved" },
-      { key: "created", label: "Created" },
-    ],
-  },
-  {
-    key: "payments-list",
-    title: "Payments Export",
-    description: "Payment transactions with method, status, references",
-    domain: "Data",
-    filters: ["direction", "statuses"],
-    statusOptions: [
-      "action-required",
-      "processing",
-      "success",
-      "failed",
-      "canceled",
-      "refunded",
-    ],
-    columns: [
-      { key: "created", label: "Created" },
-      { key: "method", label: "Method" },
-      { key: "status", label: "Status" },
-      { key: "currency", label: "Currency" },
-      { key: "amount", label: "Amount", unit: "ETB" },
-      { key: "transaction_id", label: "Transaction" },
-      { key: "merchant_order_id", label: "Merchant order" },
-      { key: "paid", label: "Paid" },
-    ],
-  },
-];
-
-export const REPORT_CONFIG_BY_KEY = new Map(
-  REPORT_CONFIGS.map((c) => [c.key, c]),
-);
-
-export const REPORT_DOMAINS: ReportDomain[] = [
-  "Commercial",
-  "Operations",
-  "Finance",
-  "Data",
-];
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 2a1963f8d..8f8068a45 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -174,7 +174,7 @@ import {
 } from "./locomotives.service";
 import { overviewService } from "./overview.service";
 import { reportsService } from "./reports.service";
-import type { ReportQueryInput, ReportResult } from "@/types/reports";
+import type { ReportCatalogEntry, ReportRunParams, ReportRunResult } from "@/types/reports";
 import {
   paymentsService,
   type PaginatedPayments,
@@ -3030,7 +3030,10 @@ export const api = {
   },
 
   reports: {
-    run: endpoint<ReportQueryInput, ReportResult>(
+    catalog: endpoint<void, ReportCatalogEntry[]>("reports", "catalog", () =>
+      reportsService.catalog(),
+    ),
+    run: endpoint<ReportRunParams, ReportRunResult>(
       "reports",
       "run",
       (input) => reportsService.run(input),
diff --git a/apps/edr-freight-web/backoffice/src/services/reports.service.ts b/apps/edr-freight-web/backoffice/src/services/reports.service.ts
index 6f6995614..f04bc8c8f 100644
--- a/apps/edr-freight-web/backoffice/src/services/reports.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/reports.service.ts
@@ -1,14 +1,31 @@
 import { api as client } from "../auth/http";
 import { unwrap } from "@/utils/endpoint";
 import { URL_CONSTANTS } from "@/constants/URLS";
-import type { ReportQueryInput, ReportResult } from "@/types/reports";
+import type { ReportCatalogEntry, ReportRunParams, ReportRunResult } from "@/types/reports";
+
+const R = URL_CONSTANTS.REPORTS;
 
 export const reportsService = {
-  run: async ({ key, ...params }: ReportQueryInput): Promise<ReportResult> => {
-    const response = await client.get<ReportResult>(
-      URL_CONSTANTS.REPORTS.RUN(key),
-      { params },
-    );
+  catalog: async (): Promise<ReportCatalogEntry[]> => {
+    const response = await client.get(R.CATALOG);
     return unwrap(response.data);
   },
+
+  run: async ({ key, ...params }: ReportRunParams): Promise<ReportRunResult> => {
+    const response = await client.get(R.RUN(key), { params });
+    return unwrap(response.data);
+  },
+
+  /** Streams the export file as a blob — caller triggers the browser save. */
+  download: async (
+    key: string,
+    format: "xlsx" | "pdf",
+    params: Omit<ReportRunParams, "key" | "page" | "pageSize">,
+  ): Promise<Blob> => {
+    const response = await client.get(R.EXPORT(key), {
+      params: { ...params, format },
+      responseType: "blob",
+    });
+    return response.data as Blob;
+  },
 };
diff --git a/apps/edr-freight-web/backoffice/src/types/reports.ts b/apps/edr-freight-web/backoffice/src/types/reports.ts
index 72326788c..854b1a801 100644
--- a/apps/edr-freight-web/backoffice/src/types/reports.ts
+++ b/apps/edr-freight-web/backoffice/src/types/reports.ts
@@ -1,27 +1,77 @@
+export type ReportColumnType =
+  | "string"
+  | "number"
+  | "money"
+  | "tons"
+  | "percent"
+  | "date";
+
+export interface ReportColumn {
+  key: string;
+  label: string;
+  type: ReportColumnType;
+  sortable?: boolean;
+}
+
+export type ReportFilterType = "daterange" | "date" | "select" | "multiselect" | "text";
+
+export interface ReportFilterOption {
+  value: string;
+  label: string;
+}
+
+export interface ReportFilterDef {
+  key: string;
+  label: string;
+  type: ReportFilterType;
+  options?: ReportFilterOption[];
+}
+
+export interface ReportIdKey {
+  key: string;
+  label: string;
+}
+
 export interface ReportKpi {
   label: string;
   value: number;
   unit?: string;
 }
 
-export type ReportRow = Record<string, unknown>;
-
-export interface ReportResult {
-  kpis: ReportKpi[];
-  rows: ReportRow[];
-}
-
-/** Query params for GET /reports/:key. List filters are comma-separated. */
-export interface ReportQueryInput {
+/** Mirrors the backend's ReportCatalogEntry — one entry per GET /reports item. */
+export interface ReportCatalogEntry {
   key: string;
-  dateFrom?: string;
-  dateTo?: string;
-  granularity?: "day" | "week" | "month";
-  companyIds?: string;
-  routeIds?: string;
-  yardIds?: string;
-  cargoTypeIds?: string;
-  statuses?: string;
-  direction?: string;
-  freightType?: string;
+  title: string;
+  description: string;
+  group: "Commercial" | "Operations" | "Finance";
+  idKey?: ReportIdKey;
+  filters: ReportFilterDef[];
+  columns: ReportColumn[];
+  defaultSort?: { key: string; dir: "ASC" | "DESC" };
+  hasSummary: boolean;
 }
+
+export interface ReportPageMeta {
+  page: number;
+  pageSize: number;
+  total: number;
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+}
+
+export interface ReportRunResult {
+  columns: ReportColumn[];
+  items: Record<string, unknown>[];
+  meta: ReportPageMeta;
+  kpis: ReportKpi[];
+}
+
+/** Query params for GET /reports/:key — page/sort plus whatever filters the report declares. */
+export type ReportRunParams = Record<string, string | number | undefined> & {
+  key: string;
+  page?: number;
+  pageSize?: number;
+  sortBy?: string;
+  sortOrder?: "ASC" | "DESC";
+};

From 9930bef8aafb09e13e94921c4ee784e5b3c87a94 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 07:54:44 +0000
Subject: [PATCH 065/174] fix(freight-api): quote fallback sort aliases

Sorting by a column with no explicit sortExpr fell back to the bare
select alias unquoted. Postgres folds unquoted identifiers to lowercase,
so any camelCase alias (utilizationPct, bookedTons) 42703'd. Quote the
fallback to match the case TypeORM's addSelect actually emitted.
---
 .../src/modules/reports/report-runner.service.ts    | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/reports/report-runner.service.ts b/apps/edr-freight-api/src/modules/reports/report-runner.service.ts
index 5df9ba2e1..09933de42 100644
--- a/apps/edr-freight-api/src/modules/reports/report-runner.service.ts
+++ b/apps/edr-freight-api/src/modules/reports/report-runner.service.ts
@@ -48,6 +48,15 @@ function coerceParams(
   return params;
 }
 
+/**
+ * Sort expression for a column with no explicit `sortExpr`: the SELECT alias
+ * TypeORM emitted for it, quoted. TypeORM always double-quotes `addSelect`
+ * aliases in the generated SQL (preserving case) — ordering by the bare,
+ * unquoted key instead lets Postgres fold it to lowercase and 42703 on any
+ * camelCase alias (e.g. "utilizationPct" -> unquoted "utilizationpct").
+ */
+const aliasSortExpr = (key: string): string => `"${key.replace(/"/g, '""')}"`;
+
 /** Resolve a client-requested sort column against the report's own whitelist. */
 function resolveSort(
   def: ReportDefinition,
@@ -57,14 +66,14 @@ function resolveSort(
   const dir = sortOrder?.toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
   const requested = sortBy && def.columns.find((c) => c.key === sortBy && c.sortable);
   if (requested) {
-    return { key: requested.key, expr: requested.sortExpr ?? requested.key, dir };
+    return { key: requested.key, expr: requested.sortExpr ?? aliasSortExpr(requested.key), dir };
   }
   if (!def.defaultSort) return null;
   const fallback = def.columns.find((c) => c.key === def.defaultSort!.key);
   if (!fallback) return null;
   return {
     key: fallback.key,
-    expr: fallback.sortExpr ?? fallback.key,
+    expr: fallback.sortExpr ?? aliasSortExpr(fallback.key),
     dir: def.defaultSort.dir,
   };
 }

From c0cdf805601b1adc33e0b43baa1c2e791a361867 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 08:08:13 +0000
Subject: [PATCH 066/174] feat(freight-api): add 4 fleet-ops reports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

wagon-fleet-status, wagon-status-duration, wagon-requests,
locomotive-fleet-status. First batch off the ITLMS dashboard spec —
fleet data (wagons/locomotives/transfer-requests) needed no schema
work, just resolvers. No frontend changes: catalog is server-driven.
---
 .../locomotive-fleet-status.report.ts         | 67 +++++++++++++
 .../definitions/wagon-fleet-status.report.ts  | 76 +++++++++++++++
 .../definitions/wagon-requests.report.ts      | 85 +++++++++++++++++
 .../wagon-status-duration.report.ts           | 94 +++++++++++++++++++
 .../src/modules/reports/report.registry.ts    |  8 ++
 .../src/seed/freight-permissions.registry.ts  |  4 +
 6 files changed, 334 insertions(+)
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/locomotive-fleet-status.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/wagon-fleet-status.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/wagon-requests.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/wagon-status-duration.report.ts

diff --git a/apps/edr-freight-api/src/modules/reports/definitions/locomotive-fleet-status.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/locomotive-fleet-status.report.ts
new file mode 100644
index 000000000..f2b9377f6
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/locomotive-fleet-status.report.ts
@@ -0,0 +1,67 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { Locomotive, LOCOMOTIVE_STATUSES } from '../../locomotives/entities/locomotive.entity';
+import { Yard } from '../../rule-engine/entities/yard.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+const STATUS_OPTIONS = LOCOMOTIVE_STATUSES.map((v) => ({ value: v, label: v.replace(/_/g, ' ') }));
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Locomotive, 'l')
+    .leftJoin(Yard, 'y', 'y.id = l.current_yard_id')
+    .where('l.deleted_at IS NULL');
+
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('l.status IN (:...statuses)', { statuses });
+  return qb;
+}
+
+export const locomotiveFleetStatusReport: ReportDefinition = {
+  key: 'locomotive-fleet-status',
+  title: 'Locomotive Fleet Status',
+  description: 'Locomotive counts by type, station and status',
+  group: 'Operations',
+  filters: [{ key: 'statuses', label: 'Status', type: 'multiselect', options: STATUS_OPTIONS }],
+  columns: [
+    { key: 'locomotiveType', label: 'Type', type: 'string', sortable: true },
+    { key: 'station', label: 'Station', type: 'string', sortable: true },
+    { key: 'status', label: 'Status', type: 'string', sortable: true },
+    { key: 'count', label: 'Count', type: 'number', sortable: true },
+  ],
+  defaultSort: { key: 'count', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('l.locomotive_type', 'locomotiveType')
+      .addSelect("COALESCE(y.label, 'Unassigned')", 'station')
+      .addSelect('l.status', 'status')
+      .addSelect('COUNT(*)::int', 'count')
+      .groupBy('l.locomotive_type')
+      .addGroupBy('y.label')
+      .addGroupBy('l.status');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'total')
+      .addSelect('COUNT(*) FILTER (WHERE l.status = :available)::int', 'available')
+      .addSelect('COUNT(*) FILTER (WHERE l.status = :assigned)::int', 'assigned')
+      .addSelect('COUNT(*) FILTER (WHERE l.status = :maintenance)::int', 'maintenance')
+      .addSelect('COUNT(*) FILTER (WHERE l.status = :outOfService)::int', 'outOfService')
+      .setParameters({
+        available: 'AVAILABLE',
+        assigned: 'ASSIGNED',
+        maintenance: 'MAINTENANCE',
+        outOfService: 'OUT_OF_SERVICE',
+      })
+      .getRawOne();
+    return [
+      { label: 'Total locomotives', value: Number(row?.total ?? 0) },
+      { label: 'Available', value: Number(row?.available ?? 0) },
+      { label: 'Assigned', value: Number(row?.assigned ?? 0) },
+      { label: 'Under maintenance', value: Number(row?.maintenance ?? 0) },
+      { label: 'Out of service', value: Number(row?.outOfService ?? 0) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/wagon-fleet-status.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/wagon-fleet-status.report.ts
new file mode 100644
index 000000000..1371936f5
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/wagon-fleet-status.report.ts
@@ -0,0 +1,76 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { WagonStatus } from '@edr/types';
+import { Wagon } from '../../wagons/entities/wagon.entity';
+import { WagonType } from '../../wagon-types/entities/wagon-type.entity';
+import { Yard } from '../../rule-engine/entities/yard.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+const STATUS_OPTIONS = Object.values(WagonStatus).map((v) => ({
+  value: v,
+  label: v.replace(/_/g, ' '),
+}));
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Wagon, 'w')
+    .leftJoin(WagonType, 'wt', 'wt.id = w.wagon_type_id')
+    .leftJoin(Yard, 'y', 'y.id = w.current_yard_id')
+    .where('w.deleted_at IS NULL');
+
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('w.status IN (:...statuses)', { statuses });
+  return qb;
+}
+
+export const wagonFleetStatusReport: ReportDefinition = {
+  key: 'wagon-fleet-status',
+  title: 'Wagon Fleet Status',
+  description: 'Wagon counts by type, station and status',
+  group: 'Operations',
+  filters: [{ key: 'statuses', label: 'Status', type: 'multiselect', options: STATUS_OPTIONS }],
+  columns: [
+    { key: 'wagonType', label: 'Wagon type', type: 'string', sortable: true },
+    { key: 'station', label: 'Station', type: 'string', sortable: true },
+    { key: 'status', label: 'Status', type: 'string', sortable: true },
+    { key: 'count', label: 'Count', type: 'number', sortable: true },
+  ],
+  defaultSort: { key: 'count', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('COALESCE(wt.name, \'Unknown\')', 'wagonType')
+      .addSelect("COALESCE(y.label, 'Unassigned')", 'station')
+      .addSelect('w.status', 'status')
+      .addSelect('COUNT(*)::int', 'count')
+      .groupBy('wt.name')
+      .addGroupBy('y.label')
+      .addGroupBy('w.status');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'total')
+      .addSelect('COUNT(*) FILTER (WHERE w.status = :available)::int', 'available')
+      .addSelect('COUNT(*) FILTER (WHERE w.status = :assigned)::int', 'assigned')
+      .addSelect('COUNT(*) FILTER (WHERE w.status = :maintenance)::int', 'maintenance')
+      .addSelect('COUNT(*) FILTER (WHERE w.status = :detained)::int', 'detained')
+      .addSelect('COUNT(*) FILTER (WHERE w.status = :outOfService)::int', 'outOfService')
+      .setParameters({
+        available: WagonStatus.Available,
+        assigned: WagonStatus.Assigned,
+        maintenance: WagonStatus.Maintenance,
+        detained: WagonStatus.Detained,
+        outOfService: WagonStatus.OutOfService,
+      })
+      .getRawOne();
+    return [
+      { label: 'Total wagons', value: Number(row?.total ?? 0) },
+      { label: 'Available', value: Number(row?.available ?? 0) },
+      { label: 'Assigned', value: Number(row?.assigned ?? 0) },
+      { label: 'Under maintenance', value: Number(row?.maintenance ?? 0) },
+      { label: 'Detained', value: Number(row?.detained ?? 0) },
+      { label: 'Out of service', value: Number(row?.outOfService ?? 0) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/wagon-requests.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/wagon-requests.report.ts
new file mode 100644
index 000000000..df5ac364c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/wagon-requests.report.ts
@@ -0,0 +1,85 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { WagonTransferRequestStatus } from '@edr/types';
+import { WagonTransferRequest } from '../../wagons/entities/wagon-transfer-request.entity';
+import { WagonType } from '../../wagon-types/entities/wagon-type.entity';
+import { Yard } from '../../rule-engine/entities/yard.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+const STATUS_OPTIONS = Object.values(WagonTransferRequestStatus).map((v) => ({
+  value: v,
+  label: v.replace(/_/g, ' '),
+}));
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(WagonTransferRequest, 'r')
+    .leftJoin(Yard, 'fy', 'fy.id = r.from_yard_id')
+    .leftJoin(Yard, 'ty', 'ty.id = r.to_yard_id')
+    .leftJoin(WagonType, 'wt', 'wt.id = r.wagon_type_id')
+    .where('r.deleted_at IS NULL');
+
+  if (params.dateFrom) qb.andWhere('r.created_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('r.created_at < :dateTo', { dateTo: params.dateTo });
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('r.status IN (:...statuses)', { statuses });
+  return qb;
+}
+
+export const wagonRequestsReport: ReportDefinition = {
+  key: 'wagon-requests',
+  title: 'Wagon Requests',
+  description: 'Inter-yard wagon transfer requests and fulfilment delay',
+  group: 'Operations',
+  filters: [
+    { key: 'date', label: 'Requested', type: 'daterange' },
+    { key: 'statuses', label: 'Status', type: 'multiselect', options: STATUS_OPTIONS },
+  ],
+  columns: [
+    { key: 'fromYard', label: 'From', type: 'string', sortable: true, sortExpr: 'fy.label' },
+    { key: 'toYard', label: 'To', type: 'string', sortable: true, sortExpr: 'ty.label' },
+    { key: 'wagonType', label: 'Wagon type', type: 'string' },
+    { key: 'quantity', label: 'Requested', type: 'number' },
+    { key: 'fulfilledQuantity', label: 'Fulfilled', type: 'number' },
+    { key: 'status', label: 'Status', type: 'string', sortable: true, sortExpr: 'r.status' },
+    { key: 'requestedAt', label: 'Requested at', type: 'date', sortable: true, sortExpr: 'r.created_at' },
+    { key: 'fulfilledAt', label: 'Fulfilled at', type: 'date' },
+    { key: 'delayDays', label: 'Delay (days)', type: 'number', sortable: true },
+  ],
+  defaultSort: { key: 'requestedAt', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('fy.label', 'fromYard')
+      .addSelect('ty.label', 'toYard')
+      .addSelect("COALESCE(wt.name, 'Unknown')", 'wagonType')
+      .addSelect('r.quantity', 'quantity')
+      .addSelect('r.fulfilled_quantity', 'fulfilledQuantity')
+      .addSelect('r.status', 'status')
+      .addSelect(`to_char(r.created_at, 'YYYY-MM-DD')`, 'requestedAt')
+      .addSelect(`to_char(r.fulfilled_at, 'YYYY-MM-DD')`, 'fulfilledAt')
+      .addSelect(
+        `ROUND(EXTRACT(EPOCH FROM (COALESCE(r.fulfilled_at, now()) - r.created_at))::numeric / 86400, 1)::float8`,
+        'delayDays',
+      );
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'requests')
+      .addSelect('COUNT(*) FILTER (WHERE r.status IN (:...openStatuses))::int', 'open')
+      .addSelect(
+        `ROUND(AVG(EXTRACT(EPOCH FROM (COALESCE(r.fulfilled_at, now()) - r.created_at))::numeric / 86400), 1)::float8`,
+        'avgDelayDays',
+      )
+      .setParameters({
+        openStatuses: [WagonTransferRequestStatus.Pending, WagonTransferRequestStatus.PartiallyFulfilled],
+      })
+      .getRawOne();
+    return [
+      { label: 'Requests', value: Number(row?.requests ?? 0) },
+      { label: 'Still open', value: Number(row?.open ?? 0) },
+      { label: 'Avg delay', value: Number(row?.avgDelayDays ?? 0), unit: 'd' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/wagon-status-duration.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/wagon-status-duration.report.ts
new file mode 100644
index 000000000..348f681d1
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/wagon-status-duration.report.ts
@@ -0,0 +1,94 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { WagonStatus } from '@edr/types';
+import { Wagon } from '../../wagons/entities/wagon.entity';
+import { WagonType } from '../../wagon-types/entities/wagon-type.entity';
+import { Yard } from '../../rule-engine/entities/yard.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+// Only these two statuses have an operational "how long has it been stuck
+// here" question — everything else (Available, Assigned, ...) turns over too
+// fast for a days-in-status view to matter.
+const TRACKED_STATUSES = [WagonStatus.Maintenance, WagonStatus.Detained];
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Wagon, 'w')
+    .leftJoin(WagonType, 'wt', 'wt.id = w.wagon_type_id')
+    .leftJoin(Yard, 'y', 'y.id = w.current_yard_id')
+    // Latest time each wagon flipped INTO its current status, per (wagon, status)
+    // pair — a plain (non-correlated) derived table, joined on both columns, so
+    // it stays a normal JOIN rather than needing a LATERAL correlated subquery.
+    .leftJoin(
+      (sub) =>
+        sub
+          .select('l.wagon_id', 'wagon_id')
+          .addSelect('l.to_status', 'to_status')
+          .addSelect('MAX(l.created_at)', 'since')
+          .from('freight.wagon_status_logs', 'l')
+          .groupBy('l.wagon_id')
+          .addGroupBy('l.to_status'),
+      'log',
+      'log.wagon_id = w.id AND log.to_status = w.status',
+    )
+    .where('w.deleted_at IS NULL')
+    .andWhere('w.status IN (:...trackedStatuses)', { trackedStatuses: TRACKED_STATUSES });
+
+  const status = params.status as string | null;
+  if (status) qb.andWhere('w.status = :status', { status });
+  return qb;
+}
+
+export const wagonStatusDurationReport: ReportDefinition = {
+  key: 'wagon-status-duration',
+  title: 'Wagon Status Duration',
+  description: 'How long each wagon has sat in Maintenance or Detained',
+  group: 'Operations',
+  filters: [
+    {
+      key: 'status',
+      label: 'Status',
+      type: 'select',
+      options: TRACKED_STATUSES.map((v) => ({ value: v, label: v.replace(/_/g, ' ') })),
+    },
+  ],
+  columns: [
+    { key: 'wagonNumber', label: 'Wagon', type: 'string', sortable: true, sortExpr: 'w.wagon_number' },
+    { key: 'wagonType', label: 'Wagon type', type: 'string' },
+    { key: 'station', label: 'Station', type: 'string' },
+    { key: 'status', label: 'Status', type: 'string', sortable: true, sortExpr: 'w.status' },
+    { key: 'since', label: 'Since', type: 'date', sortable: true },
+    { key: 'daysInStatus', label: 'Days in status', type: 'number', sortable: true },
+  ],
+  defaultSort: { key: 'daysInStatus', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('w.wagon_number', 'wagonNumber')
+      .addSelect("COALESCE(wt.name, 'Unknown')", 'wagonType')
+      .addSelect("COALESCE(y.label, 'Unassigned')", 'station')
+      .addSelect('w.status', 'status')
+      .addSelect(`to_char(COALESCE(log.since, w.updated_at), 'YYYY-MM-DD')`, 'since')
+      .addSelect(
+        `FLOOR(EXTRACT(EPOCH FROM (now() - COALESCE(log.since, w.updated_at))) / 86400)::int`,
+        'daysInStatus',
+      );
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*) FILTER (WHERE w.status = :maintenance)::int', 'maintenance')
+      .addSelect('COUNT(*) FILTER (WHERE w.status = :detained)::int', 'detained')
+      .addSelect(
+        `MAX(FLOOR(EXTRACT(EPOCH FROM (now() - COALESCE(log.since, w.updated_at))) / 86400))::int`,
+        'longest',
+      )
+      .setParameters({ maintenance: WagonStatus.Maintenance, detained: WagonStatus.Detained })
+      .getRawOne();
+    return [
+      { label: 'Under maintenance', value: Number(row?.maintenance ?? 0) },
+      { label: 'Detained', value: Number(row?.detained ?? 0) },
+      { label: 'Longest days in status', value: Number(row?.longest ?? 0), unit: 'd' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/report.registry.ts b/apps/edr-freight-api/src/modules/reports/report.registry.ts
index 26474d025..dfc6ff002 100644
--- a/apps/edr-freight-api/src/modules/reports/report.registry.ts
+++ b/apps/edr-freight-api/src/modules/reports/report.registry.ts
@@ -3,6 +3,10 @@ import { bookingsListReport } from './definitions/bookings-list.report';
 import { revenueByCustomerReport } from './definitions/revenue-by-customer.report';
 import { agingReceivablesReport } from './definitions/aging-receivables.report';
 import { contractUtilizationReport } from './definitions/contract-utilization.report';
+import { wagonFleetStatusReport } from './definitions/wagon-fleet-status.report';
+import { wagonStatusDurationReport } from './definitions/wagon-status-duration.report';
+import { wagonRequestsReport } from './definitions/wagon-requests.report';
+import { locomotiveFleetStatusReport } from './definitions/locomotive-fleet-status.report';
 import { ReportDefinition } from './report.types';
 
 /**
@@ -15,6 +19,10 @@ export const REPORTS: ReportDefinition[] = [
   revenueByCustomerReport,
   agingReceivablesReport,
   contractUtilizationReport,
+  wagonFleetStatusReport,
+  wagonStatusDurationReport,
+  wagonRequestsReport,
+  locomotiveFleetStatusReport,
 ];
 
 const BY_KEY = new Map<ReportKey, ReportDefinition>(REPORTS.map((r) => [r.key, r]));
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 7470ed2b5..f9a0f959f 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -59,6 +59,10 @@ export const REPORT_KEYS = [
   "revenue-by-customer",
   "aging-receivables",
   "contract-utilization",
+  "wagon-fleet-status",
+  "wagon-status-duration",
+  "wagon-requests",
+  "locomotive-fleet-status",
 ] as const;
 
 export type ReportKey = (typeof REPORT_KEYS)[number];

From a53a9c71523b443961ef51f823087fc489166710 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 08:14:17 +0000
Subject: [PATCH 067/174] feat(freight-api): add 6 booking/train-lifecycle
 reports

booking-status-breakdown (dedupes the same 'status per port/train/
cargo/contract' ask across 4 dashboards), train-schedule-status,
train-turnaround, wagon-teu-utilization, loaded-capacity,
global-logistics-wagons.

Dropped freight-weight-variance from this batch: the schema has no
'charged weight' distinct from VGM/actual, so a charged-vs-actual
variance report isn't buildable without a product decision on what
'charged' means here.
---
 .../booking-status-breakdown.report.ts        | 108 ++++++++++++++++++
 .../global-logistics-wagons.report.ts         |  68 +++++++++++
 .../definitions/loaded-capacity.report.ts     |  78 +++++++++++++
 .../train-schedule-status.report.ts           | 100 ++++++++++++++++
 .../definitions/train-turnaround.report.ts    |  86 ++++++++++++++
 .../wagon-teu-utilization.report.ts           |  76 ++++++++++++
 .../src/modules/reports/report.registry.ts    |  12 ++
 .../src/seed/freight-permissions.registry.ts  |   6 +
 8 files changed, 534 insertions(+)
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/booking-status-breakdown.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/global-logistics-wagons.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/loaded-capacity.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/train-schedule-status.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/train-turnaround.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/wagon-teu-utilization.report.ts

diff --git a/apps/edr-freight-api/src/modules/reports/definitions/booking-status-breakdown.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/booking-status-breakdown.report.ts
new file mode 100644
index 000000000..a01f714ec
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/booking-status-breakdown.report.ts
@@ -0,0 +1,108 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { BookingStatus } from '@edr/types';
+import { Booking } from '../../bookings/entities/booking.entity';
+import { Yard } from '../../rule-engine/entities/yard.entity';
+import { CargoType } from '../../rule-engine/entities/cargo-type.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+// One resolver behind "Booking per status, per port/train/date/cargo/contract
+// type" — the same breakdown Operation, Marketing, Global Logistics and the
+// Operation Report each ask for verbatim. Embed once, reuse everywhere.
+const TONS = 'COALESCE(b.bulk_total_weight_tons, b.cargo_total_weight_vgm)';
+const REVENUE = 'COALESCE(b.adjusted_total_amount, b.total_amount)';
+
+const STATUS_OPTIONS = [...new Set(Object.values(BookingStatus))].map((v) => ({
+  value: v,
+  label: v.replace(/_/g, ' '),
+}));
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params, directions } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Booking, 'b')
+    .leftJoin(Yard, 'o', 'o.id = b.origin_yard_id')
+    .leftJoin(CargoType, 'cty', 'cty.id = b.cargo_type_id')
+    .where('b.deleted_at IS NULL');
+
+  if (params.dateFrom) qb.andWhere('b.created_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('b.created_at < :dateTo', { dateTo: params.dateTo });
+  if (params.direction) qb.andWhere('b.trade_direction = :direction', { direction: params.direction });
+  if (params.freightType) qb.andWhere('b.freight_type = :freightType', { freightType: params.freightType });
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('b.status IN (:...statuses)', { statuses });
+  if (directions !== null) {
+    qb.andWhere(directions.length ? 'b.trade_direction IN (:...directions)' : '1 = 0', { directions });
+  }
+  return qb;
+}
+
+export const bookingStatusBreakdownReport: ReportDefinition = {
+  key: 'booking-status-breakdown',
+  title: 'Bookings by Status',
+  description: 'Booking counts by status, direction, origin station, cargo and contract type',
+  group: 'Commercial',
+  filters: [
+    { key: 'date', label: 'Created', type: 'daterange' },
+    {
+      key: 'direction',
+      label: 'Direction',
+      type: 'select',
+      options: [
+        { value: 'IMPORT', label: 'Import' },
+        { value: 'EXPORT', label: 'Export' },
+        { value: 'DOMESTIC', label: 'Domestic' },
+      ],
+    },
+    {
+      key: 'freightType',
+      label: 'Freight type',
+      type: 'select',
+      options: [
+        { value: 'CONTAINER', label: 'Container' },
+        { value: 'BULK', label: 'Bulk' },
+      ],
+    },
+    { key: 'statuses', label: 'Status', type: 'multiselect', options: STATUS_OPTIONS },
+  ],
+  columns: [
+    { key: 'status', label: 'Status', type: 'string', sortable: true, sortExpr: 'b.status' },
+    { key: 'direction', label: 'Direction', type: 'string', sortable: true, sortExpr: 'b.trade_direction' },
+    { key: 'originStation', label: 'Origin', type: 'string', sortable: true },
+    { key: 'cargoType', label: 'Cargo type', type: 'string', sortable: true },
+    { key: 'contractKind', label: 'Contract type', type: 'string', sortable: true },
+    { key: 'bookings', label: 'Bookings', type: 'number', sortable: true },
+    { key: 'tons', label: 'Tonnage', type: 'tons', sortable: true },
+    { key: 'amount', label: 'Amount', type: 'money', sortable: true },
+  ],
+  defaultSort: { key: 'bookings', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('b.status', 'status')
+      .addSelect('b.trade_direction', 'direction')
+      .addSelect("COALESCE(o.label, 'Unknown')", 'originStation')
+      .addSelect("COALESCE(cty.cargo_type_name, 'Other')", 'cargoType')
+      .addSelect("COALESCE(b.contract_kind, 'SPOT')", 'contractKind')
+      .addSelect('COUNT(*)::int', 'bookings')
+      .addSelect(`ROUND(COALESCE(SUM(${TONS}), 0))::float8`, 'tons')
+      .addSelect(`ROUND(COALESCE(SUM(${REVENUE}), 0))::float8`, 'amount')
+      .groupBy('b.status')
+      .addGroupBy('b.trade_direction')
+      .addGroupBy('o.label')
+      .addGroupBy('cty.cargo_type_name')
+      .addGroupBy('b.contract_kind');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'bookings')
+      .addSelect(`ROUND(COALESCE(SUM(${TONS}), 0))::float8`, 'tons')
+      .addSelect(`ROUND(COALESCE(SUM(${REVENUE}), 0))::float8`, 'amount')
+      .getRawOne();
+    return [
+      { label: 'Bookings', value: Number(row?.bookings ?? 0) },
+      { label: 'Tonnage', value: Number(row?.tons ?? 0), unit: 't' },
+      { label: 'Amount', value: Number(row?.amount ?? 0), unit: 'ETB' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/global-logistics-wagons.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/global-logistics-wagons.report.ts
new file mode 100644
index 000000000..e23ce5469
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/global-logistics-wagons.report.ts
@@ -0,0 +1,68 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { ScheduleWagonAdjustmentLog } from '../../train-schedules/entities/schedule-wagon-adjustment-log.entity';
+import { TrainSchedule } from '../../train-schedules/entities/train-schedule.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+// ADD = allocated, REMOVE = cancelled. SWITCH (a physical wagon swap, net
+// count unchanged) is excluded — it's neither an allocation nor a cancellation.
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(ScheduleWagonAdjustmentLog, 'l')
+    .leftJoin(TrainSchedule, 'ts', 'ts.id = l.train_schedule_id')
+    .where('l.deleted_at IS NULL')
+    .andWhere("l.action IN ('ADD', 'REMOVE')");
+
+  if (params.dateFrom) qb.andWhere('l.occurred_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('l.occurred_at < :dateTo', { dateTo: params.dateTo });
+  if (params.direction) qb.andWhere('ts.direction = :direction', { direction: params.direction });
+  return qb;
+}
+
+export const globalLogisticsWagonsReport: ReportDefinition = {
+  key: 'global-logistics-wagons',
+  title: 'Wagon Allocations by Day',
+  description: 'Wagons allocated vs. cancelled per day, by direction',
+  group: 'Operations',
+  filters: [
+    { key: 'date', label: 'Date', type: 'daterange' },
+    {
+      key: 'direction',
+      label: 'Direction',
+      type: 'select',
+      options: [
+        { value: 'IMPORT', label: 'Import' },
+        { value: 'EXPORT', label: 'Export' },
+        { value: 'DOMESTIC', label: 'Domestic' },
+      ],
+    },
+  ],
+  columns: [
+    { key: 'date', label: 'Date', type: 'date', sortable: true, sortExpr: `date_trunc('day', l.occurred_at)` },
+    { key: 'direction', label: 'Direction', type: 'string', sortable: true },
+    { key: 'allocated', label: 'Allocated', type: 'number', sortable: true },
+    { key: 'cancelled', label: 'Cancelled', type: 'number', sortable: true },
+  ],
+  defaultSort: { key: 'date', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select(`to_char(date_trunc('day', l.occurred_at), 'YYYY-MM-DD')`, 'date')
+      .addSelect("COALESCE(ts.direction, 'Unknown')", 'direction')
+      .addSelect("COUNT(*) FILTER (WHERE l.action = 'ADD')::int", 'allocated')
+      .addSelect("COUNT(*) FILTER (WHERE l.action = 'REMOVE')::int", 'cancelled')
+      .groupBy(`date_trunc('day', l.occurred_at)`)
+      .addGroupBy('ts.direction');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select("COUNT(*) FILTER (WHERE l.action = 'ADD')::int", 'allocated')
+      .addSelect("COUNT(*) FILTER (WHERE l.action = 'REMOVE')::int", 'cancelled')
+      .getRawOne();
+    return [
+      { label: 'Allocated', value: Number(row?.allocated ?? 0) },
+      { label: 'Cancelled', value: Number(row?.cancelled ?? 0) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/loaded-capacity.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/loaded-capacity.report.ts
new file mode 100644
index 000000000..8827b77b8
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/loaded-capacity.report.ts
@@ -0,0 +1,78 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { TrainSetWagon } from '../../train-sets/entities/train-set-wagon.entity';
+import { TrainSchedule } from '../../train-schedules/entities/train-schedule.entity';
+import { WagonType } from '../../wagon-types/entities/wagon-type.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+// train_set_wagons.assigned_weight_tons is the planned load per slot, already
+// maintained by the wagon-allocation flow — no need to re-derive it from
+// bulk/container line items.
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(TrainSetWagon, 'tsw')
+    .innerJoin(TrainSchedule, 'ts', 'ts.train_set_id = tsw.train_set_id')
+    .leftJoin(WagonType, 'wt', 'wt.id = tsw.wagon_type_id')
+    .where('tsw.deleted_at IS NULL AND ts.deleted_at IS NULL');
+
+  if (params.trainNumber) {
+    qb.andWhere('ts.train_number ILIKE :trainNumber', { trainNumber: `%${params.trainNumber}%` });
+  }
+  if (params.dateFrom) {
+    qb.andWhere('ts.scheduled_departure_date >= :dateFrom', { dateFrom: params.dateFrom });
+  }
+  if (params.dateTo) qb.andWhere('ts.scheduled_departure_date < :dateTo', { dateTo: params.dateTo });
+  return qb;
+}
+
+export const loadedCapacityReport: ReportDefinition = {
+  key: 'loaded-capacity',
+  title: 'Loaded Capacity',
+  description: 'Nameplate vs. loaded capacity per train, by wagon type',
+  group: 'Operations',
+  filters: [
+    { key: 'trainNumber', label: 'Train No.', type: 'text' },
+    { key: 'date', label: 'Departure', type: 'daterange' },
+  ],
+  columns: [
+    { key: 'trainNumber', label: 'Train No.', type: 'string', sortable: true, sortExpr: 'ts.train_number' },
+    { key: 'departureDate', label: 'Departure', type: 'date' },
+    { key: 'wagonType', label: 'Wagon type', type: 'string', sortable: true },
+    { key: 'wagons', label: 'Wagons', type: 'number', sortable: true },
+    { key: 'capacityTons', label: 'Capacity', type: 'tons', sortable: true },
+    { key: 'loadedTons', label: 'Loaded', type: 'tons', sortable: true },
+    { key: 'utilizationPct', label: 'Utilization', type: 'percent', sortable: true },
+  ],
+  defaultSort: { key: 'loadedTons', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('ts.train_number', 'trainNumber')
+      .addSelect(`to_char(ts.scheduled_departure_date, 'YYYY-MM-DD')`, 'departureDate')
+      .addSelect("COALESCE(wt.name, 'Unknown')", 'wagonType')
+      .addSelect('COUNT(*)::int', 'wagons')
+      .addSelect('COALESCE(SUM(tsw.capacity_tons), 0)::float8', 'capacityTons')
+      .addSelect('COALESCE(SUM(tsw.assigned_weight_tons), 0)::float8', 'loadedTons')
+      .addSelect(
+        `CASE WHEN COALESCE(SUM(tsw.capacity_tons), 0) > 0
+              THEN ROUND(SUM(tsw.assigned_weight_tons) / SUM(tsw.capacity_tons) * 100)::float8 END`,
+        'utilizationPct',
+      )
+      .groupBy('ts.train_number')
+      .addGroupBy('ts.scheduled_departure_date')
+      .addGroupBy('wt.name');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'wagons')
+      .addSelect('COALESCE(SUM(tsw.capacity_tons), 0)::float8', 'capacityTons')
+      .addSelect('COALESCE(SUM(tsw.assigned_weight_tons), 0)::float8', 'loadedTons')
+      .getRawOne();
+    return [
+      { label: 'Wagons', value: Number(row?.wagons ?? 0) },
+      { label: 'Capacity', value: Number(row?.capacityTons ?? 0), unit: 't' },
+      { label: 'Loaded', value: Number(row?.loadedTons ?? 0), unit: 't' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/train-schedule-status.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/train-schedule-status.report.ts
new file mode 100644
index 000000000..88a25d890
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/train-schedule-status.report.ts
@@ -0,0 +1,100 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { TrainSchedule, TRAIN_SCHEDULE_STATUSES } from '../../train-schedules/entities/train-schedule.entity';
+import { Yard } from '../../rule-engine/entities/yard.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+// ITLMS's spec lists Scheduled/Dispatched/In Transit/Arrived/Cancelled as the
+// train lifecycle. The platform tracks DRAFT/SCHEDULED/DISPATCHED/ARRIVED/
+// CANCELLED — no separate "in transit" status exists (a dispatched schedule
+// with no actual_arrival_at yet *is* in transit; reported as DISPATCHED).
+const STATUS_OPTIONS = TRAIN_SCHEDULE_STATUSES.map((v) => ({ value: v, label: v }));
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(TrainSchedule, 'ts')
+    .leftJoin(Yard, 'o', 'o.id = ts.origin_station_id')
+    .leftJoin(Yard, 'd', 'd.id = ts.destination_station_id')
+    .where('ts.deleted_at IS NULL');
+
+  if (params.dateFrom) {
+    qb.andWhere('ts.scheduled_departure_date >= :dateFrom', { dateFrom: params.dateFrom });
+  }
+  if (params.dateTo) {
+    qb.andWhere('ts.scheduled_departure_date < :dateTo', { dateTo: params.dateTo });
+  }
+  if (params.direction) qb.andWhere('ts.direction = :direction', { direction: params.direction });
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('ts.status IN (:...statuses)', { statuses });
+  return qb;
+}
+
+export const trainScheduleStatusReport: ReportDefinition = {
+  key: 'train-schedule-status',
+  title: 'Train Schedules',
+  description: 'Scheduled, dispatched, arrived and cancelled train departures',
+  group: 'Operations',
+  filters: [
+    { key: 'date', label: 'Departure', type: 'daterange' },
+    {
+      key: 'direction',
+      label: 'Direction',
+      type: 'select',
+      options: [
+        { value: 'IMPORT', label: 'Import' },
+        { value: 'EXPORT', label: 'Export' },
+        { value: 'DOMESTIC', label: 'Domestic' },
+      ],
+    },
+    { key: 'statuses', label: 'Status', type: 'multiselect', options: STATUS_OPTIONS },
+  ],
+  columns: [
+    { key: 'trainNumber', label: 'Train No.', type: 'string', sortable: true, sortExpr: 'ts.train_number' },
+    { key: 'reference', label: 'Reference', type: 'string' },
+    { key: 'status', label: 'Status', type: 'string', sortable: true, sortExpr: 'ts.status' },
+    { key: 'direction', label: 'Direction', type: 'string' },
+    { key: 'origin', label: 'Origin', type: 'string' },
+    { key: 'destination', label: 'Destination', type: 'string' },
+    {
+      key: 'scheduledDeparture',
+      label: 'Scheduled dep.',
+      type: 'date',
+      sortable: true,
+      sortExpr: 'ts.scheduled_departure_date',
+    },
+    { key: 'actualDeparture', label: 'Actual dep.', type: 'date' },
+    { key: 'actualArrival', label: 'Actual arr.', type: 'date' },
+  ],
+  defaultSort: { key: 'scheduledDeparture', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('ts.train_number', 'trainNumber')
+      .addSelect('ts.reference', 'reference')
+      .addSelect('ts.status', 'status')
+      .addSelect('ts.direction', 'direction')
+      .addSelect("COALESCE(o.label, 'Unknown')", 'origin')
+      .addSelect("COALESCE(d.label, 'Unknown')", 'destination')
+      .addSelect(`to_char(ts.scheduled_departure_date, 'YYYY-MM-DD')`, 'scheduledDeparture')
+      .addSelect(`to_char(ts.actual_departure_at, 'YYYY-MM-DD HH24:MI')`, 'actualDeparture')
+      .addSelect(`to_char(ts.actual_arrival_at, 'YYYY-MM-DD HH24:MI')`, 'actualArrival');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'total')
+      .addSelect('COUNT(*) FILTER (WHERE ts.status = :scheduled)::int', 'scheduled')
+      .addSelect('COUNT(*) FILTER (WHERE ts.status = :dispatched)::int', 'dispatched')
+      .addSelect('COUNT(*) FILTER (WHERE ts.status = :arrived)::int', 'arrived')
+      .addSelect('COUNT(*) FILTER (WHERE ts.status = :cancelled)::int', 'cancelled')
+      .setParameters({ scheduled: 'SCHEDULED', dispatched: 'DISPATCHED', arrived: 'ARRIVED', cancelled: 'CANCELLED' })
+      .getRawOne();
+    return [
+      { label: 'Total', value: Number(row?.total ?? 0) },
+      { label: 'Scheduled', value: Number(row?.scheduled ?? 0) },
+      { label: 'Dispatched', value: Number(row?.dispatched ?? 0) },
+      { label: 'Arrived', value: Number(row?.arrived ?? 0) },
+      { label: 'Cancelled', value: Number(row?.cancelled ?? 0) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/train-turnaround.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/train-turnaround.report.ts
new file mode 100644
index 000000000..7dc7b8c3c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/train-turnaround.report.ts
@@ -0,0 +1,86 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { TrainSchedule } from '../../train-schedules/entities/train-schedule.entity';
+import { Yard } from '../../rule-engine/entities/yard.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+// "Turnaround" here is departure-to-arrival transit time on the actual (not
+// scheduled) timestamps. Station dwell time (arrival -> the SAME train's next
+// departure) would need pairing consecutive schedules by physical train,
+// which isn't tracked directly — deferred, not modeled as a shortcut.
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(TrainSchedule, 'ts')
+    .leftJoin(Yard, 'o', 'o.id = ts.origin_station_id')
+    .leftJoin(Yard, 'd', 'd.id = ts.destination_station_id')
+    .where('ts.deleted_at IS NULL')
+    .andWhere('ts.actual_departure_at IS NOT NULL')
+    .andWhere('ts.actual_arrival_at IS NOT NULL');
+
+  if (params.dateFrom) qb.andWhere('ts.actual_departure_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('ts.actual_departure_at < :dateTo', { dateTo: params.dateTo });
+  if (params.direction) qb.andWhere('ts.direction = :direction', { direction: params.direction });
+  return qb;
+}
+
+export const trainTurnaroundReport: ReportDefinition = {
+  key: 'train-turnaround',
+  title: 'Train Turnaround',
+  description: 'Actual departure-to-arrival transit time per schedule',
+  group: 'Operations',
+  filters: [
+    { key: 'date', label: 'Departed', type: 'daterange' },
+    {
+      key: 'direction',
+      label: 'Direction',
+      type: 'select',
+      options: [
+        { value: 'IMPORT', label: 'Import' },
+        { value: 'EXPORT', label: 'Export' },
+        { value: 'DOMESTIC', label: 'Domestic' },
+      ],
+    },
+  ],
+  columns: [
+    { key: 'trainNumber', label: 'Train No.', type: 'string', sortable: true, sortExpr: 'ts.train_number' },
+    { key: 'origin', label: 'Origin', type: 'string' },
+    { key: 'destination', label: 'Destination', type: 'string' },
+    {
+      key: 'actualDeparture',
+      label: 'Departed',
+      type: 'date',
+      sortable: true,
+      sortExpr: 'ts.actual_departure_at',
+    },
+    { key: 'actualArrival', label: 'Arrived', type: 'date' },
+    { key: 'transitHours', label: 'Transit (hrs)', type: 'number', sortable: true },
+  ],
+  defaultSort: { key: 'actualDeparture', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('ts.train_number', 'trainNumber')
+      .addSelect("COALESCE(o.label, 'Unknown')", 'origin')
+      .addSelect("COALESCE(d.label, 'Unknown')", 'destination')
+      .addSelect(`to_char(ts.actual_departure_at, 'YYYY-MM-DD HH24:MI')`, 'actualDeparture')
+      .addSelect(`to_char(ts.actual_arrival_at, 'YYYY-MM-DD HH24:MI')`, 'actualArrival')
+      .addSelect(
+        `ROUND(EXTRACT(EPOCH FROM (ts.actual_arrival_at - ts.actual_departure_at))::numeric / 3600, 1)::float8`,
+        'transitHours',
+      );
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'trips')
+      .addSelect(
+        `ROUND(AVG(EXTRACT(EPOCH FROM (ts.actual_arrival_at - ts.actual_departure_at)))::numeric / 3600, 1)::float8`,
+        'avgHours',
+      )
+      .getRawOne();
+    return [
+      { label: 'Trips', value: Number(row?.trips ?? 0) },
+      { label: 'Avg transit', value: Number(row?.avgHours ?? 0), unit: 'h' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/wagon-teu-utilization.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/wagon-teu-utilization.report.ts
new file mode 100644
index 000000000..7dabec37c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/wagon-teu-utilization.report.ts
@@ -0,0 +1,76 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { Wagon } from '../../wagons/entities/wagon.entity';
+import { WagonType } from '../../wagon-types/entities/wagon-type.entity';
+import { TrainSchedule } from '../../train-schedules/entities/train-schedule.entity';
+import { Container } from '../../container-management/entities/container.entity';
+import { ContainerType } from '../../rule-engine/entities/container-type.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+// TEU = container size in feet / 20 (20ft -> 1 TEU, 40ft -> 2 TEU). Scoped to
+// each wagon's CURRENT schedule pin — a live-state view, not a historical one.
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Wagon, 'w')
+    .innerJoin(TrainSchedule, 'ts', 'ts.id = w.current_train_schedule_id')
+    .leftJoin(WagonType, 'wt', 'wt.id = w.wagon_type_id')
+    .leftJoin(Container, 'c', 'c.wagon_id = w.id AND c.deleted_at IS NULL')
+    .leftJoin(ContainerType, 'ct', 'ct.id = c.container_type_id')
+    .where('w.deleted_at IS NULL');
+
+  if (params.trainNumber) {
+    qb.andWhere('ts.train_number ILIKE :trainNumber', { trainNumber: `%${params.trainNumber}%` });
+  }
+  if (params.dateFrom) {
+    qb.andWhere('ts.scheduled_departure_date >= :dateFrom', { dateFrom: params.dateFrom });
+  }
+  if (params.dateTo) qb.andWhere('ts.scheduled_departure_date < :dateTo', { dateTo: params.dateTo });
+  return qb;
+}
+
+export const wagonTeuUtilizationReport: ReportDefinition = {
+  key: 'wagon-teu-utilization',
+  title: 'Wagon TEU Utilization',
+  description: 'TEU loaded per wagon on its currently assigned train',
+  group: 'Operations',
+  filters: [
+    { key: 'trainNumber', label: 'Train No.', type: 'text' },
+    { key: 'date', label: 'Departure', type: 'daterange' },
+  ],
+  columns: [
+    { key: 'wagonNumber', label: 'Wagon', type: 'string', sortable: true, sortExpr: 'w.wagon_number' },
+    { key: 'wagonType', label: 'Wagon type', type: 'string' },
+    { key: 'trainNumber', label: 'Train No.', type: 'string', sortable: true, sortExpr: 'ts.train_number' },
+    { key: 'departureDate', label: 'Departure', type: 'date' },
+    { key: 'containers', label: 'Containers', type: 'number', sortable: true },
+    { key: 'teu', label: 'TEU', type: 'number', sortable: true },
+  ],
+  defaultSort: { key: 'teu', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('w.wagon_number', 'wagonNumber')
+      .addSelect("COALESCE(wt.name, 'Unknown')", 'wagonType')
+      .addSelect('ts.train_number', 'trainNumber')
+      .addSelect(`to_char(ts.scheduled_departure_date, 'YYYY-MM-DD')`, 'departureDate')
+      .addSelect('COUNT(c.id)::int', 'containers')
+      .addSelect('(COALESCE(SUM(ct.size_ft), 0) / 20.0)::float8', 'teu')
+      .groupBy('w.wagon_number')
+      .addGroupBy('wt.name')
+      .addGroupBy('ts.train_number')
+      .addGroupBy('ts.scheduled_departure_date');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(DISTINCT w.id)::int', 'wagons')
+      .addSelect('COUNT(c.id)::int', 'containers')
+      .addSelect('(COALESCE(SUM(ct.size_ft), 0) / 20.0)::float8', 'teu')
+      .getRawOne();
+    return [
+      { label: 'Wagons', value: Number(row?.wagons ?? 0) },
+      { label: 'Containers', value: Number(row?.containers ?? 0) },
+      { label: 'Total TEU', value: Number(row?.teu ?? 0) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/report.registry.ts b/apps/edr-freight-api/src/modules/reports/report.registry.ts
index dfc6ff002..0d9b1d3a2 100644
--- a/apps/edr-freight-api/src/modules/reports/report.registry.ts
+++ b/apps/edr-freight-api/src/modules/reports/report.registry.ts
@@ -7,6 +7,12 @@ import { wagonFleetStatusReport } from './definitions/wagon-fleet-status.report'
 import { wagonStatusDurationReport } from './definitions/wagon-status-duration.report';
 import { wagonRequestsReport } from './definitions/wagon-requests.report';
 import { locomotiveFleetStatusReport } from './definitions/locomotive-fleet-status.report';
+import { bookingStatusBreakdownReport } from './definitions/booking-status-breakdown.report';
+import { trainScheduleStatusReport } from './definitions/train-schedule-status.report';
+import { trainTurnaroundReport } from './definitions/train-turnaround.report';
+import { wagonTeuUtilizationReport } from './definitions/wagon-teu-utilization.report';
+import { loadedCapacityReport } from './definitions/loaded-capacity.report';
+import { globalLogisticsWagonsReport } from './definitions/global-logistics-wagons.report';
 import { ReportDefinition } from './report.types';
 
 /**
@@ -23,6 +29,12 @@ export const REPORTS: ReportDefinition[] = [
   wagonStatusDurationReport,
   wagonRequestsReport,
   locomotiveFleetStatusReport,
+  bookingStatusBreakdownReport,
+  trainScheduleStatusReport,
+  trainTurnaroundReport,
+  wagonTeuUtilizationReport,
+  loadedCapacityReport,
+  globalLogisticsWagonsReport,
 ];
 
 const BY_KEY = new Map<ReportKey, ReportDefinition>(REPORTS.map((r) => [r.key, r]));
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index f9a0f959f..9cddfde87 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -63,6 +63,12 @@ export const REPORT_KEYS = [
   "wagon-status-duration",
   "wagon-requests",
   "locomotive-fleet-status",
+  "booking-status-breakdown",
+  "train-schedule-status",
+  "train-turnaround",
+  "wagon-teu-utilization",
+  "loaded-capacity",
+  "global-logistics-wagons",
 ] as const;
 
 export type ReportKey = (typeof REPORT_KEYS)[number];

From 29913259f60da2b3fe615303ea49655da65f7517 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 08:23:19 +0000
Subject: [PATCH 068/174] feat(freight-api): add 9 commercial/finance reports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

customer-status (company-profile roles, not Company — importer/
exporter/forwarder lives there), contract-lifecycle, customs-documents
(clearance milestones), invoicing-pipeline, first-last-mile-bookings
(one resolver, UNION ALL over first_mile/last_mile — verified the
raw-string .from() subquery against the live query builder, not just
hand-written SQL, after the join-alias bug earlier this branch),
invoices-by-status, payments-by-status, revenue-summary, cargo-summary.

payments carries no deleted_at column despite extending BaseEntity —
caught by column-checking against the live DB before shipping, dropped
the soft-delete filter for that one query.

Completes the ITLMS dashboard spec's 20-resolver dedup list (19 built,
freight-weight-variance dropped — no charged-vs-actual weight
distinction in the schema).
---
 .../definitions/cargo-summary.report.ts       | 58 ++++++++++++
 .../definitions/contract-lifecycle.report.ts  | 83 +++++++++++++++++
 .../definitions/customer-status.report.ts     | 67 ++++++++++++++
 .../definitions/customs-documents.report.ts   | 66 ++++++++++++++
 .../first-last-mile-bookings.report.ts        | 90 +++++++++++++++++++
 .../definitions/invoices-by-status.report.ts  | 72 +++++++++++++++
 .../definitions/invoicing-pipeline.report.ts  | 59 ++++++++++++
 .../definitions/payments-by-status.report.ts  | 73 +++++++++++++++
 .../definitions/revenue-summary.report.ts     | 61 +++++++++++++
 .../src/modules/reports/report.registry.ts    | 18 ++++
 .../src/seed/freight-permissions.registry.ts  |  9 ++
 11 files changed, 656 insertions(+)
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/cargo-summary.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/contract-lifecycle.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/customer-status.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/customs-documents.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/first-last-mile-bookings.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/invoices-by-status.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/invoicing-pipeline.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/payments-by-status.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/revenue-summary.report.ts

diff --git a/apps/edr-freight-api/src/modules/reports/definitions/cargo-summary.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/cargo-summary.report.ts
new file mode 100644
index 000000000..ee3063ee1
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/cargo-summary.report.ts
@@ -0,0 +1,58 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { Booking } from '../../bookings/entities/booking.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+const TONS = 'COALESCE(b.bulk_total_weight_tons, b.cargo_total_weight_vgm)';
+const NOT_UMBRELLA = "(b.contract_kind IS NULL OR b.contract_kind <> 'GENERAL')";
+const DEAD_STATUSES = ['DRAFT', 'CANCELLED', 'REJECTED', 'EXPIRED'];
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params, directions } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Booking, 'b')
+    .where(`b.deleted_at IS NULL AND ${NOT_UMBRELLA}`)
+    .andWhere('b.status NOT IN (:...deadStatuses)', { deadStatuses: DEAD_STATUSES });
+
+  if (params.dateFrom) qb.andWhere('b.created_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('b.created_at < :dateTo', { dateTo: params.dateTo });
+  if (directions !== null) {
+    qb.andWhere(directions.length ? 'b.trade_direction IN (:...directions)' : '1 = 0', { directions });
+  }
+  return qb;
+}
+
+export const cargoSummaryReport: ReportDefinition = {
+  key: 'cargo-summary',
+  title: 'Cargo Summary',
+  description: 'Cargo tonnage by direction and cargo type',
+  group: 'Operations',
+  filters: [{ key: 'date', label: 'Created', type: 'daterange' }],
+  columns: [
+    { key: 'direction', label: 'Direction', type: 'string', sortable: true },
+    { key: 'freightType', label: 'Cargo type', type: 'string', sortable: true },
+    { key: 'bookings', label: 'Bookings', type: 'number', sortable: true },
+    { key: 'tons', label: 'Tonnage', type: 'tons', sortable: true },
+  ],
+  defaultSort: { key: 'tons', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('b.trade_direction', 'direction')
+      .addSelect('b.freight_type', 'freightType')
+      .addSelect('COUNT(*)::int', 'bookings')
+      .addSelect(`ROUND(COALESCE(SUM(${TONS}), 0))::float8`, 'tons')
+      .groupBy('b.trade_direction')
+      .addGroupBy('b.freight_type');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select(`ROUND(COALESCE(SUM(${TONS}), 0))::float8`, 'tons')
+      .addSelect('COUNT(*)::int', 'bookings')
+      .getRawOne();
+    return [
+      { label: 'Bookings', value: Number(row?.bookings ?? 0) },
+      { label: 'Total tonnage', value: Number(row?.tons ?? 0), unit: 't' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/contract-lifecycle.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/contract-lifecycle.report.ts
new file mode 100644
index 000000000..513abeda4
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/contract-lifecycle.report.ts
@@ -0,0 +1,83 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { Contract, CONTRACT_KINDS, CONTRACT_STATUSES } from '../../contracts/entities/contract.entity';
+import { Company } from '../../companies/entities/company.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params, directions } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Contract, 'ct')
+    .leftJoin(Company, 'c', 'c.id = ct.company_id')
+    .where('ct.deleted_at IS NULL');
+
+  if (params.dateFrom) qb.andWhere('ct.contract_valid_from >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('ct.contract_valid_from < :dateTo', { dateTo: params.dateTo });
+  if (params.kind) qb.andWhere('ct.contract_kind = :kind', { kind: params.kind });
+  if (params.direction) qb.andWhere('ct.trade_direction = :direction', { direction: params.direction });
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('ct.status IN (:...statuses)', { statuses });
+  if (directions !== null) {
+    qb.andWhere(directions.length ? 'ct.trade_direction IN (:...directions)' : '1 = 0', { directions });
+  }
+  return qb;
+}
+
+export const contractLifecycleReport: ReportDefinition = {
+  key: 'contract-lifecycle',
+  title: 'Contracts',
+  description: 'Signed, active and cancelled contracts',
+  group: 'Commercial',
+  filters: [
+    { key: 'date', label: 'Valid from', type: 'daterange' },
+    { key: 'kind', label: 'Kind', type: 'select', options: CONTRACT_KINDS.map((v) => ({ value: v, label: v })) },
+    {
+      key: 'direction',
+      label: 'Direction',
+      type: 'select',
+      options: [
+        { value: 'IMPORT', label: 'Import' },
+        { value: 'EXPORT', label: 'Export' },
+        { value: 'DOMESTIC', label: 'Domestic' },
+      ],
+    },
+    { key: 'statuses', label: 'Status', type: 'multiselect', options: CONTRACT_STATUSES.map((v) => ({ value: v, label: v.replace(/_/g, ' ') })) },
+  ],
+  columns: [
+    { key: 'reference', label: 'Reference', type: 'string', sortable: true, sortExpr: 'ct.reference' },
+    { key: 'customer', label: 'Customer', type: 'string', sortable: true, sortExpr: 'c.name' },
+    { key: 'kind', label: 'Kind', type: 'string' },
+    { key: 'direction', label: 'Direction', type: 'string' },
+    { key: 'freightType', label: 'Freight type', type: 'string' },
+    { key: 'status', label: 'Status', type: 'string', sortable: true, sortExpr: 'ct.status' },
+    { key: 'validFrom', label: 'Valid from', type: 'date', sortable: true, sortExpr: 'ct.contract_valid_from' },
+    { key: 'validUntil', label: 'Valid until', type: 'date' },
+    { key: 'signedAt', label: 'Signed', type: 'date' },
+  ],
+  defaultSort: { key: 'validFrom', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('ct.reference', 'reference')
+      .addSelect("COALESCE(c.name, ct.government_institution, 'Unknown')", 'customer')
+      .addSelect('ct.contract_kind', 'kind')
+      .addSelect('ct.trade_direction', 'direction')
+      .addSelect('ct.freight_type', 'freightType')
+      .addSelect('ct.status', 'status')
+      .addSelect(`to_char(ct.contract_valid_from, 'YYYY-MM-DD')`, 'validFrom')
+      .addSelect(`to_char(ct.contract_valid_until, 'YYYY-MM-DD')`, 'validUntil')
+      .addSelect(`to_char(ct.fully_executed_at, 'YYYY-MM-DD')`, 'signedAt');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'total')
+      .addSelect('COUNT(*) FILTER (WHERE ct.fully_executed_at IS NOT NULL)::int', 'signed')
+      .addSelect("COUNT(*) FILTER (WHERE ct.status = 'CANCELLED')::int", 'cancelled')
+      .getRawOne();
+    return [
+      { label: 'Contracts', value: Number(row?.total ?? 0) },
+      { label: 'Signed', value: Number(row?.signed ?? 0) },
+      { label: 'Cancelled', value: Number(row?.cancelled ?? 0) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/customer-status.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/customer-status.report.ts
new file mode 100644
index 000000000..60b6ff31a
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/customer-status.report.ts
@@ -0,0 +1,67 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { CompanyProfile, ProfileStatus, ProfileType } from '../../companies/entities/company-profile.entity';
+import { Company } from '../../companies/entities/company.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+// "Type (Importer, Exporter, Freight Forwarding)" and "Active/Suspended" are
+// CompanyProfile fields, not Company's — a company can hold several profiles
+// (e.g. importer AND exporter), each independently approved/suspended.
+const TYPE_OPTIONS = Object.values(ProfileType).map((v) => ({ value: v, label: v.replace(/_/g, ' ') }));
+const STATUS_OPTIONS = Object.values(ProfileStatus).map((v) => ({ value: v, label: v }));
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(CompanyProfile, 'cp')
+    .innerJoin(Company, 'c', 'c.id = cp.company_id')
+    .where('cp.deleted_at IS NULL');
+
+  if (params.type) qb.andWhere('cp.type = :type', { type: params.type });
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('cp.status IN (:...statuses)', { statuses });
+  return qb;
+}
+
+export const customerStatusReport: ReportDefinition = {
+  key: 'customer-status',
+  title: 'Customer Profiles',
+  description: 'Company profiles by role type and approval status',
+  group: 'Commercial',
+  filters: [
+    { key: 'type', label: 'Type', type: 'select', options: TYPE_OPTIONS },
+    { key: 'statuses', label: 'Status', type: 'multiselect', options: STATUS_OPTIONS },
+  ],
+  columns: [
+    { key: 'company', label: 'Company', type: 'string', sortable: true, sortExpr: 'c.name' },
+    { key: 'type', label: 'Type', type: 'string', sortable: true, sortExpr: 'cp.type' },
+    { key: 'status', label: 'Status', type: 'string', sortable: true, sortExpr: 'cp.status' },
+    { key: 'reference', label: 'Reference', type: 'string' },
+    { key: 'note', label: 'Note', type: 'string' },
+    { key: 'reviewedAt', label: 'Reviewed', type: 'date', sortable: true, sortExpr: 'cp.reviewed_at' },
+  ],
+  defaultSort: { key: 'reviewedAt', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('c.name', 'company')
+      .addSelect('cp.type', 'type')
+      .addSelect('cp.status', 'status')
+      .addSelect("COALESCE(cp.reference, '')", 'reference')
+      .addSelect("COALESCE(cp.review_note, '')", 'note')
+      .addSelect(`to_char(cp.reviewed_at, 'YYYY-MM-DD')`, 'reviewedAt');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'total')
+      .addSelect('COUNT(*) FILTER (WHERE cp.status = :active)::int', 'active')
+      .addSelect('COUNT(*) FILTER (WHERE cp.status = :suspended)::int', 'suspended')
+      .setParameters({ active: ProfileStatus.Active, suspended: ProfileStatus.Suspended })
+      .getRawOne();
+    return [
+      { label: 'Profiles', value: Number(row?.total ?? 0) },
+      { label: 'Active', value: Number(row?.active ?? 0) },
+      { label: 'Suspended', value: Number(row?.suspended ?? 0) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/customs-documents.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/customs-documents.report.ts
new file mode 100644
index 000000000..a0bcb32fc
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/customs-documents.report.ts
@@ -0,0 +1,66 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import {
+  ClearanceMilestone,
+  MILESTONE_OWNER_REGIONS,
+  MILESTONE_STATUSES,
+} from '../../contracts/entities/clearance-milestone.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds.createQueryBuilder().from(ClearanceMilestone, 'cm').where('cm.deleted_at IS NULL');
+
+  if (params.dateFrom) qb.andWhere('cm.created_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('cm.created_at < :dateTo', { dateTo: params.dateTo });
+  if (params.ownerRegion) qb.andWhere('cm.owner_region = :ownerRegion', { ownerRegion: params.ownerRegion });
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('cm.status IN (:...statuses)', { statuses });
+  return qb;
+}
+
+export const customsDocumentsReport: ReportDefinition = {
+  key: 'customs-documents',
+  title: 'Customs Clearance Milestones',
+  description: 'Clearance milestone volume by label, owner and status',
+  group: 'Operations',
+  filters: [
+    { key: 'date', label: 'Created', type: 'daterange' },
+    {
+      key: 'ownerRegion',
+      label: 'Owner',
+      type: 'select',
+      options: MILESTONE_OWNER_REGIONS.map((v) => ({ value: v, label: v })),
+    },
+    { key: 'statuses', label: 'Status', type: 'multiselect', options: MILESTONE_STATUSES.map((v) => ({ value: v, label: v })) },
+  ],
+  columns: [
+    { key: 'milestone', label: 'Milestone', type: 'string', sortable: true },
+    { key: 'ownerRegion', label: 'Owner', type: 'string', sortable: true },
+    { key: 'status', label: 'Status', type: 'string', sortable: true },
+    { key: 'count', label: 'Count', type: 'number', sortable: true },
+  ],
+  defaultSort: { key: 'count', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('cm.milestone_label', 'milestone')
+      .addSelect("COALESCE(cm.owner_region, 'Unassigned')", 'ownerRegion')
+      .addSelect('cm.status', 'status')
+      .addSelect('COUNT(*)::int', 'count')
+      .groupBy('cm.milestone_label')
+      .addGroupBy('cm.owner_region')
+      .addGroupBy('cm.status');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'total')
+      .addSelect("COUNT(*) FILTER (WHERE cm.status = 'COMPLETED')::int", 'completed')
+      .addSelect("COUNT(*) FILTER (WHERE cm.status = 'PENDING')::int", 'pending')
+      .getRawOne();
+    return [
+      { label: 'Milestones', value: Number(row?.total ?? 0) },
+      { label: 'Completed', value: Number(row?.completed ?? 0) },
+      { label: 'Pending', value: Number(row?.pending ?? 0) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/first-last-mile-bookings.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/first-last-mile-bookings.report.ts
new file mode 100644
index 000000000..d3abe10dc
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/first-last-mile-bookings.report.ts
@@ -0,0 +1,90 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { Booking } from '../../bookings/entities/booking.entity';
+import { Company } from '../../companies/entities/company.entity';
+import { Vehicle } from '../../vehicles/entities/vehicle.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+// FirstMile and LastMile are separate tables with an identical shape (status,
+// booking, optional vehicle). One resolver, unioned, with a `leg` column —
+// beats shipping two near-duplicate reports for the two halves of the trip.
+const LEG_UNION = `(
+  SELECT 'FIRST' AS leg, fm.id AS id, fm.booking_id AS booking_id, fm.status AS status,
+    fm.vehicle_id AS vehicle_id, fm.created_at AS created_at
+  FROM freight.first_mile fm WHERE fm.deleted_at IS NULL
+  UNION ALL
+  SELECT 'LAST' AS leg, lm.id AS id, lm.booking_id AS booking_id, lm.status AS status,
+    lm.vehicle_id AS vehicle_id, lm.created_at AS created_at
+  FROM freight.last_mile lm WHERE lm.deleted_at IS NULL
+)`;
+
+const STATUS_OPTIONS = [
+  { value: 'PAYMENT_PENDING', label: 'Payment pending' },
+  { value: 'READY_TO_TRANSIT', label: 'Ready to transit' },
+  { value: 'IN_TRANSIT', label: 'In transit' },
+  { value: 'RECEIVED_TO_PORT', label: 'Received to port' },
+  { value: 'DELIVERED', label: 'Delivered' },
+];
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(LEG_UNION, 'fl')
+    .innerJoin(Booking, 'b', 'b.id = fl.booking_id')
+    .leftJoin(Company, 'c', 'c.id = b.company_id')
+    .leftJoin(Vehicle, 'v', 'v.id = fl.vehicle_id')
+    .where('1 = 1');
+
+  if (params.leg) qb.andWhere('fl.leg = :leg', { leg: params.leg });
+  if (params.dateFrom) qb.andWhere('fl.created_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('fl.created_at < :dateTo', { dateTo: params.dateTo });
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('fl.status IN (:...statuses)', { statuses });
+  return qb;
+}
+
+export const firstLastMileBookingsReport: ReportDefinition = {
+  key: 'first-last-mile-bookings',
+  title: 'First/Last Mile Trucking',
+  description: 'First- and last-mile bookings by status and truck assignment',
+  group: 'Operations',
+  filters: [
+    { key: 'date', label: 'Created', type: 'daterange' },
+    { key: 'leg', label: 'Leg', type: 'select', options: [{ value: 'FIRST', label: 'First mile' }, { value: 'LAST', label: 'Last mile' }] },
+    { key: 'statuses', label: 'Status', type: 'multiselect', options: STATUS_OPTIONS },
+  ],
+  columns: [
+    { key: 'leg', label: 'Leg', type: 'string', sortable: true },
+    { key: 'booking', label: 'Booking', type: 'string', sortable: true, sortExpr: 'b.reference' },
+    { key: 'customer', label: 'Customer', type: 'string', sortable: true, sortExpr: 'c.name' },
+    { key: 'status', label: 'Status', type: 'string', sortable: true, sortExpr: 'fl.status' },
+    { key: 'truck', label: 'Truck', type: 'string' },
+    { key: 'assigned', label: 'Assigned', type: 'string', sortable: true },
+    { key: 'createdAt', label: 'Created', type: 'date', sortable: true, sortExpr: 'fl.created_at' },
+  ],
+  defaultSort: { key: 'createdAt', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('fl.leg', 'leg')
+      .addSelect('b.reference', 'booking')
+      .addSelect("COALESCE(c.name, 'Unknown')", 'customer')
+      .addSelect('fl.status', 'status')
+      .addSelect("COALESCE(v.plate_number, '—')", 'truck')
+      .addSelect("CASE WHEN fl.vehicle_id IS NOT NULL THEN 'Assigned' ELSE 'Unassigned' END", 'assigned')
+      .addSelect(`to_char(fl.created_at, 'YYYY-MM-DD')`, 'createdAt');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'total')
+      .addSelect('COUNT(*) FILTER (WHERE fl.vehicle_id IS NOT NULL)::int', 'assigned')
+      .getRawOne();
+    const total = Number(row?.total ?? 0);
+    const assigned = Number(row?.assigned ?? 0);
+    return [
+      { label: 'Trips', value: total },
+      { label: 'Assigned', value: assigned },
+      { label: 'Unassigned', value: total - assigned },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/invoices-by-status.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/invoices-by-status.report.ts
new file mode 100644
index 000000000..81b183f90
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/invoices-by-status.report.ts
@@ -0,0 +1,72 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { Freight } from '@edr/types';
+import { Invoice } from '../../billing/entities/invoice.entity';
+import { Company } from '../../companies/entities/company.entity';
+import { CompanyProfile } from '../../companies/entities/company-profile.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+const STATUS_OPTIONS = Object.values(Freight.InvoiceStatus).map((v) => ({ value: v, label: v }));
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Invoice, 'i')
+    .innerJoin(Company, 'c', 'c.id = i.company_id')
+    .leftJoin(CompanyProfile, 'cp', 'cp.id = i.company_profile_id')
+    .where('i.deleted_at IS NULL');
+
+  if (params.dateFrom) qb.andWhere('i.issued_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('i.issued_at < :dateTo', { dateTo: params.dateTo });
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('i.status IN (:...statuses)', { statuses });
+  return qb;
+}
+
+export const invoicesByStatusReport: ReportDefinition = {
+  key: 'invoices-by-status',
+  title: 'Invoices',
+  description: 'Every invoice with customer, profile type and settlement status',
+  group: 'Finance',
+  filters: [
+    { key: 'date', label: 'Issued', type: 'daterange' },
+    { key: 'statuses', label: 'Status', type: 'multiselect', options: STATUS_OPTIONS },
+  ],
+  columns: [
+    { key: 'invoiceNumber', label: 'Invoice No.', type: 'string', sortable: true, sortExpr: 'i.invoice_number' },
+    { key: 'customer', label: 'Customer', type: 'string', sortable: true, sortExpr: 'c.name' },
+    { key: 'profileType', label: 'Profile', type: 'string' },
+    { key: 'status', label: 'Status', type: 'string', sortable: true, sortExpr: 'i.status' },
+    { key: 'totalAmount', label: 'Total', type: 'money', sortable: true },
+    { key: 'paidAmount', label: 'Paid', type: 'money' },
+    { key: 'balanceAmount', label: 'Balance', type: 'money', sortable: true },
+    { key: 'issuedAt', label: 'Issued', type: 'date', sortable: true, sortExpr: 'i.issued_at' },
+    { key: 'dueAt', label: 'Due', type: 'date' },
+  ],
+  defaultSort: { key: 'issuedAt', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('i.invoice_number', 'invoiceNumber')
+      .addSelect('c.name', 'customer')
+      .addSelect("COALESCE(cp.type, 'Unknown')", 'profileType')
+      .addSelect('i.status', 'status')
+      .addSelect('ROUND(i.total_amount)::float8', 'totalAmount')
+      .addSelect('ROUND(i.paid_amount)::float8', 'paidAmount')
+      .addSelect('ROUND(i.balance_amount)::float8', 'balanceAmount')
+      .addSelect(`to_char(i.issued_at, 'YYYY-MM-DD')`, 'issuedAt')
+      .addSelect(`to_char(i.due_at, 'YYYY-MM-DD')`, 'dueAt');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'invoices')
+      .addSelect('ROUND(COALESCE(SUM(i.total_amount), 0))::float8', 'total')
+      .addSelect('ROUND(COALESCE(SUM(i.balance_amount), 0))::float8', 'balance')
+      .getRawOne();
+    return [
+      { label: 'Invoices', value: Number(row?.invoices ?? 0) },
+      { label: 'Total value', value: Number(row?.total ?? 0), unit: 'ETB' },
+      { label: 'Outstanding', value: Number(row?.balance ?? 0), unit: 'ETB' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/invoicing-pipeline.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/invoicing-pipeline.report.ts
new file mode 100644
index 000000000..8907f4f5a
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/invoicing-pipeline.report.ts
@@ -0,0 +1,59 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { Freight } from '@edr/types';
+import { Invoice } from '../../billing/entities/invoice.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+const STATUS_OPTIONS = Object.values(Freight.InvoiceStatus).map((v) => ({ value: v, label: v }));
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = ctx.ds.createQueryBuilder().from(Invoice, 'i').where('i.deleted_at IS NULL');
+
+  if (params.dateFrom) qb.andWhere('i.created_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('i.created_at < :dateTo', { dateTo: params.dateTo });
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('i.status IN (:...statuses)', { statuses });
+  return qb;
+}
+
+export const invoicingPipelineReport: ReportDefinition = {
+  key: 'invoicing-pipeline',
+  title: 'Invoicing Pipeline',
+  description: 'Invoice volume and value by type and status',
+  group: 'Finance',
+  filters: [
+    { key: 'date', label: 'Created', type: 'daterange' },
+    { key: 'statuses', label: 'Status', type: 'multiselect', options: STATUS_OPTIONS },
+  ],
+  columns: [
+    { key: 'type', label: 'Type', type: 'string', sortable: true },
+    { key: 'status', label: 'Status', type: 'string', sortable: true },
+    { key: 'invoices', label: 'Invoices', type: 'number', sortable: true },
+    { key: 'totalAmount', label: 'Total', type: 'money', sortable: true },
+    { key: 'balance', label: 'Outstanding', type: 'money', sortable: true },
+  ],
+  defaultSort: { key: 'invoices', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('i.type', 'type')
+      .addSelect('i.status', 'status')
+      .addSelect('COUNT(*)::int', 'invoices')
+      .addSelect('ROUND(COALESCE(SUM(i.total_amount), 0))::float8', 'totalAmount')
+      .addSelect('ROUND(COALESCE(SUM(i.balance_amount), 0))::float8', 'balance')
+      .groupBy('i.type')
+      .addGroupBy('i.status');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'invoices')
+      .addSelect('ROUND(COALESCE(SUM(i.total_amount), 0))::float8', 'totalAmount')
+      .addSelect('ROUND(COALESCE(SUM(i.balance_amount), 0))::float8', 'balance')
+      .getRawOne();
+    return [
+      { label: 'Invoices', value: Number(row?.invoices ?? 0) },
+      { label: 'Total value', value: Number(row?.totalAmount ?? 0), unit: 'ETB' },
+      { label: 'Outstanding', value: Number(row?.balance ?? 0), unit: 'ETB' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/payments-by-status.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/payments-by-status.report.ts
new file mode 100644
index 000000000..15e99a4b1
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/payments-by-status.report.ts
@@ -0,0 +1,73 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { PaymentEntity } from '../../payment/entities/payment.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+// No direct company link on payments (refId points at whatever the intent was
+// for — booking, demurrage, ...); breakdown stops at status/method/currency.
+const STATUS_OPTIONS = [
+  { value: 'action-required', label: 'Action required' },
+  { value: 'processing', label: 'Processing' },
+  { value: 'success', label: 'Success' },
+  { value: 'failed', label: 'Failed' },
+  { value: 'canceled', label: 'Canceled' },
+  { value: 'refunded', label: 'Refunded' },
+];
+const METHOD_OPTIONS = ['telebirr', 'cbe-birr', 'ebirr', 'waafi', 'card', 'dmoney', 'cac-bank', 'cbe-bill'].map(
+  (v) => ({ value: v, label: v }),
+);
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  // payments carries no deleted_at column (unlike the rest of the schema) —
+  // confirmed against the live DB, not assumed from BaseEntity.
+  const qb = ctx.ds.createQueryBuilder().from(PaymentEntity, 'p').where('1 = 1');
+
+  if (params.dateFrom) qb.andWhere('p.created_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('p.created_at < :dateTo', { dateTo: params.dateTo });
+  if (params.method) qb.andWhere('p.method = :method', { method: params.method });
+  const statuses = params.statuses as string[] | null;
+  if (statuses) qb.andWhere('p.status IN (:...statuses)', { statuses });
+  return qb;
+}
+
+export const paymentsByStatusReport: ReportDefinition = {
+  key: 'payments-by-status',
+  title: 'Payments by Status',
+  description: 'Payment volume and value by status, method and currency',
+  group: 'Finance',
+  filters: [
+    { key: 'date', label: 'Created', type: 'daterange' },
+    { key: 'method', label: 'Method', type: 'select', options: METHOD_OPTIONS },
+    { key: 'statuses', label: 'Status', type: 'multiselect', options: STATUS_OPTIONS },
+  ],
+  columns: [
+    { key: 'status', label: 'Status', type: 'string', sortable: true },
+    { key: 'method', label: 'Method', type: 'string', sortable: true },
+    { key: 'currency', label: 'Currency', type: 'string' },
+    { key: 'payments', label: 'Payments', type: 'number', sortable: true },
+    { key: 'amount', label: 'Amount', type: 'money', sortable: true },
+  ],
+  defaultSort: { key: 'amount', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('p.status', 'status')
+      .addSelect('p.method', 'method')
+      .addSelect('p.currency', 'currency')
+      .addSelect('COUNT(*)::int', 'payments')
+      .addSelect('ROUND(COALESCE(SUM(p.amount), 0))::float8', 'amount')
+      .groupBy('p.status')
+      .addGroupBy('p.method')
+      .addGroupBy('p.currency');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'payments')
+      .addSelect("ROUND(COALESCE(SUM(p.amount) FILTER (WHERE p.status = 'success'), 0))::float8", 'paid')
+      .getRawOne();
+    return [
+      { label: 'Payments', value: Number(row?.payments ?? 0) },
+      { label: 'Total paid', value: Number(row?.paid ?? 0), unit: 'ETB' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/revenue-summary.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/revenue-summary.report.ts
new file mode 100644
index 000000000..684d4e2e5
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/revenue-summary.report.ts
@@ -0,0 +1,61 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { Booking } from '../../bookings/entities/booking.entity';
+import { ReportContext, ReportDefinition } from '../report.types';
+
+const REVENUE = 'COALESCE(b.adjusted_total_amount, b.total_amount)';
+const NOT_UMBRELLA = "(b.contract_kind IS NULL OR b.contract_kind <> 'GENERAL')";
+const DEAD_STATUSES = ['DRAFT', 'CANCELLED', 'REJECTED', 'EXPIRED'];
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params, directions } = ctx;
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Booking, 'b')
+    .where(`b.deleted_at IS NULL AND ${NOT_UMBRELLA}`)
+    .andWhere('b.status NOT IN (:...deadStatuses)', { deadStatuses: DEAD_STATUSES });
+
+  if (params.dateFrom) qb.andWhere('b.created_at >= :dateFrom', { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere('b.created_at < :dateTo', { dateTo: params.dateTo });
+  if (directions !== null) {
+    qb.andWhere(directions.length ? 'b.trade_direction IN (:...directions)' : '1 = 0', { directions });
+  }
+  return qb;
+}
+
+export const revenueSummaryReport: ReportDefinition = {
+  key: 'revenue-summary',
+  title: 'Revenue Summary',
+  description: 'Booking revenue by direction, cargo type and currency',
+  group: 'Finance',
+  filters: [{ key: 'date', label: 'Created', type: 'daterange' }],
+  columns: [
+    { key: 'direction', label: 'Direction', type: 'string', sortable: true },
+    { key: 'freightType', label: 'Cargo type', type: 'string', sortable: true },
+    { key: 'currency', label: 'Currency', type: 'string' },
+    { key: 'bookings', label: 'Bookings', type: 'number', sortable: true },
+    { key: 'revenue', label: 'Revenue', type: 'money', sortable: true },
+  ],
+  defaultSort: { key: 'revenue', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select('b.trade_direction', 'direction')
+      .addSelect('b.freight_type', 'freightType')
+      .addSelect('b.payment_currency', 'currency')
+      .addSelect('COUNT(*)::int', 'bookings')
+      .addSelect(`ROUND(COALESCE(SUM(${REVENUE}), 0))::float8`, 'revenue')
+      .groupBy('b.trade_direction')
+      .addGroupBy('b.freight_type')
+      .addGroupBy('b.payment_currency');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select(`ROUND(COALESCE(SUM(${REVENUE}), 0))::float8`, 'revenue')
+      .addSelect('COUNT(*)::int', 'bookings')
+      .getRawOne();
+    return [
+      { label: 'Bookings', value: Number(row?.bookings ?? 0) },
+      { label: 'Total revenue', value: Number(row?.revenue ?? 0), unit: 'ETB' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/report.registry.ts b/apps/edr-freight-api/src/modules/reports/report.registry.ts
index 0d9b1d3a2..004b61e5b 100644
--- a/apps/edr-freight-api/src/modules/reports/report.registry.ts
+++ b/apps/edr-freight-api/src/modules/reports/report.registry.ts
@@ -13,6 +13,15 @@ import { trainTurnaroundReport } from './definitions/train-turnaround.report';
 import { wagonTeuUtilizationReport } from './definitions/wagon-teu-utilization.report';
 import { loadedCapacityReport } from './definitions/loaded-capacity.report';
 import { globalLogisticsWagonsReport } from './definitions/global-logistics-wagons.report';
+import { customerStatusReport } from './definitions/customer-status.report';
+import { contractLifecycleReport } from './definitions/contract-lifecycle.report';
+import { customsDocumentsReport } from './definitions/customs-documents.report';
+import { invoicingPipelineReport } from './definitions/invoicing-pipeline.report';
+import { firstLastMileBookingsReport } from './definitions/first-last-mile-bookings.report';
+import { invoicesByStatusReport } from './definitions/invoices-by-status.report';
+import { paymentsByStatusReport } from './definitions/payments-by-status.report';
+import { revenueSummaryReport } from './definitions/revenue-summary.report';
+import { cargoSummaryReport } from './definitions/cargo-summary.report';
 import { ReportDefinition } from './report.types';
 
 /**
@@ -35,6 +44,15 @@ export const REPORTS: ReportDefinition[] = [
   wagonTeuUtilizationReport,
   loadedCapacityReport,
   globalLogisticsWagonsReport,
+  customerStatusReport,
+  contractLifecycleReport,
+  customsDocumentsReport,
+  invoicingPipelineReport,
+  firstLastMileBookingsReport,
+  invoicesByStatusReport,
+  paymentsByStatusReport,
+  revenueSummaryReport,
+  cargoSummaryReport,
 ];
 
 const BY_KEY = new Map<ReportKey, ReportDefinition>(REPORTS.map((r) => [r.key, r]));
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 9cddfde87..e98127042 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -69,6 +69,15 @@ export const REPORT_KEYS = [
   "wagon-teu-utilization",
   "loaded-capacity",
   "global-logistics-wagons",
+  "customer-status",
+  "contract-lifecycle",
+  "customs-documents",
+  "invoicing-pipeline",
+  "first-last-mile-bookings",
+  "invoices-by-status",
+  "payments-by-status",
+  "revenue-summary",
+  "cargo-summary",
 ] as const;
 
 export type ReportKey = (typeof REPORT_KEYS)[number];

From 833e62990e429b2ac4a79e05b746fffe88d1ace7 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Thu, 13 Aug 2026 08:22:51 +0000
Subject: [PATCH 069/174] feat(train-scheduling): add wagon type, tare, equated
 length, station, seal no and note columns to import marshalling doc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Import Load List / Marshalling Document only rendered Seq, Wagon,
Booking, Company, Load, Container numbers, Weight T — missing fields
present on the physical marshaling sheet (wagon type, tare, equated
length, departure/arrival station, seal no) and a blank note column
for yard staff. Export marshalling doc already had most of these;
import doc now matches. Existing columns kept in place, unchanged.
---
 .../last-mile-requests.controller.ts          | 13 +++
 .../last-mile-requests.service.ts             | 22 +++++
 .../services/train-scheduling.service.ts      | 27 +++++-
 .../detail/BookingMileServicesCard.tsx        | 60 +++++++++++-
 .../portal/src/constants/URLS.ts              |  1 +
 .../components/MileSummaryCard.tsx            | 97 +++++++++++++++++--
 .../services/last-mile-requests.service.ts    |  7 ++
 7 files changed, 215 insertions(+), 12 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.controller.ts b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.controller.ts
index 3d9fa4254..ff52ff9d7 100644
--- a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.controller.ts
+++ b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.controller.ts
@@ -48,6 +48,19 @@ export class LastMileRequestsController {
     return this.requestsService.freeTruckCount().then((count) => ({ count }));
   }
 
+  // Customer-facing like :id — booking detail (portal + backoffice) lists the
+  // booking's requests to link the stored LM contract. Ownership-checked in
+  // the service for portal callers.
+  @Get('by-booking/:bookingId')
+  @MixedAudience(FREIGHT_PERMS.lastMile.requestView)
+  @ApiOperation({ summary: "A booking's last-mile requests, newest first — LM contract reference" })
+  findForBooking(
+    @Param('bookingId', ParseUUIDPipe) bookingId: string,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.requestsService.findForBooking(bookingId, user?.id ?? null);
+  }
+
   @Get(':id/price-estimate')
   @BookingStaff(FREIGHT_PERMS.lastMile.requestView)
   @ApiOperation({
diff --git a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.service.ts b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.service.ts
index ebdc93746..37612d318 100644
--- a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.service.ts
+++ b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-requests.service.ts
@@ -221,6 +221,28 @@ export class LastMileRequestsService {
     return record;
   }
 
+  /**
+   * Every request on a booking, newest first — the booking-detail pages
+   * (portal + backoffice) use this to surface the LM contract later. Portal
+   * callers pass their userId and are ownership-checked against the booking's
+   * company, mirroring findById.
+   */
+  async findForBooking(bookingId: string, userId?: string | null): Promise<LastMileRequest[]> {
+    if (userId) {
+      const companyId = await this.bookingsService.resolveCustomerCompanyId(userId);
+      if (companyId) {
+        const booking = await this.bookingsRepository.findById(bookingId);
+        if (booking?.companyId && booking.companyId !== companyId) {
+          throw new BadRequestException('This booking does not belong to your company');
+        }
+      }
+    }
+    return this.requestsRepository.findAll({
+      where: { bookingId },
+      order: { createdAt: 'DESC' },
+    });
+  }
+
   /**
    * Rule-based price estimate for the approval dialog: estimated km (yard GPS →
    * delivery point, straight-line) × the LIVE last-mile rate rules against the
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index fc9395ffb..6c89c6980 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -3002,6 +3002,9 @@ export class TrainSchedulingService {
         .map((wagon) => ({
           sequenceNo: wagon.sequenceNo,
           wagonNumber: wagon.physicalWagon?.wagonNumber ?? null,
+          wagonType: wagon.wagonType?.code ?? wagon.wagonType?.name ?? null,
+          tareWeightTons: wagon.wagonType?.tareWeightTons ?? null,
+          equatedLengthM: wagon.wagonType?.equatedLengthM ?? null,
           allocations: (wagon.allocations ?? []).map((allocation) => ({
             bookingId: allocation.bookingId,
             bookingReference: allocation.booking?.reference ?? null,
@@ -3501,26 +3504,37 @@ export class TrainSchedulingService {
     const allocationRows = loadList.wagons
       .flatMap((wagon) => {
         const wagonCells = `<td>${esc(wagon.sequenceNo)}</td>
-            <td>${esc(wagon.wagonNumber)}</td>`;
+            <td>${esc(wagon.wagonNumber)}</td>
+            <td>${esc(wagon.wagonType)}</td>
+            <td class="num">${wagon.tareWeightTons == null ? '-' : esc(Number(wagon.tareWeightTons).toFixed(2))}</td>
+            <td class="num">${wagon.equatedLengthM == null ? '-' : esc(Number(wagon.equatedLengthM).toFixed(3))}</td>
+            <td>${esc(loadList.origin)}</td>
+            <td>${esc(loadList.destination)}</td>`;
         // An empty wagon still runs in the consist, so it still gets a line — see
         // buildExportLoadListHtml.
         if (wagon.allocations.length === 0) {
           return [
             `<tr class="empty">
             ${wagonCells}
-            <td colspan="4">EMPTY — no cargo allocated</td>
+            <td colspan="7">EMPTY — no cargo allocated</td>
           </tr>`,
           ];
         }
         return wagon.allocations.map(
           (allocation) => {
             const companyName = (allocation.booking as unknown as { company?: { name?: string } } | undefined)?.company?.name ?? '-';
+            const sealNumbers = (allocation.containerItems ?? [])
+              .map((item) => item.sealNumber)
+              .filter(Boolean)
+              .join(', ');
             return `<tr>
             ${wagonCells}
             <td>${esc(allocation.bookingReference ?? allocation.bookingId)}</td>
             <td>${esc(companyName)}</td>
             <td>${esc(allocation.loadType)}</td>
             <td>${esc(allocation.containerNumbers.length ? allocation.containerNumbers.join(', ') : '-')}</td>
+            <td>${esc(sealNumbers || '-')}</td>
+            <td></td>
             <td class="num">${esc(Number(allocation.allocatedWeightTons || 0).toFixed(3))}</td>
           </tr>`;
           },
@@ -3609,15 +3623,22 @@ export class TrainSchedulingService {
         <tr>
           <th>Seq</th>
           <th>Wagon</th>
+          <th>Wagon Type</th>
+          <th class="num">Tare</th>
+          <th class="num">Equated</th>
+          <th>Departure Station</th>
+          <th>Arrival Station</th>
           <th>Booking</th>
           <th>Company</th>
           <th>Load</th>
           <th>Container numbers</th>
+          <th>Seal No</th>
+          <th>Note</th>
           <th class="num">Weight T</th>
         </tr>
       </thead>
       <tbody>
-        ${allocationRows || '<tr><td colspan="6">No wagons on this train set.</td></tr>'}
+        ${allocationRows || '<tr><td colspan="14">No wagons on this train set.</td></tr>'}
       </tbody>
     </table>
 
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingMileServicesCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingMileServicesCard.tsx
index 3236e5cae..0a079bb4d 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingMileServicesCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingMileServicesCard.tsx
@@ -1,6 +1,9 @@
-import { Truck } from "lucide-react";
-import { SimpleGrid } from "@mantine/core";
+import { Download, Truck } from "lucide-react";
+import { Button, Group, SimpleGrid, Stack, Text } from "@mantine/core";
+import { useQuery } from "@tanstack/react-query";
 
+import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
+import { lastMileRequestsService } from "@/services/last-mile-requests.service";
 import type { BookingDetail } from "@/types/booking";
 
 import { SectionCard } from "./SectionCard";
@@ -10,12 +13,37 @@ export interface BookingMileServicesCardProps {
   booking: BookingDetail;
 }
 
-/** First / last mile addresses. Renders nothing when neither is present. */
+/**
+ * First / last mile addresses, plus the stored last-mile contract reference
+ * (signed status + PDF download) for Truck & Machinery once a request on this
+ * booking is approved. Renders nothing when neither address is present.
+ */
 export function BookingMileServicesCard({ booking }: BookingMileServicesCardProps) {
+  const { data: requestsResponse } = useQuery({
+    queryKey: QUERY_KEYS.LAST_MILE_REQUESTS.list({ bookingId: booking.id }),
+    queryFn: async () =>
+      (await lastMileRequestsService.list({ bookingId: booking.id })).data,
+    enabled: Boolean(booking.lastMileDeliveryAddress),
+  });
+  const approvedRequest = (requestsResponse?.data ?? []).find(
+    (r) => r.status === "APPROVED",
+  );
+
   if (!booking.firstMilePickupAddress && !booking.lastMileDeliveryAddress) {
     return null;
   }
 
+  const downloadContract = async () => {
+    if (!approvedRequest) return;
+    const blob = (await lastMileRequestsService.contractDocument(approvedRequest.id)).data;
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `last-mile-contract-${booking.reference ?? booking.id}.pdf`;
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
   return (
     <SectionCard icon={Truck} title="Mile services" accent="grape">
       <SimpleGrid cols={{ base: 1, md: 2 }} spacing="sm">
@@ -26,6 +54,32 @@ export function BookingMileServicesCard({ booking }: BookingMileServicesCardProp
           <MetricTile label="Last mile delivery" value={booking.lastMileDeliveryAddress} />
         )}
       </SimpleGrid>
+      {approvedRequest && (
+        <Group justify="space-between" align="center" wrap="wrap" mt="sm">
+          <Stack gap={0}>
+            <Text size="sm" fw={600}>
+              Last-mile contract
+            </Text>
+            <Text size="xs" c={approvedRequest.customerSignedAt ? "green.8" : "orange.8"}>
+              {approvedRequest.customerSignedAt
+                ? `Signed ${new Date(approvedRequest.customerSignedAt).toLocaleDateString()}${
+                    approvedRequest.signerDisplayName
+                      ? ` by ${approvedRequest.signerDisplayName}`
+                      : ""
+                  }`
+                : "Awaiting customer signature"}
+            </Text>
+          </Stack>
+          <Button
+            size="xs"
+            variant="light"
+            leftSection={<Download size={14} />}
+            onClick={() => void downloadContract()}
+          >
+            Download PDF
+          </Button>
+        </Group>
+      )}
     </SectionCard>
   );
 }
diff --git a/apps/edr-freight-web/portal/src/constants/URLS.ts b/apps/edr-freight-web/portal/src/constants/URLS.ts
index a0d33f5ba..c9576d192 100644
--- a/apps/edr-freight-web/portal/src/constants/URLS.ts
+++ b/apps/edr-freight-web/portal/src/constants/URLS.ts
@@ -224,6 +224,7 @@ export const URL_CONSTANTS = {
   },
 
   LAST_MILE_REQUESTS: {
+    BY_BOOKING: (bookingId: string) => `/api/last-mile-requests/by-booking/${bookingId}`,
     BY_ID: (id: string) => `/api/last-mile-requests/${id}`,
     SUBMIT: (id: string) => `/api/last-mile-requests/${id}/submit`,
     CONTRACT_VIEW: (id: string) => `/api/last-mile-requests/${id}/contract/view`,
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/MileSummaryCard.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/MileSummaryCard.tsx
index bfb57529f..6619dbd06 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/MileSummaryCard.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/MileSummaryCard.tsx
@@ -1,5 +1,6 @@
-import { Box, Group, Stack, Text } from "@mantine/core";
+import { Box, Button, Group, Stack, Text } from "@mantine/core";
 import { useQuery } from "@tanstack/react-query";
+import { useNavigate } from "react-router-dom";
 
 import type { Freight } from "@edr/types";
 
@@ -8,6 +9,7 @@ import type {
   MileLegSummary,
   MileVehicleSummary,
 } from "@/services/bookings.service";
+import { lastMileRequestsService } from "@/services/last-mile-requests.service";
 
 import { CardTitle, SectionCard } from "./layout";
 
@@ -171,12 +173,85 @@ function LegBlock({
   );
 }
 
+/**
+ * Reference row for the stored last-mile contract: signed status, open the
+ * contract page (view / sign), download the PDF.
+ */
+function LastMileContractRow({
+  bookingId,
+  requestId,
+  signedAt,
+  signerDisplayName,
+}: {
+  bookingId: string;
+  requestId: string;
+  signedAt?: string | null;
+  signerDisplayName?: string | null;
+}) {
+  const navigate = useNavigate();
+  const download = async () => {
+    const blob = await lastMileRequestsService.downloadContractDocument(requestId);
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = "last-mile-contract.pdf";
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  return (
+    <Group
+      justify="space-between"
+      align="center"
+      wrap="wrap"
+      pt={8}
+      mt={4}
+      style={{ borderTop: "1px solid #F2F5F8" }}
+    >
+      <Stack gap={2} style={{ minWidth: 0 }}>
+        <Text fz="13px" fw={700} c="#10202F">
+          Last-mile contract
+        </Text>
+        <Text fz="12px" c={signedAt ? "#0A6F4D" : "#B45309"}>
+          {signedAt
+            ? `Signed ${new Date(signedAt).toLocaleDateString()}${
+                signerDisplayName ? ` by ${signerDisplayName}` : ""
+              }`
+            : "Awaiting your signature"}
+        </Text>
+      </Stack>
+      <Group gap={8}>
+        <Button
+          size="xs"
+          variant="light"
+          onClick={() =>
+            navigate(`/bookings/${bookingId}/last-mile-contract?requestId=${requestId}`)
+          }
+        >
+          {signedAt ? "View contract" : "View & sign"}
+        </Button>
+        <Button size="xs" variant="default" onClick={() => void download()}>
+          Download PDF
+        </Button>
+      </Group>
+    </Group>
+  );
+}
+
 export function MileSummaryCard({ booking }: { booking: Freight.IBooking }) {
   const { data } = useQuery({
     queryKey: ["booking-mile-summary", booking.id],
     queryFn: () => bookingsService.mileSummary(booking.id),
   });
 
+  // The stored LM contract lives on the booking's approved last-mile request.
+  const { data: lmRequests } = useQuery({
+    queryKey: ["booking-last-mile-requests", booking.id],
+    queryFn: () => lastMileRequestsService.listForBooking(booking.id),
+    enabled: !!booking.lastMileDeliveryAddress,
+  });
+  const approvedRequest = (lmRequests ?? []).find((r) => r.status === "APPROVED");
+
   const firstLeg = data?.firstMile ?? null;
   const lastLeg = data?.lastMile ?? null;
 
@@ -202,11 +277,21 @@ export function MileSummaryCard({ booking }: { booking: Freight.IBooking }) {
           />
         )}
         {showLast && (
-          <LegBlock
-            title="Last mile"
-            leg={lastLeg}
-            address={booking.lastMileDeliveryAddress}
-          />
+          <Box>
+            <LegBlock
+              title="Last mile"
+              leg={lastLeg}
+              address={booking.lastMileDeliveryAddress}
+            />
+            {approvedRequest && (
+              <LastMileContractRow
+                bookingId={booking.id}
+                requestId={approvedRequest.id}
+                signedAt={approvedRequest.customerSignedAt}
+                signerDisplayName={approvedRequest.signerDisplayName}
+              />
+            )}
+          </Box>
         )}
       </Stack>
     </SectionCard>
diff --git a/apps/edr-freight-web/portal/src/services/last-mile-requests.service.ts b/apps/edr-freight-web/portal/src/services/last-mile-requests.service.ts
index 5069eafe3..08133ba08 100644
--- a/apps/edr-freight-web/portal/src/services/last-mile-requests.service.ts
+++ b/apps/edr-freight-web/portal/src/services/last-mile-requests.service.ts
@@ -12,6 +12,7 @@ export interface LastMileRequest {
   requestedContainerNumbers?: string[] | null;
   requestedDeliveryDate?: string | null;
   customerSignedAt?: string | null;
+  signerDisplayName?: string | null;
   rejectionReason?: string | null;
   createdAt: string;
   updatedAt: string;
@@ -46,6 +47,12 @@ export const lastMileRequestsService = {
     return data.data ?? data;
   },
 
+  /** The booking's requests, newest first — links the stored LM contract. */
+  listForBooking: async (bookingId: string): Promise<LastMileRequest[]> => {
+    const { data } = await client.get(L.BY_BOOKING(bookingId));
+    return data.data ?? data;
+  },
+
   /** Confirm which containers go via EDR last-mile and the requested delivery date. */
   submit: async (
     id: string,

From 6f14cf8bbf9141542ed71c9aa5baf8b92bf47860 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 08:33:59 +0000
Subject: [PATCH 070/174] feat(freight-backoffice): add DateRangePicker,
 replace ad-hoc from/to date filters
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a shadcn Popover+Calendar range picker with presets (Today, Last 7/30
days, this/last month, YTD) and Apply/Cancel. Swaps it into every shadcn-family
from-to date filter: activity log, sector reports, incoming records (EN
branch), CombinedFilterBar (13 consumers), user records, audit log — also
fixes an uncontrolled-input bug on the audit log date fields.

Mantine-based ListControls/ReportFilters left untouched (different UI kit).
---
 .../backoffice/src/pages/AuditLog.tsx         |  22 +-
 .../sectorReports/SectorReportFilters.tsx     |  32 +--
 .../externalIncomingRecordsV2.tsx             |  25 +--
 .../internalIncomingRecordsV2.tsx             |  25 +--
 .../components/userRecords/userRecords.tsx    |  31 +--
 .../shared/common/ui/date-range-picker.tsx    | 197 ++++++++++++++++++
 .../activity-log/activity-filters.tsx         | 103 +--------
 .../components/filters/CombinedFilterBar.tsx  |  31 +--
 8 files changed, 252 insertions(+), 214 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/shared/common/ui/date-range-picker.tsx

diff --git a/apps/edr-freight-web/backoffice/src/pages/AuditLog.tsx b/apps/edr-freight-web/backoffice/src/pages/AuditLog.tsx
index 5374bcee7..1f2c9461e 100644
--- a/apps/edr-freight-web/backoffice/src/pages/AuditLog.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/AuditLog.tsx
@@ -1,5 +1,6 @@
 import React, { useEffect, useState } from "react";
 import { Input } from "@/shared/common/ui/input";
+import { DateRangePicker, parseDay, formatDay } from "@/shared/common/ui/date-range-picker";
 import {
   Select,
   SelectTrigger,
@@ -134,21 +135,12 @@ const buildQuery = (): CollectionQueryDTO => {
           className="w-64"
         />
 
-        <div className="flex gap-2 items-center">
-          <Input
-            type="date"
-            onChange={(e) =>
-              setDateRange({ ...dateRange, start: e.target.value })
-            }
-          />
-          <span className="text-muted-foreground text-sm">to</span>
-          <Input
-            type="date"
-            onChange={(e) =>
-              setDateRange({ ...dateRange, end: e.target.value })
-            }
-          />
-        </div>
+        <DateRangePicker
+          value={{ from: parseDay(dateRange.start), to: parseDay(dateRange.end) }}
+          onChange={(range) =>
+            setDateRange({ start: formatDay(range.from), end: formatDay(range.to) })
+          }
+        />
 
         <Select value={sort} onValueChange={setSort}>
           <SelectTrigger className="w-[180px]">
diff --git a/apps/edr-freight-web/backoffice/src/record-management/components/sectorReports/SectorReportFilters.tsx b/apps/edr-freight-web/backoffice/src/record-management/components/sectorReports/SectorReportFilters.tsx
index 1ad10b52b..1d148c594 100644
--- a/apps/edr-freight-web/backoffice/src/record-management/components/sectorReports/SectorReportFilters.tsx
+++ b/apps/edr-freight-web/backoffice/src/record-management/components/sectorReports/SectorReportFilters.tsx
@@ -14,6 +14,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/shared/common/ui/select";
+import { DateRangePicker, parseDay, formatDay } from "@/shared/common/ui/date-range-picker";
 
 export interface ReportFilterOption {
   id: string;
@@ -167,33 +168,18 @@ export function SectorReportFilters({
         </Select>
       </label>
 
-      <label className="space-y-1.5 text-xs font-medium">
+      <label className="space-y-1.5 text-xs font-medium sm:col-span-2">
         <span className="flex items-center gap-2">
           <CalendarDays className="size-4 text-primary" />
-          From date
+          Date range
         </span>
-        <input
-          type="date"
-          value={fromDate}
-          max={toDate || undefined}
+        <DateRangePicker
+          value={{ from: parseDay(fromDate), to: parseDay(toDate) }}
+          onChange={(range) => {
+            onFromDateChange(formatDay(range.from));
+            onToDateChange(formatDay(range.to));
+          }}
           disabled={!unitId || loading}
-          onChange={(event) => onFromDateChange(event.target.value)}
-          className="flex h-9 w-full rounded-md border border-input bg-background px-3 py-1 text-sm shadow-sm outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50"
-        />
-      </label>
-
-      <label className="space-y-1.5 text-xs font-medium">
-        <span className="flex items-center gap-2">
-          <CalendarDays className="size-4 text-primary" />
-          To date
-        </span>
-        <input
-          type="date"
-          value={toDate}
-          min={fromDate || undefined}
-          disabled={!unitId || loading}
-          onChange={(event) => onToDateChange(event.target.value)}
-          className="flex h-9 w-full rounded-md border border-input bg-background px-3 py-1 text-sm shadow-sm outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50"
         />
       </label>
 
diff --git a/apps/edr-freight-web/backoffice/src/record-management/components/userIncoming/externalIncomingRecords/externalIncomingRecordsV2.tsx b/apps/edr-freight-web/backoffice/src/record-management/components/userIncoming/externalIncomingRecords/externalIncomingRecordsV2.tsx
index 1b3d6bb1e..859892524 100644
--- a/apps/edr-freight-web/backoffice/src/record-management/components/userIncoming/externalIncomingRecords/externalIncomingRecordsV2.tsx
+++ b/apps/edr-freight-web/backoffice/src/record-management/components/userIncoming/externalIncomingRecords/externalIncomingRecordsV2.tsx
@@ -2,6 +2,7 @@ import { useState, useEffect, useMemo, useCallback } from "react";
 import { DataTable } from "@/record-management/common/DataTable";
 import { Button } from "@/shared/common/ui/button";
 import { Input } from "@/shared/common/ui/input";
+import { DateRangePicker, parseDay, formatDay } from "@/shared/common/ui/date-range-picker";
 import {
   Select,
   SelectContent,
@@ -383,23 +384,13 @@ const ExternalIncomingRecords = () => {
           ) : (
             <div className="flex flex-col sm:flex-row gap-2">
               {lang.startsWith("en") ? (
-                <>
-                  <label className="mt-2">From: </label>
-                  <Input
-                    type="date"
-                    value={fromDispatchedDate}
-                    onChange={(e) => setFromDispatchedDate(e.target.value)}
-                    className="w-[150px]"
-                  />
-                  <label className="mt-2">To: </label>
-                  <Input
-                    type="date"
-                    value={toDispatchedDate}
-                    onChange={(e) => setToDispatchedDate(e.target.value)}
-                    min={fromDispatchedDate}
-                    className="w-[150px]"
-                  />
-                </>
+                <DateRangePicker
+                  value={{ from: parseDay(fromDispatchedDate), to: parseDay(toDispatchedDate) }}
+                  onChange={(range) => {
+                    setFromDispatchedDate(formatDay(range.from));
+                    setToDispatchedDate(formatDay(range.to));
+                  }}
+                />
               ) : (
                 <div className="flex flex-wrap items-center gap-3">
                   {/* From Date */}
diff --git a/apps/edr-freight-web/backoffice/src/record-management/components/userIncoming/internalIncomingRecords/internalIncomingRecordsV2.tsx b/apps/edr-freight-web/backoffice/src/record-management/components/userIncoming/internalIncomingRecords/internalIncomingRecordsV2.tsx
index b7deb4247..25cdb4056 100644
--- a/apps/edr-freight-web/backoffice/src/record-management/components/userIncoming/internalIncomingRecords/internalIncomingRecordsV2.tsx
+++ b/apps/edr-freight-web/backoffice/src/record-management/components/userIncoming/internalIncomingRecords/internalIncomingRecordsV2.tsx
@@ -2,6 +2,7 @@ import { useState, useEffect, useMemo, useCallback } from "react";
 import { DataTable } from "@/record-management/common/DataTable";
 import { Button } from "@/shared/common/ui/button";
 import { Input } from "@/shared/common/ui/input";
+import { DateRangePicker, parseDay, formatDay } from "@/shared/common/ui/date-range-picker";
 import {
   Select,
   SelectContent,
@@ -326,23 +327,13 @@ const InternalIncomingRecordsV2 = () => {
           ) : (
             <div className="flex flex-col sm:flex-row gap-2">
               {lang.startsWith("en") ? (
-                <>
-                  <label className="mt-2">From: </label>
-                  <Input
-                    type="date"
-                    value={fromDispatchedDate}
-                    onChange={(e) => setFromDispatchedDate(e.target.value)}
-                    className="w-[150px]"
-                  />
-                  <label className="mt-2">To: </label>
-                  <Input
-                    type="date"
-                    value={toDispatchedDate}
-                    onChange={(e) => setToDispatchedDate(e.target.value)}
-                    min={fromDispatchedDate}
-                    className="w-[150px]"
-                  />
-                </>
+                <DateRangePicker
+                  value={{ from: parseDay(fromDispatchedDate), to: parseDay(toDispatchedDate) }}
+                  onChange={(range) => {
+                    setFromDispatchedDate(formatDay(range.from));
+                    setToDispatchedDate(formatDay(range.to));
+                  }}
+                />
               ) : (
                 <div className="flex flex-wrap items-center gap-3">
                   {/* From Date */}
diff --git a/apps/edr-freight-web/backoffice/src/record-management/components/userRecords/userRecords.tsx b/apps/edr-freight-web/backoffice/src/record-management/components/userRecords/userRecords.tsx
index c07e3610e..30df56009 100644
--- a/apps/edr-freight-web/backoffice/src/record-management/components/userRecords/userRecords.tsx
+++ b/apps/edr-freight-web/backoffice/src/record-management/components/userRecords/userRecords.tsx
@@ -17,6 +17,7 @@ import {
 } from "@/shared/common/ui/select";
 import { Input } from "@/shared/common/ui/input";
 import { Button } from "@/shared/common/ui/button";
+import { DateRangePicker, parseDay, formatDay } from "@/shared/common/ui/date-range-picker";
 import { Badge } from "@/shared/common/ui/badge";
 import { AdvancedTable } from "@/shared/common/ui/table/AdvancedTable";
 import { useLocalizedName } from "@/shared/common/localizedName";
@@ -521,29 +522,13 @@ const UserRecords = () => {
               {selectedFilter?.type === "dateRange" ? (
                 <div className="flex flex-col sm:flex-row gap-2">
                   {lang.startsWith("en") ? (
-                    <>
-                      <label className="mt-2">From: </label>
-                      <Input
-                        type="date"
-                        value={fromDate}
-                        onChange={(e) => setFromDate(e.target.value)}
-                        onKeyDown={(e) => {
-                          if (e.key === "Enter") handleAddFilter();
-                        }}
-                        className="w-[150px]"
-                      />
-                      <label className="mt-2">To: </label>
-                      <Input
-                        type="date"
-                        value={toDate}
-                        onChange={(e) => setToDate(e.target.value)}
-                        onKeyDown={(e) => {
-                          if (e.key === "Enter") handleAddFilter();
-                        }}
-                        min={fromDate}
-                        className="w-[150px]"
-                      />
-                    </>
+                    <DateRangePicker
+                      value={{ from: parseDay(fromDate), to: parseDay(toDate) }}
+                      onChange={(range) => {
+                        setFromDate(formatDay(range.from));
+                        setToDate(formatDay(range.to));
+                      }}
+                    />
                   ) : (
                     <div className="flex flex-wrap items-center gap-3">
                       <div className="relative">
diff --git a/apps/edr-freight-web/backoffice/src/shared/common/ui/date-range-picker.tsx b/apps/edr-freight-web/backoffice/src/shared/common/ui/date-range-picker.tsx
new file mode 100644
index 000000000..07df09353
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/shared/common/ui/date-range-picker.tsx
@@ -0,0 +1,197 @@
+import * as React from "react";
+import { CalendarIcon, ChevronDown } from "lucide-react";
+import {
+  format,
+  isSameDay,
+  isSameYear,
+  startOfDay,
+  endOfDay,
+  startOfMonth,
+  endOfMonth,
+  startOfYear,
+  subDays,
+  subMonths,
+} from "date-fns";
+
+import { cn } from "@/shared/lib/utils";
+import { Button } from "@/shared/common/ui/button";
+import { Calendar } from "@/shared/common/ui/calendar";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/shared/common/ui/popover";
+
+export interface DateRangeValue {
+  from?: Date;
+  to?: Date;
+}
+
+/** Parse a `YYYY-MM-DD` string as a local calendar day (avoids the UTC-midnight timezone shift `new Date(str)` has). */
+export function parseDay(value?: string | null): Date | undefined {
+  if (!value) return undefined;
+  const [y, m, d] = value.split("-").map(Number);
+  if (!y || !m || !d) return undefined;
+  return new Date(y, m - 1, d);
+}
+
+/** Format a `Date` back to `YYYY-MM-DD`, for call sites still storing plain date strings. */
+export function formatDay(date?: Date): string {
+  return date ? format(date, "yyyy-MM-dd") : "";
+}
+
+interface DateRangePreset {
+  label: string;
+  range: () => DateRangeValue;
+}
+
+const DEFAULT_PRESETS: DateRangePreset[] = [
+  { label: "Today", range: () => ({ from: startOfDay(new Date()), to: endOfDay(new Date()) }) },
+  {
+    label: "Yesterday",
+    range: () => ({ from: startOfDay(subDays(new Date(), 1)), to: endOfDay(subDays(new Date(), 1)) }),
+  },
+  { label: "Last 7 days", range: () => ({ from: startOfDay(subDays(new Date(), 6)), to: endOfDay(new Date()) }) },
+  { label: "Last 30 days", range: () => ({ from: startOfDay(subDays(new Date(), 29)), to: endOfDay(new Date()) }) },
+  { label: "This month", range: () => ({ from: startOfMonth(new Date()), to: endOfDay(new Date()) }) },
+  {
+    label: "Last month",
+    range: () => ({
+      from: startOfMonth(subMonths(new Date(), 1)),
+      to: endOfMonth(subMonths(new Date(), 1)),
+    }),
+  },
+  { label: "Year to date", range: () => ({ from: startOfYear(new Date()), to: endOfDay(new Date()) }) },
+];
+
+function formatRangeLabel(value?: DateRangeValue, placeholder = "Select date range") {
+  if (!value?.from) return placeholder;
+  if (!value.to || isSameDay(value.from, value.to)) {
+    return format(value.from, "MMM d, y");
+  }
+  if (isSameYear(value.from, value.to)) {
+    return `${format(value.from, "MMM d")} – ${format(value.to, "MMM d, y")}`;
+  }
+  return `${format(value.from, "MMM d, y")} – ${format(value.to, "MMM d, y")}`;
+}
+
+interface DateRangePickerProps {
+  value?: DateRangeValue;
+  onChange?: (range: DateRangeValue) => void;
+  presets?: DateRangePreset[];
+  placeholder?: string;
+  numberOfMonths?: number;
+  className?: string;
+  align?: "start" | "center" | "end";
+  disabled?: boolean;
+}
+
+export function DateRangePicker({
+  value,
+  onChange,
+  presets = DEFAULT_PRESETS,
+  placeholder = "Select date range",
+  numberOfMonths = 2,
+  className,
+  align = "start",
+  disabled = false,
+}: DateRangePickerProps) {
+  const [open, setOpen] = React.useState(false);
+  const [draft, setDraft] = React.useState<DateRangeValue | undefined>(value);
+
+  // Reset the draft to the committed value each time the popover opens
+  React.useEffect(() => {
+    if (open) setDraft(value);
+  }, [open, value]);
+
+  const activePresetLabel = React.useMemo(() => {
+    if (!draft?.from || !draft?.to) return null;
+    const match = presets.find((preset) => {
+      const r = preset.range();
+      return r.from && r.to && isSameDay(r.from, draft.from!) && isSameDay(r.to, draft.to!);
+    });
+    return match?.label ?? null;
+  }, [draft, presets]);
+
+  function applyPreset(preset: DateRangePreset) {
+    const range = preset.range();
+    setDraft(range);
+    onChange?.(range);
+    setOpen(false);
+  }
+
+  function handleApply() {
+    if (draft?.from) onChange?.({ from: draft.from, to: draft.to ?? draft.from });
+    setOpen(false);
+  }
+
+  function handleCancel() {
+    setDraft(value);
+    setOpen(false);
+  }
+
+  return (
+    <Popover open={open && !disabled} onOpenChange={(next: boolean) => setOpen(next && !disabled)}>
+      <PopoverTrigger asChild>
+        <Button
+          type="button"
+          variant="outline"
+          disabled={disabled}
+          className={cn(
+            "min-w-[240px] justify-start gap-2 font-normal text-slate-700 dark:text-slate-200",
+            !value?.from && "text-slate-500 dark:text-slate-400",
+            className,
+          )}
+        >
+          <CalendarIcon className="size-4 text-slate-500 dark:text-slate-400" />
+          <span className="flex-1 text-left">{formatRangeLabel(value, placeholder)}</span>
+          <ChevronDown className="size-4 text-slate-400" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent align={align} className="w-auto p-0">
+        <div className="flex flex-col sm:flex-row">
+          <div className="flex shrink-0 flex-col gap-0.5 border-b p-2 sm:border-b-0 sm:border-r sm:w-[160px]">
+            {presets.map((preset) => (
+              <button
+                key={preset.label}
+                type="button"
+                onClick={() => applyPreset(preset)}
+                className={cn(
+                  "rounded-md px-2.5 py-1.5 text-left text-sm font-medium text-slate-600 hover:bg-slate-100 dark:text-slate-300 dark:hover:bg-slate-800",
+                  activePresetLabel === preset.label &&
+                    "bg-primary-50 text-primary-700 hover:bg-primary-50 dark:bg-primary-900/30 dark:text-primary-300",
+                )}
+              >
+                {preset.label}
+              </button>
+            ))}
+          </div>
+
+          <div className="flex flex-col">
+            <Calendar
+              mode="range"
+              selected={draft}
+              onSelect={(range: DateRangeValue | undefined) => setDraft(range ?? undefined)}
+              numberOfMonths={numberOfMonths}
+              defaultMonth={draft?.from ?? value?.from}
+              className="border-none shadow-none"
+            />
+            <div className="flex items-center justify-between gap-3 border-t p-3">
+              <span className="text-sm text-slate-500 dark:text-slate-400">
+                {formatRangeLabel(draft, "No dates selected")}
+              </span>
+              <div className="flex gap-2">
+                <Button variant="ghost" size="sm" onClick={handleCancel}>
+                  Cancel
+                </Button>
+                <Button size="sm" disabled={!draft?.from} onClick={handleApply}>
+                  Apply
+                </Button>
+              </div>
+            </div>
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/shared/components/activity-log/activity-filters.tsx b/apps/edr-freight-web/backoffice/src/shared/components/activity-log/activity-filters.tsx
index f1dc6a849..61e4a2a3b 100644
--- a/apps/edr-freight-web/backoffice/src/shared/components/activity-log/activity-filters.tsx
+++ b/apps/edr-freight-web/backoffice/src/shared/components/activity-log/activity-filters.tsx
@@ -1,6 +1,5 @@
 'use client'
 
-import { useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import { Input } from '@/shared/common/ui/input'
 import {
@@ -11,14 +10,8 @@ import {
 	SelectValue,
 } from '@/shared/common/ui/select'
 import { Button } from '@/shared/common/ui/button'
-import {
-	Popover,
-	PopoverContent,
-	PopoverTrigger,
-} from '@/shared/common/ui/popover'
-import { Calendar } from '@/shared/common/ui/calendar'
-import { Search, Filter, CalendarIcon, X } from 'lucide-react'
-import { format } from 'date-fns'
+import { DateRangePicker } from '@/shared/common/ui/date-range-picker'
+import { Search, Filter, X } from 'lucide-react'
 import { cn } from '@/shared/lib/utils'
 
 interface ActivityFiltersProps {
@@ -53,7 +46,6 @@ export function ActivityFilters({
 	onClearFilters,
 }: ActivityFiltersProps) {
 	const { t } = useTranslation()
-	const [datePickerOpen, setDatePickerOpen] = useState(false)
 
 	const textStrong = 'text-gray-900 dark:text-gray-100'
 	const textMuted = 'text-gray-500 dark:text-gray-400'
@@ -168,92 +160,11 @@ export function ActivityFilters({
 			</div>
 
 			<div className="flex items-center gap-4">
-				<Popover open={datePickerOpen} onOpenChange={setDatePickerOpen}>
-					<PopoverTrigger asChild>
-						<Button
-							variant="outline"
-							className={cn(
-								'w-full md:w-auto justify-start text-left font-normal',
-								border,
-								surface,
-								textStrong,
-							)}
-						>
-							<CalendarIcon
-								className={cn('mr-2 h-4 w-4', textMuted)}
-							/>
-							{dateRange.from ? (
-								dateRange.to ? (
-									<>
-										{format(dateRange.from, 'LLL dd, y')} -{' '}
-										{format(dateRange.to, 'LLL dd, y')}
-									</>
-								) : (
-									format(dateRange.from, 'LLL dd, y')
-								)
-							) : (
-								<span className={textMuted}>
-									{t('auditLog.filters.dateRange')}
-								</span>
-							)}
-						</Button>
-					</PopoverTrigger>
-					<PopoverContent
-						className={cn('w-auto p-0', border, surface)}
-						align="start"
-					>
-						<Calendar
-							initialFocus
-							mode="range"
-							defaultMonth={dateRange.from}
-							selected={{
-								from: dateRange.from,
-								to: dateRange.to,
-							}}
-							onSelect={(range) => {
-								onDateRangeChange({
-									from: range?.from,
-									to: range?.to,
-								})
-							}}
-							numberOfMonths={2}
-						/>
-					</PopoverContent>
-				</Popover>
-
-				<Button
-					variant="outline"
-					onClick={() => {
-						const today = new Date()
-						const last7Days = new Date(today)
-						last7Days.setDate(last7Days.getDate() - 7)
-
-						onDateRangeChange({
-							from: last7Days,
-							to: today,
-						})
-					}}
-					className={cn(border, surface, textStrong, hoverText)}
-				>
-					{t('auditLog.filters.last7Days')}
-				</Button>
-
-				<Button
-					variant="outline"
-					onClick={() => {
-						const today = new Date()
-						const last30Days = new Date(today)
-						last30Days.setDate(last30Days.getDate() - 30)
-
-						onDateRangeChange({
-							from: last30Days,
-							to: today,
-						})
-					}}
-					className={cn(border, surface, textStrong, hoverText)}
-				>
-					{t('auditLog.filters.last30Days')}
-				</Button>
+				<DateRangePicker
+					value={dateRange}
+					onChange={onDateRangeChange}
+					placeholder={t('auditLog.filters.dateRange')}
+				/>
 			</div>
 		</div>
 	)
diff --git a/apps/edr-freight-web/backoffice/src/shared/components/filters/CombinedFilterBar.tsx b/apps/edr-freight-web/backoffice/src/shared/components/filters/CombinedFilterBar.tsx
index 1ec063e4e..f21a86a61 100644
--- a/apps/edr-freight-web/backoffice/src/shared/components/filters/CombinedFilterBar.tsx
+++ b/apps/edr-freight-web/backoffice/src/shared/components/filters/CombinedFilterBar.tsx
@@ -8,6 +8,7 @@ import EthiopianDatePickerModal, {
 import { Badge } from "@/shared/common/ui/badge";
 import { Button } from "@/shared/common/ui/button";
 import { Input } from "@/shared/common/ui/input";
+import { DateRangePicker, parseDay, formatDay } from "@/shared/common/ui/date-range-picker";
 import {
   Select,
   SelectContent,
@@ -225,29 +226,13 @@ export function CombinedFilterBar({
         {selectedFilter?.type === "dateRange" ? (
           <div className="flex flex-col sm:flex-row gap-2">
             {lang.startsWith("en") ? (
-              <>
-                <label className="mt-2">From: </label>
-                <Input
-                  type="date"
-                  value={fromDate}
-                  onChange={(event) => setFromDate(event.target.value)}
-                  onKeyDown={(event) => {
-                    if (event.key === "Enter") addFilter();
-                  }}
-                  className="w-[150px]"
-                />
-                <label className="mt-2">To: </label>
-                <Input
-                  type="date"
-                  value={toDate}
-                  onChange={(event) => setToDate(event.target.value)}
-                  onKeyDown={(event) => {
-                    if (event.key === "Enter") addFilter();
-                  }}
-                  min={fromDate}
-                  className="w-[150px]"
-                />
-              </>
+              <DateRangePicker
+                value={{ from: parseDay(fromDate), to: parseDay(toDate) }}
+                onChange={(range) => {
+                  setFromDate(formatDay(range.from));
+                  setToDate(formatDay(range.to));
+                }}
+              />
             ) : (
               <div className="flex flex-wrap items-center gap-3">
                 <div className="relative">

From efc5a2438030c41fa5f7c6551fdb19f82faf48d6 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 08:34:08 +0000
Subject: [PATCH 071/174] feat(reports): add optional chart view to the report
 engine
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ReportDefinition gets an optional chart {type: line|bar, x, y[]} field —
plots the same rows the table gets, no separate query. Frontend adds a
table/chart toggle (defaults to table) using the existing recharts
dependency, no new package.

Chart view fetches up to 100 rows (the API's page-size ceiling) instead
of the table's current page, so it doesn't silently plot a fraction of
the filtered set; shows a truncation note past that cap.

Wired onto 5 reports as proof: wagon-fleet-status, locomotive-fleet-
status, booking-status-breakdown, revenue-summary (bar), and
global-logistics-wagons (line). Everything else stays table-only —
charting is opt-in per report, not a default.
---
 .../booking-status-breakdown.report.ts        |  1 +
 .../global-logistics-wagons.report.ts         |  1 +
 .../locomotive-fleet-status.report.ts         |  1 +
 .../definitions/revenue-summary.report.ts     |  1 +
 .../definitions/wagon-fleet-status.report.ts  |  1 +
 .../modules/reports/report.registry.spec.ts   | 11 +++
 .../src/modules/reports/report.types.ts       | 17 ++++
 .../src/components/reports/ReportChart.tsx    | 83 +++++++++++++++++++
 .../src/components/reports/ReportView.tsx     | 80 +++++++++++-------
 .../backoffice/src/types/reports.ts           |  9 ++
 10 files changed, 175 insertions(+), 30 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/reports/ReportChart.tsx

diff --git a/apps/edr-freight-api/src/modules/reports/definitions/booking-status-breakdown.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/booking-status-breakdown.report.ts
index a01f714ec..449c47181 100644
--- a/apps/edr-freight-api/src/modules/reports/definitions/booking-status-breakdown.report.ts
+++ b/apps/edr-freight-api/src/modules/reports/definitions/booking-status-breakdown.report.ts
@@ -77,6 +77,7 @@ export const bookingStatusBreakdownReport: ReportDefinition = {
     { key: 'amount', label: 'Amount', type: 'money', sortable: true },
   ],
   defaultSort: { key: 'bookings', dir: 'DESC' },
+  chart: { type: 'bar', x: 'status', y: ['bookings'] },
   query(ctx) {
     return baseQuery(ctx)
       .select('b.status', 'status')
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/global-logistics-wagons.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/global-logistics-wagons.report.ts
index e23ce5469..d3fd759f7 100644
--- a/apps/edr-freight-api/src/modules/reports/definitions/global-logistics-wagons.report.ts
+++ b/apps/edr-freight-api/src/modules/reports/definitions/global-logistics-wagons.report.ts
@@ -46,6 +46,7 @@ export const globalLogisticsWagonsReport: ReportDefinition = {
     { key: 'cancelled', label: 'Cancelled', type: 'number', sortable: true },
   ],
   defaultSort: { key: 'date', dir: 'DESC' },
+  chart: { type: 'line', x: 'date', y: ['allocated', 'cancelled'] },
   query(ctx) {
     return baseQuery(ctx)
       .select(`to_char(date_trunc('day', l.occurred_at), 'YYYY-MM-DD')`, 'date')
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/locomotive-fleet-status.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/locomotive-fleet-status.report.ts
index f2b9377f6..cf971cf2c 100644
--- a/apps/edr-freight-api/src/modules/reports/definitions/locomotive-fleet-status.report.ts
+++ b/apps/edr-freight-api/src/modules/reports/definitions/locomotive-fleet-status.report.ts
@@ -32,6 +32,7 @@ export const locomotiveFleetStatusReport: ReportDefinition = {
     { key: 'count', label: 'Count', type: 'number', sortable: true },
   ],
   defaultSort: { key: 'count', dir: 'DESC' },
+  chart: { type: 'bar', x: 'status', y: ['count'] },
   query(ctx) {
     return baseQuery(ctx)
       .select('l.locomotive_type', 'locomotiveType')
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/revenue-summary.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/revenue-summary.report.ts
index 684d4e2e5..512e05be8 100644
--- a/apps/edr-freight-api/src/modules/reports/definitions/revenue-summary.report.ts
+++ b/apps/edr-freight-api/src/modules/reports/definitions/revenue-summary.report.ts
@@ -37,6 +37,7 @@ export const revenueSummaryReport: ReportDefinition = {
     { key: 'revenue', label: 'Revenue', type: 'money', sortable: true },
   ],
   defaultSort: { key: 'revenue', dir: 'DESC' },
+  chart: { type: 'bar', x: 'direction', y: ['revenue'] },
   query(ctx) {
     return baseQuery(ctx)
       .select('b.trade_direction', 'direction')
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/wagon-fleet-status.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/wagon-fleet-status.report.ts
index 1371936f5..8855c491b 100644
--- a/apps/edr-freight-api/src/modules/reports/definitions/wagon-fleet-status.report.ts
+++ b/apps/edr-freight-api/src/modules/reports/definitions/wagon-fleet-status.report.ts
@@ -38,6 +38,7 @@ export const wagonFleetStatusReport: ReportDefinition = {
     { key: 'count', label: 'Count', type: 'number', sortable: true },
   ],
   defaultSort: { key: 'count', dir: 'DESC' },
+  chart: { type: 'bar', x: 'status', y: ['count'] },
   query(ctx) {
     return baseQuery(ctx)
       .select('COALESCE(wt.name, \'Unknown\')', 'wagonType')
diff --git a/apps/edr-freight-api/src/modules/reports/report.registry.spec.ts b/apps/edr-freight-api/src/modules/reports/report.registry.spec.ts
index 84bbfb27a..ccec53c3d 100644
--- a/apps/edr-freight-api/src/modules/reports/report.registry.spec.ts
+++ b/apps/edr-freight-api/src/modules/reports/report.registry.spec.ts
@@ -38,4 +38,15 @@ describe('REPORTS', () => {
       expect(def.filters.some((f) => f.key === def.idKey!.key)).toBe(false);
     }
   });
+
+  it('chart.x and chart.y, when declared, point at real column keys', () => {
+    for (const def of REPORTS) {
+      if (!def.chart) continue;
+      const columnKeys = new Set(def.columns.map((c) => c.key));
+      expect(columnKeys.has(def.chart.x)).toBe(true);
+      for (const y of def.chart.y) {
+        expect(columnKeys.has(y)).toBe(true);
+      }
+    }
+  });
 });
diff --git a/apps/edr-freight-api/src/modules/reports/report.types.ts b/apps/edr-freight-api/src/modules/reports/report.types.ts
index 85b73040c..a709ac654 100644
--- a/apps/edr-freight-api/src/modules/reports/report.types.ts
+++ b/apps/edr-freight-api/src/modules/reports/report.types.ts
@@ -42,6 +42,21 @@ export interface ReportKpi {
   unit?: string;
 }
 
+export type ReportChartType = 'line' | 'bar';
+
+/**
+ * Plots the SAME rows the table gets — no separate query. `x` and `y` are
+ * column keys from `columns`. A report whose group-by has dimensions beyond
+ * `x` will render one mark per row (e.g. two rows sharing a date because they
+ * differ by direction), which is a busier chart, not a wrong one. Pivoting
+ * rows into one-per-x series is a later add if a report actually needs it.
+ */
+export interface ReportChartDef {
+  type: ReportChartType;
+  x: string;
+  y: string[];
+}
+
 /**
  * Optional entity scope a report can be embedded against — e.g. a
  * contract-utilization report shown on a single contract's detail page.
@@ -73,6 +88,8 @@ export interface ReportDefinition {
   query(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral>;
   /** KPIs over the same filtered set; shown above the table and in exports. */
   summary?(ctx: ReportContext): Promise<ReportKpi[]>;
+  /** Optional chart view of the same rows. Table remains the default view. */
+  chart?: ReportChartDef;
 }
 
 /** Catalog shape served by GET /reports — metadata only, no rows. */
diff --git a/apps/edr-freight-web/backoffice/src/components/reports/ReportChart.tsx b/apps/edr-freight-web/backoffice/src/components/reports/ReportChart.tsx
new file mode 100644
index 000000000..0be5384be
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/reports/ReportChart.tsx
@@ -0,0 +1,83 @@
+import { Box, Text } from "@mantine/core";
+import {
+  Bar,
+  BarChart,
+  CartesianGrid,
+  Legend,
+  Line,
+  LineChart,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from "recharts";
+
+import { overviewChartColors } from "@/components/overview/overview.styles";
+import type { ReportChartDef, ReportColumn } from "@/types/reports";
+
+import { formatReportCell } from "./report-format";
+
+interface ReportChartProps {
+  chart: ReportChartDef;
+  items: Record<string, unknown>[];
+  columns: ReportColumn[];
+  /** Filtered row count on the server. Chart is capped at 100 rows (the API's
+   * page-size ceiling) — surface it plainly rather than silently truncate. */
+  total?: number;
+}
+
+const COLORS = overviewChartColors.pipeline;
+
+/** Plots the same rows the table gets — chart.x/chart.y are just column keys. */
+export function ReportChart({ chart, items, columns, total }: ReportChartProps) {
+  const columnByKey = new Map(columns.map((c) => [c.key, c]));
+  const yLabel = (key: string) => columnByKey.get(key)?.label ?? key;
+  const yType = (key: string) => columnByKey.get(key)?.type ?? "number";
+
+  if (!items.length) {
+    return (
+      <Text size="sm" c="dimmed" ta="center" py="xl">
+        No data for the selected filters.
+      </Text>
+    );
+  }
+
+  const Chart = chart.type === "line" ? LineChart : BarChart;
+
+  const truncated = typeof total === "number" && total > items.length;
+
+  return (
+    <Box px="md" pb="md">
+      {truncated ? (
+        <Text size="xs" c="dimmed" mb="xs">
+          Showing first {items.length} of {total} rows. Narrow the filters to see the rest charted.
+        </Text>
+      ) : null}
+      <ResponsiveContainer width="100%" height={320}>
+        <Chart data={items} margin={{ top: 8, right: 16, left: 0, bottom: 24 }}>
+          <CartesianGrid strokeDasharray="3 3" stroke="#e5e7eb" />
+          <XAxis
+            dataKey={chart.x}
+            tick={{ fontSize: 11 }}
+            angle={-20}
+            textAnchor="end"
+            height={50}
+            stroke="#94a3b8"
+          />
+          <YAxis tick={{ fontSize: 12 }} stroke="#94a3b8" />
+          <Tooltip formatter={(value, name) => [formatReportCell(value, yType(String(name))), yLabel(String(name))]} />
+          {chart.y.length > 1 ? <Legend formatter={(name) => yLabel(String(name))} /> : null}
+          {chart.y.map((key, i) =>
+            chart.type === "line" ? (
+              <Line key={key} type="monotone" dataKey={key} stroke={COLORS[i % COLORS.length]} strokeWidth={2} dot={false} />
+            ) : (
+              <Bar key={key} dataKey={key} fill={COLORS[i % COLORS.length]} radius={[4, 4, 0, 0]} />
+            ),
+          )}
+        </Chart>
+      </ResponsiveContainer>
+    </Box>
+  );
+}
+
+export default ReportChart;
diff --git a/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx b/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx
index 0e28cd5fe..b1c5822fc 100644
--- a/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx
@@ -1,8 +1,8 @@
-import { ActionIcon, Alert, Box, Card, Group, Stack, Text, Tooltip, UnstyledButton } from "@mantine/core";
+import { ActionIcon, Alert, Box, Card, Group, SegmentedControl, Stack, Text, Tooltip, UnstyledButton } from "@mantine/core";
 import { useDebouncedValue } from "@mantine/hooks";
 import { useQuery } from "@tanstack/react-query";
 import type { Column, SortingState } from "@tanstack/react-table";
-import { ArrowDown, ArrowUp, ArrowUpDown, FileSpreadsheet, FileText, RefreshCw } from "lucide-react";
+import { ArrowDown, ArrowUp, ArrowUpDown, FileSpreadsheet, FileText, LayoutGrid, LineChart, RefreshCw } from "lucide-react";
 import { useMemo, useState } from "react";
 
 import { KpiStrip } from "@/components/page/KpiStrip";
@@ -11,6 +11,7 @@ import { reportsService } from "@/services/reports.service";
 import type { ReportRunParams } from "@/types/reports";
 import { DataTable, DataTableFooter, usePagination, type ColumnDef } from "@edr/ui-common";
 
+import { ReportChart } from "./ReportChart";
 import { ReportFilters, type ReportFilterValues } from "./ReportFilters";
 import { formatKpiValue, formatReportCell } from "./report-format";
 
@@ -60,20 +61,24 @@ export function ReportView({ reportKey, idKeyValue }: ReportViewProps) {
   const [filterValues, setFilterValues] = useState<ReportFilterValues>({});
   const [debouncedFilters] = useDebouncedValue(filterValues, 300);
   const [exporting, setExporting] = useState<"xlsx" | "pdf" | null>(null);
+  const [view, setView] = useState<"table" | "chart">("table");
 
   const runParams: ReportRunParams | undefined = useMemo(() => {
     if (!def) return undefined;
     const sort = sorting[0];
     return {
       key: def.key,
-      page: pagination.pageIndex + 1,
-      pageSize: pagination.pageSize,
+      // Chart view isn't paginated on screen — pull the server's max page (100)
+      // in one shot instead of just whatever page the table happens to be on,
+      // so the chart doesn't silently plot a fraction of the filtered rows.
+      page: view === "chart" ? 1 : pagination.pageIndex + 1,
+      pageSize: view === "chart" ? 100 : pagination.pageSize,
       sortBy: sort?.id,
       sortOrder: sort ? (sort.desc ? "DESC" : "ASC") : undefined,
       ...debouncedFilters,
       ...(def.idKey && idKeyValue ? { [def.idKey.key]: idKeyValue } : {}),
     };
-  }, [def, pagination, sorting, debouncedFilters, idKeyValue]);
+  }, [def, view, pagination, sorting, debouncedFilters, idKeyValue]);
 
   const { data, isLoading, isError, isFetching, refetch } = useQuery({
     ...api.reports.run.queryOptions({ input: runParams as ReportRunParams }),
@@ -141,6 +146,17 @@ export function ReportView({ reportKey, idKeyValue }: ReportViewProps) {
                 }}
               />
               <Group gap="xs">
+                {def.chart ? (
+                  <SegmentedControl
+                    size="xs"
+                    value={view}
+                    onChange={(v) => setView(v as "table" | "chart")}
+                    data={[
+                      { label: <LayoutGrid size={14} />, value: "table" },
+                      { label: <LineChart size={14} />, value: "chart" },
+                    ]}
+                  />
+                ) : null}
                 <Tooltip label="Export to Excel">
                   <ActionIcon
                     variant="default"
@@ -178,31 +194,35 @@ export function ReportView({ reportKey, idKeyValue }: ReportViewProps) {
             </Group>
           </Box>
 
-          <Box style={{ overflowX: "auto" }} w="100%">
-            <DataTable
-              columns={columns}
-              data={data?.items ?? []}
-              status={isLoading ? "loading" : isError ? "error" : "success"}
-              emptyMessage="No data for the selected filters."
-              error={isError ? { message: "Failed to load report.", onRetry: () => void refetch() } : undefined}
-              pagination={{
-                pageIndex: pagination.pageIndex,
-                pageSize: pagination.pageSize,
-                pageCount,
-                totalCount: total,
-              }}
-              tableOptions={{
-                state: { sorting },
-                onSortingChange: setSorting,
-                onPaginationChange: setPagination,
-                manualPagination: true,
-                manualSorting: true,
-                pageCount,
-              }}
-              containerClassName="border-0 shadow-none bg-transparent"
-              footer={DataTableFooter}
-            />
-          </Box>
+          {view === "chart" && def.chart ? (
+            <ReportChart chart={def.chart} items={data?.items ?? []} columns={def.columns} total={total} />
+          ) : (
+            <Box style={{ overflowX: "auto" }} w="100%">
+              <DataTable
+                columns={columns}
+                data={data?.items ?? []}
+                status={isLoading ? "loading" : isError ? "error" : "success"}
+                emptyMessage="No data for the selected filters."
+                error={isError ? { message: "Failed to load report.", onRetry: () => void refetch() } : undefined}
+                pagination={{
+                  pageIndex: pagination.pageIndex,
+                  pageSize: pagination.pageSize,
+                  pageCount,
+                  totalCount: total,
+                }}
+                tableOptions={{
+                  state: { sorting },
+                  onSortingChange: setSorting,
+                  onPaginationChange: setPagination,
+                  manualPagination: true,
+                  manualSorting: true,
+                  pageCount,
+                }}
+                containerClassName="border-0 shadow-none bg-transparent"
+                footer={DataTableFooter}
+              />
+            </Box>
+          )}
         </Stack>
       </Card>
     </Stack>
diff --git a/apps/edr-freight-web/backoffice/src/types/reports.ts b/apps/edr-freight-web/backoffice/src/types/reports.ts
index 854b1a801..8bdd6bd23 100644
--- a/apps/edr-freight-web/backoffice/src/types/reports.ts
+++ b/apps/edr-freight-web/backoffice/src/types/reports.ts
@@ -38,6 +38,14 @@ export interface ReportKpi {
   unit?: string;
 }
 
+export type ReportChartType = "line" | "bar";
+
+export interface ReportChartDef {
+  type: ReportChartType;
+  x: string;
+  y: string[];
+}
+
 /** Mirrors the backend's ReportCatalogEntry — one entry per GET /reports item. */
 export interface ReportCatalogEntry {
   key: string;
@@ -49,6 +57,7 @@ export interface ReportCatalogEntry {
   columns: ReportColumn[];
   defaultSort?: { key: string; dir: "ASC" | "DESC" };
   hasSummary: boolean;
+  chart?: ReportChartDef;
 }
 
 export interface ReportPageMeta {

From 58b47318e9c8f8b304a5d01d484473e0941eb438 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 08:45:29 +0000
Subject: [PATCH 072/174] feat(freight-backoffice): consolidate Mantine from/to
 date filters into range pickers

Replaces every remaining split from/to Mantine DateInput/DatePickerInput pair
with a single DatePickerInput type="range", sharing one preset list (Today,
Last 7/30 days, this/last month, YTD) via getDateRangePresets(). Covers
ListControls (18 consumers), FleetResourcePage, ContractRequestsPage,
BookingRequestsPage (created + scheduled ranges), WagonCancellationsPage,
BatchBoardPage, ClearanceDocumentsPage, ShipmentRequestsPage.

Native Mantine range picker, not the shadcn DateRangePicker, to match each
page's existing design system instead of clashing with it.

Reports date-range filter (ReportFilters.tsx) intentionally left untouched.
---
 .../src/components/common/ListControls.tsx    | 36 +++++------
 .../src/components/common/dateRangePresets.ts | 41 +++++++++++++
 .../pages/bookings/BookingRequestsPage.tsx    | 59 +++++++------------
 .../pages/bookings/WagonCancellationsPage.tsx | 31 ++++------
 .../contracts/ClearanceDocumentsPage.tsx      | 34 ++++-------
 .../pages/contracts/ContractRequestsPage.tsx  | 34 ++++-------
 .../pages/contracts/ShipmentRequestsPage.tsx  | 31 ++++------
 .../src/pages/fleet/FleetResourcePage.tsx     | 28 ++++-----
 .../pages/trainScheduling/BatchBoardPage.tsx  | 28 ++++-----
 9 files changed, 146 insertions(+), 176 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/common/dateRangePresets.ts

diff --git a/apps/edr-freight-web/backoffice/src/components/common/ListControls.tsx b/apps/edr-freight-web/backoffice/src/components/common/ListControls.tsx
index 92ab514ad..8ca604ba4 100644
--- a/apps/edr-freight-web/backoffice/src/components/common/ListControls.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/common/ListControls.tsx
@@ -2,6 +2,7 @@ import { Button, Group, TextInput } from "@mantine/core";
 import { DatePickerInput } from "@mantine/dates";
 import { Search, X } from "lucide-react";
 import type { ReactNode } from "react";
+import { getDateRangePresets } from "./dateRangePresets";
 
 export interface ListControlsProps {
   search: string;
@@ -54,28 +55,19 @@ const ListControls = ({
     )}
 
     {showDateRange && (
-      <>
-        <DatePickerInput
-          label={dateLabel ? `${dateLabel} from` : "From"}
-          placeholder="Any"
-          value={dateFrom}
-          onChange={onDateFromChange}
-          // Cannot start after it ends — the picker refuses the invalid range
-          // instead of silently returning nothing.
-          maxDate={dateTo ?? undefined}
-          clearable
-          w={150}
-        />
-        <DatePickerInput
-          label={dateLabel ? `${dateLabel} to` : "To"}
-          placeholder="Any"
-          value={dateTo}
-          onChange={onDateToChange}
-          minDate={dateFrom ?? undefined}
-          clearable
-          w={150}
-        />
-      </>
+      <DatePickerInput
+        type="range"
+        label={dateLabel ?? "Date range"}
+        placeholder="Any"
+        value={[dateFrom, dateTo]}
+        onChange={([from, to]) => {
+          onDateFromChange(from);
+          onDateToChange(to);
+        }}
+        presets={getDateRangePresets()}
+        clearable
+        w={230}
+      />
     )}
 
     {children}
diff --git a/apps/edr-freight-web/backoffice/src/components/common/dateRangePresets.ts b/apps/edr-freight-web/backoffice/src/components/common/dateRangePresets.ts
new file mode 100644
index 000000000..e59e3bb84
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/common/dateRangePresets.ts
@@ -0,0 +1,41 @@
+import {
+  format,
+  startOfDay,
+  endOfDay,
+  startOfMonth,
+  endOfMonth,
+  startOfYear,
+  subDays,
+  subMonths,
+} from "date-fns";
+import type { DatePickerPreset } from "@mantine/dates";
+
+const iso = (date: Date) => format(date, "yyyy-MM-dd");
+
+/**
+ * Shared "Today / Last 7 days / …" presets for every Mantine
+ * `<DatePickerInput type="range" presets={getDateRangePresets()} />` in the app,
+ * so every from/to filter offers the same shortcuts. Computed fresh per call
+ * (not a module-level constant) so "Today" stays today.
+ */
+export function getDateRangePresets(): DatePickerPreset<"range">[] {
+  const today = new Date();
+  return [
+    { label: "Today", value: [iso(startOfDay(today)), iso(endOfDay(today))] },
+    {
+      label: "Yesterday",
+      value: [iso(startOfDay(subDays(today, 1))), iso(endOfDay(subDays(today, 1)))],
+    },
+    { label: "Last 7 days", value: [iso(startOfDay(subDays(today, 6))), iso(endOfDay(today))] },
+    { label: "Last 30 days", value: [iso(startOfDay(subDays(today, 29))), iso(endOfDay(today))] },
+    { label: "This month", value: [iso(startOfMonth(today)), iso(endOfDay(today))] },
+    {
+      label: "Last month",
+      value: [
+        iso(startOfMonth(subMonths(today, 1))),
+        iso(endOfMonth(subMonths(today, 1))),
+      ],
+    },
+    { label: "Year to date", value: [iso(startOfYear(today)), iso(endOfDay(today))] },
+  ];
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
index 91eb52033..d55c45c3a 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
@@ -13,7 +13,8 @@ import {
   Text,
   TextInput,
 } from "@mantine/core";
-import { DateInput } from "@mantine/dates";
+import { DatePickerInput } from "@mantine/dates";
+import { getDateRangePresets } from "@/components/common/dateRangePresets";
 import { useDebouncedValue } from "@mantine/hooks";
 import {
   AlertTriangle,
@@ -764,53 +765,33 @@ export default function BookingRequestsPage() {
                       radius="lg"
                       style={{ minWidth: 140 }}
                     />
-                    <DateInput
-                      placeholder="Created from"
-                      value={createdFrom}
-                      onChange={(v) => {
-                        setCreatedFrom(v ? new Date(v) : null);
+                    <DatePickerInput
+                      type="range"
+                      placeholder="Created date range"
+                      value={[createdFrom, createdTo]}
+                      onChange={([from, to]) => {
+                        setCreatedFrom(from ? new Date(from) : null);
+                        setCreatedTo(to ? new Date(to) : null);
                         resetPage();
                       }}
-                      maxDate={createdTo ?? undefined}
+                      presets={getDateRangePresets()}
                       clearable
                       radius="lg"
-                      style={{ minWidth: 140 }}
+                      style={{ minWidth: 220 }}
                     />
-                    <DateInput
-                      placeholder="Created to"
-                      value={createdTo}
-                      onChange={(v) => {
-                        setCreatedTo(v ? new Date(v) : null);
+                    <DatePickerInput
+                      type="range"
+                      placeholder="Scheduled date range"
+                      value={[scheduledFrom, scheduledTo]}
+                      onChange={([from, to]) => {
+                        setScheduledFrom(from ? new Date(from) : null);
+                        setScheduledTo(to ? new Date(to) : null);
                         resetPage();
                       }}
-                      minDate={createdFrom ?? undefined}
+                      presets={getDateRangePresets()}
                       clearable
                       radius="lg"
-                      style={{ minWidth: 140 }}
-                    />
-                    <DateInput
-                      placeholder="Scheduled from"
-                      value={scheduledFrom}
-                      onChange={(v) => {
-                        setScheduledFrom(v ? new Date(v) : null);
-                        resetPage();
-                      }}
-                      maxDate={scheduledTo ?? undefined}
-                      clearable
-                      radius="lg"
-                      style={{ minWidth: 150 }}
-                    />
-                    <DateInput
-                      placeholder="Scheduled to"
-                      value={scheduledTo}
-                      onChange={(v) => {
-                        setScheduledTo(v ? new Date(v) : null);
-                        resetPage();
-                      }}
-                      minDate={scheduledFrom ?? undefined}
-                      clearable
-                      radius="lg"
-                      style={{ minWidth: 150 }}
+                      style={{ minWidth: 230 }}
                     />
                     {activeFilterCount > 0 ? (
                       <Button
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/WagonCancellationsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/WagonCancellationsPage.tsx
index fff83d479..b1b4ef3ca 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/WagonCancellationsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/WagonCancellationsPage.tsx
@@ -11,7 +11,8 @@ import {
   Text,
   TextInput,
 } from "@mantine/core";
-import { DateInput } from "@mantine/dates";
+import { DatePickerInput } from "@mantine/dates";
+import { getDateRangePresets } from "@/components/common/dateRangePresets";
 import { useDebouncedValue } from "@mantine/hooks";
 import { useMutation, useQuery } from "@tanstack/react-query";
 import { Search, XCircle } from "lucide-react";
@@ -304,29 +305,19 @@ export default function WagonCancellationsPage() {
                 w={190}
                 radius="md"
               />
-              <DateInput
-                placeholder="From"
-                value={from}
-                onChange={(v) => {
-                  setFrom(v ? new Date(v) : null);
+              <DatePickerInput
+                type="range"
+                placeholder="Date range"
+                value={[from, to]}
+                onChange={([newFrom, newTo]) => {
+                  setFrom(newFrom ? new Date(newFrom) : null);
+                  setTo(newTo ? new Date(newTo) : null);
                   resetPage();
                 }}
-                maxDate={to ?? undefined}
+                presets={getDateRangePresets()}
                 clearable
                 radius="md"
-                style={{ minWidth: 140 }}
-              />
-              <DateInput
-                placeholder="To"
-                value={to}
-                onChange={(v) => {
-                  setTo(v ? new Date(v) : null);
-                  resetPage();
-                }}
-                minDate={from ?? undefined}
-                clearable
-                radius="md"
-                style={{ minWidth: 140 }}
+                style={{ minWidth: 220 }}
               />
               <Button
                 variant="subtle"
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx
index ca4ed18ce..197e947a5 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx
@@ -10,7 +10,8 @@ import {
   TextInput,
   ThemeIcon,
 } from "@mantine/core";
-import { DateInput } from "@mantine/dates";
+import { DatePickerInput } from "@mantine/dates";
+import { getDateRangePresets } from "@/components/common/dateRangePresets";
 import { useDebouncedValue } from "@mantine/hooks";
 import { keepPreviousData, useQuery } from "@tanstack/react-query";
 import { FileText, Inbox, RefreshCw, Search, User, X } from "lucide-react";
@@ -348,31 +349,20 @@ export default function ClearanceDocumentsPage() {
                   style={{ minWidth: 140 }}
                   aria-label="Filter by ownership"
                 />
-                <DateInput
-                  placeholder="Created from"
-                  value={createdFrom}
-                  onChange={(v) => {
-                    setCreatedFrom(v ? new Date(v) : null);
+                <DatePickerInput
+                  type="range"
+                  placeholder="Created date range"
+                  value={[createdFrom, createdTo]}
+                  onChange={([from, to]) => {
+                    setCreatedFrom(from ? new Date(from) : null);
+                    setCreatedTo(to ? new Date(to) : null);
                     resetPage();
                   }}
-                  maxDate={createdTo ?? undefined}
+                  presets={getDateRangePresets()}
                   clearable
                   radius="lg"
-                  style={{ minWidth: 140 }}
-                  aria-label="Created from"
-                />
-                <DateInput
-                  placeholder="Created to"
-                  value={createdTo}
-                  onChange={(v) => {
-                    setCreatedTo(v ? new Date(v) : null);
-                    resetPage();
-                  }}
-                  minDate={createdFrom ?? undefined}
-                  clearable
-                  radius="lg"
-                  style={{ minWidth: 140 }}
-                  aria-label="Created to"
+                  style={{ minWidth: 220 }}
+                  aria-label="Created date range"
                 />
               </Group>
             </Box>
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
index 3ff989bb5..dfbb26d25 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
@@ -13,7 +13,8 @@ import {
   TextInput,
   ThemeIcon,
 } from "@mantine/core";
-import { DateInput } from "@mantine/dates";
+import { DatePickerInput } from "@mantine/dates";
+import { getDateRangePresets } from "@/components/common/dateRangePresets";
 import { useDebouncedValue } from "@mantine/hooks";
 import {
   AlertTriangle,
@@ -613,31 +614,20 @@ export default function ContractRequestsPage() {
                     style={{ minWidth: 140 }}
                     aria-label="Filter by payment currency"
                   />
-                  <DateInput
-                    placeholder="Created from"
-                    value={createdFrom}
-                    onChange={(v) => {
-                      setCreatedFrom(v ? new Date(v) : null);
+                  <DatePickerInput
+                    type="range"
+                    placeholder="Created date range"
+                    value={[createdFrom, createdTo]}
+                    onChange={([from, to]) => {
+                      setCreatedFrom(from ? new Date(from) : null);
+                      setCreatedTo(to ? new Date(to) : null);
                       resetPage();
                     }}
-                    maxDate={createdTo ?? undefined}
+                    presets={getDateRangePresets()}
                     clearable
                     radius="lg"
-                    style={{ minWidth: 140 }}
-                    aria-label="Created from"
-                  />
-                  <DateInput
-                    placeholder="Created to"
-                    value={createdTo}
-                    onChange={(v) => {
-                      setCreatedTo(v ? new Date(v) : null);
-                      resetPage();
-                    }}
-                    minDate={createdFrom ?? undefined}
-                    clearable
-                    radius="lg"
-                    style={{ minWidth: 140 }}
-                    aria-label="Created to"
+                    style={{ minWidth: 220 }}
+                    aria-label="Created date range"
                   />
                   {activeFilterCount > 0 ? (
                     <Button
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ShipmentRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ShipmentRequestsPage.tsx
index 4eb93cafd..81b037ae6 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ShipmentRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ShipmentRequestsPage.tsx
@@ -17,7 +17,8 @@ import {
   Textarea,
   TextInput,
 } from "@mantine/core";
-import { DateInput } from "@mantine/dates";
+import { DatePickerInput } from "@mantine/dates";
+import { getDateRangePresets } from "@/components/common/dateRangePresets";
 import {
   ArrowUpDown,
   FilterX,
@@ -460,25 +461,19 @@ export default function ShipmentRequestsPage() {
                 allowDeselect={false}
                 aria-label="Cargo type"
               />
-              <DateInput
+              <DatePickerInput
+                type="range"
                 radius="md"
-                w={150}
-                placeholder="Preferred from"
-                value={preferredFrom}
-                onChange={(v) => setPreferredFrom(v ? new Date(v) : null)}
-                maxDate={preferredTo ?? undefined}
+                w={230}
+                placeholder="Preferred date range"
+                value={[preferredFrom, preferredTo]}
+                onChange={([from, to]) => {
+                  setPreferredFrom(from ? new Date(from) : null);
+                  setPreferredTo(to ? new Date(to) : null);
+                }}
+                presets={getDateRangePresets()}
                 clearable
-                aria-label="Preferred date from"
-              />
-              <DateInput
-                radius="md"
-                w={150}
-                placeholder="Preferred to"
-                value={preferredTo}
-                onChange={(v) => setPreferredTo(v ? new Date(v) : null)}
-                minDate={preferredFrom ?? undefined}
-                clearable
-                aria-label="Preferred date to"
+                aria-label="Preferred date range"
               />
               <Select
                 radius="md"
diff --git a/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx b/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
index 06d9a20ab..d837ee712 100644
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
@@ -1,6 +1,7 @@
 import type { ColumnDef } from "@edr/ui-common";
 import { Box, Button, Card, Container, Group, Modal, Select, Stack, Text, TextInput, Title } from "@mantine/core";
 import { DatePickerInput } from "@mantine/dates";
+import { getDateRangePresets } from "@/components/common/dateRangePresets";
 import { keepPreviousData, useMutation, useQuery } from "@tanstack/react-query";
 
 import { api } from "@/services/api";
@@ -613,26 +614,19 @@ const FleetResourcePage = () => {
               filters={
                 <Group gap="sm" wrap="wrap" align="center">
                   <DatePickerInput
-                    aria-label="Created from"
-                    placeholder="Created from"
-                    value={dateFrom}
-                    onChange={setDateFrom}
-                    maxDate={dateTo ?? undefined}
+                    type="range"
+                    aria-label="Created date range"
+                    placeholder="Created date range"
+                    value={[dateFrom, dateTo]}
+                    onChange={([from, to]) => {
+                      setDateFrom(from);
+                      setDateTo(to);
+                    }}
+                    presets={getDateRangePresets()}
                     clearable
                     size="sm"
                     radius="lg"
-                    w={160}
-                  />
-                  <DatePickerInput
-                    aria-label="Created to"
-                    placeholder="Created to"
-                    value={dateTo}
-                    onChange={setDateTo}
-                    minDate={dateFrom ?? undefined}
-                    clearable
-                    size="sm"
-                    radius="lg"
-                    w={160}
+                    w={240}
                   />
                 {listFilterSelects ? (
                   <Group gap="sm" wrap="wrap" align="center">
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/BatchBoardPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/BatchBoardPage.tsx
index 6520c208e..3d77c1fc0 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/BatchBoardPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/BatchBoardPage.tsx
@@ -19,7 +19,8 @@ import {
   ThemeIcon,
   Tooltip,
 } from "@mantine/core";
-import { DateInput } from "@mantine/dates";
+import { DatePickerInput } from "@mantine/dates";
+import { getDateRangePresets } from "@/components/common/dateRangePresets";
 import { useDebouncedValue } from "@mantine/hooks";
 import {
   AlertTriangle,
@@ -792,24 +793,19 @@ export default function BatchBoardPage() {
                     w={140}
                     styles={{ input: { borderColor: "var(--mantine-color-gray-3)" } }}
                   />
-                  <DateInput
+                  <DatePickerInput
+                    type="range"
                     size="sm"
                     radius="lg"
-                    placeholder="Departs from"
-                    value={departureFrom}
-                    onChange={(v) => setDepartureFrom(v ? new Date(v) : null)}
+                    placeholder="Departure date range"
+                    value={[departureFrom, departureTo]}
+                    onChange={([from, to]) => {
+                      setDepartureFrom(from ? new Date(from) : null);
+                      setDepartureTo(to ? new Date(to) : null);
+                    }}
+                    presets={getDateRangePresets()}
                     clearable
-                    w={140}
-                    styles={{ input: { borderColor: "var(--mantine-color-gray-3)" } }}
-                  />
-                  <DateInput
-                    size="sm"
-                    radius="lg"
-                    placeholder="Departs to"
-                    value={departureTo}
-                    onChange={(v) => setDepartureTo(v ? new Date(v) : null)}
-                    clearable
-                    w={140}
+                    w={230}
                     styles={{ input: { borderColor: "var(--mantine-color-gray-3)" } }}
                   />
                   <Select

From 6a102bf9383bb7705adfa48aeb9d9ed2c4148882 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 08:53:03 +0000
Subject: [PATCH 073/174] feat(reports): header actions, single export dialog,
 date-range presets

- ReportPage drops its own PageHeader (and the back arrow); ReportView
  now optionally renders the header itself (pageHeader prop) with
  export/refresh as its actions. Embedded ReportSection usage is
  unaffected (keeps the inline toolbar next to filters).
- Replace the two xlsx/pdf icon buttons with one Export button opening
  a dialog: format as large icon radio cards, fields as checkboxes
  (select-all toggle), record count (default all, capped per format).
  Export applies the report's current filters and sort.
- Backend: export route accepts fields (whitelisted against the
  report's own columns) and limit; ReportExportService takes an
  optional column subset instead of always dumping every column.
- Fixed a real bug found while wiring this up: runAll() ignored the
  caller's sortBy/sortOrder and always used the report's default sort,
  so exports silently didn't match whatever order was on screen.
- Report daterange filters now use DatePickerInput + the shared
  getDateRangePresets() (Today/Last 7 days/This month/...) instead of
  two bare DateInputs, matching every other date-range filter in the
  app.
- Removed the reports hub grid page. /dashboard/reports now redirects
  to the first report the caller has access to, or /dashboard if they
  have none.
---
 .../modules/reports/report-export.service.ts  |  15 +-
 .../modules/reports/report-runner.service.ts  |   4 +-
 .../src/modules/reports/reports.controller.ts |  18 +-
 apps/edr-freight-web/backoffice/src/App.tsx   |   4 +-
 .../components/reports/ReportExportButton.tsx | 158 ++++++++++++++++++
 .../src/components/reports/ReportFilters.tsx  |  37 ++--
 .../src/components/reports/ReportView.tsx     | 150 ++++++++---------
 .../src/pages/reports/ReportPage.tsx          |  13 +-
 .../src/pages/reports/ReportsHubPage.tsx      |  64 -------
 .../pages/reports/ReportsIndexRedirect.tsx    |  17 ++
 10 files changed, 293 insertions(+), 187 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/reports/ReportExportButton.tsx
 delete mode 100644 apps/edr-freight-web/backoffice/src/pages/reports/ReportsHubPage.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/reports/ReportsIndexRedirect.tsx

diff --git a/apps/edr-freight-api/src/modules/reports/report-export.service.ts b/apps/edr-freight-api/src/modules/reports/report-export.service.ts
index f07317134..f0919c9c7 100644
--- a/apps/edr-freight-api/src/modules/reports/report-export.service.ts
+++ b/apps/edr-freight-api/src/modules/reports/report-export.service.ts
@@ -36,6 +36,7 @@ export class ReportExportService {
     def: ReportDefinition,
     rows: Record<string, unknown>[],
     kpis: ReportKpi[],
+    columns: ReportColumn[] = def.columns,
   ): Promise<Buffer> {
     const workbook = new ExcelJS.Workbook();
     const sheet = workbook.addWorksheet(def.title.slice(0, 31));
@@ -45,14 +46,14 @@ export class ReportExportService {
       sheet.addRow([]);
     }
 
-    const headerRow = sheet.addRow(def.columns.map((c) => c.label));
+    const headerRow = sheet.addRow(columns.map((c) => c.label));
     headerRow.font = { bold: true };
 
     for (const row of rows) {
-      sheet.addRow(def.columns.map((c) => row[c.key] ?? null));
+      sheet.addRow(columns.map((c) => row[c.key] ?? null));
     }
 
-    def.columns.forEach((col, i) => {
+    columns.forEach((col, i) => {
       const format = NUMBER_FORMAT[col.type];
       const excelCol = sheet.getColumn(i + 1);
       excelCol.width = Math.max(col.label.length + 2, 12);
@@ -67,8 +68,9 @@ export class ReportExportService {
     def: ReportDefinition,
     rows: Record<string, unknown>[],
     kpis: ReportKpi[],
+    columns: ReportColumn[] = def.columns,
   ): Promise<Buffer> {
-    const html = this.buildHtml(def, rows, kpis);
+    const html = this.buildHtml(def, rows, kpis, columns);
     return this.pdfRender.htmlToPdfBuffer(html, { label: `report:${def.key}`, landscape: true });
   }
 
@@ -76,6 +78,7 @@ export class ReportExportService {
     def: ReportDefinition,
     rows: Record<string, unknown>[],
     kpis: ReportKpi[],
+    columns: ReportColumn[],
   ): string {
     const esc = (v: unknown) =>
       String(v ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -89,11 +92,11 @@ export class ReportExportService {
           .join('')}</div>`
       : '';
 
-    const head = def.columns.map((c) => `<th>${esc(c.label)}</th>`).join('');
+    const head = columns.map((c) => `<th>${esc(c.label)}</th>`).join('');
     const body = rows
       .map(
         (row) =>
-          `<tr>${def.columns.map((c) => `<td>${esc(formatCell(row[c.key], c.type))}</td>`).join('')}</tr>`,
+          `<tr>${columns.map((c) => `<td>${esc(formatCell(row[c.key], c.type))}</td>`).join('')}</tr>`,
       )
       .join('');
 
diff --git a/apps/edr-freight-api/src/modules/reports/report-runner.service.ts b/apps/edr-freight-api/src/modules/reports/report-runner.service.ts
index 09933de42..a9b662077 100644
--- a/apps/edr-freight-api/src/modules/reports/report-runner.service.ts
+++ b/apps/edr-freight-api/src/modules/reports/report-runner.service.ts
@@ -132,7 +132,9 @@ export class ReportRunnerService {
     const params = coerceParams(def, raw);
     const ctx = { ds: this.ds, params, directions };
     const qb = def.query(ctx);
-    const sort = resolveSort(def, undefined, undefined);
+    // Same sort the on-screen table is using, not always the default — an
+    // export is supposed to match what the user is looking at.
+    const sort = resolveSort(def, raw.sortBy, raw.sortOrder);
     if (sort) qb.orderBy(sort.expr, sort.dir);
     const items = await qb.limit(limit).getRawMany();
     if (items.length >= limit) {
diff --git a/apps/edr-freight-api/src/modules/reports/reports.controller.ts b/apps/edr-freight-api/src/modules/reports/reports.controller.ts
index 49d0307eb..7941c7583 100644
--- a/apps/edr-freight-api/src/modules/reports/reports.controller.ts
+++ b/apps/edr-freight-api/src/modules/reports/reports.controller.ts
@@ -53,20 +53,30 @@ export class ReportsController {
   @ApiOperation({ summary: 'Export a report to xlsx or pdf' })
   async export(
     @Param('key') key: string,
-    @Query() query: RawReportQuery & { format?: string },
+    @Query() query: RawReportQuery & { format?: string; fields?: string; limit?: string },
     @CurrentUser() user: TCurrentUser,
     @Res() res: Response,
   ): Promise<void> {
     const def = this.resolve(key, user);
     const directions = await this.userTradeAccessService.resolveAllowedDirections(user);
     const format = query.format === 'pdf' ? 'pdf' : 'xlsx';
-    const cap = format === 'pdf' ? PDF_ROW_CAP : XLSX_ROW_CAP;
+    const formatCap = format === 'pdf' ? PDF_ROW_CAP : XLSX_ROW_CAP;
+    const requestedLimit = Number(query.limit);
+    const cap = requestedLimit > 0 ? Math.min(requestedLimit, formatCap) : formatCap;
+
+    // Whitelist against the report's own columns — an unknown/empty `fields`
+    // value falls back to every column rather than shipping a blank sheet.
+    const requestedFields = query.fields?.split(',').filter(Boolean);
+    const columns = requestedFields?.length
+      ? def.columns.filter((c) => requestedFields.includes(c.key))
+      : def.columns;
+    const exportColumns = columns.length ? columns : def.columns;
 
     const { items, kpis } = await this.runner.runAll(def, query, directions, cap);
     const buffer =
       format === 'pdf'
-        ? await this.exportService.toPdf(def, items, kpis)
-        : await this.exportService.toXlsx(def, items, kpis);
+        ? await this.exportService.toPdf(def, items, kpis, exportColumns)
+        : await this.exportService.toXlsx(def, items, kpis, exportColumns);
 
     const filename = `${def.key}.${format === 'pdf' ? 'pdf' : 'xlsx'}`;
     res.setHeader('Content-Disposition', `attachment; filename="${filename}"`);
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index 94ad11f1b..fa2798f5c 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -41,7 +41,7 @@ import InvoicesPage from "./pages/invoices/InvoicesPage";
 import UsdPaymentsPage from "./pages/invoices/UsdPaymentsPage";
 import MyProfilePage from "./pages/dashboard/MyProfilePage";
 import OverviewPage from "./pages/dashboard/OverviewPage";
-import ReportsHubPage from "./pages/reports/ReportsHubPage";
+import ReportsIndexRedirect from "./pages/reports/ReportsIndexRedirect";
 import ReportPage from "./pages/reports/ReportPage";
 import AuditLogsPage from "./pages/AuditLogsPage";
 import AiBookingMockTestPage from "./pages/ai/AiBookingMockTestPage";
@@ -214,7 +214,7 @@ const App = () => {
       <Route path="/dashboard" element={<Navigate to={landingPath} replace />} />
       <Route path="/dashboard" element={<DashboardShell />}>
         <Route path="overview" element={<RequirePermission permission={FREIGHT_PERMS.overview.view}><OverviewPage /></RequirePermission>} />
-        <Route path="reports" element={<RequirePermission permission={FREIGHT_PERMS.reports.view}><ReportsHubPage /></RequirePermission>} />
+        <Route path="reports" element={<RequirePermission permission={FREIGHT_PERMS.reports.view}><ReportsIndexRedirect /></RequirePermission>} />
         <Route path="reports/:reportKey" element={<RequirePermission permission={FREIGHT_PERMS.reports.view}><ReportPage /></RequirePermission>} />
         <Route path="audit-logs" element={<RequirePermission permission={FREIGHT_PERMS.auditLog.view}><AuditLogsPage /></RequirePermission>} />
         {/* Dev/testing page for the mock AI booking assistant. */}
diff --git a/apps/edr-freight-web/backoffice/src/components/reports/ReportExportButton.tsx b/apps/edr-freight-web/backoffice/src/components/reports/ReportExportButton.tsx
new file mode 100644
index 000000000..76ff7d628
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/reports/ReportExportButton.tsx
@@ -0,0 +1,158 @@
+import { Button, Checkbox, Group, Modal, Radio, Select, SimpleGrid, Stack, Text } from "@mantine/core";
+import { Download, FileSpreadsheet, FileText } from "lucide-react";
+import { useState } from "react";
+
+import { reportsService } from "@/services/reports.service";
+import type { ReportCatalogEntry, ReportRunParams } from "@/types/reports";
+
+interface ReportExportButtonProps {
+  def: ReportCatalogEntry;
+  /** Filters + sort currently applied on screen — no key/page/pageSize. */
+  params: Omit<ReportRunParams, "key" | "page" | "pageSize">;
+}
+
+const RECORD_OPTIONS = [
+  { value: "all", label: "All (up to format limit)" },
+  { value: "100", label: "First 100" },
+  { value: "500", label: "First 500" },
+  { value: "1000", label: "First 1,000" },
+];
+
+/** Triggers a browser save for a blob without leaving the SPA. */
+function saveBlob(blob: Blob, filename: string) {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+/** One export button: format, which fields, how many records — applies the
+ * filters/sort already on screen. Record count defaults to all (capped
+ * server-side per format). */
+export function ReportExportButton({ def, params }: ReportExportButtonProps) {
+  const [opened, setOpened] = useState(false);
+  const [format, setFormat] = useState<"xlsx" | "pdf">("xlsx");
+  const [fields, setFields] = useState<string[]>(def.columns.map((c) => c.key));
+  const [records, setRecords] = useState("all");
+  const [exporting, setExporting] = useState(false);
+
+  const allSelected = fields.length === def.columns.length;
+  const toggleField = (key: string) =>
+    setFields((prev) => (prev.includes(key) ? prev.filter((k) => k !== key) : [...prev, key]));
+  const toggleAll = () => setFields(allSelected ? [] : def.columns.map((c) => c.key));
+
+  const handleDownload = async () => {
+    setExporting(true);
+    try {
+      const blob = await reportsService.download(def.key, format, {
+        ...params,
+        fields: allSelected ? undefined : fields.join(","),
+        limit: records === "all" ? undefined : records,
+      });
+      saveBlob(blob, `${def.key}.${format}`);
+      setOpened(false);
+    } finally {
+      setExporting(false);
+    }
+  };
+
+  return (
+    <>
+      <Button
+        variant="default"
+        radius="md"
+        size="sm"
+        leftSection={<Download size={16} />}
+        onClick={() => setOpened(true)}
+      >
+        Export
+      </Button>
+
+      <Modal opened={opened} onClose={() => setOpened(false)} title="Export report" radius="md" size="md">
+        <Stack gap="lg">
+          <div>
+            <Text size="sm" fw={600} mb="xs">
+              Format
+            </Text>
+            <Radio.Group value={format} onChange={(v) => setFormat(v as "xlsx" | "pdf")}>
+              <SimpleGrid cols={2}>
+                <Radio.Card value="xlsx" radius="md" p="md">
+                  <Group wrap="nowrap" gap="sm">
+                    <Radio.Indicator />
+                    <FileSpreadsheet size={22} />
+                    <Text size="sm" fw={500}>
+                      Excel (.xlsx)
+                    </Text>
+                  </Group>
+                </Radio.Card>
+                <Radio.Card value="pdf" radius="md" p="md">
+                  <Group wrap="nowrap" gap="sm">
+                    <Radio.Indicator />
+                    <FileText size={22} />
+                    <Text size="sm" fw={500}>
+                      PDF
+                    </Text>
+                  </Group>
+                </Radio.Card>
+              </SimpleGrid>
+            </Radio.Group>
+          </div>
+
+          <div>
+            <Group justify="space-between" mb="xs">
+              <Text size="sm" fw={600}>
+                Fields
+              </Text>
+              <Button variant="subtle" size="compact-sm" onClick={toggleAll}>
+                {allSelected ? "Clear all" : "Select all"}
+              </Button>
+            </Group>
+            <SimpleGrid cols={2} spacing="xs">
+              {def.columns.map((col) => (
+                <Checkbox
+                  key={col.key}
+                  label={col.label}
+                  checked={fields.includes(col.key)}
+                  onChange={() => toggleField(col.key)}
+                />
+              ))}
+            </SimpleGrid>
+          </div>
+
+          <Select
+            label="Records"
+            value={records}
+            onChange={(v) => setRecords(v ?? "all")}
+            data={RECORD_OPTIONS}
+            allowDeselect={false}
+            radius="md"
+            size="sm"
+          />
+
+          <Text size="xs" c="dimmed">
+            Uses the filters and sorting currently applied to the report.
+          </Text>
+
+          <Group justify="flex-end">
+            <Button variant="default" radius="md" onClick={() => setOpened(false)}>
+              Cancel
+            </Button>
+            <Button
+              radius="md"
+              loading={exporting}
+              disabled={!fields.length}
+              leftSection={<Download size={16} />}
+              onClick={() => void handleDownload()}
+            >
+              Download
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
+    </>
+  );
+}
+
+export default ReportExportButton;
diff --git a/apps/edr-freight-web/backoffice/src/components/reports/ReportFilters.tsx b/apps/edr-freight-web/backoffice/src/components/reports/ReportFilters.tsx
index 9412d4db8..e44e97ec8 100644
--- a/apps/edr-freight-web/backoffice/src/components/reports/ReportFilters.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/reports/ReportFilters.tsx
@@ -1,7 +1,8 @@
 import { Group, MultiSelect, Select, TextInput } from "@mantine/core";
-import { DateInput } from "@mantine/dates";
+import { DateInput, DatePickerInput } from "@mantine/dates";
 import { Search } from "lucide-react";
 
+import { getDateRangePresets } from "@/components/common/dateRangePresets";
 import type { ReportFilterDef } from "@/types/reports";
 
 export interface ReportFilterValues {
@@ -29,26 +30,20 @@ export function ReportFilters({ filters, values, onChange }: ReportFiltersProps)
         switch (filter.type) {
           case "daterange":
             return (
-              <Group key={filter.key} gap="xs" wrap="nowrap">
-                <DateInput
-                  placeholder={`${filter.label} from`}
-                  value={toDate(values[`${filter.key}From`])}
-                  onChange={(d) => set({ [`${filter.key}From`]: fromDate(d) })}
-                  radius="md"
-                  size="sm"
-                  clearable
-                  w={150}
-                />
-                <DateInput
-                  placeholder={`${filter.label} to`}
-                  value={toDate(values[`${filter.key}To`])}
-                  onChange={(d) => set({ [`${filter.key}To`]: fromDate(d) })}
-                  radius="md"
-                  size="sm"
-                  clearable
-                  w={150}
-                />
-              </Group>
+              <DatePickerInput
+                key={filter.key}
+                type="range"
+                placeholder={filter.label}
+                value={[values[`${filter.key}From`] ?? null, values[`${filter.key}To`] ?? null]}
+                onChange={([from, to]) =>
+                  set({ [`${filter.key}From`]: fromDate(from), [`${filter.key}To`]: fromDate(to) })
+                }
+                presets={getDateRangePresets()}
+                radius="md"
+                size="sm"
+                clearable
+                w={230}
+              />
             );
           case "date":
             return (
diff --git a/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx b/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx
index b1c5822fc..47f5a194a 100644
--- a/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx
@@ -2,16 +2,17 @@ import { ActionIcon, Alert, Box, Card, Group, SegmentedControl, Stack, Text, Too
 import { useDebouncedValue } from "@mantine/hooks";
 import { useQuery } from "@tanstack/react-query";
 import type { Column, SortingState } from "@tanstack/react-table";
-import { ArrowDown, ArrowUp, ArrowUpDown, FileSpreadsheet, FileText, LayoutGrid, LineChart, RefreshCw } from "lucide-react";
+import { ArrowDown, ArrowUp, ArrowUpDown, LayoutGrid, LineChart, RefreshCw } from "lucide-react";
 import { useMemo, useState } from "react";
 
+import { PageHeader } from "@/components/page";
 import { KpiStrip } from "@/components/page/KpiStrip";
 import { api } from "@/services/api";
-import { reportsService } from "@/services/reports.service";
 import type { ReportRunParams } from "@/types/reports";
 import { DataTable, DataTableFooter, usePagination, type ColumnDef } from "@edr/ui-common";
 
 import { ReportChart } from "./ReportChart";
+import { ReportExportButton } from "./ReportExportButton";
 import { ReportFilters, type ReportFilterValues } from "./ReportFilters";
 import { formatKpiValue, formatReportCell } from "./report-format";
 
@@ -35,24 +36,18 @@ interface ReportViewProps {
   reportKey: string;
   /** Scopes the report to one entity when embedded (e.g. a contract detail page). */
   idKeyValue?: string;
-}
-
-/** Triggers a browser save for a blob without leaving the SPA. */
-function saveBlob(blob: Blob, filename: string) {
-  const url = URL.createObjectURL(blob);
-  const a = document.createElement("a");
-  a.href = url;
-  a.download = filename;
-  a.click();
-  URL.revokeObjectURL(url);
+  /** Full-page usage: renders the title/description as a PageHeader (no back
+   * arrow) with export/refresh as its actions, instead of inline above the
+   * table. Off by default for embedded sections. */
+  pageHeader?: boolean;
 }
 
 /**
  * The report engine: one component renders any report the catalog describes —
- * filters, KPI strip, sortable/paginated table, xlsx/pdf export. Adding a
- * report never touches this file.
+ * filters, KPI strip, sortable/paginated table or chart, xlsx/pdf export.
+ * Adding a report never touches this file.
  */
-export function ReportView({ reportKey, idKeyValue }: ReportViewProps) {
+export function ReportView({ reportKey, idKeyValue, pageHeader }: ReportViewProps) {
   const { data: catalog } = useQuery(api.reports.catalog.queryOptions());
   const def = catalog?.find((r) => r.key === reportKey);
 
@@ -60,12 +55,22 @@ export function ReportView({ reportKey, idKeyValue }: ReportViewProps) {
   const [sorting, setSorting] = useState<SortingState>([]);
   const [filterValues, setFilterValues] = useState<ReportFilterValues>({});
   const [debouncedFilters] = useDebouncedValue(filterValues, 300);
-  const [exporting, setExporting] = useState<"xlsx" | "pdf" | null>(null);
   const [view, setView] = useState<"table" | "chart">("table");
 
+  // Filters + sort as the user currently has them — independent of the view
+  // toggle's paging, so export always matches what's on screen either way.
+  const appliedParams = useMemo(() => {
+    const sort = sorting[0];
+    return {
+      sortBy: sort?.id,
+      sortOrder: sort ? (sort.desc ? "DESC" as const : "ASC" as const) : undefined,
+      ...debouncedFilters,
+      ...(def?.idKey && idKeyValue ? { [def.idKey.key]: idKeyValue } : {}),
+    };
+  }, [def, sorting, debouncedFilters, idKeyValue]);
+
   const runParams: ReportRunParams | undefined = useMemo(() => {
     if (!def) return undefined;
-    const sort = sorting[0];
     return {
       key: def.key,
       // Chart view isn't paginated on screen — pull the server's max page (100)
@@ -73,12 +78,9 @@ export function ReportView({ reportKey, idKeyValue }: ReportViewProps) {
       // so the chart doesn't silently plot a fraction of the filtered rows.
       page: view === "chart" ? 1 : pagination.pageIndex + 1,
       pageSize: view === "chart" ? 100 : pagination.pageSize,
-      sortBy: sort?.id,
-      sortOrder: sort ? (sort.desc ? "DESC" : "ASC") : undefined,
-      ...debouncedFilters,
-      ...(def.idKey && idKeyValue ? { [def.idKey.key]: idKeyValue } : {}),
+      ...appliedParams,
     };
-  }, [def, view, pagination, sorting, debouncedFilters, idKeyValue]);
+  }, [def, view, pagination, appliedParams]);
 
   const { data, isLoading, isError, isFetching, refetch } = useQuery({
     ...api.reports.run.queryOptions({ input: runParams as ReportRunParams }),
@@ -106,26 +108,55 @@ export function ReportView({ reportKey, idKeyValue }: ReportViewProps) {
     [def?.columns],
   );
 
-  const handleExport = async (format: "xlsx" | "pdf") => {
-    if (!def) return;
-    setExporting(format);
-    try {
-      const { key: _key, page: _page, pageSize: _pageSize, ...filters } = runParams ?? {};
-      const blob = await reportsService.download(def.key, format, filters);
-      saveBlob(blob, `${def.key}.${format}`);
-    } finally {
-      setExporting(null);
-    }
-  };
-
   if (!def) {
     return catalog ? (
       <Alert color="red">You don't have access to this report.</Alert>
     ) : null;
   }
 
+  const chartToggle = def.chart ? (
+    <SegmentedControl
+      size="xs"
+      value={view}
+      onChange={(v) => setView(v as "table" | "chart")}
+      data={[
+        { label: <LayoutGrid size={14} />, value: "table" },
+        { label: <LineChart size={14} />, value: "chart" },
+      ]}
+    />
+  ) : null;
+
+  const refreshButton = (
+    <Tooltip label="Refresh">
+      <ActionIcon
+        variant="default"
+        radius="md"
+        loading={isFetching}
+        onClick={() => void refetch()}
+        aria-label="Refresh"
+      >
+        <RefreshCw size={16} />
+      </ActionIcon>
+    </Tooltip>
+  );
+
+  const exportButton = <ReportExportButton def={def} params={appliedParams} />;
+
   return (
     <Stack gap="md">
+      {pageHeader ? (
+        <PageHeader
+          title={def.title}
+          subtitle={def.description}
+          action={
+            <Group gap="xs">
+              {exportButton}
+              {refreshButton}
+            </Group>
+          }
+        />
+      ) : null}
+
       {data?.kpis.length ? (
         <KpiStrip
           loading={isLoading}
@@ -146,50 +177,13 @@ export function ReportView({ reportKey, idKeyValue }: ReportViewProps) {
                 }}
               />
               <Group gap="xs">
-                {def.chart ? (
-                  <SegmentedControl
-                    size="xs"
-                    value={view}
-                    onChange={(v) => setView(v as "table" | "chart")}
-                    data={[
-                      { label: <LayoutGrid size={14} />, value: "table" },
-                      { label: <LineChart size={14} />, value: "chart" },
-                    ]}
-                  />
-                ) : null}
-                <Tooltip label="Export to Excel">
-                  <ActionIcon
-                    variant="default"
-                    radius="md"
-                    loading={exporting === "xlsx"}
-                    onClick={() => void handleExport("xlsx")}
-                    aria-label="Export to Excel"
-                  >
-                    <FileSpreadsheet size={16} />
-                  </ActionIcon>
-                </Tooltip>
-                <Tooltip label="Export to PDF">
-                  <ActionIcon
-                    variant="default"
-                    radius="md"
-                    loading={exporting === "pdf"}
-                    onClick={() => void handleExport("pdf")}
-                    aria-label="Export to PDF"
-                  >
-                    <FileText size={16} />
-                  </ActionIcon>
-                </Tooltip>
-                <Tooltip label="Refresh">
-                  <ActionIcon
-                    variant="default"
-                    radius="md"
-                    loading={isFetching}
-                    onClick={() => void refetch()}
-                    aria-label="Refresh"
-                  >
-                    <RefreshCw size={16} />
-                  </ActionIcon>
-                </Tooltip>
+                {chartToggle}
+                {pageHeader ? null : (
+                  <>
+                    {exportButton}
+                    {refreshButton}
+                  </>
+                )}
               </Group>
             </Group>
           </Box>
diff --git a/apps/edr-freight-web/backoffice/src/pages/reports/ReportPage.tsx b/apps/edr-freight-web/backoffice/src/pages/reports/ReportPage.tsx
index 0869adb4e..16651cdf2 100644
--- a/apps/edr-freight-web/backoffice/src/pages/reports/ReportPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/reports/ReportPage.tsx
@@ -1,23 +1,14 @@
-import { useQuery } from "@tanstack/react-query";
 import { useParams } from "react-router-dom";
 
 import { ReportView } from "@/components/reports/ReportView";
-import { PageContainer, PageHeader } from "@/components/page";
-import { api } from "@/services/api";
+import { PageContainer } from "@/components/page";
 
 export default function ReportPage() {
   const { reportKey = "" } = useParams<{ reportKey: string }>();
-  const { data: catalog } = useQuery(api.reports.catalog.queryOptions());
-  const def = catalog?.find((r) => r.key === reportKey);
 
   return (
     <PageContainer>
-      <PageHeader
-        title={def?.title ?? "Report"}
-        subtitle={def?.description}
-        backTo="/dashboard/reports"
-      />
-      <ReportView reportKey={reportKey} />
+      <ReportView reportKey={reportKey} pageHeader />
     </PageContainer>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/reports/ReportsHubPage.tsx b/apps/edr-freight-web/backoffice/src/pages/reports/ReportsHubPage.tsx
deleted file mode 100644
index 172afca82..000000000
--- a/apps/edr-freight-web/backoffice/src/pages/reports/ReportsHubPage.tsx
+++ /dev/null
@@ -1,64 +0,0 @@
-import { Alert, Card, SimpleGrid, Skeleton, Stack, Text, Title } from "@mantine/core";
-import { useQuery } from "@tanstack/react-query";
-import { useNavigate } from "react-router-dom";
-
-import { PageContainer, PageHeader } from "@/components/page";
-import { api } from "@/services/api";
-import type { ReportCatalogEntry } from "@/types/reports";
-
-const GROUP_ORDER: ReportCatalogEntry["group"][] = ["Commercial", "Operations", "Finance"];
-
-export default function ReportsHubPage() {
-  const navigate = useNavigate();
-  const { data: catalog, isLoading, isError } = useQuery(api.reports.catalog.queryOptions());
-
-  const groups = GROUP_ORDER.map((group) => ({
-    group,
-    reports: (catalog ?? []).filter((r) => r.group === group),
-  })).filter((g) => g.reports.length);
-
-  return (
-    <PageContainer>
-      <PageHeader title="Reports" subtitle="Every report you have access to, grouped by area." />
-
-      {isError ? <Alert color="red">Failed to load the report catalog.</Alert> : null}
-
-      {isLoading ? (
-        <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="md">
-          {Array.from({ length: 6 }).map((_, i) => (
-            <Skeleton key={i} height={96} radius="md" />
-          ))}
-        </SimpleGrid>
-      ) : null}
-
-      {!isLoading && !isError && !groups.length ? (
-        <Text c="dimmed">You don't have access to any reports yet.</Text>
-      ) : null}
-
-      {groups.map(({ group, reports }) => (
-        <Stack key={group} gap="sm">
-          <Title order={4}>{group}</Title>
-          <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="md">
-            {reports.map((report) => (
-              <Card
-                key={report.key}
-                withBorder
-                radius="md"
-                p="md"
-                className="cursor-pointer transition-colors hover:bg-gray-50"
-                onClick={() => navigate(`/dashboard/reports/${report.key}`)}
-              >
-                <Text fw={600} c="edr-text">
-                  {report.title}
-                </Text>
-                <Text size="sm" c="dimmed" mt={4}>
-                  {report.description}
-                </Text>
-              </Card>
-            ))}
-          </SimpleGrid>
-        </Stack>
-      ))}
-    </PageContainer>
-  );
-}
diff --git a/apps/edr-freight-web/backoffice/src/pages/reports/ReportsIndexRedirect.tsx b/apps/edr-freight-web/backoffice/src/pages/reports/ReportsIndexRedirect.tsx
new file mode 100644
index 000000000..a341b388e
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/reports/ReportsIndexRedirect.tsx
@@ -0,0 +1,17 @@
+import { useQuery } from "@tanstack/react-query";
+import { Navigate } from "react-router-dom";
+
+import { api } from "@/services/api";
+
+/**
+ * `/dashboard/reports` has no page of its own — it forwards to the first
+ * report the caller has access to (catalog order = registration order,
+ * already permission-filtered server-side), or home if they have none.
+ */
+export default function ReportsIndexRedirect() {
+  const { data: catalog, isLoading } = useQuery(api.reports.catalog.queryOptions());
+
+  if (isLoading) return null;
+  const first = catalog?.[0];
+  return <Navigate to={first ? `/dashboard/reports/${first.key}` : "/dashboard"} replace />;
+}

From 58cb71a9cf6872e6dde8791a5f96d75e5bbec6e8 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Thu, 13 Aug 2026 08:55:17 +0000
Subject: [PATCH 074/174] feat(train-scheduling): add direct truck-to-train
 load action beside Load

Export bookings whose cargo goes straight from customer truck to wagon
never get a warehouse GRN, so the load gate (assertExportReceivedWithGrn)
rejects them forever unless staff first flip exportHandoverMode on the
booking detail page, then come back and retry Load.

Add a Truck to Train button next to Load in the schedule workspace's
on-train list, shown for EXPORT bookings at the boarding yard. One click
sets exportHandoverMode=DIRECT_TO_TRAIN then loads the booking.
---
 .../ScheduleWorkspacePanel.tsx                | 51 +++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleWorkspacePanel.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleWorkspacePanel.tsx
index de954742e..25c20c8db 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleWorkspacePanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/ScheduleWorkspacePanel.tsx
@@ -29,6 +29,7 @@ import {
   // Repeat, // used by the hidden Move (reassign) button
   Train,
   TrainFront,
+  Truck,
   Weight,
   X,
 } from "lucide-react";
@@ -37,6 +38,7 @@ import { CountdownTimer } from "@edr/ui-common";
 
 import { BookingStatusBadge } from "@/components/bookings/BookingStatusBadge";
 import { api } from "@/services/api";
+import { bookingsService } from "@/services/bookings.service";
 import { useToast } from "@/hooks/use-toast";
 import type {
   EligibleContainerBooking,
@@ -411,6 +413,31 @@ export function ScheduleWorkspacePanel({
       );
   };
 
+  // Export cargo that skipped the warehouse (customer truck straight onto the
+  // wagon) has no GRN and never will — loadBooking's GRN gate would keep
+  // rejecting it forever. Setting DIRECT_TO_TRAIN tells that gate the carriage
+  // acceptance sheet is the handover document instead, then loads in one click.
+  const [truckToTrainPending, setTruckToTrainPending] = useState<string | null>(null);
+  const doTruckToTrain = (bookingId: string, ref: string) => {
+    setTruckToTrainPending(bookingId);
+    bookingsService
+      .setExportHandoverMode(bookingId, "DIRECT_TO_TRAIN")
+      .then(() => loadJourney.mutateAsync({ scheduleId: schedule.id, bookingId }))
+      .then(() => {
+        toast({ title: `${ref} loaded — direct truck-to-train handover` });
+        onChanged();
+        void yardWorkQuery.refetch();
+      })
+      .catch((error) =>
+        toast({
+          title: "Could not load as direct truck-to-train",
+          description: apiErrorMessage(error, "Please try again."),
+          variant: "destructive",
+        }),
+      )
+      .finally(() => setTruckToTrainPending(null));
+  };
+
   const doUnload = (bookingId: string, ref: string) => {
     unloadJourney
       .mutateAsync({ scheduleId: schedule.id, bookingId })
@@ -708,6 +735,12 @@ export function ScheduleWorkspacePanel({
                     const alightHere = trainAtYardId != null && b.destinationYardId === trainAtYardId;
                     const showLoad = canWork && !riding && !done && (journey?.canLoad ?? false);
                     const showUnload = canWork && riding && (journey?.canUnload ?? false);
+                    const showTruckToTrain =
+                      canWork &&
+                      !riding &&
+                      !done &&
+                      boardHere &&
+                      b.tradeDirection === "EXPORT";
                     return (
                       <BookingCard
                         key={b.id}
@@ -764,6 +797,24 @@ export function ScheduleWorkspacePanel({
                                 </Button>
                               </Tooltip>
                             ) : null}
+                            {showTruckToTrain ? (
+                              <Tooltip
+                                label="Customer truck loaded straight onto the wagon — no warehouse receipt, no GRN. Sets direct truck-to-train handover and loads."
+                                withArrow
+                              >
+                                <Button
+                                  size="compact-sm"
+                                  variant="light"
+                                  color="blue"
+                                  radius="md"
+                                  leftSection={<Truck size={13} />}
+                                  loading={truckToTrainPending === b.id}
+                                  onClick={() => doTruckToTrain(b.id, ref)}
+                                >
+                                  Truck to Train
+                                </Button>
+                              </Tooltip>
+                            ) : null}
                             {showUnload ? (
                               <Tooltip
                                 label={

From cb27d82e8f4522b9085795f3f934c7e627ef7c0c Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 09:07:49 +0000
Subject: [PATCH 075/174] test(freight-api): cover export field/limit/format
 resolution

Extracted the export route's format/cap/column-whitelist branching out
of the controller into pure functions (resolveExportFormat,
resolveExportCap, resolveExportColumns) and added a spec: unknown
format falls back to xlsx, limit clamps to the format cap and ignores
non-positive/NaN input, unknown field keys are dropped and an
all-unknown fields list falls back to every column instead of
shipping a blank sheet. Was untested branching logic before this.
---
 .../report-export-request.util.spec.ts        | 62 +++++++++++++++++++
 .../reports/report-export-request.util.ts     | 29 +++++++++
 .../src/modules/reports/reports.controller.ts | 18 ++----
 3 files changed, 96 insertions(+), 13 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/reports/report-export-request.util.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/report-export-request.util.ts

diff --git a/apps/edr-freight-api/src/modules/reports/report-export-request.util.spec.ts b/apps/edr-freight-api/src/modules/reports/report-export-request.util.spec.ts
new file mode 100644
index 000000000..dc6fa6230
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/report-export-request.util.spec.ts
@@ -0,0 +1,62 @@
+import { PDF_ROW_CAP, XLSX_ROW_CAP } from './report-export.service';
+import { resolveExportCap, resolveExportColumns, resolveExportFormat } from './report-export-request.util';
+import { ReportColumn } from './report.types';
+
+describe('resolveExportFormat', () => {
+  it('only \'pdf\' exports as pdf', () => {
+    expect(resolveExportFormat('pdf')).toBe('pdf');
+  });
+
+  it.each([undefined, 'xlsx', 'csv', ''])('%p falls back to xlsx', (raw) => {
+    expect(resolveExportFormat(raw)).toBe('xlsx');
+  });
+});
+
+describe('resolveExportCap', () => {
+  it('missing limit uses the full format cap', () => {
+    expect(resolveExportCap('xlsx', undefined)).toBe(XLSX_ROW_CAP);
+    expect(resolveExportCap('pdf', undefined)).toBe(PDF_ROW_CAP);
+  });
+
+  it('a limit under the cap is used as-is', () => {
+    expect(resolveExportCap('pdf', '100')).toBe(100);
+  });
+
+  it('a limit over the cap is clamped down', () => {
+    expect(resolveExportCap('pdf', String(PDF_ROW_CAP + 1000))).toBe(PDF_ROW_CAP);
+    expect(resolveExportCap('xlsx', String(XLSX_ROW_CAP + 1))).toBe(XLSX_ROW_CAP);
+  });
+
+  it.each(['0', '-5', 'not-a-number', ''])('non-positive/invalid limit %p falls back to the cap', (raw) => {
+    expect(resolveExportCap('xlsx', raw)).toBe(XLSX_ROW_CAP);
+  });
+});
+
+describe('resolveExportColumns', () => {
+  const columns: ReportColumn[] = [
+    { key: 'a', label: 'A', type: 'string' },
+    { key: 'b', label: 'B', type: 'number' },
+    { key: 'c', label: 'C', type: 'money' },
+  ];
+  const def = { columns };
+
+  it('missing fields returns every column', () => {
+    expect(resolveExportColumns(def, undefined)).toEqual(columns);
+  });
+
+  it('empty fields string returns every column', () => {
+    expect(resolveExportColumns(def, '')).toEqual(columns);
+  });
+
+  it('a known subset filters to just those columns, in the report\'s own order', () => {
+    expect(resolveExportColumns(def, 'c,a')).toEqual([columns[0], columns[2]]);
+  });
+
+  it('unknown keys are dropped, not passed through', () => {
+    expect(resolveExportColumns(def, 'a,ghost')).toEqual([columns[0]]);
+  });
+
+  it('all-unknown keys falls back to every column instead of a blank sheet', () => {
+    expect(resolveExportColumns(def, 'ghost,also-ghost')).toEqual(columns);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/reports/report-export-request.util.ts b/apps/edr-freight-api/src/modules/reports/report-export-request.util.ts
new file mode 100644
index 000000000..18f2fa322
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/report-export-request.util.ts
@@ -0,0 +1,29 @@
+import { PDF_ROW_CAP, XLSX_ROW_CAP } from './report-export.service';
+import { ReportColumn, ReportDefinition } from './report.types';
+
+export type ExportFormat = 'xlsx' | 'pdf';
+
+/** Anything but the literal string 'pdf' exports as xlsx. */
+export function resolveExportFormat(raw: string | undefined): ExportFormat {
+  return raw === 'pdf' ? 'pdf' : 'xlsx';
+}
+
+/** Caller's requested row limit, clamped to the format's hard cap. A
+ * missing/non-positive/non-numeric limit means "as many as the format allows". */
+export function resolveExportCap(format: ExportFormat, rawLimit: string | undefined): number {
+  const formatCap = format === 'pdf' ? PDF_ROW_CAP : XLSX_ROW_CAP;
+  const requested = Number(rawLimit);
+  return requested > 0 ? Math.min(requested, formatCap) : formatCap;
+}
+
+/** Caller's requested column subset, whitelisted against the report's own
+ * columns. Missing, empty, or all-unknown `rawFields` falls back to every
+ * column rather than shipping a blank sheet. */
+export function resolveExportColumns(
+  def: Pick<ReportDefinition, 'columns'>,
+  rawFields: string | undefined,
+): ReportColumn[] {
+  const requested = rawFields?.split(',').filter(Boolean);
+  const filtered = requested?.length ? def.columns.filter((c) => requested.includes(c.key)) : def.columns;
+  return filtered.length ? filtered : def.columns;
+}
diff --git a/apps/edr-freight-api/src/modules/reports/reports.controller.ts b/apps/edr-freight-api/src/modules/reports/reports.controller.ts
index 7941c7583..4d213bc2b 100644
--- a/apps/edr-freight-api/src/modules/reports/reports.controller.ts
+++ b/apps/edr-freight-api/src/modules/reports/reports.controller.ts
@@ -8,7 +8,8 @@ import { BookingStaff } from '../../common/booking-guards';
 import { assertFreightPermission, hasFreightPermission } from '../../common/freight-permission.util';
 import { FREIGHT_PERMS, reportPermissionKey } from '../../seed/freight-permissions.registry';
 import { UserTradeAccessService } from '../user-trade-access/user-trade-access.service';
-import { PDF_ROW_CAP, ReportExportService, XLSX_ROW_CAP } from './report-export.service';
+import { ReportExportService } from './report-export.service';
+import { resolveExportCap, resolveExportColumns, resolveExportFormat } from './report-export-request.util';
 import { RawReportQuery, ReportRunnerService } from './report-runner.service';
 import { REPORTS, getReport } from './report.registry';
 import { ReportCatalogEntry, ReportDefinition } from './report.types';
@@ -59,18 +60,9 @@ export class ReportsController {
   ): Promise<void> {
     const def = this.resolve(key, user);
     const directions = await this.userTradeAccessService.resolveAllowedDirections(user);
-    const format = query.format === 'pdf' ? 'pdf' : 'xlsx';
-    const formatCap = format === 'pdf' ? PDF_ROW_CAP : XLSX_ROW_CAP;
-    const requestedLimit = Number(query.limit);
-    const cap = requestedLimit > 0 ? Math.min(requestedLimit, formatCap) : formatCap;
-
-    // Whitelist against the report's own columns — an unknown/empty `fields`
-    // value falls back to every column rather than shipping a blank sheet.
-    const requestedFields = query.fields?.split(',').filter(Boolean);
-    const columns = requestedFields?.length
-      ? def.columns.filter((c) => requestedFields.includes(c.key))
-      : def.columns;
-    const exportColumns = columns.length ? columns : def.columns;
+    const format = resolveExportFormat(query.format);
+    const cap = resolveExportCap(format, query.limit);
+    const exportColumns = resolveExportColumns(def, query.fields);
 
     const { items, kpis } = await this.runner.runAll(def, query, directions, cap);
     const buffer =

From 4ae63d4e5ca870ab46534a4e557d87e93714db8f Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 09:29:09 +0000
Subject: [PATCH 076/174] fix: report ordering

---
 apps/edr-freight-web/backoffice/src/App.tsx   |  294 ++++-
 .../components/layout/sidebar-sections.tsx    | 1021 +++++++++--------
 2 files changed, 770 insertions(+), 545 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index fa2798f5c..a176855f4 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -83,7 +83,6 @@ import TrainScheduleTrackPage from "./pages/trainScheduling/TrainScheduleTrackPa
 import TrainSchedulingGlobalRulesPage from "./pages/trainScheduling/TrainSchedulingGlobalRulesPage";
 import TradeAccessPage from "./pages/configuration/TradeAccessPage";
 import ExchangeRateSettingsCard from "./pages/settings/ExchangeRateSettingsCard";
-import ContractValidityPeriodsPage from "./pages/configuration/ContractValidityPeriodsPage";
 import FirstMilePage from "./pages/operations/FirstMilePage";
 import LastMilePage from "./pages/operations/LastMilePage";
 import TrainDetailPage from "./pages/trains/TrainDetailPage";
@@ -211,12 +210,43 @@ const App = () => {
       {/* Landing is per-user: /dashboard/overview is gated on overview:view, so
           a fixed target strands anyone without that key on a blank page. */}
       <Route path="/" element={<Navigate to={landingPath} replace />} />
-      <Route path="/dashboard" element={<Navigate to={landingPath} replace />} />
+      <Route
+        path="/dashboard"
+        element={<Navigate to={landingPath} replace />}
+      />
       <Route path="/dashboard" element={<DashboardShell />}>
-        <Route path="overview" element={<RequirePermission permission={FREIGHT_PERMS.overview.view}><OverviewPage /></RequirePermission>} />
-        <Route path="reports" element={<RequirePermission permission={FREIGHT_PERMS.reports.view}><ReportsIndexRedirect /></RequirePermission>} />
-        <Route path="reports/:reportKey" element={<RequirePermission permission={FREIGHT_PERMS.reports.view}><ReportPage /></RequirePermission>} />
-        <Route path="audit-logs" element={<RequirePermission permission={FREIGHT_PERMS.auditLog.view}><AuditLogsPage /></RequirePermission>} />
+        <Route
+          path="overview"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.overview.view}>
+              <OverviewPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="reports"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.reports.view}>
+              <ReportsIndexRedirect />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="reports/:reportKey"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.reports.view}>
+              <ReportPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="audit-logs"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.auditLog.view}>
+              <AuditLogsPage />
+            </RequirePermission>
+          }
+        />
         {/* Dev/testing page for the mock AI booking assistant. */}
         <Route
           path="ai-booking-mock-test"
@@ -228,7 +258,14 @@ const App = () => {
         />
         <Route path="profile" element={<MyProfilePage />} />
 
-        <Route path="booking-requests" element={<RequirePermission permission={FREIGHT_PERMS.bookings.view}><BookingRequestsPage /></RequirePermission>} />
+        <Route
+          path="booking-requests"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.bookings.view}>
+              <BookingRequestsPage />
+            </RequirePermission>
+          }
+        />
         <Route
           path="payments"
           element={
@@ -237,7 +274,14 @@ const App = () => {
             </RequirePermission>
           }
         />
-        <Route path="support" element={<RequirePermission permission={FREIGHT_PERMS.support.agentView}><SupportInboxPage /></RequirePermission>} />
+        <Route
+          path="support"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.support.agentView}>
+              <SupportInboxPage />
+            </RequirePermission>
+          }
+        />
         <Route
           path="customers"
           element={
@@ -278,7 +322,14 @@ const App = () => {
             </RequirePermission>
           }
         />
-        <Route path="booking-requests/new" element={<RequirePermission permission={FREIGHT_PERMS.bookings.view}><NewBookingPage /></RequirePermission>} />
+        <Route
+          path="booking-requests/new"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.bookings.view}>
+              <NewBookingPage />
+            </RequirePermission>
+          }
+        />
         <Route
           path="wagon-cancellations"
           element={
@@ -487,25 +538,195 @@ const App = () => {
           path="bookings/:id/milestones"
           element={<BookingMilestonesRedirect />}
         />
-        <Route path="warehouses" element={<RequirePermission permission={FREIGHT_PERMS.warehouses.view}><WarehouseListPage /></RequirePermission>} />
-        <Route path="warehouses/:id" element={<RequirePermission permission={FREIGHT_PERMS.warehouses.view}><WarehouseDetailPage /></RequirePermission>} />
-        <Route path="warehouse-inventory" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><WarehouseInventoryPage /></RequirePermission>} />
-        <Route path="import-warehouse" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><ImportWarehouseFlowPage /></RequirePermission>} />
-        <Route path="export-warehouse" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><ExportWarehouseFlowPage /></RequirePermission>} />
-        <Route path="arrival-queue" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><ArrivalQueuePage /></RequirePermission>} />
-        <Route path="loading-queue" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><LoadingQueuePage /></RequirePermission>} />
-        <Route path="intercity" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><IntercityPage /></RequirePermission>} />
-        <Route path="trucks-on-site" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><TrucksOnSitePage /></RequirePermission>} />
-        <Route path="import-trucks" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><ImportTrucksPage /></RequirePermission>} />
-        <Route path="container-returns" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><ContainerReturnsPage /></RequirePermission>} />
-        <Route path="loaded-inventory" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><LoadedInventoryPage /></RequirePermission>} />
-        <Route path="dispatch-queue" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><DispatchQueuePage /></RequirePermission>} />
-        <Route path="export-djibouti-unloading" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><ExportDjiboutiUnloadingQueuePage /></RequirePermission>} />
-        <Route path="interchange-documents" element={<RequirePermission permission={FREIGHT_PERMS.interchangeDocuments.view}><InterchangeDocumentsPage /></RequirePermission>} />
-        <Route path="inventory-inquiry" element={<RequirePermission permission={FREIGHT_PERMS.warehouseInventory.view}><InventoryInquiryPage /></RequirePermission>} />
-        <Route path="warehouse-rules" element={<RequirePermission permission={[FREIGHT_PERMS.warehouseAllocationRules.view, FREIGHT_PERMS.warehouseFeeRules.view]}><WarehouseRulesPage /></RequirePermission>} />
-        <Route path="warehouse-fee-invoices" element={<RequirePermission permission={FREIGHT_PERMS.warehouseFeeInvoices.view}><WarehouseInvoicesPage /></RequirePermission>} />
-        <Route path="warehouse-dashboard" element={<RequirePermission permission={FREIGHT_PERMS.warehouseDashboard.view}><WarehouseDashboardPage /></RequirePermission>} />
+        <Route
+          path="warehouses"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.warehouses.view}>
+              <WarehouseListPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="warehouses/:id"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.warehouses.view}>
+              <WarehouseDetailPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="warehouse-inventory"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <WarehouseInventoryPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="import-warehouse"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <ImportWarehouseFlowPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="export-warehouse"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <ExportWarehouseFlowPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="arrival-queue"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <ArrivalQueuePage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="loading-queue"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <LoadingQueuePage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="intercity"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <IntercityPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="trucks-on-site"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <TrucksOnSitePage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="import-trucks"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <ImportTrucksPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="container-returns"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <ContainerReturnsPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="loaded-inventory"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <LoadedInventoryPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="dispatch-queue"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <DispatchQueuePage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="export-djibouti-unloading"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <ExportDjiboutiUnloadingQueuePage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="interchange-documents"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.interchangeDocuments.view}
+            >
+              <InterchangeDocumentsPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="inventory-inquiry"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseInventory.view}
+            >
+              <InventoryInquiryPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="warehouse-rules"
+          element={
+            <RequirePermission
+              permission={[
+                FREIGHT_PERMS.warehouseAllocationRules.view,
+                FREIGHT_PERMS.warehouseFeeRules.view,
+              ]}
+            >
+              <WarehouseRulesPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="warehouse-fee-invoices"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseFeeInvoices.view}
+            >
+              <WarehouseInvoicesPage />
+            </RequirePermission>
+          }
+        />
+        <Route
+          path="warehouse-dashboard"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.warehouseDashboard.view}
+            >
+              <WarehouseDashboardPage />
+            </RequirePermission>
+          }
+        />
 
         <Route
           path="operations/train-scheduling"
@@ -784,7 +1005,9 @@ const App = () => {
         <Route
           path="file-settings"
           element={
-            <RequirePermission permission={FREIGHT_PERMS.settings.fileUpload.view}>
+            <RequirePermission
+              permission={FREIGHT_PERMS.settings.fileUpload.view}
+            >
               <FileUploadSettingsPage />
             </RequirePermission>
           }
@@ -792,7 +1015,9 @@ const App = () => {
         <Route
           path="dropdown-settings"
           element={
-            <RequirePermission permission={FREIGHT_PERMS.settings.dropdown.view}>
+            <RequirePermission
+              permission={FREIGHT_PERMS.settings.dropdown.view}
+            >
               <DropdownSettingsPage />
             </RequirePermission>
           }
@@ -807,9 +1032,7 @@ const App = () => {
         <Route
           path="stamp-settings"
           element={
-            <RequirePermission
-              permission={FREIGHT_PERMS.settings.stamp.view}
-            >
+            <RequirePermission permission={FREIGHT_PERMS.settings.stamp.view}>
               <CompanyStampSettingsPage />
             </RequirePermission>
           }
@@ -878,7 +1101,9 @@ const App = () => {
         <Route
           path="configuration/exchange-rate"
           element={
-            <RequirePermission permission={FREIGHT_PERMS.settings.exchangeRate.view}>
+            <RequirePermission
+              permission={FREIGHT_PERMS.settings.exchangeRate.view}
+            >
               <div className="p-4">
                 <ExchangeRateSettingsCard />
               </div>
@@ -946,4 +1171,3 @@ function LegacyGlEthiopiaClearanceRedirect() {
 }
 
 export default App;
-
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 4548dc134..7114fa129 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -55,518 +55,519 @@ export const buildSidebarSections = (
   demoItems: SidebarItem[],
   reportItems: SidebarItem[] = [],
 ): SidebarSection[] => [
-  {
-    title: "Main menu",
-    items: [
-      {
-        label: "Overview",
-        href: "/dashboard/overview",
-        icon: <LayoutDashboard />,
-        permission: FREIGHT_PERMS.overview.view,
-      },
-      {
-        label: "Reports",
-        href: "/dashboard/reports",
-        icon: <BarChart3 />,
-        permission: FREIGHT_PERMS.reports.view,
-        // Populated from the live GET /reports catalog (already permission-
-        // filtered server-side) — no report key is ever hand-listed here.
-        ...(reportItems.length ? { children: reportItems } : {}),
-      },
-      {
-        label: "Customers",
-        href: "/dashboard/customers",
-        icon: <Building2 />,
-        permission: FREIGHT_PERMS.customers.view,
-      },
-      {
-        label: "Contracts",
-        href: "/dashboard/contract-requests",
-        icon: <FileSignature />,
-        permission: FREIGHT_PERMS.contracts.view,
-      },
-      {
-        label: "Bookings",
-        href: "/dashboard/booking-requests",
-        icon: <FileText />,
-        permission: FREIGHT_PERMS.bookings.view,
-      },
-      {
-        label: "Wagon cancellations",
-        href: "/dashboard/wagon-cancellations",
-        icon: <XCircle />,
-        permission: FREIGHT_PERMS.bookings.wagonCancellationView,
-      },
-      // Operations hub: per-shipment clearance-document review for services
-      // WITHOUT customs clearing (self-clearance) — bookings only.
-      {
-        label: "Clearance Documents",
-        href: "/dashboard/contracts/clearance-documents",
-        icon: <ShieldCheck />,
-        permission: FREIGHT_PERMS.contracts.opsClearanceReview,
-      },
-      {
-        label: "Payments",
-        href: "/dashboard/payments",
-        icon: <Wallet />,
-        permission: FREIGHT_PERMS.payments.view,
-      },
-      {
-        label: "Invoices",
-        href: "/dashboard/invoices",
-        icon: <Receipt />,
-        permission: FREIGHT_PERMS.invoices.view,
-      },
-      {
-        label: "USD Payments",
-        href: "/dashboard/usd-payments",
-        icon: <Landmark />,
-        permission: FREIGHT_PERMS.invoices.view,
-      },
-      {
-        label: "Support",
-        href: "/dashboard/support",
-        icon: <LifeBuoy />,
-        permission: FREIGHT_PERMS.support.agentView,
-      },
-      ...demoItems,
-    ],
-  },
-  {
-    // title: "Port & Terminal",
-    items: [
-      {
-        label: "Operations",
-        icon: <Settings />,
-        children: [
-          {
-            label: "Clearance",
-            href: "/dashboard/contracts/clearance",
-            icon: <ShieldCheck />,
-            permission: [
-              FREIGHT_PERMS.contracts.clearanceReview,
-              FREIGHT_PERMS.contracts.clearanceEtActions,
-            ],
-          },
-          // {
-          //   label: "Shipment Requests",
-          //   href: "/dashboard/shipment-requests",
-          //   icon: <Send />,
-          //   permission: FREIGHT_PERMS.contracts.createBooking,
-          // },
-          // Operations Path A queue: per-booking self-clearance review for
-          // GENERAL non-customs booking instances (and legacy self-clear bookings).
-          // {
-          //   label: "Self-Clearance Review",
-          //   href: "/dashboard/contracts/ops-clearance",
-          //   icon: <ShieldCheck />,
-          //   permission: FREIGHT_PERMS.contracts.opsClearanceReview,
-          // },
-          {
-            label: "GL Djibouti Clearance",
-            href: "/dashboard/gl-djibouti/clearance",
-            icon: <Ship />,
-            permission: FREIGHT_PERMS.contracts.clearanceDjActions,
-          },
-          {
-            label: "Train Schedules",
-            href: "/dashboard/operations/train-scheduling-v2",
-            icon: <Train />,
-            permission: FREIGHT_PERMS.trainScheduling.view,
-          },
-          {
-            label: "Batch Board",
-            href: "/dashboard/operations/batch-board",
-            icon: <LayoutGrid />,
-            permission: FREIGHT_PERMS.trainScheduling.view,
-          },
-          {
-            label: "First Mile",
-            href: "/dashboard/operations/first-mile",
-            icon: <Truck />,
-            permission: FREIGHT_PERMS.firstMile.view,
-          },
-          {
-            label: "Last Mile",
-            href: "/dashboard/operations/last-mile",
-            icon: <Truck />,
-            permission: FREIGHT_PERMS.lastMile.view,
-          },
-        ],
-      },
-      {
-        label: "Fleet Management",
-        icon: <Truck />,
-        children: [
-          {
-            label: "Fleet Dashboard",
-            href: "/dashboard/fleet-dashboard",
-            icon: <LayoutDashboard />,
-            permission: FREIGHT_PERMS.fleetDashboard.view,
-          },
-          {
-            label: "Routes",
-            href: "/dashboard/routes",
-            icon: <Network />,
-            permission: FREIGHT_PERMS.routes.view,
-          },
-          {
-            label: "Locomotives",
-            href: "/dashboard/locomotives",
-            icon: <Train />,
-            permission: FREIGHT_PERMS.locomotives.view,
-          },
-          {
-            label: "Train Builder",
-            href: "/dashboard/train-builder",
-            icon: <Hammer />,
-            permission: FREIGHT_PERMS.trains.view,
-          },
+    {
+      title: "Main menu",
+      items: [
+        {
+          label: "Overview",
+          href: "/dashboard/overview",
+          icon: <LayoutDashboard />,
+          permission: FREIGHT_PERMS.overview.view,
+        },
+        {
+          label: "Customers",
+          href: "/dashboard/customers",
+          icon: <Building2 />,
+          permission: FREIGHT_PERMS.customers.view,
+        },
+        {
+          label: "Contracts",
+          href: "/dashboard/contract-requests",
+          icon: <FileSignature />,
+          permission: FREIGHT_PERMS.contracts.view,
+        },
+        {
+          label: "Bookings",
+          href: "/dashboard/booking-requests",
+          icon: <FileText />,
+          permission: FREIGHT_PERMS.bookings.view,
+        },
+        {
+          label: "Wagon cancellations",
+          href: "/dashboard/wagon-cancellations",
+          icon: <XCircle />,
+          permission: FREIGHT_PERMS.bookings.wagonCancellationView,
+        },
+        // Operations hub: per-shipment clearance-document review for services
+        // WITHOUT customs clearing (self-clearance) — bookings only.
+        {
+          label: "Clearance Documents",
+          href: "/dashboard/contracts/clearance-documents",
+          icon: <ShieldCheck />,
+          permission: FREIGHT_PERMS.contracts.opsClearanceReview,
+        },
+        {
+          label: "Payments",
+          href: "/dashboard/payments",
+          icon: <Wallet />,
+          permission: FREIGHT_PERMS.payments.view,
+        },
+        {
+          label: "Invoices",
+          href: "/dashboard/invoices",
+          icon: <Receipt />,
+          permission: FREIGHT_PERMS.invoices.view,
+        },
+        {
+          label: "USD Payments",
+          href: "/dashboard/usd-payments",
+          icon: <Landmark />,
+          permission: FREIGHT_PERMS.invoices.view,
+        },
+        {
+          label: "Support",
+          href: "/dashboard/support",
+          icon: <LifeBuoy />,
+          permission: FREIGHT_PERMS.support.agentView,
+        },
+        ...demoItems,
+      ],
+    },
+    {
+      // title: "Port & Terminal",
+      items: [
+        {
+          label: "Operations",
+          icon: <Settings />,
+          children: [
+            {
+              label: "Clearance",
+              href: "/dashboard/contracts/clearance",
+              icon: <ShieldCheck />,
+              permission: [
+                FREIGHT_PERMS.contracts.clearanceReview,
+                FREIGHT_PERMS.contracts.clearanceEtActions,
+              ],
+            },
+            // {
+            //   label: "Shipment Requests",
+            //   href: "/dashboard/shipment-requests",
+            //   icon: <Send />,
+            //   permission: FREIGHT_PERMS.contracts.createBooking,
+            // },
+            // Operations Path A queue: per-booking self-clearance review for
+            // GENERAL non-customs booking instances (and legacy self-clear bookings).
+            // {
+            //   label: "Self-Clearance Review",
+            //   href: "/dashboard/contracts/ops-clearance",
+            //   icon: <ShieldCheck />,
+            //   permission: FREIGHT_PERMS.contracts.opsClearanceReview,
+            // },
+            {
+              label: "GL Djibouti Clearance",
+              href: "/dashboard/gl-djibouti/clearance",
+              icon: <Ship />,
+              permission: FREIGHT_PERMS.contracts.clearanceDjActions,
+            },
+            {
+              label: "Train Schedules",
+              href: "/dashboard/operations/train-scheduling-v2",
+              icon: <Train />,
+              permission: FREIGHT_PERMS.trainScheduling.view,
+            },
+            {
+              label: "Batch Board",
+              href: "/dashboard/operations/batch-board",
+              icon: <LayoutGrid />,
+              permission: FREIGHT_PERMS.trainScheduling.view,
+            },
+            {
+              label: "First Mile",
+              href: "/dashboard/operations/first-mile",
+              icon: <Truck />,
+              permission: FREIGHT_PERMS.firstMile.view,
+            },
+            {
+              label: "Last Mile",
+              href: "/dashboard/operations/last-mile",
+              icon: <Truck />,
+              permission: FREIGHT_PERMS.lastMile.view,
+            },
+          ],
+        },
+        {
+          label: "Fleet Management",
+          icon: <Truck />,
+          children: [
+            {
+              label: "Fleet Dashboard",
+              href: "/dashboard/fleet-dashboard",
+              icon: <LayoutDashboard />,
+              permission: FREIGHT_PERMS.fleetDashboard.view,
+            },
+            {
+              label: "Routes",
+              href: "/dashboard/routes",
+              icon: <Network />,
+              permission: FREIGHT_PERMS.routes.view,
+            },
+            {
+              label: "Locomotives",
+              href: "/dashboard/locomotives",
+              icon: <Train />,
+              permission: FREIGHT_PERMS.locomotives.view,
+            },
+            {
+              label: "Train Builder",
+              href: "/dashboard/train-builder",
+              icon: <Hammer />,
+              permission: FREIGHT_PERMS.trains.view,
+            },
 
-          // {
-          //   label: "Wagon types",
-          //   href: "/dashboard/wagon-types",
-          //   icon: <Boxes />,
-          // },
-          {
-            label: "Wagons",
-            href: "/dashboard/wagons",
-            icon: <Truck />,
-            permission: FREIGHT_PERMS.wagons.view,
-          },
-          {
-            label: "Wagon Transfers",
-            href: "/dashboard/wagon-transfers",
-            icon: <ArrowLeftRight />,
-            permission: [
-              FREIGHT_PERMS.wagons.transferView,
-              FREIGHT_PERMS.wagons.view,
-            ],
-          },
-          {
-            label: "Vehicles",
-            href: "/dashboard/vehicles",
-            icon: <Truck />,
-            permission: FREIGHT_PERMS.vehicles.view,
-          },
-          {
-            label: "Drivers",
-            href: "/dashboard/drivers",
-            icon: <Users />,
-            permission: FREIGHT_PERMS.drivers.view,
-          },
-          {
-            label: "Track Vehicles",
-            href: "/dashboard/tracking",
-            icon: <MapPin />,
-            permission: FREIGHT_PERMS.tracking.view,
-          },
-          {
-            label: "Fuel Purchases",
-            href: "/dashboard/fuel-purchases",
-            icon: <Truck />,
-            permission: FREIGHT_PERMS.fuel.view,
-          },
-          {
-            label: "Fuel Analytics",
-            href: "/dashboard/fuel-stats",
-            icon: <Truck />,
-            permission: FREIGHT_PERMS.fuel.view,
-          },
-          {
-            label: "Maintenance",
-            href: "/dashboard/maintenance",
-            icon: <Truck />,
-            permission: FREIGHT_PERMS.maintenance.view,
-          },
-          {
-            label: "Work Orders",
-            href: "/dashboard/work-orders",
-            icon: <SlidersHorizontal />,
-            permission: FREIGHT_PERMS.maintenance.view,
-          },
-          {
-            label: "Compliance & Alerts",
-            href: "/dashboard/compliance",
-            icon: <ShieldCheck />,
-            permission: FREIGHT_PERMS.compliance.view,
-          },
-          {
-            label: "Incidents",
-            href: "/dashboard/incidents",
-            icon: <FileText />,
-            // No dedicated backend key exists for incidents yet. Not part of
-            // the fleet.view/admin fallback cleanup — removing fleet.view
-            // here with nothing to replace it would lock the page to
-            // super-admin only, so it stays as the sole (if coarse) gate.
-            permission: FREIGHT_PERMS.fleet.view,
-          },
-          {
-            label: "Procurement",
-            href: "/dashboard/procurement",
-            icon: <Package />,
-            permission: FREIGHT_PERMS.procurement.view,
-          },
-          {
-            label: "Financial Reports",
-            href: "/dashboard/financial-reports",
-            icon: <Wallet />,
-            permission: FREIGHT_PERMS.fleetReports.view,
-          },
-          // {
-          //   label: "Containers",
-          //   href: "/dashboard/containers",
-          //   icon: <Container />,
-          // },
-          // {
-          //   label: "Cargoes",
-          //   href: "/dashboard/cargoes",
-          //   icon: <Package />,
-          // },
-        ],
-      },
-      {
-        label: "Imports",
-        href: "/dashboard/import-warehouse",
-        icon: <PackageOpen />,
-        permission: FREIGHT_PERMS.warehouseInventory.view,
-        children: [
-          {
-            label: "Import Overview",
-            href: "/dashboard/import-warehouse",
-            icon: <PackageOpen />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-          {
-            label: "Arrival Queue",
-            href: "/dashboard/arrival-queue",
-            icon: <PackageOpen />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-          {
-            label: "Import Trucks",
-            href: "/dashboard/import-trucks",
-            icon: <Truck />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-          {
-            label: "Container Returns",
-            href: "/dashboard/container-returns",
-            icon: <Container />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-          {
-            label: "Terminal Inventory",
-            href: "/dashboard/warehouse-inventory?direction=IMPORT",
-            icon: <Package />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-          {
-            label: "Inventory Inquiry",
-            href: "/dashboard/inventory-inquiry",
-            icon: <Boxes />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-        ],
-      },
-      {
-        label: "Exports",
-        href: "/dashboard/export-warehouse",
-        icon: <Truck />,
-        permission: FREIGHT_PERMS.warehouseInventory.view,
-        children: [
-          {
-            label: "Export Overview",
-            href: "/dashboard/export-warehouse",
-            icon: <Truck />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-          {
-            label: "Loading Queue",
-            href: "/dashboard/loading-queue",
-            icon: <Truck />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-          {
-            label: "Loaded Inventory",
-            href: "/dashboard/loaded-inventory",
-            icon: <PackageCheck />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-          {
-            label: "Dispatch Queue",
-            href: "/dashboard/dispatch-queue",
-            icon: <Send />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-          {
-            label: "Djibouti Unloading",
-            href: "/dashboard/export-djibouti-unloading",
-            icon: <PackageOpen />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-          {
-            label: "Interchange Documents",
-            href: "/dashboard/interchange-documents",
-            icon: <FileText />,
-            permission: FREIGHT_PERMS.interchangeDocuments.view,
-          },
-          {
-            label: "Terminal Inventory",
-            href: "/dashboard/warehouse-inventory?direction=EXPORT",
-            icon: <Package />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-        ],
-      },
-      {
-        label: "Intercity",
-        href: "/dashboard/intercity",
-        icon: <TrainFront />,
-        permission: FREIGHT_PERMS.trainScheduling.view,
-        children: [
-          {
-            label: "Intercity Cargo",
-            href: "/dashboard/intercity",
-            icon: <TrainFront />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-        ],
-      },
-      {
-        label: "Warehouse Management",
-        icon: <Container />,
-        children: [
-          {
-            label: "Warehouse Dashboard",
-            href: "/dashboard/warehouse-dashboard",
-            icon: <LayoutDashboard />,
-            permission: FREIGHT_PERMS.warehouseDashboard.view,
-          },
-          {
-            // Yard-wide, not per-direction: the gate sees import and export
-            // trucks at the same barrier.
-            label: "Trucks on Site",
-            href: "/dashboard/trucks-on-site",
-            icon: <Truck />,
-            permission: FREIGHT_PERMS.warehouseInventory.view,
-          },
-          {
-            label: "Warehouses",
-            href: "/dashboard/warehouses",
-            icon: <Container />,
-            permission: FREIGHT_PERMS.warehouses.view,
-          },
-          {
-            label: "Allocation & Fees",
-            href: "/dashboard/warehouse-rules",
-            icon: <SlidersHorizontal />,
-            permission: [
-              FREIGHT_PERMS.warehouseAllocationRules.view,
-              FREIGHT_PERMS.warehouseFeeRules.view,
-            ],
-          },
-          {
-            label: "Fee Invoices",
-            href: "/dashboard/warehouse-fee-invoices",
-            icon: <Wallet />,
-            permission: FREIGHT_PERMS.warehouseFeeInvoices.view,
-          },
-        ],
-      },
-    ],
-  },
-  {
-    title: "Freight configuration",
-    mutedTitle: true,
-    items: [
-      {
-        label: "File settings",
-        href: "/dashboard/file-settings",
-        icon: <Paperclip />,
-        permission: FREIGHT_PERMS.settings.fileUpload.view,
-      },
-      {
-        label: "Dropdown settings",
-        href: "/dashboard/dropdown-settings",
-        icon: <Settings />,
-        permission: FREIGHT_PERMS.settings.dropdown.view,
-      },
-      {
-        // One entry, one stamp. The former "Stamp settings" entry here pointed
-        // at the per-officer teeter (ማህተም), not a company seal — it moved to
-        // /user-management/teeter-and-signature.
-        label: "Company stamp",
-        href: "/dashboard/stamp-settings",
-        icon: <Stamp />,
-        permission: FREIGHT_PERMS.settings.stamp.view,
-      },
-      {
-        label: "Contract templates",
-        href: "/dashboard/contract-templates",
-        icon: <ScrollText />,
-        // `view` opens the page; `read` alone is API-only and shows no menu.
-        permission: FREIGHT_PERMS.settings.contractTemplates.view,
-      },
-      {
-        label: "Portal content",
-        href: "/dashboard/portal-content",
-        icon: <BookOpen />,
-        permission: [
-          FREIGHT_PERMS.settings.supportContent.view,
-          FREIGHT_PERMS.settings.supportContent.manage,
-        ],
-      },
-      {
-        label: "Audit logs",
-        href: "/dashboard/audit-logs",
-        icon: <History />,
-        permission: FREIGHT_PERMS.auditLog.view,
-      },
-      {
-        label: "Configuration",
-        href: "/dashboard/configuration",
-        icon: <Boxes />,
-        children: [
-          ...getCategorySidebarChildren("configuration"),
-          {
-            label: "Train scheduling rules",
-            href: "/dashboard/configuration/train-scheduling-rules",
-            permission: FREIGHT_PERMS.trainScheduling.rulesManage,
-          },
-          {
-            label: "Trade access",
-            href: "/dashboard/configuration/trade-access",
-            permission: FREIGHT_PERMS.tradeAccess.view,
-          },
-          {
-            label: "Exchange rate",
-            href: "/dashboard/configuration/exchange-rate",
-            permission: FREIGHT_PERMS.settings.exchangeRate.view,
-          },
-        ],
-      },
-      {
-        label: "Rules",
-        href: "/dashboard/rules",
-        icon: <SlidersHorizontal />,
-        children: getCategorySidebarChildren("rules"),
-      },
+            // {
+            //   label: "Wagon types",
+            //   href: "/dashboard/wagon-types",
+            //   icon: <Boxes />,
+            // },
+            {
+              label: "Wagons",
+              href: "/dashboard/wagons",
+              icon: <Truck />,
+              permission: FREIGHT_PERMS.wagons.view,
+            },
+            {
+              label: "Wagon Transfers",
+              href: "/dashboard/wagon-transfers",
+              icon: <ArrowLeftRight />,
+              permission: [
+                FREIGHT_PERMS.wagons.transferView,
+                FREIGHT_PERMS.wagons.view,
+              ],
+            },
+            {
+              label: "Vehicles",
+              href: "/dashboard/vehicles",
+              icon: <Truck />,
+              permission: FREIGHT_PERMS.vehicles.view,
+            },
+            {
+              label: "Drivers",
+              href: "/dashboard/drivers",
+              icon: <Users />,
+              permission: FREIGHT_PERMS.drivers.view,
+            },
+            {
+              label: "Track Vehicles",
+              href: "/dashboard/tracking",
+              icon: <MapPin />,
+              permission: FREIGHT_PERMS.tracking.view,
+            },
+            {
+              label: "Fuel Purchases",
+              href: "/dashboard/fuel-purchases",
+              icon: <Truck />,
+              permission: FREIGHT_PERMS.fuel.view,
+            },
+            {
+              label: "Fuel Analytics",
+              href: "/dashboard/fuel-stats",
+              icon: <Truck />,
+              permission: FREIGHT_PERMS.fuel.view,
+            },
+            {
+              label: "Maintenance",
+              href: "/dashboard/maintenance",
+              icon: <Truck />,
+              permission: FREIGHT_PERMS.maintenance.view,
+            },
+            {
+              label: "Work Orders",
+              href: "/dashboard/work-orders",
+              icon: <SlidersHorizontal />,
+              permission: FREIGHT_PERMS.maintenance.view,
+            },
+            {
+              label: "Compliance & Alerts",
+              href: "/dashboard/compliance",
+              icon: <ShieldCheck />,
+              permission: FREIGHT_PERMS.compliance.view,
+            },
+            {
+              label: "Incidents",
+              href: "/dashboard/incidents",
+              icon: <FileText />,
+              // No dedicated backend key exists for incidents yet. Not part of
+              // the fleet.view/admin fallback cleanup — removing fleet.view
+              // here with nothing to replace it would lock the page to
+              // super-admin only, so it stays as the sole (if coarse) gate.
+              permission: FREIGHT_PERMS.fleet.view,
+            },
+            {
+              label: "Procurement",
+              href: "/dashboard/procurement",
+              icon: <Package />,
+              permission: FREIGHT_PERMS.procurement.view,
+            },
+            {
+              label: "Financial Reports",
+              href: "/dashboard/financial-reports",
+              icon: <Wallet />,
+              permission: FREIGHT_PERMS.fleetReports.view,
+            },
+            // {
+            //   label: "Containers",
+            //   href: "/dashboard/containers",
+            //   icon: <Container />,
+            // },
+            // {
+            //   label: "Cargoes",
+            //   href: "/dashboard/cargoes",
+            //   icon: <Package />,
+            // },
+          ],
+        },
+        {
+          label: "Imports",
+          href: "/dashboard/import-warehouse",
+          icon: <PackageOpen />,
+          permission: FREIGHT_PERMS.warehouseInventory.view,
+          children: [
+            {
+              label: "Import Overview",
+              href: "/dashboard/import-warehouse",
+              icon: <PackageOpen />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+            {
+              label: "Arrival Queue",
+              href: "/dashboard/arrival-queue",
+              icon: <PackageOpen />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+            {
+              label: "Import Trucks",
+              href: "/dashboard/import-trucks",
+              icon: <Truck />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+            {
+              label: "Container Returns",
+              href: "/dashboard/container-returns",
+              icon: <Container />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+            {
+              label: "Terminal Inventory",
+              href: "/dashboard/warehouse-inventory?direction=IMPORT",
+              icon: <Package />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+            {
+              label: "Inventory Inquiry",
+              href: "/dashboard/inventory-inquiry",
+              icon: <Boxes />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+          ],
+        },
+        {
+          label: "Exports",
+          href: "/dashboard/export-warehouse",
+          icon: <Truck />,
+          permission: FREIGHT_PERMS.warehouseInventory.view,
+          children: [
+            {
+              label: "Export Overview",
+              href: "/dashboard/export-warehouse",
+              icon: <Truck />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+            {
+              label: "Loading Queue",
+              href: "/dashboard/loading-queue",
+              icon: <Truck />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+            {
+              label: "Loaded Inventory",
+              href: "/dashboard/loaded-inventory",
+              icon: <PackageCheck />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+            {
+              label: "Dispatch Queue",
+              href: "/dashboard/dispatch-queue",
+              icon: <Send />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+            {
+              label: "Djibouti Unloading",
+              href: "/dashboard/export-djibouti-unloading",
+              icon: <PackageOpen />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+            {
+              label: "Interchange Documents",
+              href: "/dashboard/interchange-documents",
+              icon: <FileText />,
+              permission: FREIGHT_PERMS.interchangeDocuments.view,
+            },
+            {
+              label: "Terminal Inventory",
+              href: "/dashboard/warehouse-inventory?direction=EXPORT",
+              icon: <Package />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+          ],
+        },
+        {
+          label: "Intercity",
+          href: "/dashboard/intercity",
+          icon: <TrainFront />,
+          permission: FREIGHT_PERMS.trainScheduling.view,
+          children: [
+            {
+              label: "Intercity Cargo",
+              href: "/dashboard/intercity",
+              icon: <TrainFront />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+          ],
+        },
+        {
+          label: "Warehouse Management",
+          icon: <Container />,
+          children: [
+            {
+              label: "Warehouse Dashboard",
+              href: "/dashboard/warehouse-dashboard",
+              icon: <LayoutDashboard />,
+              permission: FREIGHT_PERMS.warehouseDashboard.view,
+            },
+            {
+              // Yard-wide, not per-direction: the gate sees import and export
+              // trucks at the same barrier.
+              label: "Trucks on Site",
+              href: "/dashboard/trucks-on-site",
+              icon: <Truck />,
+              permission: FREIGHT_PERMS.warehouseInventory.view,
+            },
+            {
+              label: "Warehouses",
+              href: "/dashboard/warehouses",
+              icon: <Container />,
+              permission: FREIGHT_PERMS.warehouses.view,
+            },
+            {
+              label: "Allocation & Fees",
+              href: "/dashboard/warehouse-rules",
+              icon: <SlidersHorizontal />,
+              permission: [
+                FREIGHT_PERMS.warehouseAllocationRules.view,
+                FREIGHT_PERMS.warehouseFeeRules.view,
+              ],
+            },
+            {
+              label: "Fee Invoices",
+              href: "/dashboard/warehouse-fee-invoices",
+              icon: <Wallet />,
+              permission: FREIGHT_PERMS.warehouseFeeInvoices.view,
+            },
+          ],
+        },
 
-      {
-        label: "Staff",
-        href: "/user-management",
-        icon: <Users />,
-        permission: [
-          FREIGHT_PERMS.admin,
-          FREIGHT_PERMS.staff.roles.view,
-          FREIGHT_PERMS.staff.employeeRegistration.view,
-          FREIGHT_PERMS.staff.roleAssignment.view,
-        ],
-      },
-    ],
-  },
-];
+        {
+          label: "Reports",
+          href: "/dashboard/reports",
+          icon: <BarChart3 />,
+          permission: FREIGHT_PERMS.reports.view,
+          // Populated from the live GET /reports catalog (already permission-
+          // filtered server-side) — no report key is ever hand-listed here.
+          ...(reportItems.length ? { children: reportItems } : {}),
+        },
+      ],
+    },
+    {
+      title: "Freight configuration",
+      mutedTitle: true,
+      items: [
+        {
+          label: "File settings",
+          href: "/dashboard/file-settings",
+          icon: <Paperclip />,
+          permission: FREIGHT_PERMS.settings.fileUpload.view,
+        },
+        {
+          label: "Dropdown settings",
+          href: "/dashboard/dropdown-settings",
+          icon: <Settings />,
+          permission: FREIGHT_PERMS.settings.dropdown.view,
+        },
+        {
+          // One entry, one stamp. The former "Stamp settings" entry here pointed
+          // at the per-officer teeter (ማህተም), not a company seal — it moved to
+          // /user-management/teeter-and-signature.
+          label: "Company stamp",
+          href: "/dashboard/stamp-settings",
+          icon: <Stamp />,
+          permission: FREIGHT_PERMS.settings.stamp.view,
+        },
+        {
+          label: "Contract templates",
+          href: "/dashboard/contract-templates",
+          icon: <ScrollText />,
+          // `view` opens the page; `read` alone is API-only and shows no menu.
+          permission: FREIGHT_PERMS.settings.contractTemplates.view,
+        },
+        {
+          label: "Portal content",
+          href: "/dashboard/portal-content",
+          icon: <BookOpen />,
+          permission: [
+            FREIGHT_PERMS.settings.supportContent.view,
+            FREIGHT_PERMS.settings.supportContent.manage,
+          ],
+        },
+        {
+          label: "Audit logs",
+          href: "/dashboard/audit-logs",
+          icon: <History />,
+          permission: FREIGHT_PERMS.auditLog.view,
+        },
+        {
+          label: "Configuration",
+          href: "/dashboard/configuration",
+          icon: <Boxes />,
+          children: [
+            ...getCategorySidebarChildren("configuration"),
+            {
+              label: "Train scheduling rules",
+              href: "/dashboard/configuration/train-scheduling-rules",
+              permission: FREIGHT_PERMS.trainScheduling.rulesManage,
+            },
+            {
+              label: "Trade access",
+              href: "/dashboard/configuration/trade-access",
+              permission: FREIGHT_PERMS.tradeAccess.view,
+            },
+            {
+              label: "Exchange rate",
+              href: "/dashboard/configuration/exchange-rate",
+              permission: FREIGHT_PERMS.settings.exchangeRate.view,
+            },
+          ],
+        },
+        {
+          label: "Rules",
+          href: "/dashboard/rules",
+          icon: <SlidersHorizontal />,
+          children: getCategorySidebarChildren("rules"),
+        },
+
+        {
+          label: "Staff",
+          href: "/user-management",
+          icon: <Users />,
+          permission: [
+            FREIGHT_PERMS.admin,
+            FREIGHT_PERMS.staff.roles.view,
+            FREIGHT_PERMS.staff.employeeRegistration.view,
+            FREIGHT_PERMS.staff.roleAssignment.view,
+          ],
+        },
+      ],
+    },
+  ];
 
 /**
  * Keep only items the user is permitted to see; drop now-empty sections.

From 89dba01cd797ed561341195fccac1c449e8957fd Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Thu, 13 Aug 2026 09:27:01 +0000
Subject: [PATCH 077/174] feat(train-scheduling): notify customer of CAS on
 direct-to-train load

Direct truck-to-train export cargo skips the warehouse, so the existing
carriage acceptance sheet ready notice (fired on warehouse receive)
never reached these bookings. Their handover moment is the load itself.

Extract notifyCarriageAcceptanceReady into a shared notifications util
(was private to WarehouseInventoryService) and call it from
BookingJourneyService.loadBooking for EXPORT + DIRECT_TO_TRAIN bookings,
right after the GRN gate, before the load transaction proceeds.
---
 .../notifications/notify-company.util.ts      | 41 +++++++++++++++++++
 .../booking-journey.service.spec.ts           |  2 +
 .../booking-journey.service.ts                | 22 +++++++++-
 .../warehouses/warehouse-inventory.service.ts | 32 +++++----------
 4 files changed, 75 insertions(+), 22 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/notifications/notify-company.util.ts b/apps/edr-freight-api/src/modules/notifications/notify-company.util.ts
index e3b2fd80a..467b172ba 100644
--- a/apps/edr-freight-api/src/modules/notifications/notify-company.util.ts
+++ b/apps/edr-freight-api/src/modules/notifications/notify-company.util.ts
@@ -1,6 +1,9 @@
 import { DataSource } from 'typeorm';
+import { Logger } from '@nestjs/common';
 
+import { NotificationAudience, NotificationType } from '@edr/types';
 import { NotificationsService } from './notifications.service';
+import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
 import {
   companyNotifyEmailExpr,
   companyNotifyPhoneExpr,
@@ -42,3 +45,41 @@ export async function sendCompanyChannels(
     }
   }
 }
+
+/**
+ * Tell the customer their export carriage acceptance sheet is ready to
+ * download from the portal — the sheet itself is generated on demand by
+ * BookingsService.carriageAcceptanceSheet, never stored, so this is a
+ * "ready" notice + link, not an attachment (the email pipeline carries text
+ * only). Shared by every path that makes a booking's handover final: the
+ * warehouse gate on receive, and direct truck-to-train on load (that cargo
+ * never sees a warehouse, so its handover moment IS the load).
+ */
+export async function notifyCarriageAcceptanceReady(
+  dataSource: DataSource,
+  notifications: NotificationsService,
+  inbox: NotificationInboxService,
+  bookingId: string,
+  logger: Logger,
+): Promise<void> {
+  try {
+    const [b]: Array<{ companyId: string | null; reference: string }> = await dataSource.query(
+      `SELECT company_id AS "companyId", reference FROM freight.bookings WHERE id = $1 AND deleted_at IS NULL`,
+      [bookingId],
+    );
+    if (!b?.companyId) return;
+    const body = `Your carriage acceptance sheet for booking ${b.reference} is ready to download from the portal.`;
+    await inbox.notify({
+      recipients: { companyId: b.companyId },
+      audience: NotificationAudience.PORTAL,
+      type: NotificationType.DOCUMENT_ACTION,
+      title: 'Carriage acceptance sheet ready',
+      body,
+      link: `/bookings/${bookingId}`,
+      data: { bookingId, reference: b.reference },
+    });
+    await sendCompanyChannels(dataSource, notifications, b.companyId, body);
+  } catch (err) {
+    logger.warn(`Carriage acceptance ready notify failed for ${bookingId}: ${(err as Error).message}`);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.spec.ts
index 0a8cc99fe..ea936465e 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.spec.ts
@@ -11,6 +11,8 @@ describe('BookingJourneyService.autoPlaceOnFreedWagons', () => {
     {} as never, // yardFacilities
     {} as never, // facilityHandling
     { emit: jest.fn() } as never, // events
+    {} as never, // notifications
+    {} as never, // inbox
   );
 
   const schedule = { id: 'sched-1', trainSetId: 'ts-1' };
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.ts
index bf6ab5069..56b28fb7f 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/booking-journey.service.ts
@@ -24,7 +24,10 @@ import { WagonBookingAllocation } from '../train-schedules/entities/wagon-bookin
 import { Wagon } from '../wagons/entities/wagon.entity';
 import { WagonMovement } from '../wagons/entities/wagon-movement.entity';
 import { TrainCheckpointEvent } from './entities/train-checkpoint-event.entity';
-import { assertExportReceivedWithGrn } from '../../common/export-received-gate';
+import { assertExportReceivedWithGrn, DIRECT_TO_TRAIN } from '../../common/export-received-gate';
+import { NotificationsService } from '../notifications/notifications.service';
+import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
+import { notifyCarriageAcceptanceReady } from '../notifications/notify-company.util';
 
 /**
  * Per-booking journey along a train's corridor — for EVERY trade direction.
@@ -52,6 +55,8 @@ export class BookingJourneyService {
     private readonly yardFacilities: YardFacilitiesService,
     private readonly facilityHandling: FacilityHandlingService,
     private readonly events: EventEmitter2,
+    private readonly notifications: NotificationsService,
+    private readonly inbox: NotificationInboxService,
     @Optional() private readonly milestoneService?: ClearanceMilestoneService,
   ) {}
 
@@ -76,6 +81,21 @@ export class BookingJourneyService {
     // Export cargo must be in the warehouse with a GRN before it can be loaded,
     // however it arrived and whatever it is allocated to.
     await assertExportReceivedWithGrn(this.dataSource, booking);
+    // Direct truck-to-train cargo never sees the warehouse, so loading IS its
+    // handover moment — the carriage acceptance sheet must go out to the
+    // customer right here, not on a receive event that will never fire.
+    if (
+      booking.tradeDirection === 'EXPORT' &&
+      booking.exportHandoverMode === DIRECT_TO_TRAIN
+    ) {
+      await notifyCarriageAcceptanceReady(
+        this.dataSource,
+        this.notifications,
+        this.inbox,
+        booking.id,
+        this.logger,
+      );
+    }
 
     const now = new Date();
     await this.dataSource.transaction(async (manager) => {
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 239485d3c..163b5bcc1 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
@@ -28,7 +28,10 @@ import type { InterchangeDocument } from '../interchange-documents/entities/inte
 import { LastMileService } from '../last-mile/last-mile.service';
 import { UpdateLastMileDto } from '../last-mile/dto/update-last-mile.dto';
 import { NotificationsService } from '../notifications/notifications.service';
-import { sendCompanyChannels } from '../notifications/notify-company.util';
+import {
+  sendCompanyChannels,
+  notifyCarriageAcceptanceReady as notifyCarriageAcceptanceReadyShared,
+} from '../notifications/notify-company.util';
 import {
   companyNotifyPhoneExpr,
   primaryContactUserJoin,
@@ -6167,26 +6170,13 @@ export class WarehouseInventoryService {
    * fires right after receive, not at marshalling.
    */
   private async notifyCarriageAcceptanceReady(bookingId: string): Promise<void> {
-    try {
-      const [b]: Array<{ companyId: string | null; reference: string }> = await this.dataSource.query(
-        `SELECT company_id AS "companyId", reference FROM freight.bookings WHERE id = $1 AND deleted_at IS NULL`,
-        [bookingId],
-      );
-      if (!b?.companyId) return;
-      const body = `Your carriage acceptance sheet for booking ${b.reference} is ready to download from the portal.`;
-      await this.inbox.notify({
-        recipients: { companyId: b.companyId },
-        audience: NotificationAudience.PORTAL,
-        type: NotificationType.DOCUMENT_ACTION,
-        title: 'Carriage acceptance sheet ready',
-        body,
-        link: `/bookings/${bookingId}`,
-        data: { bookingId, reference: b.reference },
-      });
-      await sendCompanyChannels(this.dataSource, this.notifications, b.companyId, body);
-    } catch (err) {
-      this.logger.warn(`Carriage acceptance ready notify failed for ${bookingId}: ${(err as Error).message}`);
-    }
+    await notifyCarriageAcceptanceReadyShared(
+      this.dataSource,
+      this.notifications,
+      this.inbox,
+      bookingId,
+      this.logger,
+    );
   }
 
   private async notifyOwnerInventoryReceived(params: {

From e66e622ededffd804fe61f840824a914309ee696 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Thu, 13 Aug 2026 09:52:43 +0000
Subject: [PATCH 078/174] eims cancellation

---
 .../eims/eims-cancellation.service.spec.ts      | 14 ++++++++------
 .../modules/eims/eims-cancellation.service.ts   | 17 ++++++++++++-----
 .../src/modules/eims/eims-invoice.controller.ts |  2 +-
 3 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.spec.ts
index ab5ea2548..6bd9b04b3 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.spec.ts
@@ -1,4 +1,4 @@
-import { BadRequestException } from "@nestjs/common";
+import { BadRequestException, ConflictException } from "@nestjs/common";
 import { DataSource } from "typeorm";
 
 import { Invoice } from "../billing/entities/invoice.entity";
@@ -96,14 +96,16 @@ describe("EimsCancellationService.cancelInvoiceWithEims", () => {
     expect(postBearer).toHaveBeenCalledWith("/v1/cancel", { Irn: IRN, ReasonCode: "1", Remark: "" });
   });
 
-  it("is idempotent — an already-cancelled invoice returns unchanged, no HTTP call", async () => {
-    const db = new FakeDb([invoiceRow({ eimsStatus: EimsInvoiceStatus.Cancelled })]);
+  it("refuses re-cancelling an already-cancelled invoice, per IRC-N010 — no silent no-op", async () => {
+    const db = new FakeDb([
+      invoiceRow({ eimsStatus: EimsInvoiceStatus.Cancelled, eimsCancellationDate: "Sun Dec 22 2024" }),
+    ]);
     const postBearer = jest.fn();
 
-    const view = await build(db, postBearer).cancelInvoiceWithEims(INVOICE_ID, "1");
-
+    await expect(build(db, postBearer).cancelInvoiceWithEims(INVOICE_ID, "1")).rejects.toBeInstanceOf(
+      ConflictException,
+    );
     expect(postBearer).not.toHaveBeenCalled();
-    expect(view.eimsStatus).toBe(EimsInvoiceStatus.Cancelled);
   });
 
   it("refuses to cancel an invoice that was never registered", async () => {
diff --git a/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.ts b/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.ts
index 83ff16704..73c3e87f4 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.ts
@@ -1,4 +1,4 @@
-import { BadRequestException, Injectable, Logger, NotFoundException } from "@nestjs/common";
+import { BadRequestException, ConflictException, Injectable, Logger, NotFoundException } from "@nestjs/common";
 import { InjectDataSource } from "@nestjs/typeorm";
 import { DataSource, EntityManager } from "typeorm";
 
@@ -38,8 +38,11 @@ export class EimsCancellationService {
   ) {}
 
   /**
-   * Idempotent: an already-cancelled invoice returns unchanged, no HTTP call. Refuses an invoice
-   * that was never registered — there is no IRN to cancel.
+   * Refuses an already-cancelled invoice with a 409, rather than a silent no-op — IRC-N010 in
+   * MoR's Master Compliance Checklist requires "an appropriate error or rejection message" for a
+   * repeat cancellation, not a quiet success. No HTTP call either way: this is a local check, not
+   * a retry against MoR. Also refuses an invoice that was never registered — there is no IRN to
+   * cancel.
    */
   async cancelInvoiceWithEims(
     invoiceId: string,
@@ -48,7 +51,12 @@ export class EimsCancellationService {
   ): Promise<EimsInvoiceStatusView> {
     const eligible = await this.dataSource.transaction(async (manager) => {
       const invoice = await this.lockInvoice(manager, invoiceId);
-      if (invoice.eimsStatus === EimsInvoiceStatus.Cancelled) return null;
+      if (invoice.eimsStatus === EimsInvoiceStatus.Cancelled) {
+        throw new ConflictException({
+          code: "EIMS_ALREADY_CANCELLED",
+          message: `Invoice ${invoice.invoiceNumber} was already cancelled with EIMS${invoice.eimsCancellationDate ? ` (${invoice.eimsCancellationDate})` : ""}.`,
+        });
+      }
       if (!invoice.eimsIrn) {
         throw new BadRequestException({
           code: "EIMS_NOT_REGISTERED",
@@ -57,7 +65,6 @@ export class EimsCancellationService {
       }
       return invoice;
     });
-    if (!eligible) return this.getEimsCancellationStatus(invoiceId);
 
     const request: EimsCancelRequest = { Irn: eligible.eimsIrn!, ReasonCode: reasonCode, Remark: remark ?? "" };
     // Outside any transaction — no DB lock is held across the wire.
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts
index 5db756329..c02c7870e 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts
@@ -81,7 +81,7 @@ export class EimsInvoiceController {
   @BookingStaff(FREIGHT_PERMS.invoices.eimsCancel)
   @ApiOperation({
     summary:
-      "Cancel the invoice's registered EIMS document. Idempotent — an already-cancelled invoice is returned unchanged.",
+      "Cancel the invoice's registered EIMS document. Refuses (409) an already-cancelled invoice rather than a silent no-op — see IRC-N010.",
   })
   cancel(@Param("id", ParseUUIDPipe) id: string, @Body() dto: CancelEimsRegistrationDto) {
     return this.cancellation.cancelInvoiceWithEims(id, dto.reasonCode, dto.remark);

From c4bf3c947954b5f386314976349b92414b99368e Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Thu, 13 Aug 2026 10:53:42 +0000
Subject: [PATCH 079/174] feat(freight): add company logo setting applied to
 every generated document

New logo-settings module (mirrors stamp-settings): single uploaded logo,
stored via FilesService/MinIO, injected as a data URL into invoice/receipt,
contract, warehouse, train-scheduling, and payment-receipt PDFs. Adds a
matching backoffice settings page and settings:logo:view/manage permissions.

>
---
 apps/edr-freight-api/src/app.module.ts        |   2 +
 .../contracts/contract-view-model.builder.ts  |   6 +
 .../contracts/templates/_partials/styles.hbs  |   6 +
 .../src/contracts/templates/edr-dynamic.hbs   |   2 +-
 .../src/contracts/templates/generic.hbs       |   2 +-
 .../src/contracts/templates/last-mile.hbs     |   3 +-
 .../migrations/3500000000000-LogoSettings.ts  |  27 +++
 .../invoice-document.service.spec.ts          |   2 +-
 .../documents/invoice-document.service.ts     |  13 +-
 .../billing/documents/logo-markup.util.ts     |  35 ++++
 .../last-mile-contract.service.ts             |   3 +
 .../dto/update-logo-setting.dto.ts            |   9 +
 .../entities/logo-setting.entity.ts           |  25 +++
 .../logo-settings/logo-settings.controller.ts |  39 ++++
 .../logo-settings/logo-settings.module.ts     |  24 +++
 .../logo-settings/logo-settings.repository.ts |  21 +++
 .../logo-settings/logo-settings.service.ts    | 161 ++++++++++++++++
 .../modules/payment/payment.service.spec.ts   |   2 +
 .../src/modules/payment/payment.service.ts    |   3 +
 .../src/modules/payment/templates/receipt.hbs |   9 +
 .../services/train-scheduling.service.spec.ts |   1 +
 .../services/train-scheduling.service.ts      |  20 +-
 .../warehouses/warehouse-inventory.service.ts |  18 ++
 .../src/seed/freight-permissions.registry.ts  |  16 ++
 apps/edr-freight-web/backoffice/src/App.tsx   |  10 +
 .../src/components/contracts/LogoUpload.tsx   | 172 ++++++++++++++++++
 .../components/layout/sidebar-sections.tsx    |   7 +
 .../backoffice/src/hooks/useLogoSettings.ts   |  45 +++++
 .../backoffice/src/lib/permissions.ts         |   6 +
 .../src/pages/settings/LogoSettingsPage.tsx   |  88 +++++++++
 .../src/services/logoSettings.service.ts      |  31 ++++
 31 files changed, 800 insertions(+), 8 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3500000000000-LogoSettings.ts
 create mode 100644 apps/edr-freight-api/src/modules/billing/documents/logo-markup.util.ts
 create mode 100644 apps/edr-freight-api/src/modules/logo-settings/dto/update-logo-setting.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/logo-settings/entities/logo-setting.entity.ts
 create mode 100644 apps/edr-freight-api/src/modules/logo-settings/logo-settings.controller.ts
 create mode 100644 apps/edr-freight-api/src/modules/logo-settings/logo-settings.module.ts
 create mode 100644 apps/edr-freight-api/src/modules/logo-settings/logo-settings.repository.ts
 create mode 100644 apps/edr-freight-api/src/modules/logo-settings/logo-settings.service.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/contracts/LogoUpload.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/hooks/useLogoSettings.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/settings/LogoSettingsPage.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/services/logoSettings.service.ts

diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index 1efe750fc..c106ffff2 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -49,6 +49,7 @@ import { FileUploadSettingsModule } from "./modules/file-upload-settings/file-up
 import { DropdownSettingsModule } from "./modules/dropdown-settings/dropdown-settings.module";
 import { ExchangeSettingsModule } from "./modules/exchange-settings/exchange-settings.module";
 import { StampSettingsModule } from "./modules/stamp-settings/stamp-settings.module";
+import { LogoSettingsModule } from "./modules/logo-settings/logo-settings.module";
 import { ContractTemplatesModule } from "./modules/contract-templates/contract-templates.module";
 import { SupportContentModule } from "./modules/support-content/support-content.module";
 import { OtpModule } from "./modules/otp/otp.module";
@@ -209,6 +210,7 @@ if (!process.env.APPLICATION_NAME) {
     DropdownSettingsModule,
     ExchangeSettingsModule,
     StampSettingsModule,
+    LogoSettingsModule,
     ContractTemplatesModule,
     SupportContentModule,
     OtpModule,
diff --git a/apps/edr-freight-api/src/contracts/contract-view-model.builder.ts b/apps/edr-freight-api/src/contracts/contract-view-model.builder.ts
index 94a6809e6..517934bb9 100644
--- a/apps/edr-freight-api/src/contracts/contract-view-model.builder.ts
+++ b/apps/edr-freight-api/src/contracts/contract-view-model.builder.ts
@@ -10,6 +10,7 @@ import { ContractPricingScheduleBuilder, PricingSchedule } from './contract-pric
 import { ContractRateScheduleBuilder, RateSchedule } from './contract-rate-schedule.builder';
 import { ContractTemplateResolver } from './contract-template.resolver';
 import { StampSettingsService } from '../modules/stamp-settings/stamp-settings.service';
+import { LogoSettingsService } from '../modules/logo-settings/logo-settings.service';
 import { ContractTemplateMeta, getTemplateMeta } from './contract-template.registry';
 
 export interface ContractSignatureView {
@@ -111,6 +112,8 @@ export interface ContractViewModel {
   hasCustomerSignature: boolean;
   hasStaffSignature: boolean;
   dynamicTemplate?: ContractDynamicTemplateView;
+  /** Company logo for the cover-page header (LogoSettingsService); null renders the "EDR" mark. */
+  logoImageUrl?: string | null;
 }
 
 @Injectable()
@@ -121,6 +124,7 @@ export class ContractViewModelBuilder {
     private readonly pricingBuilder: ContractPricingScheduleBuilder,
     private readonly rateScheduleBuilder: ContractRateScheduleBuilder,
     private readonly stampSettings: StampSettingsService,
+    private readonly logoSettings: LogoSettingsService,
   ) {}
 
   async build(bookingId: string): Promise<{ booking: Booking; view: ContractViewModel }> {
@@ -138,6 +142,7 @@ export class ContractViewModelBuilder {
       template.freight,
     );
     const signatures = await this.loadSignatures(bookingId);
+    const logoImageUrl = await this.logoSettings.getLogoImageUrl();
 
     const hasCustomer = signatures.some((s) => s.role === 'CUSTOMER');
     const hasStaff = signatures.some((s) => s.role === 'STAFF');
@@ -194,6 +199,7 @@ export class ContractViewModelBuilder {
       hasContractDocument: hasContractFile,
       hasCustomerSignature: hasCustomer,
       hasStaffSignature: hasStaff,
+      logoImageUrl,
     };
 
     return { booking, view };
diff --git a/apps/edr-freight-api/src/contracts/templates/_partials/styles.hbs b/apps/edr-freight-api/src/contracts/templates/_partials/styles.hbs
index d9bc9927f..09bf3031e 100644
--- a/apps/edr-freight-api/src/contracts/templates/_partials/styles.hbs
+++ b/apps/edr-freight-api/src/contracts/templates/_partials/styles.hbs
@@ -77,6 +77,12 @@
     letter-spacing: 0.08em;
     width: 72px;
   }
+  .logo-mark img {
+    display: block;
+    max-height: 100%;
+    max-width: 100%;
+    object-fit: contain;
+  }
   .kicker {
     color: #0e5b45;
     font-family: Arial, sans-serif;
diff --git a/apps/edr-freight-api/src/contracts/templates/edr-dynamic.hbs b/apps/edr-freight-api/src/contracts/templates/edr-dynamic.hbs
index 6ba7c1610..81631e5d2 100644
--- a/apps/edr-freight-api/src/contracts/templates/edr-dynamic.hbs
+++ b/apps/edr-freight-api/src/contracts/templates/edr-dynamic.hbs
@@ -11,7 +11,7 @@
     {{!-- ─────────────────────────── Cover page ─────────────────────────── --}}
     <section class="cover page-section">
       <div class="brand-row">
-        <div class="logo-mark">EDR</div>
+        <div class="logo-mark">{{#if logoImageUrl}}<img src="{{logoImageUrl}}" alt="Company logo" />{{else}}EDR{{/if}}</div>
         <div>
           <p class="kicker">Ethio-Djibouti Standard Gauge Railway Share Company</p>
           <p class="muted">Freight Transport Services</p>
diff --git a/apps/edr-freight-api/src/contracts/templates/generic.hbs b/apps/edr-freight-api/src/contracts/templates/generic.hbs
index 75f795bce..f576c99ce 100644
--- a/apps/edr-freight-api/src/contracts/templates/generic.hbs
+++ b/apps/edr-freight-api/src/contracts/templates/generic.hbs
@@ -9,7 +9,7 @@
   <main class="contract">
     <section class="cover page-section">
       <div class="brand-row">
-        <div class="logo-mark">EDR</div>
+        <div class="logo-mark">{{#if logoImageUrl}}<img src="{{logoImageUrl}}" alt="Company logo" />{{else}}EDR{{/if}}</div>
         <div>
           <p class="kicker">Ethio-Djibouti Standard Gauge Railway Share Company</p>
           <p class="muted">Freight Transport Contract</p>
diff --git a/apps/edr-freight-api/src/contracts/templates/last-mile.hbs b/apps/edr-freight-api/src/contracts/templates/last-mile.hbs
index 9437bb18b..0cfef51d5 100644
--- a/apps/edr-freight-api/src/contracts/templates/last-mile.hbs
+++ b/apps/edr-freight-api/src/contracts/templates/last-mile.hbs
@@ -9,6 +9,7 @@
     main { padding: 32px 40px; }
     .brand-row { display: flex; align-items: center; gap: 14px; border-bottom: 3px solid #1a5632; padding-bottom: 14px; }
     .logo-mark { background: #1a5632; color: #fff; font-weight: 700; font-size: 18px; padding: 10px 14px; border-radius: 6px; }
+    .logo-mark img { display: block; max-height: 32px; max-width: 100px; object-fit: contain; }
     .kicker { margin: 0; font-weight: 700; }
     .muted { margin: 0; color: #666; }
     h1 { font-size: 20px; margin: 24px 0 4px; }
@@ -32,7 +33,7 @@
 <body>
   <main>
     <div class="brand-row">
-      <div class="logo-mark">EDR</div>
+      <div class="logo-mark">{{#if logoImageUrl}}<img src="{{logoImageUrl}}" alt="Company logo" />{{else}}EDR{{/if}}</div>
       <div>
         <p class="kicker">Ethio-Djibouti Standard Gauge Railway Share Company</p>
         <p class="muted">Last-Mile Delivery Contract</p>
diff --git a/apps/edr-freight-api/src/migrations/3500000000000-LogoSettings.ts b/apps/edr-freight-api/src/migrations/3500000000000-LogoSettings.ts
new file mode 100644
index 000000000..36d70906f
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3500000000000-LogoSettings.ts
@@ -0,0 +1,27 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Single-row table holding the one company logo image stamped onto every
+ * generated document (see LogoSettingsService). Same single-row shape as
+ * stamp_settings; the app never inserts more than one row.
+ */
+export class LogoSettings3500000000000 implements MigrationInterface {
+  name = "LogoSettings3500000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.logo_settings (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        logo_file_id uuid REFERENCES freight.files(id),
+        updated_by_id uuid,
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz
+      );
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.logo_settings;`);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
index 00e590e17..bc5250888 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
@@ -14,7 +14,7 @@ const model = (over: Partial<InvoiceDocumentModel> = {}): InvoiceDocumentModel =
 });
 
 describe("InvoiceDocumentService.buildHtml — EIMS QR", () => {
-  const service = new InvoiceDocumentService({} as never, {} as never);
+  const service = new InvoiceDocumentService({} as never, {} as never, {} as never);
 
   it("renders no QR block when qrImageUrl is unset", () => {
     const html = service.buildHtml(model());
diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
index d83b7e2f0..f6b264636 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
@@ -1,8 +1,10 @@
 import { Injectable } from "@nestjs/common";
 
 import { StampSettingsService } from "../../stamp-settings/stamp-settings.service";
+import { LogoSettingsService } from "../../logo-settings/logo-settings.service";
 import { PdfRenderService } from "./pdf-render.service";
 import { sealClass, sealImageCss, sealMarkup } from "./seal-markup.util";
+import { logoImageCss, logoMarkup } from "./logo-markup.util";
 import {
   PdfColor,
   assembleSinglePagePdf,
@@ -62,6 +64,7 @@ export interface InvoiceDocumentModel {
    * explicitly only to override that default for one document.
    */
   stampImageUrl?: string | null;
+  logoImageUrl?: string | null;
   /**
    * MoR EIMS verification QR (data URL, pre-rendered by the caller from `Invoice.eimsSignedQr` —
    * see that column's comment). Set only once an invoice is actually registered; the IRN text
@@ -81,6 +84,7 @@ export class InvoiceDocumentService {
   constructor(
     private readonly pdf: PdfRenderService,
     private readonly stampSettings: StampSettingsService,
+    private readonly logoSettings: LogoSettingsService,
   ) {}
 
   async render(
@@ -90,7 +94,11 @@ export class InvoiceDocumentService {
       model.stampImageUrl !== undefined
         ? model.stampImageUrl
         : await this.stampSettings.getStampImageUrl();
-    const resolvedModel: InvoiceDocumentModel = { ...model, stampImageUrl };
+    const logoImageUrl =
+      model.logoImageUrl !== undefined
+        ? model.logoImageUrl
+        : await this.logoSettings.getLogoImageUrl();
+    const resolvedModel: InvoiceDocumentModel = { ...model, stampImageUrl, logoImageUrl };
 
     const html = this.buildHtml(resolvedModel);
     const kindLabel = model.kind === "RECEIPT" ? "receipt" : "invoice";
@@ -250,6 +258,7 @@ export class InvoiceDocumentService {
       model.sealText ?? (model.kind === "RECEIPT" || model.status === "PAID" ? "EDR PAID" : "EDR");
     const sealInner = sealMarkup(model.stampImageUrl, sealText);
     const sealCssClass = sealClass(model.stampImageUrl);
+    const logoInner = logoMarkup(model.logoImageUrl);
 
     const qrMarkup = model.qrImageUrl
       ? `<div class="qr"><img src="${esc(model.qrImageUrl)}" alt="EIMS verification QR" /><span>Scan to verify (MoR EIMS)</span></div>`
@@ -293,6 +302,7 @@ export class InvoiceDocumentService {
     .meta strong { display: block; color: #0f172a; font-size: 17px; margin-top: 5px; }
     .seal { position: absolute; right: 28px; top: 118px; width: 116px; height: 116px; border: 4px double #0f766e; border-radius: 999px; color: #0f766e; display: flex; align-items: center; justify-content: center; text-align: center; font-weight: 800; font-size: 18px; transform: rotate(-14deg); opacity: .82; }
     ${sealImageCss()}
+    ${logoImageCss()}
     .qr { position: absolute; right: 160px; top: 118px; width: 90px; text-align: center; }
     .qr img { width: 90px; height: 90px; }
     .qr span { display: block; font-size: 7px; color: #64748b; margin-top: 3px; }
@@ -322,6 +332,7 @@ export class InvoiceDocumentService {
   <div class="doc">
     <div class="top">
       <div>
+        ${logoInner}
         <div class="brand">Ethio-Djibouti Railway S.C.</div>
         <h1>${esc(model.title)} ${model.kind === "RECEIPT" ? "Receipt" : "Invoice"}</h1>
       </div>
diff --git a/apps/edr-freight-api/src/modules/billing/documents/logo-markup.util.ts b/apps/edr-freight-api/src/modules/billing/documents/logo-markup.util.ts
new file mode 100644
index 000000000..f78109855
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/documents/logo-markup.util.ts
@@ -0,0 +1,35 @@
+/**
+ * The single decision every EDR document makes about its header logo: draw
+ * the one uploaded company logo when configured (LogoSettingsService), or
+ * render nothing — the existing "Ethio-Djibouti Railway S.C." text brand next
+ * to it already covers the no-logo case, so there is no text fallback here
+ * (contrast seal-markup.util.ts, whose seal has no text of its own).
+ */
+
+function escapeHtml(value: unknown): string {
+  return String(value ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * `<img>` markup for the header logo, or "" when unset. `logoImageUrl` is
+ * expected to be a data URL from LogoSettingsService.getLogoImageUrl().
+ * `className` defaults to "doc-logo" — each document supplies that class's
+ * sizing in its own <style> block (see logoImageCss()).
+ */
+export function logoMarkup(
+  logoImageUrl: string | null | undefined,
+  className = "doc-logo",
+): string {
+  if (!logoImageUrl) return "";
+  return `<img class="${className}" src="${escapeHtml(logoImageUrl)}" alt="Company logo" />`;
+}
+
+/** Default CSS for the header logo — append inside a document's <style> block. */
+export function logoImageCss(className = "doc-logo"): string {
+  return `.${className} { display: block; max-height: 48px; max-width: 180px; margin-bottom: 6px; object-fit: contain; }`;
+}
diff --git a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-contract.service.ts b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-contract.service.ts
index c30112617..b1c89199c 100644
--- a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-contract.service.ts
+++ b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-contract.service.ts
@@ -13,6 +13,7 @@ import { FilesService } from '../files/files.service';
 import { FileRecord } from '../files/entities/file.entity';
 import { MinioService } from '../minio/minio.service';
 import { SignaturesService } from '../signatures/signatures.service';
+import { LogoSettingsService } from '../logo-settings/logo-settings.service';
 import { SignLastMileContractDto } from './dto/sign-last-mile-contract.dto';
 import { LastMileRequest } from './entities/last-mile-request.entity';
 import { LastMileRequestsRepository } from './last-mile-requests.repository';
@@ -41,6 +42,7 @@ export class LastMileContractService {
     private readonly pdfService: ContractPdfService,
     private readonly signaturesService: SignaturesService,
     private readonly dataSource: DataSource,
+    private readonly logoSettings: LogoSettingsService,
   ) {}
 
   async getContractView(id: string, viewerUserId?: string | null) {
@@ -194,6 +196,7 @@ export class LastMileContractService {
     return {
       companyName: booking.company?.name ?? 'Customer',
       bookingReference: booking.reference ?? request.bookingId,
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
       containerCount: containers.length || null,
       containerList: containers.join(', '),
       cargoDescription,
diff --git a/apps/edr-freight-api/src/modules/logo-settings/dto/update-logo-setting.dto.ts b/apps/edr-freight-api/src/modules/logo-settings/dto/update-logo-setting.dto.ts
new file mode 100644
index 000000000..b5fecaf20
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/logo-settings/dto/update-logo-setting.dto.ts
@@ -0,0 +1,9 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsString, MinLength } from "class-validator";
+
+export class UpdateLogoSettingDto {
+  @ApiProperty({ description: "Logo image as a base64 data URL (PNG/JPG)." })
+  @IsString()
+  @MinLength(1)
+  logoImageBase64!: string;
+}
diff --git a/apps/edr-freight-api/src/modules/logo-settings/entities/logo-setting.entity.ts b/apps/edr-freight-api/src/modules/logo-settings/entities/logo-setting.entity.ts
new file mode 100644
index 000000000..dbe8e17df
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/logo-settings/entities/logo-setting.entity.ts
@@ -0,0 +1,25 @@
+import { BaseEntity } from "@edr/api-common";
+import { Column, Entity, JoinColumn, ManyToOne } from "typeorm";
+
+import { FileRecord } from "../../files/entities/file.entity";
+
+/**
+ * Single-row table holding the one company logo image stamped onto every
+ * generated document (invoices/receipts, contracts, warehouse papers,
+ * train-scheduling manifests, payment receipts). Same single-row shape as
+ * stamp_settings — `get()` lazily creates the row, and there is never more
+ * than one.
+ */
+@Entity({ schema: "freight", name: "logo_settings" })
+export class LogoSetting extends BaseEntity {
+  @Column({ name: "logo_file_id", type: "uuid", nullable: true })
+  logoFileId?: string | null;
+
+  @ManyToOne(() => FileRecord, { nullable: true })
+  @JoinColumn({ name: "logo_file_id" })
+  logoFile?: FileRecord | null;
+
+  /** IAM user id of the last operator to set/clear the logo. */
+  @Column({ name: "updated_by_id", type: "uuid", nullable: true })
+  updatedById?: string | null;
+}
diff --git a/apps/edr-freight-api/src/modules/logo-settings/logo-settings.controller.ts b/apps/edr-freight-api/src/modules/logo-settings/logo-settings.controller.ts
new file mode 100644
index 000000000..0e3007c0f
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/logo-settings/logo-settings.controller.ts
@@ -0,0 +1,39 @@
+import { Body, Controller, Delete, Get, Put } from "@nestjs/common";
+import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
+import { CurrentUser } from "@edr/api-common";
+import type { TCurrentUser } from "@tria-plc/api-common/modules/auth/types/current-user.type";
+
+import { BookingStaff } from "../../common/booking-guards";
+import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
+import { UpdateLogoSettingDto } from "./dto/update-logo-setting.dto";
+import { LogoSettingsService } from "./logo-settings.service";
+
+@ApiTags("logo-settings")
+@ApiBearerAuth()
+@Controller("logo-settings")
+export class LogoSettingsController {
+  constructor(private readonly service: LogoSettingsService) {}
+
+  @Get()
+  @BookingStaff([FREIGHT_PERMS.settings.logo.view, FREIGHT_PERMS.admin])
+  @ApiOperation({ summary: "Current company logo used on every generated document" })
+  get() {
+    return this.service.getView();
+  }
+
+  @Put()
+  @BookingStaff([FREIGHT_PERMS.settings.logo.manage, FREIGHT_PERMS.admin])
+  @ApiOperation({ summary: "Replace the company logo" })
+  update(@Body() dto: UpdateLogoSettingDto, @CurrentUser() user: TCurrentUser) {
+    return this.service.setLogo(dto.logoImageBase64, user?.id ?? null);
+  }
+
+  @Delete()
+  @BookingStaff([FREIGHT_PERMS.settings.logo.manage, FREIGHT_PERMS.admin])
+  @ApiOperation({
+    summary: "Clear the company logo (documents fall back to their text mark)",
+  })
+  clear(@CurrentUser() user: TCurrentUser) {
+    return this.service.clearLogo(user?.id ?? null);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/logo-settings/logo-settings.module.ts b/apps/edr-freight-api/src/modules/logo-settings/logo-settings.module.ts
new file mode 100644
index 000000000..86b257297
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/logo-settings/logo-settings.module.ts
@@ -0,0 +1,24 @@
+import { Global, Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+
+import { FilesModule } from "../files/files.module";
+import { MinioModule } from "../minio/minio.module";
+import { LogoSetting } from "./entities/logo-setting.entity";
+import { LogoSettingsController } from "./logo-settings.controller";
+import { LogoSettingsRepository } from "./logo-settings.repository";
+import { LogoSettingsService } from "./logo-settings.service";
+
+/**
+ * Global so every document-generating module (billing, contracts,
+ * warehouses, train-scheduling, payment) can inject {@link LogoSettingsService}
+ * without pulling in a circular dependency — same reasoning as
+ * StampSettingsModule.
+ */
+@Global()
+@Module({
+  imports: [TypeOrmModule.forFeature([LogoSetting]), FilesModule, MinioModule],
+  controllers: [LogoSettingsController],
+  providers: [LogoSettingsRepository, LogoSettingsService],
+  exports: [LogoSettingsService],
+})
+export class LogoSettingsModule {}
diff --git a/apps/edr-freight-api/src/modules/logo-settings/logo-settings.repository.ts b/apps/edr-freight-api/src/modules/logo-settings/logo-settings.repository.ts
new file mode 100644
index 000000000..24d440d56
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/logo-settings/logo-settings.repository.ts
@@ -0,0 +1,21 @@
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+import { BaseRepository } from "@edr/api-common";
+
+import { LogoSetting } from "./entities/logo-setting.entity";
+
+@Injectable()
+export class LogoSettingsRepository extends BaseRepository<LogoSetting> {
+  constructor(
+    @InjectRepository(LogoSetting)
+    repo: Repository<LogoSetting>,
+  ) {
+    super(repo);
+  }
+
+  /** The single settings row, with its logo file joined, or null before first upload. */
+  findSingleton(): Promise<LogoSetting | null> {
+    return this.repository.findOne({ where: {}, relations: ["logoFile"] });
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/logo-settings/logo-settings.service.ts b/apps/edr-freight-api/src/modules/logo-settings/logo-settings.service.ts
new file mode 100644
index 000000000..916e45e61
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/logo-settings/logo-settings.service.ts
@@ -0,0 +1,161 @@
+import { Injectable, Logger } from "@nestjs/common";
+import { Readable } from "stream";
+import { DataSource } from "typeorm";
+
+import { FilesService } from "../files/files.service";
+import { FileRecord } from "../files/entities/file.entity";
+import { MinioService } from "../minio/minio.service";
+import { LogoSettingsRepository } from "./logo-settings.repository";
+import { LogoSetting } from "./entities/logo-setting.entity";
+
+export interface LogoSettingView {
+  logoImageUrl: string | null;
+  updatedById: string | null;
+  updatedAt: Date | null;
+}
+
+/**
+ * Owns the single `logo_settings` row: the one company logo image used on
+ * every generated document. Same single-row shape as StampSettingsService,
+ * the value is an uploaded image (via FilesService) rather than a scalar.
+ */
+@Injectable()
+export class LogoSettingsService {
+  private readonly logger = new Logger(LogoSettingsService.name);
+
+  constructor(
+    private readonly repository: LogoSettingsRepository,
+    private readonly filesService: FilesService,
+    private readonly minioService: MinioService,
+    private readonly dataSource: DataSource,
+  ) {}
+
+  /** The settings row, created empty on first access. */
+  async get(): Promise<LogoSetting> {
+    const existing = await this.repository.findSingleton();
+    if (existing) return existing;
+    return this.repository.create({ logoFileId: null, updatedById: null });
+  }
+
+  /** Current logo, with the image inlined as a data URL (or null if unset). */
+  async getView(): Promise<LogoSettingView> {
+    const setting = await this.get();
+    return {
+      logoImageUrl: await this.inlineImageUrl(setting.logoFile?.url),
+      updatedById: setting.updatedById ?? null,
+      updatedAt: setting.updatedAt ?? null,
+    };
+  }
+
+  /**
+   * The logo image for embedding into generated documents, ALWAYS as a
+   * `data:` URL or null. Never throws — document generation must succeed even
+   * if the logo lookup fails; callers render their existing text/mark
+   * fallback on null (see logo-markup.util.ts).
+   */
+  async getLogoImageUrl(): Promise<string | null> {
+    try {
+      const setting = await this.get();
+      const inlined = await this.inlineImageUrl(setting.logoFile?.url);
+      if (inlined && !inlined.startsWith("data:")) {
+        this.logger.warn(
+          `Company logo could not be inlined for document rendering (falling back to the text mark): ${inlined}`,
+        );
+        return null;
+      }
+      return inlined;
+    } catch (err) {
+      this.logger.warn(
+        `Could not load company logo for PDF rendering: ${(err as Error).message}`,
+      );
+      return null;
+    }
+  }
+
+  /** Replace the logo image, storing it in MinIO via FilesService. */
+  async setLogo(
+    logoImageBase64: string,
+    updatedById?: string | null,
+  ): Promise<LogoSettingView> {
+    const current = await this.get();
+    const previousFileId = current.logoFileId ?? null;
+
+    const fileRecord = await this.filesService.upload({
+      resourceId: current.id,
+      resource: "logo_settings",
+      code: "logo",
+      file: this.toUploadFile(logoImageBase64),
+      uploadedByUserId: updatedById ?? null,
+    });
+
+    await this.repository.update(current.id, {
+      logoFileId: fileRecord.id,
+      updatedById: updatedById ?? null,
+    });
+
+    if (previousFileId && previousFileId !== fileRecord.id) {
+      await this.dataSource.getRepository(FileRecord).delete(previousFileId);
+    }
+
+    this.logger.log(`Company logo updated by ${updatedById ?? "unknown user"}`);
+    return this.getView();
+  }
+
+  /** Clear the logo (documents fall back to their text/mark). */
+  async clearLogo(updatedById?: string | null): Promise<LogoSettingView> {
+    const current = await this.get();
+    const previousFileId = current.logoFileId ?? null;
+
+    await this.repository.update(current.id, {
+      logoFileId: null,
+      updatedById: updatedById ?? null,
+    });
+
+    if (previousFileId) {
+      await this.dataSource.getRepository(FileRecord).delete(previousFileId);
+    }
+
+    return this.getView();
+  }
+
+  private toUploadFile(base64: string): Express.Multer.File {
+    const raw = base64.includes(",") ? base64.split(",")[1]! : base64;
+    const buffer = Buffer.from(raw, "base64");
+    return {
+      fieldname: "logo",
+      originalname: "company-logo.png",
+      encoding: "7bit",
+      mimetype: "image/png",
+      size: buffer.length,
+      buffer,
+      stream: Readable.from(buffer),
+      destination: "",
+      filename: "",
+      path: "",
+    };
+  }
+
+  private async inlineImageUrl(url?: string | null): Promise<string | null> {
+    if (!url) return null;
+    if (url.startsWith("data:")) return url;
+    try {
+      const objectName = this.minioService.getObjectNameFromUrl(url);
+      const stream = await this.minioService.getFileStream(objectName);
+      const buffer = await this.streamToBuffer(stream);
+      return `data:image/png;base64,${buffer.toString("base64")}`;
+    } catch {
+      return url;
+    }
+  }
+
+  private streamToBuffer(stream: Readable): Promise<Buffer> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      stream.on("data", (chunk: Buffer | string) => {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+      stream.on("error", reject);
+      stream.on("end", () => resolve(Buffer.concat(chunks)));
+    });
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/payment/payment.service.spec.ts b/apps/edr-freight-api/src/modules/payment/payment.service.spec.ts
index aca224c07..5be987935 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.service.spec.ts
@@ -49,6 +49,7 @@ describe("PaymentService.confirmOtp", () => {
       repo as never,
       client as never,
       billing as never,
+      {} as never,
     );
     return { service, repo, billing };
   };
@@ -197,6 +198,7 @@ describe("PaymentService.markIntentSucceeded", () => {
       repo as never,
       {} as never,
       billing as never,
+      {} as never,
     );
     return { service, repo, billing };
   };
diff --git a/apps/edr-freight-api/src/modules/payment/payment.service.ts b/apps/edr-freight-api/src/modules/payment/payment.service.ts
index 4d27c8c77..037e188f8 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.service.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.service.ts
@@ -13,6 +13,7 @@ import { PaymentEntity } from "./entities/payment.entity";
 import { PaymentRepository } from "./payment.repository";
 import { PaymentClientService } from "./payment-client.service";
 import { BillingService } from "../billing/billing.service";
+import { LogoSettingsService } from "../logo-settings/logo-settings.service";
 
 import * as fs from "fs";
 import * as path from "path";
@@ -104,6 +105,7 @@ export class PaymentService {
     private readonly paymentClient: PaymentClientService,
     @Inject(forwardRef(() => BillingService))
     private readonly billing: BillingService,
+    private readonly logoSettings: LogoSettingsService,
   ) { }
 
   async getAll(filters: {
@@ -657,6 +659,7 @@ export class PaymentService {
       total: payment.amount.toString(),
       currency: payment.currency,
       reason: payment.reason,
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
     });
   }
 
diff --git a/apps/edr-freight-api/src/modules/payment/templates/receipt.hbs b/apps/edr-freight-api/src/modules/payment/templates/receipt.hbs
index 0f156f6dc..067e2d0ba 100644
--- a/apps/edr-freight-api/src/modules/payment/templates/receipt.hbs
+++ b/apps/edr-freight-api/src/modules/payment/templates/receipt.hbs
@@ -45,6 +45,14 @@
             margin: 0;
         }
 
+        .header .doc-logo {
+            display: block;
+            margin: 0 auto 10px;
+            max-height: 48px;
+            max-width: 180px;
+            object-fit: contain;
+        }
+
         .details-table {
             width: 100%;
             border-collapse: collapse;
@@ -126,6 +134,7 @@
 <body>
     <div class="receipt-box">
         <div class="header">
+            {{#if logoImageUrl}}<img class="doc-logo" src="{{logoImageUrl}}" alt="Company logo" />{{/if}}
             <h1>{{vendorName}}</h1>
             <p>{{vendorAddress}}</p>
         </div>
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
index e6b3a5040..10ebaf6ee 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
@@ -181,6 +181,7 @@ describe('TrainSchedulingService', () => {
         autoArriveAtFinalYard: jest.fn().mockResolvedValue([]),
       } as never, // bookingJourneyService
       { dispatched: jest.fn(), arrived: jest.fn() } as never, // bookingNotifier
+      { getLogoImageUrl: jest.fn().mockResolvedValue(null) } as never, // logoSettings
     );
 
     const defaultFleetWagons = [
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index 6c89c6980..5ce93fe0b 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -177,6 +177,8 @@ import { RouteMilestone } from '../../routes/entities/route-milestone.entity';
 import { deriveTradeDirection } from '../../../common/derive-trade-direction.util';
 import { WarehouseInventoryService } from '../../warehouses/warehouse-inventory.service';
 import { WarehouseReleaseDocumentService } from '../../warehouses/warehouse-release-document.service';
+import { LogoSettingsService } from '../../logo-settings/logo-settings.service';
+import { logoImageCss, logoMarkup } from '../../billing/documents/logo-markup.util';
 import {
   autoFillPlacements,
   findMissingContainerNumberIssues,
@@ -376,6 +378,7 @@ export class TrainSchedulingService {
     private readonly bookingWindowGateway: BookingWindowGateway,
     private readonly bookingJourneyService: BookingJourneyService,
     private readonly bookingNotifier: BookingNotifierService,
+    private readonly logoSettings: LogoSettingsService,
     @Optional() private readonly milestoneService?: ClearanceMilestoneService,
     private readonly configService?: ConfigService,
     // forwardRef: BookingBatchService injects this service back; @Optional so
@@ -3025,7 +3028,7 @@ export class TrainSchedulingService {
     const loadList = await this.generateImportLoadList(scheduleId, {
       performedBy: 'DOCUMENT_GENERATION',
     });
-    const html = this.buildImportLoadListHtml(loadList);
+    const html = this.buildImportLoadListHtml(loadList, await this.logoSettings.getLogoImageUrl());
     // Styled table-aware fallback (marshalling grid) when Chromium is unavailable —
     // NOT the release-order fallback (would mislabel this as a gate-clearance order).
     const buffer = await this.pdfDocuments.renderTabularDocument(html, 'Import marshalling / load list');
@@ -3045,7 +3048,9 @@ export class TrainSchedulingService {
       throw new BadRequestException('Export marshalling document applies only to EXPORT schedules');
     }
 
-    const html = this.buildExportLoadListHtml(schedule);
+    const html = this.buildExportLoadListHtml(schedule, {
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
+    });
     // Styled table-aware fallback (marshalling grid) — see importLoadListDocument.
     const buffer = await this.pdfDocuments.renderTabularDocument(html, 'Export marshalling / load list');
     const reference = schedule.trainNumber ?? schedule.id;
@@ -3117,6 +3122,7 @@ export class TrainSchedulingService {
       positionLabel,
       wagons,
       unassignedBookings,
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
     });
     // Styled table-aware fallback (marshalling grid) — see importLoadListDocument.
     const buffer = await this.pdfDocuments.renderTabularDocument(html, 'Intercity marshalling / load list');
@@ -3160,6 +3166,7 @@ export class TrainSchedulingService {
       positionLabel?: string;
       wagons?: TrainSetWagon[];
       unassignedBookings?: Booking[];
+      logoImageUrl?: string | null;
     },
   ): string {
     const esc = (value: unknown) =>
@@ -3278,6 +3285,7 @@ export class TrainSchedulingService {
     .tile { border: 1px solid #cbd5e1; padding: 8px; min-height: 50px; }
     .tile span { display: block; color: #64748b; font-size: 9px; text-transform: uppercase; letter-spacing: .05em; margin-bottom: 4px; }
     .tile strong { font-size: 11px; }
+    ${logoImageCss()}
     table { width: 100%; border-collapse: collapse; }
     th { background: #f8fafc; color: #475569; text-align: left; }
     th, td { border: 1px solid #cbd5e1; padding: 5px 6px; font-size: 9.5px; vertical-align: top; }
@@ -3292,6 +3300,7 @@ export class TrainSchedulingService {
 <body>
   <div class="top">
     <div>
+      ${logoMarkup(opts?.logoImageUrl)}
       <div class="brand">Ethio-Djibouti Railway S.C.</div>
       <h1>${esc(opts?.title ?? 'Export Marshalling Document / Load List')}</h1>
     </div>
@@ -3471,7 +3480,10 @@ export class TrainSchedulingService {
     }
   }
 
-  private buildImportLoadListHtml(loadList: Awaited<ReturnType<TrainSchedulingService['generateImportLoadList']>>): string {
+  private buildImportLoadListHtml(
+    loadList: Awaited<ReturnType<TrainSchedulingService['generateImportLoadList']>>,
+    logoImageUrl?: string | null,
+  ): string {
     const esc = (value: unknown) =>
       String(value ?? '-')
         .replace(/&/g, '&amp;')
@@ -3562,6 +3574,7 @@ export class TrainSchedulingService {
     .tile { border: 1px solid #cbd5e1; padding: 10px; min-height: 58px; }
     .tile span { display: block; color: #64748b; font-size: 10px; text-transform: uppercase; letter-spacing: .05em; margin-bottom: 5px; }
     .tile strong { font-size: 13px; }
+    ${logoImageCss()}
     .status { display: grid; grid-template-columns: repeat(6, 1fr); gap: 8px; margin-top: 14px; }
     .step { border: 1px solid #cbd5e1; padding: 8px; font-size: 10px; text-align: center; min-height: 48px; }
     .done { background: #ecfdf5; border-color: #22c55e; color: #14532d; font-weight: 700; }
@@ -3583,6 +3596,7 @@ export class TrainSchedulingService {
   <div class="doc">
     <div class="top">
       <div>
+        ${logoMarkup(logoImageUrl)}
         <div class="brand">Ethio-Djibouti Railway S.C.</div>
         <h1>Import Load List /<br />Marshalling Document</h1>
         <div class="subtitle">Djibouti-side gatepass, loading, and departure manifest</div>
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 163b5bcc1..58b5e9493 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
@@ -38,6 +38,8 @@ import {
 } from '../notifications/resolve-company-phone.util';
 import { SignaturesService } from '../signatures/signatures.service';
 import { StampSettingsService } from '../stamp-settings/stamp-settings.service';
+import { LogoSettingsService } from '../logo-settings/logo-settings.service';
+import { logoImageCss, logoMarkup } from '../billing/documents/logo-markup.util';
 import { sealClass, sealImageCss, sealMarkup } from '../billing/documents/seal-markup.util';
 import { BulkInspectDto } from './dto/bulk-inspect.dto';
 import { BulkReceiveDto, TruckEntranceDto } from './dto/bulk-receive.dto';
@@ -420,6 +422,7 @@ export class WarehouseInventoryService {
     private readonly inbox: NotificationInboxService,
     private readonly events: EventEmitter2,
     private readonly stampSettings: StampSettingsService,
+    private readonly logoSettings: LogoSettingsService,
   ) {}
 
   /**
@@ -3751,6 +3754,7 @@ export class WarehouseInventoryService {
       reference,
       issuedAt,
       stampImageUrl: await this.stampSettings.getStampImageUrl(),
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
       bookingReference,
       bookingStatus: row?.bookingStatus ?? null,
       customerName: row?.customerName ?? null,
@@ -4222,6 +4226,7 @@ export class WarehouseInventoryService {
 
     const html = this.buildGrnDocumentHtml({
       grnNumber: row.grnNumber,
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
       receivedAt: row.receivedAt ? new Date(row.receivedAt) : new Date(),
       bookingReference: row.bookingReference ?? row.bookingId ?? 'N/A',
       bookingStatus: row.bookingStatus ?? null,
@@ -4806,6 +4811,7 @@ export class WarehouseInventoryService {
       reference,
       handedOverAt,
       stampImageUrl: await this.stampSettings.getStampImageUrl(),
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
       bookingReference,
       bookingStatus: row.bookingStatus ?? null,
       customerName: row.customerName ?? null,
@@ -5487,6 +5493,8 @@ export class WarehouseInventoryService {
     zone: string | null;
     inventoryStatus: string | null;
     receiveSummary: string | null;
+    /** The one global company logo; null renders the plain text brand. */
+    logoImageUrl?: string | null;
   }): string {
     const esc = (value: unknown) =>
       String(value ?? '-')
@@ -5543,6 +5551,7 @@ export class WarehouseInventoryService {
     .ref { text-align: right; font-size: 11px; color: #334155; padding-top: 8px; }
     .ref strong { display: block; color: #061323; font-size: 18px; margin: 5px 0 8px; letter-spacing: .02em; }
     .rule { height: 3px; background: #0f766e; margin: 16px 0 22px; }
+    ${logoImageCss()}
     .notice { width: 76%; margin: 0 0 18px; padding: 13px 18px; background: #f0fdfa; border: 1px solid #5eead4; border-left: 5px solid #0f766e; font-size: 13px; line-height: 1.45; }
     .section-title { margin: 18px 0 8px; font-size: 13px; font-weight: 800; color: #0f766e; text-transform: uppercase; letter-spacing: .12em; }
     table { width: 100%; border-collapse: collapse; }
@@ -5556,6 +5565,7 @@ export class WarehouseInventoryService {
 <body>
   <div class="top">
     <div>
+      ${logoMarkup(data.logoImageUrl)}
       <div class="brand">Ethio-Djibouti Railway S.C.</div>
       <h1>Goods Received Note</h1>
       <div class="subtitle">Warehouse receiving confirmation</div>
@@ -5613,6 +5623,8 @@ export class WarehouseInventoryService {
     truckWeightTons?: number | null;
     /** The one global company stamp; null falls back to the drawn text seal. */
     stampImageUrl?: string | null;
+    /** The one global company logo; null renders the plain text brand. */
+    logoImageUrl?: string | null;
   }): string {
     const esc = (value: unknown) =>
       String(value ?? '-')
@@ -5700,12 +5712,14 @@ export class WarehouseInventoryService {
     .seal::before { content: ""; position: absolute; width: 78px; height: 78px; border: 1px solid #17633a; border-radius: 999px; }
     .seal span { position: relative; }
     ${sealImageCss()}
+    ${logoImageCss()}
   </style>
 </head>
 <body>
   <div class="doc">
     <div class="top">
       <div>
+        ${logoMarkup(data.logoImageUrl)}
         <div class="brand">Ethio-Djibouti Railway S.C.</div>
         <h1>Warehouse Release / Exit Paper</h1>
         <div class="subtitle">Official gate clearance and warehouse exit authorization</div>
@@ -5775,6 +5789,8 @@ export class WarehouseInventoryService {
     } | null;
     /** The one global company stamp; null falls back to the drawn text seal. */
     stampImageUrl?: string | null;
+    /** The one global company logo; null renders the plain text brand. */
+    logoImageUrl?: string | null;
   }): string {
     const esc = (value: unknown) =>
       String(value ?? '-')
@@ -5853,11 +5869,13 @@ export class WarehouseInventoryService {
     .seal::before { content: ""; position: absolute; width: 78px; height: 78px; border: 1px solid #17633a; border-radius: 999px; }
     .seal span { position: relative; }
     ${sealImageCss()}
+    ${logoImageCss()}
   </style>
 </head>
 <body>
   <div class="top">
     <div>
+      ${logoMarkup(data.logoImageUrl)}
       <div class="brand">Ethio-Djibouti Railway S.C.</div>
       <h1>Import Goods Handover Document</h1>
       <div class="subtitle">EDR to customer warehouse handover</div>
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index cdbffd961..f0b71a056 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -1211,6 +1211,16 @@ export const CONFIG_SETTINGS_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:settings:stamp:manage",
     "Manage the company stamp",
   ),
+  perm(
+    "b4b00004-0001-4000-8000-000000000001",
+    "edr_freight_app:settings:logo:view",
+    "View the company logo",
+  ),
+  perm(
+    "b4b00004-0001-4000-8000-000000000002",
+    "edr_freight_app:settings:logo:manage",
+    "Manage the company logo",
+  ),
   // The per-officer approval teeter (ማህተም) — an individual's own stamp +
   // signature, not the company seal. It used to ride on settings:stamp:*, which
   // now gates the ONE company stamp; this key was split out when the two were
@@ -1935,6 +1945,12 @@ export const FREIGHT_PERMS = {
       view: "edr_freight_app:settings:stamp:view",
       manage: "edr_freight_app:settings:stamp:manage",
     },
+    // The ONE company logo, applied to every generated document (invoices,
+    // receipts, contracts, warehouse papers, train-scheduling manifests).
+    logo: {
+      view: "edr_freight_app:settings:logo:view",
+      manage: "edr_freight_app:settings:logo:manage",
+    },
     // The per-officer approval teeter (ማህተም) + signature — genuinely per-person,
     // and NOT the company seal above. Retired: `invoiceStamp`, which used to
     // gate the company stamp before the two were untangled.
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index 64f91da72..37795b2f2 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -52,6 +52,7 @@ import NoAccessPage from "./pages/NoAccessPage";
 import FileUploadSettingsPage from "./pages/documents/FileUploadSettingsPage";
 import DropdownSettingsPage from "./pages/dropdown_settings/DropdownSettingsPage";
 import CompanyStampSettingsPage from "./pages/settings/CompanyStampSettingsPage";
+import LogoSettingsPage from "./pages/settings/LogoSettingsPage";
 import ContractTemplatesPage from "./pages/contract_templates/ContractTemplatesPage";
 import PortalContentPage from "./pages/portal_content/PortalContentPage";
 import ContractTemplateEditorPage from "./pages/contract_templates/ContractTemplateEditorPage";
@@ -807,6 +808,15 @@ const App = () => {
           path="invoice-stamp-settings"
           element={<Navigate to="/dashboard/stamp-settings" replace />}
         />
+        {/* The ONE company logo, shown in the header of every generated document. */}
+        <Route
+          path="logo-settings"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.settings.logo.view}>
+              <LogoSettingsPage />
+            </RequirePermission>
+          }
+        />
         <Route
           path="contract-templates"
           element={
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/LogoUpload.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/LogoUpload.tsx
new file mode 100644
index 000000000..f8ffe0fd0
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/LogoUpload.tsx
@@ -0,0 +1,172 @@
+import { useRef, useState } from "react";
+import { Box, Button, Group, Image, Paper, Stack, Text } from "@mantine/core";
+import { ImageIcon, RefreshCw, X } from "lucide-react";
+
+const MAX_LOGO_MB = 10;
+
+export interface LogoUploadProps {
+  /** Logo image as a data URL, or null when none is attached yet. */
+  value: string | null;
+  onChange: (dataUrl: string | null) => void;
+  label?: string;
+  description?: string;
+}
+
+/**
+ * Company logo picker — reads the picked image straight into a data URL,
+ * same transport as {@link StampUpload}. Kept as its own component (not a
+ * generalized image-upload) matching how stamp/teeter are already separate
+ * files here despite the near-identical shape.
+ */
+export function LogoUpload({
+  value,
+  onChange,
+  label = "Company logo",
+  description = "Attach the official company logo.",
+}: LogoUploadProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [dragging, setDragging] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [fileName, setFileName] = useState<string | null>(null);
+
+  const readFile = (file: File | undefined | null) => {
+    if (!file) return;
+    if (!file.type.startsWith("image/")) {
+      setError("The logo must be an image file (PNG or JPG).");
+      return;
+    }
+    if (file.size > MAX_LOGO_MB * 1024 * 1024) {
+      setError(`The logo image must be under ${MAX_LOGO_MB} MB.`);
+      return;
+    }
+    const reader = new FileReader();
+    reader.onload = () => {
+      setError(null);
+      setFileName(file.name);
+      onChange(typeof reader.result === "string" ? reader.result : null);
+    };
+    reader.onerror = () => setError("Could not read that file. Try another.");
+    reader.readAsDataURL(file);
+  };
+
+  const openPicker = () => inputRef.current?.click();
+
+  const clear = () => {
+    setFileName(null);
+    setError(null);
+    onChange(null);
+    if (inputRef.current) inputRef.current.value = "";
+  };
+
+  return (
+    <Stack gap={6}>
+      <Text size="sm" fw={500}>
+        {label}
+      </Text>
+
+      <input
+        ref={inputRef}
+        type="file"
+        accept="image/png,image/jpeg,image/webp"
+        hidden
+        onChange={(e) => readFile(e.currentTarget.files?.[0])}
+      />
+
+      {value ? (
+        <Paper withBorder radius="md" p="sm">
+          <Group gap="md" wrap="nowrap" align="center">
+            <Box
+              style={{
+                background:
+                  "repeating-conic-gradient(var(--mantine-color-gray-1) 0% 25%, transparent 0% 50%) 50% / 14px 14px",
+                borderRadius: 8,
+                flexShrink: 0,
+                padding: 6,
+              }}
+            >
+              <Image
+                src={value}
+                alt="Company logo"
+                fit="contain"
+                h={92}
+                w={92}
+              />
+            </Box>
+            <Stack gap={4} style={{ flex: 1, minWidth: 0 }}>
+              <Text size="sm" fw={500} truncate>
+                {fileName ?? "Logo attached"}
+              </Text>
+              <Text size="xs" c="dimmed">
+                Shown in the header of every generated document.
+              </Text>
+              <Group gap="xs" mt={2}>
+                <Button
+                  size="compact-xs"
+                  variant="light"
+                  color="edr-green"
+                  leftSection={<RefreshCw size={13} />}
+                  onClick={openPicker}
+                >
+                  Replace
+                </Button>
+                <Button
+                  size="compact-xs"
+                  variant="subtle"
+                  color="red"
+                  leftSection={<X size={13} />}
+                  onClick={clear}
+                >
+                  Remove
+                </Button>
+              </Group>
+            </Stack>
+          </Group>
+        </Paper>
+      ) : (
+        <Paper
+          withBorder
+          radius="md"
+          p="lg"
+          onClick={openPicker}
+          onDragOver={(e) => {
+            e.preventDefault();
+            setDragging(true);
+          }}
+          onDragLeave={() => setDragging(false)}
+          onDrop={(e) => {
+            e.preventDefault();
+            setDragging(false);
+            readFile(e.dataTransfer.files?.[0]);
+          }}
+          style={{
+            borderColor: dragging
+              ? "var(--mantine-color-edr-green-6)"
+              : undefined,
+            borderStyle: "dashed",
+            backgroundColor: dragging
+              ? "var(--mantine-color-edr-green-0)"
+              : undefined,
+            cursor: "pointer",
+          }}
+        >
+          <Stack gap={6} align="center">
+            <ImageIcon size={26} color="var(--mantine-color-edr-green-6)" />
+            <Text size="sm" fw={500}>
+              Upload company logo
+            </Text>
+            <Text size="xs" c="dimmed" ta="center">
+              {description} Drop an image here or click to browse — PNG or JPG,
+              up to {MAX_LOGO_MB} MB.
+            </Text>
+          </Stack>
+        </Paper>
+      )}
+
+      {error && (
+        <Text size="xs" c="red.7">
+          {error}
+        </Text>
+      )}
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 95608b6db..08d81da5a 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -9,6 +9,7 @@ import {
   FileText,
   Hammer,
   History,
+  Image as ImageIcon,
   Landmark,
   LayoutDashboard,
   LayoutGrid,
@@ -495,6 +496,12 @@ export const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[]
         icon: <Stamp />,
         permission: FREIGHT_PERMS.settings.stamp.view,
       },
+      {
+        label: "Company logo",
+        href: "/dashboard/logo-settings",
+        icon: <ImageIcon />,
+        permission: FREIGHT_PERMS.settings.logo.view,
+      },
       {
         label: "Contract templates",
         href: "/dashboard/contract-templates",
diff --git a/apps/edr-freight-web/backoffice/src/hooks/useLogoSettings.ts b/apps/edr-freight-web/backoffice/src/hooks/useLogoSettings.ts
new file mode 100644
index 000000000..662906f42
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/hooks/useLogoSettings.ts
@@ -0,0 +1,45 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useTranslation } from "react-i18next";
+import { toast } from "sonner";
+
+import { logoSettingsService } from "@/services/logoSettings.service";
+import { useErrorHandler } from "@/shared/hooks/useErrorHandler";
+
+const QUERY_KEY = ["logoSettings"];
+
+export const useLogoSettingsQuery = () =>
+  useQuery({
+    queryKey: QUERY_KEY,
+    queryFn: () => logoSettingsService.get(),
+  });
+
+export const useSetLogo = () => {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+  const { handleError } = useErrorHandler(t);
+
+  return useMutation({
+    mutationFn: (logoImageBase64: string) =>
+      logoSettingsService.set(logoImageBase64),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: QUERY_KEY });
+      toast.success(t("logoSettings.updated", "Company logo updated"));
+    },
+    onError: handleError,
+  });
+};
+
+export const useClearLogo = () => {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+  const { handleError } = useErrorHandler(t);
+
+  return useMutation({
+    mutationFn: () => logoSettingsService.clear(),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: QUERY_KEY });
+      toast.success(t("logoSettings.cleared", "Company logo removed"));
+    },
+    onError: handleError,
+  });
+};
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index c69aa5d1b..06f1f45da 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -334,6 +334,12 @@ export const FREIGHT_PERMS = {
       view: "edr_freight_app:settings:stamp:view",
       manage: "edr_freight_app:settings:stamp:manage",
     },
+    // The ONE company logo, applied to every generated document (invoices,
+    // receipts, contracts, warehouse papers, train-scheduling manifests).
+    logo: {
+      view: "edr_freight_app:settings:logo:view",
+      manage: "edr_freight_app:settings:logo:manage",
+    },
     // The per-officer approval teeter (ማህተም) + signature — genuinely per-person,
     // and NOT the company seal above. Retired: `invoiceStamp`, which used to
     // gate the company stamp before the two were untangled.
diff --git a/apps/edr-freight-web/backoffice/src/pages/settings/LogoSettingsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/settings/LogoSettingsPage.tsx
new file mode 100644
index 000000000..d2f09cd48
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/settings/LogoSettingsPage.tsx
@@ -0,0 +1,88 @@
+import { useEffect, useState } from "react";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/shared/common/ui/card";
+import { Button } from "@/shared/common/ui/button";
+import { Save, Trash2 } from "lucide-react";
+
+import { LogoUpload } from "@/components/contracts/LogoUpload";
+import {
+  useClearLogo,
+  useSetLogo,
+  useLogoSettingsQuery,
+} from "@/hooks/useLogoSettings";
+
+/**
+ * The ONE company logo, read by every document path server-side via
+ * LogoSettingsService: invoices and receipts, contract cover pages, warehouse
+ * GRN/release/handover papers, train-scheduling manifests, and the payment
+ * receipt. Single global image — no per-document choice.
+ */
+export default function LogoSettingsPage() {
+  const { data, isLoading } = useLogoSettingsQuery();
+  const setLogo = useSetLogo();
+  const clearLogo = useClearLogo();
+  const [draft, setDraft] = useState<string | null>(null);
+
+  useEffect(() => {
+    setDraft(null);
+  }, [data?.logoImageUrl]);
+
+  const value = draft !== null ? draft : (data?.logoImageUrl ?? null);
+  const dirty = draft !== null && draft !== data?.logoImageUrl;
+
+  const handleSave = async () => {
+    if (!draft) return;
+    await setLogo.mutateAsync(draft);
+  };
+
+  const handleClear = async () => {
+    if (!data?.logoImageUrl) return;
+    await clearLogo.mutateAsync();
+  };
+
+  return (
+    <div className="p-4 w-full max-w-screen-sm mx-auto">
+      <Card className="shadow-lg border-gray-200 dark:border-gray-700">
+        <CardHeader>
+          <CardTitle>Company logo</CardTitle>
+          <CardDescription>
+            The single EDR logo, applied to every generated document —
+            invoices and receipts, contracts, warehouse papers, train-scheduling
+            manifests, and payment receipts. Replacing it here changes it
+            everywhere at once.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <LogoUpload
+            value={isLoading ? null : value}
+            onChange={setDraft}
+            label="Company logo"
+            description="Shown in the header of every generated document."
+          />
+
+          <div className="flex items-center gap-2">
+            <Button onClick={handleSave} disabled={!dirty || setLogo.isPending}>
+              <Save className="mr-2 h-4 w-4" />
+              Save
+            </Button>
+            {data?.logoImageUrl && !dirty && (
+              <Button
+                variant="outline"
+                onClick={handleClear}
+                disabled={clearLogo.isPending}
+              >
+                <Trash2 className="mr-2 h-4 w-4" />
+                Remove
+              </Button>
+            )}
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/services/logoSettings.service.ts b/apps/edr-freight-web/backoffice/src/services/logoSettings.service.ts
new file mode 100644
index 000000000..fd89f2ed3
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/services/logoSettings.service.ts
@@ -0,0 +1,31 @@
+import { api as client } from "../auth/http";
+import { unwrap } from "@/utils/endpoint";
+import type { ApiResponse } from "@/types/apiResponse";
+
+const BASE = "/logo-settings";
+
+/** Company logo used on every generated document. */
+export interface LogoSettings {
+  logoImageUrl: string | null;
+  updatedById: string | null;
+  updatedAt: string | null;
+}
+
+export const logoSettingsService = {
+  get: async (): Promise<LogoSettings> => {
+    const response = await client.get<ApiResponse<LogoSettings>>(BASE);
+    return unwrap(response.data);
+  },
+
+  set: async (logoImageBase64: string): Promise<LogoSettings> => {
+    const response = await client.put<ApiResponse<LogoSettings>>(BASE, {
+      logoImageBase64,
+    });
+    return unwrap(response.data);
+  },
+
+  clear: async (): Promise<LogoSettings> => {
+    const response = await client.delete<ApiResponse<LogoSettings>>(BASE);
+    return unwrap(response.data);
+  },
+};

From 86d69a95779c049b13e3382974b3f6ac37e29003 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 11:22:45 +0000
Subject: [PATCH 080/174] chore: group invoices, payments and usd payments

---
 apps/edr-freight-web/backoffice/src/App.tsx   |  32 +--
 .../src/components/layout/route-meta.ts       |   8 +-
 .../components/layout/sidebar-sections.tsx    |  20 +-
 .../src/pages/invoices/FinanceHubPage.tsx     | 100 +++++++++
 .../src/pages/invoices/InvoicesPage.tsx       | 205 +++++++++---------
 .../src/pages/invoices/UsdPaymentsPage.tsx    |  35 ++-
 .../src/pages/payments/PaymentsPage.tsx       |  14 +-
 7 files changed, 244 insertions(+), 170 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx

diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index a176855f4..cf6e275ca 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -37,15 +37,13 @@ import DocumentClearanceListPage from "./pages/bookings/DocumentClearanceListPag
 import CustomerDetailPage from "./pages/customers/CustomerDetailPage";
 import CustomersPage from "./pages/customers/CustomersPage";
 import InvoiceDetailPage from "./pages/invoices/InvoiceDetailPage";
-import InvoicesPage from "./pages/invoices/InvoicesPage";
-import UsdPaymentsPage from "./pages/invoices/UsdPaymentsPage";
+import FinanceHubPage from "./pages/invoices/FinanceHubPage";
 import MyProfilePage from "./pages/dashboard/MyProfilePage";
 import OverviewPage from "./pages/dashboard/OverviewPage";
 import ReportsIndexRedirect from "./pages/reports/ReportsIndexRedirect";
 import ReportPage from "./pages/reports/ReportPage";
 import AuditLogsPage from "./pages/AuditLogsPage";
 import AiBookingMockTestPage from "./pages/ai/AiBookingMockTestPage";
-import PaymentsPage from "./pages/payments/PaymentsPage";
 //import EmployeesPage from "./pages/dashboard/user-management/EmployeesPage";
 import { RequirePermission } from "./components/auth/RequirePermission";
 import { FREIGHT_PERMS } from "./lib/permissions";
@@ -266,13 +264,11 @@ const App = () => {
             </RequirePermission>
           }
         />
+        {/* Payments used to be its own page; it's now the "payments" tab on
+            the merged Invoices hub. Old bookmarks/links still land there. */}
         <Route
           path="payments"
-          element={
-            <RequirePermission permission={FREIGHT_PERMS.payments.view}>
-              <PaymentsPage />
-            </RequirePermission>
-          }
+          element={<Navigate to="/dashboard/invoices?tab=payments" replace />}
         />
         <Route
           path="support"
@@ -298,21 +294,27 @@ const App = () => {
             </RequirePermission>
           }
         />
+        {/* Merged Invoices / Payments / USD Payments hub — tabs switch via
+            ?tab=invoices|payments|usd-payments (default invoices). Access is
+            OR'd across both keys so a user with just one still gets in; each
+            tab hides itself if the user lacks the permission it used to be
+            routed on. */}
         <Route
           path="invoices"
           element={
-            <RequirePermission permission={FREIGHT_PERMS.invoices.view}>
-              <InvoicesPage />
+            <RequirePermission
+              permission={[
+                FREIGHT_PERMS.invoices.view,
+                FREIGHT_PERMS.payments.view,
+              ]}
+            >
+              <FinanceHubPage />
             </RequirePermission>
           }
         />
         <Route
           path="usd-payments"
-          element={
-            <RequirePermission permission={FREIGHT_PERMS.invoices.view}>
-              <UsdPaymentsPage />
-            </RequirePermission>
-          }
+          element={<Navigate to="/dashboard/invoices?tab=usd-payments" replace />}
         />
         <Route
           path="invoices/:id"
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts b/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts
index 9b75f35f5..20794f72b 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts
+++ b/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts
@@ -44,10 +44,12 @@ const ROUTE_META: Array<{ prefix: string; meta: PageMeta }> = [
     },
   },
   {
-    prefix: "/dashboard/payments",
+    // Invoices, Payments, and USD Payments are tabs on one page now
+    // (FinanceHubPage); the header title itself is set per-tab there.
+    prefix: "/dashboard/invoices",
     meta: {
-      title: "Payments",
-      subtitle: "View booking payment transactions",
+      title: "Invoices",
+      subtitle: "Invoices, payments, and USD bank transfers",
     },
   },
   {
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 7114fa129..e3db92296 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -9,7 +9,6 @@ import {
   FileText,
   Hammer,
   History,
-  Landmark,
   LayoutDashboard,
   LayoutGrid,
   MapPin,
@@ -97,22 +96,13 @@ export const buildSidebarSections = (
           permission: FREIGHT_PERMS.contracts.opsClearanceReview,
         },
         {
-          label: "Payments",
-          href: "/dashboard/payments",
-          icon: <Wallet />,
-          permission: FREIGHT_PERMS.payments.view,
-        },
-        {
-          label: "Invoices",
+          // Invoices, Payments, and USD Payments live on one page as tabs
+          // (FinanceHubPage) — single nav entry, OR'd across both keys so
+          // either permission alone still gets a user in.
+          label: "Transactions",
           href: "/dashboard/invoices",
           icon: <Receipt />,
-          permission: FREIGHT_PERMS.invoices.view,
-        },
-        {
-          label: "USD Payments",
-          href: "/dashboard/usd-payments",
-          icon: <Landmark />,
-          permission: FREIGHT_PERMS.invoices.view,
+          permission: [FREIGHT_PERMS.invoices.view, FREIGHT_PERMS.payments.view],
         },
         {
           label: "Support",
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx
new file mode 100644
index 000000000..bd5169262
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx
@@ -0,0 +1,100 @@
+import { Tabs } from "@mantine/core";
+import { Landmark, Receipt, Wallet } from "lucide-react";
+import { useSearchParams } from "react-router-dom";
+
+import { useAuth } from "@/auth/useAuth";
+import { PageContainer, PageHeader } from "@/components/page";
+import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
+
+import InvoicesPanel from "./InvoicesPage";
+import UsdPaymentsPanel from "./UsdPaymentsPage";
+import PaymentsPanel from "../payments/PaymentsPage";
+
+/**
+ * Invoices, Payments, and USD Payments used to be three separate routes/pages
+ * with near-identical chrome. They're merged here as URL-linkable tabs
+ * (`?tab=`) on one page — each tab keeps the permission it was individually
+ * gated on before, and just doesn't render if the user lacks it.
+ */
+const TABS = [
+  {
+    key: "invoices",
+    label: "Invoices",
+    icon: Receipt,
+    permission: FREIGHT_PERMS.invoices.view,
+    subtitle:
+      "Every invoice issued across bookings, warehouse fees and clearance charges.",
+    Panel: InvoicesPanel,
+  },
+  {
+    key: "payments",
+    label: "Payments",
+    icon: Wallet,
+    permission: FREIGHT_PERMS.payments.view,
+    subtitle: "View and reconcile booking payment transactions.",
+    Panel: PaymentsPanel,
+  },
+  {
+    key: "usd-payments",
+    label: "USD Payments",
+    icon: Landmark,
+    // Same gate as Invoices, not a dedicated key — mirrors the old route.
+    permission: FREIGHT_PERMS.invoices.view,
+    subtitle:
+      "USD invoices are paid by bank transfer. Upload the customer's slip and confirm the payment before the pay window closes.",
+    Panel: UsdPaymentsPanel,
+  },
+] as const;
+
+type TabKey = (typeof TABS)[number]["key"];
+
+export default function FinanceHubPage() {
+  const { user } = useAuth();
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const visibleTabs = TABS.filter((tab) => hasPermission(user, tab.permission));
+  const requested = searchParams.get("tab");
+  const active: TabKey =
+    visibleTabs.find((tab) => tab.key === requested)?.key ??
+    visibleTabs[0]?.key ??
+    "invoices";
+  const activeTab = visibleTabs.find((tab) => tab.key === active);
+
+  const handleChange = (value: string | null) => {
+    if (!value) return;
+    setSearchParams(
+      (prev) => {
+        const next = new URLSearchParams(prev);
+        next.set("tab", value);
+        return next;
+      },
+      { replace: true },
+    );
+  };
+
+  return (
+    <PageContainer>
+      <PageHeader title={activeTab?.label ?? "Invoices"} subtitle={activeTab?.subtitle} />
+
+      <Tabs value={active} onChange={handleChange} keepMounted={false}>
+        <Tabs.List>
+          {visibleTabs.map((tab) => (
+            <Tabs.Tab
+              key={tab.key}
+              value={tab.key}
+              leftSection={<tab.icon size={16} />}
+            >
+              {tab.label}
+            </Tabs.Tab>
+          ))}
+        </Tabs.List>
+
+        {visibleTabs.map((tab) => (
+          <Tabs.Panel key={tab.key} value={tab.key} pt="lg">
+            <tab.Panel />
+          </Tabs.Panel>
+        ))}
+      </Tabs>
+    </PageContainer>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
index fd839de16..afa4fa603 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
@@ -21,7 +21,6 @@ import {
   formatMoney,
   humanize,
 } from "@/components/customers";
-import { PageContainer, PageHeader } from "@/components/page";
 import { api } from "@/services/api";
 import type { Invoice } from "@/types/invoice";
 import {
@@ -31,7 +30,8 @@ import {
   type ColumnDef,
 } from "@edr/ui-common";
 
-export default function InvoicesPage() {
+/** Invoices tab body of `FinanceHubPage` — page chrome lives in the parent. */
+export default function InvoicesPanel() {
   const navigate = useNavigate();
   const { pagination, setPagination } = usePagination({ pageSize: 10 });
   const [query, setQuery] = useState("");
@@ -127,112 +127,103 @@ export default function InvoicesPage() {
   );
 
   return (
-    <PageContainer>
-      <PageHeader
-        title="Invoices"
-        subtitle="Every invoice issued across bookings, warehouse fees and clearance charges."
-        action={
-          <ActionIcon
-            variant="default"
-            size="lg"
-            radius="md"
-            aria-label="Refresh"
-            loading={isFetching}
-            onClick={() => void refetch()}
-          >
-            <RefreshCw size={16} />
-          </ActionIcon>
-        }
-      />
+    <Card p={0}>
+      <Stack gap={0}>
+        <Box px="md" pt="md" pb="sm" w="100%">
+          <Group justify="space-between" gap="md" wrap="wrap">
+            <TextInput
+              placeholder="Search by invoice number…"
+              leftSection={<Search size={18} />}
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              rightSection={
+                query ? (
+                  <ActionIcon
+                    size="sm"
+                    color="gray"
+                    radius="md"
+                    variant="transparent"
+                    onClick={() => setQuery("")}
+                  >
+                    <X size={16} />
+                  </ActionIcon>
+                ) : null
+              }
+              style={{ flex: 1, minWidth: "240px" }}
+              radius="lg"
+            />
+            <SegmentedControl
+              size="sm"
+              radius="md"
+              value={statusFilter || "all"}
+              onChange={(v) => {
+                setStatusFilter(
+                  v === "all" ? "" : (v as Freight.InvoiceStatus),
+                );
+                setPagination((prev) => ({ ...prev, pageIndex: 0 }));
+              }}
+              data={[
+                { label: "All", value: "all" },
+                { label: "Pending", value: "PENDING" },
+                { label: "Payment processing", value: "PAYMENT_PROCESSING" },
+                { label: "Paid", value: "PAID" },
+                { label: "Overdue", value: "OVERDUE" },
+              ]}
+            />
+            <Text size="sm" c="dimmed">
+              {total} record{total !== 1 ? "s" : ""}
+            </Text>
+            <ActionIcon
+              variant="default"
+              size="lg"
+              radius="md"
+              aria-label="Refresh"
+              loading={isFetching}
+              onClick={() => void refetch()}
+            >
+              <RefreshCw size={16} />
+            </ActionIcon>
+          </Group>
+        </Box>
 
-      <Card p={0}>
-        <Stack gap={0}>
-          <Box px="md" pt="md" pb="sm" w="100%">
-            <Group justify="space-between" gap="md" wrap="wrap">
-              <TextInput
-                placeholder="Search by invoice number…"
-                leftSection={<Search size={18} />}
-                value={query}
-                onChange={(e) => setQuery(e.target.value)}
-                rightSection={
-                  query ? (
-                    <ActionIcon
-                      size="sm"
-                      color="gray"
-                      radius="md"
-                      variant="transparent"
-                      onClick={() => setQuery("")}
-                    >
-                      <X size={16} />
-                    </ActionIcon>
-                  ) : null
-                }
-                style={{ flex: 1, minWidth: "240px" }}
-                radius="lg"
-              />
-              <SegmentedControl
-                size="sm"
-                radius="md"
-                value={statusFilter || "all"}
-                onChange={(v) => {
-                  setStatusFilter(
-                    v === "all" ? "" : (v as Freight.InvoiceStatus),
-                  );
-                  setPagination((prev) => ({ ...prev, pageIndex: 0 }));
-                }}
-                data={[
-                  { label: "All", value: "all" },
-                  { label: "Pending", value: "PENDING" },
-                  { label: "Payment processing", value: "PAYMENT_PROCESSING" },
-                  { label: "Paid", value: "PAID" },
-                  { label: "Overdue", value: "OVERDUE" },
-                ]}
-              />
-              <Text size="sm" c="dimmed">
-                {total} record{total !== 1 ? "s" : ""}
-              </Text>
-            </Group>
+        <Box style={{ overflowX: "auto" }} w="100%">
+          <Box miw={920}>
+            <DataTable
+              columns={columns}
+              data={rows}
+              status={isLoading ? "loading" : isError ? "error" : "success"}
+              onRowClick={(row) => navigate(`/dashboard/invoices/${row.id}`)}
+              emptyMessage={
+                debouncedQuery
+                  ? "No invoices match your search."
+                  : "No invoices yet."
+              }
+              error={
+                isError
+                  ? {
+                      message: "Failed to load invoices.",
+                      onRetry: () => void refetch(),
+                    }
+                  : undefined
+              }
+              pagination={{
+                pageIndex: pagination.pageIndex,
+                pageSize: pagination.pageSize,
+                pageCount,
+                totalCount: total,
+              }}
+              tableOptions={{
+                state: { pagination },
+                onPaginationChange: setPagination,
+                manualPagination: true,
+                pageCount,
+              }}
+              containerClassName="border-0 shadow-none bg-transparent"
+              footer={DataTableFooter}
+            />
           </Box>
-
-          <Box style={{ overflowX: "auto" }} w="100%">
-            <Box miw={920}>
-              <DataTable
-                columns={columns}
-                data={rows}
-                status={isLoading ? "loading" : isError ? "error" : "success"}
-                onRowClick={(row) => navigate(`/dashboard/invoices/${row.id}`)}
-                emptyMessage={
-                  debouncedQuery
-                    ? "No invoices match your search."
-                    : "No invoices yet."
-                }
-                error={
-                  isError
-                    ? {
-                        message: "Failed to load invoices.",
-                        onRetry: () => void refetch(),
-                      }
-                    : undefined
-                }
-                pagination={{
-                  pageIndex: pagination.pageIndex,
-                  pageSize: pagination.pageSize,
-                  pageCount,
-                  totalCount: total,
-                }}
-                tableOptions={{
-                  state: { pagination },
-                  onPaginationChange: setPagination,
-                  manualPagination: true,
-                  pageCount,
-                }}
-                containerClassName="border-0 shadow-none bg-transparent"
-                footer={DataTableFooter}
-              />
-            </Box>
-          </Box>
-        </Stack>
-      </Card>
-    </PageContainer>
+        </Box>
+      </Stack>
+    </Card>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx
index 585abea21..023b92e0d 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx
@@ -25,7 +25,6 @@ import {
   humanize,
 } from "@/components/customers";
 import { PhasedFileDropzone } from "@/components/contracts/PhasedFileDropzone";
-import { PageContainer, PageHeader } from "@/components/page";
 import { useAuth } from "@/auth/useAuth";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import { api } from "@/services/api";
@@ -95,7 +94,8 @@ function windowClosed(row: OfflineUsdInvoice): boolean {
   return Boolean(deadline && new Date(deadline).getTime() <= Date.now());
 }
 
-export default function UsdPaymentsPage() {
+/** USD Payments tab body of `FinanceHubPage` — page chrome lives in the parent. */
+export default function UsdPaymentsPanel() {
   const navigate = useNavigate();
   const { pagination, setPagination } = usePagination({ pageSize: 10 });
   const [query, setQuery] = useState("");
@@ -262,24 +262,7 @@ export default function UsdPaymentsPage() {
   );
 
   return (
-    <PageContainer>
-      <PageHeader
-        title="USD Payments"
-        subtitle="USD invoices are paid by bank transfer. Upload the customer's slip and confirm the payment before the pay window closes."
-        action={
-          <ActionIcon
-            variant="default"
-            size="lg"
-            radius="md"
-            aria-label="Refresh"
-            loading={isFetching}
-            onClick={() => void refetch()}
-          >
-            <RefreshCw size={16} />
-          </ActionIcon>
-        }
-      />
-
+    <>
       <Card p={0}>
         <Stack gap={0}>
           <Box px="md" pt="md" pb="sm" w="100%">
@@ -324,6 +307,16 @@ export default function UsdPaymentsPage() {
               <Text size="sm" c="dimmed">
                 {total} record{total !== 1 ? "s" : ""}
               </Text>
+              <ActionIcon
+                variant="default"
+                size="lg"
+                radius="md"
+                aria-label="Refresh"
+                loading={isFetching}
+                onClick={() => void refetch()}
+              >
+                <RefreshCw size={16} />
+              </ActionIcon>
             </Group>
           </Box>
 
@@ -421,6 +414,6 @@ export default function UsdPaymentsPage() {
           </Stack>
         )}
       </Modal>
-    </PageContainer>
+    </>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/payments/PaymentsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/payments/PaymentsPage.tsx
index 60044e550..2d98cc805 100644
--- a/apps/edr-freight-web/backoffice/src/pages/payments/PaymentsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/payments/PaymentsPage.tsx
@@ -25,7 +25,7 @@ import { useMemo, useState } from "react";
 
 import { useQuery } from "@tanstack/react-query";
 
-import { KpiStrip, PageContainer, PageHeader } from "@/components/page";
+import { KpiStrip } from "@/components/page";
 import { api } from "@/services/api";
 import type { PaymentMethod, PaymentRow } from "@/services/payments.service";
 import {
@@ -101,7 +101,8 @@ function formatDate(iso: string | null): string {
 const tableHeader =
   "text-xs font-semibold uppercase tracking-wide text-muted-foreground";
 
-export default function PaymentsPage() {
+/** Payments tab body of `FinanceHubPage` — page chrome lives in the parent. */
+export default function PaymentsPanel() {
   const { pagination, setPagination } = usePagination({ pageSize: 10 });
   const [query, setQuery] = useState("");
   const [statusTab, setStatusTab] = useState<StatusTabKey>("all");
@@ -205,12 +206,7 @@ export default function PaymentsPage() {
   ];
 
   return (
-    <PageContainer>
-      <PageHeader
-        title="Payments"
-        subtitle="View and reconcile booking payment transactions."
-      />
-
+    <Stack gap="lg">
       <KpiStrip
         loading={summaryLoading}
         items={[
@@ -360,6 +356,6 @@ export default function PaymentsPage() {
           </Box>
         </Stack>
       </Card>
-    </PageContainer>
+    </Stack>
   );
 }

From 6c96b7ad94847c64d496e362d4d5d53c08fe3abb Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Thu, 13 Aug 2026 11:27:15 +0000
Subject: [PATCH 081/174] fix(warehouses): free warehouse/yard/zone capacity on
 export dispatch

dispatch() (LOADED -> DISPATCHED) routed through the shared transition()
helper, which only flipped status/timestamp and never called
applyCapacityDelta. deliver() (import pickup) already decrements
correctly, so export cargo leaving by train inflated currentWeight/
currentVolume/currentContainers forever instead of freeing capacity.

Add optional freeCapacity hook to transition(), wire dispatch() to it,
mirroring the negative-delta pattern already used in deliver().
---
 .../warehouses/warehouse-inventory.service.ts   | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

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 58b5e9493..7412f0269 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
@@ -5161,6 +5161,7 @@ export class WarehouseInventoryService {
       activityType: 'INVENTORY_DISPATCHED',
       description: 'Inventory dispatched',
       performedBy,
+      freeCapacity: true,
     });
   }
 
@@ -5445,6 +5446,8 @@ export class WarehouseInventoryService {
       description: string;
       performedBy?: string;
       preloaded?: WarehouseInventory;
+      /** Cargo physically leaves the warehouse on this transition — free up capacity (mirrors deliver()). */
+      freeCapacity?: boolean;
     },
   ): Promise<WarehouseInventory> {
     const item = opts.preloaded ?? (await this.findById(id));
@@ -5455,6 +5458,20 @@ export class WarehouseInventoryService {
         status: to,
         [opts.timestampField]: new Date(),
       });
+
+      if (opts.freeCapacity) {
+        const weight = Number(item.weight) || 0;
+        const volume = Number(item.volume) || 0;
+        const containerCount = item.containerId ? Math.round(Number(item.quantity) || 0) : 0;
+        await this.applyCapacityDelta(
+          manager,
+          { warehouseId: item.warehouseId, yardId: item.yardId, zoneId: item.zoneId },
+          -weight,
+          -volume,
+          -containerCount,
+        );
+      }
+
       await this.activityLog.record(
         {
           activityType: opts.activityType,

From 0df4be1820e4495e4ddd7cc284e478da0853fc26 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 12:44:06 +0000
Subject: [PATCH 082/174] style: overview revamp

---
 .../overview/dto/overview-response.dto.ts     |  61 ++-
 .../modules/overview/overview.repository.ts   | 259 ++++++++++++-
 .../src/modules/overview/overview.service.ts  |  30 +-
 apps/edr-freight-web/backoffice/src/App.tsx   |  17 +
 .../src/components/layout/route-meta.ts       |  28 ++
 .../overview/OverviewKpiSection.tsx           | 167 ---------
 .../overview/OverviewPageHeader.tsx           |  66 ----
 .../overview/OverviewRecentBookingsTable.tsx  | 138 ++++---
 .../overview/OverviewTabContent.tsx           | 119 ------
 .../overview/overview-domains.config.ts       |  88 +++++
 .../src/components/overview/overview.css      |   7 +-
 .../components/overview/summary/CountUp.tsx   |  44 +++
 .../summary/OverviewActivityHeatmap.tsx       | 125 +++++++
 .../summary/OverviewAttentionCard.tsx         | 149 ++++++++
 .../overview/summary/OverviewHero.tsx         | 140 +++++++
 .../overview/summary/OverviewHeroKpis.tsx     |  67 ++++
 .../overview/summary/OverviewNetworkCard.tsx  |  88 +++++
 .../summary/OverviewPipelineFunnel.tsx        | 113 ++++++
 .../overview/summary/OverviewRevenueMix.tsx   | 143 +++++++
 .../summary/OverviewRevenueVolumeChart.tsx    | 172 +++++++++
 .../overview/summary/OverviewSankeyFlow.tsx   | 170 +++++++++
 .../overview/summary/SummaryCard.tsx          |  65 ++++
 .../overview/summary/chart-style.ts           |  14 +
 .../overview/summary/flow-colors.ts           |  25 ++
 .../overview/summary/mergeTrend.test.ts       |  56 +++
 .../components/overview/summary/mergeTrend.ts |  63 ++++
 .../overview/summary/overview-summary.css     |  65 ++++
 .../tabs/OverviewBookingsTabPanel.tsx         |   6 -
 .../tabs/OverviewContractsTabPanel.tsx        |   6 -
 .../tabs/OverviewOperationsTabPanel.tsx       |   6 -
 .../src/components/page/KpiStrip.tsx          |  12 +-
 .../pages/dashboard/OverviewDomainPage.tsx    | 145 ++++++++
 .../src/pages/dashboard/OverviewPage.tsx      | 352 +++++++-----------
 packages/types/src/freight/overview.ts        |  50 ++-
 34 files changed, 2412 insertions(+), 644 deletions(-)
 delete mode 100644 apps/edr-freight-web/backoffice/src/components/overview/OverviewKpiSection.tsx
 delete mode 100644 apps/edr-freight-web/backoffice/src/components/overview/OverviewPageHeader.tsx
 delete mode 100644 apps/edr-freight-web/backoffice/src/components/overview/OverviewTabContent.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/overview-domains.config.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/CountUp.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewActivityHeatmap.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewAttentionCard.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHero.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHeroKpis.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewNetworkCard.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewPipelineFunnel.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueMix.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueVolumeChart.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewSankeyFlow.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/SummaryCard.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/chart-style.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/flow-colors.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/mergeTrend.test.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/mergeTrend.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/summary/overview-summary.css
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewDomainPage.tsx

diff --git a/apps/edr-freight-api/src/modules/overview/dto/overview-response.dto.ts b/apps/edr-freight-api/src/modules/overview/dto/overview-response.dto.ts
index 005dad08a..1bd22c7c0 100644
--- a/apps/edr-freight-api/src/modules/overview/dto/overview-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/overview/dto/overview-response.dto.ts
@@ -21,6 +21,7 @@ export class OverviewContractKpisDto {
 export class OverviewOperationsKpisDto {
   @ApiProperty() trainsActive!: number;
   @ApiProperty() wagonsAvailable!: number;
+  @ApiProperty() wagonsTotal!: number;
   @ApiProperty() containersInTransit!: number;
   @ApiProperty() cargoesLoaded!: number;
   @ApiProperty() schedulesUpcoming!: number;
@@ -108,6 +109,41 @@ export class OverviewRecentContractDto {
   @ApiProperty() createdAt!: string;
 }
 
+export class OverviewPeriodTotalsDto {
+  @ApiProperty() bookingsCreated!: number;
+  @ApiProperty() revenueEtb!: number;
+  @ApiProperty() revenueUsd!: number;
+  @ApiProperty() tons!: number;
+}
+
+export class OverviewRevenueSliceDto {
+  @ApiProperty() label!: string;
+  @ApiProperty() amountEtb!: number;
+  @ApiProperty() amountUsd!: number;
+}
+
+export class OverviewTonsTrendPointDto {
+  @ApiProperty({ example: '2026-06-01' }) date!: string;
+  @ApiProperty() tons!: number;
+}
+
+export class OverviewRevenueFlowDto {
+  @ApiProperty() direction!: string;
+  @ApiProperty() freightType!: string;
+  @ApiProperty() amountEtb!: number;
+  @ApiProperty() amountUsd!: number;
+}
+
+export class OverviewHeatmapCellDto {
+  @ApiProperty({ description: 'ISO weekday, 1 = Monday … 7 = Sunday' })
+  dow!: number;
+
+  @ApiProperty({ description: '3-hour block, 0 = 00–03 … 7 = 21–24' })
+  block!: number;
+
+  @ApiProperty() count!: number;
+}
+
 export class OverviewResponseDto {
   @ApiProperty({ type: OverviewKpisDto })
   kpis!: OverviewKpisDto;
@@ -124,8 +160,29 @@ export class OverviewResponseDto {
   @ApiProperty({ type: [OverviewPaymentTrendPointDto] })
   paymentTrend!: OverviewPaymentTrendPointDto[];
 
-  @ApiProperty({ type: [OverviewRecentBookingDto] })
-  recentBookings!: OverviewRecentBookingDto[];
+  @ApiProperty({ type: OverviewPeriodTotalsDto })
+  current!: OverviewPeriodTotalsDto;
+
+  @ApiProperty({ type: OverviewPeriodTotalsDto })
+  previous!: OverviewPeriodTotalsDto;
+
+  @ApiProperty({ type: [OverviewRevenueSliceDto] })
+  revenueByDirection!: OverviewRevenueSliceDto[];
+
+  @ApiProperty({ type: [OverviewRevenueSliceDto] })
+  revenueByFreightType!: OverviewRevenueSliceDto[];
+
+  @ApiProperty({ type: [OverviewPaymentTrendPointDto] })
+  previousPaymentTrend!: OverviewPaymentTrendPointDto[];
+
+  @ApiProperty({ type: [OverviewTonsTrendPointDto] })
+  tonsTrend!: OverviewTonsTrendPointDto[];
+
+  @ApiProperty({ type: [OverviewRevenueFlowDto] })
+  revenueFlows!: OverviewRevenueFlowDto[];
+
+  @ApiProperty({ type: [OverviewHeatmapCellDto] })
+  bookingHeatmap!: OverviewHeatmapCellDto[];
 
   @ApiProperty() generatedAt!: string;
 }
diff --git a/apps/edr-freight-api/src/modules/overview/overview.repository.ts b/apps/edr-freight-api/src/modules/overview/overview.repository.ts
index c61320d8c..18b6bb54d 100644
--- a/apps/edr-freight-api/src/modules/overview/overview.repository.ts
+++ b/apps/edr-freight-api/src/modules/overview/overview.repository.ts
@@ -155,6 +155,7 @@ export class OverviewRepository {
   async getOperationsKpis(): Promise<{
     trainsActive: number;
     wagonsAvailable: number;
+    wagonsTotal: number;
     containersInTransit: number;
     cargoesLoaded: number;
     schedulesUpcoming: number;
@@ -163,6 +164,7 @@ export class OverviewRepository {
     const [
       trainsActive,
       wagonsAvailable,
+      wagonsTotal,
       containersInTransit,
       cargoesLoaded,
       schedulesUpcoming,
@@ -185,6 +187,10 @@ export class OverviewRepository {
             status: Freight.WagonStatus.Available,
           })
           .getCount(),
+        this.wagonRepository
+          .createQueryBuilder("wagon")
+          .where("wagon.deleted_at IS NULL")
+          .getCount(),
         this.containerRepository
           .createQueryBuilder("container")
           .where("container.deleted_at IS NULL")
@@ -218,6 +224,7 @@ export class OverviewRepository {
     return {
       trainsActive,
       wagonsAvailable,
+      wagonsTotal,
       containersInTransit,
       cargoesLoaded,
       schedulesUpcoming,
@@ -345,9 +352,16 @@ export class OverviewRepository {
     );
   }
 
+  /**
+   * Daily successful-payment revenue for a `days`-wide window shifted back by
+   * `offsetDays` — `0` (default) is the current window ending today,
+   * `offsetDays: days` is the immediately preceding window (the ghost-line
+   * comparison series on the overview chart).
+   */
   async getPaymentTrend(
     days: number,
     dirs?: string[],
+    offsetDays = 0,
   ): Promise<{ date: string; amountEtb: number; amountUsd: number }[]> {
     const scope = bookingRefScopeSql("payment.ref_id", dirs);
     const rows = await this.paymentRepository
@@ -366,8 +380,8 @@ export class OverviewRepository {
       )
       .where("payment.status = :status", { status: "success" })
       .andWhere(
-        `COALESCE(payment.paid_at, payment.created_at) >= CURRENT_DATE - :days::int + 1`,
-        { days },
+        `COALESCE(payment.paid_at, payment.created_at) >= CURRENT_DATE - :offsetDays::int - :days::int + 1 AND COALESCE(payment.paid_at, payment.created_at) < CURRENT_DATE - :offsetDays::int + 1`,
+        { days, offsetDays },
       )
       .andWhere(scope.sql, scope.params)
       .groupBy(`COALESCE(payment.paid_at, payment.created_at)::date`)
@@ -546,6 +560,247 @@ export class OverviewRepository {
     }));
   }
 
+  /**
+   * Bookings created, revenue and tonnage for one `days`-wide window, shifted
+   * back by `offsetDays`. Called twice by the service — `offsetDays: 0` for
+   * the current period, `offsetDays: days` for the immediately preceding
+   * one-of-the-same-length period — so the page can show a real vs-prior-period
+   * delta instead of a bare count.
+   */
+  async getPeriodTotals(
+    days: number,
+    offsetDays: number,
+    dirs?: string[],
+  ): Promise<{
+    bookingsCreated: number;
+    revenueEtb: number;
+    revenueUsd: number;
+    tons: number;
+  }> {
+    const bookingScope = directionScopeSql("booking.trade_direction", dirs);
+    const paymentScope = bookingRefScopeSql("payment.ref_id", dirs);
+    const cargoScope = directionScopeSql("booking.trade_direction", dirs);
+    const windowSql = (column: string) =>
+      `${column} >= CURRENT_DATE - :offsetDays::int - :days::int + 1 AND ${column} < CURRENT_DATE - :offsetDays::int + 1`;
+
+    const [bookingsCreated, revenueRow, tonsRow] = await Promise.all([
+      this.bookingRepository
+        .createQueryBuilder("booking")
+        .where("booking.deleted_at IS NULL")
+        .andWhere(EXCLUDE_GENERAL_CONTRACT_BOOKINGS)
+        .andWhere(bookingScope.sql, bookingScope.params)
+        .andWhere(windowSql("booking.created_at"), { days, offsetDays })
+        .getCount(),
+      this.paymentRepository
+        .createQueryBuilder("payment")
+        .select(
+          `COALESCE(SUM(payment.amount) FILTER (WHERE payment.currency = 'ETB'), 0)`,
+          "revenueEtb",
+        )
+        .addSelect(
+          `COALESCE(SUM(payment.amount) FILTER (WHERE payment.currency = 'USD'), 0)`,
+          "revenueUsd",
+        )
+        .where("payment.status = :status", { status: "success" })
+        .andWhere(
+          windowSql("COALESCE(payment.paid_at, payment.created_at)"),
+          { days, offsetDays },
+        )
+        .andWhere(paymentScope.sql, paymentScope.params)
+        .getRawOne<{ revenueEtb: string; revenueUsd: string }>(),
+      this.cargoRepository
+        .createQueryBuilder("cargo")
+        .leftJoin(Booking, "booking", "booking.id = cargo.booking_id")
+        .select(`COALESCE(SUM(cargo.weight), 0) / 1000`, "tons")
+        .where("cargo.deleted_at IS NULL")
+        .andWhere(windowSql("cargo.created_at"), { days, offsetDays })
+        .andWhere(cargoScope.sql, cargoScope.params)
+        .getRawOne<{ tons: string }>(),
+    ]);
+
+    return {
+      bookingsCreated,
+      revenueEtb: Number(revenueRow?.revenueEtb ?? 0),
+      revenueUsd: Number(revenueRow?.revenueUsd ?? 0),
+      tons: Number(tonsRow?.tons ?? 0),
+    };
+  }
+
+  /** Revenue for the selected range, split by booking trade direction. */
+  async getRevenueByDirection(
+    days: number,
+    dirs?: string[],
+  ): Promise<{ label: string; amountEtb: number; amountUsd: number }[]> {
+    const scope = bookingRefScopeSql("payment.ref_id", dirs);
+    const rows = await this.paymentRepository
+      .createQueryBuilder("payment")
+      .leftJoin(Booking, "booking", "booking.id::text = payment.ref_id")
+      .select("booking.trade_direction", "label")
+      .addSelect(
+        `COALESCE(SUM(payment.amount) FILTER (WHERE payment.currency = 'ETB'), 0)`,
+        "amountEtb",
+      )
+      .addSelect(
+        `COALESCE(SUM(payment.amount) FILTER (WHERE payment.currency = 'USD'), 0)`,
+        "amountUsd",
+      )
+      .where("payment.status = :status", { status: "success" })
+      .andWhere(
+        `COALESCE(payment.paid_at, payment.created_at) >= CURRENT_DATE - :days::int + 1`,
+        { days },
+      )
+      .andWhere(scope.sql, scope.params)
+      .andWhere("booking.trade_direction IS NOT NULL")
+      .groupBy("booking.trade_direction")
+      .getRawMany<{ label: string; amountEtb: string; amountUsd: string }>();
+
+    return rows.map((row) => ({
+      label: row.label,
+      amountEtb: Number(row.amountEtb),
+      amountUsd: Number(row.amountUsd),
+    }));
+  }
+
+  /** Revenue for the selected range, split by booking freight type. */
+  async getRevenueByFreightType(
+    days: number,
+    dirs?: string[],
+  ): Promise<{ label: string; amountEtb: number; amountUsd: number }[]> {
+    const scope = bookingRefScopeSql("payment.ref_id", dirs);
+    const rows = await this.paymentRepository
+      .createQueryBuilder("payment")
+      .leftJoin(Booking, "booking", "booking.id::text = payment.ref_id")
+      .select("booking.freight_type", "label")
+      .addSelect(
+        `COALESCE(SUM(payment.amount) FILTER (WHERE payment.currency = 'ETB'), 0)`,
+        "amountEtb",
+      )
+      .addSelect(
+        `COALESCE(SUM(payment.amount) FILTER (WHERE payment.currency = 'USD'), 0)`,
+        "amountUsd",
+      )
+      .where("payment.status = :status", { status: "success" })
+      .andWhere(
+        `COALESCE(payment.paid_at, payment.created_at) >= CURRENT_DATE - :days::int + 1`,
+        { days },
+      )
+      .andWhere(scope.sql, scope.params)
+      .andWhere("booking.freight_type IS NOT NULL")
+      .groupBy("booking.freight_type")
+      .getRawMany<{ label: string; amountEtb: string; amountUsd: string }>();
+
+    return rows.map((row) => ({
+      label: row.label,
+      amountEtb: Number(row.amountEtb),
+      amountUsd: Number(row.amountUsd),
+    }));
+  }
+
+  /** Daily cargo tonnage for the selected range — hero sparkline series. */
+  async getTonsTrend(
+    days: number,
+    dirs?: string[],
+  ): Promise<{ date: string; tons: number }[]> {
+    const scope = directionScopeSql("booking.trade_direction", dirs);
+    const rows = await this.cargoRepository
+      .createQueryBuilder("cargo")
+      .leftJoin(Booking, "booking", "booking.id = cargo.booking_id")
+      .select(`to_char(cargo.created_at::date, 'YYYY-MM-DD')`, "date")
+      .addSelect(`COALESCE(SUM(cargo.weight), 0) / 1000`, "tons")
+      .where("cargo.deleted_at IS NULL")
+      .andWhere(scope.sql, scope.params)
+      .andWhere(`cargo.created_at >= CURRENT_DATE - :days::int + 1`, { days })
+      .groupBy("cargo.created_at::date")
+      .orderBy("cargo.created_at::date", "ASC")
+      .getRawMany<{ date: string; tons: string }>();
+
+    return rows.map((row) => ({ date: row.date, tons: Number(row.tons) }));
+  }
+
+  /**
+   * Revenue for the selected range as direction → freight-type flows — the
+   * Sankey on the overview. One row per (direction, freight type) pair.
+   */
+  async getRevenueFlows(
+    days: number,
+    dirs?: string[],
+  ): Promise<
+    {
+      direction: string;
+      freightType: string;
+      amountEtb: number;
+      amountUsd: number;
+    }[]
+  > {
+    const scope = bookingRefScopeSql("payment.ref_id", dirs);
+    const rows = await this.paymentRepository
+      .createQueryBuilder("payment")
+      .leftJoin(Booking, "booking", "booking.id::text = payment.ref_id")
+      .select("booking.trade_direction", "direction")
+      .addSelect("booking.freight_type", "freightType")
+      .addSelect(
+        `COALESCE(SUM(payment.amount) FILTER (WHERE payment.currency = 'ETB'), 0)`,
+        "amountEtb",
+      )
+      .addSelect(
+        `COALESCE(SUM(payment.amount) FILTER (WHERE payment.currency = 'USD'), 0)`,
+        "amountUsd",
+      )
+      .where("payment.status = :status", { status: "success" })
+      .andWhere(
+        `COALESCE(payment.paid_at, payment.created_at) >= CURRENT_DATE - :days::int + 1`,
+        { days },
+      )
+      .andWhere(scope.sql, scope.params)
+      .andWhere("booking.trade_direction IS NOT NULL")
+      .andWhere("booking.freight_type IS NOT NULL")
+      .groupBy("booking.trade_direction")
+      .addGroupBy("booking.freight_type")
+      .getRawMany<{
+        direction: string;
+        freightType: string;
+        amountEtb: string;
+        amountUsd: string;
+      }>();
+
+    return rows.map((row) => ({
+      direction: row.direction,
+      freightType: row.freightType,
+      amountEtb: Number(row.amountEtb),
+      amountUsd: Number(row.amountUsd),
+    }));
+  }
+
+  /**
+   * Booking arrivals bucketed by ISO weekday (1 = Mon … 7 = Sun) and 3-hour
+   * block (0 = 00–03 … 7 = 21–24) — the demand-rhythm heatmap. Buckets use
+   * the database server's timezone, same as every ::date grouping here.
+   */
+  async getBookingHeatmap(
+    days: number,
+    dirs?: string[],
+  ): Promise<{ dow: number; block: number; count: number }[]> {
+    const scope = directionScopeSql("booking.trade_direction", dirs);
+    const rows = await this.bookingRepository
+      .createQueryBuilder("booking")
+      .select("EXTRACT(ISODOW FROM booking.created_at)::int", "dow")
+      .addSelect("FLOOR(EXTRACT(HOUR FROM booking.created_at) / 3)::int", "block")
+      .addSelect("COUNT(*)::int", "count")
+      .where("booking.deleted_at IS NULL")
+      .andWhere(EXCLUDE_GENERAL_CONTRACT_BOOKINGS)
+      .andWhere(scope.sql, scope.params)
+      .andWhere(`booking.created_at >= CURRENT_DATE - :days::int + 1`, { days })
+      .groupBy("EXTRACT(ISODOW FROM booking.created_at)::int")
+      .addGroupBy("FLOOR(EXTRACT(HOUR FROM booking.created_at) / 3)::int")
+      .getRawMany<{ dow: string; block: string; count: string }>();
+
+    return rows.map((row) => ({
+      dow: Number(row.dow),
+      block: Number(row.block),
+      count: Number(row.count),
+    }));
+  }
+
   async getTrainStatusBreakdown(): Promise<
     { status: string; count: number }[]
   > {
diff --git a/apps/edr-freight-api/src/modules/overview/overview.service.ts b/apps/edr-freight-api/src/modules/overview/overview.service.ts
index 399bf4f72..a10bb8816 100644
--- a/apps/edr-freight-api/src/modules/overview/overview.service.ts
+++ b/apps/edr-freight-api/src/modules/overview/overview.service.ts
@@ -56,7 +56,14 @@ export class OverviewService {
       bookingTrend,
       statusCounts,
       paymentTrend,
-      recentBookings,
+      current,
+      previous,
+      revenueByDirection,
+      revenueByFreightType,
+      previousPaymentTrend,
+      tonsTrend,
+      revenueFlows,
+      bookingHeatmap,
     ] = await Promise.all([
       this.overviewRepository.getBookingKpis(dirs),
       this.overviewRepository.getContractKpis(dirs),
@@ -67,7 +74,14 @@ export class OverviewService {
       this.overviewRepository.getBookingTrend(days, dirs),
       this.overviewRepository.getStatusCounts(dirs),
       this.overviewRepository.getPaymentTrend(days, dirs),
-      this.overviewRepository.getRecentBookings(8, dirs),
+      this.overviewRepository.getPeriodTotals(days, 0, dirs),
+      this.overviewRepository.getPeriodTotals(days, days, dirs),
+      this.overviewRepository.getRevenueByDirection(days, dirs),
+      this.overviewRepository.getRevenueByFreightType(days, dirs),
+      this.overviewRepository.getPaymentTrend(days, dirs, days),
+      this.overviewRepository.getTonsTrend(days, dirs),
+      this.overviewRepository.getRevenueFlows(days, dirs),
+      this.overviewRepository.getBookingHeatmap(days, dirs),
     ]);
 
     const { bookingsByPipeline, bookingsByStatus } =
@@ -86,10 +100,14 @@ export class OverviewService {
       bookingsByStatus,
       bookingsByPipeline,
       paymentTrend,
-      recentBookings: recentBookings.map((row) => ({
-        ...row,
-        createdAt: row.createdAt.toISOString(),
-      })),
+      current,
+      previous,
+      revenueByDirection,
+      revenueByFreightType,
+      previousPaymentTrend,
+      tonsTrend,
+      revenueFlows,
+      bookingHeatmap,
       generatedAt: new Date().toISOString(),
     };
   }
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index a9b9db226..b9b96de08 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -40,6 +40,8 @@ import InvoiceDetailPage from "./pages/invoices/InvoiceDetailPage";
 import FinanceHubPage from "./pages/invoices/FinanceHubPage";
 import MyProfilePage from "./pages/dashboard/MyProfilePage";
 import OverviewPage from "./pages/dashboard/OverviewPage";
+import OverviewDomainPage from "./pages/dashboard/OverviewDomainPage";
+import { OVERVIEW_DOMAINS } from "./components/overview/overview-domains.config";
 import ReportsIndexRedirect from "./pages/reports/ReportsIndexRedirect";
 import ReportPage from "./pages/reports/ReportPage";
 import AuditLogsPage from "./pages/AuditLogsPage";
@@ -222,6 +224,21 @@ const App = () => {
             </RequirePermission>
           }
         />
+        {/* One drill-down route per overview domain — the old per-tab charts,
+            now each on its own page. Single source of truth for the
+            permission gate is OVERVIEW_DOMAINS, shared with the summary
+            page's "View all" links. */}
+        {OVERVIEW_DOMAINS.map((domain) => (
+          <Route
+            key={domain.key}
+            path={`overview/${domain.key}`}
+            element={
+              <RequirePermission permission={domain.permission}>
+                <OverviewDomainPage />
+              </RequirePermission>
+            }
+          />
+        ))}
         <Route
           path="reports"
           element={
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts b/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts
index 20794f72b..636310e38 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts
+++ b/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts
@@ -36,6 +36,34 @@ const ROUTE_META: Array<{ prefix: string; meta: PageMeta }> = [
       subtitle: "Dashboard summary and key metrics",
     },
   },
+  {
+    prefix: "/dashboard/overview/bookings",
+    meta: { title: "Bookings", subtitle: "Booking volume, pipeline, and recent activity" },
+  },
+  {
+    prefix: "/dashboard/overview/contracts",
+    meta: { title: "Contracts", subtitle: "Contract volume, pipeline, and recent activity" },
+  },
+  {
+    prefix: "/dashboard/overview/billing",
+    meta: { title: "Billing", subtitle: "Revenue, payments, and collection status" },
+  },
+  {
+    prefix: "/dashboard/overview/operations",
+    meta: { title: "Operations", subtitle: "Trains, schedules, containers, and cargo" },
+  },
+  {
+    prefix: "/dashboard/overview/fleet",
+    meta: { title: "Fleet", subtitle: "Wagon and train fleet status" },
+  },
+  {
+    prefix: "/dashboard/overview/customers",
+    meta: { title: "Customers", subtitle: "Customer growth and top accounts" },
+  },
+  {
+    prefix: "/dashboard/overview/staff",
+    meta: { title: "Staff", subtitle: "Employee and user account status" },
+  },
   {
     prefix: "/dashboard/profile",
     meta: {
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/OverviewKpiSection.tsx b/apps/edr-freight-web/backoffice/src/components/overview/OverviewKpiSection.tsx
deleted file mode 100644
index ea99d098e..000000000
--- a/apps/edr-freight-web/backoffice/src/components/overview/OverviewKpiSection.tsx
+++ /dev/null
@@ -1,167 +0,0 @@
-import {
-  AlertCircle,
-  Banknote,
-  Box,
-  Clock,
-  Container,
-  CreditCard,
-  FileText,
-  Train,
-  Truck,
-  UserCheck,
-  Users,
-  Wallet,
-} from "lucide-react";
-import { Group, Paper, Stack, Text } from "@mantine/core";
-
-import type { IOverviewKpis } from "@/types/overview";
-import { OverviewKpiCard } from "./OverviewKpiCard";
-
-function formatCurrency(amount: number, currency: "ETB" | "USD") {
-  return new Intl.NumberFormat("en-US", {
-    style: "currency",
-    currency,
-    maximumFractionDigits: 0,
-  }).format(amount);
-}
-
-export function OverviewKpiSection({ kpis }: { kpis: IOverviewKpis }) {
-  const bookingItems = [
-    {
-      label: "Active bookings",
-      value: kpis.bookings.totalActive,
-      icon: FileText,
-      accent: "emerald" as const,
-    },
-    {
-      label: "Needs action",
-      value: kpis.bookings.needsAction,
-      icon: AlertCircle,
-      accent: "amber" as const,
-    },
-    {
-      label: "Urgent",
-      value: kpis.bookings.urgent,
-      icon: Clock,
-      accent: "rose" as const,
-    },
-    {
-      label: "In approval",
-      value: kpis.bookings.inApproval,
-      icon: UserCheck,
-      accent: "sky" as const,
-    },
-    {
-      label: "Submitted today",
-      value: kpis.bookings.submittedToday,
-      icon: FileText,
-    },
-  ];
-
-  const operationsItems = [
-    {
-      label: "Active trains",
-      value: kpis.operations.trainsActive,
-      icon: Train,
-      accent: "emerald" as const,
-    },
-    {
-      label: "Wagons available",
-      value: kpis.operations.wagonsAvailable,
-      icon: Truck,
-    },
-    {
-      label: "Containers in transit",
-      value: kpis.operations.containersInTransit,
-      icon: Container,
-    },
-    {
-      label: "Cargoes loaded",
-      value: kpis.operations.cargoesLoaded,
-      icon: Box,
-    },
-  ];
-
-  const billingItems = [
-    {
-      label: "Revenue MTD (ETB)",
-      value: formatCurrency(kpis.billing.revenueMtdEtb, "ETB"),
-      icon: Banknote,
-      accent: "emerald" as const,
-    },
-    {
-      label: "Revenue MTD (USD)",
-      value: formatCurrency(kpis.billing.revenueMtdUsd, "USD"),
-      icon: Wallet,
-    },
-    {
-      label: "Pending payments",
-      value: kpis.billing.pendingPayments,
-      icon: CreditCard,
-      accent: "amber" as const,
-    },
-    {
-      label: "Successful MTD",
-      value: kpis.billing.successfulPaymentsMtd,
-      icon: Banknote,
-    },
-  ];
-
-  const peopleItems = [
-    {
-      label: "Total customers",
-      value: kpis.customers.totalCustomers,
-      icon: Users,
-    },
-    {
-      label: "New this month",
-      value: kpis.customers.newCustomersThisMonth,
-      icon: Users,
-      accent: "emerald" as const,
-    },
-    {
-      label: "Active employees",
-      value: kpis.staff.activeEmployees,
-      icon: UserCheck,
-    },
-    {
-      label: "Active users",
-      value: kpis.staff.activeUsers,
-      icon: Users,
-    },
-  ];
-
-  const sections = [
-    { title: "Bookings", items: bookingItems },
-    { title: "Operations", items: operationsItems },
-    { title: "Billing", items: billingItems },
-    { title: "Customers & staff", items: peopleItems },
-  ];
-
-  return (
-    <Stack gap="md">
-      {sections.map((section) => (
-        <Paper
-          key={section.title}
-          p="md"
-          radius="lg"
-          withBorder
-          style={{
-            background: "white",
-            border: "1px solid var(--mantine-color-gray-2)",
-            overflowX: "auto",
-          }}
-        >
-          <Text size="sm" fw={600} mb="sm" c="dimmed">
-            {section.title}
-          </Text>
-          <Group gap="md" style={{ flexWrap: "nowrap", minWidth: "min-content" }}>
-            {section.items.map((item) => (
-              <OverviewKpiCard key={item.label} item={item} />
-            ))}
-          </Group>
-        </Paper>
-      ))}
-    </Stack>
-  );
-}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/OverviewPageHeader.tsx b/apps/edr-freight-web/backoffice/src/components/overview/OverviewPageHeader.tsx
deleted file mode 100644
index 529981add..000000000
--- a/apps/edr-freight-web/backoffice/src/components/overview/OverviewPageHeader.tsx
+++ /dev/null
@@ -1,66 +0,0 @@
-import { ActionIcon, Group, SegmentedControl, Text } from "@mantine/core";
-import { RefreshCw } from "lucide-react";
-
-import type { OverviewRange } from "@/types/overview";
-
-const RANGE_OPTIONS = [
-  { label: "7 days", value: "7d" },
-  { label: "30 days", value: "30d" },
-  { label: "90 days", value: "90d" },
-];
-
-function formatRelativeTime(iso: string | undefined) {
-  if (!iso) return "—";
-  const diffMs = Date.now() - new Date(iso).getTime();
-  const minutes = Math.floor(diffMs / 60_000);
-  if (minutes < 1) return "just now";
-  if (minutes < 60) return `${minutes}m ago`;
-  const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}h ago`;
-  return new Date(iso).toLocaleString();
-}
-
-interface OverviewPageHeaderProps {
-  range: OverviewRange;
-  onRangeChange: (range: OverviewRange) => void;
-  generatedAt?: string;
-  onRefresh: () => void;
-  isRefreshing?: boolean;
-}
-
-export function OverviewPageHeader({
-  range,
-  onRangeChange,
-  generatedAt,
-  onRefresh,
-  isRefreshing,
-}: OverviewPageHeaderProps) {
-  return (
-    <Group justify="space-between" align="center" wrap="wrap" gap="md">
-      <Text size="sm" c="dimmed">
-        Updated {formatRelativeTime(generatedAt)}
-      </Text>
-      <Group gap="sm">
-        <SegmentedControl
-          value={range}
-          onChange={(value) => onRangeChange(value as OverviewRange)}
-          data={RANGE_OPTIONS}
-          size="sm"
-          radius="lg"
-          color="edr-green"
-        />
-        <ActionIcon
-          variant="light"
-          color="edr-green"
-          size="lg"
-          radius="lg"
-          aria-label="Refresh dashboard"
-          onClick={onRefresh}
-          loading={isRefreshing}
-        >
-          <RefreshCw size={18} />
-        </ActionIcon>
-      </Group>
-    </Group>
-  );
-}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/OverviewRecentBookingsTable.tsx b/apps/edr-freight-web/backoffice/src/components/overview/OverviewRecentBookingsTable.tsx
index b13f5c473..e1ceaec1c 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/OverviewRecentBookingsTable.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/OverviewRecentBookingsTable.tsx
@@ -1,9 +1,11 @@
-import { useNavigate } from "react-router-dom";
-import { Paper, Stack, Table, Text } from "@mantine/core";
+import { History } from "lucide-react";
+import { Link, useNavigate } from "react-router-dom";
+import { Table, Text } from "@mantine/core";
 
 import { BookingPriorityBadge } from "@/components/bookings/BookingPriorityBadge";
 import { BookingStatusBadge } from "@/components/bookings/BookingStatusBadge";
 import type { IOverviewRecentBooking } from "@/types/overview";
+import { SummaryCard } from "./summary/SummaryCard";
 
 function formatAmount(amount: number | null, currency: string | null) {
   if (amount == null) return "—";
@@ -23,56 +25,90 @@ export function OverviewRecentBookingsTable({
   const navigate = useNavigate();
 
   return (
-    <Paper p="lg" radius="lg" withBorder>
-      <Stack gap="md">
-        <Text fw={600}>Recent bookings</Text>
-        {bookings.length === 0 ? (
-          <Text size="sm" c="dimmed" ta="center" py="lg">
-            No recent bookings
-          </Text>
-        ) : (
-          <Table highlightOnHover verticalSpacing="sm">
-            <Table.Thead>
-              <Table.Tr>
-                <Table.Th>Reference</Table.Th>
-                <Table.Th>Customer</Table.Th>
-                <Table.Th>Status</Table.Th>
-                <Table.Th>Priority</Table.Th>
-                <Table.Th>Amount</Table.Th>
-                <Table.Th>Created</Table.Th>
-              </Table.Tr>
-            </Table.Thead>
-            <Table.Tbody>
-              {bookings.map((booking) => (
-                <Table.Tr
-                  key={booking.id}
-                  style={{ cursor: "pointer" }}
-                  onClick={() => navigate(`/dashboard/booking-requests/${booking.id}`)}
-                >
-                  <Table.Td>
-                    <Text fw={600} size="sm">
-                      {booking.reference}
-                    </Text>
-                  </Table.Td>
-                  <Table.Td>{booking.customerLabel}</Table.Td>
-                  <Table.Td>
-                    <BookingStatusBadge status={booking.status} />
-                  </Table.Td>
-                  <Table.Td>
-                    <BookingPriorityBadge score={booking.priorityScore} />
-                  </Table.Td>
-                  <Table.Td>
+    <SummaryCard
+      icon={History}
+      accent="gray"
+      title="Recent bookings"
+      subtitle="Latest submissions, newest first"
+      minHeight={260}
+      action={
+        <Text
+          component={Link}
+          to="/dashboard/booking-requests"
+          size="xs"
+          fw={600}
+          c="edr-green"
+          style={{ whiteSpace: "nowrap", textDecoration: "none" }}
+        >
+          View all →
+        </Text>
+      }
+    >
+      {bookings.length === 0 ? (
+        <Text size="sm" c="dimmed" ta="center" py="lg">
+          No recent bookings
+        </Text>
+      ) : (
+        <Table highlightOnHover verticalSpacing="sm" horizontalSpacing="sm">
+          <Table.Thead>
+            <Table.Tr>
+              {["Reference", "Customer", "Status", "Priority", "Amount", "Created"].map(
+                (header) => (
+                  <Table.Th
+                    key={header}
+                    style={{
+                      fontSize: 11,
+                      fontWeight: 700,
+                      textTransform: "uppercase",
+                      letterSpacing: 0.3,
+                      color: "var(--mantine-color-edr-muted-6)",
+                      borderBottom: "1px solid var(--mantine-color-gray-2)",
+                    }}
+                  >
+                    {header}
+                  </Table.Th>
+                ),
+              )}
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            {bookings.map((booking) => (
+              <Table.Tr
+                key={booking.id}
+                style={{ cursor: "pointer" }}
+                onClick={() => navigate(`/dashboard/booking-requests/${booking.id}`)}
+              >
+                <Table.Td>
+                  <Text fw={600} size="sm">
+                    {booking.reference}
+                  </Text>
+                </Table.Td>
+                <Table.Td>
+                  <Text size="sm" truncate style={{ maxWidth: 180 }}>
+                    {booking.customerLabel}
+                  </Text>
+                </Table.Td>
+                <Table.Td>
+                  <BookingStatusBadge status={booking.status} />
+                </Table.Td>
+                <Table.Td>
+                  <BookingPriorityBadge score={booking.priorityScore} />
+                </Table.Td>
+                <Table.Td>
+                  <Text size="sm" style={{ fontVariantNumeric: "tabular-nums" }}>
                     {formatAmount(booking.totalAmount, booking.paymentCurrency)}
-                  </Table.Td>
-                  <Table.Td>
+                  </Text>
+                </Table.Td>
+                <Table.Td>
+                  <Text size="sm" c="dimmed">
                     {new Date(booking.createdAt).toLocaleDateString()}
-                  </Table.Td>
-                </Table.Tr>
-              ))}
-            </Table.Tbody>
-          </Table>
-        )}
-      </Stack>
-    </Paper>
+                  </Text>
+                </Table.Td>
+              </Table.Tr>
+            ))}
+          </Table.Tbody>
+        </Table>
+      )}
+    </SummaryCard>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/OverviewTabContent.tsx b/apps/edr-freight-web/backoffice/src/components/overview/OverviewTabContent.tsx
deleted file mode 100644
index cf71198a6..000000000
--- a/apps/edr-freight-web/backoffice/src/components/overview/OverviewTabContent.tsx
+++ /dev/null
@@ -1,119 +0,0 @@
-import { AlertCircle } from "lucide-react";
-import { Alert, Button, Center, Loader, Paper, Skeleton, Stack } from "@mantine/core";
-
-import {
-  useOverviewBillingTab,
-  useOverviewBookingsTab,
-  useOverviewContractsTab,
-  useOverviewCustomersTab,
-  useOverviewOperationsTab,
-  useOverviewStaffTab,
-} from "@/hooks/useOverview";
-import type { OverviewRange, OverviewTabKey } from "@/types/overview";
-import { OverviewBillingTabPanel } from "./tabs/OverviewBillingTabPanel";
-import { OverviewBookingsTabPanel } from "./tabs/OverviewBookingsTabPanel";
-import { OverviewContractsTabPanel } from "./tabs/OverviewContractsTabPanel";
-import { OverviewCustomersTabPanel } from "./tabs/OverviewCustomersTabPanel";
-import { OverviewFleetTabPanel } from "./tabs/OverviewFleetTabPanel";
-import { OverviewOperationsTabPanel } from "./tabs/OverviewOperationsTabPanel";
-import { OverviewStaffTabPanel } from "./tabs/OverviewStaffTabPanel";
-
-function TabSkeleton() {
-  return (
-    <Stack gap="lg">
-      <Skeleton height={120} radius="lg" />
-      <Skeleton height={320} radius="lg" />
-      <Skeleton height={320} radius="lg" />
-    </Stack>
-  );
-}
-
-interface OverviewTabContentProps {
-  tab: OverviewTabKey;
-  range: OverviewRange;
-}
-
-export function OverviewTabContent({ tab, range }: OverviewTabContentProps) {
-  const bookings = useOverviewBookingsTab(range, tab === "bookings");
-  const contracts = useOverviewContractsTab(range, tab === "contracts");
-  const billing = useOverviewBillingTab(range, tab === "billing");
-  // Fleet reuses the operations dataset — same query key, so switching between
-  // the two tabs costs one fetch.
-  const operations = useOverviewOperationsTab(
-    range,
-    tab === "operations" || tab === "fleet",
-  );
-  const customers = useOverviewCustomersTab(range, tab === "customers");
-  const staff = useOverviewStaffTab(range, tab === "staff");
-
-  const query =
-    tab === "bookings"
-      ? bookings
-      : tab === "contracts"
-        ? contracts
-        : tab === "billing"
-          ? billing
-          : tab === "operations" || tab === "fleet"
-            ? operations
-            : tab === "customers"
-              ? customers
-              : staff;
-
-  const { isLoading, isError, refetch, isFetching } = query;
-
-  if (isLoading) {
-    return <TabSkeleton />;
-  }
-
-  if (isError || !query.data) {
-    return (
-      <Paper p="xl" radius="lg" withBorder>
-        <Alert
-          icon={<AlertCircle size={16} />}
-          color="red"
-          title="Failed to load tab data"
-          variant="light"
-        >
-          <Stack gap="sm" align="flex-start">
-            <span>Could not load {tab} metrics. Please try again.</span>
-            <Button size="xs" variant="light" color="red" onClick={() => void refetch()}>
-              Retry
-            </Button>
-          </Stack>
-        </Alert>
-      </Paper>
-    );
-  }
-
-  return (
-    <Stack gap="md" pos="relative">
-      {isFetching && (
-        <Center style={{ position: "absolute", top: 8, right: 8, zIndex: 2 }}>
-          <Loader size="sm" color="edr-green" />
-        </Center>
-      )}
-
-      {tab === "bookings" && bookings.data && (
-        <OverviewBookingsTabPanel data={bookings.data} />
-      )}
-      {tab === "contracts" && contracts.data && (
-        <OverviewContractsTabPanel data={contracts.data} />
-      )}
-      {tab === "billing" && billing.data && (
-        <OverviewBillingTabPanel data={billing.data} />
-      )}
-      {tab === "operations" && operations.data && (
-        <OverviewOperationsTabPanel data={operations.data} />
-      )}
-      {tab === "fleet" && operations.data && (
-        <OverviewFleetTabPanel data={operations.data} />
-      )}
-      {tab === "customers" && customers.data && (
-        <OverviewCustomersTabPanel data={customers.data} />
-      )}
-      {tab === "staff" && staff.data && (
-        <OverviewStaffTabPanel data={staff.data} />
-      )}
-    </Stack>
-  );
-}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/overview-domains.config.ts b/apps/edr-freight-web/backoffice/src/components/overview/overview-domains.config.ts
new file mode 100644
index 000000000..4d106eeeb
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/overview-domains.config.ts
@@ -0,0 +1,88 @@
+import {
+  Banknote,
+  FileSignature,
+  FileText,
+  Train,
+  TrainFront,
+  UserCheck,
+  Users,
+  type LucideIcon,
+} from "lucide-react";
+
+import { FREIGHT_PERMS } from "@/lib/permissions";
+import type { OverviewTabKey } from "@/types/overview";
+
+/**
+ * Single source of truth for the seven overview drill-down pages — used both
+ * to build the `/dashboard/overview/:domain` routes in App.tsx and to render
+ * each page's header in OverviewDomainPage. One list, no duplicated permission
+ * arrays to drift out of sync.
+ */
+export const OVERVIEW_DOMAINS: Array<{
+  key: OverviewTabKey;
+  label: string;
+  subtitle: string;
+  icon: LucideIcon;
+  /** Any of these keys grants the page. */
+  permission: string[];
+}> = [
+  {
+    key: "bookings",
+    label: "Bookings",
+    subtitle: "Booking volume, pipeline, and recent activity",
+    icon: FileText,
+    permission: [FREIGHT_PERMS.bookings.view],
+  },
+  {
+    key: "contracts",
+    label: "Contracts",
+    subtitle: "Contract volume, pipeline, and recent activity",
+    icon: FileSignature,
+    permission: [FREIGHT_PERMS.contracts.view],
+  },
+  {
+    key: "billing",
+    label: "Billing",
+    subtitle: "Revenue, payments, and collection status",
+    icon: Banknote,
+    permission: [FREIGHT_PERMS.bookings.view, FREIGHT_PERMS.payments.view],
+  },
+  {
+    key: "operations",
+    label: "Operations",
+    subtitle: "Trains, schedules, containers, and cargo",
+    icon: Train,
+    permission: [
+      FREIGHT_PERMS.trainScheduling.view,
+      FREIGHT_PERMS.warehouseInventory.view,
+      FREIGHT_PERMS.firstMile.view,
+      FREIGHT_PERMS.lastMile.view,
+    ],
+  },
+  {
+    key: "fleet",
+    label: "Fleet",
+    subtitle: "Wagon and train fleet status",
+    icon: TrainFront,
+    permission: [FREIGHT_PERMS.wagons.view, FREIGHT_PERMS.trainScheduling.view],
+  },
+  {
+    key: "customers",
+    label: "Customers",
+    subtitle: "Customer growth and top accounts",
+    icon: Users,
+    permission: [FREIGHT_PERMS.customers.view],
+  },
+  {
+    key: "staff",
+    label: "Staff",
+    subtitle: "Employee and user account status",
+    icon: UserCheck,
+    permission: [
+      FREIGHT_PERMS.admin,
+      FREIGHT_PERMS.staff.roles.view,
+      FREIGHT_PERMS.staff.employeeRegistration.view,
+      FREIGHT_PERMS.staff.roleAssignment.view,
+    ],
+  },
+];
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/overview.css b/apps/edr-freight-web/backoffice/src/components/overview/overview.css
index 86b468df3..10b358bbd 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/overview.css
+++ b/apps/edr-freight-web/backoffice/src/components/overview/overview.css
@@ -1,5 +1,8 @@
 /* ============================================================
-   EDR Freight — Overview page styles (hero controls + tabs)
+   EDR Freight — shared "premium" tab bar + segmented control styles.
+   Named after the overview page they were first built for, but now shared
+   by BookingStatusTabs, ContractStatusTabs, and ReceiveInventoryModal —
+   do not remove `.ov-tablist` / `.ov-tab` without checking those importers.
    ============================================================ */
 
 /* ---- Hero range segmented control (on gradient) ---- */
@@ -19,7 +22,7 @@
   color: var(--mantine-color-edr-green-7);
 }
 
-/* ---- Premium tab bar ---- */
+/* ---- Premium tab bar (BookingStatusTabs, ContractStatusTabs, ReceiveInventoryModal) ---- */
 .ov-tablist {
   display: flex;
   flex-wrap: wrap;
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/CountUp.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/CountUp.tsx
new file mode 100644
index 000000000..28802e321
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/CountUp.tsx
@@ -0,0 +1,44 @@
+import { useEffect, useRef, useState } from "react";
+
+const DURATION_MS = 750;
+
+function prefersReducedMotion() {
+  return (
+    typeof window !== "undefined" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  );
+}
+
+/**
+ * Animates a number from 0 to `value` (ease-out) on mount and whenever the
+ * value changes — the hero-KPI count-up. Renders the final value immediately
+ * when the user prefers reduced motion.
+ */
+export function CountUp({
+  value,
+  format = (n) => Math.round(n).toLocaleString(),
+}: {
+  value: number;
+  format?: (n: number) => string;
+}) {
+  const [display, setDisplay] = useState(() => (prefersReducedMotion() ? value : 0));
+  const frame = useRef<number>(0);
+
+  useEffect(() => {
+    if (prefersReducedMotion()) {
+      setDisplay(value);
+      return;
+    }
+    const start = performance.now();
+    const tick = (now: number) => {
+      const t = Math.min(1, (now - start) / DURATION_MS);
+      const eased = 1 - (1 - t) ** 3;
+      setDisplay(value * eased);
+      if (t < 1) frame.current = requestAnimationFrame(tick);
+    };
+    frame.current = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frame.current);
+  }, [value]);
+
+  return <>{format(display)}</>;
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewActivityHeatmap.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewActivityHeatmap.tsx
new file mode 100644
index 000000000..4f1958265
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewActivityHeatmap.tsx
@@ -0,0 +1,125 @@
+import { Fragment } from "react";
+import { CalendarClock } from "lucide-react";
+import { Badge, Group, Stack, Text, Tooltip } from "@mantine/core";
+
+import type { IOverviewHeatmapCell } from "@/types/overview";
+import { SummaryCard } from "./SummaryCard";
+
+/** ISO weekday order, 1 = Monday. */
+const DAY_LABELS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+/** 3-hour blocks, 0 = 00–03 … 7 = 21–24. */
+const BLOCK_LABELS = ["12a", "3a", "6a", "9a", "12p", "3p", "6p", "9p"];
+
+/** Map an intensity in (0, 1] to the brand-green ramp; zero stays neutral. */
+function cellColor(count: number, max: number) {
+  if (count === 0) return "var(--mantine-color-gray-1)";
+  const shade = Math.max(1, Math.min(7, Math.ceil((count / max) * 7)));
+  return `var(--mantine-color-edr-green-${shade})`;
+}
+
+interface OverviewActivityHeatmapProps {
+  cells: IOverviewHeatmapCell[];
+}
+
+/**
+ * When demand arrives: booking submissions by weekday × 3-hour block for the
+ * selected range. The bright cells (and the peak badge) are the hours the
+ * intake team needs to be staffed for.
+ */
+export function OverviewActivityHeatmap({ cells }: OverviewActivityHeatmapProps) {
+  const countByCell = new Map(cells.map((c) => [`${c.dow}-${c.block}`, c.count]));
+  const max = Math.max(0, ...cells.map((c) => c.count));
+  const peak = cells.reduce<IOverviewHeatmapCell | null>(
+    (best, c) => (c.count > (best?.count ?? 0) ? c : best),
+    null,
+  );
+
+  return (
+    <SummaryCard
+      icon={CalendarClock}
+      accent="violet"
+      title="Booking rhythm"
+      subtitle="When bookings arrive, by weekday and time"
+      action={
+        peak ? (
+          <Badge variant="light" color="violet" size="sm" style={{ textTransform: "none" }}>
+            Peak {DAY_LABELS[peak.dow - 1]} {BLOCK_LABELS[peak.block]}
+          </Badge>
+        ) : null
+      }
+    >
+      {max === 0 ? (
+        <Text size="sm" c="dimmed" ta="center" py="xl">
+          No bookings in this period
+        </Text>
+      ) : (
+        <Stack gap={4}>
+          <div
+            style={{
+              display: "grid",
+              gridTemplateColumns: "36px repeat(8, 1fr)",
+              gap: 3,
+            }}
+          >
+            <span />
+            {BLOCK_LABELS.map((label) => (
+              <Text key={label} size="xs" c="dimmed" ta="center">
+                {label}
+              </Text>
+            ))}
+            {DAY_LABELS.map((day, dayIndex) => (
+              <Fragment key={day}>
+                <Text size="xs" c="dimmed" style={{ lineHeight: "24px" }}>
+                  {day}
+                </Text>
+                {BLOCK_LABELS.map((_, block) => {
+                  const count = countByCell.get(`${dayIndex + 1}-${block}`) ?? 0;
+                  return (
+                    <Tooltip
+                      key={`${day}-${block}`}
+                      label={`${day} ${BLOCK_LABELS[block]}–${BLOCK_LABELS[(block + 1) % 8]} · ${count} booking${count === 1 ? "" : "s"}`}
+                      withArrow
+                      openDelay={150}
+                    >
+                      <div
+                        style={{
+                          height: 24,
+                          borderRadius: 6,
+                          background: cellColor(count, max),
+                          cursor: "default",
+                          transition: "transform 120ms ease",
+                        }}
+                      />
+                    </Tooltip>
+                  );
+                })}
+              </Fragment>
+            ))}
+          </div>
+          <Group gap={6} justify="flex-end" mt={4}>
+            <Text size="xs" c="dimmed">
+              Less
+            </Text>
+            {[0, 2, 4, 6].map((shade) => (
+              <div
+                key={shade}
+                style={{
+                  width: 14,
+                  height: 14,
+                  borderRadius: 4,
+                  background:
+                    shade === 0
+                      ? "var(--mantine-color-gray-1)"
+                      : `var(--mantine-color-edr-green-${shade + 1})`,
+                }}
+              />
+            ))}
+            <Text size="xs" c="dimmed">
+              More
+            </Text>
+          </Group>
+        </Stack>
+      )}
+    </SummaryCard>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewAttentionCard.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewAttentionCard.tsx
new file mode 100644
index 000000000..142b8814f
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewAttentionCard.tsx
@@ -0,0 +1,149 @@
+import {
+  AlertCircle,
+  Banknote,
+  BellRing,
+  Check,
+  ChevronRight,
+  Clock,
+  FileSignature,
+  ShieldCheck,
+} from "lucide-react";
+import { Link } from "react-router-dom";
+import { Badge, Group, Stack, Text, ThemeIcon } from "@mantine/core";
+
+import type { IOverviewBillingKpis, IOverviewBookingKpis, IOverviewContractKpis } from "@/types/overview";
+import { SummaryCard } from "./SummaryCard";
+
+interface OverviewAttentionCardProps {
+  bookings: IOverviewBookingKpis;
+  contracts: IOverviewContractKpis;
+  billing: IOverviewBillingKpis;
+}
+
+/**
+ * The work queue, demoted below the money/volume story but still one glance
+ * away — this page is read by executives first, staff second. Every row
+ * links to the real filtered (or closest available) list; none are dead ends.
+ */
+export function OverviewAttentionCard({ bookings, contracts, billing }: OverviewAttentionCardProps) {
+  const rows = [
+    {
+      key: "needsAction",
+      label: "Bookings needing action",
+      count: bookings.needsAction,
+      icon: AlertCircle,
+      href: "/dashboard/booking-requests",
+    },
+    {
+      key: "urgent",
+      label: "Urgent bookings",
+      count: bookings.urgent,
+      icon: Clock,
+      href: "/dashboard/booking-requests",
+    },
+    {
+      key: "contractsApproval",
+      label: "Contracts in approval",
+      count: contracts.inApproval,
+      icon: FileSignature,
+      href: "/dashboard/contract-requests",
+    },
+    {
+      key: "contractsClearance",
+      label: "Contracts in clearance",
+      count: contracts.inClearance,
+      icon: ShieldCheck,
+      href: "/dashboard/contracts/clearance",
+    },
+    {
+      key: "pendingPayments",
+      label: "Pending payments",
+      count: billing.pendingPayments,
+      icon: Banknote,
+      href: "/dashboard/payments",
+    },
+  ];
+  const openItems = rows.reduce((sum, row) => sum + row.count, 0);
+  const allClear = openItems === 0;
+
+  return (
+    <SummaryCard
+      icon={BellRing}
+      accent="orange"
+      title="Needs attention"
+      subtitle="Waiting on someone here"
+      minHeight={260}
+      action={
+        allClear ? null : (
+          <Badge variant="light" color="orange" size="sm" style={{ textTransform: "none" }}>
+            {openItems.toLocaleString()} open
+          </Badge>
+        )
+      }
+    >
+      {allClear ? (
+        <Stack align="center" gap={8} py="lg">
+          <ThemeIcon variant="light" color="edr-green" size={48} radius="xl">
+            <Check size={26} />
+          </ThemeIcon>
+          <Text fw={700}>All clear</Text>
+          <Text size="sm" c="dimmed">
+            Nothing waiting on you right now.
+          </Text>
+        </Stack>
+      ) : (
+        <Stack gap={4}>
+          {rows.map((row) => {
+            const Icon = row.icon;
+            const active = row.count > 0;
+            return (
+              <Link
+                key={row.key}
+                to={row.href}
+                className="ov-row"
+                style={{ textDecoration: "none", color: "inherit", padding: "7px 10px" }}
+              >
+                <Group justify="space-between" wrap="nowrap">
+                  <Group gap={10} wrap="nowrap" style={{ minWidth: 0 }}>
+                    <ThemeIcon
+                      variant="light"
+                      color={active ? "orange" : "gray"}
+                      size={30}
+                      radius={10}
+                      style={{ flexShrink: 0 }}
+                    >
+                      <Icon size={16} />
+                    </ThemeIcon>
+                    <Text size="sm" c="edr-text" truncate>
+                      {row.label}
+                    </Text>
+                  </Group>
+                  <Group gap={6} wrap="nowrap" style={{ flexShrink: 0 }}>
+                    <Text
+                      size="sm"
+                      fw={700}
+                      ta="center"
+                      c={active ? "orange.8" : "dimmed"}
+                      style={{
+                        minWidth: 34,
+                        background: active
+                          ? "var(--mantine-color-orange-0)"
+                          : "var(--mantine-color-gray-0)",
+                        borderRadius: 999,
+                        padding: "1px 8px",
+                        fontVariantNumeric: "tabular-nums",
+                      }}
+                    >
+                      {row.count}
+                    </Text>
+                    <ChevronRight size={14} style={{ color: "var(--mantine-color-edr-muted-6)" }} />
+                  </Group>
+                </Group>
+              </Link>
+            );
+          })}
+        </Stack>
+      )}
+    </SummaryCard>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHero.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHero.tsx
new file mode 100644
index 000000000..04e2b273f
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHero.tsx
@@ -0,0 +1,140 @@
+import { RefreshCw } from "lucide-react";
+import { ActionIcon, Badge, Group, SegmentedControl, Stack, Text } from "@mantine/core";
+
+import { useAuth } from "@/auth/useAuth";
+import { freightBrand } from "@/theme/freight-brand";
+import type { OverviewRange } from "@/types/overview";
+import "@/components/overview/overview.css";
+
+const RANGE_OPTIONS = [
+  { label: "7 days", value: "7d" },
+  { label: "30 days", value: "30d" },
+  { label: "90 days", value: "90d" },
+];
+
+function formatRelativeTime(iso: string | undefined) {
+  if (!iso) return "—";
+  const diffMs = Date.now() - new Date(iso).getTime();
+  const minutes = Math.floor(diffMs / 60_000);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return new Date(iso).toLocaleString();
+}
+
+function greeting(hour: number) {
+  if (hour < 12) return "Good morning";
+  if (hour < 18) return "Good afternoon";
+  return "Good evening";
+}
+
+interface OverviewHeroProps {
+  range: OverviewRange;
+  onRangeChange: (range: OverviewRange) => void;
+  generatedAt?: string;
+  onRefresh: () => void;
+  isRefreshing?: boolean;
+}
+
+/**
+ * Brand-gradient greeting banner: time-of-day greeting with the signed-in
+ * user's first name, today's date, freshness badge, and the range controls.
+ * Extra bottom padding leaves room for the KPI strip to overlap it.
+ */
+export function OverviewHero({
+  range,
+  onRangeChange,
+  generatedAt,
+  onRefresh,
+  isRefreshing,
+}: OverviewHeroProps) {
+  const { user } = useAuth();
+  const fullName = (user?.name?.en ?? user?.name?.am)?.trim();
+  const firstName = fullName ? fullName.split(/\s+/)[0] : undefined;
+  const now = new Date();
+  const dateLabel = now.toLocaleDateString(undefined, {
+    weekday: "long",
+    day: "numeric",
+    month: "long",
+    year: "numeric",
+  });
+
+  return (
+    <div
+      style={{
+        background: freightBrand.gradient,
+        borderRadius: 20,
+        padding: "28px 28px 76px",
+        position: "relative",
+        overflow: "hidden",
+      }}
+    >
+      {/* Soft highlight so the flat gradient reads as a lit surface. */}
+      <div
+        style={{
+          position: "absolute",
+          inset: 0,
+          background:
+            "radial-gradient(640px 240px at 85% -40%, rgba(255, 255, 255, 0.2), transparent)",
+          pointerEvents: "none",
+        }}
+      />
+      <Group
+        justify="space-between"
+        align="flex-start"
+        wrap="wrap"
+        gap="md"
+        style={{ position: "relative" }}
+      >
+        <Stack gap={6}>
+          <Text c="white" fw={800} fz={26} lh={1.15} style={{ letterSpacing: "-0.02em" }}>
+            {greeting(now.getHours())}
+            {firstName ? `, ${firstName}` : ""} 👋
+          </Text>
+          <Group gap={10}>
+            <Text c="rgba(255,255,255,0.75)" size="sm">
+              {dateLabel}
+            </Text>
+            <Badge
+              size="sm"
+              variant="light"
+              style={{
+                background: "rgba(255,255,255,0.16)",
+                color: "rgba(255,255,255,0.9)",
+                textTransform: "none",
+              }}
+            >
+              Updated {formatRelativeTime(generatedAt)}
+            </Badge>
+          </Group>
+        </Stack>
+        <Group gap="sm">
+          <SegmentedControl
+            value={range}
+            onChange={(value) => onRangeChange(value as OverviewRange)}
+            data={RANGE_OPTIONS}
+            size="sm"
+            radius="lg"
+            classNames={{
+              root: "ov-seg-root",
+              indicator: "ov-seg-indicator",
+              label: "ov-seg-label",
+            }}
+          />
+          <ActionIcon
+            variant="white"
+            color="edr-green"
+            size="lg"
+            radius="lg"
+            aria-label="Refresh dashboard"
+            onClick={onRefresh}
+            loading={isRefreshing}
+          >
+            <RefreshCw size={18} />
+          </ActionIcon>
+        </Group>
+      </Group>
+    </div>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHeroKpis.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHeroKpis.tsx
new file mode 100644
index 000000000..32ee768d1
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHeroKpis.tsx
@@ -0,0 +1,67 @@
+import { Banknote, FileSignature, FileText, Package } from "lucide-react";
+
+import { KpiStrip, type KpiItem } from "@/components/page";
+import type { IOverviewKpis, IOverviewPeriodTotals } from "@/types/overview";
+import { CountUp } from "./CountUp";
+
+function formatCurrency(amount: number, currency: "ETB" | "USD") {
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency,
+    maximumFractionDigits: 0,
+  }).format(amount);
+}
+
+/** Period-over-period % change, or undefined when there's no prior baseline to compare against. */
+function pctDelta(current: number, previous: number): number | undefined {
+  if (previous === 0) return undefined;
+  return Math.round(((current - previous) / previous) * 100);
+}
+
+interface OverviewHeroKpisProps {
+  kpis: IOverviewKpis;
+  current: IOverviewPeriodTotals;
+  previous: IOverviewPeriodTotals;
+  rangeLabel: string;
+}
+
+/**
+ * The four numbers an executive reads first: money and volume for the
+ * selected range, plus what's currently in flight. Revenue and cargo carry a
+ * real vs-prior-period delta; the two workflow snapshots don't, because
+ * "active bookings/contracts" is a point-in-time gauge, not a period total —
+ * showing a delta for it would mean inventing a comparison that isn't real.
+ */
+export function OverviewHeroKpis({ kpis, current, previous, rangeLabel }: OverviewHeroKpisProps) {
+  const items: KpiItem[] = [
+    {
+      label: `Revenue (${rangeLabel})`,
+      value: <CountUp value={current.revenueEtb} format={(n) => formatCurrency(n, "ETB")} />,
+      hint: formatCurrency(current.revenueUsd, "USD"),
+      icon: Banknote,
+      color: "yellow",
+      delta: pctDelta(current.revenueEtb, previous.revenueEtb),
+    },
+    {
+      label: "Cargo moved",
+      value: <CountUp value={current.tons} format={(n) => `${Math.round(n).toLocaleString()} t`} />,
+      icon: Package,
+      color: "edr-green",
+      delta: pctDelta(current.tons, previous.tons),
+    },
+    {
+      label: "Active bookings",
+      value: <CountUp value={kpis.bookings.totalActive} />,
+      icon: FileText,
+      color: "edr-green",
+    },
+    {
+      label: "Active contracts",
+      value: <CountUp value={kpis.contracts.totalActive} />,
+      icon: FileSignature,
+      color: "edr-green",
+    },
+  ];
+
+  return <KpiStrip items={items} />;
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewNetworkCard.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewNetworkCard.tsx
new file mode 100644
index 000000000..57a1a1fdc
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewNetworkCard.tsx
@@ -0,0 +1,88 @@
+import {
+  CalendarClock,
+  Container as ContainerIcon,
+  Send,
+  Train,
+  TrainFront,
+} from "lucide-react";
+import { Group, SimpleGrid, Stack, Text } from "@mantine/core";
+
+import { MiniRing } from "@/components/common/MiniGraph";
+import type { IOverviewOperationsKpis } from "@/types/overview";
+import { CountUp } from "./CountUp";
+import { SummaryCard } from "./SummaryCard";
+
+const STATS: Array<{
+  key: keyof IOverviewOperationsKpis;
+  label: string;
+  icon: typeof Train;
+}> = [
+  { key: "trainsActive", label: "Trains active", icon: Train },
+  { key: "dispatchedToday", label: "Dispatched today", icon: Send },
+  { key: "schedulesUpcoming", label: "Upcoming departures", icon: CalendarClock },
+  { key: "containersInTransit", label: "Containers in transit", icon: ContainerIcon },
+];
+
+/** Network snapshot: four operational stats plus real wagon-utilization (available / total), not a decorative gauge. */
+export function OverviewNetworkCard({ kpis }: { kpis: IOverviewOperationsKpis }) {
+  const utilizationPct = kpis.wagonsTotal > 0 ? (kpis.wagonsAvailable / kpis.wagonsTotal) * 100 : null;
+
+  return (
+    <SummaryCard
+      icon={TrainFront}
+      accent="edr-green"
+      title="Network"
+      subtitle="Fleet and movement, right now"
+      to="/dashboard/overview/fleet"
+      action={
+        <Text size="xs" fw={600} c="edr-green" style={{ whiteSpace: "nowrap" }}>
+          View fleet →
+        </Text>
+      }
+    >
+      <Stack gap="sm">
+        <Group align="center" gap="lg" className="ov-inset" p={14} wrap="nowrap">
+          <MiniRing pct={utilizationPct} accent="emerald" size={76} stroke={8}>
+            <Text size="16px" fw={800} lh={1}>
+              {utilizationPct != null ? `${Math.round(utilizationPct)}%` : "—"}
+            </Text>
+          </MiniRing>
+          <Stack gap={2}>
+            <Text size="xs" fw={700} tt="uppercase" c="dimmed" style={{ letterSpacing: 0.3 }}>
+              Wagons available
+            </Text>
+            <Text fw={800} fz={22} lh={1.1}>
+              {kpis.wagonsAvailable.toLocaleString()}
+              <Text component="span" fz="sm" fw={600} c="dimmed">
+                {" "}
+                / {kpis.wagonsTotal.toLocaleString()}
+              </Text>
+            </Text>
+          </Stack>
+        </Group>
+
+        <SimpleGrid cols={2} spacing="sm">
+          {STATS.map((stat) => {
+            const Icon = stat.icon;
+            return (
+              <Group key={stat.label} gap={10} wrap="nowrap" className="ov-inset" p={12}>
+                <Icon
+                  size={18}
+                  style={{ flexShrink: 0, color: "var(--mantine-color-edr-green-6)" }}
+                />
+                <Stack gap={0} style={{ minWidth: 0 }}>
+                  <Text fw={800} fz="lg" lh={1.15}>
+                    <CountUp value={kpis[stat.key]} />
+                  </Text>
+                  <Text size="xs" c="dimmed" truncate>
+                    {stat.label}
+                  </Text>
+                </Stack>
+              </Group>
+            );
+          })}
+        </SimpleGrid>
+      </Stack>
+    </SummaryCard>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewPipelineFunnel.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewPipelineFunnel.tsx
new file mode 100644
index 000000000..f28540298
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewPipelineFunnel.tsx
@@ -0,0 +1,113 @@
+import { Filter } from "lucide-react";
+import { Link } from "react-router-dom";
+import { Badge, Stack, Text } from "@mantine/core";
+
+import { BOOKING_LIST_TABS } from "@/features/bookings/booking-status.config";
+import type { IOverviewPipelineCount } from "@/types/overview";
+import { SummaryCard } from "./SummaryCard";
+
+/** Sequential green ramp from the theme's own edr-green scale — rising intensity as bookings progress through the pipeline. */
+const RAMP_SHADES = [3, 4, 5, 5, 6, 6, 7, 8, 9];
+
+interface OverviewPipelineFunnelProps {
+  data: IOverviewPipelineCount[];
+}
+
+/** Booking pipeline by stage, in workflow order. Each row deep-links to the exact statuses it represents. */
+export function OverviewPipelineFunnel({ data }: OverviewPipelineFunnelProps) {
+  const rows = data
+    .map((item) => ({
+      ...item,
+      tab: BOOKING_LIST_TABS.find((t) => t.key === item.stage),
+    }))
+    .filter((row) => row.tab);
+  const maxCount = Math.max(1, ...rows.map((r) => r.count));
+  const total = rows.reduce((sum, r) => sum + r.count, 0);
+  const hasData = total > 0;
+
+  return (
+    <SummaryCard
+      icon={Filter}
+      accent="edr-green"
+      title="Booking pipeline"
+      subtitle="Every row opens the exact filtered list"
+      action={
+        hasData ? (
+          <Badge variant="light" color="edr-green" size="sm" style={{ textTransform: "none" }}>
+            {total.toLocaleString()} in pipeline
+          </Badge>
+        ) : null
+      }
+    >
+      {!hasData ? (
+        <Text size="sm" c="dimmed" ta="center" py="xl">
+          No bookings in pipeline
+        </Text>
+      ) : (
+        <Stack gap={4}>
+          {rows.map((row, index) => {
+            const statuses = row.tab?.statuses;
+            const href = statuses?.length
+              ? `/dashboard/booking-requests?statuses=${statuses.join(",")}`
+              : "/dashboard/booking-requests";
+            const shade = RAMP_SHADES[Math.min(index, RAMP_SHADES.length - 1)];
+
+            return (
+              <Link
+                key={row.stage}
+                to={href}
+                className="ov-row"
+                style={{
+                  display: "flex",
+                  alignItems: "center",
+                  gap: 12,
+                  textDecoration: "none",
+                  padding: "7px 10px",
+                }}
+              >
+                <Text size="sm" fw={500} c="edr-text" style={{ width: 140, flexShrink: 0 }} truncate>
+                  {row.tab?.label ?? row.stage}
+                </Text>
+                <div
+                  style={{
+                    flex: 1,
+                    height: 20,
+                    borderRadius: 999,
+                    background: "var(--mantine-color-gray-1)",
+                    overflow: "hidden",
+                  }}
+                >
+                  <div
+                    style={{
+                      width: `${(row.count / maxCount) * 100}%`,
+                      height: "100%",
+                      borderRadius: 999,
+                      background: `linear-gradient(90deg, var(--mantine-color-edr-green-${Math.max(shade - 2, 1)}), var(--mantine-color-edr-green-${shade}))`,
+                      transition: "width 300ms ease",
+                    }}
+                  />
+                </div>
+                <Text
+                  size="sm"
+                  fw={700}
+                  ta="center"
+                  style={{
+                    minWidth: 44,
+                    flexShrink: 0,
+                    background: "var(--mantine-color-gray-0)",
+                    border: "1px solid var(--mantine-color-gray-2)",
+                    borderRadius: 999,
+                    padding: "1px 8px",
+                    fontVariantNumeric: "tabular-nums",
+                  }}
+                >
+                  {row.count}
+                </Text>
+              </Link>
+            );
+          })}
+        </Stack>
+      )}
+    </SummaryCard>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueMix.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueMix.tsx
new file mode 100644
index 000000000..c2839350b
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueMix.tsx
@@ -0,0 +1,143 @@
+import { PieChart } from "lucide-react";
+import { Stack, Text } from "@mantine/core";
+
+import type { IOverviewRevenueSlice } from "@/types/overview";
+import { DIRECTION_COLORS, FLOW_FALLBACK_COLOR, FREIGHT_TYPE_COLORS } from "./flow-colors";
+import { CountUp } from "./CountUp";
+import { SummaryCard } from "./SummaryCard";
+
+function formatEtb(amount: number) {
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "ETB",
+    maximumFractionDigits: 0,
+  }).format(amount);
+}
+
+const DIRECTION_LABELS: Record<string, string> = {
+  IMPORT: "Import",
+  EXPORT: "Export",
+  DOMESTIC: "Domestic",
+};
+
+const FREIGHT_TYPE_LABELS: Record<string, string> = {
+  CONTAINER: "Container",
+  BULK: "Bulk",
+};
+
+/** One breakdown's proportion bar + legend, sized by ETB revenue (no FX rate exists to fold USD in). */
+function MixRow({
+  title,
+  slices,
+  labels,
+  colors,
+}: {
+  title: string;
+  slices: IOverviewRevenueSlice[];
+  labels: Record<string, string>;
+  colors: Record<string, string>;
+}) {
+  const total = slices.reduce((sum, s) => sum + s.amountEtb, 0);
+
+  return (
+    <Stack gap={8} className="ov-inset" p={12}>
+      <Text size="xs" fw={700} tt="uppercase" c="dimmed" style={{ letterSpacing: 0.3 }}>
+        {title}
+      </Text>
+      {total === 0 ? (
+        <Text size="sm" c="dimmed">
+          No revenue in this period
+        </Text>
+      ) : (
+        <>
+          <div
+            style={{
+              display: "flex",
+              height: 12,
+              borderRadius: 999,
+              overflow: "hidden",
+              gap: 2,
+            }}
+          >
+            {slices
+              .filter((s) => s.amountEtb > 0)
+              .map((s) => (
+                <div
+                  key={s.label}
+                  style={{
+                    width: `${(s.amountEtb / total) * 100}%`,
+                    background: colors[s.label] ?? FLOW_FALLBACK_COLOR,
+                    borderRadius: 999,
+                  }}
+                />
+              ))}
+          </div>
+          <Stack gap={4}>
+            {slices
+              .filter((s) => s.amountEtb > 0)
+              .map((s) => (
+                <div
+                  key={s.label}
+                  style={{ display: "flex", alignItems: "center", gap: 8, fontSize: 12 }}
+                >
+                  <span
+                    style={{
+                      width: 8,
+                      height: 8,
+                      borderRadius: 999,
+                      flexShrink: 0,
+                      background: colors[s.label] ?? FLOW_FALLBACK_COLOR,
+                    }}
+                  />
+                  <span style={{ flex: 1, color: "var(--mantine-color-edr-muted-6)" }}>
+                    {labels[s.label] ?? s.label}
+                  </span>
+                  <span style={{ fontWeight: 600 }}>{formatEtb(s.amountEtb)}</span>
+                  <span style={{ color: "var(--mantine-color-edr-muted-6)", minWidth: 32, textAlign: "right" }}>
+                    {Math.round((s.amountEtb / total) * 100)}%
+                  </span>
+                </div>
+              ))}
+          </Stack>
+        </>
+      )}
+    </Stack>
+  );
+}
+
+interface OverviewRevenueMixProps {
+  byDirection: IOverviewRevenueSlice[];
+  byFreightType: IOverviewRevenueSlice[];
+}
+
+/** ETB revenue split two ways — trade direction and freight type — anchored by the range total. */
+export function OverviewRevenueMix({ byDirection, byFreightType }: OverviewRevenueMixProps) {
+  const total = byDirection.reduce((sum, s) => sum + s.amountEtb, 0);
+
+  return (
+    <SummaryCard icon={PieChart} accent="yellow" title="Revenue mix" subtitle="ETB, selected range">
+      <Stack gap="md">
+        <div>
+          <Text fw={800} fz={24} lh={1.1} style={{ letterSpacing: "-0.02em" }}>
+            <CountUp value={total} format={formatEtb} />
+          </Text>
+          <Text size="xs" c="dimmed">
+            attributed to a trade direction
+          </Text>
+        </div>
+        <MixRow
+          title="By trade direction"
+          slices={byDirection}
+          labels={DIRECTION_LABELS}
+          colors={DIRECTION_COLORS}
+        />
+        <MixRow
+          title="By freight type"
+          slices={byFreightType}
+          labels={FREIGHT_TYPE_LABELS}
+          colors={FREIGHT_TYPE_COLORS}
+        />
+      </Stack>
+    </SummaryCard>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueVolumeChart.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueVolumeChart.tsx
new file mode 100644
index 000000000..12b20a45e
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueVolumeChart.tsx
@@ -0,0 +1,172 @@
+import {
+  Area,
+  Bar,
+  CartesianGrid,
+  ComposedChart,
+  Line,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from "recharts";
+import { ChartColumnBig } from "lucide-react";
+import { Group, Text } from "@mantine/core";
+
+import type { IOverviewPaymentTrendPoint, IOverviewTrendPoint } from "@/types/overview";
+import { overviewChartColors } from "../overview.styles";
+import { chartAxisTick, chartGridStroke, chartTooltipStyle } from "./chart-style";
+import { mergeTrend } from "./mergeTrend";
+import { SummaryCard } from "./SummaryCard";
+
+function formatDateLabel(date: string) {
+  return new Date(`${date}T00:00:00`).toLocaleDateString(undefined, {
+    month: "short",
+    day: "numeric",
+  });
+}
+
+function formatEtb(amount: number) {
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "ETB",
+    maximumFractionDigits: 0,
+  }).format(amount);
+}
+
+const compact = new Intl.NumberFormat("en-US", { notation: "compact" });
+
+/** Dot-and-label legend row rendered in the card header instead of recharts' default. */
+function LegendDot({ color, dashed, label }: { color: string; dashed?: boolean; label: string }) {
+  return (
+    <Group gap={5} wrap="nowrap">
+      {dashed ? (
+        <svg width={14} height={4} aria-hidden>
+          <line x1={0} y1={2} x2={14} y2={2} stroke={color} strokeWidth={2} strokeDasharray="3 2" />
+        </svg>
+      ) : (
+        <span style={{ width: 8, height: 8, borderRadius: 999, background: color }} />
+      )}
+      <Text size="xs" c="dimmed">
+        {label}
+      </Text>
+    </Group>
+  );
+}
+
+interface OverviewRevenueVolumeChartProps {
+  bookingTrend: IOverviewTrendPoint[];
+  paymentTrend: IOverviewPaymentTrendPoint[];
+  previousPaymentTrend: IOverviewPaymentTrendPoint[];
+  rangeDays: number;
+}
+
+/**
+ * Volume and money in one read: bars are bookings created per day, the gold
+ * area is ETB revenue per day, and the dashed ghost line is the preceding
+ * period's revenue shifted onto the same axis — "are we pacing ahead of last
+ * period" at a glance.
+ */
+export function OverviewRevenueVolumeChart({
+  bookingTrend,
+  paymentTrend,
+  previousPaymentTrend,
+  rangeDays,
+}: OverviewRevenueVolumeChartProps) {
+  const data = mergeTrend(bookingTrend, paymentTrend, previousPaymentTrend, rangeDays);
+  const hasData = data.some((point) => point.bookings > 0 || point.revenueEtb > 0);
+
+  return (
+    <SummaryCard
+      icon={ChartColumnBig}
+      accent="yellow"
+      title="Bookings & revenue"
+      subtitle="Daily volume vs ETB revenue"
+      action={
+        <Group gap="md" wrap="nowrap">
+          <LegendDot color="var(--mantine-color-edr-green-4)" label="Bookings" />
+          <LegendDot color={overviewChartColors.primary} label="Revenue" />
+          <LegendDot color="var(--mantine-color-gray-5)" dashed label="Prev period" />
+        </Group>
+      }
+    >
+      {!hasData ? (
+          <Text size="sm" c="dimmed" ta="center" py="xl">
+            No activity in this period
+          </Text>
+        ) : (
+          <ResponsiveContainer width="100%" height={280}>
+            <ComposedChart data={data} margin={{ top: 8, right: 4, left: 0, bottom: 0 }}>
+              <defs>
+                <linearGradient id="ov-revenue-fill" x1="0" y1="0" x2="0" y2="1">
+                  <stop offset="0%" stopColor={overviewChartColors.primary} stopOpacity={0.22} />
+                  <stop offset="100%" stopColor={overviewChartColors.primary} stopOpacity={0} />
+                </linearGradient>
+              </defs>
+              <CartesianGrid vertical={false} stroke={chartGridStroke} />
+              <XAxis
+                dataKey="date"
+                tickFormatter={formatDateLabel}
+                tick={chartAxisTick}
+                axisLine={false}
+                tickLine={false}
+                minTickGap={24}
+              />
+              <YAxis
+                yAxisId="bookings"
+                allowDecimals={false}
+                tick={chartAxisTick}
+                axisLine={false}
+                tickLine={false}
+                width={32}
+              />
+              <YAxis
+                yAxisId="revenue"
+                orientation="right"
+                tickFormatter={(value) => compact.format(Number(value))}
+                tick={chartAxisTick}
+                axisLine={false}
+                tickLine={false}
+                width={44}
+              />
+              <Tooltip
+                labelFormatter={(value) => formatDateLabel(String(value))}
+                formatter={(value, name) =>
+                  name === "Bookings" ? [value, name] : [formatEtb(Number(value)), name]
+                }
+                contentStyle={chartTooltipStyle}
+              />
+              <Bar
+                yAxisId="bookings"
+                dataKey="bookings"
+                name="Bookings"
+                fill="var(--mantine-color-edr-green-4)"
+                radius={[5, 5, 0, 0]}
+                barSize={14}
+              />
+              <Line
+                yAxisId="revenue"
+                type="monotone"
+                dataKey="prevRevenueEtb"
+                name="Prev period"
+                stroke="var(--mantine-color-gray-5)"
+                strokeWidth={1.5}
+                strokeDasharray="5 4"
+                dot={false}
+              />
+              <Area
+                yAxisId="revenue"
+                type="monotone"
+                dataKey="revenueEtb"
+                name="Revenue"
+                stroke={overviewChartColors.primary}
+                strokeWidth={2.5}
+                fill="url(#ov-revenue-fill)"
+                dot={false}
+                activeDot={{ r: 4 }}
+              />
+            </ComposedChart>
+        </ResponsiveContainer>
+      )}
+    </SummaryCard>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewSankeyFlow.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewSankeyFlow.tsx
new file mode 100644
index 000000000..1e4597ee9
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewSankeyFlow.tsx
@@ -0,0 +1,170 @@
+import { Waypoints } from "lucide-react";
+import { ResponsiveContainer, Sankey, Tooltip, type SankeyLinkProps } from "recharts";
+import { Text } from "@mantine/core";
+
+import type { IOverviewRevenueFlow } from "@/types/overview";
+import { chartTooltipStyle } from "./chart-style";
+import { SummaryCard } from "./SummaryCard";
+import {
+  DIRECTION_COLORS,
+  FLOW_FALLBACK_COLOR,
+  FLOW_LABELS,
+  FREIGHT_TYPE_COLORS,
+} from "./flow-colors";
+
+function formatEtb(amount: number) {
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "ETB",
+    maximumFractionDigits: 0,
+  }).format(amount);
+}
+
+interface SankeyNodeDatum {
+  name: string;
+  key: string;
+  color: string;
+}
+
+/** Build recharts Sankey data: direction nodes on the left, freight types on the right. */
+function toSankeyData(flows: IOverviewRevenueFlow[]) {
+  const active = flows.filter((f) => f.amountEtb > 0);
+  const nodes: SankeyNodeDatum[] = [];
+  const indexByKey = new Map<string, number>();
+  const nodeIndex = (key: string, color: string) => {
+    const existing = indexByKey.get(key);
+    if (existing != null) return existing;
+    nodes.push({ name: FLOW_LABELS[key] ?? key, key, color });
+    indexByKey.set(key, nodes.length - 1);
+    return nodes.length - 1;
+  };
+
+  // Register directions first so they all land on the left column.
+  for (const flow of active) {
+    nodeIndex(flow.direction, DIRECTION_COLORS[flow.direction] ?? FLOW_FALLBACK_COLOR);
+  }
+  const links = active.map((flow) => ({
+    source: indexByKey.get(flow.direction)!,
+    target: nodeIndex(
+      flow.freightType,
+      FREIGHT_TYPE_COLORS[flow.freightType] ?? FLOW_FALLBACK_COLOR,
+    ),
+    value: flow.amountEtb,
+  }));
+
+  return { nodes, links };
+}
+
+function FlowNode({
+  x,
+  y,
+  width,
+  height,
+  index,
+  payload,
+}: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  index: number;
+  payload: { name?: string; value?: number; color?: string };
+}) {
+  // Labels sit to the right of every bar: the right margin reserves room for
+  // the last column, and the pale ribbons stay readable under the left one.
+  return (
+    <g key={`node-${index}`}>
+      <rect x={x} y={y} width={width} height={height} fill={payload.color} rx={3} />
+      <text
+        x={x + width + 8}
+        y={y + height / 2 - 6}
+        textAnchor="start"
+        dominantBaseline="central"
+        fontSize={12}
+        fontWeight={600}
+        fill="#1f2937"
+      >
+        {payload.name}
+      </text>
+      <text
+        x={x + width + 8}
+        y={y + height / 2 + 9}
+        textAnchor="start"
+        dominantBaseline="central"
+        fontSize={11}
+        fill="var(--mantine-color-gray-6)"
+      >
+        {formatEtb(payload.value ?? 0)}
+      </text>
+    </g>
+  );
+}
+
+/** Ribbon tinted by its source direction — the corridor keeps its color across the chart. */
+function FlowLink({
+  sourceX,
+  targetX,
+  sourceY,
+  targetY,
+  sourceControlX,
+  targetControlX,
+  linkWidth,
+  index,
+  payload,
+}: SankeyLinkProps) {
+  // Custom node fields (color) ride along on the layout node recharts hands back.
+  const source = payload.source as { color?: string };
+  return (
+    <path
+      key={`link-${index}`}
+      d={`M${sourceX},${sourceY} C${sourceControlX},${sourceY} ${targetControlX},${targetY} ${targetX},${targetY}`}
+      fill="none"
+      stroke={source.color ?? FLOW_FALLBACK_COLOR}
+      strokeOpacity={0.3}
+      strokeWidth={linkWidth}
+    />
+  );
+}
+
+interface OverviewSankeyFlowProps {
+  flows: IOverviewRevenueFlow[];
+}
+
+/**
+ * Where the money runs: ETB revenue as ribbons from trade direction to
+ * freight type. Ribbon thickness is proportional to revenue, so the biggest
+ * corridor is unmissable.
+ */
+export function OverviewSankeyFlow({ flows }: OverviewSankeyFlowProps) {
+  const data = toSankeyData(flows);
+
+  return (
+    <SummaryCard
+      icon={Waypoints}
+      accent="sky"
+      title="Revenue flow"
+      subtitle="Trade direction → freight type, sized by ETB revenue"
+    >
+      {data.links.length === 0 ? (
+        <Text size="sm" c="dimmed" ta="center" py="xl">
+          No revenue in this period
+        </Text>
+      ) : (
+        <ResponsiveContainer width="100%" height={252}>
+          <Sankey
+            data={data}
+            node={FlowNode}
+            link={FlowLink}
+            nodePadding={32}
+            margin={{ top: 20, right: 96, bottom: 12, left: 4 }}
+          >
+            <Tooltip
+              formatter={(value) => formatEtb(Number(value))}
+              contentStyle={chartTooltipStyle}
+            />
+          </Sankey>
+        </ResponsiveContainer>
+      )}
+    </SummaryCard>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/SummaryCard.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/SummaryCard.tsx
new file mode 100644
index 000000000..cfd022fe9
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/SummaryCard.tsx
@@ -0,0 +1,65 @@
+import type { LucideIcon } from "lucide-react";
+import { Group, Stack, Text, ThemeIcon } from "@mantine/core";
+import type { ElementType, ReactNode } from "react";
+import { Link } from "react-router-dom";
+
+import "./overview-summary.css";
+
+interface SummaryCardProps {
+  icon: LucideIcon;
+  /** Mantine color for the icon chip. */
+  accent?: string;
+  title: string;
+  subtitle?: string;
+  /** Right side of the header — a legend, badge, or link. */
+  action?: ReactNode;
+  /** Makes the whole card a link (adds the hover lift). */
+  to?: string;
+  minHeight?: number;
+  children: ReactNode;
+}
+
+/**
+ * Shared chrome for every overview card: soft gradient surface, layered
+ * shadow, icon-chip header with title/subtitle, optional action slot.
+ * One look for the whole page instead of eight flat white boxes.
+ */
+export function SummaryCard({
+  icon: Icon,
+  accent = "edr-green",
+  title,
+  subtitle,
+  action,
+  to,
+  minHeight = 340,
+  children,
+}: SummaryCardProps) {
+  const Root: ElementType = to ? Link : "div";
+  return (
+    <Root
+      {...(to ? { to } : {})}
+      className={to ? "ov-card ov-card--link" : "ov-card"}
+      style={{ minHeight }}
+    >
+      <Group justify="space-between" align="flex-start" wrap="nowrap" mb="md" gap="sm">
+        <Group gap={12} wrap="nowrap" style={{ minWidth: 0 }}>
+          <ThemeIcon variant="light" color={accent} size={38} radius={12} style={{ flexShrink: 0 }}>
+            <Icon size={20} />
+          </ThemeIcon>
+          <Stack gap={1} style={{ minWidth: 0 }}>
+            <Text fw={700} lh={1.25} c="edr-text" truncate>
+              {title}
+            </Text>
+            {subtitle ? (
+              <Text size="xs" c="dimmed" truncate>
+                {subtitle}
+              </Text>
+            ) : null}
+          </Stack>
+        </Group>
+        {action}
+      </Group>
+      {children}
+    </Root>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/chart-style.ts b/apps/edr-freight-web/backoffice/src/components/overview/summary/chart-style.ts
new file mode 100644
index 000000000..9f7dbae8d
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/chart-style.ts
@@ -0,0 +1,14 @@
+import type { CSSProperties } from "react";
+
+/** Shared recharts styling for the overview summary charts. */
+export const chartGridStroke = "#EEF1F5";
+
+export const chartAxisTick = { fontSize: 11, fill: "#8fa0b2" } as const;
+
+export const chartTooltipStyle: CSSProperties = {
+  borderRadius: 12,
+  border: "1px solid #EEF1F5",
+  boxShadow: "0 8px 24px rgba(16, 32, 47, 0.1)",
+  fontSize: 12,
+  padding: "8px 12px",
+};
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/flow-colors.ts b/apps/edr-freight-web/backoffice/src/components/overview/summary/flow-colors.ts
new file mode 100644
index 000000000..f3c7a2ace
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/flow-colors.ts
@@ -0,0 +1,25 @@
+/**
+ * Fixed colors + labels for trade directions and freight types, shared by the
+ * revenue mix and Sankey so the same entity is always the same color (and
+ * matches the operations departure chart's direction hexes).
+ */
+export const DIRECTION_COLORS: Record<string, string> = {
+  EXPORT: "#D98A0B",
+  IMPORT: "#0369a1",
+  DOMESTIC: "#7c3aed",
+};
+
+export const FREIGHT_TYPE_COLORS: Record<string, string> = {
+  CONTAINER: "#1B9E7A",
+  BULK: "#34D9AE",
+};
+
+export const FLOW_LABELS: Record<string, string> = {
+  IMPORT: "Import",
+  EXPORT: "Export",
+  DOMESTIC: "Domestic",
+  CONTAINER: "Container",
+  BULK: "Bulk",
+};
+
+export const FLOW_FALLBACK_COLOR = "#94a3b8";
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/mergeTrend.test.ts b/apps/edr-freight-web/backoffice/src/components/overview/summary/mergeTrend.test.ts
new file mode 100644
index 000000000..369b19237
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/mergeTrend.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+
+import { mergeTrend } from "./mergeTrend";
+
+describe("mergeTrend", () => {
+  it("unions dates from both trends, zero-filling the side that has no row", () => {
+    const result = mergeTrend(
+      [
+        { date: "2026-06-01", count: 3 },
+        { date: "2026-06-02", count: 5 },
+      ],
+      [{ date: "2026-06-02", amountEtb: 1000, amountUsd: 0 }],
+    );
+
+    expect(result).toEqual([
+      { date: "2026-06-01", bookings: 3, revenueEtb: 0 },
+      { date: "2026-06-02", bookings: 5, revenueEtb: 1000 },
+    ]);
+  });
+
+  it("sorts chronologically regardless of input order", () => {
+    const result = mergeTrend(
+      [{ date: "2026-06-03", count: 1 }],
+      [{ date: "2026-06-01", amountEtb: 500, amountUsd: 0 }],
+    );
+
+    expect(result.map((p) => p.date)).toEqual(["2026-06-01", "2026-06-03"]);
+  });
+
+  it("returns an empty series when both trends are empty", () => {
+    expect(mergeTrend([], [])).toEqual([]);
+  });
+
+  it("shifts the previous period forward so day N lands on day N of the current window", () => {
+    const result = mergeTrend(
+      [{ date: "2026-06-08", count: 2 }],
+      [],
+      [
+        // 7d range: 2026-06-01 + 7 = 2026-06-08 (existing row), 06-02 + 7 = 06-09 (new row)
+        { date: "2026-06-01", amountEtb: 400, amountUsd: 0 },
+        { date: "2026-06-02", amountEtb: 250, amountUsd: 0 },
+      ],
+      7,
+    );
+
+    expect(result).toEqual([
+      { date: "2026-06-08", bookings: 2, revenueEtb: 0, prevRevenueEtb: 400 },
+      { date: "2026-06-09", bookings: 0, revenueEtb: 0, prevRevenueEtb: 250 },
+    ]);
+  });
+
+  it("shifts across a month boundary without timezone drift", () => {
+    const result = mergeTrend([], [], [{ date: "2026-05-28", amountEtb: 100, amountUsd: 0 }], 7);
+    expect(result[0].date).toBe("2026-06-04");
+  });
+});
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/mergeTrend.ts b/apps/edr-freight-web/backoffice/src/components/overview/summary/mergeTrend.ts
new file mode 100644
index 000000000..0ddc0d705
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/mergeTrend.ts
@@ -0,0 +1,63 @@
+import type { IOverviewPaymentTrendPoint, IOverviewTrendPoint } from "@/types/overview";
+
+export interface RevenueVolumePoint {
+  date: string;
+  bookings: number;
+  revenueEtb: number;
+  /** Same-offset day of the preceding period — the ghost comparison line. */
+  prevRevenueEtb?: number;
+}
+
+/** `date` (YYYY-MM-DD) plus `days` days, in UTC so no DST/timezone drift. */
+export function shiftDate(date: string, days: number): string {
+  const parsed = new Date(`${date}T00:00:00Z`);
+  parsed.setUTCDate(parsed.getUTCDate() + days);
+  return parsed.toISOString().slice(0, 10);
+}
+
+/**
+ * Merge the booking-count trend and the payment trend into one date-keyed
+ * series for the combined volume/revenue chart. Both trends only carry rows
+ * for days with activity (no zero-filled gaps), so this unions the dates
+ * rather than assuming they line up.
+ *
+ * When the previous period's payment trend is provided, each of its days is
+ * shifted forward by `shiftDays` (the range length) so day N of the prior
+ * window lands on day N of the current one, and lands in `prevRevenueEtb`.
+ */
+export function mergeTrend(
+  bookingTrend: IOverviewTrendPoint[],
+  paymentTrend: IOverviewPaymentTrendPoint[],
+  previousPaymentTrend: IOverviewPaymentTrendPoint[] = [],
+  shiftDays = 0,
+): RevenueVolumePoint[] {
+  const byDate = new Map<string, RevenueVolumePoint>();
+
+  for (const point of bookingTrend) {
+    byDate.set(point.date, { date: point.date, bookings: point.count, revenueEtb: 0 });
+  }
+  for (const point of paymentTrend) {
+    const existing = byDate.get(point.date);
+    if (existing) {
+      existing.revenueEtb = point.amountEtb;
+    } else {
+      byDate.set(point.date, { date: point.date, bookings: 0, revenueEtb: point.amountEtb });
+    }
+  }
+  for (const point of previousPaymentTrend) {
+    const date = shiftDate(point.date, shiftDays);
+    const existing = byDate.get(date);
+    if (existing) {
+      existing.prevRevenueEtb = point.amountEtb;
+    } else {
+      byDate.set(date, {
+        date,
+        bookings: 0,
+        revenueEtb: 0,
+        prevRevenueEtb: point.amountEtb,
+      });
+    }
+  }
+
+  return [...byDate.values()].sort((a, b) => a.date.localeCompare(b.date));
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/overview-summary.css b/apps/edr-freight-web/backoffice/src/components/overview/summary/overview-summary.css
new file mode 100644
index 000000000..0391010b8
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/overview-summary.css
@@ -0,0 +1,65 @@
+/* Staggered fade-up entrance for the overview bands. Delay is set inline per
+   band; disabled entirely for reduced-motion users. */
+.ov-band {
+  animation: ov-rise 420ms ease-out both;
+}
+
+@keyframes ov-rise {
+  from {
+    opacity: 0;
+    transform: translateY(14px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ov-band {
+    animation: none;
+  }
+}
+
+/* ---- Shared card chrome (SummaryCard) ---- */
+.ov-card {
+  display: block;
+  height: 100%;
+  background: linear-gradient(180deg, #ffffff 0%, #fbfdfc 100%);
+  border: 1px solid var(--mantine-color-edr-border-0);
+  border-radius: 20px;
+  padding: 20px;
+  color: inherit;
+  text-decoration: none;
+  box-shadow:
+    0 1px 2px rgba(16, 32, 47, 0.04),
+    0 12px 32px -18px rgba(16, 32, 47, 0.14);
+  transition:
+    box-shadow 180ms ease,
+    transform 180ms ease,
+    border-color 180ms ease;
+}
+/* The lift is a click affordance — only linked cards get it. */
+.ov-card--link:hover {
+  box-shadow:
+    0 2px 4px rgba(16, 32, 47, 0.05),
+    0 20px 44px -18px rgba(16, 32, 47, 0.2);
+  border-color: var(--mantine-color-edr-green-2);
+  transform: translateY(-2px);
+}
+
+/* Soft inset panel for grouping content inside a card. */
+.ov-inset {
+  background: var(--mantine-color-gray-0);
+  border: 1px solid var(--mantine-color-gray-1);
+  border-radius: 14px;
+}
+
+/* Interactive list row inside a card. */
+.ov-row {
+  border-radius: 12px;
+  transition: background 140ms ease;
+}
+.ov-row:hover {
+  background: var(--mantine-color-gray-0);
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewBookingsTabPanel.tsx b/apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewBookingsTabPanel.tsx
index cacba63e1..696741873 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewBookingsTabPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewBookingsTabPanel.tsx
@@ -59,12 +59,6 @@ export function OverviewBookingsTabPanel({ data }: OverviewBookingsTabPanelProps
             accent: "sky",
             hint: "Pending sign-off",
           },
-          {
-            label: "Submitted today",
-            value: data.kpis.submittedToday,
-            icon: FileText,
-            hint: "New since midnight",
-          },
         ]}
       />
 
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewContractsTabPanel.tsx b/apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewContractsTabPanel.tsx
index e185f40d2..9265da37d 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewContractsTabPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewContractsTabPanel.tsx
@@ -76,12 +76,6 @@ export function OverviewContractsTabPanel({
             accent: "rose",
             hint: "Customs / documents",
           },
-          {
-            label: "Created today",
-            value: data.kpis.createdToday,
-            icon: FileSignature,
-            hint: "New since midnight",
-          },
         ]}
       />
 
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewOperationsTabPanel.tsx b/apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewOperationsTabPanel.tsx
index 675a81b32..b335ccf9c 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewOperationsTabPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewOperationsTabPanel.tsx
@@ -1,5 +1,4 @@
 import {
-  Box,
   CalendarClock,
   Container as ContainerIcon,
   Send,
@@ -78,11 +77,6 @@ export function OverviewOperationsTabPanel({ data }: OverviewOperationsTabPanelP
             value: data.kpis.containersInTransit,
             icon: ContainerIcon,
           },
-          {
-            label: "Cargoes loaded",
-            value: data.kpis.cargoesLoaded,
-            icon: Box,
-          },
         ]}
       />
 
diff --git a/apps/edr-freight-web/backoffice/src/components/page/KpiStrip.tsx b/apps/edr-freight-web/backoffice/src/components/page/KpiStrip.tsx
index 6b90d6c8a..01a80db61 100644
--- a/apps/edr-freight-web/backoffice/src/components/page/KpiStrip.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/page/KpiStrip.tsx
@@ -103,8 +103,16 @@ export function KpiStrip({ items, loading = false }: KpiStripProps) {
                         component="span"
                         fz="xs"
                         fw={700}
-                        c={item.delta > 0 ? "edr-green" : "red"}
-                        style={{ whiteSpace: "nowrap" }}
+                        c={item.delta > 0 ? "edr-green.7" : "red.7"}
+                        style={{
+                          whiteSpace: "nowrap",
+                          background:
+                            item.delta > 0
+                              ? "var(--mantine-color-edr-green-0)"
+                              : "var(--mantine-color-red-0)",
+                          borderRadius: 999,
+                          padding: "1px 7px",
+                        }}
                       >
                         {item.delta > 0 ? "▲" : "▼"}
                         {Math.abs(item.delta)}
diff --git a/apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewDomainPage.tsx b/apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewDomainPage.tsx
new file mode 100644
index 000000000..25ede8b4e
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewDomainPage.tsx
@@ -0,0 +1,145 @@
+import { useState } from "react";
+import { useParams } from "react-router-dom";
+import { AlertCircle, RefreshCw } from "lucide-react";
+import { ActionIcon, Alert, Button, Center, Loader, Paper, SegmentedControl, Skeleton, Stack } from "@mantine/core";
+
+import { PageContainer, PageHeader } from "@/components/page";
+import { OVERVIEW_DOMAINS } from "@/components/overview/overview-domains.config";
+import { OverviewBillingTabPanel } from "@/components/overview/tabs/OverviewBillingTabPanel";
+import { OverviewBookingsTabPanel } from "@/components/overview/tabs/OverviewBookingsTabPanel";
+import { OverviewContractsTabPanel } from "@/components/overview/tabs/OverviewContractsTabPanel";
+import { OverviewCustomersTabPanel } from "@/components/overview/tabs/OverviewCustomersTabPanel";
+import { OverviewFleetTabPanel } from "@/components/overview/tabs/OverviewFleetTabPanel";
+import { OverviewOperationsTabPanel } from "@/components/overview/tabs/OverviewOperationsTabPanel";
+import { OverviewStaffTabPanel } from "@/components/overview/tabs/OverviewStaffTabPanel";
+import {
+  useOverviewBillingTab,
+  useOverviewBookingsTab,
+  useOverviewContractsTab,
+  useOverviewCustomersTab,
+  useOverviewOperationsTab,
+  useOverviewStaffTab,
+} from "@/hooks/useOverview";
+import type { OverviewRange, OverviewTabKey } from "@/types/overview";
+
+const RANGE_OPTIONS = [
+  { label: "7 days", value: "7d" },
+  { label: "30 days", value: "30d" },
+  { label: "90 days", value: "90d" },
+];
+
+function DomainSkeleton() {
+  return (
+    <Stack gap="lg">
+      <Skeleton height={92} radius="lg" />
+      <Skeleton height={320} radius="lg" />
+      <Skeleton height={320} radius="lg" />
+    </Stack>
+  );
+}
+
+/**
+ * One domain's full depth — what used to be a tab panel on the overview page
+ * is now its own page, reached from that domain's "View all →" link. Same
+ * per-domain hooks and panel components as before; only the tab-switch
+ * wrapper (OverviewTabContent) is gone, replaced by a route param.
+ */
+export default function OverviewDomainPage() {
+  const { domain } = useParams<{ domain: OverviewTabKey }>();
+  const [range, setRange] = useState<OverviewRange>("30d");
+
+  const meta = OVERVIEW_DOMAINS.find((d) => d.key === domain);
+
+  const bookings = useOverviewBookingsTab(range, domain === "bookings");
+  const contracts = useOverviewContractsTab(range, domain === "contracts");
+  const billing = useOverviewBillingTab(range, domain === "billing");
+  // Fleet reuses the operations dataset — same query key, so switching between
+  // the two pages costs no extra fetch.
+  const operations = useOverviewOperationsTab(
+    range,
+    domain === "operations" || domain === "fleet",
+  );
+  const customers = useOverviewCustomersTab(range, domain === "customers");
+  const staff = useOverviewStaffTab(range, domain === "staff");
+
+  const query =
+    domain === "bookings"
+      ? bookings
+      : domain === "contracts"
+        ? contracts
+        : domain === "billing"
+          ? billing
+          : domain === "operations" || domain === "fleet"
+            ? operations
+            : domain === "customers"
+              ? customers
+              : staff;
+
+  const { isLoading, isError, refetch, isFetching } = query;
+
+  return (
+    <PageContainer>
+      <PageHeader
+        title={meta?.label ?? "Overview"}
+        subtitle={meta?.subtitle}
+        backTo="/dashboard/overview"
+        action={
+          <>
+            <SegmentedControl
+              value={range}
+              onChange={(value) => setRange(value as OverviewRange)}
+              data={RANGE_OPTIONS}
+              size="sm"
+              radius="lg"
+              color="edr-green"
+            />
+            <ActionIcon
+              variant="light"
+              color="edr-green"
+              size="lg"
+              radius="lg"
+              aria-label="Refresh"
+              onClick={() => void refetch()}
+              loading={isFetching && !isLoading}
+            >
+              <RefreshCw size={18} />
+            </ActionIcon>
+          </>
+        }
+      />
+
+      {isLoading ? (
+        <DomainSkeleton />
+      ) : isError || !query.data ? (
+        <Paper p="xl" radius="lg" withBorder>
+          <Alert icon={<AlertCircle size={16} />} color="red" title="Failed to load" variant="light">
+            <Stack gap="sm" align="flex-start">
+              <span>Could not load {meta?.label ?? "this"} metrics. Please try again.</span>
+              <Button size="xs" variant="light" color="red" onClick={() => void refetch()}>
+                Retry
+              </Button>
+            </Stack>
+          </Alert>
+        </Paper>
+      ) : (
+        <Stack gap="md" pos="relative">
+          {isFetching && (
+            <Center style={{ position: "absolute", top: 8, right: 8, zIndex: 2 }}>
+              <Loader size="sm" color="edr-green" />
+            </Center>
+          )}
+
+          {domain === "bookings" && bookings.data && <OverviewBookingsTabPanel data={bookings.data} />}
+          {domain === "contracts" && contracts.data && <OverviewContractsTabPanel data={contracts.data} />}
+          {domain === "billing" && billing.data && <OverviewBillingTabPanel data={billing.data} />}
+          {domain === "operations" && operations.data && (
+            <OverviewOperationsTabPanel data={operations.data} />
+          )}
+          {domain === "fleet" && operations.data && <OverviewFleetTabPanel data={operations.data} />}
+          {domain === "customers" && customers.data && <OverviewCustomersTabPanel data={customers.data} />}
+          {domain === "staff" && staff.data && <OverviewStaffTabPanel data={staff.data} />}
+        </Stack>
+      )}
+    </PageContainer>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewPage.tsx b/apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewPage.tsx
index 008149adb..aa29fa0cf 100644
--- a/apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewPage.tsx
@@ -1,141 +1,61 @@
 import { useState } from "react";
-import {
-  AlertCircle,
-  Banknote,
-  FileSignature,
-  FileText,
-  Train,
-  TrainFront,
-  UserCheck,
-  Users,
-} from "lucide-react";
-import {
-  Alert,
-  Badge,
-  Button,
-  Container,
-  Skeleton,
-  Stack,
-  Tabs,
-} from "@mantine/core";
+import { AlertCircle } from "lucide-react";
+import { Alert, Button, Grid, Skeleton, Stack, Text } from "@mantine/core";
 import { useQueryClient } from "@tanstack/react-query";
 
-import { useAuth } from "@/auth/useAuth";
-import { OverviewPageHeader } from "@/components/overview/OverviewPageHeader";
-import { OverviewTabContent } from "@/components/overview/OverviewTabContent";
-import "@/components/overview/overview.css";
+import { PageContainer } from "@/components/page";
+import { OverviewActivityHeatmap } from "@/components/overview/summary/OverviewActivityHeatmap";
+import { OverviewAttentionCard } from "@/components/overview/summary/OverviewAttentionCard";
+import { OverviewHero } from "@/components/overview/summary/OverviewHero";
+import { OverviewHeroKpis } from "@/components/overview/summary/OverviewHeroKpis";
+import { OverviewNetworkCard } from "@/components/overview/summary/OverviewNetworkCard";
+import { OverviewPipelineFunnel } from "@/components/overview/summary/OverviewPipelineFunnel";
+import { OverviewRevenueMix } from "@/components/overview/summary/OverviewRevenueMix";
+import { OverviewRevenueVolumeChart } from "@/components/overview/summary/OverviewRevenueVolumeChart";
+import { OverviewSankeyFlow } from "@/components/overview/summary/OverviewSankeyFlow";
 import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
 import { useOverview } from "@/hooks/useOverview";
-import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
-import type { OverviewRange, OverviewTabKey } from "@/types/overview";
+import type { OverviewRange } from "@/types/overview";
+import "@/components/overview/summary/overview-summary.css";
 
-const TAB_ITEMS: Array<{
-  value: OverviewTabKey;
-  label: string;
-  icon: typeof FileText;
-  kpiKey:
-    | "bookings"
-    | "contracts"
-    | "billing"
-    | "operations"
-    | "customers"
-    | "staff";
-  metricKey: string;
-  /** Any of these keys grants the tab. */
-  permission: string[];
-}> = [
-  {
-    value: "bookings",
-    label: "Bookings",
-    icon: FileText,
-    kpiKey: "bookings",
-    metricKey: "totalActive",
-    permission: [FREIGHT_PERMS.bookings.view],
-  },
-  {
-    value: "contracts",
-    label: "Contracts",
-    icon: FileSignature,
-    kpiKey: "contracts",
-    metricKey: "totalActive",
-    permission: [FREIGHT_PERMS.contracts.view],
-  },
-  {
-    value: "billing",
-    label: "Billing",
-    icon: Banknote,
-    kpiKey: "billing",
-    metricKey: "successfulPaymentsMtd",
-    permission: [FREIGHT_PERMS.bookings.view, FREIGHT_PERMS.payments.view],
-  },
-  {
-    value: "operations",
-    label: "Operations",
-    icon: Train,
-    kpiKey: "operations",
-    metricKey: "trainsActive",
-    permission: [
-      FREIGHT_PERMS.trainScheduling.view,
-      FREIGHT_PERMS.warehouseInventory.view,
-      FREIGHT_PERMS.firstMile.view,
-      FREIGHT_PERMS.lastMile.view,
-    ],
-  },
-  {
-    value: "fleet",
-    label: "Fleet",
-    icon: TrainFront,
-    kpiKey: "operations",
-    metricKey: "wagonsAvailable",
-    permission: [FREIGHT_PERMS.wagons.view, FREIGHT_PERMS.trainScheduling.view],
-  },
-  {
-    value: "customers",
-    label: "Customers",
-    icon: Users,
-    kpiKey: "customers",
-    metricKey: "totalCustomers",
-    permission: [FREIGHT_PERMS.customers.view],
-  },
-  {
-    value: "staff",
-    label: "Staff",
-    icon: UserCheck,
-    kpiKey: "staff",
-    metricKey: "activeEmployees",
-    permission: [
-      FREIGHT_PERMS.admin,
-      FREIGHT_PERMS.staff.roles.view,
-      FREIGHT_PERMS.staff.employeeRegistration.view,
-      FREIGHT_PERMS.staff.roleAssignment.view,
-    ],
-  },
-];
+const RANGE_LABEL: Record<OverviewRange, string> = { "7d": "7d", "30d": "30d", "90d": "90d" };
+const RANGE_DAYS: Record<OverviewRange, number> = { "7d": 7, "30d": 30, "90d": 90 };
 
-function HeaderSkeleton() {
+/** Uppercase section eyebrow — matches the WarehouseDashboardPage convention. */
+function SectionTitle({ children }: { children: string }) {
   return (
-    <Stack gap="md">
-      <Skeleton height={48} radius="md" />
-      <Skeleton height={52} radius="lg" />
+    <Text fw={700} fz="sm" tt="uppercase" c="edr-muted" style={{ letterSpacing: 0.4 }}>
+      {children}
+    </Text>
+  );
+}
+
+/** One page band: eyebrow + content, with a staggered entrance by index. */
+function Band({ index, title, children }: { index: number; title: string; children: React.ReactNode }) {
+  return (
+    <Stack gap="sm" className="ov-band" style={{ animationDelay: `${index * 70}ms` }}>
+      <SectionTitle>{title}</SectionTitle>
+      {children}
+    </Stack>
+  );
+}
+
+function OverviewSkeleton() {
+  return (
+    <Stack gap="lg">
+      <Skeleton height={92} radius="lg" />
+      <Skeleton height={340} radius="lg" />
+      <Skeleton height={340} radius="lg" />
+      <Skeleton height={340} radius="lg" />
     </Stack>
   );
 }
 
 const OverviewPage = () => {
   const [range, setRange] = useState<OverviewRange>("30d");
-  const [activeTab, setActiveTab] = useState<OverviewTabKey>("bookings");
   const queryClient = useQueryClient();
-  const { user } = useAuth();
-  const { data: summary, isLoading, isError, error, refetch, isFetching } = useOverview(range);
+  const { data, isLoading, isError, error, refetch, isFetching } = useOverview(range);
 
-  // Permission-scoped view: only tabs the user may see; a restricted role
-  // (e.g. operations) gets a summary 403 — that is not a connection problem.
-  const visibleTabs = TAB_ITEMS.filter((tab) =>
-    tab.permission.some((key) => hasPermission(user, key)),
-  );
-  const currentTab = visibleTabs.some((t) => t.value === activeTab)
-    ? activeTab
-    : visibleTabs[0]?.value;
   const accessDenied =
     (error as { response?: { status?: number } } | null)?.response?.status === 403;
 
@@ -144,97 +64,113 @@ const OverviewPage = () => {
     void queryClient.invalidateQueries({ queryKey: QUERY_KEYS.OVERVIEW.ROOT });
   };
 
-  const getTabBadge = (tab: (typeof TAB_ITEMS)[number]) => {
-    if (!summary?.kpis) return 0;
-    const group = summary.kpis[tab.kpiKey] as unknown as Record<string, number>;
-    return group[tab.metricKey] ?? 0;
-  };
-
   return (
-    <Container fluid px="md" py="md">
-      <Stack gap="lg">
-        {isLoading && !summary ? (
-          <HeaderSkeleton />
-        ) : (
-          <OverviewPageHeader
-            range={range}
-            onRangeChange={setRange}
-            generatedAt={summary?.generatedAt}
-            onRefresh={handleRefresh}
-            isRefreshing={isFetching && !isLoading}
-          />
-        )}
+    <PageContainer>
+      {/* Gradient greeting hero; the KPI strip overlaps its bottom edge. */}
+      <div className="ov-band">
+        <OverviewHero
+          range={range}
+          onRangeChange={setRange}
+          generatedAt={data?.generatedAt}
+          onRefresh={handleRefresh}
+          isRefreshing={isFetching && !isLoading}
+        />
+        {data ? (
+          <div style={{ marginTop: -52, paddingInline: 20, position: "relative" }}>
+            <OverviewHeroKpis
+              kpis={data.kpis}
+              current={data.current}
+              previous={data.previous}
+              rangeLabel={RANGE_LABEL[range]}
+            />
+          </div>
+        ) : null}
+      </div>
 
-        {isError && !accessDenied && (
-          <Alert
-            icon={<AlertCircle size={16} />}
-            color="red"
-            title="Unable to load dashboard summary"
-            variant="light"
-          >
-            <Stack gap="sm" align="flex-start">
-              <span>Check your connection and try again.</span>
-              <Button size="xs" variant="light" color="red" onClick={() => void refetch()}>
-                Retry
-              </Button>
-            </Stack>
-          </Alert>
-        )}
+      {isError && !accessDenied && (
+        <Alert
+          icon={<AlertCircle size={16} />}
+          color="red"
+          title="Unable to load dashboard summary"
+          variant="light"
+          mt="lg"
+        >
+          <Stack gap="sm" align="flex-start">
+            <span>Check your connection and try again.</span>
+            <Button size="xs" variant="light" color="red" onClick={() => void refetch()}>
+              Retry
+            </Button>
+          </Stack>
+        </Alert>
+      )}
 
-        {visibleTabs.length === 0 && !isLoading && !isError && (
-          <Alert color="gray" variant="light" title="No dashboard sections available">
-            Your role has no access to any overview section.
-          </Alert>
-        )}
+      {accessDenied && (
+        <Alert color="gray" variant="light" title="No dashboard access" mt="lg">
+          Your role has no access to the overview.
+        </Alert>
+      )}
 
-        {visibleTabs.length > 0 && (
-          <Tabs
-            value={currentTab}
-            onChange={(value) =>
-              setActiveTab((value as OverviewTabKey) ?? visibleTabs[0].value)
-            }
-            variant="pills"
-            color="edr-green"
-            keepMounted={false}
-            classNames={{ list: "ov-tablist", tab: "ov-tab" }}
-          >
-            <Tabs.List>
-              {visibleTabs.map((tab) => {
-                const Icon = tab.icon;
-                const isActive = currentTab === tab.value;
-                return (
-                  <Tabs.Tab
-                    key={tab.value}
-                    value={tab.value}
-                    leftSection={<Icon size={17} />}
-                    rightSection={
-                      summary ? (
-                        <Badge
-                          size="sm"
-                          radius="sm"
-                          variant={isActive ? "white" : "light"}
-                          color={isActive ? "edr-green" : "gray"}
-                        >
-                          {getTabBadge(tab)}
-                        </Badge>
-                      ) : undefined
-                    }
-                  >
-                    {tab.label}
-                  </Tabs.Tab>
-                );
-              })}
-            </Tabs.List>
+      {isLoading && !data ? (
+        <Stack mt="lg">
+          <OverviewSkeleton />
+        </Stack>
+      ) : data ? (
+        <Stack gap="xl" mt="xl">
+          {/* Band 1 — revenue & volume: growing, making money, pacing vs last period. */}
+          <Band index={1} title="Revenue & volume">
+            <Grid gap="md">
+              <Grid.Col span={{ base: 12, lg: 8 }}>
+                <OverviewRevenueVolumeChart
+                  bookingTrend={data.bookingTrend}
+                  paymentTrend={data.paymentTrend}
+                  previousPaymentTrend={data.previousPaymentTrend}
+                  rangeDays={RANGE_DAYS[range]}
+                />
+              </Grid.Col>
+              <Grid.Col span={{ base: 12, lg: 4 }}>
+                <OverviewRevenueMix
+                  byDirection={data.revenueByDirection}
+                  byFreightType={data.revenueByFreightType}
+                />
+              </Grid.Col>
+            </Grid>
+          </Band>
 
-            {visibleTabs.map((tab) => (
-              <Tabs.Panel key={tab.value} value={tab.value} pt="lg">
-                <OverviewTabContent tab={tab.value} range={range} />
-              </Tabs.Panel>
-            ))}
-          </Tabs>
-        )}
-      </Stack>
-    </Container>
+          {/* Band 2 — where the money runs, and what's waiting on someone. */}
+          <Band index={2} title="Money flow & attention">
+            <Grid gap="md">
+              <Grid.Col span={{ base: 12, lg: 7 }}>
+                <OverviewSankeyFlow flows={data.revenueFlows} />
+              </Grid.Col>
+              <Grid.Col span={{ base: 12, lg: 5 }}>
+                <OverviewAttentionCard
+                  bookings={data.kpis.bookings}
+                  contracts={data.kpis.contracts}
+                  billing={data.kpis.billing}
+                />
+              </Grid.Col>
+            </Grid>
+          </Band>
+
+          {/* Band 3 — the network now, and when demand arrives. */}
+          <Band index={3} title="Network & rhythm">
+            <Grid gap="md">
+              <Grid.Col span={{ base: 12, lg: 5 }}>
+                <OverviewNetworkCard kpis={data.kpis.operations} />
+              </Grid.Col>
+              <Grid.Col span={{ base: 12, lg: 7 }}>
+                <OverviewActivityHeatmap cells={data.bookingHeatmap} />
+              </Grid.Col>
+            </Grid>
+          </Band>
+
+          {/* Band 4 — the booking pipeline, full width so every stage bar has room. */}
+          <Band index={4} title="Pipeline">
+            <OverviewPipelineFunnel data={data.bookingsByPipeline} />
+          </Band>
+        </Stack>
+      ) : null}
+    </PageContainer>
   );
 };
 
diff --git a/packages/types/src/freight/overview.ts b/packages/types/src/freight/overview.ts
index e3d98bc00..4972db10d 100644
--- a/packages/types/src/freight/overview.ts
+++ b/packages/types/src/freight/overview.ts
@@ -13,6 +13,7 @@ export interface IOverviewBookingKpis {
 export interface IOverviewOperationsKpis {
   trainsActive: number;
   wagonsAvailable: number;
+  wagonsTotal: number;
   containersInTransit: number;
   cargoesLoaded: number;
   schedulesUpcoming: number;
@@ -99,13 +100,60 @@ export interface IOverviewRecentContract {
   createdAt: string;
 }
 
+/** Bookings/revenue/tonnage totals for one range-wide window. */
+export interface IOverviewPeriodTotals {
+  bookingsCreated: number;
+  revenueEtb: number;
+  revenueUsd: number;
+  tons: number;
+}
+
+/** One label's revenue split, e.g. a trade direction or freight type. */
+export interface IOverviewRevenueSlice {
+  label: string;
+  amountEtb: number;
+  amountUsd: number;
+}
+
+export interface IOverviewTonsTrendPoint {
+  date: string;
+  tons: number;
+}
+
+/** One direction → freight-type revenue flow (Sankey link). */
+export interface IOverviewRevenueFlow {
+  direction: string;
+  freightType: string;
+  amountEtb: number;
+  amountUsd: number;
+}
+
+/** Booking arrivals for one weekday × 3-hour block. */
+export interface IOverviewHeatmapCell {
+  /** ISO weekday, 1 = Monday … 7 = Sunday. */
+  dow: number;
+  /** 3-hour block, 0 = 00–03 … 7 = 21–24. */
+  block: number;
+  count: number;
+}
+
 export interface IOverviewDashboard {
   kpis: IOverviewKpis;
   bookingTrend: IOverviewTrendPoint[];
   bookingsByStatus: IOverviewStatusCount[];
   bookingsByPipeline: IOverviewPipelineCount[];
   paymentTrend: IOverviewPaymentTrendPoint[];
-  recentBookings: IOverviewRecentBooking[];
+  /** Totals for the selected range, ending today. */
+  current: IOverviewPeriodTotals;
+  /** Totals for the immediately preceding range of the same length — the delta baseline. */
+  previous: IOverviewPeriodTotals;
+  revenueByDirection: IOverviewRevenueSlice[];
+  revenueByFreightType: IOverviewRevenueSlice[];
+  /** The preceding same-length window's daily revenue — ghost-line comparison. */
+  previousPaymentTrend: IOverviewPaymentTrendPoint[];
+  tonsTrend: IOverviewTonsTrendPoint[];
+  revenueFlows: IOverviewRevenueFlow[];
+  bookingHeatmap: IOverviewHeatmapCell[];
   generatedAt: string;
 }
 

From 9fff469ffa8733bd674c952de28ca198fa5dab70 Mon Sep 17 00:00:00 2001
From: marshalyordanos <marshalyordanosseifu@gmail.com>
Date: Thu, 13 Aug 2026 15:54:40 +0300
Subject: [PATCH 083/174] feat: implement shipping line bookings management

- Add ShippingLineBookingsPage for listing and managing shipping line bookings.
- Create ShippingLineDocumentsModal for document uploads related to bookings.
- Introduce ShippingLineInitiateModal for initiating new shipping line bookings.
- Implement booking document state management with booking-doc-state utility.
- Add shipping line bookings service for API interactions.
- Update index to export new components and services.
- Enhance types for freight to include shipping line credits.
---
 .../3450000000000-BookingShippingLine.ts      | 117 +++++
 .../3460000000000-ShippingLineCredits.ts      | 201 +++++++++
 .../3470000000000-ShippingLineRates.ts        | 127 ++++++
 .../src/modules/billing/billing.module.ts     |   4 +-
 .../src/modules/billing/billing.service.ts    |  41 +-
 .../billing/entities/invoice.entity.ts        |  25 +-
 .../bookings/booking-pricing.service.ts       |  25 +-
 .../src/modules/bookings/clearance.util.ts    |  24 +
 .../bookings/entities/booking.entity.ts       |  37 +-
 .../src/modules/companies/companies.module.ts |   5 +-
 .../rule-engine/dto/create-rate.dto.ts        |   8 +
 .../dto/list-rule-engine-query.dto.ts         |  16 +
 .../rule-engine/entities/rate.entity.ts       |  19 +
 .../interfaces/rates.repository.interface.ts  |   2 +
 .../repositories/rates.repository.ts          |  27 +-
 .../modules/rule-engine/rule-engine.module.ts |   4 +
 .../rule-engine/rule-engine.service.spec.ts   | 142 ++++++
 .../rule-engine/rule-engine.service.ts        |  37 +-
 .../services/rates.duplicate-pattern.spec.ts  |   2 +
 .../rule-engine/services/rates.service.ts     |  52 +++
 .../dto/cancel-shipping-line-booking.dto.ts   |  15 +
 .../dto/initiate-shipping-line-booking.dto.ts |  38 ++
 .../dto/shipping-line-credit.dto.ts           |  51 +++
 .../entities/shipping-line-credit.entity.ts   | 110 +++++
 .../shipping-line-bookings.controller.ts      |  96 ++++
 .../shipping-line-bookings.service.ts         | 363 +++++++++++++++
 .../shipping-line-companies.module.ts         |  41 +-
 .../shipping-line-credits.controller.ts       | 127 ++++++
 .../shipping-line-credits.repository.ts       | 138 ++++++
 .../shipping-line-credits.service.spec.ts     | 296 ++++++++++++
 .../shipping-line-credits.service.ts          | 420 ++++++++++++++++++
 .../warehouses/warehouse-invoice.service.ts   |   4 +-
 .../src/seed/file-upload-settings.seeder.ts   |  20 +
 .../src/seed/freight-permissions.registry.ts  |  26 ++
 .../ruleEngine/RuleEngineFormDialog.tsx       |  64 ++-
 .../src/hooks/rule-engine/useRuleEngine.ts    |  24 +
 .../bookings/DocumentClearanceDetailPage.tsx  |  17 +-
 .../ruleEngine/RuleEngineResourcePage.tsx     |  64 ++-
 .../src/pages/ruleEngine/config/resources.ts  | 244 +++++++++-
 .../services/ruleEngine/ruleEngine.service.ts |   6 +
 apps/edr-freight-web/portal/src/App.tsx       |   8 +
 .../portal/src/components/AppLayout.tsx       |  13 +-
 .../ShippingLineBookingDetailPage.tsx         | 402 +++++++++++++++++
 .../ShippingLineBookingsPage.tsx              | 323 +++++++++++++-
 .../ShippingLineDocumentsModal.tsx            | 248 +++++++++++
 .../ShippingLineInitiateModal.tsx             | 267 +++++++++++
 .../pages/shipping-line/booking-doc-state.ts  |  85 ++++
 .../portal/src/pages/shipping-line/index.ts   |   1 +
 .../shipping-line-bookings.service.ts         | 129 ++++++
 packages/types/src/freight/index.ts           |   7 +
 50 files changed, 4485 insertions(+), 77 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3450000000000-BookingShippingLine.ts
 create mode 100644 apps/edr-freight-api/src/migrations/3460000000000-ShippingLineCredits.ts
 create mode 100644 apps/edr-freight-api/src/migrations/3470000000000-ShippingLineRates.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/dto/cancel-shipping-line-booking.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/dto/initiate-shipping-line-booking.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/dto/shipping-line-credit.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/entities/shipping-line-credit.entity.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.controller.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.controller.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.repository.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.ts
 create mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingDetailPage.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineDocumentsModal.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineInitiateModal.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/booking-doc-state.ts
 create mode 100644 apps/edr-freight-web/portal/src/services/shipping-line-bookings.service.ts

diff --git a/apps/edr-freight-api/src/migrations/3450000000000-BookingShippingLine.ts b/apps/edr-freight-api/src/migrations/3450000000000-BookingShippingLine.ts
new file mode 100644
index 000000000..d53914ef3
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3450000000000-BookingShippingLine.ts
@@ -0,0 +1,117 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Shipping lines book rail capacity directly, without a contract.
+ *
+ * A booking has always been owned by `company_id` (a customer `companies` row),
+ * but a shipping line is a `shipping_line_companies` row and deliberately NOT a
+ * company — it carries no TIN, licence or operational profiles. So it gets its
+ * own nullable owner column rather than a synthetic company row.
+ *
+ * Exactly one of the two is set: `company_id` for a customer booking,
+ * `shipping_line_company_id` for a shipping-line one. Existing rows keep
+ * `company_id` and a NULL `shipping_line_company_id`, so nothing needs
+ * backfilling and every customer query filtering on `company_id` behaves
+ * exactly as before. Government bookings already bill to a seeded government
+ * company, so they satisfy the CHECK unchanged.
+ *
+ * NOTE: not to be confused with the existing `bookings.shipping_line_id`, which
+ * is cargo metadata naming the carrier line that moves the goods
+ * (`freight.shipping_lines`, reference data). This column points at
+ * `freight.shipping_line_companies` — the portal account — and is unrelated.
+ */
+export class BookingShippingLine3450000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings
+        ADD COLUMN IF NOT EXISTS shipping_line_company_id uuid
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_bookings_shipping_line_company_id
+        ON freight.bookings (shipping_line_company_id)
+    `);
+
+    // `company_id` / `company_profile_id` are NOT NULL and point at the customer
+    // tables, so a shipping-line booking could not be inserted at all. Relax
+    // them to nullable; their foreign keys are left in place and keep validating
+    // every non-NULL value, so a customer booking is constrained exactly as
+    // before. The CHECK below is what now guarantees an owner is present.
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings ALTER COLUMN company_id DROP NOT NULL
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings ALTER COLUMN company_profile_id DROP NOT NULL
+    `);
+
+    // Route and service are inherited from the contract on a customer booking.
+    // A shipping line initiates before any of that is known — the bare booking
+    // exists only to hang documents off — so these are relaxed too and filled
+    // in when the booking is completed. Existing rows all have values, and the
+    // customer paths still always set them.
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings ALTER COLUMN origin_yard_id DROP NOT NULL
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings ALTER COLUMN destination_yard_id DROP NOT NULL
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings ALTER COLUMN service_type_id DROP NOT NULL
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings ALTER COLUMN freight_type DROP NOT NULL
+    `);
+
+    // No FK: kept consistent with how the column is populated at the service
+    // layer, and avoids a lock on shipping_line_companies during deploy.
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings
+        DROP CONSTRAINT IF EXISTS chk_bookings_single_owner
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings
+        ADD CONSTRAINT chk_bookings_single_owner
+        CHECK (
+          (company_id IS NOT NULL AND shipping_line_company_id IS NULL)
+          OR (company_id IS NULL AND shipping_line_company_id IS NOT NULL)
+        )
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings
+        DROP CONSTRAINT IF EXISTS chk_bookings_single_owner
+    `);
+
+    // Only reinstate NOT NULL if no shipping-line booking exists; those rows
+    // have a NULL company_id by design and would make the ALTER fail. Leaving
+    // the columns nullable is the safe outcome — the constraint is additive.
+    const [{ count }] = (await queryRunner.query(`
+      SELECT COUNT(*)::int AS count FROM freight.bookings
+      WHERE shipping_line_company_id IS NOT NULL
+    `)) as Array<{ count: number }>;
+
+    if (count === 0) {
+      for (const column of [
+        "company_id",
+        "company_profile_id",
+        "origin_yard_id",
+        "destination_yard_id",
+        "service_type_id",
+        "freight_type",
+      ]) {
+        await queryRunner.query(`
+          ALTER TABLE freight.bookings ALTER COLUMN ${column} SET NOT NULL
+        `);
+      }
+    }
+
+    await queryRunner.query(`
+      DROP INDEX IF EXISTS freight.idx_bookings_shipping_line_company_id
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings DROP COLUMN IF EXISTS shipping_line_company_id
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3460000000000-ShippingLineCredits.ts b/apps/edr-freight-api/src/migrations/3460000000000-ShippingLineCredits.ts
new file mode 100644
index 000000000..5a59d9d80
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3460000000000-ShippingLineCredits.ts
@@ -0,0 +1,201 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Shipping lines consume services before paying for them.
+ *
+ * A shipping line books rail capacity and the booking proceeds with no payment
+ * gate at all — unlike a customer booking, which cannot advance until its
+ * PREPAID invoice settles. What the line owes is instead recorded here as a
+ * credit: one row per booking, priced once and never recalculated. Finance
+ * later selects a batch of unbilled credits, generates a single invoice for
+ * them, and the line pays that invoice through the normal CBE flow. When the
+ * invoice settles, its credits are marked paid and stop counting as debt.
+ *
+ * This is deliberately NOT a wallet or a stored balance. There is no money in
+ * the system to draw down: a credit is a debt the line already incurred, so
+ * the outstanding figure is always derived (`SUM(amount) WHERE status <>
+ * 'PAID'`) rather than kept in a column that UPDATEs can drift out of sync.
+ *
+ * `invoices.company_id` / `company_profile_id` are relaxed to nullable for the
+ * same reason `bookings` was in {@link BookingShippingLine3450000000000}: a
+ * shipping line is not a `companies` row and never will be, so an invoice
+ * billed to one has no customer to point at. Both FKs stay in place and keep
+ * validating every non-NULL value, so a customer invoice is constrained
+ * exactly as before; the CHECK below is what now guarantees a payer exists.
+ */
+export class ShippingLineCredits3460000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // ── Invoices: allow a shipping-line payer ────────────────────────────────
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+        ADD COLUMN IF NOT EXISTS shipping_line_company_id uuid
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_invoices_shipping_line_company_id
+        ON freight.invoices (shipping_line_company_id)
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices ALTER COLUMN company_id DROP NOT NULL
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices ALTER COLUMN company_profile_id DROP NOT NULL
+    `);
+
+    // Exactly one payer. Mirrors chk_bookings_single_owner so the two tables
+    // answer "who owes this?" the same way. Existing rows all have company_id
+    // and a NULL shipping_line_company_id, so nothing needs backfilling.
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+        DROP CONSTRAINT IF EXISTS chk_invoices_single_payer
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+        ADD CONSTRAINT chk_invoices_single_payer
+        CHECK (
+          (company_id IS NOT NULL AND shipping_line_company_id IS NULL)
+          OR (company_id IS NULL AND shipping_line_company_id IS NOT NULL)
+        )
+    `);
+
+    // ── The credit ledger ────────────────────────────────────────────────────
+    await queryRunner.query(`
+      DO $$ BEGIN
+        CREATE TYPE freight.shipping_line_credits_status_enum AS ENUM (
+          'UNBILLED', 'BILLED', 'PAID', 'CANCELLED'
+        );
+      EXCEPTION WHEN duplicate_object THEN NULL; END $$
+    `);
+
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.shipping_line_credits (
+        id uuid DEFAULT gen_random_uuid() NOT NULL,
+        shipping_line_company_id uuid NOT NULL,
+        booking_id uuid NOT NULL,
+        amount numeric(14,2) NOT NULL,
+        currency character varying(8) DEFAULT 'ETB'::character varying NOT NULL,
+        status freight.shipping_line_credits_status_enum
+          DEFAULT 'UNBILLED'::freight.shipping_line_credits_status_enum NOT NULL,
+        description character varying(255),
+        invoice_id uuid,
+        billed_at timestamp with time zone,
+        paid_at timestamp with time zone,
+        cancelled_at timestamp with time zone,
+        cancellation_reason character varying(255),
+        created_at timestamp with time zone DEFAULT now() NOT NULL,
+        updated_at timestamp with time zone DEFAULT now() NOT NULL,
+        deleted_at timestamp with time zone,
+        CONSTRAINT pk_shipping_line_credits PRIMARY KEY (id),
+        CONSTRAINT chk_shipping_line_credits_amount CHECK (amount >= 0),
+        -- The state machine, enforced in the DB rather than trusted to the
+        -- service: an UNBILLED credit has no invoice, and anything past
+        -- UNBILLED must name the invoice it was billed on. Without this a
+        -- half-applied batch could leave BILLED rows with a NULL invoice_id
+        -- and silently vanish from both the unbilled list and the invoice.
+        CONSTRAINT chk_shipping_line_credits_invoice_link CHECK (
+          (status = 'UNBILLED' AND invoice_id IS NULL)
+          OR (status IN ('BILLED', 'PAID') AND invoice_id IS NOT NULL)
+          OR status = 'CANCELLED'
+        )
+      )
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE freight.shipping_line_credits
+        DROP CONSTRAINT IF EXISTS fk_shipping_line_credits_shipping_line
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.shipping_line_credits
+        ADD CONSTRAINT fk_shipping_line_credits_shipping_line
+        FOREIGN KEY (shipping_line_company_id)
+        REFERENCES freight.shipping_line_companies(id) ON DELETE RESTRICT
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE freight.shipping_line_credits
+        DROP CONSTRAINT IF EXISTS fk_shipping_line_credits_booking
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.shipping_line_credits
+        ADD CONSTRAINT fk_shipping_line_credits_booking
+        FOREIGN KEY (booking_id)
+        REFERENCES freight.bookings(id) ON DELETE RESTRICT
+    `);
+
+    // SET NULL rather than CASCADE: deleting an invoice must never delete the
+    // record of what was owed. The row would then violate the link CHECK, so a
+    // credit whose invoice is removed has to be walked back to UNBILLED
+    // explicitly — which is the correct, visible outcome.
+    await queryRunner.query(`
+      ALTER TABLE freight.shipping_line_credits
+        DROP CONSTRAINT IF EXISTS fk_shipping_line_credits_invoice
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.shipping_line_credits
+        ADD CONSTRAINT fk_shipping_line_credits_invoice
+        FOREIGN KEY (invoice_id)
+        REFERENCES freight.invoices(id) ON DELETE SET NULL
+    `);
+
+    // One live credit per booking. Partial so a soft-deleted or cancelled row
+    // does not block re-pricing a booking that was voided and rebooked.
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS uq_shipping_line_credits_booking
+        ON freight.shipping_line_credits (booking_id)
+        WHERE deleted_at IS NULL AND status <> 'CANCELLED'
+    `);
+
+    // Drives the two hot reads: finance's unbilled worklist per line, and the
+    // outstanding total on the shipping-line detail page.
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_shipping_line_credits_line_status
+        ON freight.shipping_line_credits (shipping_line_company_id, status)
+        WHERE deleted_at IS NULL
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_shipping_line_credits_invoice_id
+        ON freight.shipping_line_credits (invoice_id)
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      DROP TABLE IF EXISTS freight.shipping_line_credits
+    `);
+    await queryRunner.query(`
+      DROP TYPE IF EXISTS freight.shipping_line_credits_status_enum
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+        DROP CONSTRAINT IF EXISTS chk_invoices_single_payer
+    `);
+
+    // Only reinstate NOT NULL if no shipping-line invoice exists; those rows
+    // have a NULL company_id by design and would make the ALTER fail. Leaving
+    // the columns nullable is the safe outcome — the constraint is additive.
+    const [{ count }] = (await queryRunner.query(`
+      SELECT COUNT(*)::int AS count FROM freight.invoices
+      WHERE shipping_line_company_id IS NOT NULL
+    `)) as Array<{ count: number }>;
+
+    if (count === 0) {
+      await queryRunner.query(`
+        ALTER TABLE freight.invoices ALTER COLUMN company_id SET NOT NULL
+      `);
+      await queryRunner.query(`
+        ALTER TABLE freight.invoices ALTER COLUMN company_profile_id SET NOT NULL
+      `);
+    }
+
+    await queryRunner.query(`
+      DROP INDEX IF EXISTS freight.idx_invoices_shipping_line_company_id
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+        DROP COLUMN IF EXISTS shipping_line_company_id
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3470000000000-ShippingLineRates.ts b/apps/edr-freight-api/src/migrations/3470000000000-ShippingLineRates.ts
new file mode 100644
index 000000000..05e0bb799
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3470000000000-ShippingLineRates.ts
@@ -0,0 +1,127 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Per-shipping-line rates.
+ *
+ * A shipping line books rail capacity directly (see BookingShippingLine3450000000000)
+ * and negotiates its own prices, so the rate table gains an owner column:
+ * `shipping_line_company_id` NULL = the standard rate every customer pays,
+ * NOT NULL = a rate that only that line's bookings resolve.
+ *
+ * Points at `freight.shipping_line_companies` (the portal account that owns the
+ * booking), NOT `freight.shipping_lines` — the latter is carrier reference data
+ * naming who physically moves the goods, and the existing SHIPPING_LINE trigger
+ * already keys off it. Both stay independent.
+ *
+ * Line rates OVERRIDE rather than stack: a booking owned by a line prices off
+ * that line's rate for the lane, and is hard-blocked when none exists (the
+ * standard rate is deliberately not a fallback — see RuleEngineService).
+ *
+ * Every existing row keeps a NULL owner, so nothing needs backfilling and the
+ * standard-rate lookups behave exactly as before.
+ */
+export class ShippingLineRates3470000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.rates
+        ADD COLUMN IF NOT EXISTS shipping_line_company_id uuid
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE freight.rates
+        DROP CONSTRAINT IF EXISTS "FK_rates_shipping_line_company"
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.rates
+        ADD CONSTRAINT "FK_rates_shipping_line_company"
+        FOREIGN KEY (shipping_line_company_id)
+        REFERENCES freight.shipping_line_companies (id)
+        ON DELETE RESTRICT
+    `);
+
+    // Rate resolution always filters by owner, so the lookups this column
+    // participates in are (owner, lane) — indexed together with rate_type,
+    // which every lookup also pins.
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_rates_shipping_line_company_id
+        ON freight.rates (shipping_line_company_id)
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_rates_shipping_line_lane
+        ON freight.rates (shipping_line_company_id, rate_type, origin_yard_id, destination_yard_id)
+        WHERE shipping_line_company_id IS NOT NULL
+    `);
+
+    // A shipping line sells import freight only — the export leg is contracted
+    // through the customer, not the carrier. Enforced here so a line rate can
+    // never be filed against an export lane regardless of which API path wrote
+    // it. Surcharges carry no direction and are unaffected.
+    await queryRunner.query(`
+      ALTER TABLE freight.rates
+        DROP CONSTRAINT IF EXISTS "CK_rates_shipping_line_import_only"
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.rates
+        ADD CONSTRAINT "CK_rates_shipping_line_import_only" CHECK (
+          deleted_at IS NOT NULL OR status = 'SUPERSEDED' OR
+          shipping_line_company_id IS NULL OR
+          trade_direction IS NULL OR trade_direction = 'IMPORT'
+        )
+    `);
+
+    // The owner joins the rate's identity. Without it MSC's 20ft Djibouti→Modjo
+    // rate collides with the standard rate for the same lane — same rate_type,
+    // same scope, same unit — and the insert fails on UQ_rates_pattern. NULL
+    // (the standard rate) collapses to the zero uuid like every other nullable
+    // scope column, so existing rows keep their current uniqueness exactly.
+    await queryRunner.query(`DROP INDEX IF EXISTS freight."UQ_rates_pattern"`);
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS "UQ_rates_pattern" ON freight.rates USING btree (
+        rate_type,
+        COALESCE(shipping_line_company_id, '00000000-0000-0000-0000-000000000000'::uuid),
+        COALESCE(container_type_id, '00000000-0000-0000-0000-000000000000'::uuid),
+        COALESCE(cargo_type_id, '00000000-0000-0000-0000-000000000000'::uuid),
+        COALESCE(trade_direction, ''::character varying),
+        COALESCE(origin_yard_id, '00000000-0000-0000-0000-000000000000'::uuid),
+        COALESCE(destination_yard_id, '00000000-0000-0000-0000-000000000000'::uuid),
+        rate_unit,
+        COALESCE(min_km, '-1'::numeric)
+      ) WHERE ((deleted_at IS NULL) AND ((status)::text <> 'SUPERSEDED'::text))
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    // Restore the pre-owner pattern index (as left by LastMileRateBands).
+    await queryRunner.query(`DROP INDEX IF EXISTS freight."UQ_rates_pattern"`);
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS "UQ_rates_pattern" ON freight.rates USING btree (
+        rate_type,
+        COALESCE(container_type_id, '00000000-0000-0000-0000-000000000000'::uuid),
+        COALESCE(cargo_type_id, '00000000-0000-0000-0000-000000000000'::uuid),
+        COALESCE(trade_direction, ''::character varying),
+        COALESCE(origin_yard_id, '00000000-0000-0000-0000-000000000000'::uuid),
+        COALESCE(destination_yard_id, '00000000-0000-0000-0000-000000000000'::uuid),
+        rate_unit,
+        COALESCE(min_km, '-1'::numeric)
+      ) WHERE ((deleted_at IS NULL) AND ((status)::text <> 'SUPERSEDED'::text))
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE freight.rates
+        DROP CONSTRAINT IF EXISTS "CK_rates_shipping_line_import_only"
+    `);
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS freight.idx_rates_shipping_line_lane`,
+    );
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS freight.idx_rates_shipping_line_company_id`,
+    );
+    await queryRunner.query(`
+      ALTER TABLE freight.rates
+        DROP CONSTRAINT IF EXISTS "FK_rates_shipping_line_company"
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.rates DROP COLUMN IF EXISTS shipping_line_company_id
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/billing.module.ts b/apps/edr-freight-api/src/modules/billing/billing.module.ts
index 7ec5c333b..06849d560 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.module.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.module.ts
@@ -19,7 +19,8 @@ import { FilesModule } from "../files/files.module";
   imports: [
     TypeOrmModule.forFeature([Invoice, InvoiceLine]),
     forwardRef(() => PaymentModule),
-    CompaniesModule,
+    // Cycles back via ShippingLineCompaniesModule, which imports this module.
+    forwardRef(() => CompaniesModule),
     DocumentsModule,
     UserTradeAccessModule,
     FilesModule,
@@ -29,3 +30,4 @@ import { FilesModule } from "../files/files.module";
   exports: [BillingService],
 })
 export class BillingModule {}
+  
\ No newline at end of file
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 6c7e8455d..7d0f1e962 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -112,8 +112,16 @@ export interface GenerateInvoiceInput {
   sourceId: string;
   /** What the invoice is for (e.g. "prepaid", "credit"). */
   type: string;
-  companyId: string;
-  companyProfileId: string;
+  /** The customer billed. Omit only when billing a shipping line instead. */
+  companyId?: string | null;
+  companyProfileId?: string | null;
+  /**
+   * The shipping line billed, for an invoice covering batched shipping-line
+   * credits. Mutually exclusive with `companyId` — the DB enforces this via
+   * `chk_invoices_single_payer`, and {@link createInvoice} rejects a payload
+   * setting both or neither before it ever reaches the constraint.
+   */
+  shippingLineCompanyId?: string | null;
   lines: InvoiceLineInput[];
   currency?: string;
   /** Explicit pre-tax subtotal; defaults to the sum of line amounts. */
@@ -139,8 +147,11 @@ export interface InvoiceEventPayload {
   source: Freight.InvoiceSource;
   sourceId: string;
   type: string;
-  companyId: string;
-  companyProfileId: string;
+  /** Null when the payer is a shipping line rather than a customer company. */
+  companyId: string | null;
+  companyProfileId: string | null;
+  /** Set only on shipping-line invoices; mutually exclusive with `companyId`. */
+  shippingLineCompanyId?: string | null;
   totalAmount: number;
   currency: string;
   status: Freight.InvoiceStatus;
@@ -609,7 +620,6 @@ export class BillingService {
     input: GenerateInvoiceInput,
     manager?: EntityManager,
   ): Promise<Invoice & { lines: InvoiceLine[] }> {
-    console.log("oooooooooo", input);
     const run = (mg: EntityManager) => this.createInvoice(input, mg);
     return manager ? run(manager) : this.dataSource.transaction(run);
   }
@@ -622,6 +632,21 @@ export class BillingService {
     const status = input.status ?? Freight.InvoiceStatus.Pending;
     const issued = status !== Freight.InvoiceStatus.Draft;
 
+    // Exactly one payer, checked here so a bad payload fails with a clear
+    // message instead of a raw `chk_invoices_single_payer` violation.
+    const billsCompany = Boolean(input.companyId);
+    const billsShippingLine = Boolean(input.shippingLineCompanyId);
+    if (billsCompany === billsShippingLine) {
+      throw new BadRequestException(
+        "An invoice must be billed to exactly one payer: either companyId or shippingLineCompanyId.",
+      );
+    }
+    if (billsCompany && !input.companyProfileId) {
+      throw new BadRequestException(
+        "companyProfileId is required when billing a company.",
+      );
+    }
+
     const lines = input.lines.map((l) => {
       const quantity = l.quantity ?? 1;
       const unitRate = l.unitRate ?? 0;
@@ -657,8 +682,9 @@ export class BillingService {
         source: input.source,
         sourceId: input.sourceId,
         type: input.type,
-        companyId: input.companyId,
-        companyProfileId: input.companyProfileId,
+        companyId: input.companyId ?? null,
+        companyProfileId: input.companyProfileId ?? null,
+        shippingLineCompanyId: input.shippingLineCompanyId ?? null,
         subtotalAmount: round2(subtotalAmount),
         taxAmount: round2(taxAmount),
         totalAmount: round2(totalAmount),
@@ -988,6 +1014,7 @@ export class BillingService {
       type: invoice.type,
       companyId: invoice.companyId,
       companyProfileId: invoice.companyProfileId,
+      shippingLineCompanyId: invoice.shippingLineCompanyId ?? null,
       totalAmount: invoice.totalAmount,
       currency: invoice.currency,
       status: invoice.status,
diff --git a/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts b/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
index 411d15ebe..3690e946d 100644
--- a/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
+++ b/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
@@ -23,22 +23,37 @@ export class Invoice extends BaseEntity {
   @Column({ name: "invoice_number", type: "varchar", length: 64, unique: true })
   invoiceNumber!: string;
 
-  /** The customer (company) this invoice is billed to. */
-  @Column({ name: "company_id", type: "uuid" })
-  companyId!: string;
+  /**
+   * The customer (company) this invoice is billed to. Null on a shipping-line
+   * invoice, which is billed to `shippingLineCompanyId` instead — a shipping
+   * line is deliberately not a `companies` row. A DB CHECK
+   * (`chk_invoices_single_payer`) guarantees exactly one of the two is set.
+   */
+  @Column({ name: "company_id", type: "uuid", nullable: true })
+  companyId!: string | null;
 
   @ManyToOne(() => Company)
   @JoinColumn({ name: "company_id" })
   company?: Company;
 
   /** The specific company profile (importer/exporter/forwarder/...) billed. */
-  @Column({ name: "company_profile_id", type: "uuid" })
-  companyProfileId!: string;
+  @Column({ name: "company_profile_id", type: "uuid", nullable: true })
+  companyProfileId!: string | null;
 
   @ManyToOne(() => CompanyProfile)
   @JoinColumn({ name: "company_profile_id" })
   companyProfile?: CompanyProfile;
 
+  /**
+   * The shipping line billed, when this invoice bills batched shipping-line
+   * credits rather than a customer booking. Mutually exclusive with
+   * `companyId`. No relation is declared: `ShippingLineCredit` already owns
+   * that edge, and importing the shipping-lines module here would close an
+   * import cycle (shipping-lines already depends on billing).
+   */
+  @Column({ name: "shipping_line_company_id", type: "uuid", nullable: true })
+  shippingLineCompanyId?: string | null;
+
   /** Sum of line amounts before tax; defaults to `totalAmount` for tax-free invoices. */
   @Column({ name: "subtotal_amount", type: "numeric", precision: 14, scale: 2, default: 0 })
   subtotalAmount!: number;
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-pricing.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-pricing.service.ts
index 4ebebe879..f7dc40a82 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-pricing.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-pricing.service.ts
@@ -165,7 +165,7 @@ export class BookingPricingService {
       total += line.amount;
     }
 
-    const liveRates = await this.ratesService.findLiveRates();
+    const liveRates = await this.liveRatesForBooking(booking);
     const rateById = new Map(liveRates.map((r) => [r.id, r]));
     const usedRatesMap = new Map([...baseRates, ...mileRates].map((r) => [r.id, r]));
 
@@ -414,6 +414,9 @@ export class BookingPricingService {
       isGovernment: booking.isGovernment,
       allowConsolidation,
       shippingLineId: booking.shippingLineId,
+      // A shipping line's own booking prices off that line's negotiated rates
+      // instead of the standard customer ones (see RuleEngineService.ratesForOwner).
+      shippingLineCompanyId: booking.shippingLineCompanyId,
       originYardId: booking.originYardId,
       destinationYardId: booking.destinationYardId,
       totalWagons,
@@ -428,6 +431,22 @@ export class BookingPricingService {
     };
   }
 
+  /**
+   * LIVE rates this booking may price off.
+   *
+   * A shipping-line booking sees only its own line's rates; a customer booking
+   * only the standard ones. Line rates override rather than stack, and the
+   * standard rate is not a fallback — a lane the line has no rate for falls
+   * through to the existing "no rate configured" hard block, which is the
+   * intended outcome rather than silently billing the customer price.
+   */
+  private async liveRatesForBooking(booking: Booking): Promise<Rate[]> {
+    const rates = await this.ratesService.findLiveRates();
+    return booking.shippingLineCompanyId
+      ? rates.filter((r) => r.shippingLineCompanyId === booking.shippingLineCompanyId)
+      : rates.filter((r) => !r.shippingLineCompanyId);
+  }
+
   private async requireBooking(id: string): Promise<Booking> {
     const booking = await this.bookingsRepository.findByIdWithFiles(id);
     if (!booking) throw new NotFoundException(`Booking ${id} not found`);
@@ -512,7 +531,7 @@ export class BookingPricingService {
     warnings: string[];
     blocked: string[];
   }> {
-    const liveRates = await this.ratesService.findLiveRates();
+    const liveRates = await this.liveRatesForBooking(booking);
     const paymentCurrency = booking.paymentCurrency;
     const isEtbBooking = paymentCurrency === 'ETB';
     const usdToEtb = isEtbBooking ? await this.exchangeService.getRate('USD', 'ETB') : 1;
@@ -713,7 +732,7 @@ export class BookingPricingService {
       return { lineItems: [], usedRates: [] };
     }
 
-    const liveRates = await this.ratesService.findLiveRates();
+    const liveRates = await this.liveRatesForBooking(booking);
     const paymentCurrency = booking.paymentCurrency;
     const isEtbBooking = paymentCurrency === 'ETB';
     const usdToEtb = isEtbBooking ? await this.exchangeService.getRate('USD', 'ETB') : 1;
diff --git a/apps/edr-freight-api/src/modules/bookings/clearance.util.ts b/apps/edr-freight-api/src/modules/bookings/clearance.util.ts
index e28917715..c7fc71449 100644
--- a/apps/edr-freight-api/src/modules/bookings/clearance.util.ts
+++ b/apps/edr-freight-api/src/modules/bookings/clearance.util.ts
@@ -16,6 +16,16 @@ type Freight = 'container' | 'bulk';
  */
 export const INTERCITY_DOCUMENTS_SETTING_CODE = 'intercity_documents';
 
+/**
+ * The document set a shipping line uploads on a booking it initiated.
+ *
+ * Shipping lines book without a contract, so none of the trade-direction /
+ * freight / customs matrix below applies to them — this one admin-configured
+ * set is what Operations reviews before the booking may be completed.
+ */
+export const SHIPPING_LINE_DOCUMENTS_SETTING_CODE =
+  'shipping_line_booking_documents';
+
 /** Trade direction → clearance operation. DOMESTIC has no customs clearance. */
 function operationFor(tradeDirection: string): Op | null {
   if (tradeDirection === 'IMPORT') return 'import';
@@ -67,6 +77,20 @@ export function clearanceCodesForBooking(booking: Booking): {
   outputCode: string | null;
   includesCustoms: boolean;
 } {
+  // Shipping-line bookings resolve to their own single set and never reach the
+  // matrix below: they have no contract, and their trade direction / freight
+  // type are placeholders until the booking is completed, so the customer codes
+  // would resolve to a set that was never meant for them. Keyed off the owner
+  // column, which is NULL on every customer booking — so no customer booking
+  // can take this branch.
+  if (booking.shippingLineCompanyId) {
+    return {
+      inputCode: SHIPPING_LINE_DOCUMENTS_SETTING_CODE,
+      outputCode: null,
+      includesCustoms: false,
+    };
+  }
+
   // Customs applies when EITHER the service type bundles it OR the booking was
   // created with customsClearingEnabled (copied from the contract). Contract
   // bookings carry customsClearingEnabled even when the serviceType relation
diff --git a/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts b/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
index dbc306e3b..cdcfbc3eb 100644
--- a/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
+++ b/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
@@ -108,15 +108,34 @@ export class Booking extends BaseEntity {
   // @JoinColumn({ name: 'customer_id' })
   // customer?: Customer;
 
-  // Every booking is billed to a company — government bookings bill to a seeded
-  // government company (companies.kind = 'government'). Enforced NOT NULL.
-  @Column({ name: 'company_id', type: 'uuid' })
+  // Every CUSTOMER booking is billed to a company — government bookings bill to
+  // a seeded government company (companies.kind = 'government'). NULL only on a
+  // shipping-line booking, owned by `shippingLineCompanyId` instead; a DB CHECK
+  // enforces that exactly one of the two is set.
+  @Column({ name: 'company_id', type: 'uuid', nullable: true })
   companyId!: string;
 
   @ManyToOne(() => Company, { nullable: true })
   @JoinColumn({ name: 'company_id' })
   company?: Company | null;
 
+  /**
+   * The shipping-line ACCOUNT that owns this booking, when it is not a
+   * customer's. Shipping lines book without a contract and are not `companies`
+   * rows (no TIN, licence or operational profiles), so they get their own owner
+   * column rather than a synthetic company. NULL on every customer booking.
+   *
+   * Deliberately NOT `shippingLineId` above: that is cargo metadata naming the
+   * carrier line that moves the goods (`freight.shipping_lines`, reference data
+   * set on customer bookings too). This points at `shipping_line_companies` —
+   * the portal account — and the two are unrelated.
+   *
+   * No relation is declared: `ShippingLineCompany` lives in its own module and
+   * the column is read by id, matching how the migration leaves it FK-free.
+   */
+  @Column({ name: 'shipping_line_company_id', type: 'uuid', nullable: true })
+  shippingLineCompanyId?: string | null;
+
   /**
    * The operational profile (importer/exporter/forwarder) this booking belongs
    * to. Stamped at creation from the booking's trade direction (IMPORT→importer,
@@ -125,7 +144,9 @@ export class Booking extends BaseEntity {
    * commercial bookings resolve it from trade direction / active mode;
    * government bookings carry the explicitly-picked government profile.
    */
-  @Column({ name: 'company_profile_id', type: 'uuid' })
+  // NULL only on a shipping-line booking — shipping lines have no operational
+  // profiles. Always set on a customer booking, as before.
+  @Column({ name: 'company_profile_id', type: 'uuid', nullable: true })
   companyProfileId!: string;
 
   @ManyToOne(() => CompanyProfile, { nullable: true })
@@ -259,7 +280,7 @@ export class Booking extends BaseEntity {
   @Column({ name: 'contract_type', type: 'varchar', length: 20 })
   contractType!: string;
 
-  @Column({ name: 'service_type_id', type: 'uuid' })
+  @Column({ name: 'service_type_id', type: 'uuid', nullable: true })
   serviceTypeId!: string;
 
   @ManyToOne(() => ServiceType)
@@ -337,14 +358,14 @@ export class Booking extends BaseEntity {
   @Column({ name: 'equipment_return', type: 'varchar', length: 20 })
   equipmentReturn!: string;
 
-  @Column({ name: 'origin_yard_id', type: 'uuid' })
+  @Column({ name: 'origin_yard_id', type: 'uuid', nullable: true })
   originYardId!: string;
 
   @ManyToOne(() => Yard) 
   @JoinColumn({ name: 'origin_yard_id' })
   originYard?: Yard;
 
-  @Column({ name: 'destination_yard_id', type: 'uuid' })
+  @Column({ name: 'destination_yard_id', type: 'uuid', nullable: true })
   destinationYardId!: string;
 
   @ManyToOne(() => Yard)
@@ -354,7 +375,7 @@ export class Booking extends BaseEntity {
   @Column({ name: 'trade_direction', type: 'varchar', length: 10 })
   tradeDirection!: string;
 
-  @Column({ name: 'freight_type', type: 'varchar', length: 20 })
+  @Column({ name: 'freight_type', type: 'varchar', length: 20, nullable: true })
   freightType!: string;
 
   @Column({ name: 'cargo_type_id', type: 'uuid', nullable: true })
diff --git a/apps/edr-freight-api/src/modules/companies/companies.module.ts b/apps/edr-freight-api/src/modules/companies/companies.module.ts
index aa0a00dff..b990aa8f0 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.module.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.module.ts
@@ -46,8 +46,9 @@ import { VerifaydaModule } from "../verifayda/verifayda.module";
     // Fayda identity verification for the company's owner and PoA.
     VerifaydaModule,
     // `GET /companies/getInfo` serves both portal audiences: it must recognise a
-    // shipping-line session, which has no company row to look up.
-    ShippingLineCompaniesModule,
+    // shipping-line session, which has no company row to look up. forwardRef
+    // because that module imports BillingModule, which imports this one.
+    forwardRef(() => ShippingLineCompaniesModule),
   ],
   controllers: [CompaniesController],
   providers: [
diff --git a/apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts b/apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts
index eccb14017..73ae42a0d 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts
@@ -75,6 +75,14 @@ export class CreateRateDto {
   @IsUUID()
   destinationYardId?: string;
 
+  @ApiPropertyOptional({
+    description:
+      'FK to shipping_line_companies.id — set to price this rate for one shipping line only. Omitted/null = the standard rate every customer pays. A line rate overrides the standard one for that line\'s bookings.',
+  })
+  @IsOptional()
+  @IsUUID()
+  shippingLineCompanyId?: string;
+
   @ApiPropertyOptional({ enum: CURRENCIES })
   @IsOptional()
   @IsIn([...CURRENCIES])
diff --git a/apps/edr-freight-api/src/modules/rule-engine/dto/list-rule-engine-query.dto.ts b/apps/edr-freight-api/src/modules/rule-engine/dto/list-rule-engine-query.dto.ts
index d22bd84a7..774037e36 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/dto/list-rule-engine-query.dto.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/dto/list-rule-engine-query.dto.ts
@@ -141,6 +141,22 @@ export class ListRatesQueryDto extends PaginationQueryDto {
   @IsString()
   @MaxLength(200)
   trigger?: string;
+
+  @ApiPropertyOptional({
+    description: 'Filter to one shipping line\'s rates.',
+  })
+  @IsOptional()
+  @IsUUID()
+  shippingLineCompanyId?: string;
+
+  @ApiPropertyOptional({
+    description:
+      'true = only shipping-line rates (any line), false = only standard customer rates. Omitted = both. Powers the Shipping line tab.',
+  })
+  @IsOptional()
+  @Transform(toOptionalBoolean)
+  @IsBoolean()
+  isShippingLineRate?: boolean;
 }
 
 export class ListWeightLimitRulesQueryDto extends PaginationQueryDto {
diff --git a/apps/edr-freight-api/src/modules/rule-engine/entities/rate.entity.ts b/apps/edr-freight-api/src/modules/rule-engine/entities/rate.entity.ts
index 925a3555a..c60d03d31 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/entities/rate.entity.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/entities/rate.entity.ts
@@ -1,5 +1,6 @@
 import { BaseEntity } from '@edr/api-common';
 import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+import { ShippingLineCompany } from '../../shipping-lines/entities/shipping-line-company.entity';
 import { CargoType } from './cargo-type.entity';
 import { ContainerType } from './container-type.entity';
 import { Yard } from './yard.entity';
@@ -108,6 +109,7 @@ export type RateTrigger = typeof RATE_TRIGGERS[number];
 @Index(['trigger'])
 @Index(['originYardId'])
 @Index(['destinationYardId'])
+@Index(['shippingLineCompanyId'])
 export class Rate extends BaseEntity {
   @Column({ name: 'rate_type', type: 'varchar', length: 50 })
   rateType!: RateType;
@@ -155,6 +157,23 @@ export class Rate extends BaseEntity {
   @JoinColumn({ name: 'destination_yard_id' })
   destinationYard?: Yard | null;
 
+  /**
+   * The shipping line this rate belongs to, or NULL for the standard rate every
+   * customer pays. A booking owned by a shipping line prices exclusively off
+   * that line's rates — the standard rate is NOT a fallback, so a missing line
+   * rate hard-blocks the booking rather than quietly billing the customer price.
+   *
+   * Points at `shipping_line_companies` (the portal account that books capacity),
+   * not `shipping_lines` (carrier reference data behind the SHIPPING_LINE
+   * trigger). The two are unrelated despite the similar names.
+   */
+  @Column({ name: 'shipping_line_company_id', type: 'uuid', nullable: true })
+  shippingLineCompanyId?: string | null;
+
+  @ManyToOne(() => ShippingLineCompany, { nullable: true, eager: false })
+  @JoinColumn({ name: 'shipping_line_company_id' })
+  shippingLineCompany?: ShippingLineCompany | null;
+
   @Column({ name: 'currency', type: 'varchar', length: 5 })
   currency!: string;
 
diff --git a/apps/edr-freight-api/src/modules/rule-engine/interfaces/rates.repository.interface.ts b/apps/edr-freight-api/src/modules/rule-engine/interfaces/rates.repository.interface.ts
index 9797ff715..ba2509068 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/interfaces/rates.repository.interface.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/interfaces/rates.repository.interface.ts
@@ -16,6 +16,8 @@ export interface IRatesRepository {
     rateType: string;
     /** Omitted for singly-resolved rates — see the repository implementation. */
     rateUnit?: string;
+    /** Owning shipping line; null/omitted = the standard customer rate. */
+    shippingLineCompanyId?: string | null;
     containerTypeId?: string | null;
     cargoTypeId?: string | null;
     tradeDirection?: string | null;
diff --git a/apps/edr-freight-api/src/modules/rule-engine/repositories/rates.repository.ts b/apps/edr-freight-api/src/modules/rule-engine/repositories/rates.repository.ts
index 7417987dc..8a739095e 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/repositories/rates.repository.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/repositories/rates.repository.ts
@@ -69,6 +69,7 @@ export class RatesRepository implements IRatesRepository {
   findByPattern(pattern: {
     rateType: string;
     rateUnit?: string;
+    shippingLineCompanyId?: string | null;
     containerTypeId?: string | null;
     cargoTypeId?: string | null;
     tradeDirection?: string | null;
@@ -85,6 +86,16 @@ export class RatesRepository implements IRatesRepository {
       qb.andWhere('rate.rate_unit = :rateUnit', { rateUnit: pattern.rateUnit });
     }
 
+    // The owner is part of the identity: a line's rate for a lane is a
+    // different rate from the standard one, not a duplicate of it.
+    if (pattern.shippingLineCompanyId) {
+      qb.andWhere('rate.shipping_line_company_id = :shippingLineCompanyId', {
+        shippingLineCompanyId: pattern.shippingLineCompanyId,
+      });
+    } else {
+      qb.andWhere('rate.shipping_line_company_id IS NULL');
+    }
+
     if (pattern.containerTypeId) {
       qb.andWhere('rate.container_type_id = :containerTypeId', { containerTypeId: pattern.containerTypeId });
     } else {
@@ -139,8 +150,22 @@ export class RatesRepository implements IRatesRepository {
       // yards joined the route columns have only ids to render.
       .leftJoinAndSelect('rate.originYard', 'originYard')
       .leftJoinAndSelect('rate.destinationYard', 'destinationYard')
+      // The shipping-line tab renders the owning line's name, not its id.
+      .leftJoinAndSelect('rate.shippingLineCompany', 'shippingLineCompany')
       .orderBy('rate.createdAt', query.sortOrder ?? 'DESC');
 
+    if (query.shippingLineCompanyId) {
+      qb.andWhere('rate.shippingLineCompanyId = :shippingLineCompanyId', {
+        shippingLineCompanyId: query.shippingLineCompanyId,
+      });
+    } else if (query.isShippingLineRate !== undefined) {
+      // Tab filter: shipping-line rates (any line) vs standard customer rates.
+      qb.andWhere(
+        query.isShippingLineRate
+          ? 'rate.shippingLineCompanyId IS NOT NULL'
+          : 'rate.shippingLineCompanyId IS NULL',
+      );
+    }
     if (query.status) {
       qb.andWhere('rate.status = :status', { status: query.status });
     }
@@ -164,7 +189,7 @@ export class RatesRepository implements IRatesRepository {
     }
     if (query.search) {
       qb.andWhere(
-        '(rate.rateType ILIKE :search OR rate.status ILIKE :search OR rate.rateUnit ILIKE :search OR rate.currency ILIKE :search)',
+        '(rate.rateType ILIKE :search OR rate.status ILIKE :search OR rate.rateUnit ILIKE :search OR rate.currency ILIKE :search OR shippingLineCompany.name ILIKE :search)',
         { search: `%${query.search}%` },
       );
     }
diff --git a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts
index d487387b8..549a35fa2 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts
@@ -69,6 +69,7 @@ import { YardFacilitiesService } from './services/yard-facilities.service';
 import { RuleEngineService } from './rule-engine.service';
 
 import { NotificationInboxModule } from '../notification-inbox/notification-inbox.module';
+import { ShippingLineCompaniesModule } from '../shipping-lines/shipping-line-companies.module';
 import { WagonTypesModule } from '../wagon-types/wagon-types.module';
 
 import { BookingCargoModifier } from '../bookings/entities/booking-cargo-modifier.entity';
@@ -102,6 +103,9 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
     // Rated wagon capacities — cargo types validate their per-wagon tonnage cap
     // against them (a cap above the rating is a typo, not a policy).
     WagonTypesModule,
+    // Rates may be scoped to one shipping line; creating such a rate validates
+    // the line exists and is active.
+    ShippingLineCompaniesModule,
   ],
   controllers: [
     CargoTypesController,
diff --git a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.spec.ts b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.spec.ts
index 281f2d1b2..c530e5314 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.spec.ts
@@ -527,3 +527,145 @@ describe('RuleEngineService — fuel surcharge (per lane + cargo type)', () => {
     expect(fuelMods(result)).toHaveLength(0);
   });
 });
+
+describe('RuleEngineService — shipping-line rates override the standard ones', () => {
+  const LINE = 'slc-msc';
+
+  /** Standard customer container-import rate on the lane. */
+  const standardBase: Rate = {
+    id: 'rate-standard-20',
+    rateType: 'CONTAINER_IMPORT',
+    trigger: 'ALWAYS',
+    rateValue: 1000,
+    rateUnit: 'PER_CONTAINER',
+    currency: 'USD',
+    status: 'LIVE',
+    containerTypeId: 'ct-20',
+    cargoTypeId: null,
+    shippingLineCompanyId: null,
+    originYardId: 'yard-dj',
+    destinationYardId: 'yard-adama',
+  } as Rate;
+
+  /** The same lane, priced for one shipping line. */
+  const lineBase: Rate = {
+    ...standardBase,
+    id: 'rate-line-20',
+    rateValue: 1200,
+    shippingLineCompanyId: LINE,
+  } as Rate;
+
+  const standardHazard: Rate = {
+    id: 'rate-hazard-standard',
+    rateType: 'HAZARD_SURCHARGE',
+    trigger: 'HAZARDOUS',
+    rateValue: 50,
+    rateUnit: 'PER_CONTAINER',
+    currency: 'USD',
+    status: 'LIVE',
+    containerTypeId: null,
+    cargoTypeId: null,
+    shippingLineCompanyId: null,
+  } as Rate;
+
+  const lineHazard: Rate = {
+    ...standardHazard,
+    id: 'rate-hazard-line',
+    rateValue: 80,
+    shippingLineCompanyId: LINE,
+  } as Rate;
+
+  const buildService = (rates: Rate[]) =>
+    new RuleEngineService(
+      { findById: jest.fn().mockResolvedValue(null) } as never,
+      { findById: jest.fn().mockResolvedValue(null) } as never,
+      {
+        findActiveByContainerTypeId: jest
+          .fn()
+          .mockResolvedValue([{ id: 'wlr-20', maxVgmTons: 20, maxCapacityTons: null }]),
+      } as never,
+      { findAllActive: jest.fn().mockResolvedValue([]) } as never,
+      { findLiveRates: jest.fn().mockResolvedValue(rates) } as never,
+      { findById: jest.fn().mockResolvedValue(null) } as never,
+      {} as never,
+    );
+
+  // One 20ft at 25 t against a 20 t limit → 5 t excess.
+  const bookingInput = (
+    overrides: Partial<BookingEvaluationInput> = {},
+  ): BookingEvaluationInput => ({
+    serviceTypeId: 'svc-1',
+    paymentCurrency: 'USD',
+    tradeDirection: 'IMPORT',
+    isHazardous: false,
+    totalWagons: 1,
+    originYardId: 'yard-dj',
+    destinationYardId: 'yard-adama',
+    containers: [
+      { containerTypeId: 'ct-20', quantity: 1, vgmPerUnitTons: 25, totalVgmTons: 25 },
+    ],
+    ...overrides,
+  });
+
+  const overweightOf = (result: { appliedModifiers: Array<{ surchargeCode: string }> }) =>
+    result.appliedModifiers.filter((m) => m.surchargeCode === 'OVERWEIGHT_PER_TON');
+
+  it('derives a line booking\'s overweight from the LINE\'s base rate, not the standard one', async () => {
+    const result = await buildService([standardBase, lineBase]).evaluate(
+      bookingInput({ shippingLineCompanyId: LINE }),
+    );
+    const ow = overweightOf(result);
+    expect(ow).toHaveLength(1);
+    // The line's 1200 / (2 × 20) = 30 USD/t, not the standard 1000 → 25 USD/t.
+    expect(ow[0]).toMatchObject({
+      rateId: lineBase.id,
+      unitPriceUsd: 30,
+      calculatedAmount: 150,
+    });
+  });
+
+  it('keeps a customer booking on the standard rate even when a line rate exists', async () => {
+    const result = await buildService([standardBase, lineBase]).evaluate(bookingInput());
+    const ow = overweightOf(result);
+    expect(ow).toHaveLength(1);
+    expect(ow[0]).toMatchObject({
+      rateId: standardBase.id,
+      unitPriceUsd: 25,
+      calculatedAmount: 125,
+    });
+  });
+
+  it('does not fall back to the standard rate when the line has none for the lane', async () => {
+    const result = await buildService([standardBase]).evaluate(
+      bookingInput({ shippingLineCompanyId: LINE }),
+    );
+    // No line rate on the lane → nothing to derive from. Base freight is what
+    // hard-blocks the booking; the standard 1000 must never be borrowed here.
+    expect(overweightOf(result)).toHaveLength(0);
+  });
+
+  it('bills the line\'s own surcharge and never the standard one alongside it', async () => {
+    const result = await buildService([
+      standardBase,
+      lineBase,
+      standardHazard,
+      lineHazard,
+    ]).evaluate(bookingInput({ shippingLineCompanyId: LINE, isHazardous: true }));
+
+    const hazard = result.appliedModifiers.filter(
+      (m) => m.surchargeCode === 'HAZARD_SURCHARGE',
+    );
+    expect(hazard).toHaveLength(1);
+    expect(hazard[0]).toMatchObject({ rateId: lineHazard.id, calculatedAmount: 80 });
+  });
+
+  it('hard-blocks a requested service the line has no surcharge rate for', async () => {
+    const result = await buildService([standardBase, lineBase, standardHazard]).evaluate(
+      bookingInput({ shippingLineCompanyId: LINE, isHazardous: true }),
+    );
+    // The standard hazard rate exists but belongs to customers, so the line's
+    // hazardous booking must block rather than borrow it.
+    expect(result.hardBlocked).toHaveLength(1);
+    expect(result.hardBlocked[0]).toContain('hazardous');
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
index 908d00ecc..5c9055415 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
@@ -74,6 +74,16 @@ export interface BookingEvaluationInput {
   isGovernment?: boolean;
   allowConsolidation?: boolean;
   shippingLineId?: string | null;
+  /**
+   * The shipping line that OWNS this booking (`bookings.shipping_line_company_id`),
+   * when it is a shipping-line booking rather than a customer one. Such a booking
+   * prices exclusively off that line's own rates — see {@link ratesForOwner}.
+   *
+   * Not to be confused with `shippingLineId` above, which is cargo metadata
+   * naming the carrier that physically moves the goods and only feeds the
+   * SHIPPING_LINE double-handling trigger.
+   */
+  shippingLineCompanyId?: string | null;
   /**
    * The booking's rail leg. Import overweight derives its per-ton price from
    * this route's own container freight rate, so the engine needs the yards.
@@ -282,7 +292,10 @@ export class RuleEngineService {
     // scope) must contribute exactly ONE line. Duplicate LIVE rate rows — e.g.
     // from a non-idempotent seeder — would otherwise repeat the same surcharge
     // many times and inflate the total, so we collapse them to one row each.
-    const liveRates = await this.ratesRepo.findLiveRates();
+    const liveRates = this.ratesForOwner(
+      await this.ratesRepo.findLiveRates(),
+      input.shippingLineCompanyId,
+    );
     const surchargeRates = this.dedupeRatesBySignature(
       liveRates.filter((r) => r.trigger && r.trigger !== 'ALWAYS'),
     );
@@ -812,6 +825,28 @@ export class RuleEngineService {
     return rate.rateType ?? rate.trigger;
   }
 
+  /**
+   * Narrow the LIVE rate pool to the ones this booking's owner may price off.
+   *
+   * A customer booking sees only standard rates (no owner) — a shipping line's
+   * negotiated price must never leak into a customer quote. A shipping-line
+   * booking sees only that line's own rates: line rates OVERRIDE the standard
+   * ones rather than stacking on them, and the standard rate is deliberately
+   * NOT a fallback, so a lane the line has no rate for hard-blocks downstream
+   * (base freight already blocks on "no rate for this route") instead of
+   * quietly billing the line at the customer price.
+   *
+   * Filtering once, here, is what makes the override apply uniformly: every
+   * downstream lookup (base freight, derived overweight, empty return, lashing,
+   * fuel, and the additive surcharges) reads from this same pool, so none of
+   * them needs its own owner check.
+   */
+  private ratesForOwner(rates: Rate[], shippingLineCompanyId?: string | null): Rate[] {
+    return shippingLineCompanyId
+      ? rates.filter((r) => r.shippingLineCompanyId === shippingLineCompanyId)
+      : rates.filter((r) => !r.shippingLineCompanyId);
+  }
+
   /**
    * Collapse rates that describe the same charge to a single representative.
    *
diff --git a/apps/edr-freight-api/src/modules/rule-engine/services/rates.duplicate-pattern.spec.ts b/apps/edr-freight-api/src/modules/rule-engine/services/rates.duplicate-pattern.spec.ts
index 23d96da89..0a4108a4e 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/services/rates.duplicate-pattern.spec.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/services/rates.duplicate-pattern.spec.ts
@@ -61,6 +61,8 @@ describe('RatesService — one rate per pattern', () => {
         })),
       } as never,
       { findById: jest.fn().mockResolvedValue(null) } as never,
+      // Shipping line companies — these rates carry no owner, so it is never hit.
+      { findById: jest.fn() } as never,
     );
   });
 
diff --git a/apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts b/apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts
index 232cd9299..1902a757a 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts
@@ -8,6 +8,8 @@ import {
 } from '@nestjs/common';
 import { PaginatedResponse, YardCountry } from '@edr/types';
 import { IsNull, Not } from 'typeorm';
+import { ShippingLineStatus } from '../../shipping-lines/entities/shipping-line-company.entity';
+import { ShippingLineCompaniesService } from '../../shipping-lines/shipping-line-companies.service';
 import { CreateRateDto } from '../dto/create-rate.dto';
 import { ListRatesQueryDto } from '../dto/list-rule-engine-query.dto';
 import { UpdateRateDto } from '../dto/update-rate.dto';
@@ -39,6 +41,7 @@ export class RatesService {
     private readonly yardsRepository: IYardsRepository,
     @Inject(CARGO_TYPES_REPOSITORY)
     private readonly cargoTypesRepository: ICargoTypesRepository,
+    private readonly shippingLineCompaniesService: ShippingLineCompaniesService,
   ) {}
 
   /** List rates — standard paginated envelope with server-side search. */
@@ -491,6 +494,7 @@ export class RatesService {
     rateType: string;
     /** Passed only for additive surcharges — see {@link resolvesSingleRate}. */
     rateUnit?: string;
+    shippingLineCompanyId: string | null;
     containerTypeId: string | null;
     cargoTypeId: string | null;
     tradeDirection: string | null;
@@ -508,6 +512,35 @@ export class RatesService {
     }
   }
 
+  /**
+   * Validate the shipping line a rate is scoped to, when any.
+   *
+   * A shipping line only ever ships import — the export leg is sold through the
+   * customer's contract — so a line rate carrying an EXPORT direction is
+   * rejected here as well as by `CK_rates_shipping_line_import_only`.
+   * Returns the owner id to store (null = the standard customer rate).
+   */
+  private async resolveShippingLineScope(
+    shippingLineCompanyId: string | null | undefined,
+    tradeDirection: string | null,
+  ): Promise<string | null> {
+    if (!shippingLineCompanyId) return null;
+
+    // Throws NotFoundException when the line does not exist.
+    const line = await this.shippingLineCompaniesService.findById(shippingLineCompanyId);
+    if (line.status !== ShippingLineStatus.Active) {
+      throw new BadRequestException(
+        `${line.name} is ${line.status} — rates can only be configured for an active shipping line.`,
+      );
+    }
+    if (tradeDirection && tradeDirection !== 'IMPORT') {
+      throw new BadRequestException(
+        'Shipping line rates are import-only — the export leg is priced through the customer contract.',
+      );
+    }
+    return shippingLineCompanyId;
+  }
+
   /** Create a rate in DRAFT status. */
   async create(dto: CreateRateDto, proposedByStaffId: string): Promise<Rate> {
     const appliesTo = dto.appliesTo as Rate['appliesTo'];
@@ -568,6 +601,11 @@ export class RatesService {
       destinationYardId: dto.destinationYardId,
     });
 
+    const shippingLineCompanyId = await this.resolveShippingLineScope(
+      dto.shippingLineCompanyId,
+      tradeDirection,
+    );
+
     const rateType = deriveRateType({
       appliesTo,
       trigger,
@@ -602,6 +640,7 @@ export class RatesService {
     await this.assertNoDuplicatePattern({
       rateType,
       ...(this.resolvesSingleRate(appliesTo, trigger) ? {} : { rateUnit }),
+      shippingLineCompanyId,
       containerTypeId,
       cargoTypeId,
       tradeDirection,
@@ -614,6 +653,7 @@ export class RatesService {
       appliesTo,
       trigger,
       rateType,
+      shippingLineCompanyId,
       containerTypeId,
       cargoTypeId,
       tradeDirection,
@@ -791,6 +831,17 @@ export class RatesService {
     updates.originYardId = yardScope.originYardId;
     updates.destinationYardId = yardScope.destinationYardId;
 
+    // The owning line is re-validated on every edit: a patch that flips the
+    // direction to EXPORT has to be refused for a line rate, and a patch that
+    // moves the rate to a suspended line too.
+    const shippingLineCompanyId = await this.resolveShippingLineScope(
+      dto.shippingLineCompanyId !== undefined
+        ? dto.shippingLineCompanyId
+        : existing.shippingLineCompanyId,
+      updates.tradeDirection,
+    );
+    updates.shippingLineCompanyId = shippingLineCompanyId;
+
     // Keep the derived rateType in sync with whatever changed.
     const rateType = deriveRateType({
       appliesTo,
@@ -839,6 +890,7 @@ export class RatesService {
     await this.assertNoDuplicatePattern({
       rateType,
       ...(this.resolvesSingleRate(appliesTo, trigger) ? {} : { rateUnit }),
+      shippingLineCompanyId,
       containerTypeId: updates.containerTypeId,
       cargoTypeId: updates.cargoTypeId,
       tradeDirection: updates.tradeDirection,
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/dto/cancel-shipping-line-booking.dto.ts b/apps/edr-freight-api/src/modules/shipping-lines/dto/cancel-shipping-line-booking.dto.ts
new file mode 100644
index 000000000..1064cdeb4
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/dto/cancel-shipping-line-booking.dto.ts
@@ -0,0 +1,15 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsOptional, IsString, MaxLength } from "class-validator";
+
+/** Payload for a shipping line cancelling its own booking. */
+export class CancelShippingLineBookingDto {
+  @ApiProperty({
+    required: false,
+    description:
+      "Why the booking is being cancelled. Recorded on the booking's review-note log.",
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  reason?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/dto/initiate-shipping-line-booking.dto.ts b/apps/edr-freight-api/src/modules/shipping-lines/dto/initiate-shipping-line-booking.dto.ts
new file mode 100644
index 000000000..6cdcdd1cf
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/dto/initiate-shipping-line-booking.dto.ts
@@ -0,0 +1,38 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsIn, IsOptional, IsUUID } from "class-validator";
+
+import { FREIGHT_TYPES } from "../../bookings/entities/booking.entity";
+
+/**
+ * Payload for initiating a bare shipping-line booking.
+ *
+ * A customer's bare booking inherits its lane from the contract it is initiated
+ * under. Shipping lines have no contract, so the lane comes from a route the
+ * caller picks — one choice that yields origin, destination and trade direction
+ * together, rather than three fields that can contradict each other.
+ */
+export class InitiateShippingLineBookingDto {
+  @ApiProperty({
+    description:
+      "The lane being booked. Supplies the booking's origin yard, destination yard and trade direction.",
+  })
+  @IsUUID()
+  routeId!: string;
+
+  @ApiProperty({
+    required: false,
+    description: "Service type being booked.",
+  })
+  @IsOptional()
+  @IsUUID()
+  serviceTypeId?: string;
+
+  @ApiProperty({
+    required: false,
+    enum: FREIGHT_TYPES,
+    description: "Freight type. Defaults to CONTAINER.",
+  })
+  @IsOptional()
+  @IsIn(FREIGHT_TYPES)
+  freightType?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/dto/shipping-line-credit.dto.ts b/apps/edr-freight-api/src/modules/shipping-lines/dto/shipping-line-credit.dto.ts
new file mode 100644
index 000000000..4e659e317
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/dto/shipping-line-credit.dto.ts
@@ -0,0 +1,51 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { Type } from "class-transformer";
+import {
+  ArrayNotEmpty,
+  IsArray,
+  IsInt,
+  IsOptional,
+  IsString,
+  IsUUID,
+  MaxLength,
+  Min,
+  MinLength,
+} from "class-validator";
+
+/** Finance's request to bill a batch of unbilled credits as one invoice. */
+export class GenerateCreditInvoiceDto {
+  @ApiProperty({
+    description:
+      "The unbilled credits to bill. All must belong to the same shipping line and share one currency.",
+    type: [String],
+    format: "uuid",
+  })
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsUUID("4", { each: true })
+  creditIds!: string[];
+
+  @ApiPropertyOptional({
+    description:
+      "Pay window in days from issue. Defaults to the standard invoice term.",
+    minimum: 1,
+    example: 14,
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  dueInDays?: number;
+}
+
+/** Write-off of a single unbilled credit. */
+export class CancelCreditDto {
+  @ApiProperty({
+    description: "Why the credit is being written off. Recorded on the row.",
+    example: "Booking voided before departure",
+  })
+  @IsString()
+  @MinLength(3)
+  @MaxLength(255)
+  reason!: string;
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/entities/shipping-line-credit.entity.ts b/apps/edr-freight-api/src/modules/shipping-lines/entities/shipping-line-credit.entity.ts
new file mode 100644
index 000000000..3c81968f6
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/entities/shipping-line-credit.entity.ts
@@ -0,0 +1,110 @@
+import { BaseEntity } from "@edr/api-common";
+import { Column, Entity, Index, JoinColumn, ManyToOne } from "typeorm";
+
+import { Booking } from "../../bookings/entities/booking.entity";
+import { Invoice } from "../../billing/entities/invoice.entity";
+import { ShippingLineCompany } from "./shipping-line-company.entity";
+
+/** Where a credit sits between "service used" and "money received". */
+export enum ShippingLineCreditStatus {
+  /** Service used, priced, not yet on any invoice. Counts as debt. */
+  Unbilled = "UNBILLED",
+  /** Finance put it on an invoice; awaiting payment. Still counts as debt. */
+  Billed = "BILLED",
+  /** The invoice settled. Terminal — no longer debt, and never re-billed. */
+  Paid = "PAID",
+  /** Written off / booking voided. Terminal, excluded from every total. */
+  Cancelled = "CANCELLED",
+}
+
+/** Statuses a shipping line still owes money for. */
+export const OUTSTANDING_CREDIT_STATUSES = [
+  ShippingLineCreditStatus.Unbilled,
+  ShippingLineCreditStatus.Billed,
+] as const;
+
+/**
+ * What a shipping line owes for one booking.
+ *
+ * Shipping lines get the service first and pay later, so a booking of theirs
+ * raises no invoice and passes no payment gate — it raises one of these. The
+ * amount is frozen when the booking is priced and is never recalculated, so a
+ * later rate change cannot silently alter a debt already incurred.
+ *
+ * Finance batches unbilled credits into one invoice (see
+ * `ShippingLineCreditsService.generateInvoice`); the line pays that invoice
+ * through the ordinary CBE flow; settlement flips the batch to PAID and the
+ * debt disappears. The outstanding figure is always derived by summing
+ * {@link OUTSTANDING_CREDIT_STATUSES} rows — there is no balance column,
+ * because a stored balance is one missed UPDATE away from being a lie.
+ */
+@Entity({ schema: "freight", name: "shipping_line_credits" })
+@Index(["shippingLineCompanyId", "status"])
+@Index(["invoiceId"])
+export class ShippingLineCredit extends BaseEntity {
+  /** The line that owes this. */
+  @Column({ name: "shipping_line_company_id", type: "uuid" })
+  shippingLineCompanyId!: string;
+
+  @ManyToOne(() => ShippingLineCompany)
+  @JoinColumn({ name: "shipping_line_company_id" })
+  shippingLineCompany?: ShippingLineCompany;
+
+  /**
+   * The booking that incurred the charge. Unique among live rows (partial
+   * index excludes soft-deleted and CANCELLED), so one booking can never be
+   * billed twice.
+   */
+  @Column({ name: "booking_id", type: "uuid" })
+  bookingId!: string;
+
+  @ManyToOne(() => Booking)
+  @JoinColumn({ name: "booking_id" })
+  booking?: Booking;
+
+  /** Frozen at pricing time. Never recalculated. */
+  @Column({ name: "amount", type: "numeric", precision: 14, scale: 2 })
+  amount!: number;
+
+  @Column({ name: "currency", type: "varchar", length: 8, default: "ETB" })
+  currency!: string;
+
+  @Column({
+    name: "status",
+    type: "enum",
+    enum: ShippingLineCreditStatus,
+    default: ShippingLineCreditStatus.Unbilled,
+  })
+  status!: ShippingLineCreditStatus;
+
+  /** What the charge is for; becomes the invoice line description. */
+  @Column({ name: "description", type: "varchar", length: 255, nullable: true })
+  description?: string | null;
+
+  /** The invoice this credit was billed on; null while UNBILLED. */
+  @Column({ name: "invoice_id", type: "uuid", nullable: true })
+  invoiceId?: string | null;
+
+  @ManyToOne(() => Invoice)
+  @JoinColumn({ name: "invoice_id" })
+  invoice?: Invoice;
+
+  /** When finance put it on an invoice. */
+  @Column({ name: "billed_at", type: "timestamptz", nullable: true })
+  billedAt?: Date | null;
+
+  /** When that invoice settled. */
+  @Column({ name: "paid_at", type: "timestamptz", nullable: true })
+  paidAt?: Date | null;
+
+  @Column({ name: "cancelled_at", type: "timestamptz", nullable: true })
+  cancelledAt?: Date | null;
+
+  @Column({
+    name: "cancellation_reason",
+    type: "varchar",
+    length: 255,
+    nullable: true,
+  })
+  cancellationReason?: string | null;
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.controller.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.controller.ts
new file mode 100644
index 000000000..6c3fb60a0
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.controller.ts
@@ -0,0 +1,96 @@
+import { CurrentUser } from "@edr/api-common";
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  ParseUUIDPipe,
+  Post,
+} from "@nestjs/common";
+import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
+
+import { PortalCustomer } from "../../common/booking-guards";
+import { CancelShippingLineBookingDto } from "./dto/cancel-shipping-line-booking.dto";
+import { InitiateShippingLineBookingDto } from "./dto/initiate-shipping-line-booking.dto";
+import { ShippingLineBookingsService } from "./shipping-line-bookings.service";
+
+interface CurrentIamUser {
+  id: string;
+}
+
+/**
+ * Bookings a shipping line makes for itself, from the portal.
+ *
+ * Separate from `/bookings` (customers) on purpose — see
+ * {@link ShippingLineBookingsService} for why the two flows are not merged.
+ * `PortalCustomer` only proves a valid portal session; the service resolves the
+ * shipping-line account from that session and rejects anyone else, so the owner
+ * is never taken from the request body.
+ */
+@ApiTags("shipping-line-bookings")
+@Controller("shipping-line-bookings")
+@ApiBearerAuth()
+export class ShippingLineBookingsController {
+  constructor(
+    private readonly shippingLineBookingsService: ShippingLineBookingsService,
+  ) {}
+
+  @Post("initiate")
+  @PortalCustomer()
+  @ApiOperation({
+    summary:
+      "Initiate a bare booking (no contract). Starts at AWAITING_DOCUMENTS so the shipping line can upload its documents for Operations to approve.",
+  })
+  async initiate(
+    @CurrentUser() user: CurrentIamUser,
+    @Body() dto: InitiateShippingLineBookingDto,
+  ) {
+    return this.shippingLineBookingsService.initiate(user.id, dto);
+  }
+
+  // Declared before @Get(":id") so the path isn't captured as a booking id.
+  @Get("reference-data")
+  @PortalCustomer()
+  @ApiOperation({
+    summary:
+      "Catalog for the initiate form: bookable routes (each carrying its trade direction) and service types.",
+  })
+  async referenceData(@CurrentUser() user: CurrentIamUser) {
+    return this.shippingLineBookingsService.referenceData(user.id);
+  }
+
+  @Get("my")
+  @PortalCustomer()
+  @ApiOperation({ summary: "List the signed-in shipping line's bookings." })
+  async listMine(@CurrentUser() user: CurrentIamUser) {
+    return this.shippingLineBookingsService.listMine(user.id);
+  }
+
+  @Get(":id")
+  @PortalCustomer()
+  @ApiOperation({ summary: "Get one of the signed-in shipping line's bookings." })
+  async findMine(
+    @CurrentUser() user: CurrentIamUser,
+    @Param("id", ParseUUIDPipe) id: string,
+  ) {
+    return this.shippingLineBookingsService.findMine(user.id, id);
+  }
+
+  @Post(":id/cancel")
+  @PortalCustomer()
+  @ApiOperation({
+    summary:
+      "Cancel one of the signed-in shipping line's own bookings. Allowed only before the booking is priced.",
+  })
+  async cancelMine(
+    @CurrentUser() user: CurrentIamUser,
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: CancelShippingLineBookingDto,
+  ) {
+    return this.shippingLineBookingsService.cancelMine(
+      user.id,
+      id,
+      dto.reason,
+    );
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.service.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.service.ts
new file mode 100644
index 000000000..7a7ca457b
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.service.ts
@@ -0,0 +1,363 @@
+import { insertWithGeneratedReference } from "@edr/api-common";
+import {
+  BadRequestException,
+  ForbiddenException,
+  Injectable,
+  NotFoundException,
+} from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { In, Repository } from "typeorm";
+
+import { BookingDocumentReview } from "../bookings/entities/booking-document-review.entity";
+import { BookingReviewNote } from "../bookings/entities/booking-review-note.entity";
+import { Booking } from "../bookings/entities/booking.entity";
+import { formatRouteLabel, Route } from "../routes/entities/route.entity";
+import { ServiceType } from "../rule-engine/entities/service-type.entity";
+import { InitiateShippingLineBookingDto } from "./dto/initiate-shipping-line-booking.dto";
+import { ShippingLineCompaniesService } from "./shipping-line-companies.service";
+
+/**
+ * The only trade direction a shipping line books.
+ *
+ * Their cargo arrives by sea at Djibouti and moves inland to Ethiopia, which is
+ * IMPORT by the rule routes are stamped with (DJ→ET = IMPORT, ET→DJ = EXPORT,
+ * same country = DOMESTIC). Export and intercity lanes are therefore neither
+ * offered nor accepted.
+ */
+const SHIPPING_LINE_DIRECTION = "IMPORT";
+
+/**
+ * Statuses a shipping line may cancel its own booking from — everything before
+ * the booking is priced. Past this point cancelling has billing consequences
+ * (fees, credit notes) and belongs with Operations.
+ */
+const SHIPPING_LINE_CANCELLABLE_STATUSES: string[] = [
+  "AWAITING_DOCUMENTS",
+  "DOCUMENTS_UNDER_REVIEW",
+  "CLEARANCE_READY",
+  "CHANGES_REQUESTED",
+];
+
+/**
+ * Booking creation for shipping lines.
+ *
+ * Deliberately separate from `BookingsService` / `ContractBookingService`
+ * rather than a branch inside them. Those are built end to end around a
+ * customer: a `companies` row, an approved operational `company_profile`, a
+ * contract supplying route/quantities, and contract-capacity accounting. A
+ * shipping line has none of that — it books directly, without a contract — so
+ * branching there would mean threading "no company, no profile, no contract"
+ * through every method a customer booking passes through. Keeping it here means
+ * the customer paths are not touched at all.
+ *
+ * What IS shared is the table and the downstream lifecycle: the row lands in
+ * `freight.bookings` at `AWAITING_DOCUMENTS`, the shipping line uploads its
+ * documents against the `shipping_line_booking_documents` file-upload setting,
+ * and Operations reviews and finalizes them through the same clearance flow
+ * customers already use.
+ */
+@Injectable()
+export class ShippingLineBookingsService {
+  constructor(
+    @InjectRepository(Booking)
+    private readonly bookingsRepository: Repository<Booking>,
+    private readonly shippingLineCompaniesService: ShippingLineCompaniesService,
+  ) {}
+
+  /**
+   * Resolve the shipping-line account for a signed-in user, or reject. Every
+   * entry point goes through this: the owner is taken from the session, never
+   * from the request body, so one shipping line cannot book as another.
+   */
+  private async requireShippingLine(userId: string) {
+    const shippingLine =
+      await this.shippingLineCompaniesService.findByUserId(userId);
+    if (!shippingLine) {
+      throw new ForbiddenException("This account is not a shipping line.");
+    }
+    if (shippingLine.status !== "active") {
+      throw new ForbiddenException(
+        "This shipping-line account is suspended and cannot create bookings.",
+      );
+    }
+    return shippingLine;
+  }
+
+  /**
+   * The catalog the initiate form needs: the lanes EDR actually runs, and the
+   * services that can be booked on their own.
+   *
+   * Routes are offered instead of two loose yard pickers so a shipping line
+   * cannot invent a lane that does not exist — and because the route already
+   * carries its trade direction, which is otherwise guesswork.
+   *
+   * Read-only and scoped to bookable rows, which is why it lives here rather
+   * than reusing the staff `/routes` controller (gated behind fleet
+   * permissions a shipping line does not and should not hold).
+   */
+  async referenceData(userId: string) {
+    await this.requireShippingLine(userId);
+
+    const [routes, serviceTypes] = await Promise.all([
+      this.bookingsRepository.manager.getRepository(Route).find({
+        // Shipping lines only move inbound cargo: it lands at the Djibouti port
+        // and runs inland to Ethiopia. Filtering here rather than in the portal
+        // means an export or intercity lane is never offered AND never
+        // accepted — `initiate` re-checks the same rule below.
+        where: { status: "AVAILABLE", direction: SHIPPING_LINE_DIRECTION },
+        relations: { originYard: true, destinationYard: true },
+      }),
+      // Customs-bundled services are excluded: those run the phased ET/DJ
+      // customs workflow, which is a contract-backed flow a shipping line has
+      // no part in. Their clearance is the single document set Operations
+      // reviews on the booking itself.
+      this.bookingsRepository.manager.getRepository(ServiceType).find({
+        where: {
+          canBeBookedAlone: true,
+          includesCustoms: false,
+          isActive: true,
+        },
+        order: { displayOrder: "ASC" },
+      }),
+    ]);
+
+    return {
+      routes: routes.map((route) => ({
+        id: route.id,
+        label: formatRouteLabel(route),
+        direction: route.direction,
+        originYardId: route.originYardId,
+        // Per-yard labels so the portal can offer origin and destination as two
+        // separate pickers (the shape the customer form uses) while still
+        // resolving the pair back to one of these routes.
+        originLabel:
+          route.originYard?.label ?? route.originYard?.code ?? "Origin",
+        destinationYardId: route.destinationYardId,
+        destinationLabel:
+          route.destinationYard?.label ??
+          route.destinationYard?.code ??
+          "Destination",
+      })),
+      serviceTypes: serviceTypes.map((service) => ({
+        id: service.id,
+        name: service.serviceName,
+      })),
+    };
+  }
+
+  /**
+   * Create a BARE booking for a shipping line — no contract, no cargo, no date
+   * and no price. It exists so documents have something to hang off: the
+   * shipping line uploads them next, Operations approves, and only then is the
+   * booking completed with its cargo and shipment day.
+   */
+  async initiate(userId: string, dto: InitiateShippingLineBookingDto) {
+    const shippingLine = await this.requireShippingLine(userId);
+
+    // The route is the single source of origin, destination AND direction —
+    // resolved server-side so the three can never disagree, and so a caller
+    // cannot post a lane EDR does not run.
+    const route = await this.bookingsRepository.manager
+      .getRepository(Route)
+      .findOne({ where: { id: dto.routeId } });
+    if (!route) {
+      throw new NotFoundException(`Route ${dto.routeId} not found`);
+    }
+    if (route.status !== "AVAILABLE") {
+      throw new BadRequestException(
+        "This route is not currently available for booking.",
+      );
+    }
+    // Enforced here too, not just by filtering the picker: the route id comes
+    // from the request, so an export or intercity lane could otherwise be
+    // posted directly.
+    if (route.direction !== SHIPPING_LINE_DIRECTION) {
+      throw new BadRequestException(
+        "Shipping lines can only book inbound (Djibouti to Ethiopia) routes.",
+      );
+    }
+
+    // Same reasoning as the picker filter: a customs-bundled service would put
+    // the booking into the phased customs workflow, which has no contract to
+    // hang off here. Checked server-side because the id comes from the request.
+    if (dto.serviceTypeId) {
+      const serviceType = await this.bookingsRepository.manager
+        .getRepository(ServiceType)
+        .findOne({ where: { id: dto.serviceTypeId } });
+      if (!serviceType) {
+        throw new NotFoundException(
+          `Service type ${dto.serviceTypeId} not found`,
+        );
+      }
+      if (serviceType.includesCustoms) {
+        throw new BadRequestException(
+          "Shipping lines cannot book a service that bundles customs clearance.",
+        );
+      }
+    }
+
+    return insertWithGeneratedReference(
+      () => this.generateReference(),
+      (reference) =>
+        this.bookingsRepository.save({
+          reference,
+          // The owner columns: a shipping-line booking has no company and no
+          // operational profile, which is exactly what the `chk_bookings_
+          // single_owner` CHECK expects alongside a set shippingLineCompanyId.
+          companyId: null,
+          companyProfileId: null,
+          shippingLineCompanyId: shippingLine.id,
+          status: "AWAITING_DOCUMENTS",
+          bookingType: "ONE_TIME",
+          contractId: null,
+          contractType: "NEW",
+          createdByRole: "SHIPPING_LINE",
+          createdByUserId: userId,
+          // Taken from the chosen route, never from the request body: the
+          // direction is frozen on the route from its yard countries, so
+          // deriving it here keeps it consistent with scheduling and booking
+          // windows, which read the same field.
+          originYardId: route.originYardId,
+          destinationYardId: route.destinationYardId,
+          tradeDirection: route.direction,
+          serviceTypeId: dto.serviceTypeId ?? null,
+          freightType: dto.freightType ?? "CONTAINER",
+          // Bare instance — filled in when the booking is completed.
+          scheduledDate: null,
+          cargoTypeId: null,
+          cargoTotalWeightVgm: 0,
+        } as never),
+    );
+  }
+
+  /**
+   * List the bookings belonging to the signed-in shipping line, newest first.
+   *
+   * Each row carries `hasQueriedDocuments`: a reviewer querying a document sets
+   * that document's review status but leaves the BOOKING on
+   * DOCUMENTS_UNDER_REVIEW, so status alone cannot tell the list which bookings
+   * need the shipping line to act. Resolved in one grouped query rather than a
+   * clearance call per row.
+   */
+  async listMine(userId: string) {
+    const shippingLine = await this.requireShippingLine(userId);
+
+    const bookings = await this.bookingsRepository.find({
+      where: { shippingLineCompanyId: shippingLine.id },
+      relations: { originYard: true, destinationYard: true },
+      order: { createdAt: "DESC" },
+    });
+    if (bookings.length === 0) return [];
+
+    const queried = await this.bookingsRepository.manager
+      .getRepository(BookingDocumentReview)
+      .find({
+        where: {
+          bookingId: In(bookings.map((b) => b.id)),
+          status: "QUERIED",
+        },
+        select: { bookingId: true },
+      });
+
+    const queriedIds = new Set(queried.map((row) => row.bookingId));
+
+    return bookings.map((booking) => ({
+      ...booking,
+      hasQueriedDocuments: queriedIds.has(booking.id),
+    }));
+  }
+
+  /**
+   * Fetch one of the signed-in shipping line's own bookings. Scoped by owner so
+   * an id belonging to a customer (or another shipping line) reads as missing.
+   */
+  async findMine(userId: string, bookingId: string) {
+    const shippingLine = await this.requireShippingLine(userId);
+
+    const booking = await this.bookingsRepository.findOne({
+      where: { id: bookingId, shippingLineCompanyId: shippingLine.id },
+      // Yards are loaded so the portal can render the lane without a second
+      // lookup — they are set at initiate time from the chosen route.
+      relations: { originYard: true, destinationYard: true, serviceType: true },
+    });
+    if (!booking) throw new NotFoundException(`Booking ${bookingId} not found`);
+
+    // Same flag as the list — see listMine for why booking status alone is not
+    // enough to tell whether the shipping line has something to fix.
+    const queriedCount = await this.bookingsRepository.manager
+      .getRepository(BookingDocumentReview)
+      .count({ where: { bookingId, status: "QUERIED" } });
+
+    return { ...booking, hasQueriedDocuments: queriedCount > 0 };
+  }
+
+  /**
+   * Cancel one of the signed-in shipping line's own bookings.
+   *
+   * Its own method rather than the customer `customerCancel`: that path routes
+   * into `BookingTransitionService.cancel`, whose status whitelist covers the
+   * contract-backed lifecycle (DRAFT, SUBMITTED, PENDING_APPROVAL…) and does
+   * not include the document-clearance statuses a shipping-line booking lives
+   * in — so it would reject every one of them.
+   *
+   * Only allowed before the booking is priced and paid. Once it carries a
+   * charge, cancelling is a billing decision (fees, credit notes) that belongs
+   * with Operations, not a self-service button.
+   */
+  async cancelMine(userId: string, bookingId: string, reason?: string) {
+    const shippingLine = await this.requireShippingLine(userId);
+
+    const booking = await this.bookingsRepository.findOne({
+      where: { id: bookingId, shippingLineCompanyId: shippingLine.id },
+    });
+    if (!booking) throw new NotFoundException(`Booking ${bookingId} not found`);
+
+    if (booking.status === "CANCELLED") {
+      throw new BadRequestException("This booking is already cancelled.");
+    }
+    if (!SHIPPING_LINE_CANCELLABLE_STATUSES.includes(booking.status)) {
+      throw new BadRequestException(
+        "This booking can no longer be cancelled — please contact Operations.",
+      );
+    }
+    // Belt and braces: the statuses above are all pre-pricing, so a charge here
+    // would mean the booking moved on in a way this guard did not anticipate.
+    if (Number(booking.totalAmount ?? 0) > 0) {
+      throw new BadRequestException(
+        "This booking has already been priced — please contact Operations to cancel it.",
+      );
+    }
+
+    // The reason lives on the booking's review-note log, the same place the
+    // customer cancel path records it — there is no column for it.
+    await this.bookingsRepository.manager
+      .getRepository(BookingReviewNote)
+      .save({
+        bookingId,
+        note: reason?.trim() || "Cancelled by the shipping line",
+        type: "REJECTION",
+        authorId: userId,
+      } as never);
+
+    await this.bookingsRepository.update(bookingId, {
+      status: "CANCELLED",
+    } as never);
+
+    return this.findMine(userId, bookingId);
+  }
+
+  /** Mirrors the customer reference format — one booking sequence per year. */
+  private async generateReference(): Promise<string> {
+    const year = new Date().getFullYear();
+    const { max } = (await this.bookingsRepository
+      .createQueryBuilder("b")
+      .select(
+        `COALESCE(MAX(NULLIF(regexp_replace(b.reference, '^BK-${year}-', ''), b.reference)::int), 0)`,
+        "max",
+      )
+      .where("b.reference LIKE :prefix", { prefix: `BK-${year}-%` })
+      .getRawOne<{ max: number }>()) ?? { max: 0 };
+
+    return `BK-${year}-${String(Number(max) + 1).padStart(6, "0")}`;
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts
index 81d5b9cdf..698dfb384 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts
@@ -1,24 +1,55 @@
-import { Module } from "@nestjs/common";
+import { Module, forwardRef } from "@nestjs/common";
 import { TypeOrmModule } from "@nestjs/typeorm";
 
 import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
 
 import { FreightAuthModule } from "../auth/freight-auth.module";
+import { BillingModule } from "../billing/billing.module";
+import { Booking } from "../bookings/entities/booking.entity";
 import { OtpModule } from "../otp/otp.module";
 import { ShippingLineCompany } from "./entities/shipping-line-company.entity";
+import { ShippingLineCredit } from "./entities/shipping-line-credit.entity";
+import { ShippingLineBookingsController } from "./shipping-line-bookings.controller";
+import { ShippingLineBookingsService } from "./shipping-line-bookings.service";
 import { ShippingLineCompaniesController } from "./shipping-line-companies.controller";
 import { ShippingLineCompaniesRepository } from "./shipping-line-companies.repository";
 import { ShippingLineCompaniesService } from "./shipping-line-companies.service";
+import { ShippingLineCreditsController } from "./shipping-line-credits.controller";
+import { ShippingLineCreditsRepository } from "./shipping-line-credits.repository";
+import { ShippingLineCreditsService } from "./shipping-line-credits.service";
 
 @Module({
   imports: [
-    TypeOrmModule.forFeature([ShippingLineCompany, User]),
+    // Booking is registered here only so this module can create shipping-line
+    // rows in `freight.bookings`; the customer BookingsModule is untouched.
+    TypeOrmModule.forFeature([
+      ShippingLineCompany,
+      ShippingLineCredit,
+      User,
+      Booking,
+    ]),
     // CustomerResetService — activation links reuse the staff-triggered reset path.
     FreightAuthModule,
     OtpModule,
+    // Credits are billed by generating an ordinary invoice. Billing still knows
+    // nothing about credits and hears about settlement only by emitting its own
+    // `shipping_line_credit.invoice.paid` event, but the module graph now cycles
+    // (billing -> companies -> here -> billing), so this edge needs forwardRef.
+    forwardRef(() => BillingModule),
   ],
-  controllers: [ShippingLineCompaniesController],
-  providers: [ShippingLineCompaniesService, ShippingLineCompaniesRepository],
-  exports: [ShippingLineCompaniesService],
+  controllers: [
+    ShippingLineCompaniesController,
+    ShippingLineBookingsController,
+    ShippingLineCreditsController,
+  ],
+  providers: [
+    ShippingLineCompaniesService,
+    ShippingLineCompaniesRepository,
+    ShippingLineBookingsService,
+    ShippingLineCreditsService,
+    ShippingLineCreditsRepository,
+  ],
+  // Exported so whatever prices a shipping-line booking can record the charge.
+  exports: [ShippingLineCompaniesService, ShippingLineCreditsService],
 })
 export class ShippingLineCompaniesModule {}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.controller.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.controller.ts
new file mode 100644
index 000000000..2ac618afe
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.controller.ts
@@ -0,0 +1,127 @@
+import { CurrentUser } from "@edr/api-common";
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  ParseUUIDPipe,
+  Post,
+  Query,
+} from "@nestjs/common";
+import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
+
+import { BookingStaff, PortalCustomer } from "../../common/booking-guards";
+import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
+import {
+  CancelCreditDto,
+  GenerateCreditInvoiceDto,
+} from "./dto/shipping-line-credit.dto";
+import { ShippingLineCreditStatus } from "./entities/shipping-line-credit.entity";
+import { ShippingLineCreditsService } from "./shipping-line-credits.service";
+
+interface CurrentIamUser {
+  id: string;
+}
+
+/**
+ * Finance's view of what shipping lines owe.
+ *
+ * A shipping line books and ships without paying — the charge is recorded as a
+ * credit instead. Finance reads the unbilled list here, batches it into an
+ * invoice, and the line then pays that invoice through the ordinary
+ * `/billing` + CBE routes; nothing in this controller touches money directly.
+ */
+@ApiTags("shipping-line-credits")
+@Controller("shipping-line-credits")
+@ApiBearerAuth()
+export class ShippingLineCreditsController {
+  constructor(private readonly credits: ShippingLineCreditsService) {}
+
+  // Declared before the parameterised staff routes so "me" is never captured
+  // as a shipping-line id.
+  @Get("me")
+  @PortalCustomer()
+  @ApiOperation({
+    summary:
+      "The signed-in shipping line's own statement: outstanding balance plus its credit ledger.",
+  })
+  async myStatement(
+    @CurrentUser() user: CurrentIamUser,
+    @Query("page") page?: string,
+    @Query("pageSize") pageSize?: string,
+  ) {
+    return this.credits.myStatement(
+      user.id,
+      page ? Number(page) : 1,
+      pageSize ? Number(pageSize) : 20,
+    );
+  }
+
+  @Get(":shippingLineId/outstanding")
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.view)
+  @ApiOperation({
+    summary:
+      "What one shipping line owes: unbilled + billed totals, derived from the ledger.",
+  })
+  async outstanding(
+    @Param("shippingLineId", ParseUUIDPipe) shippingLineId: string,
+  ) {
+    return this.credits.outstanding(shippingLineId);
+  }
+
+  @Get(":shippingLineId/unbilled")
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.view)
+  @ApiOperation({
+    summary:
+      "Credits that can go on an invoice for this line, oldest first. This is the selection list.",
+  })
+  async listUnbilled(
+    @Param("shippingLineId", ParseUUIDPipe) shippingLineId: string,
+  ) {
+    return this.credits.listUnbilled(shippingLineId);
+  }
+
+  @Get(":shippingLineId")
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.view)
+  @ApiOperation({
+    summary: "Full credit ledger for one shipping line (paginated).",
+  })
+  async listCredits(
+    @Param("shippingLineId", ParseUUIDPipe) shippingLineId: string,
+    @Query("page") page?: string,
+    @Query("pageSize") pageSize?: string,
+    @Query("status") status?: ShippingLineCreditStatus,
+  ) {
+    return this.credits.listCredits(
+      shippingLineId,
+      page ? Number(page) : 1,
+      pageSize ? Number(pageSize) : 20,
+      status,
+    );
+  }
+
+  @Post("invoice")
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.invoice)
+  @ApiOperation({
+    summary:
+      "Bill a batch of unbilled credits as one invoice. All credits must belong to the same shipping line.",
+  })
+  async generateInvoice(@Body() dto: GenerateCreditInvoiceDto) {
+    return this.credits.generateInvoice(dto.creditIds, {
+      dueInDays: dto.dueInDays,
+    });
+  }
+
+  @Post(":creditId/cancel")
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.cancel)
+  @ApiOperation({
+    summary:
+      "Write off an unbilled credit. Once billed, cancel the invoice instead.",
+  })
+  async cancel(
+    @Param("creditId", ParseUUIDPipe) creditId: string,
+    @Body() dto: CancelCreditDto,
+  ) {
+    return this.credits.cancelCredit(creditId, dto.reason);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.repository.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.repository.ts
new file mode 100644
index 000000000..fac89e0df
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.repository.ts
@@ -0,0 +1,138 @@
+import { BaseRepository } from "@edr/api-common";
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { EntityManager, In, Repository } from "typeorm";
+
+import {
+  OUTSTANDING_CREDIT_STATUSES,
+  ShippingLineCredit,
+  ShippingLineCreditStatus,
+} from "./entities/shipping-line-credit.entity";
+
+/** What one shipping line currently owes, split by billing stage. */
+export interface OutstandingTotals {
+  /** Priced but not yet on an invoice. */
+  unbilledAmount: number;
+  /** On an issued invoice, awaiting payment. */
+  billedAmount: number;
+  /** `unbilledAmount + billedAmount` — the full debt. */
+  totalOutstanding: number;
+  unbilledCount: number;
+  billedCount: number;
+  currency: string;
+}
+
+@Injectable()
+export class ShippingLineCreditsRepository extends BaseRepository<ShippingLineCredit> {
+  constructor(
+    @InjectRepository(ShippingLineCredit)
+    private readonly credits: Repository<ShippingLineCredit>,
+  ) {
+    super(credits);
+  }
+
+  findByBookingId(bookingId: string): Promise<ShippingLineCredit | null> {
+    return this.credits.findOne({ where: { bookingId } });
+  }
+
+  /**
+   * Finance's worklist: everything for one line that can go on an invoice,
+   * oldest first so the longest-standing debt is billed before newer charges.
+   */
+  findUnbilled(shippingLineCompanyId: string): Promise<ShippingLineCredit[]> {
+    return this.credits.find({
+      where: {
+        shippingLineCompanyId,
+        status: ShippingLineCreditStatus.Unbilled,
+      },
+      relations: { booking: true },
+      order: { createdAt: "ASC" },
+    });
+  }
+
+  findByInvoiceId(
+    invoiceId: string,
+    manager?: EntityManager,
+  ): Promise<ShippingLineCredit[]> {
+    const repo = manager
+      ? manager.getRepository(ShippingLineCredit)
+      : this.credits;
+    return repo.find({ where: { invoiceId } });
+  }
+
+  /**
+   * Load a specific batch inside the caller's transaction and lock it, so two
+   * concurrent invoice generations cannot both claim the same credits.
+   */
+  findByIdsForUpdate(
+    manager: EntityManager,
+    ids: string[],
+  ): Promise<ShippingLineCredit[]> {
+    return manager.getRepository(ShippingLineCredit).find({
+      where: { id: In(ids) },
+      lock: { mode: "pessimistic_write" },
+    });
+  }
+
+  /**
+   * Derived debt — never a stored column. Grouped in one query so the detail
+   * page does not fan out per status.
+   */
+  async outstandingFor(
+    shippingLineCompanyId: string,
+  ): Promise<OutstandingTotals> {
+    const rows = await this.credits
+      .createQueryBuilder("credit")
+      .select("credit.status", "status")
+      .addSelect("COALESCE(SUM(credit.amount), 0)", "amount")
+      .addSelect("COUNT(*)", "count")
+      .where("credit.shippingLineCompanyId = :shippingLineCompanyId", {
+        shippingLineCompanyId,
+      })
+      .andWhere("credit.status IN (:...statuses)", {
+        statuses: [...OUTSTANDING_CREDIT_STATUSES],
+      })
+      .andWhere("credit.deletedAt IS NULL")
+      .groupBy("credit.status")
+      .getRawMany<{ status: string; amount: string; count: string }>();
+
+    const totals = (status: ShippingLineCreditStatus) => {
+      const row = rows.find((r) => r.status === status);
+      return {
+        amount: row ? Number(row.amount) : 0,
+        count: row ? Number(row.count) : 0,
+      };
+    };
+
+    const unbilled = totals(ShippingLineCreditStatus.Unbilled);
+    const billed = totals(ShippingLineCreditStatus.Billed);
+
+    return {
+      unbilledAmount: unbilled.amount,
+      billedAmount: billed.amount,
+      totalOutstanding: unbilled.amount + billed.amount,
+      unbilledCount: unbilled.count,
+      billedCount: billed.count,
+      currency: "ETB",
+    };
+  }
+
+  /** Paginated ledger for one line — every credit, whatever its status. */
+  findAllPaginated(
+    shippingLineCompanyId: string,
+    skip: number,
+    take: number,
+    status?: ShippingLineCreditStatus,
+  ): Promise<[ShippingLineCredit[], number]> {
+    return this.credits.findAndCount({
+      where: {
+        shippingLineCompanyId,
+        ...(status ? { status } : {}),
+      },
+      relations: { booking: true, invoice: true },
+      order: { createdAt: "DESC" },
+      skip,
+      take,
+    });
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.spec.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.spec.ts
new file mode 100644
index 000000000..0348d08bd
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.spec.ts
@@ -0,0 +1,296 @@
+import { BadRequestException, NotFoundException } from "@nestjs/common";
+import { Freight } from "@edr/types";
+
+import { Booking } from "../bookings/entities/booking.entity";
+import {
+  ShippingLineCredit,
+  ShippingLineCreditStatus,
+} from "./entities/shipping-line-credit.entity";
+import { ShippingLineCreditsService } from "./shipping-line-credits.service";
+
+/**
+ * The money path: a shipping line ships without paying, so the debt lives
+ * entirely in these three transitions. Each test below locks one way the debt
+ * could be lost or double-counted.
+ */
+describe("ShippingLineCreditsService", () => {
+  let creditsRepo: {
+    findByIdsForUpdate: jest.Mock;
+    findUnbilled: jest.Mock;
+    outstandingFor: jest.Mock;
+    findAllPaginated: jest.Mock;
+  };
+  let billing: { generateInvoice: jest.Mock };
+  let shippingLines: { findById: jest.Mock; findByUserId: jest.Mock };
+  let dataSource: { transaction: jest.Mock; getRepository: jest.Mock };
+  let mg: {
+    findOne: jest.Mock;
+    getRepository: jest.Mock;
+    update: jest.Mock;
+  };
+  let txRepo: { findOne: jest.Mock; save: jest.Mock; create: jest.Mock };
+  let updateResult: { affected: number };
+  let service: ShippingLineCreditsService;
+
+  const booking = {
+    id: "booking-1",
+    reference: "BK-2026-000001",
+    shippingLineCompanyId: "sl-1",
+  } as Booking;
+
+  beforeEach(() => {
+    txRepo = {
+      findOne: jest.fn().mockResolvedValue(null),
+      create: jest.fn((v) => v),
+      save: jest.fn(async (v) => ({ id: "credit-1", ...v })),
+    };
+    mg = {
+      findOne: jest.fn().mockResolvedValue(booking),
+      getRepository: jest.fn(() => txRepo),
+      update: jest.fn().mockResolvedValue({ affected: 1 }),
+    };
+    updateResult = { affected: 2 };
+    dataSource = {
+      transaction: jest.fn(async (cb) => cb(mg)),
+      getRepository: jest.fn(() => ({
+        update: jest.fn().mockResolvedValue(updateResult),
+      })),
+    };
+    creditsRepo = {
+      findByIdsForUpdate: jest.fn(),
+      findUnbilled: jest.fn(),
+      outstandingFor: jest.fn(),
+      findAllPaginated: jest.fn(),
+    };
+    billing = {
+      generateInvoice: jest.fn().mockResolvedValue({
+        id: "inv-1",
+        invoiceNumber: "INV-20260813-00001",
+        totalAmount: 50000,
+      }),
+    };
+    shippingLines = {
+      findById: jest.fn().mockResolvedValue({ id: "sl-1", name: "ESL" }),
+      findByUserId: jest.fn(),
+    };
+
+    service = new ShippingLineCreditsService(
+      dataSource as never,
+      creditsRepo as never,
+      billing as never,
+      shippingLines as never,
+    );
+  });
+
+  describe("recordCredit", () => {
+    it("records the charge against the booking's own shipping line", async () => {
+      const credit = await service.recordCredit({
+        bookingId: "booking-1",
+        amount: 20000,
+      });
+
+      expect(txRepo.save).toHaveBeenCalledWith(
+        expect.objectContaining({
+          // Taken from the booking, never from the caller.
+          shippingLineCompanyId: "sl-1",
+          bookingId: "booking-1",
+          amount: 20000,
+          status: ShippingLineCreditStatus.Unbilled,
+        }),
+      );
+      expect(credit.id).toBe("credit-1");
+    });
+
+    it("is idempotent per booking — a retried pricing step cannot double the debt", async () => {
+      const existing = {
+        id: "credit-existing",
+        status: ShippingLineCreditStatus.Unbilled,
+        amount: 20000,
+        currency: "ETB",
+      };
+      txRepo.findOne.mockResolvedValue(existing);
+
+      const credit = await service.recordCredit({
+        bookingId: "booking-1",
+        amount: 20000,
+      });
+
+      expect(credit).toBe(existing);
+      expect(txRepo.save).not.toHaveBeenCalled();
+    });
+
+    it("refuses a customer booking — those are paid up front, not on credit", async () => {
+      mg.findOne.mockResolvedValue({
+        ...booking,
+        shippingLineCompanyId: null,
+      });
+
+      await expect(
+        service.recordCredit({ bookingId: "booking-1", amount: 100 }),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it("rejects a negative amount", async () => {
+      await expect(
+        service.recordCredit({ bookingId: "booking-1", amount: -1 }),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+  });
+
+  describe("generateInvoice", () => {
+    const unbilled = (id: string, amount: number) => ({
+      id,
+      shippingLineCompanyId: "sl-1",
+      bookingId: `booking-${id}`,
+      amount,
+      currency: "ETB",
+      status: ShippingLineCreditStatus.Unbilled,
+      description: `Freight service — ${id}`,
+    });
+
+    it("bills the batch as one invoice and flips the credits to BILLED", async () => {
+      creditsRepo.findByIdsForUpdate.mockResolvedValue([
+        unbilled("c1", 20000),
+        unbilled("c2", 30000),
+      ]);
+
+      const invoice = await service.generateInvoice(["c1", "c2"]);
+
+      expect(billing.generateInvoice).toHaveBeenCalledWith(
+        expect.objectContaining({
+          source: Freight.InvoiceSource.ShippingLineCredit,
+          // The payer, not a customer — invoices.company_id stays null.
+          shippingLineCompanyId: "sl-1",
+          sourceId: "sl-1",
+          status: Freight.InvoiceStatus.Issued,
+          lines: [
+            expect.objectContaining({ amount: 20000 }),
+            expect.objectContaining({ amount: 30000 }),
+          ],
+        }),
+        mg,
+      );
+      expect(mg.update).toHaveBeenCalledWith(
+        ShippingLineCredit,
+        expect.anything(),
+        expect.objectContaining({
+          status: ShippingLineCreditStatus.Billed,
+          invoiceId: "inv-1",
+        }),
+      );
+      expect(invoice.id).toBe("inv-1");
+    });
+
+    it("refuses to bill a credit that is already on an invoice", async () => {
+      creditsRepo.findByIdsForUpdate.mockResolvedValue([
+        { ...unbilled("c1", 20000), status: ShippingLineCreditStatus.Billed },
+      ]);
+
+      await expect(service.generateInvoice(["c1"])).rejects.toBeInstanceOf(
+        BadRequestException,
+      );
+      expect(billing.generateInvoice).not.toHaveBeenCalled();
+    });
+
+    it("refuses to mix two shipping lines on one invoice", async () => {
+      creditsRepo.findByIdsForUpdate.mockResolvedValue([
+        unbilled("c1", 20000),
+        { ...unbilled("c2", 30000), shippingLineCompanyId: "sl-2" },
+      ]);
+
+      await expect(
+        service.generateInvoice(["c1", "c2"]),
+      ).rejects.toBeInstanceOf(BadRequestException);
+      expect(billing.generateInvoice).not.toHaveBeenCalled();
+    });
+
+    it("refuses to mix currencies", async () => {
+      creditsRepo.findByIdsForUpdate.mockResolvedValue([
+        unbilled("c1", 20000),
+        { ...unbilled("c2", 300), currency: "USD" },
+      ]);
+
+      await expect(
+        service.generateInvoice(["c1", "c2"]),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it("reports ids that do not exist rather than silently billing the rest", async () => {
+      creditsRepo.findByIdsForUpdate.mockResolvedValue([unbilled("c1", 20000)]);
+
+      await expect(
+        service.generateInvoice(["c1", "missing"]),
+      ).rejects.toBeInstanceOf(NotFoundException);
+    });
+
+    it("rejects an empty selection", async () => {
+      await expect(service.generateInvoice([])).rejects.toBeInstanceOf(
+        BadRequestException,
+      );
+    });
+  });
+
+  describe("onInvoicePaid", () => {
+    it("clears every billed credit on the settled invoice", async () => {
+      const update = jest.fn().mockResolvedValue({ affected: 2 });
+      dataSource.getRepository = jest.fn(() => ({ update }));
+
+      await service.onInvoicePaid({
+        invoiceId: "inv-1",
+        invoiceNumber: "INV-20260813-00001",
+      } as never);
+
+      expect(update).toHaveBeenCalledWith(
+        // Scoped to BILLED so a redelivered webhook cannot re-stamp paidAt.
+        { invoiceId: "inv-1", status: ShippingLineCreditStatus.Billed },
+        expect.objectContaining({ status: ShippingLineCreditStatus.Paid }),
+      );
+    });
+
+    it("is a no-op on webhook redelivery", async () => {
+      const update = jest.fn().mockResolvedValue({ affected: 0 });
+      dataSource.getRepository = jest.fn(() => ({ update }));
+
+      await expect(
+        service.onInvoicePaid({
+          invoiceId: "inv-1",
+          invoiceNumber: "INV-1",
+        } as never),
+      ).resolves.toBeUndefined();
+    });
+  });
+
+  describe("cancelCredit", () => {
+    it("writes off an unbilled credit", async () => {
+      creditsRepo.findByIdsForUpdate.mockResolvedValue([
+        { id: "c1", status: ShippingLineCreditStatus.Unbilled },
+      ]);
+
+      const result = await service.cancelCredit("c1", "Booking voided");
+
+      expect(result.status).toBe(ShippingLineCreditStatus.Cancelled);
+      expect(mg.update).toHaveBeenCalledWith(
+        ShippingLineCredit,
+        { id: "c1" },
+        expect.objectContaining({
+          status: ShippingLineCreditStatus.Cancelled,
+          cancellationReason: "Booking voided",
+        }),
+      );
+    });
+
+    it("refuses to write off a credit already on an invoice", async () => {
+      creditsRepo.findByIdsForUpdate.mockResolvedValue([
+        {
+          id: "c1",
+          status: ShippingLineCreditStatus.Billed,
+          invoiceId: "inv-1",
+        },
+      ]);
+
+      await expect(
+        service.cancelCredit("c1", "oops"),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.ts
new file mode 100644
index 000000000..4241a796f
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.ts
@@ -0,0 +1,420 @@
+import { logCtx } from "@edr/api-common";
+import { Freight } from "@edr/types";
+import {
+  BadRequestException,
+  ForbiddenException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from "@nestjs/common";
+import { OnEvent } from "@nestjs/event-emitter";
+import { DataSource, EntityManager, In } from "typeorm";
+
+import {
+  BillingService,
+  InvoiceEventPayload,
+  InvoiceLineInput,
+} from "../billing/billing.service";
+import { Invoice } from "../billing/entities/invoice.entity";
+import { Booking } from "../bookings/entities/booking.entity";
+import {
+  ShippingLineCredit,
+  ShippingLineCreditStatus,
+} from "./entities/shipping-line-credit.entity";
+import { ShippingLineCreditsRepository } from "./shipping-line-credits.repository";
+import { ShippingLineCompaniesService } from "./shipping-line-companies.service";
+
+/** A charge to record against a shipping line's booking. */
+export interface RecordCreditInput {
+  bookingId: string;
+  /** Frozen at this value; never recalculated afterwards. */
+  amount: number;
+  currency?: string;
+  description?: string;
+}
+
+/** Payment terms for a generated shipping-line invoice. */
+export interface GenerateCreditInvoiceOptions {
+  /** Pay window in days; defaults to the billing module's own default. */
+  dueInDays?: number;
+}
+
+/**
+ * The credit ledger for shipping lines — "use the service now, pay later".
+ *
+ * Three moments, in order:
+ *
+ * 1. **Charge.** A shipping line's booking is priced, and
+ *    {@link recordCredit} writes an UNBILLED credit. No invoice, no payment
+ *    intent, no gate on the booking — it proceeds regardless.
+ * 2. **Bill.** Finance picks a batch of unbilled credits for ONE line and
+ *    {@link generateInvoice} turns them into a single invoice, one line per
+ *    credit. The credits become BILLED.
+ * 3. **Settle.** The line pays that invoice through the ordinary CBE flow.
+ *    Billing emits `shipping_line_credit.invoice.paid`, {@link onInvoicePaid}
+ *    marks the batch PAID, and the debt disappears.
+ *
+ * Nothing here decrements a balance: the amount owed is always
+ * `SUM(amount)` over non-terminal credits. Payment is settled by the gateway
+ * webhook alone — no manual approval step — so a credit only ever leaves debt
+ * because real money arrived.
+ */
+@Injectable()
+export class ShippingLineCreditsService {
+  private readonly logger = new Logger(ShippingLineCreditsService.name);
+
+  constructor(
+    private readonly dataSource: DataSource,
+    private readonly credits: ShippingLineCreditsRepository,
+    private readonly billing: BillingService,
+    private readonly shippingLines: ShippingLineCompaniesService,
+  ) {}
+
+  // ── 1. Charge ──────────────────────────────────────────────────────────────
+
+  /**
+   * Record what a shipping line owes for one booking.
+   *
+   * Called when the booking is priced. The owner is read off the booking
+   * itself rather than passed in, so a credit can never be filed against the
+   * wrong line. Idempotent per booking: a second call returns the existing
+   * credit untouched rather than doubling the debt — safe against a retried
+   * pricing step, and the partial unique index backs it at the DB level.
+   *
+   * Pass `manager` to enlist in the caller's transaction, so the credit and
+   * whatever priced the booking commit together.
+   */
+  async recordCredit(
+    input: RecordCreditInput,
+    manager?: EntityManager,
+  ): Promise<ShippingLineCredit> {
+    if (!(input.amount >= 0)) {
+      throw new BadRequestException("Credit amount cannot be negative.");
+    }
+
+    const run = async (mg: EntityManager): Promise<ShippingLineCredit> => {
+      const booking = await mg.findOne(Booking, {
+        where: { id: input.bookingId },
+      });
+      if (!booking) {
+        throw new NotFoundException(`Booking ${input.bookingId} not found`);
+      }
+      if (!booking.shippingLineCompanyId) {
+        throw new BadRequestException(
+          `Booking ${booking.reference} is not a shipping-line booking — customer bookings are billed up front, not on credit.`,
+        );
+      }
+
+      const repo = mg.getRepository(ShippingLineCredit);
+      const existing = await repo.findOne({
+        where: { bookingId: input.bookingId },
+      });
+      if (existing && existing.status !== ShippingLineCreditStatus.Cancelled) {
+        this.logger.warn(
+          `Credit already exists for booking ${booking.reference} (${existing.status}, ${existing.amount} ${existing.currency}) — leaving it unchanged.`,
+        );
+        return existing;
+      }
+
+      const credit = await repo.save(
+        repo.create({
+          shippingLineCompanyId: booking.shippingLineCompanyId,
+          bookingId: input.bookingId,
+          amount: input.amount,
+          currency: input.currency ?? "ETB",
+          description:
+            input.description ?? `Freight service — booking ${booking.reference}`,
+          status: ShippingLineCreditStatus.Unbilled,
+        }),
+      );
+
+      logCtx(
+        {
+          creditId: credit.id,
+          bookingId: credit.bookingId,
+          shippingLineCompanyId: credit.shippingLineCompanyId,
+          amount: credit.amount,
+        },
+        { path: "shippingLineCredit.recorded" },
+      );
+
+      return credit;
+    };
+
+    return manager ? run(manager) : this.dataSource.transaction(run);
+  }
+
+  // ── 2. Bill ────────────────────────────────────────────────────────────────
+
+  /**
+   * Turn a batch of unbilled credits into one invoice.
+   *
+   * Every credit must belong to the SAME shipping line — one invoice has one
+   * payer, so a mixed batch is rejected rather than silently split. The whole
+   * thing runs in one transaction with the credits locked FOR UPDATE, so two
+   * finance users clicking at once cannot bill the same credit twice: the
+   * second transaction blocks, then finds the rows already BILLED and fails.
+   */
+  async generateInvoice(
+    creditIds: string[],
+    options: GenerateCreditInvoiceOptions = {},
+  ): Promise<Invoice> {
+    if (creditIds.length === 0) {
+      throw new BadRequestException(
+        "Select at least one credit to invoice.",
+      );
+    }
+    const uniqueIds = [...new Set(creditIds)];
+
+    return this.dataSource.transaction(async (mg) => {
+      const credits = await this.credits.findByIdsForUpdate(mg, uniqueIds);
+
+      const missing = uniqueIds.filter(
+        (id) => !credits.some((c) => c.id === id),
+      );
+      if (missing.length > 0) {
+        throw new NotFoundException(
+          `Credit(s) not found: ${missing.join(", ")}`,
+        );
+      }
+
+      const alreadyBilled = credits.filter(
+        (c) => c.status !== ShippingLineCreditStatus.Unbilled,
+      );
+      if (alreadyBilled.length > 0) {
+        throw new BadRequestException(
+          `These credits are no longer unbilled and cannot be invoiced: ${alreadyBilled
+            .map((c) => `${c.id} (${c.status})`)
+            .join(", ")}`,
+        );
+      }
+
+      const lineIds = new Set(credits.map((c) => c.shippingLineCompanyId));
+      if (lineIds.size > 1) {
+        throw new BadRequestException(
+          "All selected credits must belong to the same shipping line — one invoice has one payer.",
+        );
+      }
+      const shippingLineCompanyId = credits[0].shippingLineCompanyId;
+
+      const currencies = new Set(credits.map((c) => c.currency));
+      if (currencies.size > 1) {
+        throw new BadRequestException(
+          `Cannot mix currencies on one invoice: ${[...currencies].join(", ")}.`,
+        );
+      }
+      const currency = credits[0].currency;
+
+      const shippingLine = await this.shippingLines.findById(
+        shippingLineCompanyId,
+      );
+      if (!shippingLine) {
+        throw new NotFoundException(
+          `Shipping line ${shippingLineCompanyId} not found`,
+        );
+      }
+
+      const lines: InvoiceLineInput[] = credits.map((credit) => ({
+        chargeType: "SHIPPING_LINE_SERVICE",
+        description: credit.description ?? undefined,
+        quantity: 1,
+        unitRate: Number(credit.amount),
+        amount: Number(credit.amount),
+        currency: credit.currency,
+        metadata: { creditId: credit.id, bookingId: credit.bookingId },
+      }));
+
+      const invoice = await this.billing.generateInvoice(
+        {
+          source: Freight.InvoiceSource.ShippingLineCredit,
+          // Unlike other sources this is the payer, not a single billed
+          // record: the invoice spans many bookings, and each credit keeps its
+          // own booking link.
+          sourceId: shippingLineCompanyId,
+          type: "SHIPPING_LINE_CREDIT",
+          shippingLineCompanyId,
+          currency,
+          lines,
+          dueInDays: options.dueInDays,
+          status: Freight.InvoiceStatus.Issued,
+        },
+        mg,
+      );
+
+      const billedAt = new Date();
+      await mg.update(
+        ShippingLineCredit,
+        { id: In(credits.map((c) => c.id)) },
+        {
+          status: ShippingLineCreditStatus.Billed,
+          invoiceId: invoice.id,
+          billedAt,
+        },
+      );
+
+      logCtx(
+        {
+          invoiceId: invoice.id,
+          invoiceNumber: invoice.invoiceNumber,
+          shippingLineCompanyId,
+          creditCount: credits.length,
+          totalAmount: invoice.totalAmount,
+        },
+        { path: "shippingLineCredit.invoiced" },
+      );
+
+      return invoice;
+    });
+  }
+
+  // ── 3. Settle ──────────────────────────────────────────────────────────────
+
+  /**
+   * Clear the batch once its invoice is paid.
+   *
+   * Driven by the billing event rather than a call inside the payment path, so
+   * the CBE webhook flow needs no knowledge of credits: whatever settles the
+   * invoice — gateway webhook, or a finance-recorded offline payment — this
+   * fires. Idempotent, because a redelivered webhook re-emits the event.
+   */
+  @OnEvent("shipping_line_credit.invoice.paid")
+  async onInvoicePaid(payload: InvoiceEventPayload): Promise<void> {
+    const result = await this.dataSource
+      .getRepository(ShippingLineCredit)
+      .update(
+        {
+          invoiceId: payload.invoiceId,
+          status: ShippingLineCreditStatus.Billed,
+        },
+        { status: ShippingLineCreditStatus.Paid, paidAt: new Date() },
+      );
+
+    logCtx(
+      {
+        invoiceId: payload.invoiceId,
+        invoiceNumber: payload.invoiceNumber,
+        creditsCleared: result.affected ?? 0,
+      },
+      { path: "shippingLineCredit.settled" },
+    );
+
+    // Zero is the ordinary idempotent no-op on webhook redelivery. It is only
+    // worth a line in the log, not an error: the invoice is paid either way.
+    if (!result.affected) {
+      this.logger.log(
+        `Invoice ${payload.invoiceNumber} paid — no BILLED credits left to clear (already settled).`,
+      );
+    }
+  }
+
+  // ── Reads ──────────────────────────────────────────────────────────────────
+
+  /** Finance's worklist: what can go on an invoice for this line right now. */
+  async listUnbilled(shippingLineCompanyId: string) {
+    await this.requireShippingLine(shippingLineCompanyId);
+    const credits = await this.credits.findUnbilled(shippingLineCompanyId);
+    return {
+      items: credits,
+      totalAmount: credits.reduce((sum, c) => sum + Number(c.amount), 0),
+      currency: credits[0]?.currency ?? "ETB",
+    };
+  }
+
+  /** The debt figure shown on the shipping-line detail page. */
+  async outstanding(shippingLineCompanyId: string) {
+    await this.requireShippingLine(shippingLineCompanyId);
+    return this.credits.outstandingFor(shippingLineCompanyId);
+  }
+
+  /** Full ledger for one line, newest first. */
+  async listCredits(
+    shippingLineCompanyId: string,
+    page = 1,
+    pageSize = 20,
+    status?: ShippingLineCreditStatus,
+  ) {
+    await this.requireShippingLine(shippingLineCompanyId);
+    const [items, total] = await this.credits.findAllPaginated(
+      shippingLineCompanyId,
+      (page - 1) * pageSize,
+      pageSize,
+      status,
+    );
+    return { items, total, page, pageSize };
+  }
+
+  /**
+   * The signed-in shipping line's own statement: what it owes and why.
+   * Resolves the line from the session, so one line can never read another's.
+   */
+  async myStatement(userId: string, page = 1, pageSize = 20) {
+    const shippingLine = await this.shippingLines.findByUserId(userId);
+    if (!shippingLine) {
+      throw new ForbiddenException("This account is not a shipping line.");
+    }
+    const [outstanding, ledger] = await Promise.all([
+      this.credits.outstandingFor(shippingLine.id),
+      this.credits.findAllPaginated(
+        shippingLine.id,
+        (page - 1) * pageSize,
+        pageSize,
+      ),
+    ]);
+    return {
+      outstanding,
+      items: ledger[0],
+      total: ledger[1],
+      page,
+      pageSize,
+    };
+  }
+
+  // ── Cancellation ───────────────────────────────────────────────────────────
+
+  /**
+   * Write off an unbilled credit (booking voided, charge raised in error).
+   * Only UNBILLED credits can be cancelled — once a credit is on an issued
+   * invoice, the invoice is what has to be cancelled or credited, otherwise
+   * the invoice total would stop matching the sum of its lines.
+   */
+  async cancelCredit(
+    creditId: string,
+    reason: string,
+  ): Promise<ShippingLineCredit> {
+    return this.dataSource.transaction(async (mg) => {
+      const [credit] = await this.credits.findByIdsForUpdate(mg, [creditId]);
+      if (!credit) {
+        throw new NotFoundException(`Credit ${creditId} not found`);
+      }
+      if (credit.status !== ShippingLineCreditStatus.Unbilled) {
+        throw new BadRequestException(
+          `Only an unbilled credit can be cancelled; this one is ${credit.status}. Cancel or credit invoice ${credit.invoiceId} instead.`,
+        );
+      }
+
+      await mg.update(
+        ShippingLineCredit,
+        { id: creditId },
+        {
+          status: ShippingLineCreditStatus.Cancelled,
+          cancelledAt: new Date(),
+          cancellationReason: reason,
+        },
+      );
+
+      return { ...credit, status: ShippingLineCreditStatus.Cancelled };
+    });
+  }
+
+  private async requireShippingLine(shippingLineCompanyId: string) {
+    const shippingLine = await this.shippingLines.findById(
+      shippingLineCompanyId,
+    );
+    if (!shippingLine) {
+      throw new NotFoundException(
+        `Shipping line ${shippingLineCompanyId} not found`,
+      );
+    }
+    return shippingLine;
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts
index 6bf03c93d..558ffc1a9 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-invoice.service.ts
@@ -99,7 +99,9 @@ interface InventoryContext {
 interface ViewSource {
   id: string;
   invoiceNumber: string;
-  companyId: string;
+  /** Nullable on the entity (shipping-line invoices have no company); every
+   * warehouse invoice is customer-billed, so in practice this is always set. */
+  companyId: string | null;
   sourceId: string;
   type: string;
   status: Freight.InvoiceStatus | string;
diff --git a/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts b/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
index dd8f9bd20..53f7ad2d2 100644
--- a/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
+++ b/apps/edr-freight-api/src/seed/file-upload-settings.seeder.ts
@@ -643,6 +643,21 @@ const INTERCITY_DOCUMENT_SETTINGS: OnboardingDocumentSetting[] = [
   },
 ];
 
+// ── Shipping line booking documents ─────────────────────────────────────────
+// Collected on a shipping line's booking right after it is initiated. Shipping
+// lines book without a contract, so this set — not a contract — is what
+// Operations reviews before the booking may be completed. Fields start empty
+// and are configured in the backoffice file-settings editor, like the sets
+// above. `entity: "booking"` puts it alongside the other per-booking sets.
+const SHIPPING_LINE_DOCUMENT_SETTINGS: OnboardingDocumentSetting[] = [
+  {
+    code: "shipping_line_booking_documents",
+    label: "Shipping line booking documents",
+    entity: "booking",
+    fields: [],
+  },
+];
+
 // ── Hazardous cargo documents ───────────────────────────────────────────────
 // Asked for in the contract wizard the moment the customer flags the cargo as
 // hazardous (ONE_TIME contracts only). Fields start empty and are configured in
@@ -701,6 +716,11 @@ export class FileUploadSettingsSeeder {
           description:
             "Intercity shipment documents — contract-level for ONE_TIME (after both signatures), per booking for GENERAL; reviewed by Operations.",
         })),
+        ...SHIPPING_LINE_DOCUMENT_SETTINGS.map((s) => ({
+          ...s,
+          description:
+            "Documents a shipping line uploads on a booking it initiated. Reviewed by Operations; the booking can only be completed once they are approved.",
+        })),
       ];
 
     const missing = allSettings.filter((s) => !existingCodes.has(s.code));
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 6c891d830..dbd996c63 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -513,6 +513,25 @@ export const FINANCE_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:invoices:confirm_offline",
     "Confirm offline (bank transfer) invoice payment",
   ),
+  // Shipping lines consume services on credit and are invoiced after the fact,
+  // so what they owe is its own Finance surface, separate from invoices:view —
+  // an unbilled credit is not an invoice yet.
+  perm(
+    "d2c00001-0001-4000-8000-000000000001",
+    "edr_freight_app:shipping_line_credits:view",
+    "View shipping-line credits and outstanding balance",
+  ),
+  perm(
+    "d2c00001-0001-4000-8000-000000000002",
+    "edr_freight_app:shipping_line_credits:invoice",
+    "Generate an invoice from shipping-line credits",
+  ),
+  // Erases a debt outright, which is why it is not folded into :invoice.
+  perm(
+    "d2c00001-0001-4000-8000-000000000003",
+    "edr_freight_app:shipping_line_credits:cancel",
+    "Cancel (write off) an unbilled shipping-line credit",
+  ),
 ];
 
 // E. First / last mile operations
@@ -1730,6 +1749,13 @@ export const FREIGHT_PERMS = {
     update: "edr_freight_app:shipping_lines:update",
     resetPassword: "edr_freight_app:shipping_lines:reset-password",
   },
+  shippingLineCredits: {
+    view: "edr_freight_app:shipping_line_credits:view",
+    /** Turn a batch of unbilled credits into an invoice. */
+    invoice: "edr_freight_app:shipping_line_credits:invoice",
+    /** Write off an unbilled credit — separate grant: it erases a debt. */
+    cancel: "edr_freight_app:shipping_line_credits:cancel",
+  },
   payments: {
     view: "edr_freight_app:payments:view",
   },
diff --git a/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx b/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx
index 397496fd2..8682844d8 100644
--- a/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx
@@ -257,6 +257,34 @@ const RuleEngineFormDialog = ({
         next.cargoTypeId = "";
         next.rateUnit = "";
       }
+      // Turning the shipping-line toggle on or off swaps the entire form, so
+      // nothing answered under the other shape may survive into the payload.
+      if (name === "isShippingLineRate") {
+        next.shippingLineCompanyId = "";
+        next.shippingLineRateKind = "";
+        next.shippingLineCargoKind = "";
+        next.appliesTo = "";
+        next.trigger = "";
+        next.containerTypeId = "";
+        next.cargoTypeId = "";
+        next.originYardId = "";
+        next.destinationYardId = "";
+        next.rateUnit = "";
+      }
+      // Base-vs-surcharge and container-vs-bulk each decide the scope field and
+      // the legal units for a shipping-line rate, exactly as appliesTo and
+      // cargoKind do on the customer form.
+      if (name === "shippingLineRateKind" || name === "shippingLineCargoKind") {
+        next.containerTypeId = "";
+        next.cargoTypeId = "";
+        next.rateUnit = "";
+        if (name === "shippingLineRateKind") {
+          next.shippingLineCargoKind = "";
+          next.trigger = "";
+          next.originYardId = "";
+          next.destinationYardId = "";
+        }
+      }
       return next;
     });
   };
@@ -347,12 +375,23 @@ const RuleEngineFormDialog = ({
             borderRadius: "var(--mantine-radius-md)",
           }}
         >
-          <Text size="sm" fw={600}>
-            {field.label}
-          </Text>
+          <Stack gap={2}>
+            <Text size="sm" fw={600}>
+              {field.label}
+            </Text>
+            {field.description ? (
+              <Text size="xs" c="dimmed">
+                {field.description}
+              </Text>
+            ) : null}
+          </Stack>
           <Switch
             checked={Boolean(values[field.name])}
             onChange={(e) => setField(field.name, e.currentTarget.checked)}
+            // A toggle that re-targets what an existing record means (e.g. who
+            // a rate is priced for) is create-only — flipping it on a saved row
+            // would silently change every booking that prices off it.
+            disabled={field.disabled || (field.disabledOnEdit && !!initialRecord)}
             size="md"
             color="edr-green"
           />
@@ -493,6 +532,12 @@ const RuleEngineFormDialog = ({
       // Dynamic options (e.g. rate unit) resolve from the live form values so
       // the choices track the other fields the admin has picked.
       const options = field.optionsFromValues ? field.optionsFromValues(values) : (field.options ?? []);
+      // A derived select shows (and submits) its computed value and is locked,
+      // matching the text-input branch — used by fields the shape decides on the
+      // admin's behalf, e.g. a shipping-line rate's import-only direction.
+      const computedSelect = field.computeValue
+        ? String(field.computeValue(values) ?? "")
+        : undefined;
       return (
         <Select
           key={field.name}
@@ -501,9 +546,18 @@ const RuleEngineFormDialog = ({
           placeholder={
             selectOptionsLoading ? "Loading options..." : (field.placeholder ?? "Select an option")
           }
-          value={resolveSelectValue(field, values)}
+          value={
+            computedSelect !== undefined
+              ? computedSelect
+              : resolveSelectValue(field, values)
+          }
           onChange={(v) => setField(field.name, v === RULE_ENGINE_SELECT_NONE ? "" : v)}
-          disabled={selectOptionsLoading}
+          disabled={
+            selectOptionsLoading ||
+            field.disabled ||
+            (field.disabledOnEdit && !!initialRecord) ||
+            computedSelect !== undefined
+          }
           // Mantine's Select is not a native input, so `required` only marks it
           // visually — handleSubmit is what actually blocks an empty one.
           required={field.required}
diff --git a/apps/edr-freight-web/backoffice/src/hooks/rule-engine/useRuleEngine.ts b/apps/edr-freight-web/backoffice/src/hooks/rule-engine/useRuleEngine.ts
index 378ff1fb8..dd5078983 100644
--- a/apps/edr-freight-web/backoffice/src/hooks/rule-engine/useRuleEngine.ts
+++ b/apps/edr-freight-web/backoffice/src/hooks/rule-engine/useRuleEngine.ts
@@ -3,6 +3,8 @@ import toast from "react-hot-toast";
 
 import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
 import { api } from "@/services/api";
+import { shippingLineCompaniesService } from "@/services/shippingLineCompanies.service";
+import type { PaginatedShippingLineCompanies } from "@/types/shippingLineCompany";
 import {
   ruleEngineService,
   type RuleEngineListParams,
@@ -165,6 +167,28 @@ export const useContainerTypeOptions = (
     select: (rows) => buildContainerTypeSelectOptions(rows, includeNone),
   });
 
+/**
+ * Shipping lines a rate can be scoped to. Only ACTIVE lines are offered — the
+ * API refuses a rate filed against a suspended one, so listing them would only
+ * produce an error on submit. Sorted by name so the picker is scannable.
+ */
+export const useShippingLineCompanyOptions = (enabled = true) =>
+  useQuery({
+    queryKey: QUERY_KEYS.RULE_ENGINE.selectOptions("shipping-line-companies", {}),
+    // One page well past the number of carriers on the corridor; the picker
+    // needs the whole list, not a page of it.
+    queryFn: () => shippingLineCompaniesService.list(1, 200),
+    enabled,
+    select: (page: PaginatedShippingLineCompanies) =>
+      page.items
+        .filter((line) => line.status === "active")
+        .map((line) => ({
+          label: line.scacCode ? `${line.name} (${line.scacCode})` : line.name,
+          value: line.id,
+        }))
+        .sort((a, b) => a.label.localeCompare(b.label)),
+  });
+
 /**
  * Approval-step role options, sourced from the live IAM position types. The
  * three pre-IAM role strings are appended (marked "(legacy)") so an approval
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
index dd7513a42..33d872cbc 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
@@ -136,9 +136,20 @@ export default function DocumentClearanceDetailPage() {
     clearance?.milestones?.some(
       (m) => m.milestoneCode === "DOCUMENTS_APPROVED" && m.status === "COMPLETED",
     ) ?? false;
-  const queriesLocked = Boolean(
-    (clearance as Freight.ContractClearanceView | undefined)?.preClearanceFinalized,
-  );
+  // Querying a document is only possible while the booking is actually in
+  // review — the server enforces exactly that (reviewDocument asserts
+  // DOCUMENTS_UNDER_REVIEW), so once clearance is finalized the button could
+  // only ever produce a 400.
+  //
+  // `preClearanceFinalized` alone was not enough: it is a phased-customs field,
+  // so a non-customs booking (self-clearance, and every shipping-line booking)
+  // never sets it and kept offering Query after Operations had finalized.
+  const queriesLocked =
+    Boolean(
+      (clearance as Freight.ContractClearanceView | undefined)
+        ?.preClearanceFinalized,
+    ) ||
+    (booking?.status != null && booking.status !== "DOCUMENTS_UNDER_REVIEW");
   const workflowFiles =
     (clearance as Freight.ContractClearanceView | undefined)?.workflowFiles ?? [];
 
diff --git a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
index e345fb65a..bdb5dfd9c 100644
--- a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
@@ -43,6 +43,7 @@ import {
     useCargoTypeParentOptions,
     useContainerTypeOptions,
     useLiveRateOptions,
+    useShippingLineCompanyOptions,
     useWagonTypeOptions,
     useYardOptions,
     type YardOption,
@@ -93,6 +94,20 @@ const yardOptionsForLegEnd = (
   values: Record<string, unknown>,
   end: "origin" | "destination",
 ): { label: string; value: string }[] => {
+  // A shipping-line rate names its shape in its own fields and is always
+  // import; map it onto the appliesTo/direction pair the rest of this function
+  // reads so the country narrowing is shared rather than duplicated.
+  if (values.isShippingLineRate === true) {
+    if (!values.shippingLineCompanyId) return [];
+    const isBase = values.shippingLineRateKind === "BASE";
+    values = {
+      ...values,
+      appliesTo: isBase
+        ? String(values.shippingLineCargoKind ?? "")
+        : "OTHER",
+      tradeDirection: "IMPORT",
+    };
+  }
   const appliesTo = String(values.appliesTo ?? "");
   let country: string | undefined;
   if (appliesTo === "INTERCITY") {
@@ -280,6 +295,13 @@ const RuleEngineResourcePage = () => {
     useContainerTypeOptions(false, usesContainerTypeField);
   const { data: liveRateOptions, isLoading: liveRateOptionsLoading } =
     useLiveRateOptions(usesLiveRateField);
+  const usesShippingLineField = Boolean(
+    config?.formFields.some((f) => f.name === "shippingLineCompanyId"),
+  );
+  const {
+    data: shippingLineOptions,
+    isLoading: shippingLineOptionsLoading,
+  } = useShippingLineCompanyOptions(usesShippingLineField);
   const { data: wagonTypeOptions, isLoading: wagonTypeOptionsLoading } =
     useWagonTypeOptions(usesWagonTypeField);
   const usesYardField = Boolean(
@@ -390,6 +412,13 @@ const RuleEngineResourcePage = () => {
             ),
         };
       }
+      if (field.name === "shippingLineCompanyId") {
+        return {
+          ...field,
+          type: "select" as const,
+          options: shippingLineOptions ?? [],
+        };
+      }
       if (field.name === "rateId") {
         return {
           ...field,
@@ -612,7 +641,39 @@ const RuleEngineResourcePage = () => {
 
   const handleFormSubmit = (values: Record<string, unknown>) => {
     let payload = values;
-    if (config.slug === "rates") {
+    if (config.slug === "rates" && values.isShippingLineRate === true) {
+      // A shipping-line rate asks its shape as "base freight vs surcharge" +
+      // "container vs bulk"; the API takes the same appliesTo/trigger pair as a
+      // customer rate, so translate here and drop the form-only fields. Always
+      // import (the only direction a line ships) and always USD.
+      const {
+        isShippingLineRate: _toggle,
+        shippingLineRateKind,
+        shippingLineCargoKind,
+        ...rest
+      } = values;
+      void _toggle;
+      const isBase = shippingLineRateKind === "BASE";
+      payload = {
+        ...rest,
+        appliesTo: isBase ? String(shippingLineCargoKind ?? "CONTAINER") : "OTHER",
+        trigger: isBase ? "ALWAYS" : values.trigger,
+        tradeDirection: "IMPORT",
+        currency: "USD",
+      };
+      if (editing?.id && editing.status === "LIVE") {
+        rateChangeWorkflow.submit.mutate(
+          { rateId: String(editing.id), update: payload },
+          {
+            onSuccess: () => {
+              setFormOpen(false);
+              setEditing(null);
+            },
+          },
+        );
+        return;
+      }
+    } else if (config.slug === "rates") {
       // Base-freight categories have no surcharge trigger field — the engine
       // treats them as ALWAYS. Surcharges (Applies to = Other) keep their
       // chosen trigger.
@@ -934,6 +995,7 @@ const RuleEngineResourcePage = () => {
           (usesLiveRateField && liveRateOptionsLoading) ||
           (usesWagonTypeField && wagonTypeOptionsLoading) ||
           (usesYardField && yardOptionsLoading) ||
+          (usesShippingLineField && shippingLineOptionsLoading) ||
           (usesApprovalRoleField && approvalRoleOptionsLoading)
         }
         positionOptions={!editing ? createPositionOptions : undefined}
diff --git a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts
index 4e00a930b..aaddfe926 100644
--- a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts
+++ b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts
@@ -97,7 +97,16 @@ export interface RuleEngineOrderConfig {
 export interface RuleEngineListTab {
   key: string;
   label: string;
-  filters: { appliesTo?: string; trigger?: string };
+  filters: {
+    appliesTo?: string;
+    trigger?: string;
+    /**
+     * "true" = only shipping-line rates, "false" = only standard customer
+     * rates. Sent as a string because tab filters go on the query string
+     * verbatim.
+     */
+    isShippingLineRate?: string;
+  };
 }
 
 export interface RuleEngineResourceConfig {
@@ -205,6 +214,36 @@ const INTERCITY_KINDS = [
   { label: "Bulk", value: "BULK" },
 ];
 
+/**
+ * A shipping-line rate: priced for one carrier's own bookings instead of for
+ * every customer. The toggle drives the whole form — until a line is picked
+ * there is nothing to configure, and the shape questions (base freight vs
+ * surcharge, container vs bulk) are asked only after it is.
+ */
+const isShippingLineRate = (values: Record<string, unknown>) =>
+  values.isShippingLineRate === true;
+
+/** A shipping-line rate whose owning line has been chosen — the rest unlocks. */
+const hasShippingLine = (values: Record<string, unknown>) =>
+  isShippingLineRate(values) && Boolean(values.shippingLineCompanyId);
+
+/**
+ * What a shipping-line rate prices. Deliberately narrower than the customer
+ * form's `appliesTo`: a line buys base rail freight (its own containers or
+ * bulk) or a surcharge, and nothing else — intercity and first/last mile are
+ * customer products.
+ */
+const SHIPPING_LINE_RATE_KINDS = [
+  { label: "Base freight", value: "BASE" },
+  { label: "Surcharge", value: "SURCHARGE" },
+];
+
+/** Container vs bulk, asked once a shipping-line base-freight rate is chosen. */
+const SHIPPING_LINE_CARGO_KINDS = [
+  { label: "Container", value: "CONTAINER" },
+  { label: "Bulk", value: "BULK" },
+];
+
 /** True when the rate being edited is base rail freight, which is priced per leg. */
 const isBaseFreightRate = (values: Record<string, unknown>) =>
   ["BULK", "CONTAINER", "INTERCITY"].includes(String(values.appliesTo ?? ""));
@@ -214,7 +253,15 @@ const isBaseFreightRate = (values: Record<string, unknown>) =>
  * the empty-container return surcharge (sold per route + container type).
  */
 const isRouteScopedRate = (values: Record<string, unknown>) =>
-  isBaseFreightRate(values) ||
+  // A shipping line's base freight is priced per leg exactly like a customer's;
+  // its surcharges are route-scoped on the same triggers.
+  (isShippingLineRate(values)
+    ? hasShippingLine(values) &&
+      (values.shippingLineRateKind === "BASE" ||
+        ["CUSTOMS_CLEARANCE", "WITH_RETURN", "FUEL"].includes(
+          String(values.trigger ?? ""),
+        ))
+    : isBaseFreightRate(values)) ||
   (String(values.appliesTo ?? "") === "OTHER" &&
     ["CUSTOMS_CLEARANCE", "WITH_RETURN", "FUEL"].includes(String(values.trigger ?? "")));
 
@@ -303,6 +350,31 @@ export const rateUnitOptions = (
   values: Record<string, unknown>,
   cargoUnitOfMeasure = "",
 ) => {
+  // A shipping-line rate answers the same two questions under different names —
+  // map them onto the shape the unit table is keyed by. Base freight for a line
+  // is CONTAINER/BULK freight; a line surcharge is OTHER + its trigger.
+  if (isShippingLineRate(values)) {
+    const { shippingLineRateKind: kind, shippingLineCargoKind: cargoKind } = values;
+    if (kind === "BASE") {
+      if (cargoKind !== "CONTAINER" && cargoKind !== "BULK") return [];
+      return allowedRateUnits(
+        String(cargoKind),
+        "ALWAYS",
+        "",
+        cargoUnitOfMeasure,
+      ).map(unitOption);
+    }
+    if (kind === "SURCHARGE" && values.trigger) {
+      return allowedRateUnits(
+        "OTHER",
+        String(values.trigger),
+        String(values.cargoKind ?? ""),
+        cargoUnitOfMeasure,
+      ).map(unitOption);
+    }
+    return [];
+  }
+
   const appliesTo = String(values.appliesTo ?? "");
   const trigger = appliesTo === "OTHER" ? String(values.trigger ?? "") : "ALWAYS";
   if (!appliesTo) return [];
@@ -830,36 +902,51 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
     supportsSearch: true,
     // Category tabs — each filters server-side by appliesTo / trigger.
     listTabs: [
-      { key: "all", label: "All", filters: {} },
-      { key: "container", label: "Container", filters: { appliesTo: "CONTAINER" } },
-      { key: "bulk", label: "Bulk", filters: { appliesTo: "BULK" } },
-      { key: "intercity", label: "Intercity", filters: { appliesTo: "INTERCITY" } },
+      // "All" and every shape tab show customer rates only — a shipping line's
+      // negotiated price is its own list, not an extra row in the standard one.
+      { key: "all", label: "All", filters: { isShippingLineRate: "false" } },
+      {
+        key: "shipping-line",
+        label: "Shipping line",
+        filters: { isShippingLineRate: "true" },
+      },
+      { key: "container", label: "Container", filters: { appliesTo: "CONTAINER", isShippingLineRate: "false" } },
+      { key: "bulk", label: "Bulk", filters: { appliesTo: "BULK", isShippingLineRate: "false" } },
+      { key: "intercity", label: "Intercity", filters: { appliesTo: "INTERCITY", isShippingLineRate: "false" } },
       {
         key: "trucking",
         label: "First / Last mile",
-        filters: { appliesTo: "FIRST_MILE,LAST_MILE" },
+        filters: { appliesTo: "FIRST_MILE,LAST_MILE", isShippingLineRate: "false" },
       },
       {
         key: "customs",
         label: "Customs clearance",
-        filters: { trigger: "CUSTOMS_CLEARANCE" },
+        filters: { trigger: "CUSTOMS_CLEARANCE", isShippingLineRate: "false" },
       },
       {
         key: "return",
         label: "Container return",
-        filters: { trigger: "WITH_RETURN" },
+        filters: { trigger: "WITH_RETURN", isShippingLineRate: "false" },
       },
       {
         key: "surcharges",
         label: "Surcharges",
         filters: {
           appliesTo: "OTHER",
+          isShippingLineRate: "false",
           trigger:
             "HAZARDOUS,OVERWEIGHT,REEFER,SHIPPING_LINE,CONSOLIDATION,LASHING,CANCELLATION,PIL_EXTRA_FEE,FUEL",
         },
       },
     ],
     columns: [
+      // Blank on a standard customer rate; the owning carrier on a line rate.
+      {
+        id: "shippingLineCompany",
+        header: "Shipping line",
+        accessorKey: "shippingLineCompany",
+        format: "entityLabel",
+      },
       { id: "appliesTo", header: "Applies to", accessorKey: "appliesTo", format: "code" },
       { id: "trigger", header: "Trigger", accessorKey: "trigger" },
       // Base freight is priced per leg, so the route is what tells two otherwise
@@ -879,6 +966,59 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
       { id: "status", header: "Status", accessorKey: "status", format: "rateStatus" },
     ],
     formFields: [
+      // ── Shipping line rate ────────────────────────────────────────────────
+      // Flipping this on replaces the whole customer form: the only question
+      // is which line, and the shape questions follow once it is answered.
+      {
+        name: "isShippingLineRate",
+        label: "Shipping line rate",
+        type: "boolean",
+        description:
+          "Price this rate for one shipping line's own bookings instead of for every customer. A line rate replaces the standard rate on that lane — it does not add to it.",
+        // The owner is part of a rate's identity, so switching an existing rate
+        // between customer and line pricing would silently re-target every
+        // booking that prices off it. Create a new rate instead.
+        disabledOnEdit: true,
+        getInitialValue: (record) => Boolean(record.shippingLineCompanyId),
+      },
+      {
+        name: "shippingLineCompanyId",
+        label: "Shipping line",
+        type: "select",
+        required: true,
+        placeholder: "Which shipping line this rate is for",
+        description:
+          "Only this line's bookings price off this rate. A lane the line has no rate for is blocked at booking rather than falling back to the customer price.",
+        disabledOnEdit: true,
+        showIf: isShippingLineRate,
+      },
+      // What the line is buying. Asked only after a line is picked, so the form
+      // stays a single question until then.
+      {
+        name: "shippingLineRateKind",
+        label: "Rate type",
+        type: "select",
+        required: true,
+        options: SHIPPING_LINE_RATE_KINDS,
+        placeholder: "Base freight or a surcharge?",
+        showIf: hasShippingLine,
+        // Not stored: base freight carries trigger ALWAYS, a surcharge anything else.
+        getInitialValue: (record) =>
+          !record.trigger || record.trigger === "ALWAYS" ? "BASE" : "SURCHARGE",
+      },
+      // Container vs bulk — the line form asks this directly instead of folding
+      // it into `appliesTo` the way the customer form does.
+      {
+        name: "shippingLineCargoKind",
+        label: "Cargo kind",
+        type: "select",
+        required: true,
+        options: SHIPPING_LINE_CARGO_KINDS,
+        placeholder: "Is this rate for containers or bulk?",
+        showIf: (v) => hasShippingLine(v) && v.shippingLineRateKind === "BASE",
+        getInitialValue: (record) =>
+          record.appliesTo === "BULK" ? "BULK" : "CONTAINER",
+      },
       {
         name: "appliesTo",
         label: "Applies to",
@@ -887,6 +1027,8 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         options: RATE_APPLIES_TO,
         description:
           "Pick what this rate is for. Bulk/Container/Intercity are base freight; Other is an auto-applied surcharge.",
+        // Derived from the two questions above on a shipping-line rate.
+        showIf: (v) => !isShippingLineRate(v),
       },
       // ── Surcharge trigger — only when Applies to = Other ──────────────────
       {
@@ -897,6 +1039,20 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         options: RATE_TRIGGERS,
         placeholder: "What makes this surcharge apply?",
         showWhen: { field: "appliesTo", equals: ["OTHER"] },
+        showIf: (v) => !isShippingLineRate(v),
+      },
+      // The same trigger list for a shipping-line surcharge — a line incurs the
+      // same charges a customer does (hazard, reefer, demurrage …), just at its
+      // own negotiated price.
+      {
+        name: "trigger",
+        label: "Surcharge trigger",
+        type: "select",
+        required: true,
+        options: RATE_TRIGGERS,
+        placeholder: "What makes this surcharge apply?",
+        showIf: (v) =>
+          hasShippingLine(v) && v.shippingLineRateKind === "SURCHARGE",
       },
       // ── Trade direction — Bulk & Container base freight, plus the route-
       // scoped surcharges (customs clearance; empty-container return, which is
@@ -915,11 +1071,31 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
               ? FUEL_TRADE_DIRECTIONS
               : TRADE_DIRECTIONS.filter((d) => d.value !== "BOTH"),
         showIf: (v) =>
-          ["BULK", "CONTAINER"].includes(String(v.appliesTo ?? "")) ||
-          (String(v.appliesTo ?? "") === "OTHER" &&
-            ["CUSTOMS_CLEARANCE", "WITH_RETURN", "LASHING", "FUEL"].includes(
-              String(v.trigger ?? ""),
-            )),
+          !isShippingLineRate(v) &&
+          (["BULK", "CONTAINER"].includes(String(v.appliesTo ?? "")) ||
+            (String(v.appliesTo ?? "") === "OTHER" &&
+              ["CUSTOMS_CLEARANCE", "WITH_RETURN", "LASHING", "FUEL"].includes(
+                String(v.trigger ?? ""),
+              ))),
+      },
+      // Shipping lines only ever ship import — the export leg is sold through
+      // the customer's contract — so the direction is stated, not asked. Shown
+      // as a locked field rather than hidden so the lane the yard pickers are
+      // filtered by is visible.
+      {
+        name: "tradeDirection",
+        label: "Trade direction",
+        type: "select",
+        required: true,
+        options: [{ label: "Import", value: "IMPORT" }],
+        description: "Shipping line rates are import-only.",
+        disabled: true,
+        // No defaultValue: field names repeat across form variants and the
+        // seeded initial value is shared, so defaulting here would pre-select
+        // Import on the customer form's own direction field too. computeValue
+        // pins IMPORT on submit and locks the input regardless.
+        computeValue: () => "IMPORT",
+        showIf: hasShippingLine,
       },
       // ── Cargo kind — customs clearance is priced separately for containers
       // (one rate per container type) and bulk ───────────────────────────────
@@ -1089,9 +1265,24 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         optional: true,
         placeholder: "Select container type (optional)",
         showIf: (v) =>
-          v.appliesTo === "CONTAINER" ||
-          (v.appliesTo === "INTERCITY" && v.intercityKind === "CONTAINER") ||
-          (v.appliesTo === "OTHER" && v.trigger === "WITH_RETURN"),
+          !isShippingLineRate(v) &&
+          (v.appliesTo === "CONTAINER" ||
+            (v.appliesTo === "INTERCITY" && v.intercityKind === "CONTAINER") ||
+            (v.appliesTo === "OTHER" && v.trigger === "WITH_RETURN")),
+      },
+      // Container type for a shipping-line base-freight rate. Required here,
+      // unlike the customer form's optional catch-all: a line negotiates a
+      // price per box size, so an unscoped line rate has no meaning.
+      {
+        name: "containerTypeId",
+        label: "Container type",
+        type: "select",
+        required: true,
+        placeholder: "Which container type this rate covers",
+        showIf: (v) =>
+          hasShippingLine(v) &&
+          v.shippingLineRateKind === "BASE" &&
+          v.shippingLineCargoKind === "CONTAINER",
       },
       // ── Bulk cargo (leaf commodity) — Bulk freight, and bulk-kind intercity ─
       {
@@ -1101,8 +1292,23 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         optional: true,
         placeholder: "Select bulk commodity (optional)",
         showIf: (v) =>
-          v.appliesTo === "BULK" ||
-          (v.appliesTo === "INTERCITY" && v.intercityKind === "BULK"),
+          !isShippingLineRate(v) &&
+          (v.appliesTo === "BULK" ||
+            (v.appliesTo === "INTERCITY" && v.intercityKind === "BULK")),
+      },
+      // Bulk commodity for a shipping-line base-freight rate. Its unit of
+      // measure decides the rate unit offered below — a counted commodity
+      // (PER_ITEM) prices per item where a weighed one prices per ton.
+      {
+        name: "cargoTypeId",
+        label: "Bulk cargo type",
+        type: "select",
+        required: true,
+        placeholder: "Which bulk commodity this rate covers",
+        showIf: (v) =>
+          hasShippingLine(v) &&
+          v.shippingLineRateKind === "BASE" &&
+          v.shippingLineCargoKind === "BULK",
       },
       // ── The leg this rate prices — base freight only ──────────────────────
       // Options are narrowed to the countries the direction allows (import
diff --git a/apps/edr-freight-web/backoffice/src/services/ruleEngine/ruleEngine.service.ts b/apps/edr-freight-web/backoffice/src/services/ruleEngine/ruleEngine.service.ts
index 682da4fcc..48f944c21 100644
--- a/apps/edr-freight-web/backoffice/src/services/ruleEngine/ruleEngine.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/ruleEngine/ruleEngine.service.ts
@@ -20,6 +20,11 @@ export interface RuleEngineListParams {
   /** Rates category tabs — comma-separated appliesTo / trigger filters. */
   appliesTo?: string;
   trigger?: string;
+  /**
+   * Rates only: "true" lists shipping-line rates, "false" standard customer
+   * ones. Omitted lists both.
+   */
+  isShippingLineRate?: string;
 }
 
 export interface RuleEngineReorderPayload {
@@ -214,6 +219,7 @@ export const ruleEngineService = {
         requiresDirectorApproval: params?.requiresDirectorApproval,
         appliesTo: params?.appliesTo,
         trigger: params?.trigger,
+        isShippingLineRate: params?.isShippingLineRate,
       },
     });
     return normalizeList<T>(response.data, page, pageSize);
diff --git a/apps/edr-freight-web/portal/src/App.tsx b/apps/edr-freight-web/portal/src/App.tsx
index e47ec9faf..38d347d3a 100644
--- a/apps/edr-freight-web/portal/src/App.tsx
+++ b/apps/edr-freight-web/portal/src/App.tsx
@@ -60,6 +60,7 @@ import PaymentFailurePage from "./pages/payments/PaymentFailurePage";
 import FaydaCallbackPage from "./pages/FaydaCallbackPage";
 import PaymentSuccessPage from "./pages/payments/PaymentSuccessPage";
 import {
+  ShippingLineBookingDetailPage,
   ShippingLineBookingsPage,
   ShippingLineHelpPage,
   ShippingLineHomePage,
@@ -418,6 +419,9 @@ const App = () => {
                     onNavigate={navigate}
                     userName={displayName}
                     userEmail={userEmail}
+                    // Support chat is company-scoped; a shipping line has no
+                    // company, so every poll would 403.
+                    showSupportWidget={false}
                   >
                     <Outlet />
                   </AppLayout>
@@ -431,6 +435,10 @@ const App = () => {
                   path="/shipping-line/bookings"
                   element={<ShippingLineBookingsPage />}
                 />
+                <Route
+                  path="/shipping-line/bookings/:id"
+                  element={<ShippingLineBookingDetailPage />}
+                />
                 <Route
                   path="/shipping-line/invoices"
                   element={<ShippingLineInvoicesPage />}
diff --git a/apps/edr-freight-web/portal/src/components/AppLayout.tsx b/apps/edr-freight-web/portal/src/components/AppLayout.tsx
index c5c7a0c31..6e33d66d7 100644
--- a/apps/edr-freight-web/portal/src/components/AppLayout.tsx
+++ b/apps/edr-freight-web/portal/src/components/AppLayout.tsx
@@ -67,6 +67,12 @@ export interface AppLayoutProps {
   }[];
   /** Company type (e.g. "customer", "forwarder") — gates the "Add service" control. */
   companyType?: string | null;
+  /**
+   * Render the floating support-chat launcher. Defaults to true so the customer
+   * portal is unaffected; shipping lines pass false — support chat is scoped to
+   * a company, which they do not have.
+   */
+  showSupportWidget?: boolean;
   /** Create a new service profile of the given type (with business license). */
   onCreateProfile?: (
     type: ServiceType,
@@ -152,6 +158,7 @@ export function AppLayout({
   companyType,
   onCreateProfile,
   onReapplyProfile,
+  showSupportWidget = true,
   children,
 }: AppLayoutProps) {
   const [mobileOpen, { toggle: toggleMobile }] = useDisclosure();
@@ -859,8 +866,10 @@ export function AppLayout({
         {children}
       </AppShell.Main>
 
-      {/* Floating customer-support chat launcher. */}
-      <SupportWidget />
+      {/* Floating customer-support chat launcher. Hidden when the caller opts
+          out: support chat resolves the user's external profile → company, and
+          a shipping line has neither, so every poll would 403. */}
+      {showSupportWidget && <SupportWidget />}
 
       {/* Create-profile modal — opens when switching to a mode the company
           doesn't have a profile for yet. */}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingDetailPage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingDetailPage.tsx
new file mode 100644
index 000000000..109f2e8cf
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingDetailPage.tsx
@@ -0,0 +1,402 @@
+import {
+  Alert,
+  Badge,
+  Button,
+  Center,
+  Group,
+  Loader,
+  Modal,
+  Stack,
+  Tabs,
+  Text,
+  Textarea,
+} from "@mantine/core";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  AlertCircle,
+  ArrowLeft,
+  Ban,
+  CheckCircle2,
+  ClipboardList,
+  Clock,
+  FileText,
+  Package,
+  Upload,
+} from "lucide-react";
+import { useState } from "react";
+import { useNavigate, useParams } from "react-router-dom";
+
+import { BookingStatusBadge as StatusBadge } from "@/pages/bookings/booking-display";
+import {
+  BodyGrid,
+  CardTitle,
+  PageShell,
+  SectionCard,
+} from "@/pages/bookings/BookingDetailPage/components/layout";
+import type { ShippingLineBooking } from "@/services/shipping-line-bookings.service";
+import { shippingLineBookingsService } from "@/services/shipping-line-bookings.service";
+
+import {
+  bookingDocState,
+  hasDocuments,
+  needsUpload,
+  DOC_STATE_ACTION_LABEL,
+  DOC_STATE_COLOR,
+  DOC_STATE_LABEL,
+} from "./booking-doc-state";
+import ShippingLineDocumentsModal from "./ShippingLineDocumentsModal";
+
+/**
+ * Statuses a booking can be cancelled from — everything before it is priced.
+ * Mirrors SHIPPING_LINE_CANCELLABLE_STATUSES on the API.
+ */
+const CANCELLABLE_STATUSES = new Set([
+  "AWAITING_DOCUMENTS",
+  "DOCUMENTS_UNDER_REVIEW",
+  "CLEARANCE_READY",
+  "CHANGES_REQUESTED",
+]);
+
+/**
+ * Shipping-line booking detail.
+ *
+ * Shaped like the customer booking detail page — same shell, same two-column
+ * body — but split into Documents / Booking details tabs, since a bare
+ * shipping-line booking has little else to show until it is completed.
+ */
+export default function ShippingLineBookingDetailPage() {
+  const { id = "" } = useParams();
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+  const [docsOpen, setDocsOpen] = useState(false);
+  const [cancelOpen, setCancelOpen] = useState(false);
+  const [cancelReason, setCancelReason] = useState("");
+
+  const bookingQuery = useQuery({
+    queryKey: ["shipping-line-bookings", id],
+    queryFn: () => shippingLineBookingsService.getById(id),
+    enabled: Boolean(id),
+  });
+
+  const cancelMutation = useMutation({
+    mutationFn: () => shippingLineBookingsService.cancel(id, cancelReason),
+    onSuccess: () => {
+      setCancelOpen(false);
+      setCancelReason("");
+      void queryClient.invalidateQueries({
+        queryKey: ["shipping-line-bookings"],
+      });
+    },
+  });
+
+  if (bookingQuery.isLoading) {
+    return (
+      <PageShell>
+        <Center py={80}>
+          <Loader size="sm" />
+        </Center>
+      </PageShell>
+    );
+  }
+
+  if (bookingQuery.isError || !bookingQuery.data) {
+    return (
+      <PageShell>
+        <Alert color="red">This booking could not be loaded.</Alert>
+      </PageShell>
+    );
+  }
+
+  const booking: ShippingLineBooking = bookingQuery.data;
+  const status = booking.status as string;
+  const docState = bookingDocState(booking);
+  const showDocs = hasDocuments(docState);
+  const wantsUpload = needsUpload(docState);
+  const actionNeeded = docState === "ACTION_NEEDED";
+
+  // Mirrors the server's rule: cancellable only before the booking is priced.
+  // Kept in sync deliberately — a button the API would reject is worse than no
+  // button at all.
+  const canCancel =
+    CANCELLABLE_STATUSES.has(status) && !(Number(booking.totalAmount ?? 0) > 0);
+
+  return (
+    <PageShell>
+      <Button
+        variant="subtle"
+        color="gray"
+        size="compact-sm"
+        w="fit-content"
+        leftSection={<ArrowLeft size={15} />}
+        onClick={() => navigate("/shipping-line/bookings")}
+      >
+        Back to bookings
+      </Button>
+
+      <Group justify="space-between" align="flex-start" wrap="wrap" gap="md">
+        <Stack gap={8} miw={0}>
+          <Text fz="26px" fw={800} c="#10202F">
+            {booking.reference}
+          </Text>
+          <Group gap={8}>
+            <StatusBadge status={status} />
+            {showDocs && (
+              <Badge
+                size="sm"
+                variant="light"
+                radius="sm"
+                color={DOC_STATE_COLOR[docState]}
+                leftSection={
+                  actionNeeded ? <AlertCircle size={12} /> : undefined
+                }
+              >
+                {DOC_STATE_LABEL[docState]}
+              </Badge>
+            )}
+          </Group>
+        </Stack>
+
+        <Group gap="sm">
+          {canCancel && (
+            <Button
+              variant="light"
+              color="red"
+              radius="md"
+              leftSection={<Ban size={16} />}
+              onClick={() => setCancelOpen(true)}
+            >
+              Cancel booking
+            </Button>
+          )}
+          {showDocs && (
+            <Button
+              color={actionNeeded ? "red" : "edr-green"}
+              variant={wantsUpload ? "filled" : "light"}
+              radius="md"
+              leftSection={
+                wantsUpload ? <Upload size={16} /> : <FileText size={16} />
+              }
+              onClick={() => setDocsOpen(true)}
+            >
+              {DOC_STATE_ACTION_LABEL[docState]}
+            </Button>
+          )}
+        </Group>
+      </Group>
+
+      <Tabs defaultValue="documents" keepMounted={false}>
+        <Tabs.List>
+          <Tabs.Tab
+            value="documents"
+            leftSection={<FileText size={15} />}
+            // The one place a query surfaces without opening the tab.
+            rightSection={
+              actionNeeded ? (
+                <Badge size="xs" circle variant="filled" color="red">
+                  !
+                </Badge>
+              ) : undefined
+            }
+          >
+            Documents
+          </Tabs.Tab>
+          <Tabs.Tab value="details" leftSection={<Package size={15} />}>
+            Booking details
+          </Tabs.Tab>
+        </Tabs.List>
+
+        <Tabs.Panel value="documents" pt="lg">
+          <SectionCard>
+            <CardTitle>Documents</CardTitle>
+
+            <Stack gap="md" mt="sm">
+              {docState === "ACTION_NEEDED" ? (
+                <Alert color="red" radius="md" icon={<AlertCircle size={18} />}>
+                  Operations returned one or more documents with a query. Open
+                  the documents, read the note on each flagged item and upload a
+                  corrected file — the booking cannot move on until you do.
+                </Alert>
+              ) : docState === "AWAITING" ? (
+                <Alert
+                  color="yellow"
+                  radius="md"
+                  icon={<ClipboardList size={18} />}
+                >
+                  This booking is waiting on your documents. Upload them for
+                  Operations to review — the booking can be completed once they
+                  are approved.
+                </Alert>
+              ) : docState === "IN_REVIEW" ? (
+                <Alert color="blue" radius="md" icon={<Clock size={18} />}>
+                  Your documents are with Operations for review. You can still
+                  open them, and replace any that come back with a query.
+                </Alert>
+              ) : (
+                <Alert
+                  color="teal"
+                  radius="md"
+                  icon={<CheckCircle2 size={18} />}
+                >
+                  Your documents are approved.
+                </Alert>
+              )}
+
+              <Button
+                color={actionNeeded ? "red" : "edr-green"}
+                variant={wantsUpload ? "filled" : "light"}
+                radius="md"
+                w="fit-content"
+                leftSection={
+                  wantsUpload ? <Upload size={16} /> : <FileText size={16} />
+                }
+                onClick={() => setDocsOpen(true)}
+              >
+                {DOC_STATE_ACTION_LABEL[docState]}
+              </Button>
+            </Stack>
+          </SectionCard>
+        </Tabs.Panel>
+
+        <Tabs.Panel value="details" pt="lg">
+          <BodyGrid
+            left={
+              <SectionCard>
+                <CardTitle>Shipment</CardTitle>
+                <Stack gap="xs" mt="sm">
+                  {/* Set at initiate time from the chosen route, so it is
+                      known before Operations reviews the documents. */}
+                  <DetailRow
+                    label="Route"
+                    value={
+                      booking.originYard || booking.destinationYard
+                        ? `${
+                            booking.originYard?.label ??
+                            booking.originYard?.code ??
+                            "—"
+                          } → ${
+                            booking.destinationYard?.label ??
+                            booking.destinationYard?.code ??
+                            "—"
+                          }`
+                        : "—"
+                    }
+                  />
+                  <DetailRow
+                    label="Freight type"
+                    value={booking.freightType ?? "—"}
+                  />
+                  <DetailRow
+                    label="Trade direction"
+                    value={booking.tradeDirection ?? "—"}
+                  />
+                  <DetailRow
+                    label="Shipment day"
+                    value={
+                      booking.scheduledDate
+                        ? new Date(booking.scheduledDate).toLocaleDateString()
+                        : "Not scheduled yet"
+                    }
+                  />
+                </Stack>
+              </SectionCard>
+            }
+            right={
+              <SectionCard>
+                <CardTitle>Booking</CardTitle>
+                <Stack gap="xs" mt="sm">
+                  <DetailRow label="Reference" value={booking.reference} />
+                  <DetailRow label="Status" value={status} />
+                  <DetailRow
+                    label="Created"
+                    value={
+                      booking.createdAt
+                        ? new Date(booking.createdAt).toLocaleDateString()
+                        : "—"
+                    }
+                  />
+                </Stack>
+              </SectionCard>
+            }
+          />
+        </Tabs.Panel>
+      </Tabs>
+
+      <ShippingLineDocumentsModal
+        booking={docsOpen ? booking : null}
+        onClose={() => setDocsOpen(false)}
+      />
+
+      {/* Cancelling is irreversible, so it asks first rather than firing on the
+          button press. The reason is optional but recorded. */}
+      <Modal
+        opened={cancelOpen}
+        onClose={() => setCancelOpen(false)}
+        centered
+        radius="md"
+        title={
+          <Text fw={700} fz={16}>
+            Cancel this booking?
+          </Text>
+        }
+        overlayProps={{ blur: 2, backgroundOpacity: 0.55 }}
+      >
+        <Stack gap="md">
+          <Alert color="red" variant="light" icon={<AlertCircle size={18} />}>
+            Booking <strong>{booking.reference}</strong> will be cancelled. This
+            cannot be undone — you would need to initiate a new booking.
+          </Alert>
+
+          <Textarea
+            label="Reason (optional)"
+            placeholder="Why are you cancelling this booking?"
+            autosize
+            minRows={2}
+            maxRows={4}
+            maxLength={500}
+            value={cancelReason}
+            onChange={(e) => setCancelReason(e.currentTarget.value)}
+          />
+
+          {cancelMutation.isError && (
+            <Alert color="red" icon={<AlertCircle size={16} />}>
+              {(cancelMutation.error as Error)?.message ??
+                "Could not cancel the booking."}
+            </Alert>
+          )}
+
+          <Group justify="flex-end" gap="sm">
+            <Button
+              variant="default"
+              radius="md"
+              onClick={() => setCancelOpen(false)}
+            >
+              Keep booking
+            </Button>
+            <Button
+              color="red"
+              radius="md"
+              leftSection={<Ban size={16} />}
+              loading={cancelMutation.isPending}
+              onClick={() => cancelMutation.mutate()}
+            >
+              Cancel booking
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
+    </PageShell>
+  );
+}
+
+function DetailRow({ label, value }: { label: string; value: string }) {
+  return (
+    <Group justify="space-between" align="flex-start" gap="md" wrap="nowrap">
+      <Text fz={13} c="edr-muted">
+        {label}
+      </Text>
+      <Text fz={13} fw={600} ta="right">
+        {value}
+      </Text>
+    </Group>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
index e949e54fa..efdc917db 100644
--- a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
@@ -1,17 +1,314 @@
-import { Package } from "lucide-react";
-import ShippingLinePlaceholder from "./ShippingLinePlaceholder";
+import {
+  ActionIcon,
+  Badge,
+  Box,
+  Button,
+  Card,
+  Group,
+  Menu,
+  Stack,
+  Text,
+  Title,
+} from "@mantine/core";
+import { useQuery } from "@tanstack/react-query";
+import {
+  DataTable,
+  DataTableFooter,
+  type ColumnDef,
+  usePagination,
+} from "@edr/ui-common";
+import {
+  AlertCircle,
+  FileText,
+  MoreVertical,
+  Package,
+  Plus,
+  Upload,
+} from "lucide-react";
+import { useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
 
-/**
- * Shipping-line bookings. Contracts do not apply to shipping lines, so a
- * booking is requested directly here rather than being created against a
- * contract the way the customer flow does it.
- */
-export default function ShippingLineBookingsPage() {
+import { BookingStatusBadge as StatusBadge } from "@/pages/bookings/booking-display";
+import type { ShippingLineBooking } from "@/services/shipping-line-bookings.service";
+import { shippingLineBookingsService } from "@/services/shipping-line-bookings.service";
+
+import {
+  bookingDocState,
+  hasDocuments,
+  needsUpload,
+  DOC_STATE_ACTION_LABEL,
+  DOC_STATE_COLOR,
+  DOC_STATE_LABEL,
+} from "./booking-doc-state";
+import ShippingLineDocumentsModal from "./ShippingLineDocumentsModal";
+import ShippingLineInitiateModal from "./ShippingLineInitiateModal";
+
+function ColHeader({ label }: { label: string }) {
   return (
-    <ShippingLinePlaceholder
-      title="Bookings"
-      description="Request and track your booking requests."
-      icon={<Package size={28} className="text-slate-300" />}
-    />
+    <Text fz={12} fw={700} c="edr-muted" tt="uppercase" lts="0.04em">
+      {label}
+    </Text>
+  );
+}
+
+/**
+ * Shipping-line bookings list.
+ *
+ * Mirrors the customer bookings list (same DataTable, status badge, row-click
+ * to detail and per-row action menu) so the two portals read the same. What
+ * differs is the flow behind it: contracts do not apply to shipping lines, so
+ * "Initiate booking" creates a bare booking directly rather than routing
+ * through a contract.
+ */
+export default function ShippingLineBookingsPage() {
+  const navigate = useNavigate();
+  const { pagination, setPagination } = usePagination();
+  const [docsBooking, setDocsBooking] = useState<ShippingLineBooking | null>(
+    null,
+  );
+
+  const bookingsQuery = useQuery({
+    queryKey: ["shipping-line-bookings"],
+    queryFn: shippingLineBookingsService.list,
+  });
+
+  const [initiateOpen, setInitiateOpen] = useState(false);
+
+  const rows = useMemo(() => bookingsQuery.data ?? [], [bookingsQuery.data]);
+
+  const status = bookingsQuery.isLoading
+    ? "loading"
+    : bookingsQuery.isError
+      ? "error"
+      : "success";
+  const showEmpty = status === "success" && rows.length === 0;
+
+  const columns: ColumnDef<ShippingLineBooking>[] = [
+    {
+      id: "reference",
+      header: () => <ColHeader label="Booking" />,
+      cell: ({ row }) => (
+        <Text fw={700} fz={14}>
+          {row.original.reference}
+        </Text>
+      ),
+    },
+    {
+      id: "route",
+      header: () => <ColHeader label="Route" />,
+      cell: ({ row }) => {
+        const b = row.original;
+        const origin = b.originYard?.label ?? b.originYard?.code;
+        const dest = b.destinationYard?.label ?? b.destinationYard?.code;
+        return (
+          <Text fz={13} c={origin && dest ? undefined : "edr-muted"}>
+            {origin && dest ? `${origin} → ${dest}` : "—"}
+          </Text>
+        );
+      },
+    },
+    {
+      id: "status",
+      header: () => <ColHeader label="Status" />,
+      cell: ({ row }) => <StatusBadge status={row.original.status} />,
+    },
+    {
+      id: "documents",
+      header: () => <ColHeader label="Documents" />,
+      cell: ({ row }) => {
+        const state = bookingDocState(row.original);
+        if (state === "NONE") return null;
+        return (
+          <Badge
+            size="sm"
+            variant="light"
+            radius="sm"
+            color={DOC_STATE_COLOR[state]}
+            leftSection={
+              state === "ACTION_NEEDED" ? <AlertCircle size={12} /> : undefined
+            }
+          >
+            {DOC_STATE_LABEL[state]}
+          </Badge>
+        );
+      },
+    },
+    {
+      id: "created",
+      header: () => <ColHeader label="Created" />,
+      cell: ({ row }) => (
+        <Text fz={13} c="edr-muted">
+          {row.original.createdAt
+            ? new Date(row.original.createdAt).toLocaleDateString()
+            : "—"}
+        </Text>
+      ),
+    },
+    {
+      id: "actions",
+      size: 200,
+      header: () => null,
+      cell: ({ row }) => {
+        const booking = row.original;
+        const state = bookingDocState(booking);
+        const showDocs = hasDocuments(state);
+        const wantsUpload = needsUpload(state);
+
+        return (
+          <Group
+            gap={6}
+            justify="flex-end"
+            wrap="nowrap"
+            onClick={(e) => e.stopPropagation()}
+          >
+            {showDocs && (
+              <Button
+                size="xs"
+                radius="md"
+                variant="light"
+                // A queried document is the one case that needs to pull the
+                // eye — it is the only state where the shipping line is
+                // blocking its own booking.
+                color={state === "ACTION_NEEDED" ? "red" : "edr-green"}
+                fw={700}
+                fz={13}
+                leftSection={
+                  wantsUpload ? <Upload size={14} /> : <FileText size={14} />
+                }
+                onClick={() => setDocsBooking(booking)}
+              >
+                {DOC_STATE_ACTION_LABEL[state]}
+              </Button>
+            )}
+            <Menu position="bottom-end" withinPortal shadow="md" radius="md">
+              <Menu.Target>
+                <ActionIcon
+                  variant="transparent"
+                  size={30}
+                  radius="md"
+                  aria-label="More options"
+                >
+                  <MoreVertical size={16} color="#9AA8B5" />
+                </ActionIcon>
+              </Menu.Target>
+              <Menu.Dropdown>
+                <Menu.Item
+                  onClick={() =>
+                    navigate(`/shipping-line/bookings/${booking.id}`)
+                  }
+                >
+                  View details
+                </Menu.Item>
+                {showDocs && (
+                  <Menu.Item
+                    leftSection={
+                      wantsUpload ? (
+                        <Upload size={15} />
+                      ) : (
+                        <FileText size={15} />
+                      )
+                    }
+                    onClick={() => setDocsBooking(booking)}
+                  >
+                    {DOC_STATE_ACTION_LABEL[state]}
+                  </Menu.Item>
+                )}
+              </Menu.Dropdown>
+            </Menu>
+          </Group>
+        );
+      },
+    },
+  ];
+
+  return (
+    <Box style={{ padding: "28px 32px 32px" }}>
+      <Stack gap="lg">
+        <Group justify="space-between" align="flex-end" wrap="wrap" gap="md">
+          <Box>
+            <Title
+              order={1}
+              fw={800}
+              fz={26}
+              style={{ letterSpacing: "-0.01em" }}
+            >
+              Bookings
+            </Title>
+            <Text size="sm" c="edr-muted" mt={4}>
+              Request a booking directly — no contract required.
+            </Text>
+          </Box>
+          <Button
+            color="edr-green"
+            radius="md"
+            leftSection={<Plus size={16} />}
+            onClick={() => setInitiateOpen(true)}
+          >
+            Initiate booking
+          </Button>
+        </Group>
+
+        <Card radius={16} p={0} withBorder style={{ borderColor: "#E6ECF2" }}>
+          {showEmpty ? (
+            <Stack align="center" gap="xs" py={64}>
+              <Package size={28} className="text-slate-300" />
+              <Text c="edr-muted" size="sm">
+                No bookings yet — initiate one to get started.
+              </Text>
+              <Button
+                size="sm"
+                mt="md"
+                variant="light"
+                color="edr-green"
+                onClick={() => setInitiateOpen(true)}
+              >
+                Initiate booking
+              </Button>
+            </Stack>
+          ) : (
+            <DataTable
+              columns={columns}
+              data={rows}
+              status={status}
+              onRowClick={(row) =>
+                navigate(
+                  `/shipping-line/bookings/${(row as ShippingLineBooking).id}`,
+                )
+              }
+              pagination={{
+                pageIndex: pagination.pageIndex,
+                pageSize: pagination.pageSize,
+                pageCount: Math.max(
+                  1,
+                  Math.ceil(rows.length / pagination.pageSize),
+                ),
+                totalCount: rows.length,
+              }}
+              tableOptions={{
+                state: { pagination },
+                onPaginationChange: setPagination,
+              }}
+              containerClassName="border-0 shadow-none rounded-none"
+              footer={DataTableFooter}
+            />
+          )}
+        </Card>
+      </Stack>
+
+      <ShippingLineInitiateModal
+        opened={initiateOpen}
+        onClose={() => setInitiateOpen(false)}
+        onCreated={(booking) => {
+          setInitiateOpen(false);
+          // Straight into the new booking — documents are the next thing owed.
+          navigate(`/shipping-line/bookings/${booking.id}`);
+        }}
+      />
+
+      <ShippingLineDocumentsModal
+        booking={docsBooking}
+        onClose={() => setDocsBooking(null)}
+      />
+    </Box>
   );
 }
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineDocumentsModal.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineDocumentsModal.tsx
new file mode 100644
index 000000000..53b98c497
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineDocumentsModal.tsx
@@ -0,0 +1,248 @@
+import {
+  Alert,
+  Box,
+  Button,
+  Center,
+  Group,
+  Loader,
+  Modal,
+  Stack,
+  Text,
+} from "@mantine/core";
+import type { ShippingLineBooking } from "@/services/shipping-line-bookings.service";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { AlertCircle, CheckCircle2, Clock, Upload } from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+
+import { ClearanceDocumentUploadCard } from "@/components/contracts/ClearanceDocumentUploadCard";
+import { useFileViewer } from "@/hooks/useFileViewer";
+import { shippingLineBookingsService } from "@/services/shipping-line-bookings.service";
+
+/**
+ * Document upload for a shipping-line booking.
+ *
+ * Deliberately the same surface as the customer clearance modal
+ * (`BookingActionModal`): the grid is built from the booking's clearance view,
+ * so every field shows its uploaded file, its review badge and the reviewer's
+ * note, and can be replaced in place — an approved document is locked, exactly
+ * as it is for customers.
+ */
+export default function ShippingLineDocumentsModal({
+  booking,
+  onClose,
+}: {
+  booking: ShippingLineBooking | null;
+  onClose: () => void;
+}) {
+  const queryClient = useQueryClient();
+  const { view, viewer } = useFileViewer();
+  // Files picked but not yet submitted, keyed by document field.
+  const [pending, setPending] = useState<Record<string, File>>({});
+
+  // Each booking gets a fresh sheet — otherwise files staged for one booking
+  // would still be attached when the modal reopens on another.
+  useEffect(() => {
+    setPending({});
+  }, [booking?.id]);
+
+  const clearanceQuery = useQuery({
+    queryKey: ["shipping-line-clearance", booking?.id],
+    queryFn: () => shippingLineBookingsService.getClearance(booking!.id),
+    enabled: booking !== null,
+  });
+
+  const uploadMutation = useMutation({
+    mutationFn: () =>
+      shippingLineBookingsService.uploadDocuments(booking!.id, pending),
+    onSuccess: () => {
+      setPending({});
+      void queryClient.invalidateQueries({
+        queryKey: ["shipping-line-bookings"],
+      });
+      void queryClient.invalidateQueries({
+        queryKey: ["shipping-line-clearance", booking?.id],
+      });
+      onClose();
+    },
+  });
+
+  const clearance = clearanceQuery.data;
+  const status = clearance?.status ?? booking?.status ?? "";
+
+  // The fields this booking asks for. `uploadedBy: "gl"` rows are staff output
+  // documents, which the uploader never fills in.
+  const docs = useMemo(
+    () => (clearance?.documents ?? []).filter((d) => d.uploadedBy !== "gl"),
+    [clearance],
+  );
+
+  // Uploads are accepted while the booking is awaiting documents or already in
+  // review (fixing a queried one) — matching the server's own status gate.
+  const canUpload =
+    status === "AWAITING_DOCUMENTS" || status === "DOCUMENTS_UNDER_REVIEW";
+  const isInitialUpload = status === "AWAITING_DOCUMENTS";
+
+  // Documents a reviewer sent back. These are what the shipping line has to
+  // act on, and the reason the modal leads with a red banner rather than the
+  // neutral "in review" one.
+  const queriedDocs = docs.filter((d) => d.reviewStatus === "QUERIED");
+
+  const missingRequired = docs.filter(
+    (d) => d.required && !d.file && !pending[d.fileKey],
+  );
+  const hasStaged = Object.keys(pending).length > 0;
+
+  // First submission must cover every required field; later rounds only need
+  // the specific documents being corrected.
+  const canSubmit = isInitialUpload
+    ? hasStaged && missingRequired.length === 0
+    : hasStaged;
+
+  const stage = (fileKey: string, file: File | null) =>
+    setPending((p) => {
+      if (file) return { ...p, [fileKey]: file };
+      const next = { ...p };
+      delete next[fileKey];
+      return next;
+    });
+
+  return (
+    <>
+      <Modal
+        opened={booking !== null}
+        onClose={onClose}
+        centered
+        size="xl"
+        radius="md"
+        title={
+          <Box>
+            <Text fw={700} fz={16}>
+              Booking documents
+            </Text>
+            <Text fz={12} c="dimmed" ff="monospace">
+              {booking?.reference}
+            </Text>
+          </Box>
+        }
+        overlayProps={{ blur: 2, backgroundOpacity: 0.55 }}
+        styles={{ body: { paddingTop: 8 } }}
+      >
+        {clearanceQuery.isLoading ? (
+          <Center py="xl">
+            <Loader size="sm" />
+          </Center>
+        ) : docs.length === 0 ? (
+          <Text fz="13px" c="dimmed" py="md">
+            No document requirements are configured yet. Staff set these up in
+            the backoffice under Settings → File settings.
+          </Text>
+        ) : (
+          <Stack gap={0}>
+            {queriedDocs.length > 0 ? (
+              <Alert
+                color="red"
+                radius="md"
+                icon={<AlertCircle size={18} />}
+                mb="md"
+              >
+                {queriedDocs.length === 1
+                  ? `"${queriedDocs[0].label}" was returned with a query. `
+                  : `${queriedDocs.length} documents were returned with a query. `}
+                Read the note on each flagged document below and upload a
+                corrected file.
+              </Alert>
+            ) : status === "DOCUMENTS_UNDER_REVIEW" ? (
+              <Alert
+                color="blue"
+                radius="md"
+                icon={<Clock size={18} />}
+                mb="md"
+              >
+                Our team is reviewing your documents. Only re-upload the
+                documents flagged with a query below — approved documents stay
+                as they are.
+              </Alert>
+            ) : status === "CLEARANCE_READY" ? (
+              <Alert
+                color="teal"
+                radius="md"
+                icon={<CheckCircle2 size={18} />}
+                mb="md"
+              >
+                Your documents are approved.
+              </Alert>
+            ) : (
+              <Alert
+                color="yellow"
+                radius="md"
+                icon={<AlertCircle size={18} />}
+                mb="md"
+              >
+                Upload every required document (marked *) below to start the
+                review.
+              </Alert>
+            )}
+
+            {isInitialUpload && missingRequired.length > 0 && (
+              <Alert color="yellow" variant="light" radius="md" mb="md" p="xs">
+                <Text fz="12px" c="#9A5B00">
+                  Still required:{" "}
+                  {missingRequired.map((d) => d.label).join(", ")}
+                </Text>
+              </Alert>
+            )}
+
+            <Stack gap="md">
+              {docs.map((doc) => (
+                <ClearanceDocumentUploadCard
+                  key={doc.fileKey}
+                  label={doc.label}
+                  required={doc.required}
+                  reviewStatus={doc.reviewStatus ?? undefined}
+                  note={doc.note}
+                  uploadedFile={doc.file}
+                  stagedFile={pending[doc.fileKey] ?? null}
+                  canUpload={canUpload}
+                  // An approved document is final — same rule as the customer
+                  // flow, so it renders read-only with just a preview.
+                  onStageFile={
+                    canUpload && doc.reviewStatus !== "APPROVED"
+                      ? (file) => stage(doc.fileKey, file)
+                      : undefined
+                  }
+                  onPreview={view}
+                />
+              ))}
+            </Stack>
+
+            {uploadMutation.isError && (
+              <Alert color="red" mt="md" icon={<AlertCircle size={16} />}>
+                {(uploadMutation.error as Error)?.message ??
+                  "Could not upload the documents."}
+              </Alert>
+            )}
+
+            <Group justify="flex-end" mt="xl" gap="sm">
+              <Button variant="default" radius="md" onClick={onClose}>
+                Close
+              </Button>
+              {canUpload && (
+                <Button
+                  color="edr-green"
+                  radius="md"
+                  leftSection={<Upload size={16} />}
+                  onClick={() => uploadMutation.mutate()}
+                  loading={uploadMutation.isPending}
+                  disabled={!canSubmit}
+                >
+                  Submit documents
+                </Button>
+              )}
+            </Group>
+          </Stack>
+        )}
+      </Modal>
+      {viewer}
+    </>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineInitiateModal.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineInitiateModal.tsx
new file mode 100644
index 000000000..481d35824
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineInitiateModal.tsx
@@ -0,0 +1,267 @@
+import {
+  Alert,
+  Box,
+  Button,
+  Center,
+  Group,
+  Loader,
+  Modal,
+  Select,
+  Stack,
+  Text,
+} from "@mantine/core";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { AlertCircle, MapPin, Plus } from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+
+import {
+  shippingLineBookingsService,
+  type ShippingLineBooking,
+} from "@/services/shipping-line-bookings.service";
+
+const FREIGHT_TYPES = [
+  { value: "CONTAINER", label: "Container" },
+  { value: "BULK", label: "Bulk" },
+];
+
+/**
+ * Initiate a shipping-line booking.
+ *
+ * Origin and destination are picked separately (matching the customer form),
+ * but both lists are drawn from real routes, so the pair always resolves to a
+ * lane EDR runs. The request still sends that route's id, letting the server
+ * derive origin, destination and direction from one authoritative row.
+ *
+ * Only inbound (Djibouti to Ethiopia) lanes are offered — the API filters them
+ * and rejects anything else, so this is a fixed rule, not a UI convenience.
+ */
+export default function ShippingLineInitiateModal({
+  opened,
+  onClose,
+  onCreated,
+}: {
+  opened: boolean;
+  onClose: () => void;
+  onCreated: (booking: ShippingLineBooking) => void;
+}) {
+  const queryClient = useQueryClient();
+  const [originYardId, setOriginYardId] = useState<string | null>(null);
+  const [destinationYardId, setDestinationYardId] = useState<string | null>(
+    null,
+  );
+  const [serviceTypeId, setServiceTypeId] = useState<string | null>(null);
+  const [freightType, setFreightType] = useState<string>("CONTAINER");
+
+  // Fresh sheet each time it opens.
+  useEffect(() => {
+    if (opened) {
+      setOriginYardId(null);
+      setDestinationYardId(null);
+      setServiceTypeId(null);
+      setFreightType("CONTAINER");
+    }
+  }, [opened]);
+
+  const referenceQuery = useQuery({
+    queryKey: ["shipping-line-reference-data"],
+    queryFn: shippingLineBookingsService.referenceData,
+    enabled: opened,
+  });
+
+  const initiateMutation = useMutation({
+    mutationFn: () =>
+      shippingLineBookingsService.initiate({
+        routeId: selectedRoute!.id,
+        serviceTypeId: serviceTypeId ?? undefined,
+        freightType,
+      }),
+    onSuccess: (booking) => {
+      void queryClient.invalidateQueries({
+        queryKey: ["shipping-line-bookings"],
+      });
+      onCreated(booking);
+    },
+  });
+
+  const routes = useMemo(
+    () => referenceQuery.data?.routes ?? [],
+    [referenceQuery.data],
+  );
+  const serviceTypes = referenceQuery.data?.serviceTypes ?? [];
+
+  // Origin and destination are picked separately (as in the customer form), but
+  // the pair still has to be a route EDR actually runs — so each list is drawn
+  // from the routes, and the destination list narrows to what the chosen origin
+  // can reach. That keeps the familiar two-field shape without letting someone
+  // assemble a lane that does not exist.
+  const originOptions = useMemo(() => {
+    const seen = new Map<string, string>();
+    for (const route of routes) {
+      if (!seen.has(route.originYardId)) {
+        seen.set(route.originYardId, route.originLabel);
+      }
+    }
+    return [...seen].map(([value, label]) => ({ value, label }));
+  }, [routes]);
+
+  const destinationOptions = useMemo(() => {
+    const seen = new Map<string, string>();
+    for (const route of routes) {
+      if (originYardId && route.originYardId !== originYardId) continue;
+      if (!seen.has(route.destinationYardId)) {
+        seen.set(route.destinationYardId, route.destinationLabel);
+      }
+    }
+    return [...seen].map(([value, label]) => ({ value, label }));
+  }, [routes, originYardId]);
+
+  // The lane the two picks resolve to. Still sent as a routeId so the server
+  // keeps deriving origin/destination/direction from one authoritative row.
+  const selectedRoute = routes.find(
+    (r) =>
+      r.originYardId === originYardId &&
+      r.destinationYardId === destinationYardId,
+  );
+
+  // Changing the origin can invalidate an already-picked destination.
+  useEffect(() => {
+    if (
+      destinationYardId &&
+      !destinationOptions.some((o) => o.value === destinationYardId)
+    ) {
+      setDestinationYardId(null);
+    }
+  }, [destinationOptions, destinationYardId]);
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      centered
+      size="md"
+      radius="md"
+      title={
+        <Box>
+          <Text fw={700} fz={16}>
+            Initiate booking
+          </Text>
+          <Text fz={12} c="dimmed">
+            Pick the lane — you will upload documents next.
+          </Text>
+        </Box>
+      }
+      overlayProps={{ blur: 2, backgroundOpacity: 0.55 }}
+    >
+      {referenceQuery.isLoading ? (
+        <Center py="xl">
+          <Loader size="sm" />
+        </Center>
+      ) : routes.length === 0 ? (
+        <Text fz="13px" c="dimmed" py="md">
+          No inbound routes are available for booking right now. Please contact
+          Operations.
+        </Text>
+      ) : (
+        <Stack gap="md">
+          <Group grow align="flex-start" gap="sm">
+            <Select
+              label="Origin yard (Djibouti)"
+              placeholder="Select origin..."
+              withAsterisk
+              searchable
+              data={originOptions}
+              value={originYardId}
+              onChange={setOriginYardId}
+              comboboxProps={{ withinPortal: true }}
+            />
+            <Select
+              label="Destination yard (Ethiopia)"
+              placeholder="Select destination..."
+              withAsterisk
+              searchable
+              disabled={!originYardId}
+              data={destinationOptions}
+              value={destinationYardId}
+              onChange={setDestinationYardId}
+              comboboxProps={{ withinPortal: true }}
+            />
+          </Group>
+
+          {/* Shipping lines only move inbound cargo, so the direction is fixed
+              rather than derived per pick — stated up front so the single
+              option in each list does not read as missing data. */}
+          <Alert
+            color="blue"
+            variant="light"
+            radius="md"
+            p="xs"
+            icon={<MapPin size={15} />}
+          >
+            <Text fz={12}>
+              Inbound only — cargo moves from Djibouti to Ethiopia (
+              <Text span fw={700}>
+                IMPORT
+              </Text>
+              ).
+            </Text>
+          </Alert>
+
+          <Select
+            label="Freight type"
+            data={FREIGHT_TYPES}
+            value={freightType}
+            onChange={(v) => setFreightType(v ?? "CONTAINER")}
+            comboboxProps={{ withinPortal: true }}
+          />
+
+          {/* Only services that do NOT bundle customs are offered — the API
+              filters them and rejects the rest. If none are configured the
+              field says so rather than vanishing, which would read as a
+              missing form rather than a data gap. */}
+          {serviceTypes.length > 0 ? (
+            <Select
+              label="Service"
+              placeholder="Select a service"
+              clearable
+              data={serviceTypes.map((s) => ({ value: s.id, label: s.name }))}
+              value={serviceTypeId}
+              onChange={setServiceTypeId}
+              comboboxProps={{ withinPortal: true }}
+            />
+          ) : (
+            <Select
+              label="Service"
+              placeholder="No non-customs service configured"
+              disabled
+              data={[]}
+              value={null}
+            />
+          )}
+
+          {initiateMutation.isError && (
+            <Alert color="red" icon={<AlertCircle size={16} />}>
+              {(initiateMutation.error as Error)?.message ??
+                "Could not initiate the booking."}
+            </Alert>
+          )}
+
+          <Group justify="flex-end" mt="sm" gap="sm">
+            <Button variant="default" radius="md" onClick={onClose}>
+              Cancel
+            </Button>
+            <Button
+              color="edr-green"
+              radius="md"
+              leftSection={<Plus size={16} />}
+              loading={initiateMutation.isPending}
+              disabled={!selectedRoute}
+              onClick={() => initiateMutation.mutate()}
+            >
+              Initiate booking
+            </Button>
+          </Group>
+        </Stack>
+      )}
+    </Modal>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/booking-doc-state.ts b/apps/edr-freight-web/portal/src/pages/shipping-line/booking-doc-state.ts
new file mode 100644
index 000000000..341f1486a
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/booking-doc-state.ts
@@ -0,0 +1,85 @@
+import type { ShippingLineBooking } from "@/services/shipping-line-bookings.service";
+
+/**
+ * What the shipping line has to do about a booking's documents.
+ *
+ * Derived from the booking status AND the per-document review results, because
+ * the two disagree in the case that matters most: when a reviewer queries a
+ * document, that document's review status becomes QUERIED but the BOOKING stays
+ * on DOCUMENTS_UNDER_REVIEW. Keying the UI off status alone would keep showing
+ * "In review" while the shipping line is actually being asked to fix something.
+ */
+export type BookingDocState =
+  /** Nothing uploaded yet — the first submission is owed. */
+  | "AWAITING"
+  /** A reviewer sent something back; the shipping line must re-upload. */
+  | "ACTION_NEEDED"
+  /** Submitted and with Operations. */
+  | "IN_REVIEW"
+  /** Everything approved. */
+  | "APPROVED"
+  /** Documents do not apply at this status. */
+  | "NONE";
+
+export function bookingDocState(
+  booking: Pick<ShippingLineBooking, "status" | "hasQueriedDocuments">,
+): BookingDocState {
+  const status = booking.status as string;
+
+  // Checked before the status switch: a queried document outranks the booking's
+  // own DOCUMENTS_UNDER_REVIEW, which is exactly the case status alone misses.
+  if (booking.hasQueriedDocuments) return "ACTION_NEEDED";
+
+  switch (status) {
+    case "AWAITING_DOCUMENTS":
+      return "AWAITING";
+    case "CHANGES_REQUESTED":
+      return "ACTION_NEEDED";
+    case "DOCUMENTS_UNDER_REVIEW":
+      return "IN_REVIEW";
+    case "CLEARANCE_READY":
+      return "APPROVED";
+    default:
+      return "NONE";
+  }
+}
+
+/** Whether the document grid is worth opening at this state. */
+export function hasDocuments(state: BookingDocState): boolean {
+  return state !== "NONE";
+}
+
+/** Whether the shipping line owes an upload — drives the primary action label. */
+export function needsUpload(state: BookingDocState): boolean {
+  return state === "AWAITING" || state === "ACTION_NEEDED";
+}
+
+export const DOC_STATE_LABEL: Record<BookingDocState, string> = {
+  AWAITING: "Documents needed",
+  ACTION_NEEDED: "Action needed",
+  IN_REVIEW: "In review",
+  APPROVED: "Approved",
+  NONE: "",
+};
+
+/** Mantine colour for the state's badge/alert. */
+export const DOC_STATE_COLOR: Record<BookingDocState, string> = {
+  AWAITING: "yellow",
+  ACTION_NEEDED: "red",
+  IN_REVIEW: "blue",
+  APPROVED: "teal",
+  NONE: "gray",
+};
+
+/**
+ * Label for the button that opens the document grid. A queried document asks
+ * for a replacement, so it reads as an instruction rather than "View" — the
+ * shipping line must swap the file, not just look at it.
+ */
+export const DOC_STATE_ACTION_LABEL: Record<BookingDocState, string> = {
+  AWAITING: "Upload documents",
+  ACTION_NEEDED: "Change document",
+  IN_REVIEW: "View documents",
+  APPROVED: "View documents",
+  NONE: "View documents",
+};
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/index.ts b/apps/edr-freight-web/portal/src/pages/shipping-line/index.ts
index cb679c8cd..caaccee22 100644
--- a/apps/edr-freight-web/portal/src/pages/shipping-line/index.ts
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/index.ts
@@ -1,5 +1,6 @@
 export { default as ShippingLineHomePage } from "./ShippingLineHomePage";
 export { default as ShippingLineBookingsPage } from "./ShippingLineBookingsPage";
+export { default as ShippingLineBookingDetailPage } from "./ShippingLineBookingDetailPage";
 export { default as ShippingLineInvoicesPage } from "./ShippingLineInvoicesPage";
 export { default as ShippingLineSettingsPage } from "./ShippingLineSettingsPage";
 export { default as ShippingLineHelpPage } from "./ShippingLineHelpPage";
diff --git a/apps/edr-freight-web/portal/src/services/shipping-line-bookings.service.ts b/apps/edr-freight-web/portal/src/services/shipping-line-bookings.service.ts
new file mode 100644
index 000000000..73a0acbb5
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/services/shipping-line-bookings.service.ts
@@ -0,0 +1,129 @@
+import type { Freight } from "@edr/types";
+
+import { client } from "@/utils/api";
+
+const BASE = "/api/shipping-line-bookings";
+
+/**
+ * The `code` of the file-upload setting whose fields a shipping line fills in
+ * after initiating a booking. Configured in the backoffice file-settings editor
+ * (Other tab) and seeded by `file-upload-settings.seeder.ts`.
+ */
+export const SHIPPING_LINE_BOOKING_DOCUMENTS_CODE =
+  "shipping_line_booking_documents";
+
+/**
+ * A shipping-line booking as the portal sees it.
+ *
+ * `hasQueriedDocuments` is computed server-side: a reviewer querying a document
+ * leaves the booking on DOCUMENTS_UNDER_REVIEW, so the booking status alone
+ * cannot tell the UI that the shipping line has something to fix.
+ */
+export type ShippingLineBooking = Freight.IBooking & {
+  hasQueriedDocuments?: boolean;
+};
+
+/** A bookable lane. Its direction is frozen server-side from the yards. */
+export interface ShippingLineRouteOption {
+  id: string;
+  label: string;
+  direction: string;
+  originYardId: string;
+  originLabel: string;
+  destinationYardId: string;
+  destinationLabel: string;
+}
+
+export interface ShippingLineReferenceData {
+  routes: ShippingLineRouteOption[];
+  serviceTypes: { id: string; name: string }[];
+}
+
+/**
+ * The route is the only lane input: it yields origin, destination and trade
+ * direction together, so they cannot contradict each other.
+ */
+export interface InitiateShippingLineBookingPayload {
+  routeId: string;
+  serviceTypeId?: string;
+  freightType?: string;
+}
+
+/**
+ * Shipping-line bookings. Separate from `bookings.service.ts` (customers) — the
+ * endpoints differ, and shipping lines book without a contract.
+ */
+export const shippingLineBookingsService = {
+  /** Create a bare booking; it starts at AWAITING_DOCUMENTS. */
+  initiate: async (
+    payload: InitiateShippingLineBookingPayload,
+  ): Promise<ShippingLineBooking> => {
+    const { data } = await client.post(`${BASE}/initiate`, payload);
+    return data.data ?? data;
+  },
+
+  /** Bookable routes + service types for the initiate form. */
+  referenceData: async (): Promise<ShippingLineReferenceData> => {
+    const { data } = await client.get(`${BASE}/reference-data`);
+    return data.data ?? data;
+  },
+
+  list: async (): Promise<ShippingLineBooking[]> => {
+    const { data } = await client.get(`${BASE}/my`);
+    return data.data ?? data;
+  },
+
+  getById: async (id: string): Promise<ShippingLineBooking> => {
+    const { data } = await client.get(`${BASE}/${id}`);
+    return data.data ?? data;
+  },
+
+  /**
+   * Cancel one of the signed-in shipping line's own bookings. Only accepted
+   * before the booking is priced — the server enforces the same rule.
+   */
+  cancel: async (id: string, reason?: string): Promise<ShippingLineBooking> => {
+    const { data } = await client.post(`${BASE}/${id}/cancel`, { reason });
+    return data.data ?? data;
+  },
+
+  /**
+   * The document grid for a booking: every configured field with its uploaded
+   * file, review status and reviewer note. Same shared endpoint the customer
+   * clearance flow reads — it resolves the field set from the booking, which
+   * now maps shipping-line bookings to their own file-upload setting.
+   */
+  getClearance: async (id: string): Promise<Freight.ClearanceView> => {
+    const { data } = await client.get(`/api/bookings/${id}/clearance`);
+    return data.data ?? data;
+  },
+
+  /**
+   * Upload the booking's documents.
+   *
+   * Posts to the shared CLEARANCE documents endpoint, not `/documents`: the
+   * latter only accepts DRAFT bookings, and these start at AWAITING_DOCUMENTS.
+   * This is the same endpoint the customer clearance flow uses — it files each
+   * document for review and moves the booking to DOCUMENTS_UNDER_REVIEW.
+   */
+  uploadDocuments: async (
+    id: string,
+    files: Record<string, File | File[] | null>,
+  ): Promise<ShippingLineBooking> => {
+    const formData = new FormData();
+    for (const [key, fileOrFiles] of Object.entries(files)) {
+      if (!fileOrFiles) continue;
+      if (Array.isArray(fileOrFiles)) {
+        for (const f of fileOrFiles) formData.append(key, f);
+      } else {
+        formData.append(key, fileOrFiles);
+      }
+    }
+    const { data } = await client.post(
+      `/api/bookings/${id}/clearance/documents`,
+      formData,
+      { headers: { "Content-Type": "multipart/form-data" } },
+    );
+    return data.data ?? data;
+  },
+};
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index 68f48e187..beda7eab1 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -188,6 +188,13 @@ export enum InvoiceSource {
   LastMile = "lastmile",
   /** Customs clearance service fee — billed on the booking invoice with the freight. */
   Clearance = "clearance",
+  /**
+   * A batch of shipping-line credits billed together. Unlike every other
+   * source, `sourceId` is the shipping line's id rather than a single record's:
+   * the invoice covers many bookings, and the credits themselves carry the
+   * per-booking link.
+   */
+  ShippingLineCredit = "shipping_line_credit",
 }
 
 export enum SchedulingStatus {

From 89cdc0ad0666305f6fd140a0d8811df8e2ef17a8 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 13:46:46 +0000
Subject: [PATCH 084/174] style: ui fixes

---
 .../bookings/BookingActionsMenu.tsx           |  14 +-
 .../bookings/BookingStatusBadge.tsx           |   3 +-
 .../src/components/common/FilterToggle.tsx    |  34 ++
 .../contracts/ContractMilestonesTimeline.tsx  |   5 +-
 .../contracts/ContractStatusTabs.tsx          |  92 -----
 .../src/components/customers/badges.tsx       |  10 +-
 .../src/components/customers/format.ts        |  40 +--
 .../summary/OverviewActivityHeatmap.tsx       |   2 +-
 .../summary/OverviewAttentionCard.tsx         |  10 +-
 .../overview/summary/OverviewHero.tsx         |   3 +-
 .../overview/summary/OverviewHeroKpis.tsx     |  36 +-
 .../overview/summary/OverviewNetworkCard.tsx  |  11 +-
 .../summary/OverviewPipelineFunnel.tsx        |   2 +-
 .../overview/summary/OverviewRevenueMix.tsx   |   2 +-
 .../summary/OverviewRevenueVolumeChart.tsx    |   6 +-
 .../overview/summary/OverviewSankeyFlow.tsx   |   2 +-
 .../src/components/warehouses/options.ts      |  14 +-
 .../backoffice/src/lib/format.ts              |  62 ++++
 .../bookings/BookingRequestDetailPage.tsx     |   5 +-
 .../pages/bookings/BookingRequestsPage.tsx    | 128 +++----
 .../bookings/DocumentClearanceListPage.tsx    |   3 -
 .../src/pages/bookings/NewBookingPage.tsx     |   3 +-
 .../pages/bookings/WagonCancellationsPage.tsx |  29 +-
 .../contracts/ClearanceDocumentsPage.tsx      |   3 -
 .../contracts/ContractRequestDetailPage.tsx   |  28 +-
 .../pages/contracts/ContractRequestsPage.tsx  | 323 ++++++++----------
 .../contracts/GlDjiboutiClearanceListPage.tsx |  16 +-
 .../pages/contracts/ShipmentRequestsPage.tsx  |   2 +-
 .../src/pages/customers/CustomersPage.tsx     |  48 +--
 .../src/pages/fleet/DriverDetailPage.tsx      |  12 +-
 .../src/pages/fleet/TrackingPage.tsx          |  10 +-
 .../src/pages/fleet/VehicleDetailPage.tsx     |  10 +-
 .../src/pages/invoices/InvoicesPage.tsx       |   5 +-
 .../src/pages/invoices/UsdPaymentsPage.tsx    |   5 +-
 .../operations/EdrTruckExitPapersModal.tsx    |   7 +-
 .../src/pages/operations/FirstMilePage.tsx    |   8 +-
 .../src/pages/operations/LastMilePage.tsx     |   8 +-
 .../src/pages/payments/PaymentsPage.tsx       |  25 +-
 .../settings/ExchangeRateSettingsCard.tsx     |   3 +-
 .../pages/warehouses/ContainerReturnsPage.tsx |   3 +-
 .../src/pages/warehouses/ImportTrucksPage.tsx |   7 +-
 .../warehouses/InterchangeDocumentsPage.tsx   |   3 +-
 .../src/pages/warehouses/TrucksOnSitePage.tsx |   3 +-
 .../warehouses/WarehouseInvoicesPage.tsx      |   5 +-
 .../pages/warehouses/WarehouseRulesPage.tsx   |  11 +-
 .../backoffice/src/types/overview.ts          |   4 +
 46 files changed, 417 insertions(+), 648 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/common/FilterToggle.tsx
 delete mode 100644 apps/edr-freight-web/backoffice/src/components/contracts/ContractStatusTabs.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/lib/format.ts

diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/BookingActionsMenu.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/BookingActionsMenu.tsx
index b2d260e37..a50028e90 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/BookingActionsMenu.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/BookingActionsMenu.tsx
@@ -1,5 +1,5 @@
 import { useNavigate } from "react-router-dom";
-import { ChevronRight, ExternalLink, MoreHorizontal } from "lucide-react";
+import { ExternalLink, MoreHorizontal } from "lucide-react";
 import { Button, Menu, ActionIcon, Group, Text } from "@mantine/core";
 
 import { BookingConfirmDialog } from "./BookingConfirmDialog";
@@ -64,17 +64,9 @@ export function BookingActionsMenu({
 
   const hasMenu = listRowHasActions(row, user);
 
+  // Row click already opens the detail page — no chevron affordance needed.
   if (!hasMenu && variant === "table") {
-    return (
-      <ActionIcon
-        variant="subtle"
-        color="gray"
-        onClick={() => navigate(`/dashboard/booking-requests/${row.id}`)}
-        aria-label="View booking"
-      >
-        <ChevronRight size={16} />
-      </ActionIcon>
-    );
+    return null;
   }
 
   // Toolbar: lay every action out as a button row.
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/BookingStatusBadge.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/BookingStatusBadge.tsx
index 7d1fff022..fa21d0d9f 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/BookingStatusBadge.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/BookingStatusBadge.tsx
@@ -1,6 +1,7 @@
 import { Badge, Group } from "@mantine/core";
 import { Link2 } from "lucide-react";
 import { BOOKING_STATUS_STYLES } from "@/features/bookings/booking-status.config";
+import { humanize } from "@/lib/format";
 
 const statusColorMap: Record<string, string> = {
   DRAFT: "gray",
@@ -40,7 +41,7 @@ export function BookingStatusBadge({
   partnerReference,
 }: BookingStatusBadgeProps) {
   const style = BOOKING_STATUS_STYLES[status] ?? {
-    label: status,
+    label: humanize(status),
     color: "gray",
   };
   const color = statusColorMap[status] ?? "gray";
diff --git a/apps/edr-freight-web/backoffice/src/components/common/FilterToggle.tsx b/apps/edr-freight-web/backoffice/src/components/common/FilterToggle.tsx
new file mode 100644
index 000000000..b97f827d4
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/common/FilterToggle.tsx
@@ -0,0 +1,34 @@
+import { ActionIcon, Indicator } from "@mantine/core";
+import { Filter } from "lucide-react";
+
+export interface FilterToggleProps {
+  /** Number of active advanced filters — shown as a badge on the button. */
+  count: number;
+  expanded: boolean;
+  onClick: () => void;
+}
+
+/** Toggle for the collapsible advanced-filters row on list pages. */
+export function FilterToggle({ count, expanded, onClick }: FilterToggleProps) {
+  return (
+    <Indicator
+      label={count}
+      size={16}
+      color="edr-green"
+      disabled={count === 0}
+      offset={4}
+    >
+      <ActionIcon
+        variant={expanded ? "filled" : "default"}
+        color="edr-green"
+        size="lg"
+        radius="lg"
+        aria-label="Toggle advanced filters"
+        aria-expanded={expanded}
+        onClick={onClick}
+      >
+        <Filter size={16} />
+      </ActionIcon>
+    </Indicator>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/ContractMilestonesTimeline.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/ContractMilestonesTimeline.tsx
index 1bf9b55e7..3a3c71449 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/ContractMilestonesTimeline.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/ContractMilestonesTimeline.tsx
@@ -10,6 +10,7 @@ import {
 import { Group, Stack, Text, Timeline, Tooltip } from "@mantine/core";
 import type { Freight } from "@edr/types";
 
+import { formatDate } from "@/lib/format";
 import {
   CONTRACT_APPROVAL_ROLE_LABELS,
   HAZARDOUS_APPROVAL_ROLE_PERMISSION,
@@ -54,10 +55,6 @@ function formatAgo(iso: string): string {
   return "just now";
 }
 
-function formatDate(iso: string): string {
-  return new Date(iso).toLocaleDateString(undefined, { dateStyle: "medium" });
-}
-
 type MilestoneIcon = typeof Send;
 
 interface Milestone {
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/ContractStatusTabs.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/ContractStatusTabs.tsx
deleted file mode 100644
index 862bc1562..000000000
--- a/apps/edr-freight-web/backoffice/src/components/contracts/ContractStatusTabs.tsx
+++ /dev/null
@@ -1,92 +0,0 @@
-import { Badge, ScrollArea, Tabs } from "@mantine/core";
-import {
-  ClipboardCheck,
-  FileSignature,
-  Inbox,
-  LayoutGrid,
-  ShieldCheck,
-  Truck,
-  XCircle,
-} from "lucide-react";
-
-import "@/components/overview/overview.css";
-import {
-  CONTRACT_LIST_TABS,
-  type ContractStatusTabKey,
-} from "@/features/contracts/contract-status.config";
-
-const TAB_ICONS: Record<ContractStatusTabKey, React.ReactNode> = {
-  all: <LayoutGrid size={17} strokeWidth={1.85} />,
-  intake: <Inbox size={17} strokeWidth={1.85} />,
-  in_approval: <ClipboardCheck size={17} strokeWidth={1.85} />,
-  approved_contract: <FileSignature size={17} strokeWidth={1.85} />,
-  clearance: <ShieldCheck size={17} strokeWidth={1.85} />,
-  active: <Truck size={17} strokeWidth={1.85} />,
-  closed: <XCircle size={17} strokeWidth={1.85} />,
-};
-
-interface ContractStatusTabsProps {
-  active: ContractStatusTabKey;
-  onChange: (tab: ContractStatusTabKey) => void;
-  counts?: Partial<Record<ContractStatusTabKey, number>>;
-}
-
-export function ContractStatusTabs({
-  active,
-  onChange,
-  counts,
-}: ContractStatusTabsProps) {
-  return (
-    <Tabs
-      value={active}
-      onChange={(value) => onChange((value as ContractStatusTabKey) ?? "all")}
-      variant="pills"
-      color="edr-green"
-      keepMounted={false}
-      classNames={{ list: "ov-tablist", tab: "ov-tab" }}
-    >
-      <ScrollArea type="auto" scrollbarSize={6} offsetScrollbars="x">
-        <Tabs.List style={{ flexWrap: "nowrap", width: "max-content" }}>
-          {CONTRACT_LIST_TABS.map((tab) => {
-            const isActive = active === tab.key;
-            const count = counts?.[tab.key];
-            return (
-              <Tabs.Tab
-                key={tab.key}
-                value={tab.key}
-                leftSection={TAB_ICONS[tab.key]}
-                size={"sm"}
-                rightSection={
-                  count !== undefined ? (
-                    <Badge
-                      size="sm"
-                      radius="sm"
-                      variant={isActive ? "white" : "light"}
-                      color={isActive ? "edr-green" : "gray"}
-                      styles={
-                        isActive
-                          ? {
-                              root: {
-                                background: "rgba(255,255,255,0.9)",
-                                color: "#15805f",
-                              },
-                            }
-                          : undefined
-                      }
-                    >
-                      {count}
-                    </Badge>
-                  ) : undefined
-                }
-              >
-                {tab.label}
-              </Tabs.Tab>
-            );
-          })}
-        </Tabs.List>
-      </ScrollArea>
-    </Tabs>
-  );
-}
-
-export type { ContractStatusTabKey };
diff --git a/apps/edr-freight-web/backoffice/src/components/customers/badges.tsx b/apps/edr-freight-web/backoffice/src/components/customers/badges.tsx
index edcc4a517..90dea5adb 100644
--- a/apps/edr-freight-web/backoffice/src/components/customers/badges.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/customers/badges.tsx
@@ -116,8 +116,9 @@ export function CompanyNationalityBadge({
 
 /**
  * Profile chips for a company row: one chip per role (Importer / Exporter / …)
- * carrying its reference code. Caps at three (a company has at most three
- * profiles); any extra collapse into a `+N` chip.
+ * carrying its reference code, colored by the profile's status (green active,
+ * amber pending, red rejected/blacklisted). Caps at three (a company has at
+ * most three profiles); any extra collapse into a `+N` chip.
  */
 export function ProfileChips({
   profiles,
@@ -152,14 +153,15 @@ export function ProfileChips({
           withArrow
         >
           <Badge
-            color={PROFILE_TYPE_COLOR[profile.type] ?? "gray"}
+            color={STATUS_COLOR[profile.status] ?? "gray"}
             variant="light"
             size="sm"
             radius="md"
             fw={600}
             style={badgeStyle}
           >
-            {humanize(profile.type)} · {profile.reference}
+            {humanize(profile.type)}
+            {profile.reference ? ` · ${profile.reference}` : ""}
           </Badge>
         </Tooltip>
       ))}
diff --git a/apps/edr-freight-web/backoffice/src/components/customers/format.ts b/apps/edr-freight-web/backoffice/src/components/customers/format.ts
index 0397c1cee..341170931 100644
--- a/apps/edr-freight-web/backoffice/src/components/customers/format.ts
+++ b/apps/edr-freight-web/backoffice/src/components/customers/format.ts
@@ -1,38 +1,2 @@
-/** Shared formatting helpers for the customer-management pages. */
-
-/** snake_case / SCREAMING_CASE → Title Case. */
-export function humanize(value: string): string {
-  return value
-    .toLowerCase()
-    .split(/[_\s]+/)
-    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-    .join(" ");
-}
-
-export function formatDate(value: string | null | undefined): string {
-  if (!value) return "—";
-  const d = new Date(value);
-  return Number.isNaN(d.getTime())
-    ? "—"
-    : d.toLocaleDateString(undefined, {
-        year: "numeric",
-        month: "short",
-        day: "numeric",
-      });
-}
-
-export function formatMoney(amount: number, currency: string): string {
-  return new Intl.NumberFormat(undefined, {
-    style: "currency",
-    currency,
-    maximumFractionDigits: 0,
-  }).format(amount);
-}
-
-export function formatBytes(bytes: number): string {
-  if (!bytes) return "0 B";
-  const units = ["B", "KB", "MB", "GB"];
-  const i = Math.floor(Math.log(bytes) / Math.log(1024));
-  const value = bytes / Math.pow(1024, i);
-  return `${value.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
-}
+/** @deprecated import from "@/lib/format" (or ../../lib/format) instead. */
+export { humanize, formatDate, formatDateTime, formatMoney, formatBytes } from "../../lib/format";
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewActivityHeatmap.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewActivityHeatmap.tsx
index 4f1958265..7524c1f20 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewActivityHeatmap.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewActivityHeatmap.tsx
@@ -26,7 +26,7 @@ interface OverviewActivityHeatmapProps {
  * selected range. The bright cells (and the peak badge) are the hours the
  * intake team needs to be staffed for.
  */
-export function OverviewActivityHeatmap({ cells }: OverviewActivityHeatmapProps) {
+export function OverviewActivityHeatmap({ cells = [] }: OverviewActivityHeatmapProps) {
   const countByCell = new Map(cells.map((c) => [`${c.dow}-${c.block}`, c.count]));
   const max = Math.max(0, ...cells.map((c) => c.count));
   const peak = cells.reduce<IOverviewHeatmapCell | null>(
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewAttentionCard.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewAttentionCard.tsx
index 142b8814f..c36db5e57 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewAttentionCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewAttentionCard.tsx
@@ -30,35 +30,35 @@ export function OverviewAttentionCard({ bookings, contracts, billing }: Overview
     {
       key: "needsAction",
       label: "Bookings needing action",
-      count: bookings.needsAction,
+      count: bookings.needsAction ?? 0,
       icon: AlertCircle,
       href: "/dashboard/booking-requests",
     },
     {
       key: "urgent",
       label: "Urgent bookings",
-      count: bookings.urgent,
+      count: bookings.urgent ?? 0,
       icon: Clock,
       href: "/dashboard/booking-requests",
     },
     {
       key: "contractsApproval",
       label: "Contracts in approval",
-      count: contracts.inApproval,
+      count: contracts.inApproval ?? 0,
       icon: FileSignature,
       href: "/dashboard/contract-requests",
     },
     {
       key: "contractsClearance",
       label: "Contracts in clearance",
-      count: contracts.inClearance,
+      count: contracts.inClearance ?? 0,
       icon: ShieldCheck,
       href: "/dashboard/contracts/clearance",
     },
     {
       key: "pendingPayments",
       label: "Pending payments",
-      count: billing.pendingPayments,
+      count: billing.pendingPayments ?? 0,
       icon: Banknote,
       href: "/dashboard/payments",
     },
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHero.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHero.tsx
index 04e2b273f..5b7815eb0 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHero.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHero.tsx
@@ -2,6 +2,7 @@ import { RefreshCw } from "lucide-react";
 import { ActionIcon, Badge, Group, SegmentedControl, Stack, Text } from "@mantine/core";
 
 import { useAuth } from "@/auth/useAuth";
+import { formatDateTime } from "@/lib/format";
 import { freightBrand } from "@/theme/freight-brand";
 import type { OverviewRange } from "@/types/overview";
 import "@/components/overview/overview.css";
@@ -20,7 +21,7 @@ function formatRelativeTime(iso: string | undefined) {
   if (minutes < 60) return `${minutes}m ago`;
   const hours = Math.floor(minutes / 60);
   if (hours < 24) return `${hours}h ago`;
-  return new Date(iso).toLocaleString();
+  return formatDateTime(iso);
 }
 
 function greeting(hour: number) {
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHeroKpis.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHeroKpis.tsx
index 32ee768d1..fa250a817 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHeroKpis.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHeroKpis.tsx
@@ -34,21 +34,27 @@ interface OverviewHeroKpisProps {
  */
 export function OverviewHeroKpis({ kpis, current, previous, rangeLabel }: OverviewHeroKpisProps) {
   const items: KpiItem[] = [
-    {
-      label: `Revenue (${rangeLabel})`,
-      value: <CountUp value={current.revenueEtb} format={(n) => formatCurrency(n, "ETB")} />,
-      hint: formatCurrency(current.revenueUsd, "USD"),
-      icon: Banknote,
-      color: "yellow",
-      delta: pctDelta(current.revenueEtb, previous.revenueEtb),
-    },
-    {
-      label: "Cargo moved",
-      value: <CountUp value={current.tons} format={(n) => `${Math.round(n).toLocaleString()} t`} />,
-      icon: Package,
-      color: "edr-green",
-      delta: pctDelta(current.tons, previous.tons),
-    },
+    // An API deployed before the overview revamp omits the period totals —
+    // drop the two tiles that need them rather than crash (or hide the strip).
+    ...(current
+      ? [
+          {
+            label: `Revenue (${rangeLabel})`,
+            value: <CountUp value={current.revenueEtb} format={(n) => formatCurrency(n, "ETB")} />,
+            hint: formatCurrency(current.revenueUsd, "USD"),
+            icon: Banknote,
+            color: "yellow",
+            delta: pctDelta(current.revenueEtb, previous?.revenueEtb ?? 0),
+          },
+          {
+            label: "Cargo moved",
+            value: <CountUp value={current.tons} format={(n) => `${Math.round(n).toLocaleString()} t`} />,
+            icon: Package,
+            color: "edr-green",
+            delta: pctDelta(current.tons, previous?.tons ?? 0),
+          },
+        ]
+      : []),
     {
       label: "Active bookings",
       value: <CountUp value={kpis.bookings.totalActive} />,
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewNetworkCard.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewNetworkCard.tsx
index 57a1a1fdc..9c9bef563 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewNetworkCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewNetworkCard.tsx
@@ -25,7 +25,10 @@ const STATS: Array<{
 
 /** Network snapshot: four operational stats plus real wagon-utilization (available / total), not a decorative gauge. */
 export function OverviewNetworkCard({ kpis }: { kpis: IOverviewOperationsKpis }) {
-  const utilizationPct = kpis.wagonsTotal > 0 ? (kpis.wagonsAvailable / kpis.wagonsTotal) * 100 : null;
+  // An API deployed before the overview revamp omits the wagon counters.
+  const wagonsTotal = kpis.wagonsTotal ?? 0;
+  const wagonsAvailable = kpis.wagonsAvailable ?? 0;
+  const utilizationPct = wagonsTotal > 0 ? (wagonsAvailable / wagonsTotal) * 100 : null;
 
   return (
     <SummaryCard
@@ -52,10 +55,10 @@ export function OverviewNetworkCard({ kpis }: { kpis: IOverviewOperationsKpis })
               Wagons available
             </Text>
             <Text fw={800} fz={22} lh={1.1}>
-              {kpis.wagonsAvailable.toLocaleString()}
+              {wagonsAvailable.toLocaleString()}
               <Text component="span" fz="sm" fw={600} c="dimmed">
                 {" "}
-                / {kpis.wagonsTotal.toLocaleString()}
+                / {wagonsTotal.toLocaleString()}
               </Text>
             </Text>
           </Stack>
@@ -72,7 +75,7 @@ export function OverviewNetworkCard({ kpis }: { kpis: IOverviewOperationsKpis })
                 />
                 <Stack gap={0} style={{ minWidth: 0 }}>
                   <Text fw={800} fz="lg" lh={1.15}>
-                    <CountUp value={kpis[stat.key]} />
+                    <CountUp value={kpis[stat.key] ?? 0} />
                   </Text>
                   <Text size="xs" c="dimmed" truncate>
                     {stat.label}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewPipelineFunnel.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewPipelineFunnel.tsx
index f28540298..a1c18c281 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewPipelineFunnel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewPipelineFunnel.tsx
@@ -14,7 +14,7 @@ interface OverviewPipelineFunnelProps {
 }
 
 /** Booking pipeline by stage, in workflow order. Each row deep-links to the exact statuses it represents. */
-export function OverviewPipelineFunnel({ data }: OverviewPipelineFunnelProps) {
+export function OverviewPipelineFunnel({ data = [] }: OverviewPipelineFunnelProps) {
   const rows = data
     .map((item) => ({
       ...item,
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueMix.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueMix.tsx
index c2839350b..0603ac095 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueMix.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueMix.tsx
@@ -111,7 +111,7 @@ interface OverviewRevenueMixProps {
 }
 
 /** ETB revenue split two ways — trade direction and freight type — anchored by the range total. */
-export function OverviewRevenueMix({ byDirection, byFreightType }: OverviewRevenueMixProps) {
+export function OverviewRevenueMix({ byDirection = [], byFreightType = [] }: OverviewRevenueMixProps) {
   const total = byDirection.reduce((sum, s) => sum + s.amountEtb, 0);
 
   return (
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueVolumeChart.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueVolumeChart.tsx
index 12b20a45e..04a359e92 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueVolumeChart.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewRevenueVolumeChart.tsx
@@ -67,9 +67,9 @@ interface OverviewRevenueVolumeChartProps {
  * period" at a glance.
  */
 export function OverviewRevenueVolumeChart({
-  bookingTrend,
-  paymentTrend,
-  previousPaymentTrend,
+  bookingTrend = [],
+  paymentTrend = [],
+  previousPaymentTrend = [],
   rangeDays,
 }: OverviewRevenueVolumeChartProps) {
   const data = mergeTrend(bookingTrend, paymentTrend, previousPaymentTrend, rangeDays);
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewSankeyFlow.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewSankeyFlow.tsx
index 1e4597ee9..b7974ea48 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewSankeyFlow.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewSankeyFlow.tsx
@@ -135,7 +135,7 @@ interface OverviewSankeyFlowProps {
  * freight type. Ribbon thickness is proportional to revenue, so the biggest
  * corridor is unmissable.
  */
-export function OverviewSankeyFlow({ flows }: OverviewSankeyFlowProps) {
+export function OverviewSankeyFlow({ flows = [] }: OverviewSankeyFlowProps) {
   const data = toSankeyData(flows);
 
   return (
diff --git a/apps/edr-freight-web/backoffice/src/components/warehouses/options.ts b/apps/edr-freight-web/backoffice/src/components/warehouses/options.ts
index 8b12d33e6..5fd393268 100644
--- a/apps/edr-freight-web/backoffice/src/components/warehouses/options.ts
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/options.ts
@@ -99,18 +99,8 @@ export const formatDays = (value: number | null | undefined) => {
   return `${rounded} ${rounded === 1 ? 'day' : 'days'}`;
 };
 
-export const formatDate = (value: string | null | undefined) => {
-  if (!value) return '—';
-  const date = new Date(value);
-  if (Number.isNaN(date.getTime())) return '—';
-  return date.toLocaleString(undefined, {
-    year: 'numeric',
-    month: 'short',
-    day: 'numeric',
-    hour: '2-digit',
-    minute: '2-digit',
-  });
-};
+// Despite the name, this has always rendered date + time — hence formatDateTime.
+export { formatDateTime as formatDate } from '@/lib/format';
 
 // Name fields (warehouse / fee rule / allocation rule) accept letters and spaces only — no numbers.
 export const lettersOnly = (value: string) => value.replace(/[^A-Za-z\s]/g, '');
diff --git a/apps/edr-freight-web/backoffice/src/lib/format.ts b/apps/edr-freight-web/backoffice/src/lib/format.ts
new file mode 100644
index 000000000..4c5c6b639
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/lib/format.ts
@@ -0,0 +1,62 @@
+/** Shared display-formatting helpers for the backoffice. */
+
+/** snake_case / SCREAMING_CASE → Title Case. */
+export function humanize(value: string): string {
+  return value
+    .toLowerCase()
+    .split(/[_\s]+/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+export function formatDate(value: string | null | undefined): string {
+  if (!value) return "—";
+  const d = new Date(value);
+  return Number.isNaN(d.getTime())
+    ? "—"
+    : d.toLocaleDateString(undefined, {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+      });
+}
+
+export function formatDateTime(value: string | null | undefined): string {
+  if (!value) return "—";
+  const d = new Date(value);
+  return Number.isNaN(d.getTime())
+    ? "—"
+    : d.toLocaleString(undefined, {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+      });
+}
+
+/** Pass `fractionDigits` where cents matter; the default matches the legacy whole-figure display. */
+export function formatMoney(
+  amount: number,
+  currency: string,
+  fractionDigits?: number,
+): string {
+  return new Intl.NumberFormat(undefined, {
+    style: "currency",
+    currency,
+    ...(fractionDigits === undefined
+      ? { maximumFractionDigits: 0 }
+      : {
+          minimumFractionDigits: fractionDigits,
+          maximumFractionDigits: fractionDigits,
+        }),
+  }).format(amount);
+}
+
+export function formatBytes(bytes: number): string {
+  if (!bytes) return "0 B";
+  const units = ["B", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const value = bytes / Math.pow(1024, i);
+  return `${value.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
index fdade7980..37609ea40 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
@@ -61,6 +61,7 @@ import {
 import { WarehouseInfoCard } from "@/components/warehouses";
 import { getStatusMeta } from "@/features/bookings/booking-status.config";
 import { toBookingListRow } from "@/features/bookings/mapBookingListRow";
+import { formatDateTime, formatMoney } from "@/lib/format";
 import { cargoTonsAndItems } from "@/utils/cargoWeight";
 import type { BookingDetail } from "@/types/booking";
 import {
@@ -186,7 +187,7 @@ export default function BookingRequestDetailPage() {
   const kpis: KpiItem[] = [
     {
       label: "Total value",
-      value: `${booking.paymentCurrency} ${amount.toLocaleString(undefined, { minimumFractionDigits: 2 })}`,
+      value: formatMoney(amount, booking.paymentCurrency, 2),
       hint: booking.paymentStatus,
       icon: Wallet,
       color: "edr-green",
@@ -326,7 +327,7 @@ export default function BookingRequestDetailPage() {
 
         {booking.holdExpiresAt && booking.schedulingStatus === "HOLDING" ? (
           <Text size="xs" c="orange.7">
-            Hold expires {new Date(booking.holdExpiresAt).toLocaleString()}
+            Hold expires {formatDateTime(booking.holdExpiresAt)}
           </Text>
         ) : null}
 
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
index d55c45c3a..4bd84a247 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
@@ -5,6 +5,7 @@ import {
   Button,
   Card,
   Checkbox,
+  Collapse,
   Group,
   Modal,
   MultiSelect,
@@ -36,6 +37,8 @@ import { useNavigate, useSearchParams } from "react-router-dom";
 import { useQuery } from "@tanstack/react-query";
 
 import { BookingActionsMenu } from "@/components/bookings/BookingActionsMenu";
+import { FilterToggle } from "@/components/common/FilterToggle";
+import { formatDate, humanize } from "@/lib/format";
 import { BookingPriorityBadge } from "@/components/bookings/BookingPriorityBadge";
 import { BookingStatusBadge } from "@/components/bookings/BookingStatusBadge";
 // BookingStatusTabs / Operations* queues removed — replaced by booking-kind tabs.
@@ -50,7 +53,6 @@ import {
   useBookingList,
   useBookingListSummary,
 } from "@/hooks/bookings/useBookings";
-import { ContractReferenceLink } from "@/components/bookings/ContractReferenceLink";
 import { api } from "@/services/api";
 import type { BookingListFilter } from "@/services/bookings.service";
 import { trainSchedulingService } from "@/services/trainScheduling.service";
@@ -116,18 +118,6 @@ function endOfDayIso(d: Date): string {
   return x.toISOString();
 }
 
-function formatDate(value: string | null | undefined): string {
-  if (!value) return "—";
-  const d = new Date(value);
-  return Number.isNaN(d.getTime())
-    ? "—"
-    : d.toLocaleDateString(undefined, {
-        year: "numeric",
-        month: "short",
-        day: "numeric",
-      });
-}
-
 export default function BookingRequestsPage() {
   const navigate = useNavigate();
   // Deep links land here pre-filtered (?statuses=A,B&tradeDirection=IMPORT) —
@@ -159,6 +149,11 @@ export default function BookingRequestsPage() {
   const [createdTo, setCreatedTo] = useState<Date | null>(null);
   const [scheduledFrom, setScheduledFrom] = useState<Date | null>(null);
   const [scheduledTo, setScheduledTo] = useState<Date | null>(null);
+  // Direction is the only deep-linkable advanced filter — open the panel so a
+  // deep link never hides its own filter.
+  const [showAdvanced, setShowAdvanced] = useState(() =>
+    Boolean(paramDirection),
+  );
   const [allocateOpen, setAllocateOpen] = useState(false);
   const [allocateIds, setAllocateIds] = useState<string[]>([]);
   // Paid bookings with no train attached (staff removed them or a sweep
@@ -185,6 +180,7 @@ export default function BookingRequestsPage() {
     const next = paramStatuses.split(",").filter(Boolean);
     setStatusFilter((prev) => (prev.join(",") === next.join(",") ? prev : next));
     setDirectionFilter(paramDirection);
+    if (paramDirection) setShowAdvanced(true);
   }, [paramStatuses, paramDirection]);
 
   const filter: BookingListFilter = useMemo(() => {
@@ -278,6 +274,10 @@ export default function BookingRequestsPage() {
     (createdFrom || createdTo ? 1 : 0) +
     (scheduledFrom || scheduledTo ? 1 : 0);
 
+  // Badge on the advanced-filters toggle — active filters hidden behind it.
+  const advancedFilterCount =
+    activeFilterCount - (kindFilter ? 1 : 0) - (statusFilter.length ? 1 : 0);
+
   const clearFilters = useCallback(() => {
     setKindFilter(null);
     setStatusFilter([]);
@@ -390,13 +390,22 @@ export default function BookingRequestsPage() {
       header: () => <span className={bookingTable.headerCell}>Booking</span>,
       cell: ({ row }) => {
         const b = row.original;
+        const isGeneral = b.bookingKind === "GENERAL_CONTRACT";
         return (
           <div className="flex items-center gap-3 py-1.5">
             <div className={bookingTable.rowIcon}>
               <Package className="size-4" strokeWidth={1.75} />
             </div>
-            <div className="min-w-0">
-              <p className="truncate font-medium text-foreground">{b.reference}</p>
+            <div className="min-w-0 max-w-[220px]">
+              <div className="flex items-center gap-1.5">
+                <p className="truncate font-medium text-foreground">{b.reference}</p>
+                <Badge
+                  variant={isGeneral ? "secondary" : "outline"}
+                  className="h-5 shrink-0 px-1.5 text-[10px] font-medium"
+                >
+                  {isGeneral ? "General" : "One-time"}
+                </Badge>
+              </div>
               <p className="mt-0.5 flex items-center gap-1 truncate text-xs text-muted-foreground">
                 <User className="size-3 shrink-0 opacity-70" />
                 {b.customerLabel}
@@ -406,49 +415,6 @@ export default function BookingRequestsPage() {
         );
       },
     },
-    {
-      id: "contract",
-      header: () => <span className={bookingTable.headerCell}>Contract</span>,
-      cell: ({ row }) => {
-        const ref = row.original.contractReference;
-        return (
-          <div className="py-1">
-            {ref ? (
-              // Fall back to plain text when the id is missing — the reference is
-              // still worth showing, it just has nowhere to link to.
-              (row.original.contractId ? (
-                <ContractReferenceLink
-                  contractId={row.original.contractId}
-                  contractReference={ref}
-                  className="truncate font-mono text-xs text-foreground underline underline-offset-2 hover:text-primary"
-                />
-              ) : (
-                <span className="truncate font-mono text-xs text-foreground">{ref}</span>
-              ))
-            ) : (
-              <span className="text-xs text-muted-foreground">—</span>
-            )}
-          </div>
-        );
-      },
-    },
-    {
-      id: "bookingKind",
-      header: () => <span className={bookingTable.headerCell}>Type</span>,
-      cell: ({ row }) => {
-        const isGeneral = row.original.bookingKind === "GENERAL_CONTRACT";
-        return (
-          <div className="py-1">
-            <Badge
-              variant={isGeneral ? "secondary" : "outline"}
-              className="h-5 px-1.5 text-[10px] font-medium"
-            >
-              {isGeneral ? "General" : "One-time"}
-            </Badge>
-          </div>
-        );
-      },
-    },
     {
       id: "route",
       header: () => <span className={bookingTable.headerCell}>Route</span>,
@@ -464,15 +430,15 @@ export default function BookingRequestsPage() {
             <div className="flex gap-1.5">
               <Badge
                 variant="outline"
-                className="h-5 border-border/50 bg-background/50 px-1.5 text-[10px] font-medium uppercase backdrop-blur-sm"
+                className="h-5 border-border/50 bg-background/50 px-1.5 text-[10px] font-medium backdrop-blur-sm"
               >
-                {b.tradeDirection}
+                {humanize(b.tradeDirection)}
               </Badge>
               <Badge
                 variant="secondary"
                 className="h-5 bg-muted/40 px-1.5 text-[10px] font-medium"
               >
-                {b.freightType}
+                {humanize(b.freightType)}
               </Badge>
             </div>
           </div>
@@ -621,7 +587,7 @@ export default function BookingRequestsPage() {
             <Stack gap={0}>
               <Box px="md" pt="md" pb="sm" w="100%">
                 <Stack gap="sm">
-                  <Group justify="space-between" gap="md" wrap="wrap">
+                  <Group gap="sm" wrap="wrap">
                     <TextInput
                       placeholder="Search booking, contract or customer…"
                       leftSection={<Search size={18} />}
@@ -649,11 +615,6 @@ export default function BookingRequestsPage() {
                       style={{ flex: 1, minWidth: "200px" }}
                       radius="lg"
                     />
-                    <Text size="sm" c="dimmed">
-                      {total} record{total !== 1 ? "s" : ""}
-                    </Text>
-                  </Group>
-                  <Group gap="sm" wrap="wrap">
                     <Select
                       placeholder="All booking types"
                       data={BOOKING_KIND_OPTIONS}
@@ -679,6 +640,25 @@ export default function BookingRequestsPage() {
                       radius="lg"
                       style={{ minWidth: 220 }}
                     />
+                    <FilterToggle
+                      count={advancedFilterCount}
+                      expanded={showAdvanced}
+                      onClick={() => setShowAdvanced((v) => !v)}
+                    />
+                    {activeFilterCount > 0 ? (
+                      <Button
+                        variant="subtle"
+                        color="gray"
+                        radius="lg"
+                        leftSection={<FilterX size={16} />}
+                        onClick={clearFilters}
+                      >
+                        Clear filters ({activeFilterCount})
+                      </Button>
+                    ) : null}
+                  </Group>
+                  <Collapse expanded={showAdvanced}>
+                  <Group gap="sm" wrap="wrap">
                     <Select
                       placeholder="All origins"
                       data={yardOptions}
@@ -729,8 +709,6 @@ export default function BookingRequestsPage() {
                       radius="lg"
                       style={{ minWidth: 150 }}
                     />
-                  </Group>
-                  <Group gap="sm" wrap="wrap">
                     <Select
                       placeholder="All payment statuses"
                       data={PAYMENT_STATUS_OPTIONS}
@@ -793,18 +771,8 @@ export default function BookingRequestsPage() {
                       radius="lg"
                       style={{ minWidth: 230 }}
                     />
-                    {activeFilterCount > 0 ? (
-                      <Button
-                        variant="subtle"
-                        color="gray"
-                        radius="lg"
-                        leftSection={<FilterX size={16} />}
-                        onClick={clearFilters}
-                      >
-                        Clear filters ({activeFilterCount})
-                      </Button>
-                    ) : null}
                   </Group>
+                  </Collapse>
                 </Stack>
               </Box>
 
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 b0e199d12..2476bc24e 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceListPage.tsx
@@ -471,9 +471,6 @@ export default function DocumentClearanceListPage({
                   style={{ flex: 1, minWidth: 220 }}
                 />
                 <Group gap="sm" wrap="nowrap">
-                  <Text size="sm" c="dimmed">
-                    {total} record{total !== 1 ? "s" : ""}
-                  </Text>
                   <SegmentedControl
                     size="sm"
                     radius="md"
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/NewBookingPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/NewBookingPage.tsx
index 41600272a..4062c439a 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/NewBookingPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/NewBookingPage.tsx
@@ -42,6 +42,7 @@ import Breadcrumbs from "@/components/ui/Breadcrumbs";
 import { api as appApi } from "@/services/api";
 import { bookingsService } from "@/services/bookings.service";
 import { customersService } from "@/services/customers.service";
+import { formatDateTime } from "@/lib/format";
 
 interface RefNamed {
   id: string;
@@ -705,7 +706,7 @@ export default function NewBookingPage() {
                 />
                 <SummaryRow
                   label="Departure"
-                  value={effectiveDepartureIso ? new Date(effectiveDepartureIso).toLocaleString() : "Not set"}
+                  value={effectiveDepartureIso ? formatDateTime(effectiveDepartureIso) : "Not set"}
                 />
               </Stack>
 
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/WagonCancellationsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/WagonCancellationsPage.tsx
index b1b4ef3ca..091a8d5a2 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/WagonCancellationsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/WagonCancellationsPage.tsx
@@ -24,6 +24,7 @@ import { api } from "@/auth/http";
 import { useAuth } from "@/auth/useAuth";
 import { PageContainer, PageHeader } from "@/components/page";
 import { toDayString } from "@/hooks/useListControls";
+import { formatDate, formatMoney } from "@/lib/format";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import {
   DataTable,
@@ -96,24 +97,6 @@ function StatusChip({ status }: { status: WagonCancellationStatus }) {
   );
 }
 
-function formatDate(iso: string | null | undefined): string {
-  if (!iso) return "—";
-  const d = new Date(iso);
-  return Number.isNaN(d.getTime())
-    ? "—"
-    : d.toLocaleDateString(undefined, {
-        year: "numeric",
-        month: "short",
-        day: "numeric",
-      });
-}
-
-function formatAmount(amount: number, currency: string): string {
-  return `${currency} ${Number(amount).toLocaleString(undefined, {
-    minimumFractionDigits: 2,
-  })}`;
-}
-
 /**
  * Staff view of partial wagon cancellations: every slice of capacity a
  * customer gave back, its cancellation fee, and where the credit went
@@ -196,7 +179,9 @@ export default function WagonCancellationsPage() {
       id: "company",
       header: () => <span>Company</span>,
       cell: ({ row }) => (
-        <Text size="sm">{row.original.booking?.company?.name ?? "—"}</Text>
+        <Text size="sm" truncate maw={200}>
+          {row.original.booking?.company?.name ?? "—"}
+        </Text>
       ),
     },
     {
@@ -209,7 +194,7 @@ export default function WagonCancellationsPage() {
       header: () => <span>Fee</span>,
       cell: ({ row }) => (
         <Text size="sm" style={{ fontVariantNumeric: "tabular-nums" }}>
-          {formatAmount(row.original.feeAmount, row.original.feeCurrency)}
+          {formatMoney(row.original.feeAmount, row.original.feeCurrency, 2)}
         </Text>
       ),
     },
@@ -218,7 +203,7 @@ export default function WagonCancellationsPage() {
       header: () => <span>Credit</span>,
       cell: ({ row }) => (
         <Text size="sm" style={{ fontVariantNumeric: "tabular-nums" }}>
-          {formatAmount(row.original.creditAmount, row.original.feeCurrency)}
+          {formatMoney(row.original.creditAmount, row.original.feeCurrency, 2)}
         </Text>
       ),
     },
@@ -370,7 +355,7 @@ export default function WagonCancellationsPage() {
             <Text size="sm">
               {voiding.booking?.reference ?? voiding.bookingId} ·{" "}
               {voiding.wagonsCancelled} wagon(s) · fee{" "}
-              {formatAmount(voiding.feeAmount, voiding.feeCurrency)}
+              {formatMoney(voiding.feeAmount, voiding.feeCurrency, 2)}
             </Text>
             <Text size="sm" c="dimmed">
               The pending fee is dropped and the wagons stay on the booking.
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx
index 197e947a5..029c53dd2 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx
@@ -305,9 +305,6 @@ export default function ClearanceDocumentsPage() {
                   w={220}
                   aria-label="Filter by status"
                 />
-                <Text size="sm" c="dimmed">
-                  {total} record{total !== 1 ? "s" : ""}
-                </Text>
               </Group>
               <Group gap="sm" mt="sm" wrap="wrap">
                 <Select
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestDetailPage.tsx
index 5cb33c62a..8238f042e 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestDetailPage.tsx
@@ -1,3 +1,4 @@
+import { formatDate, formatDateTime } from "@/lib/format";
 import { directionLabel } from "@/lib/utils";
 import { useNavigate, useParams, useSearchParams } from "react-router-dom";
 import { useQuery } from "@tanstack/react-query";
@@ -114,33 +115,6 @@ const CLEARANCE_REVIEW_STATUSES = [
   ...CLEARANCE_DONE_STATUSES,
 ];
 
-function formatDate(value: string | null | undefined): string {
-  if (!value) return "—";
-  const d = new Date(value);
-  return Number.isNaN(d.getTime())
-    ? "—"
-    : d.toLocaleDateString(undefined, {
-        year: "numeric",
-        month: "short",
-        day: "numeric",
-      });
-}
-
-/** Same, plus the clock — for values the staff pick to the minute. */
-function formatDateTime(value: string | null | undefined): string {
-  if (!value) return "—";
-  const d = new Date(value);
-  return Number.isNaN(d.getTime())
-    ? "—"
-    : d.toLocaleString(undefined, {
-        year: "numeric",
-        month: "short",
-        day: "numeric",
-        hour: "2-digit",
-        minute: "2-digit",
-      });
-}
-
 export default function ContractRequestDetailPage() {
   const { id } = useParams<{ id: string }>();
   const navigate = useNavigate();
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
index dfbb26d25..cade8cc34 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
@@ -5,6 +5,7 @@ import {
   Box,
   Button,
   Card,
+  Collapse,
   Group,
   MultiSelect,
   Select,
@@ -32,29 +33,25 @@ import {
   User,
   X,
 } from "lucide-react";
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useState, type ReactNode } from "react";
 import { useNavigate } from "react-router-dom";
 
-import { ContractApprovalProgressCell } from "@/components/contracts/ContractApprovalProgressCell";
-import {
-  ContractCourtBadge,
-  ContractStatusBadge,
-} from "@/components/contracts/ContractStatusBadge";
-import {
-  ContractStatusTabs,
-  type ContractStatusTabKey,
-} from "@/components/contracts/ContractStatusTabs";
+import { ContractStatusBadge } from "@/components/contracts/ContractStatusBadge";
+import { FilterToggle } from "@/components/common/FilterToggle";
 import { bookingTable } from "@/components/bookings/booking-ui.styles";
 import { KpiStrip, PageContainer, PageHeader } from "@/components/page";
 import {
   CONTRACT_LIST_TABS,
   CONTRACT_STATUS_STYLES,
+  contractCourt,
 } from "@/features/contracts/contract-status.config";
+import { formatContractApprovalProgress } from "@/features/contracts/contract-approval-progress";
 import {
   getStaffRowAction,
   toContractListRow,
   type ContractListRow,
 } from "@/features/contracts/mapContractListRow";
+import { formatDate, humanize } from "@/lib/format";
 import {
   useContractList,
   useContractListSummary,
@@ -68,25 +65,13 @@ import {
   type ColumnDef,
 } from "@edr/ui-common";
 
-function getStatusesForTab(tab: ContractStatusTabKey): string | undefined {
-  const match = CONTRACT_LIST_TABS.find((t) => t.key === tab);
-  if (!match?.statuses?.length) return undefined;
-  return match.statuses.join(",");
-}
-
-/** Statuses selectable in the status filter for a given tab ("all" → every tab status). */
-function getStatusOptionsForTab(
-  tab: ContractStatusTabKey,
-): { value: string; label: string }[] {
-  const match = CONTRACT_LIST_TABS.find((t) => t.key === tab);
-  const statuses = match?.statuses?.length
-    ? match.statuses
-    : CONTRACT_LIST_TABS.flatMap((t) => t.statuses ?? []);
-  return statuses.map((s) => ({
+/** Every filterable status — the pill tabs are gone, so the select carries them all. */
+const STATUS_OPTIONS = CONTRACT_LIST_TABS.flatMap((t) => t.statuses ?? []).map(
+  (s) => ({
     value: s,
     label: CONTRACT_STATUS_STYLES[s]?.label ?? s,
-  }));
-}
+  }),
+);
 
 const TRADE_DIRECTION_OPTIONS = [
   { value: "IMPORT", label: "Import" },
@@ -117,8 +102,11 @@ const SORT_OPTIONS = [
   { value: "contractValidUntil:DESC", label: "Expiring latest" },
 ];
 
-/** Every column is 120px wide and wraps its content instead of truncating. */
-const COLUMN_WIDTH = 120;
+/**
+ * Per-column widths — they must sum to the table's min-w (960px, set on the
+ * containerClassName below) because table-fixed distributes any difference.
+ */
+const COLUMN_WIDTHS = { contract: 250, route: 270, status: 250, validity: 190 };
 const COLUMN_META = {
   headerClassName: "whitespace-normal break-words",
   cellClassName: "whitespace-normal break-words align-top",
@@ -138,24 +126,11 @@ function endOfDayIso(d: Date): string {
   return x.toISOString();
 }
 
-function formatDate(value: string | null | undefined): string {
-  if (!value) return "—";
-  const d = new Date(value);
-  return Number.isNaN(d.getTime())
-    ? "—"
-    : d.toLocaleDateString(undefined, {
-        year: "numeric",
-        month: "short",
-        day: "numeric",
-      });
-}
-
 export default function ContractRequestsPage() {
   const navigate = useNavigate();
   const { pagination, setPagination } = usePagination({ pageSize: 10 });
   const [query, setQuery] = useState("");
   const [debouncedQuery] = useDebouncedValue(query, 300);
-  const [activeTab, setActiveTab] = useState<ContractStatusTabKey>("all");
   // Filter controls (empty/null = "all").
   const [statusFilter, setStatusFilter] = useState<string[]>([]);
   const { filterOptions } = useMyTradeAccess();
@@ -168,12 +143,8 @@ export default function ContractRequestsPage() {
   const [createdFrom, setCreatedFrom] = useState<Date | null>(null);
   const [createdTo, setCreatedTo] = useState<Date | null>(null);
   const [sort, setSort] = useState<string>("createdAt:DESC");
-
-  const tabStatuses = getStatusesForTab(activeTab);
-  const statusOptions = useMemo(
-    () => getStatusOptionsForTab(activeTab),
-    [activeTab],
-  );
+  // All filters start empty (no URL params on this page), so collapsed is safe.
+  const [showAdvanced, setShowAdvanced] = useState(false);
 
   const resetPage = useCallback(() => {
     setPagination({ pageIndex: 0, pageSize: pagination.pageSize });
@@ -186,16 +157,11 @@ export default function ContractRequestsPage() {
       pageSize: pagination.pageSize,
       sortBy,
       sortOrder,
-      tab: activeTab,
+      // Kept as the React Query cache-key discriminator (tabs themselves are gone).
+      tab: "all",
       // Server-side free-text search (contract reference, customer name).
       ...(debouncedQuery.trim() ? { search: debouncedQuery.trim() } : {}),
-      // Explicit status picks narrow within the tab; otherwise the tab's
-      // status group applies.
-      ...(statusFilter.length
-        ? { statuses: statusFilter.join(",") }
-        : tabStatuses
-          ? { statuses: tabStatuses }
-          : {}),
+      ...(statusFilter.length ? { statuses: statusFilter.join(",") } : {}),
       ...(directionFilter ? { tradeDirection: directionFilter } : {}),
       ...(freightTypeFilter ? { freightType: freightTypeFilter } : {}),
       ...(kindFilter ? { contractKind: kindFilter } : {}),
@@ -206,8 +172,6 @@ export default function ContractRequestsPage() {
   }, [
     pagination.pageIndex,
     pagination.pageSize,
-    activeTab,
-    tabStatuses,
     debouncedQuery,
     statusFilter,
     directionFilter,
@@ -227,6 +191,10 @@ export default function ContractRequestsPage() {
     (currencyFilter ? 1 : 0) +
     (createdFrom || createdTo ? 1 : 0);
 
+  // Badge on the advanced-filters toggle — active filters hidden behind it.
+  const advancedFilterCount =
+    activeFilterCount - (statusFilter.length ? 1 : 0) - (kindFilter ? 1 : 0);
+
   const clearFilters = useCallback(() => {
     setStatusFilter([]);
     setDirectionFilter(null);
@@ -273,7 +241,7 @@ export default function ContractRequestsPage() {
   const columns: ColumnDef<ContractListRow>[] = [
     {
       id: "contract",
-      size: COLUMN_WIDTH,
+      size: COLUMN_WIDTHS.contract,
       meta: COLUMN_META,
       header: () => <span className={bookingTable.headerCell}>Customer</span>,
       cell: ({ row }) => {
@@ -296,7 +264,7 @@ export default function ContractRequestsPage() {
     },
     {
       id: "route",
-      size: COLUMN_WIDTH,
+      size: COLUMN_WIDTHS.route,
       meta: COLUMN_META,
       header: () => <span className={bookingTable.headerCell}>Route</span>,
       cell: ({ row }) => {
@@ -311,7 +279,7 @@ export default function ContractRequestsPage() {
             <div className="flex gap-1.5">
               <Badge
                 variant="outline"
-                className="h-5 border-border/50 bg-background/50 px-1.5 text-[10px] font-medium uppercase backdrop-blur-sm"
+                className="h-5 border-border/50 bg-background/50 px-1.5 text-[10px] font-medium backdrop-blur-sm"
               >
                 {directionLabel(c.tradeDirection)}
               </Badge>
@@ -319,7 +287,7 @@ export default function ContractRequestsPage() {
                 variant="secondary"
                 className="h-5 bg-muted/40 px-1.5 text-[10px] font-medium"
               >
-                {c.freightType}
+                {humanize(c.freightType)}
               </Badge>
             </div>
           </div>
@@ -328,47 +296,77 @@ export default function ContractRequestsPage() {
     },
     {
       id: "status",
-      size: COLUMN_WIDTH,
+      size: COLUMN_WIDTHS.status,
       meta: COLUMN_META,
       header: () => <span className={bookingTable.headerCell}>Status</span>,
-      cell: ({ row }) => (
-        <div className="py-1">
-          <ContractStatusBadge
-            status={row.original.status}
-            isRenewal={row.original.isRenewal}
-          />
-        </div>
-      ),
-    },
-    {
-      id: "court",
-      size: COLUMN_WIDTH,
-      meta: COLUMN_META,
-      header: () => (
-        <span className={bookingTable.headerCell}>Waiting on</span>
-      ),
-      cell: ({ row }) => (
-        <div className="py-1">
-          <ContractCourtBadge status={row.original.status} />
-        </div>
-      ),
-    },
-    {
-      id: "approval",
-      size: COLUMN_WIDTH,
-      meta: COLUMN_META,
-      header: () => <span className={bookingTable.headerCell}>Approval</span>,
-      cell: ({ row }) => <ContractApprovalProgressCell row={row.original} />,
+      cell: ({ row }) => {
+        const c = row.original;
+        const court = contractCourt(c.status);
+        const progress = formatContractApprovalProgress(
+          c.status,
+          c.approvalSteps,
+        );
+        const action = getStaffRowAction(c);
+        // One dimmed line: who it's waiting on, the staff verb, and the
+        // approval chain when one exists. "Open" adds nothing — row click
+        // already opens the detail page.
+        const pieces: ReactNode[] = [];
+        if (court) {
+          pieces.push(court === "customer" ? "With customer" : "With EDR");
+        }
+        if (action && action.variant === "filled") {
+          pieces.push(
+            // "View & sign" pointed at the contract-view page, not the
+            // detail page — keep that deep link as an inline link.
+            action.to(c.id).endsWith("/view") ? (
+              <button
+                type="button"
+                className="underline underline-offset-2 hover:text-primary"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  navigate(action.to(c.id));
+                }}
+              >
+                {action.label}
+              </button>
+            ) : (
+              action.label
+            ),
+          );
+        }
+        if ((c.approvalSteps ?? []).length > 0) {
+          pieces.push(progress.label);
+          if (!progress.complete && progress.detail.startsWith("Next:")) {
+            pieces.push(progress.detail);
+          }
+        }
+        return (
+          <div className="space-y-1 py-1">
+            <ContractStatusBadge status={c.status} isRenewal={c.isRenewal} />
+            {pieces.length ? (
+              <div className="text-xs text-muted-foreground">
+                {pieces.map((piece, i) => (
+                  <span key={i}>
+                    {i > 0 ? " · " : null}
+                    {piece}
+                  </span>
+                ))}
+              </div>
+            ) : null}
+          </div>
+        );
+      },
     },
     {
       id: "validity",
-      size: COLUMN_WIDTH,
+      size: COLUMN_WIDTHS.validity,
       meta: COLUMN_META,
       header: () => <span className={bookingTable.headerCell}>Validity</span>,
       cell: ({ row }) => {
         const c = row.original;
+        const isGeneral = c.contractKind === "GENERAL";
         return (
-          <Stack gap={2}>
+          <Stack gap={2} align="flex-start">
             <span className="inline-flex items-center gap-1.5 text-sm text-muted-foreground">
               <CalendarClock className="size-3.5" />
               {c.validUntil
@@ -382,58 +380,22 @@ export default function ContractRequestsPage() {
                 From {formatDate(c.validFrom)}
               </Text>
             ) : null}
+            <Badge
+              variant="outline"
+              className="h-5 border-border/50 bg-background/50 px-1.5 text-[10px] font-medium uppercase"
+            >
+              {isGeneral ? (
+                <span className="inline-flex items-center gap-1">
+                  <Repeat className="size-3" /> General
+                </span>
+              ) : (
+                "One-time"
+              )}
+            </Badge>
           </Stack>
         );
       },
     },
-    {
-      id: "kind",
-      size: COLUMN_WIDTH,
-      meta: COLUMN_META,
-      header: () => <span className={bookingTable.headerCell}>Kind</span>,
-      cell: ({ row }) => {
-        const isGeneral = row.original.contractKind === "GENERAL";
-        return (
-          <Badge
-            variant="outline"
-            className="h-5 border-border/50 bg-background/50 px-1.5 text-[10px] font-medium uppercase"
-          >
-            {isGeneral ? (
-              <span className="inline-flex items-center gap-1">
-                <Repeat className="size-3" /> General
-              </span>
-            ) : (
-              "One-time"
-            )}
-          </Badge>
-        );
-      },
-    },
-    {
-      id: "actions",
-      size: COLUMN_WIDTH,
-      meta: COLUMN_META,
-      header: () => <span className={bookingTable.headerCell}>Action</span>,
-      cell: ({ row }) => {
-        const action = getStaffRowAction(row.original);
-        if (!action) return null;
-        return (
-          <Button
-            size="compact-sm"
-            radius="md"
-            variant={action.variant === "filled" ? "filled" : action.variant}
-            color="edr-green"
-            onClick={(e) => {
-              // Don't let the row-click navigation fire as well.
-              e.stopPropagation();
-              navigate(action.to(row.original.id));
-            }}
-          >
-            {action.label}
-          </Button>
-        );
-      },
-    },
   ];
 
   return (
@@ -486,22 +448,11 @@ export default function ContractRequestsPage() {
           ]}
         />
 
-        <ContractStatusTabs
-          active={activeTab}
-          onChange={(tab) => {
-            setActiveTab(tab);
-            // Status picks belong to the previous tab's option set — reset.
-            setStatusFilter([]);
-            setPagination({ pageIndex: 0, pageSize: pagination.pageSize });
-          }}
-          counts={tabCounts}
-        />
-
         <Card p={0}>
           <Stack gap={0}>
             <Box px="md" pt="md" pb="sm" w="100%">
               <Stack gap="sm">
-                <Group justify="space-between" gap="md" wrap="wrap">
+                <Group gap="sm" wrap="wrap">
                   <TextInput
                     placeholder="Search reference or customer…"
                     leftSection={<Search size={18} />}
@@ -541,16 +492,11 @@ export default function ContractRequestsPage() {
                     style={{ minWidth: 170 }}
                     aria-label="Sort contracts"
                   />
-                  <Text size="sm" c="dimmed">
-                    {total} record{total !== 1 ? "s" : ""}
-                  </Text>
-                </Group>
-                <Group gap="sm" wrap="wrap">
                   <MultiSelect
                     placeholder={
                       statusFilter.length ? undefined : "All statuses"
                     }
-                    data={statusOptions}
+                    data={STATUS_OPTIONS}
                     value={statusFilter}
                     onChange={(v) => {
                       setStatusFilter(v);
@@ -562,6 +508,38 @@ export default function ContractRequestsPage() {
                     style={{ minWidth: 220 }}
                     aria-label="Filter by status"
                   />
+                  <Select
+                    placeholder="All kinds"
+                    data={CONTRACT_KIND_OPTIONS}
+                    value={kindFilter}
+                    onChange={(v) => {
+                      setKindFilter(v);
+                      resetPage();
+                    }}
+                    clearable
+                    radius="lg"
+                    style={{ minWidth: 160 }}
+                    aria-label="Filter by contract kind"
+                  />
+                  <FilterToggle
+                    count={advancedFilterCount}
+                    expanded={showAdvanced}
+                    onClick={() => setShowAdvanced((v) => !v)}
+                  />
+                  {activeFilterCount > 0 ? (
+                    <Button
+                      variant="subtle"
+                      color="gray"
+                      radius="lg"
+                      leftSection={<FilterX size={16} />}
+                      onClick={clearFilters}
+                    >
+                      Clear filters ({activeFilterCount})
+                    </Button>
+                  ) : null}
+                </Group>
+                <Collapse expanded={showAdvanced}>
+                <Group gap="sm" wrap="wrap">
                   <Select
                     placeholder="All directions"
                     data={filterOptions(TRADE_DIRECTION_OPTIONS)}
@@ -588,19 +566,6 @@ export default function ContractRequestsPage() {
                     style={{ minWidth: 160 }}
                     aria-label="Filter by freight type"
                   />
-                  <Select
-                    placeholder="All kinds"
-                    data={CONTRACT_KIND_OPTIONS}
-                    value={kindFilter}
-                    onChange={(v) => {
-                      setKindFilter(v);
-                      resetPage();
-                    }}
-                    clearable
-                    radius="lg"
-                    style={{ minWidth: 160 }}
-                    aria-label="Filter by contract kind"
-                  />
                   <Select
                     placeholder="All currencies"
                     data={CURRENCY_OPTIONS}
@@ -629,18 +594,8 @@ export default function ContractRequestsPage() {
                     style={{ minWidth: 220 }}
                     aria-label="Created date range"
                   />
-                  {activeFilterCount > 0 ? (
-                    <Button
-                      variant="subtle"
-                      color="gray"
-                      radius="lg"
-                      leftSection={<FilterX size={16} />}
-                      onClick={clearFilters}
-                    >
-                      Clear filters ({activeFilterCount})
-                    </Button>
-                  ) : null}
                 </Group>
+                </Collapse>
               </Stack>
             </Box>
 
@@ -672,7 +627,7 @@ export default function ContractRequestsPage() {
                     manualPagination: true,
                     pageCount,
                   }}
-                  // table-fixed makes the per-column 120px widths stick; without
+                  // table-fixed makes the per-column widths stick; without
                   // it auto-layout re-widens columns once cells wrap.
                   containerClassName="border-0 shadow-none bg-transparent [&_table]:table-fixed [&_table]:min-w-[960px]"
                   footer={DataTableFooter}
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/GlDjiboutiClearanceListPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/GlDjiboutiClearanceListPage.tsx
index 77ad33f56..76f2bc5b0 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/GlDjiboutiClearanceListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/GlDjiboutiClearanceListPage.tsx
@@ -1,3 +1,4 @@
+import { formatDate } from "@/lib/format";
 import { directionLabel } from "@/lib/utils";
 import { useCallback, useMemo, useState } from "react";
 import { useNavigate } from "react-router-dom";
@@ -51,18 +52,6 @@ const prettyStatus = (s?: string | null) =>
     .replace(/_/g, " ")
     .replace(/^\w/, (c) => c.toUpperCase());
 
-function formatDate(value?: string | null): string {
-  if (!value) return "—";
-  const d = new Date(value);
-  return Number.isNaN(d.getTime())
-    ? "—"
-    : d.toLocaleDateString(undefined, {
-        year: "numeric",
-        month: "short",
-        day: "numeric",
-      });
-}
-
 function yardLabel(
   yard?: { label?: string; code?: string; name?: string } | null,
   fallback = "—",
@@ -661,9 +650,6 @@ export default function GlDjiboutiClearanceListPage() {
                     Clear
                   </Button>
                 ) : null}
-                <Text size="sm" c="dimmed" ml="auto">
-                  {total} record{total !== 1 ? "s" : ""}
-                </Text>
               </Group>
             </Box>
 
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ShipmentRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ShipmentRequestsPage.tsx
index 81b037ae6..73b9907f5 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ShipmentRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ShipmentRequestsPage.tsx
@@ -294,7 +294,7 @@ export default function ShipmentRequestsPage() {
               {row.original.contractReference}
             </Text>
             {row.original.customerName ? (
-              <Text size="xs" c="dimmed" mt={2}>
+              <Text size="xs" c="dimmed" mt={2} truncate maw={200}>
                 {row.original.customerName}
               </Text>
             ) : null}
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 815615a1b..23120f98f 100644
--- a/apps/edr-freight-web/backoffice/src/pages/customers/CustomersPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/customers/CustomersPage.tsx
@@ -147,7 +147,7 @@ export default function CustomersPage() {
               </Box>
               <div style={{ minWidth: 0 }}>
                 <Group gap={8} wrap="nowrap">
-                  <Text fw={600} c="edr-text" truncate>
+                  <Text fw={600} c="edr-text" truncate maw={200}>
                     {c.name}
                   </Text>
                   <CompanyNationalityBadge nationality={c.nationality} />
@@ -156,6 +156,9 @@ export default function CustomersPage() {
                   TIN {c.tin}
                   {c.country ? ` · ${c.country}` : ""}
                 </Text>
+                <Box mt={4}>
+                  <CompanyStatusBadge status={c.status} />
+                </Box>
               </div>
             </Group>
           );
@@ -164,16 +167,9 @@ export default function CustomersPage() {
       {
         id: "profiles",
         header: "Profiles",
-        cell: ({ row }) => (
-          <ProfileChips profiles={row.original.companyProfiles} />
-        ),
-      },
-      {
-        id: "status",
-        header: "Status",
         cell: ({ row }) => {
-          // A draft's profiles are all `pending` by construction, so the
-          // "N pending" review hint would be a lie until they submit.
+          // A draft's profiles are all `pending` by construction — the
+          // status-colored chips would be a lie until they submit.
           if (isOnboardingDraft(row.original)) {
             return (
               <Tooltip label="Customer is still filling in the onboarding wizard">
@@ -183,23 +179,7 @@ export default function CustomersPage() {
               </Tooltip>
             );
           }
-          const pending = (row.original.companyProfiles ?? []).filter(
-            (p) => p.status === "pending",
-          ).length;
-          return (
-            <Group gap={6} wrap="nowrap">
-              <CompanyStatusBadge status={row.original.status} />
-              {pending > 0 ? (
-                <Tooltip
-                  label={`${pending} profile${pending > 1 ? "s" : ""} awaiting approval`}
-                >
-                  <Badge color="yellow" variant="light" size="sm" radius="sm">
-                    {pending} pending
-                  </Badge>
-                </Tooltip>
-              ) : null}
-            </Group>
-          );
+          return <ProfileChips profiles={row.original.companyProfiles} />;
         },
       },
       {
@@ -229,6 +209,7 @@ export default function CustomersPage() {
                   c="dimmed"
                   className="inline-flex items-center gap-1"
                   truncate
+                  maw={200}
                 >
                   <Mail size={12} /> {c.email}
                 </Text>
@@ -247,16 +228,6 @@ export default function CustomersPage() {
           </Text>
         ),
       },
-      {
-        id: "approved",
-        header: "Approved",
-        meta: { headerClassName: "text-right", cellClassName: "text-right" },
-        cell: ({ row }) => (
-          <Text size="sm" c="dimmed">
-            {row.original.approvedAt ? formatDate(row.original.approvedAt) : "—"}
-          </Text>
-        ),
-      },
     ],
     [],
   );
@@ -376,9 +347,6 @@ export default function CustomersPage() {
                 }}
                 data={SORT_OPTIONS.map((o) => ({ ...o }))}
               />
-              <Text size="sm" c="dimmed">
-                {total} record{total !== 1 ? "s" : ""}
-              </Text>
             </Group>
           </Box>
 
diff --git a/apps/edr-freight-web/backoffice/src/pages/fleet/DriverDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/fleet/DriverDetailPage.tsx
index 3633b1942..9e8105c54 100644
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/DriverDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/DriverDetailPage.tsx
@@ -43,17 +43,13 @@ import {
   fetchViewableFile,
 } from "@/services/files.service";
 import { useToast } from "@/hooks/use-toast";
+import { formatDateTime } from "@/lib/format";
 
 const fmtDate = (iso?: string | null) => {
   if (!iso) return "—";
   const d = new Date(iso);
   return Number.isNaN(d.getTime()) ? "—" : d.toLocaleDateString();
 };
-const fmtDateTime = (iso?: string | null) => {
-  if (!iso) return "—";
-  const d = new Date(iso);
-  return Number.isNaN(d.getTime()) ? "—" : d.toLocaleString();
-};
 const meta = (e: FleetHistoryEvent, k: string) => {
   const v = e.metadata?.[k];
   return typeof v === "string" && v ? v : null;
@@ -400,7 +396,7 @@ const VehiclesTab = ({ driverId }: { driverId: string }) => {
             {rows.map((r) => (
               <Table.Tr key={r.id}>
                 <Table.Td>{r.plate}</Table.Td>
-                <Table.Td>{fmtDateTime(r.at)}</Table.Td>
+                <Table.Td>{formatDateTime(r.at)}</Table.Td>
               </Table.Tr>
             ))}
           </Table.Tbody>
@@ -425,7 +421,7 @@ const HistoryTab = ({ driverId }: { driverId: string }) => {
                 .join(" · ")}
             </Text>
           )}
-          <Text size="xs" c="dimmed" mt={2}>{fmtDateTime(e.createdAt)}</Text>
+          <Text size="xs" c="dimmed" mt={2}>{formatDateTime(e.createdAt)}</Text>
         </Timeline.Item>
       ))}
     </Timeline>
@@ -471,7 +467,7 @@ const TripsTab = ({ driverId }: { driverId: string }) => {
                   <Table.Td>{t.booking}</Table.Td>
                   <Table.Td>{t.vehicle}</Table.Td>
                   <Table.Td>{t.status}</Table.Td>
-                  <Table.Td>{fmtDateTime(t.at)}</Table.Td>
+                  <Table.Td>{formatDateTime(t.at)}</Table.Td>
                 </Table.Tr>
               ))}
             </Table.Tbody>
diff --git a/apps/edr-freight-web/backoffice/src/pages/fleet/TrackingPage.tsx b/apps/edr-freight-web/backoffice/src/pages/fleet/TrackingPage.tsx
index cb64d3b22..bcfd9731a 100644
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/TrackingPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/TrackingPage.tsx
@@ -35,6 +35,7 @@ import {
   type GpsDevice,
 } from "@/services/gps-tracking.service";
 import { freightBrand } from "@/theme/freight-brand";
+import { formatDateTime } from "@/lib/format";
 
 // Maps JavaScript API keys are public client-side keys — lock them down by
 // HTTP-referrer in the Google Cloud console. No fallback: a hardcoded default
@@ -51,11 +52,6 @@ const deviceLabel = (d: GpsDevice) =>
     ? [d.vehicle.code, d.vehicle.plateNumber].filter(Boolean).join(" · ")
     : d.name || d.imei;
 
-const fmtTime = (iso?: string | null) => {
-  if (!iso) return "—";
-  const d = new Date(iso);
-  return Number.isNaN(d.getTime()) ? "—" : d.toLocaleString();
-};
 
 const StatBox = ({ label, value }: { label: string; value: string }) => (
   <Box p="sm" style={{ backgroundColor: "#f8f9fa", borderRadius: 8 }}>
@@ -530,7 +526,7 @@ export function TrackingPage() {
                       Last fix
                     </Text>
                     <Text fw={500} size="sm">
-                      {fmtTime(selected.lastFixAt)}
+                      {formatDateTime(selected.lastFixAt)}
                     </Text>
                   </div>
                   {selected.vehicleId && (
@@ -580,7 +576,7 @@ export function TrackingPage() {
                               </Text>
                               <Text size="xs" c="dimmed">
                                 {toNum(d.lastSpeed) ?? 0} km/h ·{" "}
-                                {fmtTime(d.lastFixAt)}
+                                {formatDateTime(d.lastFixAt)}
                               </Text>
                             </Stack>
                           </Table.Td>
diff --git a/apps/edr-freight-web/backoffice/src/pages/fleet/VehicleDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/fleet/VehicleDetailPage.tsx
index ae785a708..bcfadb698 100644
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/VehicleDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/VehicleDetailPage.tsx
@@ -42,6 +42,7 @@ import {
 } from "@/services/vehicles.service";
 import { driversService } from "@/services/drivers.service";
 import { fleetHistoryService } from "@/services/fleet-history.service";
+import { formatDateTime } from "@/lib/format";
 
 interface MaintenanceCost {
   id: string;
@@ -77,11 +78,6 @@ const fmtDate = (iso?: string | null) => {
   const d = new Date(iso);
   return Number.isNaN(d.getTime()) ? "—" : d.toLocaleDateString();
 };
-const fmtDateTime = (iso?: string | null) => {
-  if (!iso) return "—";
-  const d = new Date(iso);
-  return Number.isNaN(d.getTime()) ? "—" : d.toLocaleString();
-};
 const money = (n?: number | null) =>
   n == null ? "—" : `ETB ${Number(n).toLocaleString(undefined, { maximumFractionDigits: 2 })}`;
 
@@ -359,7 +355,7 @@ const DriverTab = ({
               {drivers.map((d) => (
                 <Table.Tr key={d.id}>
                   <Table.Td>{d.name}</Table.Td>
-                  <Table.Td>{fmtDateTime(d.at)}</Table.Td>
+                  <Table.Td>{formatDateTime(d.at)}</Table.Td>
                 </Table.Tr>
               ))}
             </Table.Tbody>
@@ -388,7 +384,7 @@ const HistoryTab = ({ vehicleId }: { vehicleId: string }) => {
                 .join(" · ")}
             </Text>
           )}
-          <Text size="xs" c="dimmed" mt={2}>{fmtDateTime(e.createdAt)}</Text>
+          <Text size="xs" c="dimmed" mt={2}>{formatDateTime(e.createdAt)}</Text>
         </Timeline.Item>
       ))}
     </Timeline>
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
index afa4fa603..9b0fb9392 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
@@ -73,7 +73,7 @@ export default function InvoicesPanel() {
         id: "billedTo",
         header: "Billed to",
         cell: ({ row }) => (
-          <Text size="sm" c="edr-text">
+          <Text size="sm" c="edr-text" truncate maw={200}>
             {row.original.company?.name ?? "—"}
           </Text>
         ),
@@ -170,9 +170,6 @@ export default function InvoicesPanel() {
                 { label: "Overdue", value: "OVERDUE" },
               ]}
             />
-            <Text size="sm" c="dimmed">
-              {total} record{total !== 1 ? "s" : ""}
-            </Text>
             <ActionIcon
               variant="default"
               size="lg"
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx
index 023b92e0d..85e7b21e3 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx
@@ -169,7 +169,7 @@ export default function UsdPaymentsPanel() {
         id: "billedTo",
         header: "Customer",
         cell: ({ row }) => (
-          <Text size="sm" c="edr-text">
+          <Text size="sm" c="edr-text" truncate maw={200}>
             {row.original.company?.name ?? "—"}
           </Text>
         ),
@@ -304,9 +304,6 @@ export default function UsdPaymentsPanel() {
                   { label: "Overdue", value: "OVERDUE" },
                 ]}
               />
-              <Text size="sm" c="dimmed">
-                {total} record{total !== 1 ? "s" : ""}
-              </Text>
               <ActionIcon
                 variant="default"
                 size="lg"
diff --git a/apps/edr-freight-web/backoffice/src/pages/operations/EdrTruckExitPapersModal.tsx b/apps/edr-freight-web/backoffice/src/pages/operations/EdrTruckExitPapersModal.tsx
index b35af1e7c..6a8b25347 100644
--- a/apps/edr-freight-web/backoffice/src/pages/operations/EdrTruckExitPapersModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/operations/EdrTruckExitPapersModal.tsx
@@ -7,6 +7,7 @@ import { warehouseService } from "@/services/warehouse.service";
 import type { LastMileRecord } from "@/services/last-mile.service";
 import { extractDownloadErrorMessage } from "@/components/warehouses/options";
 import { openPdfBlob } from "@/components/warehouses/pdf";
+import { formatDateTime } from "@/lib/format";
 
 interface EdrTruckExitPapersModalProps {
   opened: boolean;
@@ -14,8 +15,6 @@ interface EdrTruckExitPapersModalProps {
   record: LastMileRecord | null;
 }
 
-const fmt = (value?: string | null) =>
-  value ? new Date(value).toLocaleString() : "—";
 
 /**
  * Per-truck exit papers for an EDR last-mile delivery. Each assigned truck has
@@ -87,11 +86,11 @@ export function EdrTruckExitPapersModal({ opened, onClose, record }: EdrTruckExi
                       <Text size="sm">{load}</Text>
                     </Table.Td>
                     <Table.Td>
-                      <Text size="sm">{fmt(t.arrivedAt)}</Text>
+                      <Text size="sm">{formatDateTime(t.arrivedAt)}</Text>
                     </Table.Td>
                     <Table.Td>
                       {t.departedAt ? (
-                        <Text size="sm">{fmt(t.departedAt)}</Text>
+                        <Text size="sm">{formatDateTime(t.departedAt)}</Text>
                       ) : (
                         <Badge size="sm" variant="light" color="gray">
                           Still on site
diff --git a/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx b/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
index 192a748c3..ae9bd3b21 100644
--- a/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
@@ -1139,7 +1139,11 @@ const FirstMilePage = () => {
         id: "customer",
         header: "Customer",
         meta: { headerClassName, cellClassName },
-        cell: ({ row }) => customerName(row.original),
+        cell: ({ row }) => (
+          <Text size="sm" truncate maw={200}>
+            {customerName(row.original)}
+          </Text>
+        ),
       },
       {
         id: "postPayment",
@@ -1189,7 +1193,7 @@ const FirstMilePage = () => {
         id: "exactKm",
         header: "Actual Distance (KM)",
         meta: { headerClassName, cellClassName },
-        cell: ({ row }) => row.original.exactKm != null ? row.original.exactKm : <Text c="dimmed">—</Text>,
+        cell: ({ row }) => row.original.exactKm != null ? `${row.original.exactKm} km` : <Text c="dimmed">—</Text>,
       },
       {
         id: "invoice",
diff --git a/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx b/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
index 99c6e0416..9f7198609 100644
--- a/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
@@ -1296,7 +1296,11 @@ const LastMilePage = () => {
         id: "customer",
         header: "Customer",
         meta: { headerClassName, cellClassName },
-        cell: ({ row }) => customerName(row.original),
+        cell: ({ row }) => (
+          <Text size="sm" truncate maw={200}>
+            {customerName(row.original)}
+          </Text>
+        ),
       },
       {
         id: "postPayment",
@@ -1346,7 +1350,7 @@ const LastMilePage = () => {
         id: "exactKm",
         header: "Actual Distance (KM)",
         meta: { headerClassName, cellClassName },
-        cell: ({ row }) => row.original.exactKm != null ? row.original.exactKm : <Text c="dimmed">—</Text>,
+        cell: ({ row }) => row.original.exactKm != null ? `${row.original.exactKm} km` : <Text c="dimmed">—</Text>,
       },
       {
         id: "invoice",
diff --git a/apps/edr-freight-web/backoffice/src/pages/payments/PaymentsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/payments/PaymentsPage.tsx
index 2d98cc805..a560b3291 100644
--- a/apps/edr-freight-web/backoffice/src/pages/payments/PaymentsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/payments/PaymentsPage.tsx
@@ -8,7 +8,6 @@ import {
   Select,
   Stack,
   Tabs,
-  Text,
   TextInput,
 } from "@mantine/core";
 import {
@@ -26,6 +25,7 @@ import { useMemo, useState } from "react";
 import { useQuery } from "@tanstack/react-query";
 
 import { KpiStrip } from "@/components/page";
+import { formatDate, formatMoney } from "@/lib/format";
 import { api } from "@/services/api";
 import type { PaymentMethod, PaymentRow } from "@/services/payments.service";
 import {
@@ -80,24 +80,6 @@ const STATUS_COLORS: Record<string, string> = {
   refunded: "indigo",
 };
 
-function formatAmount(amount: number, currency: string): string {
-  return `${currency} ${Number(amount).toLocaleString(undefined, {
-    minimumFractionDigits: 2,
-  })}`;
-}
-
-function formatDate(iso: string | null): string {
-  if (!iso) return "—";
-  const d = new Date(iso);
-  return Number.isNaN(d.getTime())
-    ? "—"
-    : d.toLocaleDateString(undefined, {
-      year: "numeric",
-      month: "short",
-      day: "numeric",
-    });
-}
-
 const tableHeader =
   "text-xs font-semibold uppercase tracking-wide text-muted-foreground";
 
@@ -166,7 +148,7 @@ export default function PaymentsPanel() {
       header: () => <span className={tableHeader}>Amount</span>,
       cell: ({ row }) => (
         <span className="font-mono text-sm font-semibold tabular-nums text-foreground">
-          {formatAmount(row.original.amount, row.original.currency)}
+          {formatMoney(row.original.amount, row.original.currency, 2)}
         </span>
       ),
     },
@@ -327,9 +309,6 @@ export default function PaymentsPanel() {
                 }}
                 style={{ minWidth: 180 }}
               />
-              <Text size="sm" c="dimmed">
-                {total} record{total !== 1 ? "s" : ""}
-              </Text>
             </Group>
           </Box>
 
diff --git a/apps/edr-freight-web/backoffice/src/pages/settings/ExchangeRateSettingsCard.tsx b/apps/edr-freight-web/backoffice/src/pages/settings/ExchangeRateSettingsCard.tsx
index 8527879fc..da01b51ce 100644
--- a/apps/edr-freight-web/backoffice/src/pages/settings/ExchangeRateSettingsCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/settings/ExchangeRateSettingsCard.tsx
@@ -15,6 +15,7 @@ import {
   useSetExchangeFallbackRate,
 } from "@/hooks/useExchangeSettings";
 import type { ExchangeRateSource } from "@/services/exchangeSettings.service";
+import { formatDateTime } from "@/lib/format";
 
 /** Feed health, phrased for an operator rather than a developer. */
 function feedLabel(source: ExchangeRateSource | null): {
@@ -35,7 +36,7 @@ function feedLabel(source: ExchangeRateSource | null): {
 }
 
 const formatTime = (value: string | null) =>
-  value ? new Date(value).toLocaleString() : "never";
+  value ? formatDateTime(value) : "never";
 
 /**
  * USD→ETB fallback used when the CBE exchange-rate endpoint is unreachable.
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
index 6f329c8d7..f8468181c 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
@@ -37,6 +37,7 @@ import type {
   EmptyContainerReturn,
   EmptyContainerReturnStatus,
 } from "@/types/importOperations";
+import { formatDateTime } from "@/lib/format";
 
 type ReturnType = "all" | "edr" | "customer";
 
@@ -635,7 +636,7 @@ export default function ContainerReturnsPage() {
             {(historyRow.statusHistory ?? []).map((entry: any, idx: number) => (
               <Group key={idx} justify="space-between">
                 <Badge size="sm">{RETURN_STATUS_LABEL[entry.status as EmptyContainerReturnStatus] ?? entry.status}</Badge>
-                <Text size="sm" c="dimmed">{new Date(entry.changedAt).toLocaleString()}</Text>
+                <Text size="sm" c="dimmed">{formatDateTime(entry.changedAt)}</Text>
               </Group>
             ))}
             {!(historyRow.statusHistory ?? []).length && (
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/ImportTrucksPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/ImportTrucksPage.tsx
index d2cc909f2..a074006d8 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/ImportTrucksPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/ImportTrucksPage.tsx
@@ -38,6 +38,7 @@ import {
   toReleaseInventoryItem,
 } from "@/components/warehouses/options";
 import { openPdfBlob } from "@/components/warehouses/pdf";
+import { formatDateTime } from "@/lib/format";
 import { useListControls } from "@/hooks/useListControls";
 import { useToast } from "@/hooks/use-toast";
 import { api } from "@/services/api";
@@ -79,8 +80,6 @@ const TRUCK_COLUMNS = [
 const money = (amount: number, currency: string) =>
   `${Number(amount).toLocaleString(undefined, { maximumFractionDigits: 2 })} ${currency === "ETB" ? "ETB" : currency}`;
 
-const formatTime = (iso: string | null | undefined) =>
-  iso ? new Date(iso).toLocaleString() : "—";
 
 export interface BookingGroup {
   bookingId: string;
@@ -376,10 +375,10 @@ export function TruckRows({ group }: { group: BookingGroup }) {
               <Text size="sm">{t.containers.length ? t.containers.join(", ") : "Bulk"}</Text>
             </Table.Td>
             <Table.Td>
-              <Text size="xs">{formatTime(t.arrivedAt)}</Text>
+              <Text size="xs">{formatDateTime(t.arrivedAt)}</Text>
             </Table.Td>
             <Table.Td>
-              <Text size="xs">{formatTime(t.departedAt)}</Text>
+              <Text size="xs">{formatDateTime(t.departedAt)}</Text>
             </Table.Td>
             <Table.Td>{formatNumber(t.weight)}</Table.Td>
             <Table.Td>{money(t.demurrage, feeCurrency)}</Table.Td>
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/InterchangeDocumentsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/InterchangeDocumentsPage.tsx
index 3cc1f1ab6..fa2c704b2 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/InterchangeDocumentsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/InterchangeDocumentsPage.tsx
@@ -28,6 +28,7 @@ import {
   useInterchangeDocuments,
 } from '@/hooks/useInterchangeDocuments';
 import { useToast } from '@/hooks/use-toast';
+import { humanize } from '@/lib/format';
 import { interchangeDocumentsService } from '@/services/interchange-documents.service';
 import type { InterchangeDocument, InterchangeDocumentStatus } from '@/types/interchangeDocument';
 
@@ -336,7 +337,7 @@ export default function InterchangeDocumentsPage() {
         </Text>
       ),
     },
-    { id: 'direction', header: 'Direction', cell: ({ row }) => row.original.direction },
+    { id: 'direction', header: 'Direction', cell: ({ row }) => humanize(row.original.direction) },
     { id: 'train', header: 'Train No', cell: ({ row }) => row.original.trainNo ?? '-' },
     { id: 'handoverLocation', header: 'Handover Location', cell: ({ row }) => row.original.handoverLocation },
     { id: 'handoverFrom', header: 'Handover From', cell: ({ row }) => row.original.handoverFrom },
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/TrucksOnSitePage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/TrucksOnSitePage.tsx
index f095d94d4..d30f9144b 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/TrucksOnSitePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/TrucksOnSitePage.tsx
@@ -18,6 +18,7 @@ import RuleEngineListFooter from "@/components/ruleEngine/RuleEngineListFooter";
 import { useListControls } from "@/hooks/useListControls";
 import { useTrucksOnSite } from "@/hooks/useWarehouses";
 import type { TruckOnSite } from "@/types/warehouse";
+import { formatDateTime } from "@/lib/format";
 
 /**
  * Every truck inside the yard right now, across all bookings.
@@ -122,7 +123,7 @@ function Rows({ rows }: { rows: TruckOnSite[] }) {
                   </Text>
                 ) : isLongDwell(row.arrivedAt) ? (
                   <Tooltip
-                    label={`On site over ${LONG_DWELL_HOURS}h — arrived ${new Date(row.arrivedAt).toLocaleString()}`}
+                    label={`On site over ${LONG_DWELL_HOURS}h — arrived ${formatDateTime(row.arrivedAt)}`}
                     withArrow
                   >
                     <Text size="sm" c="red" fw={600}>
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseInvoicesPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseInvoicesPage.tsx
index dc4ae4f86..17becfaa6 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseInvoicesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseInvoicesPage.tsx
@@ -40,6 +40,7 @@ import { buildWarehouseExitPaperPdf } from '@/components/warehouses/warehousePdf
 import { extractErrorMessage } from '@/components/warehouses/options';
 import { useAuth } from '@/auth/useAuth';
 import { FREIGHT_PERMS, hasPermission } from '@/lib/permissions';
+import { formatMoney, humanize } from '@/lib/format';
 
 const STATUS_COLOR: Record<WarehouseInvoiceStatus, string> = {
   DRAFT: 'gray',
@@ -50,7 +51,7 @@ const STATUS_COLOR: Record<WarehouseInvoiceStatus, string> = {
   CANCELLED: 'gray',
 };
 
-const fmt = (n: number, c: string) => `${Number(n).toLocaleString()} ${c === 'ETB' ? 'Birr (ETB)' : c}`;
+const fmt = (n: number, c: string) => formatMoney(n, c, 2);
 const fmtDate = (d?: string | null) => (d ? new Date(d).toLocaleDateString() : '—');
 
 export default function WarehouseInvoicesPage() {
@@ -79,7 +80,7 @@ export default function WarehouseInvoicesPage() {
         </Text>
       ),
     },
-    { id: 'type', header: 'Type', cell: ({ row }) => row.original.invoiceType.replace(/_/g, ' ') },
+    { id: 'type', header: 'Type', cell: ({ row }) => humanize(row.original.invoiceType) },
     { id: 'total', header: 'Total', cell: ({ row }) => fmt(row.original.totalAmount, row.original.currency) },
     { id: 'paid', header: 'Paid', cell: ({ row }) => fmt(row.original.paidAmount, row.original.currency) },
     {
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseRulesPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseRulesPage.tsx
index a6339965a..8c432f92a 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseRulesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseRulesPage.tsx
@@ -46,6 +46,7 @@ import {
   type FeeRuleBasis,
   type FeeRuleType,
 } from '@/types/warehouse';
+import { humanize } from '@/lib/format';
 
 const RULE_TYPE_COLOR: Record<FeeRuleType, string> = {
   STORAGE_FEE: 'teal',
@@ -218,8 +219,8 @@ function AllocationRules() {
   const allocationColumns: ColumnDef<AllocationRule>[] = [
     { id: 'priority', header: 'Priority', cell: ({ row }) => row.original.priority },
     { id: 'name', header: 'Name', cell: ({ row }) => row.original.name },
-    { id: 'freight', header: 'Freight', cell: ({ row }) => row.original.freightType ?? dash },
-    { id: 'trade', header: 'Trade', cell: ({ row }) => row.original.tradeDirection ?? dash },
+    { id: 'freight', header: 'Freight', cell: ({ row }) => (row.original.freightType ? humanize(row.original.freightType) : dash) },
+    { id: 'trade', header: 'Trade', cell: ({ row }) => (row.original.tradeDirection ? humanize(row.original.tradeDirection) : dash) },
     { id: 'cargoCode', header: 'Cargo code', cell: ({ row }) => row.original.cargoTypeCode ?? dash },
     {
       id: 'targetYard',
@@ -615,10 +616,10 @@ function FeeRules() {
       ),
     },
     { id: 'name', header: 'Name', cell: ({ row }) => row.original.name },
-    { id: 'freight', header: 'Freight', cell: ({ row }) => row.original.freightType ?? dash },
-    { id: 'trade', header: 'Trade', cell: ({ row }) => row.original.tradeDirection ?? dash },
+    { id: 'freight', header: 'Freight', cell: ({ row }) => (row.original.freightType ? humanize(row.original.freightType) : dash) },
+    { id: 'trade', header: 'Trade', cell: ({ row }) => (row.original.tradeDirection ? humanize(row.original.tradeDirection) : dash) },
     { id: 'cargo', header: 'Cargo', cell: ({ row }) => row.original.cargoTypeCode ?? dash },
-    { id: 'container', header: 'Container', cell: ({ row }) => row.original.containerType ?? dash },
+    { id: 'container', header: 'Container', cell: ({ row }) => (row.original.containerType ? humanize(row.original.containerType) : dash) },
     {
       id: 'scope',
       header: 'Location scope',
diff --git a/apps/edr-freight-web/backoffice/src/types/overview.ts b/apps/edr-freight-web/backoffice/src/types/overview.ts
index f0553fc22..38778da49 100644
--- a/apps/edr-freight-web/backoffice/src/types/overview.ts
+++ b/apps/edr-freight-web/backoffice/src/types/overview.ts
@@ -10,6 +10,10 @@ export type {
   IOverviewTrendPoint,
   IOverviewDirectionTrendPoint,
   IOverviewTonnagePoint,
+  IOverviewPeriodTotals,
+  IOverviewRevenueSlice,
+  IOverviewRevenueFlow,
+  IOverviewHeatmapCell,
   IOverviewStatusCount,
   IOverviewPipelineCount,
   IOverviewPaymentTrendPoint,

From 0e00a98ef30e65a9c12582a2af27cdb39b184c79 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Thu, 13 Aug 2026 15:10:27 +0000
Subject: [PATCH 085/174] feat: implement shipping line booking completion
 functionality

- Added ShippingLineBookingCompletionController and associated service to handle the completion of shipping line bookings.
- Introduced a new module for booking completion to maintain module separation and avoid cyclic dependencies.
- Updated the train scheduling global rules to set default desk hours to 24 hours.
- Modified existing services and entities to accommodate the new booking completion logic.
- Enhanced the front-end components to support the new booking completion flow, including updates to the booking detail and bookings pages.
- Implemented validation and error handling for booking completion, ensuring that only approved bookings can be completed.
- Added migration to set default desk hours in the database.
---
 apps/edr-freight-api/src/app.module.ts        |   2 +
 .../3520000000000-DefaultDeskHours24h.ts      |  31 ++
 .../bookings/booking-transition.service.ts    |  39 +-
 .../modules/rule-engine/rule-engine.module.ts |   7 +-
 ...ping-line-booking-completion.controller.ts |  53 +++
 ...shipping-line-booking-completion.module.ts |  29 ++
 ...hipping-line-booking-completion.service.ts | 398 ++++++++++++++++++
 .../shipping-line-bookings.controller.ts      |  28 --
 .../shipping-line-bookings.service.ts         | 278 ------------
 .../shipping-line-companies.module.ts         |   8 -
 .../train-scheduling-global-rules.entity.ts   |   5 +-
 .../services/train-scheduling.service.ts      | 119 ++++--
 .../ruleEngine/RuleEngineFormDialog.tsx       |   6 +
 .../BookingWindowSettingsModal.tsx            |   3 +-
 .../CreateScheduleWindowFields.tsx            |   3 +-
 .../ruleEngine/RuleEngineResourcePage.tsx     |   6 +-
 .../ShippingLineBookingDetailPage.tsx         |   4 +-
 .../ShippingLineBookingsPage.tsx              |  51 ++-
 18 files changed, 681 insertions(+), 389 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3520000000000-DefaultDeskHours24h.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.controller.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.module.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.service.ts

diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index d869ddf2d..d38c6ea92 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -40,6 +40,7 @@ import { TrainSchedulesModule } from "./modules/train-schedules/train-schedules.
 import { TrainSchedulingModule } from "./modules/train-scheduling/train-scheduling.module";
 import { SchedulingRescheduleModule } from "./modules/scheduling-reschedule/scheduling-reschedule.module";
 import { CompaniesModule } from "./modules/companies/companies.module";
+import { ShippingLineBookingCompletionModule } from "./modules/shipping-lines/shipping-line-booking-completion.module";
 import { ShippingLineCompaniesModule } from "./modules/shipping-lines/shipping-line-companies.module";
 import { TrackingModule } from "./modules/tracking/tracking.module";
 import { BillingModule } from "./modules/billing/billing.module";
@@ -203,6 +204,7 @@ if (!process.env.APPLICATION_NAME) {
     SchedulingRescheduleModule,
     CompaniesModule,
     ShippingLineCompaniesModule,
+    ShippingLineBookingCompletionModule,
     TrackingModule,
     BillingModule,
     NotificationsModule,
diff --git a/apps/edr-freight-api/src/migrations/3520000000000-DefaultDeskHours24h.ts b/apps/edr-freight-api/src/migrations/3520000000000-DefaultDeskHours24h.ts
new file mode 100644
index 000000000..8cd71eff9
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3520000000000-DefaultDeskHours24h.ts
@@ -0,0 +1,31 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Default the daily booking desk to 24 hours: window_close_hour equal to
+ * window_open_hour means the desk never pauses overnight. Aligns the column
+ * default and the existing global-rules row; per-schedule overrides keep
+ * whatever staff set on them.
+ */
+export class DefaultDeskHours24h3520000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_scheduling_global_rules
+        ALTER COLUMN window_close_hour SET DEFAULT 8
+    `);
+    await queryRunner.query(`
+      UPDATE freight.train_scheduling_global_rules
+        SET window_close_hour = window_open_hour
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_scheduling_global_rules
+        ALTER COLUMN window_close_hour SET DEFAULT 17
+    `);
+    await queryRunner.query(`
+      UPDATE freight.train_scheduling_global_rules
+        SET window_close_hour = 17
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
index 7cc92be87..944e3db15 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
@@ -944,6 +944,15 @@ export class BookingTransitionService {
     bookingId: string,
     scheduledDate: string,
     requestedTrainScheduleId?: string | null,
+    opts?: {
+      /**
+       * Skip the customer day-pool departure/compatibility gate. Used ONLY by
+       * the shipping-line completion path, which has already validated the day
+       * against the line's own dedicated train (those trains are excluded from
+       * the customer pools, so the gate here would wrongly reject them).
+       */
+      bypassDayPool?: boolean;
+    },
   ): Promise<Booking> {
     const booking = await this.bookingsService.findById(bookingId);
     assertBookingStatus(booking, [
@@ -971,20 +980,22 @@ export class BookingTransitionService {
     // gate; quantity never blocks — oversized bookings get a partial split
     // offer). The batch engine assigns the specific train within that
     // (route, day) pool later.
-    const { hasDeparture, hasCompatible } =
-      await this.bookingsService.checkDayCompatibilityForBooking(
-        booking,
-        eatDay(date),
-      );
-    if (!hasDeparture) {
-      throw new BadRequestException(
-        "No departures available on the selected day for this route",
-      );
-    }
-    if (!hasCompatible) {
-      throw new BadRequestException(
-        "No wagon on the selected day can carry this cargo type — please choose another day",
-      );
+    if (!opts?.bypassDayPool) {
+      const { hasDeparture, hasCompatible } =
+        await this.bookingsService.checkDayCompatibilityForBooking(
+          booking,
+          eatDay(date),
+        );
+      if (!hasDeparture) {
+        throw new BadRequestException(
+          "No departures available on the selected day for this route",
+        );
+      }
+      if (!hasCompatible) {
+        throw new BadRequestException(
+          "No wagon on the selected day can carry this cargo type — please choose another day",
+        );
+      }
     }
 
     // Export is FCFS and never splits — a booking must ride one train whole. So
diff --git a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts
index 7d15ab889..549a35fa2 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts
@@ -1,4 +1,4 @@
-import { forwardRef, Global, Module } from '@nestjs/common';
+import { Global, Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
 import { ApprovalRulesController } from './controllers/approval-rules.controller';
@@ -104,9 +104,8 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
     // against them (a cap above the rating is a typo, not a policy).
     WagonTypesModule,
     // Rates may be scoped to one shipping line; creating such a rate validates
-    // the line exists and is active. forwardRef: shipping-lines now imports
-    // BookingsModule (booking completion), which imports this module back.
-    forwardRef(() => ShippingLineCompaniesModule),
+    // the line exists and is active.
+    ShippingLineCompaniesModule,
   ],
   controllers: [
     CargoTypesController,
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.controller.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.controller.ts
new file mode 100644
index 000000000..155988a09
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.controller.ts
@@ -0,0 +1,53 @@
+import { CurrentUser } from "@edr/api-common";
+import { Body, Controller, Get, Param, ParseUUIDPipe, Post } from "@nestjs/common";
+import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
+
+import { PortalCustomer } from "../../common/booking-guards";
+import { CompleteShippingLineBookingDto } from "./dto/complete-shipping-line-booking.dto";
+import { ShippingLineBookingCompletionService } from "./shipping-line-booking-completion.service";
+
+interface CurrentIamUser {
+  id: string;
+}
+
+/**
+ * The completion half of shipping-line bookings, sharing the
+ * `/shipping-line-bookings` prefix with {@link ShippingLineBookingsController}.
+ * Separate controller because it lives in its own module — see
+ * {@link ShippingLineBookingCompletionService} for why the module split exists.
+ */
+@ApiTags("shipping-line-bookings")
+@Controller("shipping-line-bookings")
+@ApiBearerAuth()
+export class ShippingLineBookingCompletionController {
+  constructor(
+    private readonly completionService: ShippingLineBookingCompletionService,
+  ) {}
+
+  @Get(":id/available-days")
+  @PortalCustomer()
+  @ApiOperation({
+    summary:
+      "Days with an open departure that can carry this booking's cargo — for the completion form's day picker.",
+  })
+  async availableDays(
+    @CurrentUser() user: CurrentIamUser,
+    @Param("id", ParseUUIDPipe) id: string,
+  ) {
+    return this.completionService.availableDaysMine(user.id, id);
+  }
+
+  @Post(":id/complete")
+  @PortalCustomer()
+  @ApiOperation({
+    summary:
+      "Complete an approved (CLEARANCE_READY) booking: cargo + binding shipment day. Prices off the line's rates, records the charge on the credit ledger and requests operation.",
+  })
+  async completeMine(
+    @CurrentUser() user: CurrentIamUser,
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: CompleteShippingLineBookingDto,
+  ) {
+    return this.completionService.completeMine(user.id, id, dto);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.module.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.module.ts
new file mode 100644
index 000000000..470984c70
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.module.ts
@@ -0,0 +1,29 @@
+import { Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+
+import { BookingsModule } from "../bookings/bookings.module";
+import { Booking } from "../bookings/entities/booking.entity";
+import { TrainSchedulingModule } from "../train-scheduling/train-scheduling.module";
+import { ShippingLineBookingCompletionController } from "./shipping-line-booking-completion.controller";
+import { ShippingLineBookingCompletionService } from "./shipping-line-booking-completion.service";
+import { ShippingLineCompaniesModule } from "./shipping-line-companies.module";
+
+/**
+ * Deliberately a LEAF module — registered in AppModule and imported by
+ * nothing. Completion needs BookingsModule (pricing + the operation-request
+ * transition), but ShippingLineCompaniesModule sits under rule-engine and
+ * companies, which sit under BookingsModule; importing bookings from there
+ * closes a module cycle Nest cannot construct. Keeping the completion flow
+ * here keeps the graph acyclic with no forwardRef chains.
+ */
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([Booking]),
+    BookingsModule,
+    TrainSchedulingModule,
+    ShippingLineCompaniesModule,
+  ],
+  controllers: [ShippingLineBookingCompletionController],
+  providers: [ShippingLineBookingCompletionService],
+})
+export class ShippingLineBookingCompletionModule {}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.service.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.service.ts
new file mode 100644
index 000000000..a7c938380
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.service.ts
@@ -0,0 +1,398 @@
+import {
+  BadRequestException,
+  ForbiddenException,
+  Injectable,
+  NotFoundException,
+} from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { In, Repository } from "typeorm";
+
+import { BookingPricingService } from "../bookings/booking-pricing.service";
+import { BookingTransitionService } from "../bookings/booking-transition.service";
+import { BookingsService } from "../bookings/bookings.service";
+import { BookingContainer } from "../bookings/entities/booking-container.entity";
+import { Booking } from "../bookings/entities/booking.entity";
+import { wagonsPerUnitForSize } from "../rule-engine/container-type.util";
+import { CargoType } from "../rule-engine/entities/cargo-type.entity";
+import { ContainerType } from "../rule-engine/entities/container-type.entity";
+import { eatDay } from "../train-scheduling/batch-window.util";
+import { TrainSchedule } from "../train-schedules/entities/train-schedule.entity";
+import { TrainSchedulingService } from "../train-scheduling/services/train-scheduling.service";
+import { CompleteShippingLineBookingDto } from "./dto/complete-shipping-line-booking.dto";
+import {
+  ShippingLineCredit,
+  ShippingLineCreditStatus,
+} from "./entities/shipping-line-credit.entity";
+import { ShippingLineCompaniesService } from "./shipping-line-companies.service";
+import { ShippingLineCreditsService } from "./shipping-line-credits.service";
+
+/**
+ * Completion of a shipping-line booking — the step after Operations approves
+ * its documents, mirroring what a customer does at that point: cargo + binding
+ * shipment day go in, the booking prices off the line's negotiated rates and
+ * the request lands with Operations.
+ *
+ * Its own module (not part of {@link ShippingLineBookingsService}) because it
+ * needs BookingsModule (pricing, the operation-request transition) and
+ * TrainSchedulingModule — and ShippingLineCompaniesModule is imported by
+ * rule-engine/companies, which sit UNDER BookingsModule. Importing bookings
+ * from there closes a module cycle Nest cannot construct; a leaf module that
+ * nothing imports keeps the graph acyclic.
+ */
+@Injectable()
+export class ShippingLineBookingCompletionService {
+  constructor(
+    @InjectRepository(Booking)
+    private readonly bookingsRepository: Repository<Booking>,
+    private readonly shippingLineCompaniesService: ShippingLineCompaniesService,
+    private readonly bookingsService: BookingsService,
+    private readonly bookingPricingService: BookingPricingService,
+    private readonly bookingTransitionService: BookingTransitionService,
+    private readonly trainSchedulingService: TrainSchedulingService,
+    private readonly creditsService: ShippingLineCreditsService,
+  ) {}
+
+  /** Same session→owner resolution every shipping-line entry point uses. */
+  private async requireShippingLine(userId: string) {
+    const shippingLine =
+      await this.shippingLineCompaniesService.findByUserId(userId);
+    if (!shippingLine) {
+      throw new ForbiddenException("This account is not a shipping line.");
+    }
+    if (shippingLine.status !== "active") {
+      throw new ForbiddenException(
+        "This shipping-line account is suspended and cannot create bookings.",
+      );
+    }
+    return shippingLine;
+  }
+
+  private async requireOwnBooking(
+    userId: string,
+    bookingId: string,
+    relations?: { bookingContainers?: boolean },
+  ) {
+    const shippingLine = await this.requireShippingLine(userId);
+    const booking = await this.bookingsRepository.findOne({
+      where: { id: bookingId, shippingLineCompanyId: shippingLine.id },
+      relations,
+    });
+    if (!booking) throw new NotFoundException(`Booking ${bookingId} not found`);
+    return booking;
+  }
+
+  /**
+   * The line's dedicated departures on the booking's lane (DRAFT/SCHEDULED,
+   * soonest first). These trains run NO booking-window cycle — the line books
+   * whenever it wants until the close offset stamped in `windowClosesAt` — and
+   * they are excluded from every customer pool, so this is the only source
+   * that can offer them.
+   */
+  private async dedicatedTrainsForBooking(booking: Booking) {
+    if (!booking.shippingLineCompanyId) return [];
+    return this.bookingsRepository.manager.getRepository(TrainSchedule).find({
+      where: {
+        shippingLineCompanyId: booking.shippingLineCompanyId,
+        originStationId: booking.originYardId ?? undefined,
+        destinationStationId: booking.destinationYardId ?? undefined,
+        status: In(["DRAFT", "SCHEDULED"]),
+      },
+      order: { scheduledDepartureDate: "ASC" },
+    });
+  }
+
+  /** Still bookable: the close offset before departure has not passed yet. */
+  private isStillOpen(schedule: TrainSchedule): boolean {
+    const closesAt =
+      schedule.windowClosesAt ?? schedule.scheduledDepartureDate;
+    return closesAt.getTime() > Date.now();
+  }
+
+  /**
+   * Days the shipping line may pick as the shipment day.
+   *
+   * Lanes with trains DEDICATED to this line offer exactly those trains' days,
+   * open until each train's close offset — no window cycle. Lanes without a
+   * dedicated train fall back to the shared customer day pool, exactly as
+   * before. Ownership is checked first so one line cannot probe another's
+   * booking.
+   */
+  async availableDaysMine(userId: string, bookingId: string) {
+    const booking = await this.requireOwnBooking(userId, bookingId);
+    const dedicated = await this.dedicatedTrainsForBooking(booking);
+    if (dedicated.length === 0) {
+      return this.bookingsService.availableDaysForBooking(bookingId);
+    }
+    const days = [
+      ...new Set(
+        dedicated
+          .filter((s) => this.isStillOpen(s))
+          .map((s) => eatDay(s.scheduledDepartureDate)),
+      ),
+    ];
+    return { days };
+  }
+
+  /**
+   * Complete a bare shipping-line booking once Operations has approved its
+   * documents (CLEARANCE_READY), or after Operations returned the request
+   * (OPERATION_CHANGES_REQUESTED). The cargo and the binding shipment day go
+   * in, the booking is priced off the line's negotiated rates, and the request
+   * lands with Operations (OPERATION_REQUEST_PENDING) through the same
+   * transition customers use.
+   *
+   * Payment differs from customers by design: no invoice is issued here.
+   * Shipping lines run on the credit ledger — the priced amount is recorded as
+   * an UNBILLED credit and Finance bills a batch later, so the booking
+   * proceeds without a payment gate.
+   */
+  async completeMine(
+    userId: string,
+    bookingId: string,
+    dto: CompleteShippingLineBookingDto,
+  ) {
+    const booking = await this.requireOwnBooking(userId, bookingId, {
+      bookingContainers: true,
+    });
+    if (
+      !["CLEARANCE_READY", "OPERATION_CHANGES_REQUESTED"].includes(
+        booking.status,
+      )
+    ) {
+      throw new BadRequestException(
+        "Your documents must be approved before the booking can be completed.",
+      );
+    }
+
+    // Completion is booking time. A lane with trains DEDICATED to this line
+    // has no window concept at all: the line books whenever it wants until the
+    // train's close offset. Only a lane with no dedicated train falls back to
+    // the customer window gate, unchanged.
+    const dedicated = await this.dedicatedTrainsForBooking(booking);
+    const pickedDay = eatDay(new Date(dto.scheduledDate));
+    const dedicatedOnDay = dedicated.filter(
+      (s) => eatDay(s.scheduledDepartureDate) === pickedDay,
+    );
+    let bypassDayPool = false;
+    if (dedicatedOnDay.length > 0) {
+      if (!dedicatedOnDay.some((s) => this.isStillOpen(s))) {
+        throw new BadRequestException(
+          "Booking for your train on this day has closed — the cut-off before departure has passed.",
+        );
+      }
+      // The day is backed by the line's own train, which every customer pool
+      // deliberately excludes — so the day-pool gate downstream must not run.
+      bypassDayPool = true;
+    } else if (dedicated.length > 0) {
+      throw new BadRequestException(
+        "Pick one of your assigned train days for this route.",
+      );
+    } else {
+      await this.trainSchedulingService.assertBookingWindowOpen({
+        originYardId: booking.originYardId ?? null,
+        destinationYardId: booking.destinationYardId ?? null,
+        scheduledDate: dto.scheduledDate,
+        direction: booking.tradeDirection ?? null,
+      });
+    }
+
+    let hasCargo =
+      (booking.bookingContainers?.length ?? 0) > 0 ||
+      Number(booking.cargoTotalWeightVgm) > 0;
+    const restatesCargo = Boolean(
+      dto.containers?.length || dto.cargoTypeId || dto.cargoWeightTons,
+    );
+
+    // Operations may return the request asking for the CARGO to change, not
+    // just the day. A resubmit that restates cargo starts completion over:
+    // the recorded (unbilled) credit is written off and the persisted cargo
+    // wiped, so the fresh path below re-persists, re-prices and re-records.
+    // Once the credit is on an issued invoice the cargo is frozen — the
+    // invoice total must keep matching what it bills.
+    if (hasCargo && restatesCargo) {
+      const credit = await this.bookingsRepository.manager
+        .getRepository(ShippingLineCredit)
+        .findOne({ where: { bookingId } });
+      if (credit && credit.status === ShippingLineCreditStatus.Unbilled) {
+        await this.creditsService.cancelCredit(
+          credit.id,
+          "Cargo changed before billing — booking re-priced on completion.",
+        );
+      } else if (
+        credit &&
+        credit.status !== ShippingLineCreditStatus.Cancelled
+      ) {
+        throw new BadRequestException(
+          "This booking's charge has already been invoiced — contact Operations to change its cargo.",
+        );
+      }
+      await this.wipeCargo(bookingId);
+      hasCargo = false;
+    }
+
+    // First completion persists cargo and prices the booking; a day-only
+    // resubmit after OPERATION_CHANGES_REQUESTED skips straight to the
+    // operation request with the cargo (and price) it already carries.
+    if (!hasCargo) {
+      if (booking.freightType === "CONTAINER") {
+        await this.persistContainerLines(booking, dto);
+      } else {
+        if (!dto.cargoTypeId || !(Number(dto.cargoWeightTons) > 0)) {
+          throw new BadRequestException(
+            "Bulk bookings need a cargo type and a total weight in tons.",
+          );
+        }
+        const cargoType = await this.bookingsRepository.manager
+          .getRepository(CargoType)
+          .findOne({ where: { id: dto.cargoTypeId, isActive: true } });
+        if (!cargoType) {
+          throw new NotFoundException(
+            `Cargo type ${dto.cargoTypeId} not found`,
+          );
+        }
+      }
+
+      await this.bookingsRepository.update(bookingId, {
+        cargoTypeId:
+          booking.freightType === "BULK" ? (dto.cargoTypeId ?? null) : null,
+        cargoFreeText: dto.cargoFreeText?.trim() || null,
+        cargoTotalWeightVgm:
+          booking.freightType === "BULK" ? Number(dto.cargoWeightTons) : 0,
+        bulkTotalWeightTons:
+          booking.freightType === "BULK" ? Number(dto.cargoWeightTons) : null,
+        // Hazard is per-line for containers; the booking-level flag is what
+        // pricing bills the surcharge from.
+        isHazardous: (dto.containers ?? []).some(
+          (line) => Number(line.hazardousQuantity ?? 0) > 0,
+        ),
+        // Completion fixes the cargo — and therefore the price — so it is also
+        // where the billing currency is chosen.
+        paymentCurrency: dto.paymentCurrency ?? booking.paymentCurrency,
+      } as never);
+
+      const loaded = await this.bookingsRepository.findOne({
+        where: { id: bookingId },
+        relations: { bookingContainers: true, serviceType: true },
+      });
+      const computed = await this.bookingPricingService.computePriceForBooking(
+        loaded ?? booking,
+      );
+      // A zero price or hard block means no rate is configured for this line
+      // on this lane. Roll the cargo back so the booking stays completable —
+      // the approved clearance is not lost — and surface why.
+      if (!(computed.totalAmount > 0) || computed.hardBlocked.length > 0) {
+        await this.wipeCargo(bookingId);
+        throw new BadRequestException(
+          computed.hardBlocked.length > 0
+            ? computed.hardBlocked.join("; ")
+            : "No rate is configured for your shipping line on this route/cargo — please contact Operations.",
+        );
+      }
+
+      await this.bookingsRepository.update(bookingId, {
+        totalAmount: computed.totalAmount,
+        priorityScore: computed.priorityScore,
+        pricingBreakdown: {
+          lineItems: computed.lineItems,
+          totalAmount: computed.totalAmount,
+          currency: computed.currency,
+          generatedAt: new Date().toISOString(),
+        },
+      } as never);
+      await this.bookingPricingService.createPricingSnapshots(
+        bookingId,
+        computed.usedRates,
+        computed.appliedModifiers,
+      );
+
+      // The charge goes on the line's credit ledger ("use now, pay later") —
+      // idempotent per booking, so a retried completion cannot double the debt.
+      await this.creditsService.recordCredit({
+        bookingId,
+        amount: computed.totalAmount,
+        currency: computed.currency,
+        description: `Freight service — booking ${booking.reference}`,
+      });
+    }
+
+    // Binding day, OPERATION_REQUEST_PENDING and the staff notification — the
+    // machine a customer booking uses. When the day is backed by a dedicated
+    // train, the customer day-pool gate is skipped (validated above instead).
+    return this.bookingTransitionService.requestOperation(
+      bookingId,
+      dto.scheduledDate,
+      null,
+      bypassDayPool ? { bypassDayPool: true } : undefined,
+    );
+  }
+
+  /**
+   * Persist the container lines of a CONTAINER completion. Same row shape the
+   * customer paths write (quantity per type, VGM totals, wagon share) — the
+   * per-unit ISO numbers customers also skip at booking time arrive later at
+   * yard operations.
+   */
+  private async persistContainerLines(
+    booking: Booking,
+    dto: CompleteShippingLineBookingDto,
+  ): Promise<void> {
+    const lines = dto.containers ?? [];
+    if (!lines.length) {
+      throw new BadRequestException("At least one container line is required.");
+    }
+
+    const containerTypeRepo =
+      this.bookingsRepository.manager.getRepository(ContainerType);
+    const containerRepo =
+      this.bookingsRepository.manager.getRepository(BookingContainer);
+
+    for (const line of lines) {
+      const containerType = await containerTypeRepo.findOne({
+        where: { id: line.containerTypeId, isActive: true },
+      });
+      if (!containerType) {
+        throw new NotFoundException(
+          `Container type ${line.containerTypeId} not found`,
+        );
+      }
+      const hazardous = Math.min(
+        Number(line.hazardousQuantity ?? 0),
+        line.quantity,
+      );
+      const reefer = Math.min(Number(line.reeferQuantity ?? 0), line.quantity);
+      const vgmPerUnit = Number(line.vgmPerUnitTons ?? 0);
+      await containerRepo.save(
+        containerRepo.create({
+          bookingId: booking.id,
+          containerTypeId: containerType.id,
+          containerSize: containerType.sizeFt
+            ? `${containerType.sizeFt}ft`
+            : null,
+          quantity: line.quantity,
+          hazardousQuantity: hazardous,
+          reeferQuantity: reefer,
+          returnQuantity: 0,
+          vgmPerUnitTons: vgmPerUnit,
+          totalVgmTons: vgmPerUnit * line.quantity,
+          wagonsRequired: Math.ceil(
+            line.quantity * wagonsPerUnitForSize(containerType.sizeFt),
+          ),
+        }),
+      );
+    }
+  }
+
+  /** Roll a failed/superseded completion back to the bare-booking shape. */
+  private async wipeCargo(bookingId: string): Promise<void> {
+    await this.bookingsRepository.manager
+      .getRepository(BookingContainer)
+      .softDelete({ bookingId });
+    await this.bookingsRepository.update(bookingId, {
+      cargoTypeId: null,
+      cargoTotalWeightVgm: 0,
+      bulkTotalWeightTons: null,
+      totalAmount: 0,
+      pricingBreakdown: null,
+    } as never);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.controller.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.controller.ts
index 243fd0a76..8a8e8ef2b 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.controller.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.controller.ts
@@ -11,7 +11,6 @@ import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
 
 import { PortalCustomer } from "../../common/booking-guards";
 import { CancelShippingLineBookingDto } from "./dto/cancel-shipping-line-booking.dto";
-import { CompleteShippingLineBookingDto } from "./dto/complete-shipping-line-booking.dto";
 import { InitiateShippingLineBookingDto } from "./dto/initiate-shipping-line-booking.dto";
 import { ShippingLineBookingsService } from "./shipping-line-bookings.service";
 
@@ -88,33 +87,6 @@ export class ShippingLineBookingsController {
     return this.shippingLineBookingsService.findMine(user.id, id);
   }
 
-  @Get(":id/available-days")
-  @PortalCustomer()
-  @ApiOperation({
-    summary:
-      "Days with an open departure that can carry this booking's cargo — for the completion form's day picker.",
-  })
-  async availableDays(
-    @CurrentUser() user: CurrentIamUser,
-    @Param("id", ParseUUIDPipe) id: string,
-  ) {
-    return this.shippingLineBookingsService.availableDaysMine(user.id, id);
-  }
-
-  @Post(":id/complete")
-  @PortalCustomer()
-  @ApiOperation({
-    summary:
-      "Complete an approved (CLEARANCE_READY) booking: cargo + binding shipment day. Prices off the line's rates, records the charge on the credit ledger and requests operation.",
-  })
-  async completeMine(
-    @CurrentUser() user: CurrentIamUser,
-    @Param("id", ParseUUIDPipe) id: string,
-    @Body() dto: CompleteShippingLineBookingDto,
-  ) {
-    return this.shippingLineBookingsService.completeMine(user.id, id, dto);
-  }
-
   @Post(":id/cancel")
   @PortalCustomer()
   @ApiOperation({
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.service.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.service.ts
index 333cab619..b9656807d 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.service.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.service.ts
@@ -8,28 +8,16 @@ import {
 import { InjectRepository } from "@nestjs/typeorm";
 import { In, MoreThanOrEqual, Repository } from "typeorm";
 
-import { BookingPricingService } from "../bookings/booking-pricing.service";
-import { BookingTransitionService } from "../bookings/booking-transition.service";
-import { BookingsService } from "../bookings/bookings.service";
-import { BookingContainer } from "../bookings/entities/booking-container.entity";
 import { BookingDocumentReview } from "../bookings/entities/booking-document-review.entity";
 import { BookingReviewNote } from "../bookings/entities/booking-review-note.entity";
 import { Booking } from "../bookings/entities/booking.entity";
 import { formatRouteLabel, Route } from "../routes/entities/route.entity";
-import { wagonsPerUnitForSize } from "../rule-engine/container-type.util";
 import { CargoType } from "../rule-engine/entities/cargo-type.entity";
 import { ContainerType } from "../rule-engine/entities/container-type.entity";
 import { ServiceType } from "../rule-engine/entities/service-type.entity";
 import { TrainSchedule } from "../train-schedules/entities/train-schedule.entity";
-import { TrainSchedulingService } from "../train-scheduling/services/train-scheduling.service";
-import { CompleteShippingLineBookingDto } from "./dto/complete-shipping-line-booking.dto";
 import { InitiateShippingLineBookingDto } from "./dto/initiate-shipping-line-booking.dto";
-import {
-  ShippingLineCredit,
-  ShippingLineCreditStatus,
-} from "./entities/shipping-line-credit.entity";
 import { ShippingLineCompaniesService } from "./shipping-line-companies.service";
-import { ShippingLineCreditsService } from "./shipping-line-credits.service";
 
 /**
  * The only trade direction a shipping line books.
@@ -77,11 +65,6 @@ export class ShippingLineBookingsService {
     @InjectRepository(Booking)
     private readonly bookingsRepository: Repository<Booking>,
     private readonly shippingLineCompaniesService: ShippingLineCompaniesService,
-    private readonly bookingsService: BookingsService,
-    private readonly bookingPricingService: BookingPricingService,
-    private readonly bookingTransitionService: BookingTransitionService,
-    private readonly trainSchedulingService: TrainSchedulingService,
-    private readonly creditsService: ShippingLineCreditsService,
   ) {}
 
   /**
@@ -393,267 +376,6 @@ export class ShippingLineBookingsService {
     }));
   }
 
-  /**
-   * Days the shipping line may pick as the shipment day — cargo-aware when the
-   * booking already carries cargo, departure-only before that. Same helper the
-   * customer day picker uses; ownership is checked first so one line cannot
-   * probe another's booking.
-   */
-  async availableDaysMine(userId: string, bookingId: string) {
-    const shippingLine = await this.requireShippingLine(userId);
-    const owned = await this.bookingsRepository.exists({
-      where: { id: bookingId, shippingLineCompanyId: shippingLine.id },
-    });
-    if (!owned) throw new NotFoundException(`Booking ${bookingId} not found`);
-    return this.bookingsService.availableDaysForBooking(bookingId);
-  }
-
-  /**
-   * Complete a bare shipping-line booking once Operations has approved its
-   * documents (CLEARANCE_READY), or after Operations returned the request
-   * (OPERATION_CHANGES_REQUESTED). This is the deferred half of
-   * {@link initiate}, mirroring what a customer does at this point: the cargo
-   * and the binding shipment day go in, the booking is priced off the line's
-   * negotiated rates, and the request lands with Operations
-   * (OPERATION_REQUEST_PENDING) through the same transition customers use.
-   *
-   * Payment differs from customers by design: no invoice is issued here.
-   * Shipping lines run on the credit ledger — the priced amount is recorded as
-   * an UNBILLED credit and Finance bills a batch later, so the booking
-   * proceeds without a payment gate.
-   */
-  async completeMine(
-    userId: string,
-    bookingId: string,
-    dto: CompleteShippingLineBookingDto,
-  ) {
-    const shippingLine = await this.requireShippingLine(userId);
-
-    const booking = await this.bookingsRepository.findOne({
-      where: { id: bookingId, shippingLineCompanyId: shippingLine.id },
-      relations: { bookingContainers: true },
-    });
-    if (!booking) throw new NotFoundException(`Booking ${bookingId} not found`);
-    if (
-      !["CLEARANCE_READY", "OPERATION_CHANGES_REQUESTED"].includes(
-        booking.status,
-      )
-    ) {
-      throw new BadRequestException(
-        "Your documents must be approved before the booking can be completed.",
-      );
-    }
-
-    // Completion is booking time: the route's booking window must be open —
-    // the same config-driven gate a customer booking passes.
-    await this.trainSchedulingService.assertBookingWindowOpen({
-      originYardId: booking.originYardId ?? null,
-      destinationYardId: booking.destinationYardId ?? null,
-      scheduledDate: dto.scheduledDate,
-      direction: booking.tradeDirection ?? null,
-    });
-
-    let hasCargo =
-      (booking.bookingContainers?.length ?? 0) > 0 ||
-      Number(booking.cargoTotalWeightVgm) > 0;
-    const restatesCargo = Boolean(
-      dto.containers?.length || dto.cargoTypeId || dto.cargoWeightTons,
-    );
-
-    // Operations may return the request asking for the CARGO to change, not
-    // just the day. A resubmit that restates cargo starts completion over:
-    // the recorded (unbilled) credit is written off and the persisted cargo
-    // wiped, so the fresh path below re-persists, re-prices and re-records.
-    // Once the credit is on an issued invoice the cargo is frozen — the
-    // invoice total must keep matching what it bills.
-    if (hasCargo && restatesCargo) {
-      const credit = await this.bookingsRepository.manager
-        .getRepository(ShippingLineCredit)
-        .findOne({ where: { bookingId } });
-      if (credit && credit.status === ShippingLineCreditStatus.Unbilled) {
-        await this.creditsService.cancelCredit(
-          credit.id,
-          "Cargo changed before billing — booking re-priced on completion.",
-        );
-      } else if (
-        credit &&
-        credit.status !== ShippingLineCreditStatus.Cancelled
-      ) {
-        throw new BadRequestException(
-          "This booking's charge has already been invoiced — contact Operations to change its cargo.",
-        );
-      }
-      await this.wipeCargo(bookingId);
-      hasCargo = false;
-    }
-
-    // First completion persists cargo and prices the booking; a day-only
-    // resubmit after OPERATION_CHANGES_REQUESTED skips straight to the
-    // operation request with the cargo (and price) it already carries.
-    if (!hasCargo) {
-      if (booking.freightType === "CONTAINER") {
-        await this.persistContainerLines(booking, dto);
-      } else {
-        if (!dto.cargoTypeId || !(Number(dto.cargoWeightTons) > 0)) {
-          throw new BadRequestException(
-            "Bulk bookings need a cargo type and a total weight in tons.",
-          );
-        }
-        const cargoType = await this.bookingsRepository.manager
-          .getRepository(CargoType)
-          .findOne({ where: { id: dto.cargoTypeId, isActive: true } });
-        if (!cargoType) {
-          throw new NotFoundException(
-            `Cargo type ${dto.cargoTypeId} not found`,
-          );
-        }
-      }
-
-      await this.bookingsRepository.update(bookingId, {
-        cargoTypeId:
-          booking.freightType === "BULK" ? (dto.cargoTypeId ?? null) : null,
-        cargoFreeText: dto.cargoFreeText?.trim() || null,
-        cargoTotalWeightVgm:
-          booking.freightType === "BULK" ? Number(dto.cargoWeightTons) : 0,
-        bulkTotalWeightTons:
-          booking.freightType === "BULK" ? Number(dto.cargoWeightTons) : null,
-        // Hazard is per-line for containers; the booking-level flag is what
-        // pricing bills the surcharge from.
-        isHazardous: (dto.containers ?? []).some(
-          (line) => Number(line.hazardousQuantity ?? 0) > 0,
-        ),
-        // Completion fixes the cargo — and therefore the price — so it is also
-        // where the billing currency is chosen.
-        paymentCurrency: dto.paymentCurrency ?? booking.paymentCurrency,
-      } as never);
-
-      const loaded = await this.bookingsRepository.findOne({
-        where: { id: bookingId },
-        relations: { bookingContainers: true, serviceType: true },
-      });
-      const computed = await this.bookingPricingService.computePriceForBooking(
-        loaded ?? booking,
-      );
-      // A zero price or hard block means no rate is configured for this line
-      // on this lane. Roll the cargo back so the booking stays completable —
-      // the approved clearance is not lost — and surface why.
-      if (!(computed.totalAmount > 0) || computed.hardBlocked.length > 0) {
-        await this.wipeCargo(bookingId);
-        throw new BadRequestException(
-          computed.hardBlocked.length > 0
-            ? computed.hardBlocked.join("; ")
-            : "No rate is configured for your shipping line on this route/cargo — please contact Operations.",
-        );
-      }
-
-      await this.bookingsRepository.update(bookingId, {
-        totalAmount: computed.totalAmount,
-        priorityScore: computed.priorityScore,
-        pricingBreakdown: {
-          lineItems: computed.lineItems,
-          totalAmount: computed.totalAmount,
-          currency: computed.currency,
-          generatedAt: new Date().toISOString(),
-        },
-      } as never);
-      await this.bookingPricingService.createPricingSnapshots(
-        bookingId,
-        computed.usedRates,
-        computed.appliedModifiers,
-      );
-
-      // The charge goes on the line's credit ledger ("use now, pay later") —
-      // idempotent per booking, so a retried completion cannot double the debt.
-      await this.creditsService.recordCredit({
-        bookingId,
-        amount: computed.totalAmount,
-        currency: computed.currency,
-        description: `Freight service — booking ${booking.reference}`,
-      });
-    }
-
-    // Binding day + open-departure validation, OPERATION_REQUEST_PENDING and
-    // the staff notification — the exact machine a customer booking uses.
-    await this.bookingTransitionService.requestOperation(
-      bookingId,
-      dto.scheduledDate,
-      null,
-    );
-    return this.findMine(userId, bookingId);
-  }
-
-  /**
-   * Persist the container lines of a CONTAINER completion. Same row shape the
-   * customer paths write (quantity per type, VGM totals, wagon share) — the
-   * per-unit ISO numbers customers also skip at booking time arrive later at
-   * yard operations.
-   */
-  private async persistContainerLines(
-    booking: Booking,
-    dto: CompleteShippingLineBookingDto,
-  ): Promise<void> {
-    const lines = dto.containers ?? [];
-    if (!lines.length) {
-      throw new BadRequestException(
-        "At least one container line is required.",
-      );
-    }
-
-    const containerTypeRepo =
-      this.bookingsRepository.manager.getRepository(ContainerType);
-    const containerRepo =
-      this.bookingsRepository.manager.getRepository(BookingContainer);
-
-    for (const line of lines) {
-      const containerType = await containerTypeRepo.findOne({
-        where: { id: line.containerTypeId, isActive: true },
-      });
-      if (!containerType) {
-        throw new NotFoundException(
-          `Container type ${line.containerTypeId} not found`,
-        );
-      }
-      const hazardous = Math.min(
-        Number(line.hazardousQuantity ?? 0),
-        line.quantity,
-      );
-      const reefer = Math.min(Number(line.reeferQuantity ?? 0), line.quantity);
-      const vgmPerUnit = Number(line.vgmPerUnitTons ?? 0);
-      await containerRepo.save(
-        containerRepo.create({
-          bookingId: booking.id,
-          containerTypeId: containerType.id,
-          containerSize: containerType.sizeFt
-            ? `${containerType.sizeFt}ft`
-            : null,
-          quantity: line.quantity,
-          hazardousQuantity: hazardous,
-          reeferQuantity: reefer,
-          returnQuantity: 0,
-          vgmPerUnitTons: vgmPerUnit,
-          totalVgmTons: vgmPerUnit * line.quantity,
-          wagonsRequired: Math.ceil(
-            line.quantity * wagonsPerUnitForSize(containerType.sizeFt),
-          ),
-        }),
-      );
-    }
-  }
-
-  /** Roll a failed/superseded completion back to the bare-booking shape. */
-  private async wipeCargo(bookingId: string): Promise<void> {
-    await this.bookingsRepository.manager
-      .getRepository(BookingContainer)
-      .softDelete({ bookingId });
-    await this.bookingsRepository.update(bookingId, {
-      cargoTypeId: null,
-      cargoTotalWeightVgm: 0,
-      bulkTotalWeightTons: null,
-      totalAmount: 0,
-      pricingBreakdown: null,
-    } as never);
-  }
-
   /**
    * Cancel one of the signed-in shipping line's own bookings.
    *
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts
index f8f682dde..698dfb384 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts
@@ -5,10 +5,8 @@ import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
 
 import { FreightAuthModule } from "../auth/freight-auth.module";
 import { BillingModule } from "../billing/billing.module";
-import { BookingsModule } from "../bookings/bookings.module";
 import { Booking } from "../bookings/entities/booking.entity";
 import { OtpModule } from "../otp/otp.module";
-import { TrainSchedulingModule } from "../train-scheduling/train-scheduling.module";
 import { ShippingLineCompany } from "./entities/shipping-line-company.entity";
 import { ShippingLineCredit } from "./entities/shipping-line-credit.entity";
 import { ShippingLineBookingsController } from "./shipping-line-bookings.controller";
@@ -38,12 +36,6 @@ import { ShippingLineCreditsService } from "./shipping-line-credits.service";
     // `shipping_line_credit.invoice.paid` event, but the module graph now cycles
     // (billing -> companies -> here -> billing), so this edge needs forwardRef.
     forwardRef(() => BillingModule),
-    // Booking completion reuses the customer machinery: pricing, the
-    // operation-request transition and the day picker. Both edges cycle back
-    // here (bookings -> rule-engine -> shipping-lines, train-scheduling ->
-    // bookings -> …), so both need forwardRef.
-    forwardRef(() => BookingsModule),
-    forwardRef(() => TrainSchedulingModule),
   ],
   controllers: [
     ShippingLineCompaniesController,
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/entities/train-scheduling-global-rules.entity.ts b/apps/edr-freight-api/src/modules/train-scheduling/entities/train-scheduling-global-rules.entity.ts
index 94882833b..50debc6c0 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/entities/train-scheduling-global-rules.entity.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/entities/train-scheduling-global-rules.entity.ts
@@ -57,9 +57,10 @@ export class TrainSchedulingGlobalRules extends BaseEntity {
   /**
    * Local (Africa/Addis_Ababa) hour the booking desk shuts each day. A not-yet-full
    * train whose next cycle would reopen at/after this hour pauses until the next
-   * morning's windowOpenHour. Set equal to windowOpenHour for a 24-hour desk.
+   * morning's windowOpenHour. Set equal to windowOpenHour for a 24-hour desk
+   * (the default).
    */
-  @Column({ name: 'window_close_hour', type: 'int', default: 17 })
+  @Column({ name: 'window_close_hour', type: 'int', default: 8 })
   windowCloseHour!: number;
 
   // Stored in hours; 4 decimals so sub-minute UI durations (4 min = 0.0667h)
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index a908a6926..7125e3bbf 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -471,7 +471,11 @@ export class TrainSchedulingService {
   private async emitWindowState(scheduleId: string): Promise<void> {
     try {
       const fresh = await this.trainSchedulesRepository.findById(scheduleId);
-      if (fresh) this.bookingWindowGateway.emitPhase(fresh);
+      // Dedicated shipping-line departures are never announced to the portal —
+      // the broadcast reaches every customer client.
+      if (fresh && !fresh.shippingLineCompanyId) {
+        this.bookingWindowGateway.emitPhase(fresh);
+      }
     } catch (err) {
       this.logger.warn(
         `Booking-window push failed for ${scheduleId}: ${(err as Error).message}`,
@@ -512,7 +516,11 @@ export class TrainSchedulingService {
       // and a newborn anchoring to it would inherit that dead window verbatim.
       .andWhere('s.status != :cancelledStatus', {
         cancelledStatus: TrainScheduleStatusEnum.Cancelled,
-      });
+      })
+      // A dedicated shipping-line departure is never a sibling either: it runs
+      // no window cycle, so it must neither anchor a customer group nor be
+      // dragged through one's open/doc-review/payment instants.
+      .andWhere('s.shippingLineCompanyId IS NULL');
     if (excludeScheduleId) {
       qb.andWhere('s.id != :excludeScheduleId', { excludeScheduleId });
     }
@@ -1612,8 +1620,11 @@ export class TrainSchedulingService {
       // doc-review/payment phase — so there is no cross-expiry to fix, and two
       // export trains departing the same day at different times must keep their
       // own departure-anchored windows.
+      // Dedicated shipping-line departures never group either: they run no
+      // window cycle at all, so sharing a customer group's timeline (or
+      // anchoring one) would drag them into phases they must not have.
       const groupAnchor =
-        direction === 'EXPORT'
+        direction === 'EXPORT' || dto.shippingLineCompanyId
           ? null
           : await this.findGroupWindowAnchor(
               manager,
@@ -1678,45 +1689,71 @@ export class TrainSchedulingService {
       // only re-derives NOT-YET-OPEN schedules (see restampPendingWindows); an
       // already-open schedule keeps this snapshot, and the batch board draws its
       // windows from it rather than the live config.
-      const ruleSnapshot = windowRuleSnapshot(windowCfg);
-      const computedTimes =
-        direction === 'EXPORT'
-          ? { ...ruleSnapshot, ...computeExportWindowTimes(departure, windowCfg) }
-          : {
-              // IMPORT and DOMESTIC share the import booking-day window cycle.
-              ...ruleSnapshot,
-              ...computeImportWindowTimes(departure, windowCfg, new Date()),
-            };
-      // Inside-lead departure (e.g. a huge configured lead): the raw open lands
-      // in the past — clamp it to `now` so the window tick opens it immediately.
-      if (computedTimes.windowOpensAt.getTime() < Date.now()) {
-        computedTimes.windowOpensAt = new Date();
+      let windowFields: Partial<TrainSchedule>;
+      if (dto.shippingLineCompanyId) {
+        // Dedicated shipping-line departure: NO window cycle at all. The line
+        // books whenever it wants from creation until the close offset before
+        // departure. windowPhase stays NULL, so the window engine, restamp and
+        // the customer window lists all skip this schedule; the close-offset
+        // gate is enforced by the shipping-line completion path, which reads
+        // windowClosesAt stamped here.
+        const offsetMinutes = windowCfg.importCloseOffsetMinutes ?? 0;
+        const closesAt = new Date(departure.getTime() - offsetMinutes * 60_000);
+        if (closesAt.getTime() <= Date.now()) {
+          throw new BadRequestException(
+            'With the booking-close offset applied, this departure would already be ' +
+              'closed for shipping-line booking — pick a later departure.',
+          );
+        }
+        windowFields = {
+          bookingWindowStatus: 'OPEN',
+          windowPhase: null,
+          windowOpensAt: new Date(),
+          windowClosesAt: closesAt,
+          ruleImportCloseOffsetMinutes: offsetMinutes || null,
+          windowRuleCustom: dto.windowRule != null,
+        };
+      } else {
+        const ruleSnapshot = windowRuleSnapshot(windowCfg);
+        const computedTimes =
+          direction === 'EXPORT'
+            ? { ...ruleSnapshot, ...computeExportWindowTimes(departure, windowCfg) }
+            : {
+                // IMPORT and DOMESTIC share the import booking-day window cycle.
+                ...ruleSnapshot,
+                ...computeImportWindowTimes(departure, windowCfg, new Date()),
+              };
+        // Inside-lead departure (e.g. a huge configured lead): the raw open lands
+        // in the past — clamp it to `now` so the window tick opens it immediately.
+        if (computedTimes.windowOpensAt.getTime() < Date.now()) {
+          computedTimes.windowOpensAt = new Date();
+        }
+        if (
+          computedTimes.windowOpensAt.getTime() >= computedTimes.windowClosesAt.getTime()
+        ) {
+          throw new BadRequestException(
+            'These booking-window settings leave no window before departure — with the ' +
+              'desk hours and close offset applied, the window would only open once the ' +
+              'train has left.',
+          );
+        }
+        windowFields = {
+          bookingWindowStatus: 'CLOSED',
+          windowPhase: 'PRE_WINDOW',
+          ...(groupAnchor
+            ? this.groupWindowFieldsFrom(groupAnchor, departure)
+            : computedTimes),
+          // `windowRuleSnapshot` never stamps the pay window (NULL = follow the
+          // live global value for the direction), so an explicit staff override is
+          // persisted here — the same field the post-creation override writes.
+          ...(dto.windowRule?.paymentWindowMinutes !== undefined
+            ? { rulePaymentWindowMinutes: dto.windowRule.paymentWindowMinutes }
+            : {}),
+          // Hand-configured windows opt OUT of the global re-stamp, or the next
+          // global-rules edit would overwrite exactly what staff chose here.
+          windowRuleCustom: dto.windowRule != null,
+        };
       }
-      if (
-        computedTimes.windowOpensAt.getTime() >= computedTimes.windowClosesAt.getTime()
-      ) {
-        throw new BadRequestException(
-          'These booking-window settings leave no window before departure — with the ' +
-            'desk hours and close offset applied, the window would only open once the ' +
-            'train has left.',
-        );
-      }
-      const windowFields = {
-        bookingWindowStatus: 'CLOSED',
-        windowPhase: 'PRE_WINDOW',
-        ...(groupAnchor
-          ? this.groupWindowFieldsFrom(groupAnchor, departure)
-          : computedTimes),
-        // `windowRuleSnapshot` never stamps the pay window (NULL = follow the
-        // live global value for the direction), so an explicit staff override is
-        // persisted here — the same field the post-creation override writes.
-        ...(dto.windowRule?.paymentWindowMinutes !== undefined
-          ? { rulePaymentWindowMinutes: dto.windowRule.paymentWindowMinutes }
-          : {}),
-        // Hand-configured windows opt OUT of the global re-stamp, or the next
-        // global-rules edit would overwrite exactly what staff chose here.
-        windowRuleCustom: dto.windowRule != null,
-      };
       // A built train's own consist is the schedule's capacity: full when all
       // its wagons are allocated. Trains built without wagons yet fall back to
       // the configured limit.
diff --git a/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx b/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx
index 8682844d8..e05e00917 100644
--- a/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx
@@ -227,6 +227,12 @@ const RuleEngineFormDialog = ({
       current[name] ? { ...current, [name]: "" } : current,
     );
     setValues((current) => {
+      // Mantine fires onChange even when the same option is re-picked, and the
+      // cascades below clear dependent answers (yards, unit, scope). Re-picking
+      // an unchanged value must be a no-op, or an untouched direction silently
+      // wipes the yard pair and the submit fails with "origin/destination
+      // missing" data the admin did fill in.
+      if (current[name] === value) return current;
       const next = { ...current, [name]: value };
       // Changing what a rate applies to (or its surcharge trigger) can invalidate
       // the previously-chosen unit — reset it so the admin re-picks from the new
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/BookingWindowSettingsModal.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/BookingWindowSettingsModal.tsx
index d09bce567..9bf95a01f 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/BookingWindowSettingsModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/BookingWindowSettingsModal.tsx
@@ -27,7 +27,8 @@ import type { UpdateScheduleWindowRulePayload } from "@/types/trainScheduling";
 /** Fallbacks matching the API's global-rules defaults (used when a field is null). */
 const DEFAULTS = {
   windowOpenHour: 8,
-  windowCloseHour: 17,
+  // Equal to open ⇒ 24-hour desk (the default).
+  windowCloseHour: 8,
   windowDurationHours: 3,
   docReviewMinutes: 30,
   paymentWindowMinutes: 60,
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/CreateScheduleWindowFields.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/CreateScheduleWindowFields.tsx
index b0de39baa..6d618eb64 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/CreateScheduleWindowFields.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/CreateScheduleWindowFields.tsx
@@ -22,7 +22,8 @@ import type { CreateScheduleWindowRulePayload } from "@/types/trainScheduling";
 /** Fallbacks matching the API's global-rules defaults (used if the fetch fails). */
 const DEFAULTS = {
   windowOpenHour: 8,
-  windowCloseHour: 17,
+  // Equal to open ⇒ 24-hour desk (the default).
+  windowCloseHour: 8,
   windowDurationHours: 3,
   docReviewMinutes: 30,
   paymentWindowMinutes: 60,
diff --git a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
index bdb5dfd9c..a2a33ac4d 100644
--- a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
@@ -682,7 +682,11 @@ const RuleEngineResourcePage = () => {
       // ton·km, container = per km + distance band) and the currency stays as
       // chosen (birr or dollar). Everything else remains USD-only.
       const isLastMile = values.appliesTo === "LAST_MILE";
-      const { lastMileMode, ...rest } = values;
+      // The shipping-line toggle is form-only — the API's whitelist rejects the
+      // whole payload if it leaks through ("property isShippingLineRate should
+      // not exist").
+      const { lastMileMode, isShippingLineRate: _toggle, ...rest } = values;
+      void _toggle;
       payload = {
         ...rest,
         currency: isLastMile ? (values.currency ?? "ETB") : "USD",
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingDetailPage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingDetailPage.tsx
index 457a2dbc9..669c9d610 100644
--- a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingDetailPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingDetailPage.tsx
@@ -220,7 +220,7 @@ export default function ShippingLineBookingDetailPage() {
             >
               {status === "OPERATION_CHANGES_REQUESTED"
                 ? "Resubmit booking"
-                : "Complete booking"}
+                : "Book"}
             </Button>
           )}
         </Group>
@@ -317,7 +317,7 @@ export default function ShippingLineBookingDetailPage() {
                   >
                     {status === "OPERATION_CHANGES_REQUESTED"
                       ? "Resubmit booking"
-                      : "Complete booking"}
+                      : "Book"}
                   </Button>
                 )}
               </Group>
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
index e8cd132fa..a67fb4f64 100644
--- a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
@@ -41,9 +41,16 @@ import {
   DOC_STATE_COLOR,
   DOC_STATE_LABEL,
 } from "./booking-doc-state";
+import ShippingLineCompleteModal from "./ShippingLineCompleteModal";
 import ShippingLineDocumentsModal from "./ShippingLineDocumentsModal";
 import ShippingLineInitiateModal from "./ShippingLineInitiateModal";
 
+/** Statuses where the booking is approved and waiting to be booked. */
+const BOOKABLE_STATUSES = new Set([
+  "CLEARANCE_READY",
+  "OPERATION_CHANGES_REQUESTED",
+]);
+
 function ColHeader({ label }: { label: string }) {
   return (
     <Text fz={12} fw={700} c="edr-muted" tt="uppercase" lts="0.04em">
@@ -67,6 +74,9 @@ export default function ShippingLineBookingsPage() {
   const [docsBooking, setDocsBooking] = useState<ShippingLineBooking | null>(
     null,
   );
+  const [bookBooking, setBookBooking] = useState<ShippingLineBooking | null>(
+    null,
+  );
 
   const bookingsQuery = useQuery({
     queryKey: ["shipping-line-bookings"],
@@ -154,6 +164,7 @@ export default function ShippingLineBookingsPage() {
         const state = bookingDocState(booking);
         const showDocs = hasDocuments(state);
         const wantsUpload = needsUpload(state);
+        const bookable = BOOKABLE_STATUSES.has(booking.status as string);
 
         return (
           <Group
@@ -162,7 +173,24 @@ export default function ShippingLineBookingsPage() {
             wrap="nowrap"
             onClick={(e) => e.stopPropagation()}
           >
-            {showDocs && (
+            {/* Approved documents make booking the primary move — the docs
+                button steps back into the menu so one action owns the row. */}
+            {bookable && (
+              <Button
+                size="xs"
+                radius="md"
+                color="edr-green"
+                fw={700}
+                fz={13}
+                leftSection={<PackageCheck size={14} />}
+                onClick={() => setBookBooking(booking)}
+              >
+                {booking.status === "OPERATION_CHANGES_REQUESTED"
+                  ? "Resubmit"
+                  : "Book"}
+              </Button>
+            )}
+            {showDocs && !bookable && (
               <Button
                 size="xs"
                 radius="md"
@@ -214,19 +242,14 @@ export default function ShippingLineBookingsPage() {
                     {DOC_STATE_ACTION_LABEL[state]}
                   </Menu.Item>
                 )}
-                {/* Approved documents (or an operations return) unlock the
-                    completion step — it lives on the detail page. */}
-                {(booking.status === "CLEARANCE_READY" ||
-                  booking.status === "OPERATION_CHANGES_REQUESTED") && (
+                {bookable && (
                   <Menu.Item
                     leftSection={<PackageCheck size={15} />}
-                    onClick={() =>
-                      navigate(`/shipping-line/bookings/${booking.id}`)
-                    }
+                    onClick={() => setBookBooking(booking)}
                   >
                     {booking.status === "OPERATION_CHANGES_REQUESTED"
                       ? "Resubmit booking"
-                      : "Complete booking"}
+                      : "Book"}
                   </Menu.Item>
                 )}
               </Menu.Dropdown>
@@ -325,6 +348,16 @@ export default function ShippingLineBookingsPage() {
         booking={docsBooking}
         onClose={() => setDocsBooking(null)}
       />
+
+      <ShippingLineCompleteModal
+        booking={bookBooking}
+        onClose={() => setBookBooking(null)}
+        onCompleted={(booking) => {
+          setBookBooking(null);
+          // Straight into the booking — its status and price just changed.
+          navigate(`/shipping-line/bookings/${booking.id}`);
+        }}
+      />
     </Box>
   );
 }

From 147887b7c586f9222280778abef20547bc2d5e48 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 18:13:42 +0000
Subject: [PATCH 086/174] feat: dashbaord overview

---
 .../overview/dto/overview-tab-response.dto.ts |  83 +++++
 .../modules/overview/overview.controller.ts   |  18 +
 .../modules/overview/overview.repository.ts   | 345 ++++++++++++++++++
 .../src/modules/overview/overview.service.ts  |  99 ++++-
 .../overview/layouts/ClearanceOverview.tsx    | 154 ++++++++
 .../overview/layouts/ExecutiveOverview.tsx    |  76 ++++
 .../overview/layouts/FinanceOverview.tsx      |  58 +++
 .../overview/layouts/MarketingOverview.tsx    | 154 ++++++++
 .../overview/layouts/OccOverview.tsx          | 181 +++++++++
 .../overview/layouts/OperationsOverview.tsx   | 181 +++++++++
 .../overview/layouts/TrainLoadCard.tsx        |  74 ++++
 .../overview/layouts/layout-kit.tsx           | 164 +++++++++
 .../overview/role-dashboards.config.ts        |  50 +++
 .../overview/summary/OverviewHero.tsx         |  16 +
 .../overview/summary/OverviewHeroKpis.tsx     |  12 +-
 .../src/components/page/KpiStrip.tsx          |  10 +-
 .../backoffice/src/constants/QUERY_KEYS.ts    |   2 +
 .../backoffice/src/constants/URLS.ts          |   2 +
 .../backoffice/src/hooks/useOverview.ts       |  16 +
 .../src/pages/dashboard/OverviewPage.tsx      | 114 ++----
 .../src/services/overview.service.ts          |  15 +
 .../backoffice/src/types/overview.ts          |   5 +
 packages/types/src/freight/overview.ts        |  60 +++
 23 files changed, 1795 insertions(+), 94 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/layouts/ClearanceOverview.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/layouts/ExecutiveOverview.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/layouts/FinanceOverview.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/layouts/MarketingOverview.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/layouts/OccOverview.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/layouts/OperationsOverview.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/layouts/TrainLoadCard.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/layouts/layout-kit.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/overview/role-dashboards.config.ts

diff --git a/apps/edr-freight-api/src/modules/overview/dto/overview-tab-response.dto.ts b/apps/edr-freight-api/src/modules/overview/dto/overview-tab-response.dto.ts
index 7c60a91a6..fff9c138d 100644
--- a/apps/edr-freight-api/src/modules/overview/dto/overview-tab-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/overview/dto/overview-tab-response.dto.ts
@@ -116,6 +116,28 @@ export class OverviewTonnagePointDto {
   @ApiProperty() tons!: number;
 }
 
+/** One bucket × series cell of a two-dimensional breakdown. */
+export class OverviewMatrixCellDto {
+  @ApiProperty({ example: 'Flat wagon' }) group!: string;
+  @ApiProperty({ example: 'AVAILABLE' }) series!: string;
+  @ApiProperty() count!: number;
+}
+
+export class OverviewTrainLoadDto {
+  @ApiProperty() scheduleId!: string;
+  @ApiProperty({ example: '8001' }) trainNumber!: string;
+  @ApiProperty({ example: '2026-08-13' }) date!: string;
+  @ApiProperty({ example: 'EXPORT' }) direction!: string;
+  @ApiProperty() wagonsAllocated!: number;
+  @ApiProperty() wagonsTotal!: number;
+  @ApiProperty() tons!: number;
+}
+
+export class OverviewTurnaroundDto {
+  @ApiProperty({ example: '8001' }) trainSet!: string;
+  @ApiProperty({ example: 26.5 }) hours!: number;
+}
+
 export class OverviewOperationsTabDto {
   @ApiProperty({ type: OverviewOperationsKpisDto })
   kpis!: OverviewOperationsKpisDto;
@@ -150,6 +172,64 @@ export class OverviewOperationsTabDto {
   @ApiProperty({ type: [OverviewStatusCountDto] })
   cargoStatusBreakdown!: OverviewStatusCountDto[];
 
+  @ApiProperty({ type: [OverviewLabelCountDto] })
+  bookingsByPort!: OverviewLabelCountDto[];
+
+  @ApiProperty({ type: [OverviewMatrixCellDto] })
+  bookingStatusByPort!: OverviewMatrixCellDto[];
+
+  @ApiProperty({ type: [OverviewTrainLoadDto] })
+  trainLoads!: OverviewTrainLoadDto[];
+
+  @ApiProperty()
+  generatedAt!: string;
+}
+
+export class OverviewFleetTabDto {
+  @ApiProperty({ type: [OverviewStatusCountDto] })
+  wagonStatusBreakdown!: OverviewStatusCountDto[];
+
+  @ApiProperty({ type: [OverviewMatrixCellDto] })
+  wagonStatusByType!: OverviewMatrixCellDto[];
+
+  @ApiProperty({ type: [OverviewMatrixCellDto] })
+  wagonStatusByYard!: OverviewMatrixCellDto[];
+
+  @ApiProperty({ type: [OverviewStatusCountDto] })
+  locomotiveStatusBreakdown!: OverviewStatusCountDto[];
+
+  @ApiProperty({ type: [OverviewMatrixCellDto] })
+  locomotivesByYard!: OverviewMatrixCellDto[];
+
+  @ApiProperty({ type: [OverviewLabelCountDto] })
+  locomotivesByType!: OverviewLabelCountDto[];
+
+  @ApiProperty({ nullable: true, example: 26.5 })
+  avgTurnaroundHours!: number | null;
+
+  @ApiProperty({ type: [OverviewTurnaroundDto] })
+  turnaroundByTrain!: OverviewTurnaroundDto[];
+
+  @ApiProperty()
+  generatedAt!: string;
+}
+
+export class OverviewClearanceTabDto {
+  @ApiProperty({ type: [OverviewStatusCountDto] })
+  bookingDocumentsByStatus!: OverviewStatusCountDto[];
+
+  @ApiProperty({ type: [OverviewStatusCountDto] })
+  contractDocumentsByStatus!: OverviewStatusCountDto[];
+
+  @ApiProperty({ type: [OverviewStatusCountDto] })
+  invoicesByStatus!: OverviewStatusCountDto[];
+
+  @ApiProperty({ type: [OverviewLabelCountDto] })
+  invoicesByType!: OverviewLabelCountDto[];
+
+  @ApiProperty({ type: [OverviewMatrixCellDto] })
+  handoversByMile!: OverviewMatrixCellDto[];
+
   @ApiProperty()
   generatedAt!: string;
 }
@@ -167,6 +247,9 @@ export class OverviewCustomersTabDto {
   @ApiProperty({ type: [OverviewLabelCountDto] })
   topCustomersByBookings!: OverviewLabelCountDto[];
 
+  @ApiProperty({ type: [OverviewMatrixCellDto] })
+  profilesByTypeStatus!: OverviewMatrixCellDto[];
+
   @ApiProperty()
   generatedAt!: string;
 }
diff --git a/apps/edr-freight-api/src/modules/overview/overview.controller.ts b/apps/edr-freight-api/src/modules/overview/overview.controller.ts
index 45c5cbfed..fcec82d4d 100644
--- a/apps/edr-freight-api/src/modules/overview/overview.controller.ts
+++ b/apps/edr-freight-api/src/modules/overview/overview.controller.ts
@@ -15,8 +15,10 @@ import { OverviewResponseDto } from './dto/overview-response.dto';
 import {
   OverviewBillingTabDto,
   OverviewBookingsTabDto,
+  OverviewClearanceTabDto,
   OverviewContractsTabDto,
   OverviewCustomersTabDto,
+  OverviewFleetTabDto,
   OverviewOperationsTabDto,
   OverviewStaffTabDto,
 } from './dto/overview-tab-response.dto';
@@ -106,6 +108,22 @@ export class OverviewController {
     return this.overviewService.getOperationsTab(query.range ?? '30d');
   }
 
+  @Get('fleet')
+  @BookingStaff(FREIGHT_PERMS.overview.view)
+  @ApiOperation({ summary: 'Wagon and locomotive fleet detail, plus turnaround' })
+  @ApiOkResponse({ type: OverviewFleetTabDto })
+  getFleetTab(@Query() query: OverviewQueryDto): Promise<OverviewFleetTabDto> {
+    return this.overviewService.getFleetTab(query.range ?? '30d');
+  }
+
+  @Get('clearance')
+  @BookingStaff(FREIGHT_PERMS.overview.view)
+  @ApiOperation({ summary: 'Document review and invoice queues' })
+  @ApiOkResponse({ type: OverviewClearanceTabDto })
+  getClearanceTab(): Promise<OverviewClearanceTabDto> {
+    return this.overviewService.getClearanceTab();
+  }
+
   @Get('customers')
   @BookingStaff(FREIGHT_PERMS.overview.view)
   @ApiOperation({ summary: 'Customers tab metrics and charts' })
diff --git a/apps/edr-freight-api/src/modules/overview/overview.repository.ts b/apps/edr-freight-api/src/modules/overview/overview.repository.ts
index 18b6bb54d..ec258b274 100644
--- a/apps/edr-freight-api/src/modules/overview/overview.repository.ts
+++ b/apps/edr-freight-api/src/modules/overview/overview.repository.ts
@@ -58,6 +58,21 @@ export type OverviewRecentBookingRow = {
   createdAt: Date;
 };
 
+/** One cell of a two-dimensional breakdown (bucket × stacked series). */
+export type MatrixCell = { group: string; series: string; count: number };
+
+export type TurnaroundRow = { trainSet: string; hours: number };
+
+export type TrainLoadRow = {
+  scheduleId: string;
+  trainNumber: string;
+  date: string;
+  direction: string;
+  wagonsAllocated: number;
+  wagonsTotal: number;
+  tons: number;
+};
+
 export type OverviewContractKpisRow = {
   total: number;
   totalActive: number;
@@ -1261,4 +1276,334 @@ export class OverviewRepository {
       createdAt: row.createdAt,
     }));
   }
+
+  // ---------------------------------------------------------------------------
+  // Fleet / operations detail. These read tables that have no repository
+  // injected here (locomotives, train_set_wagons, document reviews, …), so they
+  // go through the shared entity manager with plain SQL instead of adding six
+  // more constructor arguments for one query each.
+  // ---------------------------------------------------------------------------
+
+  private get sql() {
+    return this.wagonRepository.manager;
+  }
+
+  private async matrix(
+    statement: string,
+    params: unknown[] = [],
+  ): Promise<MatrixCell[]> {
+    const rows = await this.sql.query<
+      { group: string; series: string; count: string }[]
+    >(statement, params);
+    return rows.map((row) => ({
+      group: row.group,
+      series: row.series,
+      count: Number(row.count),
+    }));
+  }
+
+  private async labelCounts(
+    statement: string,
+    params: unknown[] = [],
+  ): Promise<{ label: string; count: number }[]> {
+    const rows = await this.sql.query<{ label: string; count: string }[]>(
+      statement,
+      params,
+    );
+    return rows.map((row) => ({ label: row.label, count: Number(row.count) }));
+  }
+
+  private async statusCounts(
+    statement: string,
+    params: unknown[] = [],
+  ): Promise<{ status: string; count: number }[]> {
+    const rows = await this.sql.query<{ status: string; count: string }[]>(
+      statement,
+      params,
+    );
+    return rows.map((row) => ({ status: row.status, count: Number(row.count) }));
+  }
+
+  /** Wagon lifecycle state crossed with wagon type — "how many flat wagons are detained". */
+  getWagonStatusByType(): Promise<MatrixCell[]> {
+    return this.matrix(`
+      SELECT COALESCE(wt.name, 'Unknown') AS "group",
+             w.status AS series,
+             COUNT(*)::int AS count
+      FROM freight.wagons w
+      LEFT JOIN freight.wagon_types wt ON wt.id = w.wagon_type_id
+      WHERE w.deleted_at IS NULL
+      GROUP BY 1, 2
+      ORDER BY 1, 2
+    `);
+  }
+
+  /** Same lifecycle state, per yard the wagon currently sits in. */
+  getWagonStatusByYard(): Promise<MatrixCell[]> {
+    return this.matrix(`
+      SELECT y.label AS "group",
+             w.status AS series,
+             COUNT(*)::int AS count
+      FROM freight.wagons w
+      INNER JOIN freight.yards y ON y.id = w.current_yard_id
+      WHERE w.deleted_at IS NULL
+      GROUP BY 1, 2
+      ORDER BY 1, 2
+    `);
+  }
+
+  getLocomotiveStatusBreakdown(): Promise<{ status: string; count: number }[]> {
+    return this.statusCounts(`
+      SELECT status, COUNT(*)::int AS count
+      FROM freight.locomotives
+      WHERE deleted_at IS NULL
+      GROUP BY status
+      ORDER BY count DESC
+    `);
+  }
+
+  /** Locomotives per station, split by status — the OCC's first question. */
+  getLocomotivesByYard(): Promise<MatrixCell[]> {
+    return this.matrix(`
+      SELECT COALESCE(y.label, 'Unassigned') AS "group",
+             l.status AS series,
+             COUNT(*)::int AS count
+      FROM freight.locomotives l
+      LEFT JOIN freight.yards y ON y.id = l.current_yard_id
+      WHERE l.deleted_at IS NULL
+      GROUP BY 1, 2
+      ORDER BY 1, 2
+    `);
+  }
+
+  getLocomotivesByType(): Promise<{ label: string; count: number }[]> {
+    return this.labelCounts(`
+      SELECT COALESCE(locomotive_type, 'Unknown') AS label,
+             COUNT(*)::int AS count
+      FROM freight.locomotives
+      WHERE deleted_at IS NULL
+      GROUP BY 1
+      ORDER BY count DESC
+    `);
+  }
+
+  /**
+   * Departure-to-departure gap per train set over the range. Only consecutive
+   * *actual* departures count — a schedule that never left says nothing about
+   * how fast the set turned around.
+   */
+  async getTrainTurnaround(
+    days: number,
+    limit: number,
+  ): Promise<{ avgHours: number | null; rows: TurnaroundRow[] }> {
+    const rows = await this.sql.query<
+      { trainSet: string; hours: string }[]
+    >(
+      `
+      WITH departures AS (
+        SELECT s.train_set_id,
+               s.actual_departure_at,
+               LAG(s.actual_departure_at) OVER (
+                 PARTITION BY s.train_set_id ORDER BY s.actual_departure_at
+               ) AS previous_departure
+        FROM freight.train_schedules s
+        WHERE s.deleted_at IS NULL
+          AND s.actual_departure_at IS NOT NULL
+          AND s.actual_departure_at >= NOW() - make_interval(days => $1::int)
+      )
+      SELECT COALESCE(t.train_number, t.code, 'Train set') AS "trainSet",
+             ROUND(
+               AVG(
+                 EXTRACT(EPOCH FROM (d.actual_departure_at - d.previous_departure)) / 3600
+               )::numeric,
+               1
+             ) AS hours
+      FROM departures d
+      LEFT JOIN freight.train_sets ts ON ts.id = d.train_set_id
+      LEFT JOIN freight.trains t ON t.id = ts.train_id
+      WHERE d.previous_departure IS NOT NULL
+      GROUP BY 1
+      ORDER BY hours ASC
+      LIMIT $2::int
+    `,
+      [days, limit],
+    );
+
+    const mapped = rows.map((row) => ({
+      trainSet: row.trainSet,
+      hours: Number(row.hours),
+    }));
+    const avgHours = mapped.length
+      ? Number(
+          (
+            mapped.reduce((sum, row) => sum + row.hours, 0) / mapped.length
+          ).toFixed(1),
+        )
+      : null;
+
+    return { avgHours, rows: mapped };
+  }
+
+  /**
+   * Bookings per port yard. Import cargo enters at its origin yard, export
+   * cargo leaves from its destination yard — anything else is counted at origin.
+   */
+  getBookingsByPort(days: number): Promise<{ label: string; count: number }[]> {
+    return this.labelCounts(
+      `
+      SELECT y.label AS label, COUNT(*)::int AS count
+      FROM freight.bookings b
+      INNER JOIN freight.yards y
+        ON y.id = CASE WHEN b.trade_direction = 'EXPORT'
+                       THEN b.destination_yard_id ELSE b.origin_yard_id END
+      WHERE b.deleted_at IS NULL
+        AND (b.contract_kind IS NULL OR b.contract_kind <> 'GENERAL')
+        AND b.created_at >= NOW() - make_interval(days => $1::int)
+      GROUP BY 1
+      ORDER BY count DESC
+    `,
+      [days],
+    );
+  }
+
+  getBookingStatusByPort(days: number): Promise<MatrixCell[]> {
+    return this.matrix(
+      `
+      SELECT y.label AS "group", b.status AS series, COUNT(*)::int AS count
+      FROM freight.bookings b
+      INNER JOIN freight.yards y
+        ON y.id = CASE WHEN b.trade_direction = 'EXPORT'
+                       THEN b.destination_yard_id ELSE b.origin_yard_id END
+      WHERE b.deleted_at IS NULL
+        AND (b.contract_kind IS NULL OR b.contract_kind <> 'GENERAL')
+        AND b.created_at >= NOW() - make_interval(days => $1::int)
+      GROUP BY 1, 2
+      ORDER BY 1, 2
+    `,
+      [days],
+    );
+  }
+
+  /**
+   * Wagon fill and tonnage per scheduled train. Slots come from the train set's
+   * wagon list, the load from confirmed booking allocations against those slots.
+   */
+  async getTrainLoads(limit: number): Promise<TrainLoadRow[]> {
+    const rows = await this.sql.query<
+      {
+        scheduleId: string;
+        trainNumber: string;
+        date: string;
+        direction: string;
+        wagonsTotal: string;
+        wagonsAllocated: string;
+        tons: string;
+      }[]
+    >(
+      `
+      SELECT s.id AS "scheduleId",
+             COALESCE(s.train_number, s.reference, '—') AS "trainNumber",
+             to_char(s.scheduled_departure_date, 'YYYY-MM-DD') AS date,
+             COALESCE(s.direction, 'DOMESTIC') AS direction,
+             COALESCE(slots.total, 0)::int AS "wagonsTotal",
+             COALESCE(load.wagons, 0)::int AS "wagonsAllocated",
+             COALESCE(load.tons, 0)::float AS tons
+      FROM freight.train_schedules s
+      LEFT JOIN LATERAL (
+        SELECT COUNT(*)::int AS total
+        FROM freight.train_set_wagons tsw
+        WHERE tsw.train_set_id = s.train_set_id
+          AND tsw.deleted_at IS NULL
+      ) slots ON TRUE
+      LEFT JOIN LATERAL (
+        SELECT COUNT(DISTINCT wba.train_set_wagon_id)::int AS wagons,
+               COALESCE(SUM(wba.allocated_weight_tons), 0) AS tons
+        FROM freight.wagon_booking_allocations wba
+        INNER JOIN freight.train_set_wagons tsw ON tsw.id = wba.train_set_wagon_id
+        WHERE tsw.train_set_id = s.train_set_id
+          AND wba.deleted_at IS NULL
+          AND tsw.deleted_at IS NULL
+      ) load ON TRUE
+      WHERE s.deleted_at IS NULL
+        AND s.status <> 'DRAFT'
+      ORDER BY s.scheduled_departure_date DESC
+      LIMIT $1::int
+    `,
+      [limit],
+    );
+
+    return rows.map((row) => ({
+      scheduleId: row.scheduleId,
+      trainNumber: row.trainNumber,
+      date: row.date,
+      direction: row.direction,
+      wagonsTotal: Number(row.wagonsTotal),
+      wagonsAllocated: Number(row.wagonsAllocated),
+      tons: Number(row.tons),
+    }));
+  }
+
+  getBookingDocumentsByStatus(): Promise<{ status: string; count: number }[]> {
+    return this.statusCounts(`
+      SELECT status, COUNT(*)::int AS count
+      FROM freight.booking_document_review
+      WHERE deleted_at IS NULL
+      GROUP BY status
+      ORDER BY count DESC
+    `);
+  }
+
+  getContractDocumentsByStatus(): Promise<{ status: string; count: number }[]> {
+    return this.statusCounts(`
+      SELECT status, COUNT(*)::int AS count
+      FROM freight.contract_document_review
+      WHERE deleted_at IS NULL
+      GROUP BY status
+      ORDER BY count DESC
+    `);
+  }
+
+  getInvoicesByStatus(): Promise<{ status: string; count: number }[]> {
+    return this.statusCounts(`
+      SELECT status, COUNT(*)::int AS count
+      FROM freight.invoices
+      WHERE deleted_at IS NULL
+      GROUP BY status
+      ORDER BY count DESC
+    `);
+  }
+
+  getInvoicesByType(): Promise<{ label: string; count: number }[]> {
+    return this.labelCounts(`
+      SELECT COALESCE(type, 'Other') AS label, COUNT(*)::int AS count
+      FROM freight.invoices
+      WHERE deleted_at IS NULL
+      GROUP BY 1
+      ORDER BY count DESC
+    `);
+  }
+
+  /** Handover papers per mile, split into signed and awaiting signature. */
+  getHandoversByMile(): Promise<MatrixCell[]> {
+    return this.matrix(`
+      SELECT COALESCE(mile_type, 'Unknown') AS "group",
+             CASE WHEN signed_at IS NULL THEN 'PENDING' ELSE 'SIGNED' END AS series,
+             COUNT(*)::int AS count
+      FROM freight.booking_handovers
+      WHERE deleted_at IS NULL
+      GROUP BY 1, 2
+      ORDER BY 1, 2
+    `);
+  }
+
+  /** Company profiles per type × status — active, pending and suspended per trade role. */
+  getProfilesByTypeStatus(): Promise<MatrixCell[]> {
+    return this.matrix(`
+      SELECT type AS "group", status AS series, COUNT(*)::int AS count
+      FROM freight.company_profiles
+      WHERE deleted_at IS NULL
+      GROUP BY 1, 2
+      ORDER BY 1, 2
+    `);
+  }
 }
diff --git a/apps/edr-freight-api/src/modules/overview/overview.service.ts b/apps/edr-freight-api/src/modules/overview/overview.service.ts
index a10bb8816..71ab07bf2 100644
--- a/apps/edr-freight-api/src/modules/overview/overview.service.ts
+++ b/apps/edr-freight-api/src/modules/overview/overview.service.ts
@@ -9,8 +9,10 @@ import type { OverviewResponseDto } from './dto/overview-response.dto';
 import type {
   OverviewBillingTabDto,
   OverviewBookingsTabDto,
+  OverviewClearanceTabDto,
   OverviewContractsTabDto,
   OverviewCustomersTabDto,
+  OverviewFleetTabDto,
   OverviewOperationsTabDto,
   OverviewStaffTabDto,
 } from './dto/overview-tab-response.dto';
@@ -237,6 +239,9 @@ export class OverviewService {
       wagonStatusBreakdown,
       containerStatusBreakdown,
       cargoStatusBreakdown,
+      bookingsByPort,
+      bookingStatusByPort,
+      trainLoads,
     ] = await Promise.all([
       this.overviewRepository.getOperationsKpis(),
       this.overviewRepository.getDepartureTrend(days),
@@ -249,6 +254,9 @@ export class OverviewService {
       this.overviewRepository.getWagonStatusBreakdown(),
       this.overviewRepository.getContainerStatusBreakdown(),
       this.overviewRepository.getCargoStatusBreakdown(),
+      this.overviewRepository.getBookingsByPort(days),
+      this.overviewRepository.getBookingStatusByPort(days),
+      this.overviewRepository.getTrainLoads(8),
     ]);
 
     return {
@@ -263,6 +271,76 @@ export class OverviewService {
       wagonStatusBreakdown,
       containerStatusBreakdown,
       cargoStatusBreakdown,
+      bookingsByPort,
+      bookingStatusByPort,
+      trainLoads,
+      generatedAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Rolling stock in depth: wagons and locomotives crossed with type and yard,
+   * plus how fast each train set turns around. Feeds the operations and control
+   * centre dashboards.
+   */
+  async getFleetTab(
+    range: OverviewRangeQuery = '30d',
+  ): Promise<OverviewFleetTabDto> {
+    const days = OVERVIEW_RANGE_DAYS[range];
+
+    const [
+      wagonStatusBreakdown,
+      wagonStatusByType,
+      wagonStatusByYard,
+      locomotiveStatusBreakdown,
+      locomotivesByYard,
+      locomotivesByType,
+      turnaround,
+    ] = await Promise.all([
+      this.overviewRepository.getWagonStatusBreakdown(),
+      this.overviewRepository.getWagonStatusByType(),
+      this.overviewRepository.getWagonStatusByYard(),
+      this.overviewRepository.getLocomotiveStatusBreakdown(),
+      this.overviewRepository.getLocomotivesByYard(),
+      this.overviewRepository.getLocomotivesByType(),
+      this.overviewRepository.getTrainTurnaround(days, 8),
+    ]);
+
+    return {
+      wagonStatusBreakdown,
+      wagonStatusByType,
+      wagonStatusByYard,
+      locomotiveStatusBreakdown,
+      locomotivesByYard,
+      locomotivesByType,
+      avgTurnaroundHours: turnaround.avgHours,
+      turnaroundByTrain: turnaround.rows,
+      generatedAt: new Date().toISOString(),
+    };
+  }
+
+  /** Document and invoice queues — the GL desks' and marketing's work in progress. */
+  async getClearanceTab(): Promise<OverviewClearanceTabDto> {
+    const [
+      bookingDocumentsByStatus,
+      contractDocumentsByStatus,
+      invoicesByStatus,
+      invoicesByType,
+      handoversByMile,
+    ] = await Promise.all([
+      this.overviewRepository.getBookingDocumentsByStatus(),
+      this.overviewRepository.getContractDocumentsByStatus(),
+      this.overviewRepository.getInvoicesByStatus(),
+      this.overviewRepository.getInvoicesByType(),
+      this.overviewRepository.getHandoversByMile(),
+    ]);
+
+    return {
+      bookingDocumentsByStatus,
+      contractDocumentsByStatus,
+      invoicesByStatus,
+      invoicesByType,
+      handoversByMile,
       generatedAt: new Date().toISOString(),
     };
   }
@@ -273,19 +351,26 @@ export class OverviewService {
   ): Promise<OverviewCustomersTabDto> {
     const days = OVERVIEW_RANGE_DAYS[range];
 
-    const [kpis, customerGrowthTrend, customersByType, topCustomersByBookings] =
-      await Promise.all([
-        this.overviewRepository.getCustomerKpis(),
-        this.overviewRepository.getCustomerGrowthTrend(days),
-        this.overviewRepository.getCustomersByType(),
-        this.overviewRepository.getTopCustomersByBookings(8, dirs),
-      ]);
+    const [
+      kpis,
+      customerGrowthTrend,
+      customersByType,
+      topCustomersByBookings,
+      profilesByTypeStatus,
+    ] = await Promise.all([
+      this.overviewRepository.getCustomerKpis(),
+      this.overviewRepository.getCustomerGrowthTrend(days),
+      this.overviewRepository.getCustomersByType(),
+      this.overviewRepository.getTopCustomersByBookings(8, dirs),
+      this.overviewRepository.getProfilesByTypeStatus(),
+    ]);
 
     return {
       kpis,
       customerGrowthTrend,
       customersByType,
       topCustomersByBookings,
+      profilesByTypeStatus,
       generatedAt: new Date().toISOString(),
     };
   }
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/layouts/ClearanceOverview.tsx b/apps/edr-freight-web/backoffice/src/components/overview/layouts/ClearanceOverview.tsx
new file mode 100644
index 000000000..1484cb5e9
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/layouts/ClearanceOverview.tsx
@@ -0,0 +1,154 @@
+import { Grid, Stack } from "@mantine/core";
+
+import { OverviewDonutChart } from "@/components/overview/OverviewDonutChart";
+import { OverviewHorizontalBarChart } from "@/components/overview/OverviewHorizontalBarChart";
+import { OverviewStackedBarChart } from "@/components/overview/OverviewStackedBarChart";
+import { OverviewAttentionCard } from "@/components/overview/summary/OverviewAttentionCard";
+import { OverviewPipelineFunnel } from "@/components/overview/summary/OverviewPipelineFunnel";
+import {
+  useOverviewClearanceTab,
+  useOverviewOperationsTab,
+} from "@/hooks/useOverview";
+import {
+  AsyncBand,
+  Band,
+  DIRECTION_SERIES,
+  formatDayLabel,
+  labelsToDonut,
+  pivotMatrix,
+  toDonut,
+  type RoleOverviewProps,
+} from "./layout-kit";
+
+/**
+ * The GL desks (Ethiopia / Djibouti) work cargo through clearance: containers
+ * and cargo state first, the trains carrying them second, and the bookings
+ * waiting on a human third. Clearance-document counts are not aggregated by
+ * the overview API yet, so this stops at cargo state.
+ */
+export function ClearanceOverview({ data, range }: RoleOverviewProps) {
+  const ops = useOverviewOperationsTab(range, true);
+  const clearance = useOverviewClearanceTab(true);
+  const handovers = pivotMatrix(clearance.data?.handoversByMile);
+
+  return (
+    <Stack gap="xl" mt="xl">
+      {/* Work queue first: it is what a GL desk acts on, and it is the band
+          that always has rows even when no cargo is in the yard. */}
+      <Band index={1} title="Waiting on someone">
+        <Grid gap="md">
+          <Grid.Col span={{ base: 12, lg: 5 }}>
+            <OverviewAttentionCard
+              bookings={data.kpis.bookings}
+              contracts={data.kpis.contracts}
+              billing={data.kpis.billing}
+            />
+          </Grid.Col>
+          <Grid.Col span={{ base: 12, lg: 7 }}>
+            <OverviewPipelineFunnel data={data.bookingsByPipeline} />
+          </Grid.Col>
+        </Grid>
+      </Band>
+
+      <AsyncBand index={2} title="Documents & invoices" query={clearance}>
+        {(tab) => (
+          <Grid gap="md">
+            {/* Donuts stay at lg 4 — their legends ellipsise below ~300px. */}
+            <Grid.Col span={{ base: 12, lg: 4 }}>
+              <OverviewDonutChart
+                title="Booking documents"
+                data={toDonut(tab.bookingDocumentsByStatus)}
+                emptyMessage="No documents uploaded"
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, lg: 4 }}>
+              <OverviewDonutChart
+                title="Contract documents"
+                data={toDonut(tab.contractDocumentsByStatus)}
+                emptyMessage="No documents uploaded"
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, lg: 4 }}>
+              <OverviewDonutChart
+                title="Invoices by status"
+                data={toDonut(tab.invoicesByStatus)}
+                emptyMessage="No invoices raised"
+              />
+            </Grid.Col>
+            <Grid.Col span={12}>
+              <OverviewStackedBarChart
+                title="Handover papers"
+                data={handovers.rows}
+                series={handovers.series}
+                xKey="group"
+                emptyMessage="No handovers generated"
+              />
+            </Grid.Col>
+          </Grid>
+        )}
+      </AsyncBand>
+
+      <AsyncBand index={3} title="Cargo & containers" query={ops}>
+        {(tab) => (
+          <Grid gap="md">
+            <Grid.Col span={{ base: 12, md: 4 }}>
+              <OverviewDonutChart
+                title="Container status"
+                data={toDonut(tab.containerStatusBreakdown)}
+                emptyMessage="No containers tracked"
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, md: 4 }}>
+              <OverviewDonutChart
+                title="Containers by size"
+                data={labelsToDonut(tab.containersBySize)}
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, md: 4 }}>
+              <OverviewDonutChart
+                title="Cargo status"
+                data={toDonut(tab.cargoStatusBreakdown)}
+                emptyMessage="No cargo recorded"
+              />
+            </Grid.Col>
+            <Grid.Col span={12}>
+              <OverviewHorizontalBarChart
+                title="Cargo tonnage by type"
+                data={(tab.cargoTonnageByType ?? []).map((item) => ({
+                  label: item.label,
+                  value: item.tons,
+                }))}
+                valueLabel="Tons"
+                emptyMessage="No cargo recorded"
+              />
+            </Grid.Col>
+          </Grid>
+        )}
+      </AsyncBand>
+
+      <AsyncBand index={4} title="Train movement" query={ops}>
+        {(tab) => (
+          <Grid gap="md">
+            <Grid.Col span={{ base: 12, lg: 8 }}>
+              <OverviewStackedBarChart
+                title="Train departures by direction"
+                data={tab.departureTrend ?? []}
+                series={DIRECTION_SERIES}
+                formatXLabel={formatDayLabel}
+                emptyMessage="No scheduled departures in this period"
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, lg: 4 }}>
+              <OverviewDonutChart
+                title="Schedule status"
+                data={toDonut(tab.scheduleStatusBreakdown)}
+                emptyMessage="No train schedules yet"
+              />
+            </Grid.Col>
+          </Grid>
+        )}
+      </AsyncBand>
+
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/layouts/ExecutiveOverview.tsx b/apps/edr-freight-web/backoffice/src/components/overview/layouts/ExecutiveOverview.tsx
new file mode 100644
index 000000000..6b6e12fa2
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/layouts/ExecutiveOverview.tsx
@@ -0,0 +1,76 @@
+import { Grid, Stack } from "@mantine/core";
+
+import { OverviewActivityHeatmap } from "@/components/overview/summary/OverviewActivityHeatmap";
+import { OverviewAttentionCard } from "@/components/overview/summary/OverviewAttentionCard";
+import { OverviewNetworkCard } from "@/components/overview/summary/OverviewNetworkCard";
+import { OverviewPipelineFunnel } from "@/components/overview/summary/OverviewPipelineFunnel";
+import { OverviewRevenueMix } from "@/components/overview/summary/OverviewRevenueMix";
+import { OverviewRevenueVolumeChart } from "@/components/overview/summary/OverviewRevenueVolumeChart";
+import { OverviewSankeyFlow } from "@/components/overview/summary/OverviewSankeyFlow";
+import { Band, type RoleOverviewProps } from "./layout-kit";
+
+const RANGE_DAYS: Record<string, number> = { "7d": 7, "30d": 30, "90d": 90 };
+
+/**
+ * The default layout — money, attention, network, pipeline. Kept for the CEO,
+ * director and org-manager roles, and for anyone whose role has no dedicated
+ * dashboard (superadmin, IAM admins).
+ */
+export function ExecutiveOverview({ data, range }: RoleOverviewProps) {
+  return (
+    <Stack gap="xl" mt="xl">
+      {/* Band 1 — revenue & volume: growing, making money, pacing vs last period. */}
+      <Band index={1} title="Revenue & volume">
+        <Grid gap="md">
+          <Grid.Col span={{ base: 12, lg: 8 }}>
+            <OverviewRevenueVolumeChart
+              bookingTrend={data.bookingTrend}
+              paymentTrend={data.paymentTrend}
+              previousPaymentTrend={data.previousPaymentTrend}
+              rangeDays={RANGE_DAYS[range] ?? 30}
+            />
+          </Grid.Col>
+          <Grid.Col span={{ base: 12, lg: 4 }}>
+            <OverviewRevenueMix
+              byDirection={data.revenueByDirection}
+              byFreightType={data.revenueByFreightType}
+            />
+          </Grid.Col>
+        </Grid>
+      </Band>
+
+      {/* Band 2 — where the money runs, and what's waiting on someone. */}
+      <Band index={2} title="Money flow & attention">
+        <Grid gap="md">
+          <Grid.Col span={{ base: 12, lg: 7 }}>
+            <OverviewSankeyFlow flows={data.revenueFlows} />
+          </Grid.Col>
+          <Grid.Col span={{ base: 12, lg: 5 }}>
+            <OverviewAttentionCard
+              bookings={data.kpis.bookings}
+              contracts={data.kpis.contracts}
+              billing={data.kpis.billing}
+            />
+          </Grid.Col>
+        </Grid>
+      </Band>
+
+      {/* Band 3 — the network now, and when demand arrives. */}
+      <Band index={3} title="Network & rhythm">
+        <Grid gap="md">
+          <Grid.Col span={{ base: 12, lg: 5 }}>
+            <OverviewNetworkCard kpis={data.kpis.operations} />
+          </Grid.Col>
+          <Grid.Col span={{ base: 12, lg: 7 }}>
+            <OverviewActivityHeatmap cells={data.bookingHeatmap} />
+          </Grid.Col>
+        </Grid>
+      </Band>
+
+      {/* Band 4 — the booking pipeline, full width so every stage bar has room. */}
+      <Band index={4} title="Pipeline">
+        <OverviewPipelineFunnel data={data.bookingsByPipeline} />
+      </Band>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/layouts/FinanceOverview.tsx b/apps/edr-freight-web/backoffice/src/components/overview/layouts/FinanceOverview.tsx
new file mode 100644
index 000000000..78205d29b
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/layouts/FinanceOverview.tsx
@@ -0,0 +1,58 @@
+import { Grid, Stack } from "@mantine/core";
+
+import { OverviewBillingTabPanel } from "@/components/overview/tabs/OverviewBillingTabPanel";
+import { OverviewAttentionCard } from "@/components/overview/summary/OverviewAttentionCard";
+import { OverviewRevenueMix } from "@/components/overview/summary/OverviewRevenueMix";
+import { OverviewRevenueVolumeChart } from "@/components/overview/summary/OverviewRevenueVolumeChart";
+import { OverviewSankeyFlow } from "@/components/overview/summary/OverviewSankeyFlow";
+import { useOverviewBillingTab } from "@/hooks/useOverview";
+import { AsyncBand, Band, type RoleOverviewProps } from "./layout-kit";
+
+const RANGE_DAYS: Record<string, number> = { "7d": 7, "30d": 30, "90d": 90 };
+
+/** Money only: what was earned, how it was collected, and what is still owed. */
+export function FinanceOverview({ data, range }: RoleOverviewProps) {
+  const billing = useOverviewBillingTab(range, true);
+
+  return (
+    <Stack gap="xl" mt="xl">
+      <Band index={1} title="Revenue & volume">
+        <Grid gap="md">
+          <Grid.Col span={{ base: 12, lg: 8 }}>
+            <OverviewRevenueVolumeChart
+              bookingTrend={data.bookingTrend}
+              paymentTrend={data.paymentTrend}
+              previousPaymentTrend={data.previousPaymentTrend}
+              rangeDays={RANGE_DAYS[range] ?? 30}
+            />
+          </Grid.Col>
+          <Grid.Col span={{ base: 12, lg: 4 }}>
+            <OverviewRevenueMix
+              byDirection={data.revenueByDirection}
+              byFreightType={data.revenueByFreightType}
+            />
+          </Grid.Col>
+        </Grid>
+      </Band>
+
+      <AsyncBand index={2} title="Payments" query={billing}>
+        {(tab) => <OverviewBillingTabPanel data={tab} />}
+      </AsyncBand>
+
+      <Band index={3} title="Money flow & attention">
+        <Grid gap="md">
+          <Grid.Col span={{ base: 12, lg: 7 }}>
+            <OverviewSankeyFlow flows={data.revenueFlows} />
+          </Grid.Col>
+          <Grid.Col span={{ base: 12, lg: 5 }}>
+            <OverviewAttentionCard
+              bookings={data.kpis.bookings}
+              contracts={data.kpis.contracts}
+              billing={data.kpis.billing}
+            />
+          </Grid.Col>
+        </Grid>
+      </Band>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/layouts/MarketingOverview.tsx b/apps/edr-freight-web/backoffice/src/components/overview/layouts/MarketingOverview.tsx
new file mode 100644
index 000000000..892f351e6
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/layouts/MarketingOverview.tsx
@@ -0,0 +1,154 @@
+import { Grid, Stack } from "@mantine/core";
+
+import { OverviewDonutChart } from "@/components/overview/OverviewDonutChart";
+import { OverviewHorizontalBarChart } from "@/components/overview/OverviewHorizontalBarChart";
+import { OverviewStackedBarChart } from "@/components/overview/OverviewStackedBarChart";
+import { OverviewCustomersTabPanel } from "@/components/overview/tabs/OverviewCustomersTabPanel";
+import { OverviewPipelineFunnel } from "@/components/overview/summary/OverviewPipelineFunnel";
+import { OverviewRevenueMix } from "@/components/overview/summary/OverviewRevenueMix";
+import {
+  useOverviewClearanceTab,
+  useOverviewContractsTab,
+  useOverviewCustomersTab,
+  useOverviewOperationsTab,
+} from "@/hooks/useOverview";
+import { humanize } from "@/lib/format";
+import {
+  AsyncBand,
+  Band,
+  DIRECTION_SERIES,
+  enumLabelsToBars,
+  enumLabelsToDonut,
+  formatDayLabel,
+  pivotMatrix,
+  toDonut,
+  type RoleOverviewProps,
+} from "./layout-kit";
+
+/**
+ * Customer-facing view: who is buying, what they booked, what they signed and
+ * what it earned. Customs-declaration document counts and the Djibouti invoice
+ * queue are part of the marketing brief but have no overview aggregation yet.
+ */
+export function MarketingOverview({ data, range }: RoleOverviewProps) {
+  const customers = useOverviewCustomersTab(range, true);
+  const contracts = useOverviewContractsTab(range, true);
+  const ops = useOverviewOperationsTab(range, true);
+  const clearance = useOverviewClearanceTab(true);
+  const profilesByType = pivotMatrix(customers.data?.profilesByTypeStatus);
+
+  return (
+    <Stack gap="xl" mt="xl">
+      <AsyncBand index={1} title="Customers" query={customers}>
+        {(tab) => (
+          <Stack gap="md">
+            <OverviewCustomersTabPanel data={tab} />
+            {/* Statuses live on the profile, not the company — so active vs
+                pending vs suspended is only meaningful per trade role. */}
+            <OverviewStackedBarChart
+              title="Profiles by trade role and status"
+              data={profilesByType.rows}
+              series={profilesByType.series}
+              xKey="group"
+              formatXLabel={humanize}
+              emptyMessage="No customer profiles yet"
+            />
+          </Stack>
+        )}
+      </AsyncBand>
+
+      <Band index={2} title="Booking demand">
+        <Grid gap="md">
+          <Grid.Col span={{ base: 12, lg: 7 }}>
+            <OverviewPipelineFunnel data={data.bookingsByPipeline} />
+          </Grid.Col>
+          <Grid.Col span={{ base: 12, lg: 5 }}>
+            <OverviewDonutChart
+              title="Bookings by status"
+              data={toDonut(data.bookingsByStatus)}
+              emptyMessage="No bookings yet"
+            />
+          </Grid.Col>
+        </Grid>
+      </Band>
+
+      <AsyncBand index={3} title="Contracts" query={contracts}>
+        {(tab) => (
+          <Grid gap="md">
+            <Grid.Col span={{ base: 12, lg: 4 }}>
+              <OverviewDonutChart
+                title="Contracts by status"
+                data={toDonut(tab.contractsByStatus)}
+                emptyMessage="No contracts yet"
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, lg: 4 }}>
+              <OverviewDonutChart
+                title="Contracts by kind"
+                data={enumLabelsToDonut(tab.contractsByKind)}
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, lg: 4 }}>
+              <OverviewHorizontalBarChart
+                title="Contracts by freight type"
+                data={enumLabelsToBars(tab.contractsByFreightType)}
+                valueLabel="Contracts"
+              />
+            </Grid.Col>
+          </Grid>
+        )}
+      </AsyncBand>
+
+      <AsyncBand index={4} title="Documents & invoicing" query={clearance}>
+        {(tab) => (
+          <Grid gap="md">
+            <Grid.Col span={{ base: 12, md: 4 }}>
+              <OverviewDonutChart
+                title="Customs documents"
+                data={toDonut(tab.bookingDocumentsByStatus)}
+                emptyMessage="No documents uploaded"
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, md: 4 }}>
+              <OverviewDonutChart
+                title="Invoices by status"
+                data={toDonut(tab.invoicesByStatus)}
+                emptyMessage="No invoices raised"
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, md: 4 }}>
+              <OverviewHorizontalBarChart
+                title="Invoices by type"
+                data={enumLabelsToBars(tab.invoicesByType)}
+                valueLabel="Invoices"
+                emptyMessage="No invoices raised"
+              />
+            </Grid.Col>
+          </Grid>
+        )}
+      </AsyncBand>
+
+      <Band index={5} title="Revenue & movement">
+        <Grid gap="md">
+          <Grid.Col span={{ base: 12, lg: 4 }}>
+            <OverviewRevenueMix
+              byDirection={data.revenueByDirection}
+              byFreightType={data.revenueByFreightType}
+            />
+          </Grid.Col>
+          <Grid.Col span={{ base: 12, lg: 8 }}>
+            {ops.data ? (
+              <OverviewStackedBarChart
+                title="Train departures by direction"
+                data={ops.data.departureTrend ?? []}
+                series={DIRECTION_SERIES}
+                formatXLabel={formatDayLabel}
+                emptyMessage="No scheduled departures in this period"
+              />
+            ) : null}
+          </Grid.Col>
+        </Grid>
+      </Band>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/layouts/OccOverview.tsx b/apps/edr-freight-web/backoffice/src/components/overview/layouts/OccOverview.tsx
new file mode 100644
index 000000000..f30468c48
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/layouts/OccOverview.tsx
@@ -0,0 +1,181 @@
+import { CalendarClock, Send, Timer, Train, Truck } from "lucide-react";
+import { Grid, Stack } from "@mantine/core";
+
+import { OverviewDonutChart } from "@/components/overview/OverviewDonutChart";
+import { OverviewHorizontalBarChart } from "@/components/overview/OverviewHorizontalBarChart";
+import { OverviewKpiStrip } from "@/components/overview/OverviewKpiStrip";
+import { OverviewStackedBarChart } from "@/components/overview/OverviewStackedBarChart";
+import { useOverviewFleetTab, useOverviewOperationsTab } from "@/hooks/useOverview";
+import {
+  AsyncBand,
+  DIRECTION_SERIES,
+  formatDayLabel,
+  labelsToBars,
+  pivotMatrix,
+  sumCounts,
+  toDonut,
+  type RoleOverviewProps,
+} from "./layout-kit";
+
+/**
+ * Operation control centre view: what rolling stock sits where, and what is
+ * moving today. Locomotive availability per station and train turn-around are
+ * part of the OCC brief but have no overview aggregation yet — they are absent
+ * rather than approximated.
+ */
+export function OccOverview({ range }: RoleOverviewProps) {
+  const ops = useOverviewOperationsTab(range, true);
+  const fleet = useOverviewFleetTab(range, true);
+  const wagonsByYard = pivotMatrix(fleet.data?.wagonStatusByYard);
+  const locomotivesByYard = pivotMatrix(fleet.data?.locomotivesByYard);
+
+  return (
+    <Stack gap="xl" mt="xl">
+      <AsyncBand index={1} title="Network right now" query={ops}>
+        {(tab) => (
+          <Stack gap="md">
+            <OverviewKpiStrip
+              items={[
+                {
+                  label: "Active trains",
+                  value: tab.kpis?.trainsActive ?? 0,
+                  icon: Train,
+                  accent: "emerald",
+                },
+                {
+                  label: "Departures due",
+                  value: tab.kpis?.schedulesUpcoming ?? 0,
+                  icon: CalendarClock,
+                  accent: "sky",
+                },
+                {
+                  label: "Dispatched today",
+                  value: tab.kpis?.dispatchedToday ?? 0,
+                  icon: Send,
+                  accent: "amber",
+                },
+                // Labels stay short: five cells share ~1100px at 1440 wide,
+                // and a hint pushes the last two into truncation.
+                {
+                  label: "Wagons free",
+                  value: tab.kpis?.wagonsAvailable ?? 0,
+                  icon: Truck,
+                },
+                {
+                  label: "Turnaround",
+                  value:
+                    fleet.data?.avgTurnaroundHours != null
+                      ? `${fleet.data.avgTurnaroundHours}h`
+                      : "—",
+                  icon: Timer,
+                  accent: "violet",
+                },
+              ]}
+            />
+            {/* Yard and type are long-tailed lists — bars read better than
+                donuts, and the donuts stay at lg 4 so their legends fit. */}
+            <Grid gap="md">
+              <Grid.Col span={{ base: 12, lg: 7 }}>
+                {/* Per-yard status, not a plain per-yard count: the OCC needs to
+                    know which of the wagons standing at a yard can actually run. */}
+                <OverviewStackedBarChart
+                  title="Wagons by yard and status"
+                  data={wagonsByYard.rows}
+                  series={wagonsByYard.series}
+                  xKey="group"
+                  emptyMessage="No wagons positioned"
+                />
+              </Grid.Col>
+              <Grid.Col span={{ base: 12, lg: 5 }}>
+                <OverviewHorizontalBarChart
+                  title="Wagons by type"
+                  data={labelsToBars(tab.wagonsByType)}
+                  valueLabel="Wagons"
+                  emptyMessage="No wagons registered"
+                />
+              </Grid.Col>
+              <Grid.Col span={{ base: 12, lg: 4 }}>
+                <OverviewDonutChart
+                  title={`Wagon status (${sumCounts(tab.wagonStatusBreakdown)})`}
+                  data={toDonut(tab.wagonStatusBreakdown)}
+                  emptyMessage="No wagons registered"
+                />
+              </Grid.Col>
+              <Grid.Col span={{ base: 12, lg: 4 }}>
+                <OverviewDonutChart
+                  title="Train status"
+                  data={toDonut(tab.trainStatusBreakdown)}
+                  emptyMessage="No trains registered"
+                />
+              </Grid.Col>
+              <Grid.Col span={{ base: 12, lg: 4 }}>
+                <OverviewDonutChart
+                  title="Container status"
+                  data={toDonut(tab.containerStatusBreakdown)}
+                  emptyMessage="No containers tracked"
+                />
+              </Grid.Col>
+            </Grid>
+          </Stack>
+        )}
+      </AsyncBand>
+
+      <AsyncBand index={2} title="Locomotives" query={fleet}>
+        {(tab) => (
+          <Grid gap="md">
+            <Grid.Col span={{ base: 12, lg: 7 }}>
+              <OverviewStackedBarChart
+                title="Locomotives by station and status"
+                data={locomotivesByYard.rows}
+                series={locomotivesByYard.series}
+                xKey="group"
+                emptyMessage="No locomotives registered"
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, lg: 5 }}>
+              <OverviewDonutChart
+                title={`Locomotive status (${sumCounts(tab.locomotiveStatusBreakdown)})`}
+                data={toDonut(tab.locomotiveStatusBreakdown)}
+                emptyMessage="No locomotives registered"
+              />
+            </Grid.Col>
+            <Grid.Col span={12}>
+              <OverviewHorizontalBarChart
+                title="Turnaround per train set (departure to departure)"
+                data={(tab.turnaroundByTrain ?? []).map((row) => ({
+                  label: row.trainSet,
+                  value: row.hours,
+                }))}
+                valueLabel="Hours"
+                emptyMessage="No train set has two recorded departures in this period"
+              />
+            </Grid.Col>
+          </Grid>
+        )}
+      </AsyncBand>
+
+      <AsyncBand index={3} title="Train movement" query={ops}>
+        {(tab) => (
+          <Grid gap="md">
+            <Grid.Col span={{ base: 12, lg: 8 }}>
+              <OverviewStackedBarChart
+                title="Departures by direction"
+                data={tab.departureTrend ?? []}
+                series={DIRECTION_SERIES}
+                formatXLabel={formatDayLabel}
+                emptyMessage="No scheduled departures in this period"
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, lg: 4 }}>
+              <OverviewDonutChart
+                title="Schedule status"
+                data={toDonut(tab.scheduleStatusBreakdown)}
+                emptyMessage="No train schedules yet"
+              />
+            </Grid.Col>
+          </Grid>
+        )}
+      </AsyncBand>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/layouts/OperationsOverview.tsx b/apps/edr-freight-web/backoffice/src/components/overview/layouts/OperationsOverview.tsx
new file mode 100644
index 000000000..544def510
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/layouts/OperationsOverview.tsx
@@ -0,0 +1,181 @@
+import { CircleCheck, Link2, OctagonAlert, Truck, Wrench } from "lucide-react";
+import { Grid, Stack } from "@mantine/core";
+
+import { OverviewDonutChart } from "@/components/overview/OverviewDonutChart";
+import { OverviewHorizontalBarChart } from "@/components/overview/OverviewHorizontalBarChart";
+import { OverviewKpiStrip } from "@/components/overview/OverviewKpiStrip";
+import { OverviewStackedBarChart } from "@/components/overview/OverviewStackedBarChart";
+import { OverviewPipelineFunnel } from "@/components/overview/summary/OverviewPipelineFunnel";
+import { useOverviewFleetTab, useOverviewOperationsTab } from "@/hooks/useOverview";
+import { TrainLoadCard } from "./TrainLoadCard";
+import {
+  AsyncBand,
+  Band,
+  DIRECTION_SERIES,
+  countByStatus,
+  formatDayLabel,
+  labelsToBars,
+  labelsToDonut,
+  pivotMatrix,
+  sumCounts,
+  toDonut,
+  type RoleOverviewProps,
+} from "./layout-kit";
+
+/**
+ * Wagon fleet, booking demand and freight moved — the operations officer's
+ * three questions. Wagon counts come from the status breakdown rather than the
+ * headline KPI so every lifecycle state (including detained / out of service)
+ * is accounted for against the same total.
+ */
+export function OperationsOverview({ data, range }: RoleOverviewProps) {
+  const ops = useOverviewOperationsTab(range, true);
+  const fleet = useOverviewFleetTab(range, true);
+  const statusByType = pivotMatrix(fleet.data?.wagonStatusByType);
+  const bookingsByPort = pivotMatrix(ops.data?.bookingStatusByPort);
+
+  return (
+    <Stack gap="xl" mt="xl">
+      <AsyncBand index={1} title="Wagon fleet" query={ops}>
+        {(tab) => {
+          const wagons = tab.wagonStatusBreakdown ?? [];
+          const total = sumCounts(wagons);
+          const available = countByStatus(wagons, "AVAILABLE", "IMPORT_READY", "EXPORT_READY");
+          const assigned = countByStatus(wagons, "ASSIGNED");
+
+          return (
+            <Stack gap="md">
+              {/* Five cells fit a 1440px screen only without hints — the
+                  status donut below carries the same detail anyway. */}
+              <OverviewKpiStrip
+                items={[
+                  { label: "Total wagons", value: total, icon: Truck },
+                  {
+                    label: "Available",
+                    value: available,
+                    icon: CircleCheck,
+                    accent: "emerald",
+                  },
+                  { label: "Assigned", value: assigned, icon: Link2, accent: "sky" },
+                  {
+                    label: "Maintenance",
+                    value: countByStatus(wagons, "MAINTENANCE"),
+                    icon: Wrench,
+                    accent: "amber",
+                  },
+                  {
+                    label: "Detained / OOS",
+                    value: countByStatus(wagons, "DETAINED", "OUT_OF_SERVICE"),
+                    icon: OctagonAlert,
+                    accent: "rose",
+                  },
+                ]}
+              />
+              <Grid gap="md">
+                <Grid.Col span={{ base: 12, lg: 4 }}>
+                  <OverviewDonutChart
+                    title="Wagons by status"
+                    data={toDonut(wagons)}
+                    emptyMessage="No wagons registered"
+                  />
+                </Grid.Col>
+                <Grid.Col span={{ base: 12, lg: 8 }}>
+                  {/* Status per type answers "how many flat wagons can I use
+                      today", which the plain per-type count could not. */}
+                  <OverviewStackedBarChart
+                    title="Wagons by type and status"
+                    data={statusByType.rows}
+                    series={statusByType.series}
+                    xKey="group"
+                    emptyMessage="No wagons registered"
+                  />
+                </Grid.Col>
+                <Grid.Col span={12}>
+                  <OverviewHorizontalBarChart
+                    title="Wagons by yard"
+                    data={labelsToBars(tab.wagonsByYard)}
+                    valueLabel="Wagons"
+                  />
+                </Grid.Col>
+              </Grid>
+            </Stack>
+          );
+        }}
+      </AsyncBand>
+
+      <Band index={2} title="Booking demand">
+        <Grid gap="md">
+          <Grid.Col span={{ base: 12, lg: 7 }}>
+            <OverviewPipelineFunnel data={data.bookingsByPipeline} />
+          </Grid.Col>
+          <Grid.Col span={{ base: 12, lg: 5 }}>
+            <OverviewDonutChart
+              title="Bookings by status"
+              data={toDonut(data.bookingsByStatus)}
+              emptyMessage="No bookings yet"
+            />
+          </Grid.Col>
+        </Grid>
+      </Band>
+
+      <AsyncBand index={3} title="Freight moved" query={ops}>
+        {(tab) => (
+          <Grid gap="md">
+            <Grid.Col span={{ base: 12, lg: 8 }}>
+              <OverviewStackedBarChart
+                title="Train departures by direction"
+                data={tab.departureTrend ?? []}
+                series={DIRECTION_SERIES}
+                formatXLabel={formatDayLabel}
+                emptyMessage="No scheduled departures in this period"
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, lg: 4 }}>
+              <OverviewDonutChart
+                title="Train status"
+                data={toDonut(tab.trainStatusBreakdown)}
+                emptyMessage="No trains registered"
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, md: 6 }}>
+              <OverviewHorizontalBarChart
+                title="Cargo tonnage by type"
+                data={(tab.cargoTonnageByType ?? []).map((item) => ({
+                  label: item.label,
+                  value: item.tons,
+                }))}
+                valueLabel="Tons"
+                emptyMessage="No cargo recorded"
+              />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, md: 6 }}>
+              <OverviewDonutChart
+                title="Containers by size"
+                data={labelsToDonut(tab.containersBySize)}
+              />
+            </Grid.Col>
+          </Grid>
+        )}
+      </AsyncBand>
+
+      <AsyncBand index={4} title="Trains & ports" query={ops}>
+        {(tab) => (
+          <Grid gap="md">
+            <Grid.Col span={{ base: 12, lg: 7 }}>
+              <TrainLoadCard loads={tab.trainLoads ?? []} />
+            </Grid.Col>
+            <Grid.Col span={{ base: 12, lg: 5 }}>
+              <OverviewStackedBarChart
+                title="Bookings by port and status"
+                data={bookingsByPort.rows}
+                series={bookingsByPort.series}
+                xKey="group"
+                emptyMessage="No bookings in this period"
+              />
+            </Grid.Col>
+          </Grid>
+        )}
+      </AsyncBand>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/layouts/TrainLoadCard.tsx b/apps/edr-freight-web/backoffice/src/components/overview/layouts/TrainLoadCard.tsx
new file mode 100644
index 000000000..334b59624
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/layouts/TrainLoadCard.tsx
@@ -0,0 +1,74 @@
+import { TrainFront } from "lucide-react";
+import { Badge, Group, Progress, Stack, Text } from "@mantine/core";
+
+import { humanize } from "@/lib/format";
+import type { IOverviewTrainLoad } from "@/types/overview";
+import { SummaryCard } from "@/components/overview/summary/SummaryCard";
+
+const DIRECTION_COLOR: Record<string, string> = {
+  IMPORT: "blue",
+  EXPORT: "yellow",
+  DOMESTIC: "violet",
+};
+
+/**
+ * Wagon fill per scheduled train: the bar is allocated slots against the train
+ * set's own wagon count, so a short train at 100% reads as full rather than as
+ * a small number next to a big one.
+ */
+export function TrainLoadCard({ loads = [] }: { loads: IOverviewTrainLoad[] }) {
+  return (
+    <SummaryCard
+      icon={TrainFront}
+      accent="blue"
+      title="Wagons allocated per train"
+      subtitle="Slots filled and tonnage loaded"
+    >
+      {loads.length === 0 ? (
+        <Text size="sm" c="dimmed" ta="center" py="xl">
+          No scheduled trains
+        </Text>
+      ) : (
+        <Stack gap="sm">
+          {loads.map((load) => {
+            const percent = load.wagonsTotal
+              ? Math.round((load.wagonsAllocated / load.wagonsTotal) * 100)
+              : 0;
+            return (
+              <Stack key={load.scheduleId} gap={4}>
+                <Group justify="space-between" gap="xs" wrap="nowrap">
+                  <Group gap={8} wrap="nowrap" style={{ minWidth: 0 }}>
+                    <Text size="sm" fw={600} truncate>
+                      {load.trainNumber}
+                    </Text>
+                    <Badge
+                      size="xs"
+                      variant="light"
+                      color={DIRECTION_COLOR[load.direction] ?? "gray"}
+                      style={{ textTransform: "none" }}
+                    >
+                      {humanize(load.direction)}
+                    </Badge>
+                    <Text size="xs" c="dimmed">
+                      {load.date}
+                    </Text>
+                  </Group>
+                  <Text size="xs" c="dimmed" style={{ whiteSpace: "nowrap" }}>
+                    {load.wagonsAllocated}/{load.wagonsTotal} wagons ·{" "}
+                    {Math.round(load.tons).toLocaleString()} t
+                  </Text>
+                </Group>
+                <Progress
+                  value={percent}
+                  color={percent >= 90 ? "edr-green" : percent > 0 ? "yellow" : "gray"}
+                  size="sm"
+                  radius="xl"
+                />
+              </Stack>
+            );
+          })}
+        </Stack>
+      )}
+    </SummaryCard>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/layouts/layout-kit.tsx b/apps/edr-freight-web/backoffice/src/components/overview/layouts/layout-kit.tsx
new file mode 100644
index 000000000..421284689
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/layouts/layout-kit.tsx
@@ -0,0 +1,164 @@
+import type { ReactNode } from "react";
+import { AlertCircle } from "lucide-react";
+import { Alert, Skeleton, Stack, Text } from "@mantine/core";
+
+import { humanize } from "@/lib/format";
+import { overviewChartColors } from "@/components/overview/overview.styles";
+import type {
+  IOverviewDashboard,
+  IOverviewLabelCount,
+  IOverviewMatrixCell,
+  IOverviewStatusCount,
+  OverviewRange,
+} from "@/types/overview";
+
+/** Every role layout takes the same summary payload + the selected range. */
+export interface RoleOverviewProps {
+  data: IOverviewDashboard;
+  range: OverviewRange;
+}
+
+/** Uppercase section eyebrow — matches the WarehouseDashboardPage convention. */
+export function SectionTitle({ children }: { children: string }) {
+  return (
+    <Text fw={700} fz="sm" tt="uppercase" c="edr-muted" style={{ letterSpacing: 0.4 }}>
+      {children}
+    </Text>
+  );
+}
+
+/** One page band: eyebrow + content, with a staggered entrance by index. */
+export function Band({
+  index,
+  title,
+  children,
+}: {
+  index: number;
+  title: string;
+  children: ReactNode;
+}) {
+  return (
+    <Stack gap="sm" className="ov-band" style={{ animationDelay: `${index * 70}ms` }}>
+      <SectionTitle>{title}</SectionTitle>
+      {children}
+    </Stack>
+  );
+}
+
+/** Minimal shape of the react-query result a band consumes. */
+interface BandQuery<T> {
+  data?: T;
+  isLoading: boolean;
+  isError: boolean;
+}
+
+/**
+ * A band fed by one of the per-domain overview endpoints. Loading shows a
+ * skeleton, a failure degrades to an inline notice — a role dashboard stitches
+ * several endpoints together and one 403 (a role without that domain's
+ * permission) must not blank the whole page.
+ */
+export function AsyncBand<T>({
+  index,
+  title,
+  query,
+  children,
+}: {
+  index: number;
+  title: string;
+  query: BandQuery<T>;
+  children: (data: T) => ReactNode;
+}) {
+  return (
+    <Band index={index} title={title}>
+      {query.isLoading ? (
+        <Skeleton height={300} radius="lg" />
+      ) : query.isError || !query.data ? (
+        <Alert
+          icon={<AlertCircle size={16} />}
+          color="gray"
+          variant="light"
+          title={`${title} unavailable`}
+        >
+          This section could not be loaded for your account.
+        </Alert>
+      ) : (
+        children(query.data)
+      )}
+    </Band>
+  );
+}
+
+/** Fixed direction colors (CVD-validated pair + violet): color follows the entity. */
+export const DIRECTION_SERIES = [
+  { key: "exportCount", label: "Export", color: "#D98A0B" },
+  { key: "importCount", label: "Import", color: "#0369a1" },
+  { key: "domesticCount", label: "Domestic", color: "#7c3aed" },
+];
+
+export function formatDayLabel(date: string) {
+  return new Date(`${date}T00:00:00`).toLocaleDateString(undefined, {
+    month: "short",
+    day: "numeric",
+  });
+}
+
+export function sumCounts(items: IOverviewStatusCount[] = []) {
+  return items.reduce((sum, item) => sum + item.count, 0);
+}
+
+export function countByStatus(items: IOverviewStatusCount[] = [], ...statuses: string[]) {
+  return items
+    .filter((item) => statuses.includes(item.status))
+    .reduce((sum, item) => sum + item.count, 0);
+}
+
+/** Status breakdown → donut slices; statuses are enum keys, so humanize them. */
+export function toDonut(items: IOverviewStatusCount[] = []) {
+  return items.map((item) => ({ name: humanize(item.status), value: item.count }));
+}
+
+/** Label breakdown → donut slices. Labels are names (yards, sizes) — left verbatim. */
+export function labelsToDonut(items: IOverviewLabelCount[] = []) {
+  return items.map((item) => ({ name: item.label, value: item.count }));
+}
+
+export function labelsToBars(items: IOverviewLabelCount[] = []) {
+  return items.map((item) => ({ label: item.label, value: item.count }));
+}
+
+/**
+ * Matrix cells → the row/series shape OverviewStackedBarChart wants: one row
+ * per `group`, one series per distinct `series` value, colors fixed by the
+ * series' position so a status keeps its color across charts.
+ */
+export function pivotMatrix(cells: IOverviewMatrixCell[] = []) {
+  const seriesKeys = [...new Set(cells.map((cell) => cell.series))].sort();
+  const groups = [...new Set(cells.map((cell) => cell.group))];
+
+  const rows = groups.map((group) => {
+    const row: Record<string, string | number> = { group };
+    for (const key of seriesKeys) row[key] = 0;
+    for (const cell of cells) {
+      if (cell.group === group) row[cell.series] = cell.count;
+    }
+    return row;
+  });
+
+  const series = seriesKeys.map((key, index) => ({
+    key,
+    label: humanize(key),
+    color: overviewChartColors.pipeline[index % overviewChartColors.pipeline.length],
+  }));
+
+  return { rows, series };
+}
+
+/** Same, for breakdowns whose labels are enum values (ONE_TIME, BULK, …). */
+export function enumLabelsToDonut(items: IOverviewLabelCount[] = []) {
+  return items.map((item) => ({ name: humanize(item.label), value: item.count }));
+}
+
+export function enumLabelsToBars(items: IOverviewLabelCount[] = []) {
+  return items.map((item) => ({ label: humanize(item.label), value: item.count }));
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/role-dashboards.config.ts b/apps/edr-freight-web/backoffice/src/components/overview/role-dashboards.config.ts
new file mode 100644
index 000000000..509f17a3c
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/overview/role-dashboards.config.ts
@@ -0,0 +1,50 @@
+import type { AuthUser } from "@/auth/types";
+import { getPositionKeys } from "@/lib/permissions";
+
+/** One overview composition. Every backoffice user lands on exactly one of these. */
+export type OverviewLayoutKey =
+  | "executive"
+  | "operations"
+  | "occ"
+  | "marketing"
+  | "finance"
+  | "clearance";
+
+export const OVERVIEW_LAYOUT_LABEL: Record<OverviewLayoutKey, string> = {
+  executive: "Executive dashboard",
+  operations: "Operations dashboard",
+  occ: "Control centre dashboard",
+  marketing: "Marketing dashboard",
+  finance: "Finance dashboard",
+  clearance: "Clearance & logistics dashboard",
+};
+
+/**
+ * Role/position key → layout, in match priority order: a user holding several
+ * of these keys gets the first match, so the specific operational view wins
+ * over the broad executive one. Position keys are matched too because the IAM
+ * payload models the GL desks as positions (`ethiopian_gl`) on some accounts
+ * and as roles (`edr_gl_ethiopia`) on others — see `getPositionKeys`.
+ */
+const ROLE_LAYOUTS: Array<[key: string, layout: OverviewLayoutKey]> = [
+  ["edr_operations_officer", "operations"],
+  ["truck_machinery_chief", "operations"],
+  ["edr_line_staff", "occ"],
+  ["edr_gl_ethiopia", "clearance"],
+  ["edr_gl_djibouti", "clearance"],
+  ["ethiopian_gl", "clearance"],
+  ["djibouti_gl", "clearance"],
+  ["edr_marketing", "marketing"],
+  ["edr_finance", "finance"],
+  ["edr_director", "executive"],
+  ["edr_ceo", "executive"],
+  ["edr_org_manager", "executive"],
+];
+
+/** Unmapped roles (superadmin, IAM admins, new roles) keep the executive layout. */
+export function resolveOverviewLayout(
+  user: AuthUser | null | undefined,
+): OverviewLayoutKey {
+  const held = new Set(getPositionKeys(user));
+  return ROLE_LAYOUTS.find(([key]) => held.has(key))?.[1] ?? "executive";
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHero.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHero.tsx
index 5b7815eb0..4e0fcdc10 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHero.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHero.tsx
@@ -36,6 +36,8 @@ interface OverviewHeroProps {
   generatedAt?: string;
   onRefresh: () => void;
   isRefreshing?: boolean;
+  /** Name of the role-specific layout rendered below, e.g. "Operations dashboard". */
+  label?: string;
 }
 
 /**
@@ -49,6 +51,7 @@ export function OverviewHero({
   generatedAt,
   onRefresh,
   isRefreshing,
+  label,
 }: OverviewHeroProps) {
   const { user } = useAuth();
   const fullName = (user?.name?.en ?? user?.name?.am)?.trim();
@@ -97,6 +100,19 @@ export function OverviewHero({
             <Text c="rgba(255,255,255,0.75)" size="sm">
               {dateLabel}
             </Text>
+            {label ? (
+              <Badge
+                size="sm"
+                variant="light"
+                style={{
+                  background: "rgba(255,255,255,0.16)",
+                  color: "rgba(255,255,255,0.9)",
+                  textTransform: "none",
+                }}
+              >
+                {label}
+              </Badge>
+            ) : null}
             <Badge
               size="sm"
               variant="light"
diff --git a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHeroKpis.tsx b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHeroKpis.tsx
index fa250a817..e076b1f18 100644
--- a/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHeroKpis.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/overview/summary/OverviewHeroKpis.tsx
@@ -12,6 +12,16 @@ function formatCurrency(amount: number, currency: "ETB" | "USD") {
   }).format(amount);
 }
 
+/** Compact form ("ETB 58.6M") — the hero cell is too narrow for nine digits. */
+function formatCompactCurrency(amount: number, currency: "ETB" | "USD") {
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency,
+    notation: "compact",
+    maximumFractionDigits: 1,
+  }).format(amount);
+}
+
 /** Period-over-period % change, or undefined when there's no prior baseline to compare against. */
 function pctDelta(current: number, previous: number): number | undefined {
   if (previous === 0) return undefined;
@@ -40,7 +50,7 @@ export function OverviewHeroKpis({ kpis, current, previous, rangeLabel }: Overvi
       ? [
           {
             label: `Revenue (${rangeLabel})`,
-            value: <CountUp value={current.revenueEtb} format={(n) => formatCurrency(n, "ETB")} />,
+            value: <CountUp value={current.revenueEtb} format={(n) => formatCompactCurrency(n, "ETB")} />,
             hint: formatCurrency(current.revenueUsd, "USD"),
             icon: Banknote,
             color: "yellow",
diff --git a/apps/edr-freight-web/backoffice/src/components/page/KpiStrip.tsx b/apps/edr-freight-web/backoffice/src/components/page/KpiStrip.tsx
index 01a80db61..15e2f4425 100644
--- a/apps/edr-freight-web/backoffice/src/components/page/KpiStrip.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/page/KpiStrip.tsx
@@ -19,8 +19,8 @@ export interface KpiItem {
    */
   color?: string;
   /**
-   * Optional change vs a prior period, rendered as a ▲/▼ chip next to the value
-   * (green up, red down, muted zero). E.g. today's count minus yesterday's.
+   * Optional percent change vs a prior period, rendered as a tinted ▲/▼ pill
+   * next to the value (green up, red down; zero and null hidden).
    */
   delta?: number;
   /**
@@ -64,7 +64,9 @@ export function KpiStrip({ items, loading = false }: KpiStripProps) {
               key={item.label}
               {...(linkProps as Record<string, unknown>)}
               className={cn(
-                "flex flex-1 items-center gap-3 px-5 py-4",
+                // min-w-0 lets a crowded strip (five cells, long labels)
+                // truncate its labels instead of overflowing the card.
+                "flex min-w-0 flex-1 items-center gap-3 px-5 py-4",
                 index > 0 &&
                   "border-t border-edr-border sm:border-l sm:border-t-0",
                 item.href &&
@@ -115,7 +117,7 @@ export function KpiStrip({ items, loading = false }: KpiStripProps) {
                         }}
                       >
                         {item.delta > 0 ? "▲" : "▼"}
-                        {Math.abs(item.delta)}
+                        {Math.abs(item.delta)}%
                       </Text>
                     ) : null}
                   </div>
diff --git a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
index 1ee429bad..d1bd381b9 100644
--- a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
@@ -200,6 +200,8 @@ export const QUERY_KEYS = {
       ["overview", "billing", range ?? "30d"] as const,
     operationsTab: (range?: string) =>
       ["overview", "operations", range ?? "30d"] as const,
+    fleetTab: (range?: string) => ["overview", "fleet", range ?? "30d"] as const,
+    clearanceTab: () => ["overview", "clearance"] as const,
     customersTab: (range?: string) =>
       ["overview", "customers", range ?? "30d"] as const,
     staffTab: (range?: string) =>
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index ba74f3206..0989af525 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -139,6 +139,8 @@ export const URL_CONSTANTS = {
     CONTRACTS: "/overview/contracts",
     BILLING: "/overview/billing",
     OPERATIONS: "/overview/operations",
+    FLEET: "/overview/fleet",
+    CLEARANCE: "/overview/clearance",
     CUSTOMERS: "/overview/customers",
     STAFF: "/overview/staff",
   },
diff --git a/apps/edr-freight-web/backoffice/src/hooks/useOverview.ts b/apps/edr-freight-web/backoffice/src/hooks/useOverview.ts
index f46fe865f..7225ee5bc 100644
--- a/apps/edr-freight-web/backoffice/src/hooks/useOverview.ts
+++ b/apps/edr-freight-web/backoffice/src/hooks/useOverview.ts
@@ -43,6 +43,22 @@ export function useOverviewOperationsTab(range: OverviewRange, enabled: boolean)
   });
 }
 
+export function useOverviewFleetTab(range: OverviewRange, enabled: boolean) {
+  return useQuery({
+    queryKey: QUERY_KEYS.OVERVIEW.fleetTab(range),
+    queryFn: () => overviewService.getFleetTab(range),
+    enabled,
+  });
+}
+
+export function useOverviewClearanceTab(enabled: boolean) {
+  return useQuery({
+    queryKey: QUERY_KEYS.OVERVIEW.clearanceTab(),
+    queryFn: () => overviewService.getClearanceTab(),
+    enabled,
+  });
+}
+
 export function useOverviewCustomersTab(range: OverviewRange, enabled: boolean) {
   return useQuery({
     queryKey: QUERY_KEYS.OVERVIEW.customersTab(range),
diff --git a/apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewPage.tsx b/apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewPage.tsx
index aa29fa0cf..0d1f5a6e7 100644
--- a/apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewPage.tsx
@@ -1,44 +1,40 @@
-import { useState } from "react";
+import { useState, type ReactElement } from "react";
 import { AlertCircle } from "lucide-react";
-import { Alert, Button, Grid, Skeleton, Stack, Text } from "@mantine/core";
+import { Alert, Button, Skeleton, Stack } from "@mantine/core";
 import { useQueryClient } from "@tanstack/react-query";
 
+import { useAuth } from "@/auth/useAuth";
 import { PageContainer } from "@/components/page";
-import { OverviewActivityHeatmap } from "@/components/overview/summary/OverviewActivityHeatmap";
-import { OverviewAttentionCard } from "@/components/overview/summary/OverviewAttentionCard";
+import { ClearanceOverview } from "@/components/overview/layouts/ClearanceOverview";
+import { ExecutiveOverview } from "@/components/overview/layouts/ExecutiveOverview";
+import { FinanceOverview } from "@/components/overview/layouts/FinanceOverview";
+import { MarketingOverview } from "@/components/overview/layouts/MarketingOverview";
+import { OccOverview } from "@/components/overview/layouts/OccOverview";
+import { OperationsOverview } from "@/components/overview/layouts/OperationsOverview";
+import type { RoleOverviewProps } from "@/components/overview/layouts/layout-kit";
+import {
+  OVERVIEW_LAYOUT_LABEL,
+  resolveOverviewLayout,
+  type OverviewLayoutKey,
+} from "@/components/overview/role-dashboards.config";
 import { OverviewHero } from "@/components/overview/summary/OverviewHero";
 import { OverviewHeroKpis } from "@/components/overview/summary/OverviewHeroKpis";
-import { OverviewNetworkCard } from "@/components/overview/summary/OverviewNetworkCard";
-import { OverviewPipelineFunnel } from "@/components/overview/summary/OverviewPipelineFunnel";
-import { OverviewRevenueMix } from "@/components/overview/summary/OverviewRevenueMix";
-import { OverviewRevenueVolumeChart } from "@/components/overview/summary/OverviewRevenueVolumeChart";
-import { OverviewSankeyFlow } from "@/components/overview/summary/OverviewSankeyFlow";
 import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
 import { useOverview } from "@/hooks/useOverview";
 import type { OverviewRange } from "@/types/overview";
 import "@/components/overview/summary/overview-summary.css";
 
 const RANGE_LABEL: Record<OverviewRange, string> = { "7d": "7d", "30d": "30d", "90d": "90d" };
-const RANGE_DAYS: Record<OverviewRange, number> = { "7d": 7, "30d": 30, "90d": 90 };
 
-/** Uppercase section eyebrow — matches the WarehouseDashboardPage convention. */
-function SectionTitle({ children }: { children: string }) {
-  return (
-    <Text fw={700} fz="sm" tt="uppercase" c="edr-muted" style={{ letterSpacing: 0.4 }}>
-      {children}
-    </Text>
-  );
-}
-
-/** One page band: eyebrow + content, with a staggered entrance by index. */
-function Band({ index, title, children }: { index: number; title: string; children: React.ReactNode }) {
-  return (
-    <Stack gap="sm" className="ov-band" style={{ animationDelay: `${index * 70}ms` }}>
-      <SectionTitle>{title}</SectionTitle>
-      {children}
-    </Stack>
-  );
-}
+/** Which composition each role sees below the hero. */
+const LAYOUTS: Record<OverviewLayoutKey, (props: RoleOverviewProps) => ReactElement> = {
+  executive: ExecutiveOverview,
+  operations: OperationsOverview,
+  occ: OccOverview,
+  marketing: MarketingOverview,
+  finance: FinanceOverview,
+  clearance: ClearanceOverview,
+};
 
 function OverviewSkeleton() {
   return (
@@ -54,8 +50,14 @@ function OverviewSkeleton() {
 const OverviewPage = () => {
   const [range, setRange] = useState<OverviewRange>("30d");
   const queryClient = useQueryClient();
+  const { user } = useAuth();
   const { data, isLoading, isError, error, refetch, isFetching } = useOverview(range);
 
+  // Hero, range control and headline KPIs are role-neutral; everything below
+  // them is chosen by role key.
+  const layoutKey = resolveOverviewLayout(user);
+  const RoleLayout = LAYOUTS[layoutKey];
+
   const accessDenied =
     (error as { response?: { status?: number } } | null)?.response?.status === 403;
 
@@ -74,6 +76,7 @@ const OverviewPage = () => {
           generatedAt={data?.generatedAt}
           onRefresh={handleRefresh}
           isRefreshing={isFetching && !isLoading}
+          label={OVERVIEW_LAYOUT_LABEL[layoutKey]}
         />
         {data ? (
           <div style={{ marginTop: -52, paddingInline: 20, position: "relative" }}>
@@ -115,60 +118,7 @@ const OverviewPage = () => {
           <OverviewSkeleton />
         </Stack>
       ) : data ? (
-        <Stack gap="xl" mt="xl">
-          {/* Band 1 — revenue & volume: growing, making money, pacing vs last period. */}
-          <Band index={1} title="Revenue & volume">
-            <Grid gap="md">
-              <Grid.Col span={{ base: 12, lg: 8 }}>
-                <OverviewRevenueVolumeChart
-                  bookingTrend={data.bookingTrend}
-                  paymentTrend={data.paymentTrend}
-                  previousPaymentTrend={data.previousPaymentTrend}
-                  rangeDays={RANGE_DAYS[range]}
-                />
-              </Grid.Col>
-              <Grid.Col span={{ base: 12, lg: 4 }}>
-                <OverviewRevenueMix
-                  byDirection={data.revenueByDirection}
-                  byFreightType={data.revenueByFreightType}
-                />
-              </Grid.Col>
-            </Grid>
-          </Band>
-
-          {/* Band 2 — where the money runs, and what's waiting on someone. */}
-          <Band index={2} title="Money flow & attention">
-            <Grid gap="md">
-              <Grid.Col span={{ base: 12, lg: 7 }}>
-                <OverviewSankeyFlow flows={data.revenueFlows} />
-              </Grid.Col>
-              <Grid.Col span={{ base: 12, lg: 5 }}>
-                <OverviewAttentionCard
-                  bookings={data.kpis.bookings}
-                  contracts={data.kpis.contracts}
-                  billing={data.kpis.billing}
-                />
-              </Grid.Col>
-            </Grid>
-          </Band>
-
-          {/* Band 3 — the network now, and when demand arrives. */}
-          <Band index={3} title="Network & rhythm">
-            <Grid gap="md">
-              <Grid.Col span={{ base: 12, lg: 5 }}>
-                <OverviewNetworkCard kpis={data.kpis.operations} />
-              </Grid.Col>
-              <Grid.Col span={{ base: 12, lg: 7 }}>
-                <OverviewActivityHeatmap cells={data.bookingHeatmap} />
-              </Grid.Col>
-            </Grid>
-          </Band>
-
-          {/* Band 4 — the booking pipeline, full width so every stage bar has room. */}
-          <Band index={4} title="Pipeline">
-            <OverviewPipelineFunnel data={data.bookingsByPipeline} />
-          </Band>
-        </Stack>
+        <RoleLayout data={data} range={range} />
       ) : null}
     </PageContainer>
   );
diff --git a/apps/edr-freight-web/backoffice/src/services/overview.service.ts b/apps/edr-freight-web/backoffice/src/services/overview.service.ts
index 71e7fb671..9229b0b4f 100644
--- a/apps/edr-freight-web/backoffice/src/services/overview.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/overview.service.ts
@@ -4,9 +4,11 @@ import { URL_CONSTANTS } from "@/constants/URLS";
 import type {
   IOverviewBillingTab,
   IOverviewBookingsTab,
+  IOverviewClearanceTab,
   IOverviewContractsTab,
   IOverviewCustomersTab,
   IOverviewDashboard,
+  IOverviewFleetTab,
   IOverviewOperationsTab,
   IOverviewStaffTab,
   OverviewRange,
@@ -52,6 +54,19 @@ export const overviewService = {
     return unwrap(response);
   },
 
+  getFleetTab: async (range?: OverviewRange): Promise<IOverviewFleetTab> => {
+    const response = await client.get<IOverviewFleetTab>(O.FLEET, {
+      params: range ? { range } : undefined,
+    });
+    return unwrap(response);
+  },
+
+  /** Document + invoice queues; not range-scoped — these are open work items. */
+  getClearanceTab: async (): Promise<IOverviewClearanceTab> => {
+    const response = await client.get<IOverviewClearanceTab>(O.CLEARANCE);
+    return unwrap(response);
+  },
+
   getCustomersTab: async (range?: OverviewRange): Promise<IOverviewCustomersTab> => {
     const response = await client.get<IOverviewCustomersTab>(O.CUSTOMERS, {
       params: range ? { range } : undefined,
diff --git a/apps/edr-freight-web/backoffice/src/types/overview.ts b/apps/edr-freight-web/backoffice/src/types/overview.ts
index 38778da49..85cb5fa21 100644
--- a/apps/edr-freight-web/backoffice/src/types/overview.ts
+++ b/apps/edr-freight-web/backoffice/src/types/overview.ts
@@ -22,6 +22,11 @@ export type {
   IOverviewLabelCount,
   IOverviewPaymentMethodBreakdown,
   IOverviewCurrencyAmount,
+  IOverviewMatrixCell,
+  IOverviewTrainLoad,
+  IOverviewTurnaround,
+  IOverviewFleetTab,
+  IOverviewClearanceTab,
   IOverviewBookingsTab,
   IOverviewContractsTab,
   IOverviewBillingTab,
diff --git a/packages/types/src/freight/overview.ts b/packages/types/src/freight/overview.ts
index 4972db10d..ede6d6b04 100644
--- a/packages/types/src/freight/overview.ts
+++ b/packages/types/src/freight/overview.ts
@@ -218,6 +218,34 @@ export interface IOverviewTonnagePoint {
   tons: number;
 }
 
+/**
+ * One cell of a two-dimensional breakdown — `group` is the bucket on the
+ * category axis (wagon type, yard, port), `series` the stacked slice (status).
+ */
+export interface IOverviewMatrixCell {
+  group: string;
+  series: string;
+  count: number;
+}
+
+/** One scheduled train's wagon allocation and load against its own capacity. */
+export interface IOverviewTrainLoad {
+  scheduleId: string;
+  trainNumber: string;
+  /** Scheduled departure date, YYYY-MM-DD. */
+  date: string;
+  direction: string;
+  wagonsAllocated: number;
+  wagonsTotal: number;
+  tons: number;
+}
+
+/** Departure-to-departure gap for one train set, in hours. */
+export interface IOverviewTurnaround {
+  trainSet: string;
+  hours: number;
+}
+
 export interface IOverviewOperationsTab {
   kpis: IOverviewOperationsKpis;
   departureTrend: IOverviewDirectionTrendPoint[];
@@ -230,6 +258,36 @@ export interface IOverviewOperationsTab {
   wagonStatusBreakdown: IOverviewStatusCount[];
   containerStatusBreakdown: IOverviewStatusCount[];
   cargoStatusBreakdown: IOverviewStatusCount[];
+  /** Bookings per port yard (import → origin, export → destination). */
+  bookingsByPort: IOverviewLabelCount[];
+  /** Same ports, split by booking status. */
+  bookingStatusByPort: IOverviewMatrixCell[];
+  /** Recent/upcoming trains with their wagon fill and tonnage. */
+  trainLoads: IOverviewTrainLoad[];
+  generatedAt: string;
+}
+
+export interface IOverviewFleetTab {
+  wagonStatusBreakdown: IOverviewStatusCount[];
+  wagonStatusByType: IOverviewMatrixCell[];
+  wagonStatusByYard: IOverviewMatrixCell[];
+  locomotiveStatusBreakdown: IOverviewStatusCount[];
+  locomotivesByYard: IOverviewMatrixCell[];
+  locomotivesByType: IOverviewLabelCount[];
+  /** Mean departure-to-departure gap across all train sets, null when < 2 departures. */
+  avgTurnaroundHours: number | null;
+  turnaroundByTrain: IOverviewTurnaround[];
+  generatedAt: string;
+}
+
+/** Document and invoice queues the GL desks and marketing work through. */
+export interface IOverviewClearanceTab {
+  bookingDocumentsByStatus: IOverviewStatusCount[];
+  contractDocumentsByStatus: IOverviewStatusCount[];
+  invoicesByStatus: IOverviewStatusCount[];
+  invoicesByType: IOverviewLabelCount[];
+  /** Signed vs pending handover papers, per mile. */
+  handoversByMile: IOverviewMatrixCell[];
   generatedAt: string;
 }
 
@@ -238,6 +296,8 @@ export interface IOverviewCustomersTab {
   customerGrowthTrend: IOverviewTrendPoint[];
   customersByType: IOverviewLabelCount[];
   topCustomersByBookings: IOverviewLabelCount[];
+  /** Company profiles per type × status — active vs pending vs suspended. */
+  profilesByTypeStatus: IOverviewMatrixCell[];
   generatedAt: string;
 }
 

From b9ba830a0941e0b922ae20519b6a930339b08b75 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Thu, 13 Aug 2026 18:56:52 +0000
Subject: [PATCH 087/174] shipping line

---
 ...0000000000-ShippingLineInvoiceApprovals.ts |   78 +
 .../src/modules/billing/billing.service.ts    |   51 +-
 .../booking-lifecycle-notifier.service.ts     |   86 +-
 .../bookings/booking-transition.service.ts    |   65 +-
 .../resolve-shipping-line-contact.util.ts     |   33 +
 .../dto/complete-shipping-line-booking.dto.ts |   95 +-
 .../dto/shipping-line-credit.dto.ts           |   34 +
 .../shipping-line-invoice-approval.entity.ts  |   82 +
 ...ping-line-booking-completion.controller.ts |   58 +-
 ...hipping-line-booking-completion.service.ts |  442 ++++-
 .../shipping-line-bookings.service.ts         |   31 +-
 .../shipping-line-companies.controller.ts     |    7 +-
 .../shipping-line-companies.module.ts         |    4 +
 .../shipping-line-credits.controller.ts       |  157 ++
 .../shipping-line-credits.repository.ts       |   36 +-
 .../shipping-line-credits.service.spec.ts     |    8 +
 .../shipping-line-credits.service.ts          |  360 ++++
 ...pping-line-invoice-approvals.repository.ts |   51 +
 .../train-scheduling/booking-batch.service.ts |  224 ++-
 .../booking-notifier.service.ts               |   58 +-
 .../services/train-scheduling.service.ts      |   12 +-
 .../src/seed/freight-permissions.registry.ts  |   46 +
 apps/edr-freight-web/backoffice/src/App.tsx   |   11 +
 .../bookings/detail/BookingCargoCard.tsx      |   65 +-
 .../components/layout/sidebar-sections.tsx    |    7 +
 .../shipping-lines/CreditInvoiceActions.tsx   |  363 ++++
 .../backoffice/src/constants/QUERY_KEYS.ts    |   34 +
 .../backoffice/src/constants/URLS.ts          |   16 +
 .../backoffice/src/lib/permissions.ts         |    9 +
 .../src/pages/invoices/InvoicesPage.tsx       |   45 +-
 .../ShippingLineCreditInvoicesPanel.tsx       |  279 +++
 .../ShippingLineCreditsPage.tsx               |   65 +
 .../ShippingLineCreditsPanel.tsx              |  553 ++++++
 .../backoffice/src/services/api.ts            |  126 ++
 .../services/shippingLineCredits.service.ts   |  131 ++
 .../backoffice/src/types/booking.ts           |    4 +
 .../src/types/shippingLineCredit.ts           |   96 ++
 apps/edr-freight-web/portal/src/App.tsx       |   12 +
 .../src/pages/billing/InvoiceDetailPage.tsx   |   11 +-
 .../ShippingLineBookingDetailPage.tsx         |  411 ++++-
 .../ShippingLineBookingsPage.tsx              |   22 +-
 .../ShippingLineCompleteModal.tsx             |  372 ----
 .../ShippingLineCompletePage.tsx              | 1516 +++++++++++++++++
 .../shipping-line/ShippingLineHomePage.tsx    |  856 ++++++++--
 .../ShippingLineInvoicesPage.tsx              |  236 ++-
 .../portal/src/pages/shipping-line/index.ts   |    1 +
 .../portal/src/services/api.ts                |    3 +-
 .../shipping-line-bookings.service.ts         |  143 +-
 48 files changed, 6766 insertions(+), 639 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3530000000000-ShippingLineInvoiceApprovals.ts
 create mode 100644 apps/edr-freight-api/src/modules/notifications/resolve-shipping-line-contact.util.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/entities/shipping-line-invoice-approval.entity.ts
 create mode 100644 apps/edr-freight-api/src/modules/shipping-lines/shipping-line-invoice-approvals.repository.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/shipping-lines/CreditInvoiceActions.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCreditInvoicesPanel.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCreditsPage.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCreditsPanel.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/services/shippingLineCredits.service.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/types/shippingLineCredit.ts
 delete mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineCompleteModal.tsx
 create mode 100644 apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineCompletePage.tsx

diff --git a/apps/edr-freight-api/src/migrations/3530000000000-ShippingLineInvoiceApprovals.ts b/apps/edr-freight-api/src/migrations/3530000000000-ShippingLineInvoiceApprovals.ts
new file mode 100644
index 000000000..4183be8ff
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3530000000000-ShippingLineInvoiceApprovals.ts
@@ -0,0 +1,78 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Maker–checker for manual actions on shipping-line credit invoices.
+ *
+ * A shipping-line credit invoice is normally settled by the CBE webhook. Two
+ * manual paths exist for finance: recording an offline payment (MARK_PAID)
+ * and voiding an invoice raised in error (CANCEL, which releases its credits
+ * back to the unbilled pool). Both erase or move real debt, so neither is a
+ * single-person action: one permission raises the request, a different
+ * permission — held by a chief, and never the requester themselves — approves
+ * or rejects it. Rows are never deleted; decided requests are the audit trail.
+ *
+ * One PENDING row per invoice at a time (partial unique index): a second
+ * request while one is undecided is a coordination failure, not a workflow.
+ */
+export class ShippingLineInvoiceApprovals3530000000000
+  implements MigrationInterface
+{
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      DO $$ BEGIN
+        CREATE TYPE freight.shipping_line_invoice_approvals_action_enum
+          AS ENUM ('MARK_PAID', 'CANCEL');
+      EXCEPTION WHEN duplicate_object THEN NULL; END $$
+    `);
+
+    await queryRunner.query(`
+      DO $$ BEGIN
+        CREATE TYPE freight.shipping_line_invoice_approvals_status_enum
+          AS ENUM ('PENDING', 'APPROVED', 'REJECTED');
+      EXCEPTION WHEN duplicate_object THEN NULL; END $$
+    `);
+
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.shipping_line_invoice_approvals (
+        id uuid PRIMARY KEY DEFAULT uuid_generate_v4(),
+        invoice_id uuid NOT NULL REFERENCES freight.invoices (id),
+        action freight.shipping_line_invoice_approvals_action_enum NOT NULL,
+        status freight.shipping_line_invoice_approvals_status_enum NOT NULL DEFAULT 'PENDING',
+        requested_by uuid NOT NULL,
+        reason varchar(500) NOT NULL,
+        payment_reference varchar(255),
+        decided_by uuid,
+        decided_at timestamptz,
+        decision_note varchar(500),
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz
+      )
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_sl_invoice_approvals_invoice_status
+        ON freight.shipping_line_invoice_approvals (invoice_id, status)
+    `);
+
+    // The workflow invariant, enforced where it cannot race: at most one
+    // undecided request per invoice.
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS uq_sl_invoice_approvals_one_pending
+        ON freight.shipping_line_invoice_approvals (invoice_id)
+        WHERE status = 'PENDING' AND deleted_at IS NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DROP TABLE IF EXISTS freight.shipping_line_invoice_approvals`,
+    );
+    await queryRunner.query(
+      `DROP TYPE IF EXISTS freight.shipping_line_invoice_approvals_status_enum`,
+    );
+    await queryRunner.query(
+      `DROP TYPE IF EXISTS freight.shipping_line_invoice_approvals_action_enum`,
+    );
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 6752b37c1..bc79f8899 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -13,6 +13,9 @@ import { logCtx } from "@edr/api-common";
 import { DataSource, EntityManager, In } from "typeorm";
 
 import { Booking } from "../bookings/entities/booking.entity";
+// Entity-only import (no module edge): portal reads resolve shipping-line
+// payers straight off the table.
+import { ShippingLineCompany } from "../shipping-lines/entities/shipping-line-company.entity";
 import { EimsConfig } from "../../config/eims.config";
 import { CompaniesService } from "../companies/companies.service";
 import { FilesService } from "../files/files.service";
@@ -574,23 +577,61 @@ export class BillingService {
     });
   }
 
-  /** Invoices for the signed-in customer; empty when they have no company. */
+  /**
+   * Resolve a shipping-line company from the signed-in user (null for ordinary
+   * customers). Queried straight off the entity rather than through
+   * ShippingLineCompaniesService — that module already imports billing, so a
+   * service edge back would deepen the forwardRef cycle for one lookup.
+   */
+  private async resolveShippingLineCompanyId(
+    userId: string,
+  ): Promise<string | null> {
+    const line = await this.dataSource
+      .getRepository(ShippingLineCompany)
+      .findOne({ where: { userId } });
+    return line?.id ?? null;
+  }
+
+  /**
+   * Invoices for the signed-in portal user; empty when they have no company.
+   * A payer is either a customer company or a shipping line (enforced by the
+   * DB's single-payer check), so the two lookups cannot both match.
+   */
   async findForUser(
     userId: string,
     filter: { source?: string; sourceId?: string } = {},
   ): Promise<Invoice[]> {
     const companyId = await this.resolveCompanyId(userId);
-    return companyId ? this.findByCompany(companyId, filter) : [];
+    if (companyId) return this.findByCompany(companyId, filter);
+
+    const shippingLineCompanyId =
+      await this.resolveShippingLineCompanyId(userId);
+    if (!shippingLineCompanyId) return [];
+    return this.invoices.findAll({
+      where: {
+        shippingLineCompanyId,
+        ...(filter.source ? { source: filter.source } : {}),
+        ...(filter.sourceId ? { sourceId: filter.sourceId } : {}),
+      },
+      order: { createdAt: "DESC" },
+    });
   }
 
-  /** Company-scoped invoice detail (+ lines); 404 when not owned by the user. */
+  /** Payer-scoped invoice detail (+ lines); 404 when not owned by the user. */
   async findByIdForUser(
     id: string,
     userId: string,
   ): Promise<Invoice & { lines: InvoiceLine[] }> {
-    const companyId = await this.resolveCompanyId(userId);
     const invoice = await this.findById(id);
-    if (!companyId || invoice.companyId !== companyId) {
+    const ownedByCompany =
+      invoice.companyId != null &&
+      invoice.companyId === (await this.resolveCompanyId(userId));
+    const ownedByShippingLine =
+      !ownedByCompany &&
+      invoice.shippingLineCompanyId != null &&
+      invoice.shippingLineCompanyId ===
+        (await this.resolveShippingLineCompanyId(userId));
+    if (!ownedByCompany && !ownedByShippingLine) {
       throw new NotFoundException(`Invoice ${id} not found`);
     }
     return invoice;
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 eff15ec3d..01f0fd053 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
@@ -11,6 +11,7 @@ import { Booking } from './entities/booking.entity';
 import { NotificationsService } from '../notifications/notifications.service';
 import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
 import { resolveCompanyNotifyContact } from '../notifications/resolve-company-phone.util';
+import { resolveShippingLineNotifyTarget } from '../notifications/resolve-shipping-line-contact.util';
 import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
 
 /**
@@ -58,10 +59,16 @@ export class BookingLifecycleNotifierService {
     // Both channels come from the same resolver: the company row's own columns
     // are only half the story (see companyNotifyEmailExpr), and reading them off
     // the loaded entity silently dropped every mail to a company whose address
-    // lives in `attributes`.
-    const { phone, email } = b.companyId
-      ? await resolveCompanyNotifyContact(this.dataSource, b.companyId)
-      : { phone: null, email: null };
+    // lives in `attributes`. A shipping-line booking has NO company — its
+    // contact lives on the shipping_line_companies row itself.
+    const { phone, email } = b.shippingLineCompanyId
+      ? await resolveShippingLineNotifyTarget(
+          this.dataSource,
+          b.shippingLineCompanyId,
+        )
+      : b.companyId
+        ? await resolveCompanyNotifyContact(this.dataSource, b.companyId)
+        : { phone: null, email: null };
 
     if (phone) {
       try {
@@ -82,13 +89,44 @@ export class BookingLifecycleNotifierService {
     }
   }
 
-  /** Persist + push an in-app item to all portal users of the booking's company. */
+  /**
+   * Persist + push an in-app item to the booking's portal owner: every portal
+   * user of the company, or — for a shipping-line booking — the line's own
+   * account, deep-linked into the shipping-line app rather than the customer
+   * one (its routes live under /shipping-line/*).
+   */
   private inApp(
     b: Booking,
     title: string,
     body: string,
     overrides: Partial<NotifyInput> = {},
   ): void {
+    if (b.shippingLineCompanyId) {
+      void (async () => {
+        const { userId } = await resolveShippingLineNotifyTarget(
+          this.dataSource,
+          b.shippingLineCompanyId!,
+        );
+        if (!userId) return;
+        void this.inbox.notify({
+          recipients: { userIds: [userId] },
+          audience: NotificationAudience.PORTAL,
+          type: NotificationType.BOOKING_STATUS,
+          title,
+          body,
+          data: { bookingId: b.id, reference: b.reference },
+          ...overrides,
+          // After the spread: overrides carry customer links — the bell must
+          // land a shipping line on ITS booking page.
+          link: `/shipping-line/bookings/${b.id}`,
+        });
+      })().catch((err) =>
+        this.logger.warn(
+          `shipping-line inApp failed for ${this.ref(b)}: ${(err as Error).message}`,
+        ),
+      );
+      return;
+    }
     if (!b.companyId) return; // government/unlinked bookings have no portal users
     void this.inbox.notify({
       recipients: { companyId: b.companyId },
@@ -176,13 +214,23 @@ export class BookingLifecycleNotifierService {
 
   /** Document approval finalized → customer can proceed to request operation. */
   clearanceReady(b: Booking): void {
-    const msg =
-      `Document approval for booking ${b.reference} is finalized. ` +
-      `You can now proceed to request operation from the portal.`;
+    // A shipping line's next move is BOOKING (cargo + shipment day), not the
+    // customer's operation-request step — say so, or the message points at a
+    // flow their portal does not have.
+    const msg = b.shippingLineCompanyId
+      ? `Documents for booking ${b.reference} are approved. ` +
+        `You can now book your shipment — enter the cargo and shipment day from the portal.`
+      : `Document approval for booking ${b.reference} is finalized. ` +
+        `You can now proceed to request operation from the portal.`;
     void this.notifyContact(b, msg, 'DOCUMENT APPROVAL FINALIZED');
-    this.inApp(b, 'Document approval finalized', msg, {
-      type: NotificationType.CLEARANCE_DECISION,
-    });
+    this.inApp(
+      b,
+      b.shippingLineCompanyId
+        ? 'Documents approved — book your shipment'
+        : 'Document approval finalized',
+      msg,
+      { type: NotificationType.CLEARANCE_DECISION },
+    );
   }
 
   /** Intercity documents approved → booking waits in the ride-along pool. */
@@ -234,11 +282,19 @@ export class BookingLifecycleNotifierService {
 
   /** Operation accepted → invoice ready; await payment / booking window. */
   operationAccepted(b: Booking): void {
-    const msg =
-      `Your operation request for booking ${b.reference} has been accepted. ` +
-      `An invoice has been prepared — watch for the payment window to secure your slot.`;
+    // No invoice and no pay window for a shipping line — the charge sits on
+    // its credit account and the booking boards its dedicated train directly.
+    const msg = b.shippingLineCompanyId
+      ? `Your booking ${b.reference} has been accepted. The charge has been ` +
+        `recorded on your credit account and your shipment is being placed on its train.`
+      : `Your operation request for booking ${b.reference} has been accepted. ` +
+        `An invoice has been prepared — watch for the payment window to secure your slot.`;
     void this.notifyContact(b, msg, 'OPERATION ACCEPTED');
-    this.inApp(b, 'Operation request accepted', msg);
+    this.inApp(
+      b,
+      b.shippingLineCompanyId ? 'Booking accepted' : 'Operation request accepted',
+      msg,
+    );
   }
 
   /**
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
index 944e3db15..2f50d0f38 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
@@ -39,6 +39,8 @@ import { ClearanceWorkflowService } from '../contracts/clearance-workflow.servic
 import { ContractDocPhase } from '@edr/types';
 
 import { BookingInvoiceService } from "./booking-invoice.service";
+// Type-only: the DI edge stays event-based to keep the module graph acyclic.
+import type { ShippingLineBookingAcceptedPayload } from "../shipping-lines/shipping-line-credits.service";
 
 @Injectable()
 export class BookingTransitionService {
@@ -1012,7 +1014,14 @@ export class BookingTransitionService {
     // The customer's train pick only exists for export rail; it rides the
     // booking through the space checks below AND is persisted so the accept /
     // reserve path locks onto that train (pickExportSchedule honors it).
-    const requestedId = isExportTrain ? (requestedTrainScheduleId ?? null) : null;
+    // Shipping-line completions (bypassDayPool) pick among the line's own
+    // dedicated trains — already validated by the caller, so the pick is
+    // persisted here the same way an export pick is. Customer import/domestic
+    // bookings still never carry one (the batch engine assigns their train).
+    const requestedId =
+      isExportTrain || opts?.bypassDayPool
+        ? (requestedTrainScheduleId ?? null)
+        : null;
     // Export rail rides the exact train the customer picked — never an
     // auto-assigned one. Both portal flows (clearance + contract completion)
     // surface a picker, so a missing id is an invalid submission, not a
@@ -1216,10 +1225,22 @@ export class BookingTransitionService {
     // booking page correctly still showed it as not payable. The batch engine
     // issues it in `reserve` (SELECTED_FOR_BATCH), which is where the pay window
     // and the real deadline are created — matching the portal's `canPay` gate.
-    const invoice = await this.invoiceService.ensureInvoiceForBooking(booking);
-    this.logger.log(
-      `Generated draft invoice ${invoice.invoiceNumber} (${invoice.id}) for ${booking.reference}:${booking.id} — issued on batch selection`,
-    );
+    //
+    // Shipping-line bookings mint NO invoice at all: they have no company row
+    // to bill (the invoices FK requires one) and they pay on the credit ledger
+    // — the charge was recorded at completion, and Finance bills a batch of
+    // credits later through ShippingLineCreditsService.generateInvoice.
+    if (booking.shippingLineCompanyId) {
+      this.logger.log(
+        `Skipping invoice for shipping-line booking ${booking.reference}:${booking.id} — billed later from the credit ledger`,
+      );
+    } else {
+      const invoice =
+        await this.invoiceService.ensureInvoiceForBooking(booking);
+      this.logger.log(
+        `Generated draft invoice ${invoice.invoiceNumber} (${invoice.id}) for ${booking.reference}:${booking.id} — issued on batch selection`,
+      );
+    }
     // TODO: road (truck) orders are an incomplete feature — they stop at the
     // dead-end ROAD_DISPATCH_PENDING status below (no dispatch transition, no
     // per-km pricing wired via roadKmPrice, no pay surface in the portal). They
@@ -1233,6 +1254,7 @@ export class BookingTransitionService {
         lockedAt: booking.lockedAt ?? now,
       } as never);
       const roadFresh = await this.bookingsService.findById(booking.id);
+      this.emitShippingLineAccepted(roadFresh);
       this.notifier.operationAccepted(roadFresh);
       return roadFresh;
     }
@@ -1269,11 +1291,44 @@ export class BookingTransitionService {
     // batch runs after the window closes + staff document review, never at accept
     // time. (Legacy pre-migration schedules with no window phase are still served
     // by the periodic legacy fill.)
+    //
+    // EXCEPT shipping-line bookings: they pay later on the credit ledger, so
+    // no pay window exists to wait for — accept places them straight onto
+    // their company's dedicated train and its wagons. Non-fatal on purpose:
+    // the accept has committed; an allocation hiccup leaves the booking in
+    // the day pool for the batch engine / staff instead of failing the accept.
+    if (booking.shippingLineCompanyId) {
+      try {
+        await this.bookingBatchService.allocateShippingLineAccepted(booking.id);
+      } catch (err) {
+        this.logger.warn(
+          `Auto-allocation failed for shipping-line booking ${booking.reference}:${booking.id} — left in the day pool: ${(err as Error).message}`,
+        );
+      }
+    }
     const trainFresh = await this.bookingsService.findById(booking.id);
+    this.emitShippingLineAccepted(trainFresh);
     this.notifier.operationAccepted(trainFresh);
     return trainFresh;
   }
 
+  /**
+   * A shipping-line booking becomes debt at THIS moment — Operations accepted
+   * it — not at completion/pricing. Event, not a service call:
+   * ShippingLineCreditsService listens (`shipping_line_booking.accepted`), and
+   * importing its module here would close a module cycle. Emitted after the
+   * accept has fully committed (including the export-capacity path, which can
+   * still revert the status above), so a failed accept never creates debt.
+   */
+  private emitShippingLineAccepted(booking: Booking): void {
+    if (!booking.shippingLineCompanyId) return;
+    this.events.emit("shipping_line_booking.accepted", {
+      bookingId: booking.id,
+      reference: booking.reference,
+      amount: Number(booking.totalAmount),
+    } satisfies ShippingLineBookingAcceptedPayload);
+  }
+
   async enrichBookingResponse(booking: Booking): Promise<
     Booking & {
       latestChangeRequestNote?: string | null;
diff --git a/apps/edr-freight-api/src/modules/notifications/resolve-shipping-line-contact.util.ts b/apps/edr-freight-api/src/modules/notifications/resolve-shipping-line-contact.util.ts
new file mode 100644
index 000000000..d736cdf48
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/notifications/resolve-shipping-line-contact.util.ts
@@ -0,0 +1,33 @@
+import { DataSource } from "typeorm";
+
+import { ShippingLineCompany } from "../shipping-lines/entities/shipping-line-company.entity";
+
+/**
+ * Notification target for a shipping-line booking.
+ *
+ * A shipping line is NOT a `companies` row: the company IS the account — one
+ * IAM user (`userId`), and the contact details live on the
+ * `shipping_line_companies` row itself. So the customer resolvers
+ * (external_profiles fan-out, company attributes email) never apply; this is
+ * the one lookup every shipping-line notification routes through.
+ *
+ * Entity-only import — safe from any module graph: notifiers already own a
+ * DataSource and need no service from the shipping-lines module.
+ */
+export async function resolveShippingLineNotifyTarget(
+  dataSource: DataSource,
+  shippingLineCompanyId: string,
+): Promise<{
+  userId: string | null;
+  phone: string | null;
+  email: string | null;
+}> {
+  const line = await dataSource
+    .getRepository(ShippingLineCompany)
+    .findOne({ where: { id: shippingLineCompanyId } });
+  return {
+    userId: line?.userId ?? null,
+    phone: line?.phoneNumber ?? null,
+    email: line?.email ?? null,
+  };
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/dto/complete-shipping-line-booking.dto.ts b/apps/edr-freight-api/src/modules/shipping-lines/dto/complete-shipping-line-booking.dto.ts
index c46829841..90e31e42d 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/dto/complete-shipping-line-booking.dto.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/dto/complete-shipping-line-booking.dto.ts
@@ -2,6 +2,7 @@ import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
 import { Transform, Type } from "class-transformer";
 import {
   IsArray,
+  IsBoolean,
   IsDateString,
   IsIn,
   IsInt,
@@ -15,15 +16,61 @@ import {
 
 import { PAYMENT_CURRENCIES } from "../../contracts/dto/create-contract.dto";
 
+/**
+ * One physical container on a line — number, seal, VGM and its per-container
+ * handling switches. Same shape the customer shipment form submits.
+ */
+export class CompleteShippingLineContainerUnitDto {
+  @ApiProperty({ example: "MSCU1234567" })
+  @IsString()
+  containerNumber!: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  sealNumber?: string;
+
+  @ApiProperty({ minimum: 0, description: "VGM of this container, tons." })
+  @IsNumber()
+  @Min(0)
+  @Transform(({ value }) => Number(value))
+  vgmTons!: number;
+
+  @ApiPropertyOptional({ default: false })
+  @IsOptional()
+  @IsBoolean()
+  isHazardous?: boolean;
+
+  @ApiPropertyOptional({ default: false })
+  @IsOptional()
+  @IsBoolean()
+  isReefer?: boolean;
+}
+
 /**
  * One container line the shipping line ships — container type + count, the
- * same shape the customer one-time form collects (no per-unit ISO numbers;
- * those are captured downstream at yard operations, as for customers).
+ * same shape the customer one-time form collects. When `units` is sent (the
+ * full booking page), per-container numbers/seals/VGM and handling switches
+ * are persisted exactly like the customer shipment form; without it (legacy
+ * modal shape) the line-level counts stand alone.
  */
 export class CompleteShippingLineContainerLineDto {
-  @ApiProperty({ format: "uuid", description: "Container type being shipped." })
+  @ApiPropertyOptional({
+    format: "uuid",
+    description:
+      "Container type being shipped. Optional when containerSize is sent — the server resolves the type from the size.",
+  })
+  @IsOptional()
   @IsUUID()
-  containerTypeId!: string;
+  containerTypeId?: string;
+
+  @ApiPropertyOptional({
+    description:
+      'Container size, e.g. "20ft" | "40ft". The server maps it to the configured container type (reefer variant when the line carries reefer boxes) — so the client never needs the type catalog.',
+  })
+  @IsOptional()
+  @IsString()
+  containerSize?: string;
 
   @ApiProperty({ minimum: 1 })
   @IsInt()
@@ -51,6 +98,17 @@ export class CompleteShippingLineContainerLineDto {
   @Min(0)
   @Transform(({ value }) => Number(value))
   reeferQuantity?: number;
+
+  @ApiPropertyOptional({
+    type: [CompleteShippingLineContainerUnitDto],
+    description:
+      "Per-container details. When present, the handling counts and VGM are derived from these rows.",
+  })
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => CompleteShippingLineContainerUnitDto)
+  units?: CompleteShippingLineContainerUnitDto[];
 }
 
 /**
@@ -66,6 +124,15 @@ export class CompleteShippingLineBookingDto {
   @IsDateString()
   scheduledDate!: string;
 
+  @ApiPropertyOptional({
+    format: "uuid",
+    description:
+      "Which of the line's dedicated trains this booking rides. Required when more than one departs on the chosen day; implicit with a single departure.",
+  })
+  @IsOptional()
+  @IsUUID()
+  trainScheduleId?: string;
+
   @ApiPropertyOptional({ enum: PAYMENT_CURRENCIES })
   @IsOptional()
   @IsIn([...PAYMENT_CURRENCIES])
@@ -99,6 +166,26 @@ export class CompleteShippingLineBookingDto {
   @Transform(({ value }) => Number(value))
   cargoWeightTons?: number;
 
+  @ApiPropertyOptional({
+    minimum: 0,
+    description: "Bulk freight: hazardous portion of the cargo.",
+  })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Transform(({ value }) => Number(value))
+  bulkHazardousQuantity?: number;
+
+  @ApiPropertyOptional({
+    minimum: 0,
+    description: "Bulk freight: refrigerated portion of the cargo.",
+  })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Transform(({ value }) => Number(value))
+  bulkReeferQuantity?: number;
+
   @ApiPropertyOptional({ description: "What the containers carry." })
   @IsOptional()
   @IsString()
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/dto/shipping-line-credit.dto.ts b/apps/edr-freight-api/src/modules/shipping-lines/dto/shipping-line-credit.dto.ts
index 4e659e317..7ad524f01 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/dto/shipping-line-credit.dto.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/dto/shipping-line-credit.dto.ts
@@ -38,6 +38,40 @@ export class GenerateCreditInvoiceDto {
   dueInDays?: number;
 }
 
+/** Finance's request for a manual action on a credit invoice (maker step). */
+export class RequestInvoiceActionDto {
+  @ApiProperty({
+    description:
+      "Why the action is needed. Shown to the approver and kept for audit.",
+    example: "Paid by bank transfer, slip #TT-4491",
+  })
+  @IsString()
+  @MinLength(3)
+  @MaxLength(500)
+  reason!: string;
+
+  @ApiPropertyOptional({
+    description:
+      "Offline payment reference (bank slip / transfer number). MARK_PAID requests only.",
+    example: "TT-4491",
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  paymentReference?: string;
+}
+
+/** The decision on a pending request (approve and reject routes). */
+export class DecideInvoiceActionDto {
+  @ApiPropertyOptional({
+    description: "Decision note. Required when rejecting.",
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  note?: string;
+}
+
 /** Write-off of a single unbilled credit. */
 export class CancelCreditDto {
   @ApiProperty({
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/entities/shipping-line-invoice-approval.entity.ts b/apps/edr-freight-api/src/modules/shipping-lines/entities/shipping-line-invoice-approval.entity.ts
new file mode 100644
index 000000000..54ef7338d
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/entities/shipping-line-invoice-approval.entity.ts
@@ -0,0 +1,82 @@
+import { BaseEntity } from "@edr/api-common";
+import { Column, Entity, Index, JoinColumn, ManyToOne } from "typeorm";
+
+import { Invoice } from "../../billing/entities/invoice.entity";
+
+/** What finance asked to do to a shipping-line credit invoice. */
+export enum ShippingLineInvoiceActionType {
+  /** Record a full offline settlement (paid outside the gateway). */
+  MarkPaid = "MARK_PAID",
+  /** Void the invoice; its credits return to the unbilled pool. */
+  Cancel = "CANCEL",
+}
+
+export enum ShippingLineInvoiceActionStatus {
+  Pending = "PENDING",
+  Approved = "APPROVED",
+  Rejected = "REJECTED",
+}
+
+/**
+ * Maker–checker for manual actions on shipping-line credit invoices.
+ *
+ * Marking an invoice paid by hand erases real debt, and cancelling one
+ * releases its credits back to the unbilled pool — either done unilaterally is
+ * a one-person fraud path. So finance REQUESTS the action (one permission)
+ * and a chief APPROVES or REJECTS it (a separate permission, different
+ * person). Every request is kept, decided or not: the table is the audit
+ * trail of who asked, who decided, and why.
+ */
+@Entity({ schema: "freight", name: "shipping_line_invoice_approvals" })
+@Index(["invoiceId", "status"])
+export class ShippingLineInvoiceApproval extends BaseEntity {
+  @Column({ name: "invoice_id", type: "uuid" })
+  invoiceId!: string;
+
+  @ManyToOne(() => Invoice)
+  @JoinColumn({ name: "invoice_id" })
+  invoice?: Invoice;
+
+  @Column({ name: "action", type: "enum", enum: ShippingLineInvoiceActionType })
+  action!: ShippingLineInvoiceActionType;
+
+  @Column({
+    name: "status",
+    type: "enum",
+    enum: ShippingLineInvoiceActionStatus,
+    default: ShippingLineInvoiceActionStatus.Pending,
+  })
+  status!: ShippingLineInvoiceActionStatus;
+
+  /** IAM user id of the finance staff who raised the request. */
+  @Column({ name: "requested_by", type: "uuid" })
+  requestedBy!: string;
+
+  /** Why the action is needed; shown to the approver, kept for audit. */
+  @Column({ name: "reason", type: "varchar", length: 500 })
+  reason!: string;
+
+  /** Offline payment reference (bank slip no. etc.) for MARK_PAID requests. */
+  @Column({
+    name: "payment_reference",
+    type: "varchar",
+    length: 255,
+    nullable: true,
+  })
+  paymentReference?: string | null;
+
+  /** IAM user id of the chief who approved/rejected; null while pending. */
+  @Column({ name: "decided_by", type: "uuid", nullable: true })
+  decidedBy?: string | null;
+
+  @Column({ name: "decided_at", type: "timestamptz", nullable: true })
+  decidedAt?: Date | null;
+
+  @Column({
+    name: "decision_note",
+    type: "varchar",
+    length: 500,
+    nullable: true,
+  })
+  decisionNote?: string | null;
+}
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.controller.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.controller.ts
index 155988a09..b2417a08f 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.controller.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.controller.ts
@@ -1,5 +1,13 @@
 import { CurrentUser } from "@edr/api-common";
-import { Body, Controller, Get, Param, ParseUUIDPipe, Post } from "@nestjs/common";
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  ParseUUIDPipe,
+  Post,
+  Query,
+} from "@nestjs/common";
 import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
 
 import { PortalCustomer } from "../../common/booking-guards";
@@ -37,6 +45,54 @@ export class ShippingLineBookingCompletionController {
     return this.completionService.availableDaysMine(user.id, id);
   }
 
+  @Get(":id/trains")
+  @PortalCustomer()
+  @ApiOperation({
+    summary:
+      "The line's dedicated trains on the booking's lane for a shipment day, each with per-wagon-type free space — for the completion form's train picker. Cargo context (sizes/cargoTypeId/wagons) refines the availability.",
+  })
+  async trainsForDay(
+    @CurrentUser() user: CurrentIamUser,
+    @Param("id", ParseUUIDPipe) id: string,
+    @Query("date") date?: string,
+    @Query("sizes") sizes?: string,
+    @Query("cargoTypeId") cargoTypeId?: string,
+    @Query("wagons") wagons?: string,
+  ) {
+    return this.completionService.trainsForDayMine(user.id, id, date, {
+      containerSizes: sizes ? sizes.split(",").filter(Boolean) : undefined,
+      cargoTypeId: cargoTypeId || undefined,
+      wagons: wagons ? Number(wagons) : undefined,
+    });
+  }
+
+  @Post(":id/price-preview")
+  @PortalCustomer()
+  @ApiOperation({
+    summary:
+      "Authoritative price quote for the completion payload — same compute as /complete, saved as the booking's breakdown + rate snapshots (refreshed on every re-preview). Persists nothing else.",
+  })
+  async pricePreview(
+    @CurrentUser() user: CurrentIamUser,
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: CompleteShippingLineBookingDto,
+  ) {
+    return this.completionService.previewPriceMine(user.id, id, dto);
+  }
+
+  @Get(":id/operations")
+  @PortalCustomer()
+  @ApiOperation({
+    summary:
+      "Operations view of the booking: the train it rides (assigned or requested) and the wagons allocated to it.",
+  })
+  async operations(
+    @CurrentUser() user: CurrentIamUser,
+    @Param("id", ParseUUIDPipe) id: string,
+  ) {
+    return this.completionService.operationsMine(user.id, id);
+  }
+
   @Post(":id/complete")
   @PortalCustomer()
   @ApiOperation({
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.service.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.service.ts
index a7c938380..0f7be3f18 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.service.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.service.ts
@@ -11,12 +11,18 @@ import { BookingPricingService } from "../bookings/booking-pricing.service";
 import { BookingTransitionService } from "../bookings/booking-transition.service";
 import { BookingsService } from "../bookings/bookings.service";
 import { BookingContainer } from "../bookings/entities/booking-container.entity";
+import { BookingContainerUnit } from "../bookings/entities/booking-container-unit.entity";
 import { Booking } from "../bookings/entities/booking.entity";
 import { wagonsPerUnitForSize } from "../rule-engine/container-type.util";
 import { CargoType } from "../rule-engine/entities/cargo-type.entity";
 import { ContainerType } from "../rule-engine/entities/container-type.entity";
 import { eatDay } from "../train-scheduling/batch-window.util";
+import {
+  BookingBatchService,
+  type TrainOptionCargoOverrides,
+} from "../train-scheduling/booking-batch.service";
 import { TrainSchedule } from "../train-schedules/entities/train-schedule.entity";
+import { WagonBookingAllocation } from "../train-schedules/entities/wagon-booking-allocation.entity";
 import { TrainSchedulingService } from "../train-scheduling/services/train-scheduling.service";
 import { CompleteShippingLineBookingDto } from "./dto/complete-shipping-line-booking.dto";
 import {
@@ -49,6 +55,7 @@ export class ShippingLineBookingCompletionService {
     private readonly bookingPricingService: BookingPricingService,
     private readonly bookingTransitionService: BookingTransitionService,
     private readonly trainSchedulingService: TrainSchedulingService,
+    private readonly bookingBatchService: BookingBatchService,
     private readonly creditsService: ShippingLineCreditsService,
   ) {}
 
@@ -108,6 +115,28 @@ export class ShippingLineBookingCompletionService {
     return closesAt.getTime() > Date.now();
   }
 
+  /**
+   * The line's dedicated trains on the booking's lane for one shipment day,
+   * each with per-wagon-type free space — the completion form's train picker.
+   * A booking rides ONE schedule, so with several departures that day the
+   * line picks which; the pick is validated again at complete time.
+   */
+  async trainsForDayMine(
+    userId: string,
+    bookingId: string,
+    date: string | undefined,
+    overrides?: TrainOptionCargoOverrides,
+  ) {
+    const booking = await this.requireOwnBooking(userId, bookingId);
+    if (!booking.shippingLineCompanyId) return [];
+    return this.bookingBatchService.dedicatedTrainOptionsForDay(
+      booking,
+      date ? eatDay(new Date(date)) : null,
+      booking.shippingLineCompanyId,
+      overrides,
+    );
+  }
+
   /**
    * Days the shipping line may pick as the shipment day.
    *
@@ -174,12 +203,32 @@ export class ShippingLineBookingCompletionService {
       (s) => eatDay(s.scheduledDepartureDate) === pickedDay,
     );
     let bypassDayPool = false;
+    let requestedTrainScheduleId: string | null = null;
     if (dedicatedOnDay.length > 0) {
-      if (!dedicatedOnDay.some((s) => this.isStillOpen(s))) {
+      const openOnDay = dedicatedOnDay.filter((s) => this.isStillOpen(s));
+      if (openOnDay.length === 0) {
         throw new BadRequestException(
           "Booking for your train on this day has closed — the cut-off before departure has passed.",
         );
       }
+      // A booking rides ONE schedule. Several departures that day → the line
+      // must say which; a single one is picked implicitly. The id comes from
+      // the request, so it is validated against the day's own trains.
+      if (dto.trainScheduleId) {
+        const picked = openOnDay.find((s) => s.id === dto.trainScheduleId);
+        if (!picked) {
+          throw new BadRequestException(
+            "The selected train does not run your route on that day (or its booking cut-off has passed) — pick another train.",
+          );
+        }
+        requestedTrainScheduleId = picked.id;
+      } else if (openOnDay.length === 1) {
+        requestedTrainScheduleId = openOnDay[0].id;
+      } else {
+        throw new BadRequestException(
+          "More than one of your trains departs that day — select which train this booking rides.",
+        );
+      }
       // The day is backed by the line's own train, which every customer pool
       // deliberately excludes — so the day-pool gate downstream must not run.
       bypassDayPool = true;
@@ -260,14 +309,35 @@ export class ShippingLineBookingCompletionService {
           booking.freightType === "BULK" ? Number(dto.cargoWeightTons) : 0,
         bulkTotalWeightTons:
           booking.freightType === "BULK" ? Number(dto.cargoWeightTons) : null,
+        // Bulk handling portions — sized against the cargo, billed by pricing.
+        ...(booking.freightType === "BULK"
+          ? {
+              bulkHazardousQuantity: Number(dto.bulkHazardousQuantity ?? 0),
+              bulkReeferQuantity: Number(dto.bulkReeferQuantity ?? 0),
+            }
+          : {}),
         // Hazard is per-line for containers; the booking-level flag is what
         // pricing bills the surcharge from.
-        isHazardous: (dto.containers ?? []).some(
-          (line) => Number(line.hazardousQuantity ?? 0) > 0,
-        ),
-        // Completion fixes the cargo — and therefore the price — so it is also
-        // where the billing currency is chosen.
-        paymentCurrency: dto.paymentCurrency ?? booking.paymentCurrency,
+        isHazardous:
+          (dto.containers ?? []).some(
+            (line) =>
+              Number(line.hazardousQuantity ?? 0) > 0 ||
+              (line.units ?? []).some((u) => u.isHazardous),
+          ) || Number(dto.bulkHazardousQuantity ?? 0) > 0,
+        // Same for reefer: the rule engine's REEFER trigger fires on the
+        // booking-level flag (or a reefer container TYPE) — a ticked reefer
+        // switch on a standard box only sets the per-line count, so without
+        // this flag the surcharge silently never bills.
+        isReefer:
+          (dto.containers ?? []).some(
+            (line) =>
+              Number(line.reeferQuantity ?? 0) > 0 ||
+              (line.units ?? []).some((u) => u.isReefer),
+          ) || Number(dto.bulkReeferQuantity ?? 0) > 0,
+        // Shipping lines are always billed in ETB: the charge lands on the
+        // ETB credit ledger, so the currency is enforced here rather than
+        // trusted from the payload.
+        paymentCurrency: "ETB",
       } as never);
 
       const loaded = await this.bookingsRepository.findOne({
@@ -305,14 +375,10 @@ export class ShippingLineBookingCompletionService {
         computed.appliedModifiers,
       );
 
-      // The charge goes on the line's credit ledger ("use now, pay later") —
-      // idempotent per booking, so a retried completion cannot double the debt.
-      await this.creditsService.recordCredit({
-        bookingId,
-        amount: computed.totalAmount,
-        currency: computed.currency,
-        description: `Freight service — booking ${booking.reference}`,
-      });
+      // No credit is recorded here: completion only REQUESTS the operation.
+      // The charge lands on the line's ledger when Operations accepts —
+      // `shipping_line_booking.accepted` → ShippingLineCreditsService — so a
+      // request that is returned or never accepted creates no debt.
     }
 
     // Binding day, OPERATION_REQUEST_PENDING and the staff notification — the
@@ -321,11 +387,307 @@ export class ShippingLineBookingCompletionService {
     return this.bookingTransitionService.requestOperation(
       bookingId,
       dto.scheduledDate,
-      null,
+      requestedTrainScheduleId,
       bypassDayPool ? { bypassDayPool: true } : undefined,
     );
   }
 
+  /**
+   * Authoritative price preview for the completion form's confirm step: the
+   * SAME compute the completion itself runs, over an in-memory probe shaped
+   * exactly like completeMine would persist the booking — so the figure the
+   * shipping line confirms is line-for-line what it will owe.
+   *
+   * The result is not advisory-only: the breakdown is saved on the booking and
+   * the rate snapshots are (re)written, so every re-preview refreshes them.
+   * Nothing else is persisted — no cargo rows, no credit, no transition.
+   */
+  async previewPriceMine(
+    userId: string,
+    bookingId: string,
+    dto: CompleteShippingLineBookingDto,
+  ) {
+    const booking = await this.requireOwnBooking(userId, bookingId, {
+      bookingContainers: true,
+    });
+    if (
+      !["CLEARANCE_READY", "OPERATION_CHANGES_REQUESTED"].includes(
+        booking.status,
+      )
+    ) {
+      throw new BadRequestException(
+        "Your documents must be approved before the booking can be priced.",
+      );
+    }
+
+    // In-memory cargo, mirroring what completeMine persists.
+    let probeContainers: Partial<BookingContainer>[] = [];
+    let bulkFields: Record<string, unknown> = {};
+    if (booking.freightType === "CONTAINER") {
+      const lines = dto.containers ?? [];
+      if (!lines.length) {
+        throw new BadRequestException(
+          "At least one container line is required.",
+        );
+      }
+      for (const line of lines) {
+        const containerType = await this.resolveContainerType(line);
+        const figures = this.lineFigures(line);
+        probeContainers.push({
+          containerTypeId: containerType.id,
+          containerSize: containerType.sizeFt
+            ? `${containerType.sizeFt}ft`
+            : null,
+          quantity: line.quantity,
+          hazardousQuantity: figures.hazardous,
+          reeferQuantity: figures.reefer,
+          returnQuantity: 0,
+          vgmPerUnitTons: figures.vgmPerUnit,
+          totalVgmTons: figures.totalVgm,
+          wagonsRequired: Math.ceil(
+            line.quantity * wagonsPerUnitForSize(containerType.sizeFt),
+          ),
+        });
+      }
+    } else {
+      if (!dto.cargoTypeId || !(Number(dto.cargoWeightTons) > 0)) {
+        throw new BadRequestException(
+          "Bulk bookings need a cargo type and a total weight in tons.",
+        );
+      }
+      const cargoType = await this.bookingsRepository.manager
+        .getRepository(CargoType)
+        .findOne({ where: { id: dto.cargoTypeId, isActive: true } });
+      if (!cargoType) {
+        throw new NotFoundException(`Cargo type ${dto.cargoTypeId} not found`);
+      }
+      bulkFields = {
+        cargoTypeId: dto.cargoTypeId,
+        cargoTotalWeightVgm: Number(dto.cargoWeightTons),
+        bulkTotalWeightTons: Number(dto.cargoWeightTons),
+        bulkHazardousQuantity: Number(dto.bulkHazardousQuantity ?? 0),
+        bulkReeferQuantity: Number(dto.bulkReeferQuantity ?? 0),
+      };
+      probeContainers = [];
+    }
+
+    // Prototype-preserving clone so entity getters keep working — the same
+    // probe trick the contract preview uses.
+    const probe = Object.assign(
+      Object.create(Object.getPrototypeOf(booking)),
+      booking,
+      {
+        bookingContainers: probeContainers,
+        paymentCurrency: "ETB",
+        isHazardous:
+          (dto.containers ?? []).some(
+            (line) =>
+              Number(line.hazardousQuantity ?? 0) > 0 ||
+              (line.units ?? []).some((u) => u.isHazardous),
+          ) || Number(dto.bulkHazardousQuantity ?? 0) > 0,
+        // Mirrors completeMine: without the booking-level flag the engine's
+        // REEFER trigger never fires for reefer opt-ins on standard boxes,
+        // and the quote would show base freight only.
+        isReefer:
+          (dto.containers ?? []).some(
+            (line) =>
+              Number(line.reeferQuantity ?? 0) > 0 ||
+              (line.units ?? []).some((u) => u.isReefer),
+          ) || Number(dto.bulkReeferQuantity ?? 0) > 0,
+        ...bulkFields,
+      },
+    ) as Booking;
+
+    const computed =
+      await this.bookingPricingService.computePriceForBooking(probe);
+    if (!(computed.totalAmount > 0) || computed.hardBlocked.length > 0) {
+      throw new BadRequestException(
+        computed.hardBlocked.length > 0
+          ? computed.hardBlocked.join("; ")
+          : "No rate is configured for your shipping line on this route/cargo — please contact Operations.",
+      );
+    }
+
+    // Persist the quoted figure: breakdown on the booking, snapshots of the
+    // rates it was built from. createPricingSnapshots clears the previous
+    // artifacts first, so a re-preview replaces the old quote rather than
+    // stacking a second one.
+    await this.bookingsRepository.update(bookingId, {
+      pricingBreakdown: {
+        lineItems: computed.lineItems,
+        totalAmount: computed.totalAmount,
+        currency: computed.currency,
+        generatedAt: new Date().toISOString(),
+      },
+    } as never);
+    await this.bookingPricingService.createPricingSnapshots(
+      bookingId,
+      computed.usedRates,
+      computed.appliedModifiers,
+    );
+
+    return {
+      totalAmount: computed.totalAmount,
+      currency: computed.currency,
+      lineItems: computed.lineItems,
+      warnings: computed.warnings,
+    };
+  }
+
+  /**
+   * What operations has done with the booking so far: the train it rides
+   * (assigned, or the requested one before assignment) and the wagons the
+   * batch engine allocated to it, with any container numbers loaded per wagon.
+   * Read-only, owner-scoped — feeds the detail page's Wagons & Train tab.
+   */
+  async operationsMine(userId: string, bookingId: string) {
+    const booking = await this.requireOwnBooking(userId, bookingId);
+    const manager = this.bookingsRepository.manager;
+
+    const scheduleId =
+      booking.trainScheduleId ?? booking.requestedTrainScheduleId ?? null;
+    let train: Record<string, unknown> | null = null;
+    if (scheduleId) {
+      const schedule = await manager.getRepository(TrainSchedule).findOne({
+        where: { id: scheduleId },
+        relations: { originStation: true, destinationStation: true },
+      });
+      if (schedule) {
+        train = {
+          id: schedule.id,
+          reference: schedule.reference,
+          trainNumber: schedule.trainNumber,
+          status: schedule.status,
+          direction: schedule.direction,
+          scheduledDepartureDate: schedule.scheduledDepartureDate,
+          scheduledArrivalDate: schedule.scheduledArrivalDate,
+          originLabel:
+            schedule.originStation?.label ??
+            schedule.originStation?.code ??
+            "Origin",
+          destinationLabel:
+            schedule.destinationStation?.label ??
+            schedule.destinationStation?.code ??
+            "Destination",
+          // Whether this is the confirmed assignment or still the request.
+          assigned: Boolean(booking.trainScheduleId),
+        };
+      }
+    }
+
+    const allocations = await manager
+      .getRepository(WagonBookingAllocation)
+      .find({
+        where: { bookingId },
+        relations: {
+          trainSetWagon: { wagonType: true, physicalWagon: true },
+          containerItems: true,
+        },
+        order: { createdAt: "ASC" },
+      });
+
+    const wagons = allocations.map((allocation) => ({
+      id: allocation.id,
+      status: allocation.status,
+      loadType: allocation.loadType,
+      allocatedWeightTons: Number(allocation.allocatedWeightTons),
+      sequenceNo: allocation.trainSetWagon?.sequenceNo ?? null,
+      wagonNumber: allocation.trainSetWagon?.physicalWagon?.wagonNumber ?? null,
+      wagonType:
+        allocation.trainSetWagon?.wagonType?.name ??
+        allocation.trainSetWagon?.wagonType?.code ??
+        null,
+      capacityTons: Number(allocation.trainSetWagon?.capacityTons ?? 0),
+      containerNumbers: (allocation.containerItems ?? [])
+        .map((item) => item.containerNumber)
+        .filter((n): n is string => Boolean(n)),
+    }));
+
+    return { train, wagons };
+  }
+
+  /**
+   * Resolve a line's container type: by id when the payload carries one, else
+   * from the size string ("40ft" → the active 40ft type, preferring the reefer
+   * variant when the line ships reefer boxes). Resolution lives HERE, not in
+   * the portal, so a slow or failed catalog fetch can never block a booking
+   * with a phantom "type not configured" error — mirrors the customer flow's
+   * server-side size→type mapping.
+   */
+  private async resolveContainerType(line: {
+    containerTypeId?: string;
+    containerSize?: string;
+    reeferQuantity?: number;
+    units?: { isReefer?: boolean }[];
+  }): Promise<ContainerType> {
+    const containerTypeRepo =
+      this.bookingsRepository.manager.getRepository(ContainerType);
+
+    if (line.containerTypeId) {
+      const byId = await containerTypeRepo.findOne({
+        where: { id: line.containerTypeId, isActive: true },
+      });
+      if (!byId) {
+        throw new NotFoundException(
+          `Container type ${line.containerTypeId} not found`,
+        );
+      }
+      return byId;
+    }
+
+    const sizeFt = parseInt(line.containerSize ?? "", 10);
+    if (!Number.isFinite(sizeFt)) {
+      throw new BadRequestException(
+        "Each container line needs a containerTypeId or a containerSize.",
+      );
+    }
+    const candidates = await containerTypeRepo.find({
+      where: { isActive: true },
+    });
+    const ofSize = candidates.filter((ct) => Number(ct.sizeFt) === sizeFt);
+    if (!ofSize.length) {
+      throw new BadRequestException(
+        `No ${sizeFt}ft container type is configured — please contact Operations.`,
+      );
+    }
+    const wantsReefer =
+      Number(line.reeferQuantity ?? 0) > 0 ||
+      (line.units ?? []).some((u) => u.isReefer);
+    if (wantsReefer) {
+      const reefer = ofSize.find((ct) => ct.isReefer);
+      if (reefer) return reefer;
+    }
+    return ofSize.find((ct) => !ct.isReefer) ?? ofSize[0];
+  }
+
+  /**
+   * A line's derived figures. With per-container rows (the full booking page),
+   * counts and VGM come FROM the rows — each container's switches are the
+   * source of truth. Without them, the line-level figures stand alone.
+   */
+  private lineFigures(line: {
+    quantity: number;
+    vgmPerUnitTons?: number;
+    hazardousQuantity?: number;
+    reeferQuantity?: number;
+    units?: { vgmTons?: number; isHazardous?: boolean; isReefer?: boolean }[];
+  }) {
+    const units = line.units ?? [];
+    const hazardous = units.length
+      ? units.filter((u) => u.isHazardous).length
+      : Math.min(Number(line.hazardousQuantity ?? 0), line.quantity);
+    const reefer = units.length
+      ? units.filter((u) => u.isReefer).length
+      : Math.min(Number(line.reeferQuantity ?? 0), line.quantity);
+    const totalVgm = units.length
+      ? units.reduce((s, u) => s + Number(u.vgmTons ?? 0), 0)
+      : Number(line.vgmPerUnitTons ?? 0) * line.quantity;
+    const vgmPerUnit = units.length
+      ? totalVgm / units.length
+      : Number(line.vgmPerUnitTons ?? 0);
+    return { hazardous, reefer, totalVgm, vgmPerUnit };
+  }
+
   /**
    * Persist the container lines of a CONTAINER completion. Same row shape the
    * customer paths write (quantity per type, VGM totals, wagon share) — the
@@ -341,27 +703,18 @@ export class ShippingLineBookingCompletionService {
       throw new BadRequestException("At least one container line is required.");
     }
 
-    const containerTypeRepo =
-      this.bookingsRepository.manager.getRepository(ContainerType);
     const containerRepo =
       this.bookingsRepository.manager.getRepository(BookingContainer);
+    const unitRepo =
+      this.bookingsRepository.manager.getRepository(BookingContainerUnit);
 
     for (const line of lines) {
-      const containerType = await containerTypeRepo.findOne({
-        where: { id: line.containerTypeId, isActive: true },
-      });
-      if (!containerType) {
-        throw new NotFoundException(
-          `Container type ${line.containerTypeId} not found`,
-        );
-      }
-      const hazardous = Math.min(
-        Number(line.hazardousQuantity ?? 0),
-        line.quantity,
-      );
-      const reefer = Math.min(Number(line.reeferQuantity ?? 0), line.quantity);
-      const vgmPerUnit = Number(line.vgmPerUnitTons ?? 0);
-      await containerRepo.save(
+      const containerType = await this.resolveContainerType(line);
+      // Counts and VGM derived by lineFigures — the same math the price
+      // preview runs, so the persisted cargo always matches the quote.
+      const units = line.units ?? [];
+      const figures = this.lineFigures(line);
+      const containerRow = await containerRepo.save(
         containerRepo.create({
           bookingId: booking.id,
           containerTypeId: containerType.id,
@@ -369,16 +722,31 @@ export class ShippingLineBookingCompletionService {
             ? `${containerType.sizeFt}ft`
             : null,
           quantity: line.quantity,
-          hazardousQuantity: hazardous,
-          reeferQuantity: reefer,
+          hazardousQuantity: figures.hazardous,
+          reeferQuantity: figures.reefer,
           returnQuantity: 0,
-          vgmPerUnitTons: vgmPerUnit,
-          totalVgmTons: vgmPerUnit * line.quantity,
+          vgmPerUnitTons: figures.vgmPerUnit,
+          totalVgmTons: figures.totalVgm,
           wagonsRequired: Math.ceil(
             line.quantity * wagonsPerUnitForSize(containerType.sizeFt),
           ),
         }),
       );
+      let sortOrder = 0;
+      for (const unit of units) {
+        await unitRepo.save(
+          unitRepo.create({
+            bookingContainerId: containerRow.id,
+            containerNumber: unit.containerNumber.trim().toUpperCase(),
+            sealNumber: unit.sealNumber?.trim() || null,
+            vgmTons: Number(unit.vgmTons ?? 0),
+            isHazardous: unit.isHazardous ?? false,
+            isReefer: unit.isReefer ?? false,
+            isReturn: false,
+            sortOrder: sortOrder++,
+          }),
+        );
+      }
     }
   }
 
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.service.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.service.ts
index b9656807d..da1b90129 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.service.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-bookings.service.ts
@@ -319,8 +319,16 @@ export class ShippingLineBookingsService {
     const booking = await this.bookingsRepository.findOne({
       where: { id: bookingId, shippingLineCompanyId: shippingLine.id },
       // Yards are loaded so the portal can render the lane without a second
-      // lookup — they are set at initiate time from the chosen route.
-      relations: { originYard: true, destinationYard: true, serviceType: true },
+      // lookup — they are set at initiate time from the chosen route. Cargo
+      // (container lines + units, bulk cargo type) rides along for the detail
+      // page's cargo tab once the booking is completed.
+      relations: {
+        originYard: true,
+        destinationYard: true,
+        serviceType: true,
+        cargoType: true,
+        bookingContainers: { containerType: true, units: true },
+      },
     });
     if (!booking) throw new NotFoundException(`Booking ${bookingId} not found`);
 
@@ -330,7 +338,24 @@ export class ShippingLineBookingsService {
       .getRepository(BookingDocumentReview)
       .count({ where: { bookingId, status: "QUERIED" } });
 
-    return { ...booking, hasQueriedDocuments: queriedCount > 0 };
+    // The note Operations wrote when returning the request — the line has to
+    // read it to know what to fix. Only the latest CHANGES_REQUESTED note is
+    // exposed; the other review-note types are staff-internal.
+    const changeNote =
+      booking.status === "OPERATION_CHANGES_REQUESTED"
+        ? await this.bookingsRepository.manager
+            .getRepository(BookingReviewNote)
+            .findOne({
+              where: { bookingId, type: "CHANGES_REQUESTED" },
+              order: { createdAt: "DESC" },
+            })
+        : null;
+
+    return {
+      ...booking,
+      hasQueriedDocuments: queriedCount > 0,
+      operationChangeNote: changeNote?.note ?? null,
+    };
   }
 
   /**
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.controller.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.controller.ts
index 15ba673a3..3d11e2a29 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.controller.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.controller.ts
@@ -49,7 +49,12 @@ export class ShippingLineCompaniesController {
   }
 
   @Get()
-  @BookingStaff(FREIGHT_PERMS.shippingLines.view)
+  // OR'd: the credits view needs this list as its line picker, so holding
+  // shipping_line_credits:view alone is enough to read it.
+  @BookingStaff([
+    FREIGHT_PERMS.shippingLines.view,
+    FREIGHT_PERMS.shippingLineCredits.view,
+  ])
   @ApiOperation({ summary: "List shipping lines (paginated)" })
   async list(
     @Query("page") page?: string,
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts
index 698dfb384..888a996a6 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.module.ts
@@ -9,6 +9,8 @@ import { Booking } from "../bookings/entities/booking.entity";
 import { OtpModule } from "../otp/otp.module";
 import { ShippingLineCompany } from "./entities/shipping-line-company.entity";
 import { ShippingLineCredit } from "./entities/shipping-line-credit.entity";
+import { ShippingLineInvoiceApproval } from "./entities/shipping-line-invoice-approval.entity";
+import { ShippingLineInvoiceApprovalsRepository } from "./shipping-line-invoice-approvals.repository";
 import { ShippingLineBookingsController } from "./shipping-line-bookings.controller";
 import { ShippingLineBookingsService } from "./shipping-line-bookings.service";
 import { ShippingLineCompaniesController } from "./shipping-line-companies.controller";
@@ -25,6 +27,7 @@ import { ShippingLineCreditsService } from "./shipping-line-credits.service";
     TypeOrmModule.forFeature([
       ShippingLineCompany,
       ShippingLineCredit,
+      ShippingLineInvoiceApproval,
       User,
       Booking,
     ]),
@@ -48,6 +51,7 @@ import { ShippingLineCreditsService } from "./shipping-line-credits.service";
     ShippingLineBookingsService,
     ShippingLineCreditsService,
     ShippingLineCreditsRepository,
+    ShippingLineInvoiceApprovalsRepository,
   ],
   // Exported so whatever prices a shipping-line booking can record the charge.
   exports: [ShippingLineCompaniesService, ShippingLineCreditsService],
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.controller.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.controller.ts
index 2ac618afe..7a2c8418f 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.controller.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.controller.ts
@@ -1,4 +1,5 @@
 import { CurrentUser } from "@edr/api-common";
+import { Freight } from "@edr/types";
 import {
   Body,
   Controller,
@@ -14,9 +15,12 @@ import { BookingStaff, PortalCustomer } from "../../common/booking-guards";
 import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
 import {
   CancelCreditDto,
+  DecideInvoiceActionDto,
   GenerateCreditInvoiceDto,
+  RequestInvoiceActionDto,
 } from "./dto/shipping-line-credit.dto";
 import { ShippingLineCreditStatus } from "./entities/shipping-line-credit.entity";
+import { ShippingLineInvoiceActionType } from "./entities/shipping-line-invoice-approval.entity";
 import { ShippingLineCreditsService } from "./shipping-line-credits.service";
 
 interface CurrentIamUser {
@@ -37,6 +41,159 @@ interface CurrentIamUser {
 export class ShippingLineCreditsController {
   constructor(private readonly credits: ShippingLineCreditsService) {}
 
+  @Get()
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.view)
+  @ApiOperation({
+    summary:
+      "The whole credit ledger across every shipping line (paginated), optionally filtered by line and/or status.",
+  })
+  async listAll(
+    @Query("page") page?: string,
+    @Query("pageSize") pageSize?: string,
+    @Query("status") status?: ShippingLineCreditStatus,
+    @Query("shippingLineId", new ParseUUIDPipe({ optional: true }))
+    shippingLineId?: string,
+  ) {
+    return this.credits.listAll(
+      page ? Number(page) : 1,
+      pageSize ? Number(pageSize) : 20,
+      status,
+      shippingLineId,
+    );
+  }
+
+  // Declared before the parameterised staff routes so "summary" is never
+  // captured as a shipping-line id.
+  @Get("summary")
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.view)
+  @ApiOperation({
+    summary:
+      "Outstanding totals across every shipping line, or one line when shippingLineId is given.",
+  })
+  async summaryAll(
+    @Query("shippingLineId", new ParseUUIDPipe({ optional: true }))
+    shippingLineId?: string,
+  ) {
+    return this.credits.summary(shippingLineId);
+  }
+
+  // Declared before ":shippingLineId" so "invoices" is never captured as an id.
+  @Get("invoices")
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.view)
+  @ApiOperation({
+    summary:
+      "Credit invoices across every shipping line (paginated), each with any pending manual-action request.",
+  })
+  async listInvoices(
+    @Query("page") page?: string,
+    @Query("pageSize") pageSize?: string,
+    @Query("status") status?: string,
+    @Query("shippingLineId", new ParseUUIDPipe({ optional: true }))
+    shippingLineId?: string,
+  ) {
+    return this.credits.listCreditInvoices(
+      page ? Number(page) : 1,
+      pageSize ? Number(pageSize) : 20,
+      status as Freight.InvoiceStatus | undefined,
+      shippingLineId,
+    );
+  }
+
+  @Get("invoice-actions/pending")
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.view)
+  @ApiOperation({
+    summary:
+      "Undecided manual-action requests for a batch of invoices (one lookup for a list page).",
+  })
+  async pendingInvoiceActions(@Query("invoiceIds") invoiceIds?: string) {
+    const ids = (invoiceIds ?? "")
+      .split(",")
+      .map((id) => id.trim())
+      .filter(Boolean);
+    return this.credits.pendingInvoiceActions(ids);
+  }
+
+  // ── Maker–checker on credit invoices ──────────────────────────────────────
+  // Request and approve are DIFFERENT permissions, and the service refuses a
+  // decision by the requester — marking debt paid or voiding an invoice is
+  // never a one-person action.
+
+  @Post("invoices/:invoiceId/mark-paid-request")
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.invoiceMarkPaid)
+  @ApiOperation({
+    summary:
+      "Request recording a full offline payment against a credit invoice (awaits chief approval).",
+  })
+  async requestMarkPaid(
+    @Param("invoiceId", ParseUUIDPipe) invoiceId: string,
+    @Body() dto: RequestInvoiceActionDto,
+    @CurrentUser() user: CurrentIamUser,
+  ) {
+    return this.credits.requestInvoiceAction(
+      invoiceId,
+      ShippingLineInvoiceActionType.MarkPaid,
+      user.id,
+      dto.reason,
+      dto.paymentReference,
+    );
+  }
+
+  @Post("invoices/:invoiceId/cancel-request")
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.invoiceCancel)
+  @ApiOperation({
+    summary:
+      "Request voiding a credit invoice — its credits return to the unbilled pool (awaits chief approval).",
+  })
+  async requestCancel(
+    @Param("invoiceId", ParseUUIDPipe) invoiceId: string,
+    @Body() dto: RequestInvoiceActionDto,
+    @CurrentUser() user: CurrentIamUser,
+  ) {
+    return this.credits.requestInvoiceAction(
+      invoiceId,
+      ShippingLineInvoiceActionType.Cancel,
+      user.id,
+      dto.reason,
+    );
+  }
+
+  @Post("invoice-actions/:approvalId/approve")
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.invoiceApprove)
+  @ApiOperation({
+    summary:
+      "Approve a pending invoice request — executes the offline settlement or the cancellation.",
+  })
+  async approveInvoiceAction(
+    @Param("approvalId", ParseUUIDPipe) approvalId: string,
+    @Body() dto: DecideInvoiceActionDto,
+    @CurrentUser() user: CurrentIamUser,
+  ) {
+    return this.credits.decideInvoiceAction(
+      approvalId,
+      user.id,
+      true,
+      dto.note,
+    );
+  }
+
+  @Post("invoice-actions/:approvalId/reject")
+  @BookingStaff(FREIGHT_PERMS.shippingLineCredits.invoiceReject)
+  @ApiOperation({
+    summary: "Reject a pending invoice request — nothing is changed.",
+  })
+  async rejectInvoiceAction(
+    @Param("approvalId", ParseUUIDPipe) approvalId: string,
+    @Body() dto: DecideInvoiceActionDto,
+    @CurrentUser() user: CurrentIamUser,
+  ) {
+    return this.credits.decideInvoiceAction(
+      approvalId,
+      user.id,
+      false,
+      dto.note,
+    );
+  }
+
   // Declared before the parameterised staff routes so "me" is never captured
   // as a shipping-line id.
   @Get("me")
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.repository.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.repository.ts
index fac89e0df..f1413cbaf 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.repository.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.repository.ts
@@ -76,25 +76,32 @@ export class ShippingLineCreditsRepository extends BaseRepository<ShippingLineCr
 
   /**
    * Derived debt — never a stored column. Grouped in one query so the detail
-   * page does not fan out per status.
+   * page does not fan out per status. Without a line id it totals every line —
+   * the back-office overview figure.
    */
   async outstandingFor(
-    shippingLineCompanyId: string,
+    shippingLineCompanyId?: string,
   ): Promise<OutstandingTotals> {
-    const rows = await this.credits
+    const qb = this.credits
       .createQueryBuilder("credit")
       .select("credit.status", "status")
       .addSelect("COALESCE(SUM(credit.amount), 0)", "amount")
       .addSelect("COUNT(*)", "count")
-      .where("credit.shippingLineCompanyId = :shippingLineCompanyId", {
-        shippingLineCompanyId,
-      })
-      .andWhere("credit.status IN (:...statuses)", {
+      .where("credit.status IN (:...statuses)", {
         statuses: [...OUTSTANDING_CREDIT_STATUSES],
       })
       .andWhere("credit.deletedAt IS NULL")
-      .groupBy("credit.status")
-      .getRawMany<{ status: string; amount: string; count: string }>();
+      .groupBy("credit.status");
+    if (shippingLineCompanyId) {
+      qb.andWhere("credit.shippingLineCompanyId = :shippingLineCompanyId", {
+        shippingLineCompanyId,
+      });
+    }
+    const rows = await qb.getRawMany<{
+      status: string;
+      amount: string;
+      count: string;
+    }>();
 
     const totals = (status: ShippingLineCreditStatus) => {
       const row = rows.find((r) => r.status === status);
@@ -117,19 +124,22 @@ export class ShippingLineCreditsRepository extends BaseRepository<ShippingLineCr
     };
   }
 
-  /** Paginated ledger for one line — every credit, whatever its status. */
+  /**
+   * Paginated ledger — every credit, whatever its status. Scoped to one line
+   * when an id is given, across all lines otherwise.
+   */
   findAllPaginated(
-    shippingLineCompanyId: string,
+    shippingLineCompanyId: string | undefined,
     skip: number,
     take: number,
     status?: ShippingLineCreditStatus,
   ): Promise<[ShippingLineCredit[], number]> {
     return this.credits.findAndCount({
       where: {
-        shippingLineCompanyId,
+        ...(shippingLineCompanyId ? { shippingLineCompanyId } : {}),
         ...(status ? { status } : {}),
       },
-      relations: { booking: true, invoice: true },
+      relations: { booking: true, invoice: true, shippingLineCompany: true },
       order: { createdAt: "DESC" },
       skip,
       take,
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.spec.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.spec.ts
index 0348d08bd..43e0b5c40 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.spec.ts
@@ -77,6 +77,14 @@ describe("ShippingLineCreditsService", () => {
     service = new ShippingLineCreditsService(
       dataSource as never,
       creditsRepo as never,
+      // Approvals repo — only the invoice maker–checker paths touch it.
+      {
+        findPendingByInvoice: jest.fn(),
+        findPendingByInvoiceIds: jest.fn().mockResolvedValue([]),
+        findByIdForUpdate: jest.fn(),
+        create: jest.fn(),
+        update: jest.fn(),
+      } as never,
       billing as never,
       shippingLines as never,
     );
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.ts
index 4241a796f..2fffc4c2e 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-credits.service.ts
@@ -21,7 +21,14 @@ import {
   ShippingLineCredit,
   ShippingLineCreditStatus,
 } from "./entities/shipping-line-credit.entity";
+import {
+  ShippingLineInvoiceApproval,
+  ShippingLineInvoiceActionStatus,
+  ShippingLineInvoiceActionType,
+} from "./entities/shipping-line-invoice-approval.entity";
 import { ShippingLineCreditsRepository } from "./shipping-line-credits.repository";
+import { ShippingLineInvoiceApprovalsRepository } from "./shipping-line-invoice-approvals.repository";
+import { ShippingLineCompany } from "./entities/shipping-line-company.entity";
 import { ShippingLineCompaniesService } from "./shipping-line-companies.service";
 
 /** A charge to record against a shipping line's booking. */
@@ -39,6 +46,18 @@ export interface GenerateCreditInvoiceOptions {
   dueInDays?: number;
 }
 
+/**
+ * Emitted by the booking-transition accept path for shipping-line bookings.
+ * An event rather than a service call: BookingsModule cannot import the
+ * shipping-line modules without closing a module cycle.
+ */
+export interface ShippingLineBookingAcceptedPayload {
+  bookingId: string;
+  reference: string;
+  /** The booking's priced total, frozen at completion time. */
+  amount: number;
+}
+
 /**
  * The credit ledger for shipping lines — "use the service now, pay later".
  *
@@ -66,6 +85,7 @@ export class ShippingLineCreditsService {
   constructor(
     private readonly dataSource: DataSource,
     private readonly credits: ShippingLineCreditsRepository,
+    private readonly approvals: ShippingLineInvoiceApprovalsRepository,
     private readonly billing: BillingService,
     private readonly shippingLines: ShippingLineCompaniesService,
   ) {}
@@ -144,6 +164,32 @@ export class ShippingLineCreditsService {
     return manager ? run(manager) : this.dataSource.transaction(run);
   }
 
+  /**
+   * The moment a shipping-line booking becomes debt: Operations accepted it.
+   * Swallows its own failures with a loud log instead of throwing — the accept
+   * has already committed, and failing the staff response for a ledger write
+   * would present a succeeded accept as an error. `recordCredit` is idempotent
+   * per booking, so a re-accepted (previously reverted) booking cannot double
+   * the debt.
+   */
+  @OnEvent("shipping_line_booking.accepted")
+  async onBookingAccepted(
+    payload: ShippingLineBookingAcceptedPayload,
+  ): Promise<void> {
+    try {
+      await this.recordCredit({
+        bookingId: payload.bookingId,
+        amount: payload.amount,
+        // Shipping lines are always billed in ETB (enforced at completion).
+        currency: "ETB",
+      });
+    } catch (err) {
+      this.logger.error(
+        `Failed to record credit for accepted shipping-line booking ${payload.reference} (${payload.bookingId}): ${(err as Error).message} — the debt is NOT on the ledger; record it manually or re-trigger.`,
+      );
+    }
+  }
+
   // ── 2. Bill ────────────────────────────────────────────────────────────────
 
   /**
@@ -326,6 +372,39 @@ export class ShippingLineCreditsService {
     return this.credits.outstandingFor(shippingLineCompanyId);
   }
 
+  /**
+   * Back-office overview: outstanding totals across every line, or one line
+   * when an id is given.
+   */
+  async summary(shippingLineCompanyId?: string) {
+    if (shippingLineCompanyId) {
+      await this.requireShippingLine(shippingLineCompanyId);
+    }
+    return this.credits.outstandingFor(shippingLineCompanyId);
+  }
+
+  /**
+   * The whole ledger across every shipping line, newest first — finance's
+   * landing list. Optionally narrowed to one line and/or one status.
+   */
+  async listAll(
+    page = 1,
+    pageSize = 20,
+    status?: ShippingLineCreditStatus,
+    shippingLineCompanyId?: string,
+  ) {
+    if (shippingLineCompanyId) {
+      await this.requireShippingLine(shippingLineCompanyId);
+    }
+    const [items, total] = await this.credits.findAllPaginated(
+      shippingLineCompanyId,
+      (page - 1) * pageSize,
+      pageSize,
+      status,
+    );
+    return { items, total, page, pageSize };
+  }
+
   /** Full ledger for one line, newest first. */
   async listCredits(
     shippingLineCompanyId: string,
@@ -369,6 +448,287 @@ export class ShippingLineCreditsService {
     };
   }
 
+  // ── Credit invoices: list + maker–checker manual actions ─────────────────
+
+  /**
+   * Staff list of the invoices minted from credit batches, each with its line
+   * name and any undecided manual-action request attached — the data the
+   * back-office actions column renders from.
+   */
+  async listCreditInvoices(
+    page = 1,
+    pageSize = 20,
+    status?: Freight.InvoiceStatus,
+    shippingLineCompanyId?: string,
+  ) {
+    const [invoices, total] = await this.dataSource
+      .getRepository(Invoice)
+      .findAndCount({
+        where: {
+          source: Freight.InvoiceSource.ShippingLineCredit,
+          ...(status ? { status } : {}),
+          ...(shippingLineCompanyId ? { shippingLineCompanyId } : {}),
+        },
+        order: { createdAt: "DESC" },
+        skip: (page - 1) * pageSize,
+        take: pageSize,
+      });
+
+    const lineIds = [
+      ...new Set(
+        invoices
+          .map((inv) => inv.shippingLineCompanyId)
+          .filter((id): id is string => !!id),
+      ),
+    ];
+    const lines = lineIds.length
+      ? await this.dataSource
+          .getRepository(ShippingLineCompany)
+          .find({ where: { id: In(lineIds) } })
+      : [];
+    const nameById = new Map(lines.map((l) => [l.id, l.name]));
+
+    const pending = await this.approvals.findPendingByInvoiceIds(
+      invoices.map((inv) => inv.id),
+    );
+    const pendingByInvoice = new Map(pending.map((p) => [p.invoiceId, p]));
+
+    return {
+      items: invoices.map((inv) => ({
+        ...inv,
+        shippingLineName: inv.shippingLineCompanyId
+          ? (nameById.get(inv.shippingLineCompanyId) ?? null)
+          : null,
+        pendingAction: pendingByInvoice.get(inv.id) ?? null,
+      })),
+      total,
+      page,
+      pageSize,
+    };
+  }
+
+  /** Undecided requests for a batch of invoices — feeds any invoice list. */
+  async pendingInvoiceActions(
+    invoiceIds: string[],
+  ): Promise<ShippingLineInvoiceApproval[]> {
+    // Bounded to a list page's worth of ids; anything larger is a misuse.
+    return this.approvals.findPendingByInvoiceIds(invoiceIds.slice(0, 100));
+  }
+
+  /**
+   * Finance raises a manual action on a credit invoice: record an offline
+   * payment (MARK_PAID) or void it (CANCEL). Nothing happens to the invoice
+   * yet — a chief with the matching approve permission decides it. One
+   * undecided request per invoice (backed by a partial unique index).
+   */
+  async requestInvoiceAction(
+    invoiceId: string,
+    action: ShippingLineInvoiceActionType,
+    requestedBy: string,
+    reason: string,
+    paymentReference?: string,
+  ): Promise<ShippingLineInvoiceApproval> {
+    const invoice = await this.dataSource
+      .getRepository(Invoice)
+      .findOne({ where: { id: invoiceId } });
+    if (!invoice) {
+      throw new NotFoundException(`Invoice ${invoiceId} not found`);
+    }
+    if (invoice.source !== Freight.InvoiceSource.ShippingLineCredit) {
+      throw new BadRequestException(
+        "Manual actions here apply only to shipping-line credit invoices.",
+      );
+    }
+    // Fast feedback only — the billing service re-validates authoritatively
+    // (under lock) when the request is approved.
+    if (
+      action === ShippingLineInvoiceActionType.MarkPaid &&
+      invoice.status === Freight.InvoiceStatus.Paid
+    ) {
+      throw new BadRequestException("Invoice is already paid.");
+    }
+    if (invoice.status === Freight.InvoiceStatus.Cancelled) {
+      throw new BadRequestException("Invoice is already cancelled.");
+    }
+    if (
+      action === ShippingLineInvoiceActionType.Cancel &&
+      Number(invoice.paidAmount) > 0
+    ) {
+      throw new BadRequestException(
+        "Cannot cancel an invoice that has payments recorded against it.",
+      );
+    }
+    const existing = await this.approvals.findPendingByInvoice(invoiceId);
+    if (existing) {
+      throw new BadRequestException(
+        `A ${existing.action} request is already awaiting decision on this invoice.`,
+      );
+    }
+
+    const approval = await this.approvals.create({
+      invoiceId,
+      action,
+      status: ShippingLineInvoiceActionStatus.Pending,
+      requestedBy,
+      reason,
+      paymentReference: paymentReference ?? null,
+    });
+
+    logCtx(
+      {
+        approvalId: approval.id,
+        invoiceId,
+        invoiceNumber: invoice.invoiceNumber,
+        action,
+        requestedBy,
+      },
+      { path: "shippingLineCredit.invoiceAction.requested" },
+    );
+
+    return approval;
+  }
+
+  /**
+   * Decide a pending request. Gated purely by permission (the approve/reject
+   * grants on the controller routes) — a decider holding the grant may decide
+   * ANY pending request, their own included; that trade-off is deliberate.
+   *
+   * Approval executes the real action through the billing service AFTER the
+   * decision row commits — its settlement/cancellation events must fire from
+   * billing's own committed transaction (the credits listeners react to
+   * them). If billing then rejects the action, the decision is compensated
+   * back to PENDING so the request is not silently lost.
+   */
+  async decideInvoiceAction(
+    approvalId: string,
+    decidedBy: string,
+    approve: boolean,
+    note?: string,
+  ): Promise<ShippingLineInvoiceApproval> {
+    if (!approve && !note?.trim()) {
+      throw new BadRequestException(
+        "A note is required when rejecting a request.",
+      );
+    }
+
+    const decided = await this.dataSource.transaction(async (mg) => {
+      const approval = await this.approvals.findByIdForUpdate(mg, approvalId);
+      if (!approval) {
+        throw new NotFoundException(`Request ${approvalId} not found`);
+      }
+      if (approval.status !== ShippingLineInvoiceActionStatus.Pending) {
+        throw new BadRequestException(
+          `This request was already ${approval.status.toLowerCase()}.`,
+        );
+      }
+
+      const status = approve
+        ? ShippingLineInvoiceActionStatus.Approved
+        : ShippingLineInvoiceActionStatus.Rejected;
+      await mg.update(
+        ShippingLineInvoiceApproval,
+        { id: approvalId },
+        {
+          status,
+          decidedBy,
+          decidedAt: new Date(),
+          decisionNote: note ?? null,
+        },
+      );
+      return { ...approval, status, decidedBy, decisionNote: note ?? null };
+    });
+
+    if (!approve) {
+      logCtx(
+        { approvalId, invoiceId: decided.invoiceId, decidedBy },
+        { path: "shippingLineCredit.invoiceAction.rejected" },
+      );
+      return decided;
+    }
+
+    try {
+      if (decided.action === ShippingLineInvoiceActionType.MarkPaid) {
+        const invoice = await this.dataSource
+          .getRepository(Invoice)
+          .findOne({ where: { id: decided.invoiceId } });
+        if (!invoice) {
+          throw new NotFoundException(`Invoice ${decided.invoiceId} not found`);
+        }
+        // Full settlement of the outstanding balance; billing emits
+        // `shipping_line_credit.invoice.paid`, which marks the credits PAID.
+        await this.billing.recordPayment(decided.invoiceId, {
+          amount: Number(invoice.balanceAmount ?? invoice.totalAmount),
+          method: "OFFLINE",
+          reference: decided.paymentReference ?? undefined,
+          metadata: {
+            approvalId: decided.id,
+            requestedBy: decided.requestedBy,
+            approvedBy: decidedBy,
+          },
+        });
+      } else {
+        // Billing emits `shipping_line_credit.invoice.cancelled`;
+        // onInvoiceCancelled releases the credits back to the unbilled pool.
+        await this.billing.cancelInvoice(decided.invoiceId);
+      }
+    } catch (err) {
+      // The action was refused (state changed since the request — e.g. the
+      // line paid through CBE in the meantime). Put the request back so it is
+      // not recorded as approved-but-unexecuted.
+      await this.approvals.update(approvalId, {
+        status: ShippingLineInvoiceActionStatus.Pending,
+        decidedBy: null,
+        decidedAt: null,
+        decisionNote: null,
+      });
+      throw err;
+    }
+
+    logCtx(
+      {
+        approvalId,
+        invoiceId: decided.invoiceId,
+        action: decided.action,
+        decidedBy,
+      },
+      { path: "shippingLineCredit.invoiceAction.approved" },
+    );
+
+    return decided;
+  }
+
+  /**
+   * When a credit invoice is cancelled — through the approval flow or any
+   * other billing path — its BILLED credits return to the unbilled pool so
+   * the debt can be re-billed. The debt itself never disappears on invoice
+   * cancellation; only {@link cancelCredit} writes debt off.
+   */
+  @OnEvent("shipping_line_credit.invoice.cancelled")
+  async onInvoiceCancelled(payload: InvoiceEventPayload): Promise<void> {
+    const result = await this.dataSource
+      .getRepository(ShippingLineCredit)
+      .update(
+        {
+          invoiceId: payload.invoiceId,
+          status: ShippingLineCreditStatus.Billed,
+        },
+        {
+          status: ShippingLineCreditStatus.Unbilled,
+          invoiceId: null,
+          billedAt: null,
+        },
+      );
+
+    logCtx(
+      {
+        invoiceId: payload.invoiceId,
+        invoiceNumber: payload.invoiceNumber,
+        creditsReleased: result.affected ?? 0,
+      },
+      { path: "shippingLineCredit.invoiceCancelled.released" },
+    );
+  }
+
   // ── Cancellation ───────────────────────────────────────────────────────────
 
   /**
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-invoice-approvals.repository.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-invoice-approvals.repository.ts
new file mode 100644
index 000000000..dcd904fa2
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-invoice-approvals.repository.ts
@@ -0,0 +1,51 @@
+import { BaseRepository } from "@edr/api-common";
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { EntityManager, In, Repository } from "typeorm";
+
+import {
+  ShippingLineInvoiceApproval,
+  ShippingLineInvoiceActionStatus,
+} from "./entities/shipping-line-invoice-approval.entity";
+
+@Injectable()
+export class ShippingLineInvoiceApprovalsRepository extends BaseRepository<ShippingLineInvoiceApproval> {
+  constructor(
+    @InjectRepository(ShippingLineInvoiceApproval)
+    private readonly approvals: Repository<ShippingLineInvoiceApproval>,
+  ) {
+    super(approvals);
+  }
+
+  findPendingByInvoice(
+    invoiceId: string,
+  ): Promise<ShippingLineInvoiceApproval | null> {
+    return this.approvals.findOne({
+      where: { invoiceId, status: ShippingLineInvoiceActionStatus.Pending },
+    });
+  }
+
+  /** Pending requests for a page of invoices — one query, no N+1. */
+  findPendingByInvoiceIds(
+    invoiceIds: string[],
+  ): Promise<ShippingLineInvoiceApproval[]> {
+    if (!invoiceIds.length) return Promise.resolve([]);
+    return this.approvals.find({
+      where: {
+        invoiceId: In(invoiceIds),
+        status: ShippingLineInvoiceActionStatus.Pending,
+      },
+    });
+  }
+
+  /** Load one request inside the caller's transaction, locked for decision. */
+  findByIdForUpdate(
+    manager: EntityManager,
+    id: string,
+  ): Promise<ShippingLineInvoiceApproval | null> {
+    return manager.getRepository(ShippingLineInvoiceApproval).findOne({
+      where: { id },
+      lock: { mode: "pessimistic_write" },
+    });
+  }
+}
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 b9c115d53..4418eed3d 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
@@ -26,6 +26,7 @@ import { Booking } from '../bookings/entities/booking.entity';
 import { BookingsRepository } from '../bookings/bookings.repository';
 import { BookingPricingService } from '../bookings/booking-pricing.service';
 import { formatRouteLabel } from '../routes/entities/route.entity';
+import { isRoadService } from '../bookings/road.util';
 import { RouteMilestone } from '../routes/entities/route-milestone.entity';
 import { Yard } from '../rule-engine/entities/yard.entity';
 import { CargoType } from '../rule-engine/entities/cargo-type.entity';
@@ -154,6 +155,19 @@ export interface ExportTrainOption {
   }>;
 }
 
+/** Form-entered cargo for a train-options probe (nothing persisted yet). */
+export interface TrainOptionCargoOverrides {
+  /** Container types drive the per-type space. */
+  containerTypeIds?: string[];
+  /** Size labels ("20ft"/"40ft") when the form has no type ids. */
+  containerSizes?: string[];
+  /** Bulk counterparts of the container inputs. */
+  cargoTypeId?: string;
+  cargoTypeCode?: string;
+  /** Needed wagons estimate from the form (drives the `fits` flag). */
+  wagons?: number;
+}
+
 /** A train a paid-unallocated booking can board (route + capacity verified). */
 export interface AllocationCandidate {
   id: string;
@@ -1051,19 +1065,84 @@ export class BookingBatchService implements OnModuleInit {
   async exportTrainOptionsForDay(
     booking: Booking,
     day: string,
-    overrides?: {
-      /** Cargo the customer is entering on a form (bare contract instance —
-       * nothing persisted yet): container types drive the per-type space. */
-      containerTypeIds?: string[];
-      /** Size labels ("20ft"/"40ft") when the form has no type ids. */
-      containerSizes?: string[];
-      /** Bulk counterparts of the container inputs. */
-      cargoTypeId?: string;
-      cargoTypeCode?: string;
-      /** Needed wagons estimate from the form (drives the `fits` flag). */
-      wagons?: number;
-    },
+    overrides?: TrainOptionCargoOverrides,
   ): Promise<ExportTrainOption[]> {
+    booking = await this.withCargoOverrides(booking, overrides);
+    const corridor = await this.trainSchedulesRepository.findAll({
+      where: [
+        // Dedicated shipping-line trains are never customer-booking targets.
+        { status: TrainScheduleStatusEnum.Draft, shippingLineCompanyId: IsNull() },
+        { status: TrainScheduleStatusEnum.Scheduled, shippingLineCompanyId: IsNull() },
+      ],
+    });
+    const candidates = corridor
+      .filter(
+        (s) =>
+          s.scheduledDepartureDate != null &&
+          eatDay(s.scheduledDepartureDate) === day &&
+          s.direction === 'EXPORT',
+      )
+      .sort(
+        (a, b) =>
+          a.scheduledDepartureDate!.getTime() -
+          b.scheduledDepartureDate!.getTime(),
+      );
+    return this.buildTrainOptions(booking, candidates);
+  }
+
+  /**
+   * The same per-train wagon-availability cards, but for the trains DEDICATED
+   * to a shipping line on the booking's lane + day. Same option shape as the
+   * export picker so the portal reuses the same component; `isOpen`
+   * additionally respects the dedicated close offset (windowClosesAt), since
+   * these trains run no window cycle.
+   */
+  async dedicatedTrainOptionsForDay(
+    booking: Booking,
+    day: string | null,
+    shippingLineCompanyId: string,
+    overrides?: TrainOptionCargoOverrides,
+  ): Promise<ExportTrainOption[]> {
+    booking = await this.withCargoOverrides(booking, overrides);
+    const dedicated = await this.trainSchedulesRepository.findAll({
+      where: [
+        { status: TrainScheduleStatusEnum.Draft, shippingLineCompanyId },
+        { status: TrainScheduleStatusEnum.Scheduled, shippingLineCompanyId },
+      ],
+    });
+    const candidates = dedicated
+      .filter(
+        (s) =>
+          s.scheduledDepartureDate != null &&
+          // A day narrows to that departure day; without one, every upcoming
+          // departure on the lane is listed (the picker's full card list).
+          (day
+            ? eatDay(s.scheduledDepartureDate) === day
+            : s.scheduledDepartureDate.getTime() > Date.now() - 3_600_000) &&
+          (!booking.originYardId || s.originStationId === booking.originYardId) &&
+          (!booking.destinationYardId ||
+            s.destinationStationId === booking.destinationYardId),
+      )
+      .sort(
+        (a, b) =>
+          a.scheduledDepartureDate!.getTime() -
+          b.scheduledDepartureDate!.getTime(),
+      );
+    const options = await this.buildTrainOptions(booking, candidates);
+    const now = Date.now();
+    return options.map((o) => ({
+      ...o,
+      isOpen:
+        o.isOpen &&
+        (o.bookingClosesAt == null || o.bookingClosesAt.getTime() > now),
+    }));
+  }
+
+  /** Resolve form-entered cargo onto an (unpersisted) booking probe. */
+  private async withCargoOverrides(
+    booking: Booking,
+    overrides?: TrainOptionCargoOverrides,
+  ): Promise<Booking> {
     const sizeFts = (overrides?.containerSizes ?? [])
       .map((s) => parseInt(s, 10))
       .filter((n) => Number.isFinite(n) && n > 0);
@@ -1095,26 +1174,14 @@ export class BookingBatchService implements OnModuleInit {
     if (overrides?.wagons && overrides.wagons > 0) {
       booking = { ...booking, wagonsRequired: overrides.wagons } as Booking;
     }
-    const corridor = await this.trainSchedulesRepository.findAll({
-      where: [
-        // Dedicated shipping-line trains are never customer-booking targets.
-        { status: TrainScheduleStatusEnum.Draft, shippingLineCompanyId: IsNull() },
-        { status: TrainScheduleStatusEnum.Scheduled, shippingLineCompanyId: IsNull() },
-      ],
-    });
-    const candidates = corridor
-      .filter(
-        (s) =>
-          s.scheduledDepartureDate != null &&
-          eatDay(s.scheduledDepartureDate) === day &&
-          s.direction === 'EXPORT',
-      )
-      .sort(
-        (a, b) =>
-          a.scheduledDepartureDate!.getTime() -
-          b.scheduledDepartureDate!.getTime(),
-      );
+    return booking;
+  }
 
+  /** One availability card per candidate schedule — the export picker's math. */
+  private async buildTrainOptions(
+    booking: Booking,
+    candidates: TrainSchedule[],
+  ): Promise<ExportTrainOption[]> {
     const wagonDims = await this.loadWagonDims();
     const allowed = this.allowedDimsWithTypes(booking, wagonDims);
     const neededWagons = this.wagonsFor(booking, wagonDims);
@@ -3185,6 +3252,99 @@ export class BookingBatchService implements OnModuleInit {
     }
   }
 
+  /**
+   * Auto-allocate an accepted SHIPPING-LINE booking onto its company's
+   * dedicated train for the booking's lane and shipment day.
+   *
+   * Runs at operation-accept: shipping lines pay later on the credit ledger,
+   * so there is no pay window between accept and wagon placement — the
+   * booking boards its train immediately. Customer bookings never come here;
+   * they keep the batch pool → reserve → pay → allocate pipeline.
+   *
+   * Wagon shortage parks the booking WAITING_FOR_WAGON on the schedule
+   * (without the PAID stamps the customer hold writes — nothing was paid).
+   * No dedicated train on the day is not an error: the booking simply stays
+   * in the ordinary day pool for the batch engine.
+   */
+  async allocateShippingLineAccepted(bookingId: string): Promise<void> {
+    const booking = await this.dataSource.getRepository(Booking).findOne({
+      where: { id: bookingId },
+      relations: { bookingContainers: { containerType: true }, cargoType: true },
+    });
+    if (!booking?.shippingLineCompanyId || !booking.scheduledDate) return;
+    if (isRoadService(booking.serviceType)) return;
+
+    const day = eatDay(booking.scheduledDate);
+    const dedicated = await this.dataSource.getRepository(TrainSchedule).find({
+      where: [
+        {
+          shippingLineCompanyId: booking.shippingLineCompanyId,
+          originStationId: booking.originYardId,
+          destinationStationId: booking.destinationYardId,
+          status: TrainScheduleStatusEnum.Draft,
+        },
+        {
+          shippingLineCompanyId: booking.shippingLineCompanyId,
+          originStationId: booking.originYardId,
+          destinationStationId: booking.destinationYardId,
+          status: TrainScheduleStatusEnum.Scheduled,
+        },
+      ],
+    });
+    const target = dedicated.find(
+      (s) =>
+        s.scheduledDepartureDate && eatDay(s.scheduledDepartureDate) === day,
+    );
+    if (!target) {
+      this.logger.log(
+        `[BATCH] shipping-line booking ${booking.reference} has no dedicated ` +
+          `train on ${day} — left in the day pool for the batch engine`,
+      );
+      return;
+    }
+
+    // Point the booking at its train BEFORE the shortage probe — the probe
+    // reads the link to size the need against that schedule's wagons.
+    await this.dataSource.getRepository(Booking).update(booking.id, {
+      trainScheduleId: target.id,
+    } as never);
+    booking.trainScheduleId = target.id;
+
+    // One dedicated train carries ONE booking: the accept claims the train by
+    // closing its booking window on the spot. Both gates a later booking
+    // passes — the day picker (isStillOpen on windowClosesAt) and the
+    // completion's dedicated-day check — read these fields, so a second
+    // booking can never pick this train.
+    await this.dataSource.getRepository(TrainSchedule).update(target.id, {
+      bookingWindowStatus: "CLOSED",
+      windowClosesAt: new Date(),
+    } as never);
+    this.notifyBoardChanged(target.id, "shipping_line_train_claimed");
+
+    const shortage =
+      await this.trainSchedulingService.previewPaidBookingWagonShortage(
+        target.id,
+        booking.id,
+      );
+    if (shortage) {
+      // Parked for staff to attach wagons — WITHOUT the customer hold's PAID
+      // stamps: a shipping line has paid nothing, its debt sits on the ledger.
+      await this.dataSource.getRepository(Booking).update(booking.id, {
+        schedulingStatus: "WAITING_FOR_WAGON",
+      } as never);
+      this.logger.warn(
+        `Shipping-line booking ${booking.reference} WAITING FOR WAGON on its ` +
+          `dedicated train ${target.reference ?? target.id}: needs ` +
+          `${shortage.wagonsNeeded} × ${shortage.wagonTypeCodes}, ` +
+          `${shortage.wagonsAvailable} available (short ${shortage.wagonsShort}).`,
+      );
+      this.notifyBoardChanged(target.id, "booking_waiting_wagon");
+      return;
+    }
+
+    await this.allocate(target.id, booking, "shipping_line");
+  }
+
   /**
    * One reminder per hold, shortly before its pay deadline (the window tick
    * calls this every pass; `payment_reminder_sent_at` dedups). Skips paid
@@ -3544,7 +3704,7 @@ export class BookingBatchService implements OnModuleInit {
   private async allocate(
     scheduleId: string,
     booking: Booking,
-    reason: "paid" | "gov",
+    reason: "paid" | "gov" | "shipping_line",
   ): Promise<void> {
     // Stamp the computed wagon need on the link. Several callers pass a booking
     // loaded without cargo relations (ensurePaidBookingAllocated), and a NULL
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/booking-notifier.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/booking-notifier.service.ts
index 9468387c5..1c2d99401 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/booking-notifier.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/booking-notifier.service.ts
@@ -12,6 +12,7 @@ import { Booking } from '../bookings/entities/booking.entity';
 import { NotificationsService } from '../notifications/notifications.service';
 import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
 import { resolveCompanyNotifyContact } from '../notifications/resolve-company-phone.util';
+import { resolveShippingLineNotifyTarget } from '../notifications/resolve-shipping-line-contact.util';
 import { TrainSchedulesRepository } from '../train-schedules/train-schedules.repository';
 import { BATCH_TIMEZONE } from './booking-batch.constants';
 
@@ -66,10 +67,16 @@ export class BookingNotifierService {
   ): Promise<void> {
     this.logger.log(`${logLabel} — ${this.ref(b)}`);
     // One resolver for both channels — the company row's own email column is
-    // only set for a Fayda-verified owner (see companyNotifyEmailExpr).
-    const { phone, email } = b.companyId
-      ? await resolveCompanyNotifyContact(this.dataSource, b.companyId)
-      : { phone: null, email: null };
+    // only set for a Fayda-verified owner (see companyNotifyEmailExpr). A
+    // shipping-line booking has no company; its contact is the line's row.
+    const { phone, email } = b.shippingLineCompanyId
+      ? await resolveShippingLineNotifyTarget(
+          this.dataSource,
+          b.shippingLineCompanyId,
+        )
+      : b.companyId
+        ? await resolveCompanyNotifyContact(this.dataSource, b.companyId)
+        : { phone: null, email: null };
 
     if (phone) {
       try {
@@ -90,13 +97,42 @@ export class BookingNotifierService {
     }
   }
 
-  /** Persist + push an in-app item to all portal users of the booking's company. */
+  /**
+   * Persist + push an in-app item to the booking's portal owner: every portal
+   * user of the company, or — for a shipping-line booking — the line's own
+   * account, deep-linked into the shipping-line app (/shipping-line/*).
+   */
   private inApp(
     b: Booking,
     title: string,
     body: string,
     overrides: Partial<NotifyInput> = {},
   ): void {
+    if (b.shippingLineCompanyId) {
+      void (async () => {
+        const { userId } = await resolveShippingLineNotifyTarget(
+          this.dataSource,
+          b.shippingLineCompanyId!,
+        );
+        if (!userId) return;
+        void this.inbox.notify({
+          recipients: { userIds: [userId] },
+          audience: NotificationAudience.PORTAL,
+          type: NotificationType.SCHEDULE_UPDATE,
+          title,
+          body,
+          data: { bookingId: b.id, reference: b.reference },
+          ...overrides,
+          // After the spread: the bell must land the line on ITS booking page.
+          link: `/shipping-line/bookings/${b.id}`,
+        });
+      })().catch((err) =>
+        this.logger.warn(
+          `shipping-line inApp failed for ${this.ref(b)}: ${(err as Error).message}`,
+        ),
+      );
+      return;
+    }
     if (!b.companyId) return; // government/unlinked bookings have no portal users
     void this.inbox.notify({
       recipients: { companyId: b.companyId },
@@ -209,11 +245,19 @@ export class BookingNotifierService {
     });
   }
 
-  secured(b: Booking, reason: 'paid' | 'gov', scheduleId?: string | null): void {
+  secured(
+    b: Booking,
+    reason: 'paid' | 'gov' | 'shipping_line',
+    scheduleId?: string | null,
+  ): void {
     void (async () => {
       const label = await this.scheduleLabel(scheduleId ?? b.trainScheduleId);
       const msg = `Booking ${b.reference ?? b.id} allocated on ${label}${
-        reason === 'gov' ? ' (government)' : ''
+        reason === 'gov'
+          ? ' (government)'
+          : reason === 'shipping_line'
+            ? ' (shipping line)'
+            : ''
       }.`;
       void this.notifyContact(b, msg, 'ALLOCATED');
       this.inApp(b, 'Wagon allocated', msg);
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index 7125e3bbf..12fb3dec6 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -4531,7 +4531,10 @@ export class TrainSchedulingService {
       (b) =>
         !(targetScheduleId && b.trainScheduleId === targetScheduleId) &&
         !SCHEDULABLE_BOOKING_STATUSES.includes(b.status as 'PAID') &&
-        !b.isGovernment,
+        !b.isGovernment &&
+        // Shipping-line bookings pay later on the credit ledger — never PAID
+        // up front, schedulable from accept (FULLY_EXECUTED) like government.
+        !b.shippingLineCompanyId,
     );
     if (invalidStatus.length) {
       const statuses = [...new Set(invalidStatus.map((b) => b.status))];
@@ -8647,7 +8650,12 @@ export class TrainSchedulingService {
       .map((sb) => sb.booking)
       .filter((b): b is Booking => Boolean(b));
     const eligible = linkedBookings.filter(
-      (b) => SCHEDULABLE_BOOKING_STATUSES.includes(b.status as 'PAID') || b.isGovernment,
+      (b) =>
+        SCHEDULABLE_BOOKING_STATUSES.includes(b.status as 'PAID') ||
+        b.isGovernment ||
+        // Shipping-line bookings board without paying up front — their charge
+        // sits on the credit ledger, so accept (FULLY_EXECUTED) is boardable.
+        Boolean(b.shippingLineCompanyId),
     );
     if (!eligible.length) return empty;
 
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 81b3336de..adbd22584 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -595,6 +595,28 @@ export const FINANCE_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:shipping_line_credits:cancel",
     "Cancel (write off) an unbilled shipping-line credit",
   ),
+  // Two-step manual actions on credit invoices: request grants per action,
+  // decision grants that apply to any pending request.
+  perm(
+    "d2c00001-0001-4000-8000-000000000004",
+    "edr_freight_app:shipping_line_credits:invoice_mark_paid",
+    "Request marking a shipping-line credit invoice paid (offline payment)",
+  ),
+  perm(
+    "d2c00001-0001-4000-8000-000000000005",
+    "edr_freight_app:shipping_line_credits:invoice_approve",
+    "Approve any pending shipping-line credit invoice request",
+  ),
+  perm(
+    "d2c00001-0001-4000-8000-000000000006",
+    "edr_freight_app:shipping_line_credits:invoice_cancel",
+    "Request cancelling a shipping-line credit invoice",
+  ),
+  perm(
+    "d2c00001-0001-4000-8000-000000000007",
+    "edr_freight_app:shipping_line_credits:invoice_reject",
+    "Reject any pending shipping-line credit invoice request",
+  ),
 ];
 
 // E. First / last mile operations
@@ -1829,6 +1851,18 @@ export const FREIGHT_PERMS = {
     invoice: "edr_freight_app:shipping_line_credits:invoice",
     /** Write off an unbilled credit — separate grant: it erases a debt. */
     cancel: "edr_freight_app:shipping_line_credits:cancel",
+    // Two-step manual actions on credit invoices, gated purely by permission:
+    // finance-level REQUEST grants (per action) and decision grants that apply
+    // to ANY pending request — including the holder's own.
+    /** Request recording an offline payment against a credit invoice. */
+    invoiceMarkPaid:
+      "edr_freight_app:shipping_line_credits:invoice_mark_paid",
+    /** Request voiding a credit invoice (credits return to unbilled). */
+    invoiceCancel: "edr_freight_app:shipping_line_credits:invoice_cancel",
+    /** Approve any pending invoice request (mark-paid or cancel). */
+    invoiceApprove: "edr_freight_app:shipping_line_credits:invoice_approve",
+    /** Reject any pending invoice request. */
+    invoiceReject: "edr_freight_app:shipping_line_credits:invoice_reject",
   },
   payments: {
     view: "edr_freight_app:payments:view",
@@ -2377,6 +2411,13 @@ export const ROLE_PERMISSION_PRESETS = {
     // exceptional operations, and are assigned to named admins rather than a role preset.
     FREIGHT_PERMS.payments.view,
     FREIGHT_PERMS.bookings.wagonCancellationView,
+    // Shipping-line credit ledger is a Finance surface: bill batches into
+    // invoices and RAISE manual invoice actions. Approval of those actions is
+    // deliberately absent — it sits with the chief (maker–checker).
+    FREIGHT_PERMS.shippingLineCredits.view,
+    FREIGHT_PERMS.shippingLineCredits.invoice,
+    FREIGHT_PERMS.shippingLineCredits.invoiceMarkPaid,
+    FREIGHT_PERMS.shippingLineCredits.invoiceCancel,
   ],
   // Global Logistics: manages ONLY the customs-clearance queue. Scoped out of
   // the general booking-request list (no bookings:view) — instead a dedicated
@@ -2479,6 +2520,11 @@ export const POSITION_PERMISSION_PRESETS = {
     FREIGHT_PERMS.invoices.view,
     FREIGHT_PERMS.invoices.export,
     FREIGHT_PERMS.payments.view,
+    // Decision side of the credit-invoice two-step: finance raises
+    // mark-paid/cancel requests, the chief approves or rejects them.
+    FREIGHT_PERMS.shippingLineCredits.view,
+    FREIGHT_PERMS.shippingLineCredits.invoiceApprove,
+    FREIGHT_PERMS.shippingLineCredits.invoiceReject,
   ]),
   // Director additionally manages train scheduling + rail fleet (same block the
   // operation officer/chief hold), on top of the approval-chain role preset,
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index cb4699aa1..6eda68ae1 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -37,6 +37,7 @@ import DocumentClearanceListPage from "./pages/bookings/DocumentClearanceListPag
 import CustomerDetailPage from "./pages/customers/CustomerDetailPage";
 import CustomersPage from "./pages/customers/CustomersPage";
 import ShippingLineCompaniesPage from "./pages/shipping-lines/ShippingLineCompaniesPage";
+import ShippingLineCreditsPage from "./pages/shipping-lines/ShippingLineCreditsPage";
 import InvoiceDetailPage from "./pages/invoices/InvoiceDetailPage";
 import FinanceHubPage from "./pages/invoices/FinanceHubPage";
 import MyProfilePage from "./pages/dashboard/MyProfilePage";
@@ -309,6 +310,16 @@ const App = () => {
             </RequirePermission>
           }
         />
+        <Route
+          path="shipping-line-credits"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.shippingLineCredits.view}
+            >
+              <ShippingLineCreditsPage />
+            </RequirePermission>
+          }
+        />
         <Route
           path="invoices"
           element={
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCargoCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCargoCard.tsx
index ecd903128..1070aa050 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCargoCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCargoCard.tsx
@@ -1,5 +1,5 @@
 import { Package } from "lucide-react";
-import { SimpleGrid, Divider, Box, Table, Text } from "@mantine/core";
+import { SimpleGrid, Divider, Box, Table, Text, Badge } from "@mantine/core";
 
 import type { BookingDetail } from "@/types/booking";
 import { cargoTonsAndItems } from "@/utils/cargoWeight";
@@ -16,6 +16,19 @@ export function BookingCargoCard({ booking }: BookingCargoCardProps) {
   const containers = booking.bookingContainers ?? [];
   const { tons, items } = cargoTonsAndItems(booking);
 
+  // Booking-level flags OR any container line carrying a count — the flag can
+  // lag the lines (per-line opt-ins), so either alone must light the tile.
+  const isHazardous =
+    booking.isHazardous ||
+    containers.some((c) => Number(c.hazardousQuantity ?? 0) > 0);
+  const isReefer =
+    booking.isReefer ||
+    containers.some((c) => Number(c.reeferQuantity ?? 0) > 0);
+  const showHandlingColumns = containers.some(
+    (c) =>
+      Number(c.hazardousQuantity ?? 0) > 0 || Number(c.reeferQuantity ?? 0) > 0,
+  );
+
   return (
     <SectionCard icon={Package} title="Cargo specifications" accent="orange">
       <SimpleGrid cols={{ base: 1, sm: 3 }} spacing="sm">
@@ -27,11 +40,33 @@ export function BookingCargoCard({ booking }: BookingCargoCardProps) {
         {items != null && <MetricTile label="Items" value={`${items}`} />}
         <MetricTile
           label="Hazardous"
-          value={booking.isHazardous ? "Yes" : "No"}
-          highlight={booking.isHazardous}
+          value={isHazardous ? "Yes" : "No"}
+          highlight={isHazardous}
+        />
+        <MetricTile
+          label="Refrigerated"
+          value={isReefer ? "Yes" : "No"}
+          highlight={isReefer}
         />
       </SimpleGrid>
 
+      {/* Handling that changes how the yard treats the shipment is flagged
+          loudly, not buried in the grid. */}
+      {(isHazardous || isReefer) && (
+        <Box mt="sm">
+          {isHazardous && (
+            <Badge color="red" variant="filled" radius="sm" mr={8}>
+              Hazardous cargo
+            </Badge>
+          )}
+          {isReefer && (
+            <Badge color="blue" variant="filled" radius="sm">
+              Refrigerated cargo
+            </Badge>
+          )}
+        </Box>
+      )}
+
       {containers.length > 0 && (
         <>
           <Divider my="lg" color="var(--mantine-color-gray-2)" />
@@ -42,6 +77,8 @@ export function BookingCargoCard({ booking }: BookingCargoCardProps) {
                   <Table.Th>Container type</Table.Th>
                   <Table.Th>Qty</Table.Th>
                   <Table.Th>VGM / unit</Table.Th>
+                  {showHandlingColumns && <Table.Th>Hazardous</Table.Th>}
+                  {showHandlingColumns && <Table.Th>Reefer</Table.Th>}
                 </Table.Tr>
               </Table.Thead>
               <Table.Tbody>
@@ -54,6 +91,28 @@ export function BookingCargoCard({ booking }: BookingCargoCardProps) {
                     </Table.Td>
                     <Table.Td>{c.quantity}</Table.Td>
                     <Table.Td>{c.vgmPerUnitTons} t</Table.Td>
+                    {showHandlingColumns && (
+                      <Table.Td>
+                        {Number(c.hazardousQuantity ?? 0) > 0 ? (
+                          <Text fw={700} c="red" size="sm">
+                            {c.hazardousQuantity}
+                          </Text>
+                        ) : (
+                          "—"
+                        )}
+                      </Table.Td>
+                    )}
+                    {showHandlingColumns && (
+                      <Table.Td>
+                        {Number(c.reeferQuantity ?? 0) > 0 ? (
+                          <Text fw={700} c="blue" size="sm">
+                            {c.reeferQuantity}
+                          </Text>
+                        ) : (
+                          "—"
+                        )}
+                      </Table.Td>
+                    )}
                   </Table.Tr>
                 ))}
               </Table.Tbody>
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 813e11d1c..293e82450 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -24,6 +24,7 @@ import {
   Send,
   Settings,
   ShieldCheck,
+  HandCoins,
   Ship,
   SlidersHorizontal,
   Train,
@@ -76,6 +77,12 @@ export const buildSidebarSections = (
           icon: <Ship />,
           permission: FREIGHT_PERMS.shippingLines.view,
         },
+        {
+          label: "Shipping Line Credits",
+          href: "/dashboard/shipping-line-credits",
+          icon: <HandCoins />,
+          permission: FREIGHT_PERMS.shippingLineCredits.view,
+        },
         {
           label: "Contracts",
           href: "/dashboard/contract-requests",
diff --git a/apps/edr-freight-web/backoffice/src/components/shipping-lines/CreditInvoiceActions.tsx b/apps/edr-freight-web/backoffice/src/components/shipping-lines/CreditInvoiceActions.tsx
new file mode 100644
index 000000000..6088d58f1
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/shipping-lines/CreditInvoiceActions.tsx
@@ -0,0 +1,363 @@
+import {
+  Badge,
+  Button,
+  Group,
+  Modal,
+  Stack,
+  Text,
+  Textarea,
+  TextInput,
+} from "@mantine/core";
+import { useMutation } from "@tanstack/react-query";
+import { Ban, Check, HandCoins, X } from "lucide-react";
+import { useState } from "react";
+
+import { useAuth } from "@/auth/useAuth";
+import { formatMoney } from "@/components/customers";
+import { useToast } from "@/hooks/use-toast";
+import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
+import { api } from "@/services/api";
+import type {
+  CreditInvoiceActionType,
+  CreditInvoicePendingAction,
+} from "@/types/shippingLineCredit";
+
+/** The slice of an invoice row the actions need — both list pages have it. */
+export interface CreditInvoiceActionTarget {
+  id: string;
+  invoiceNumber: string;
+  status: string;
+  currency: string;
+  totalAmount: string | number;
+  paidAmount: string | number;
+  balanceAmount: string | number;
+}
+
+/** Statuses an offline payment can still be recorded against. */
+const MARK_PAID_STATUSES = new Set([
+  "ISSUED",
+  "PENDING",
+  "PAYMENT_PROCESSING",
+  "PARTIALLY_PAID",
+  "OVERDUE",
+]);
+
+const ACTION_LABEL: Record<CreditInvoiceActionType, string> = {
+  MARK_PAID: "Mark paid",
+  CANCEL: "Cancel invoice",
+};
+
+export interface CreditInvoiceActionsProps {
+  invoice: CreditInvoiceActionTarget;
+  pendingAction: CreditInvoicePendingAction | null;
+}
+
+/**
+ * Two-step actions for ONE shipping-line credit invoice, embeddable in any
+ * invoice list. Gated purely by permission: the request grants raise
+ * mark-paid / cancel, the approve/reject grants decide ANY pending request —
+ * the holder's own included. Renders only the buttons the signed-in user's
+ * grants allow; the API enforces the same gates server-side.
+ */
+export default function CreditInvoiceActions({
+  invoice,
+  pendingAction,
+}: CreditInvoiceActionsProps) {
+  const { user } = useAuth();
+  const { toast } = useToast();
+
+  const canRequestPaid = hasPermission(
+    user,
+    FREIGHT_PERMS.shippingLineCredits.invoiceMarkPaid,
+  );
+  const canRequestCancel = hasPermission(
+    user,
+    FREIGHT_PERMS.shippingLineCredits.invoiceCancel,
+  );
+  const canApprove = hasPermission(
+    user,
+    FREIGHT_PERMS.shippingLineCredits.invoiceApprove,
+  );
+  const canReject = hasPermission(
+    user,
+    FREIGHT_PERMS.shippingLineCredits.invoiceReject,
+  );
+
+  const [requestAction, setRequestActionModal] =
+    useState<CreditInvoiceActionType | null>(null);
+  const [reason, setReason] = useState("");
+  const [paymentReference, setPaymentReference] = useState("");
+  const [decideApprove, setDecideApprove] = useState<boolean | null>(null);
+  const [decisionNote, setDecisionNote] = useState("");
+
+  const closeRequest = () => {
+    setRequestActionModal(null);
+    setReason("");
+    setPaymentReference("");
+  };
+  const closeDecide = () => {
+    setDecideApprove(null);
+    setDecisionNote("");
+  };
+
+  const { mutate: submitRequest, isPending: isRequesting } = useMutation(
+    api.shippingLineCredits.requestInvoiceAction.mutationOptions({
+      onSuccess: (_, variables) => {
+        closeRequest();
+        toast({
+          title: "Request submitted",
+          description: `${ACTION_LABEL[variables.action]} on ${invoice.invoiceNumber} now awaits a chief's approval.`,
+        });
+      },
+      onError: (err) =>
+        toast({
+          title: "Could not submit request",
+          description: err.message,
+          variant: "destructive",
+        }),
+    }),
+  );
+
+  const { mutate: submitDecision, isPending: isDeciding } = useMutation(
+    api.shippingLineCredits.decideInvoiceAction.mutationOptions({
+      onSuccess: (_, variables) => {
+        closeDecide();
+        toast({
+          title: variables.approve ? "Request approved" : "Request rejected",
+          description: variables.approve
+            ? pendingAction?.action === "MARK_PAID"
+              ? "The offline payment was recorded; the invoice and its credits are now paid."
+              : "The invoice was cancelled; its credits returned to the unbilled pool."
+            : "The request was rejected and nothing was changed.",
+        });
+      },
+      onError: (err) =>
+        toast({
+          title: "Could not decide request",
+          description: err.message,
+          variant: "destructive",
+        }),
+    }),
+  );
+
+  let body = null;
+  if (pendingAction) {
+    body = (
+      <Stack gap={6} py={4}>
+        <Badge variant="light" color="orange" title={pendingAction.reason}>
+          {ACTION_LABEL[pendingAction.action]} — awaiting approval
+        </Badge>
+        {canApprove || canReject ? (
+          <Group gap={6} wrap="nowrap">
+            {canApprove ? (
+              <Button
+                size="compact-xs"
+                color="edr-green"
+                leftSection={<Check size={12} />}
+                onClick={() => setDecideApprove(true)}
+              >
+                Approve
+              </Button>
+            ) : null}
+            {canReject ? (
+              <Button
+                size="compact-xs"
+                variant="outline"
+                color="red"
+                leftSection={<X size={12} />}
+                onClick={() => setDecideApprove(false)}
+              >
+                Reject
+              </Button>
+            ) : null}
+          </Group>
+        ) : null}
+      </Stack>
+    );
+  } else {
+    const showMarkPaid =
+      canRequestPaid && MARK_PAID_STATUSES.has(invoice.status);
+    const showCancel =
+      canRequestCancel &&
+      invoice.status !== "CANCELLED" &&
+      invoice.status !== "PAID" &&
+      invoice.status !== "REFUNDED" &&
+      Number(invoice.paidAmount) === 0;
+    body =
+      !showMarkPaid && !showCancel ? (
+        <Text size="sm" c="dimmed">
+          —
+        </Text>
+      ) : (
+        <Group gap={6} wrap="nowrap">
+          {showMarkPaid ? (
+            <Button
+              size="compact-xs"
+              variant="light"
+              color="edr-green"
+              leftSection={<HandCoins size={12} />}
+              onClick={() => setRequestActionModal("MARK_PAID")}
+            >
+              Mark paid
+            </Button>
+          ) : null}
+          {showCancel ? (
+            <Button
+              size="compact-xs"
+              variant="light"
+              color="red"
+              leftSection={<Ban size={12} />}
+              onClick={() => setRequestActionModal("CANCEL")}
+            >
+              Cancel
+            </Button>
+          ) : null}
+        </Group>
+      );
+  }
+
+  return (
+    <>
+      {body}
+
+      {/* Maker: raise the request. */}
+      <Modal
+        opened={requestAction !== null}
+        onClose={closeRequest}
+        title={
+          requestAction
+            ? `${ACTION_LABEL[requestAction]} — ${invoice.invoiceNumber}`
+            : ""
+        }
+        centered
+      >
+        <Stack gap="md">
+          <Text size="sm" c="dimmed">
+            {requestAction === "MARK_PAID"
+              ? "Records a full offline settlement of the outstanding balance. Takes effect only after a chief approves."
+              : "Voids the invoice and returns its credits to the unbilled pool. Takes effect only after a chief approves."}
+          </Text>
+          {requestAction === "MARK_PAID" ? (
+            <TextInput
+              label="Payment reference"
+              description="Bank slip / transfer number, if any."
+              value={paymentReference}
+              onChange={(e) => setPaymentReference(e.currentTarget.value)}
+            />
+          ) : null}
+          <Textarea
+            label="Reason"
+            withAsterisk
+            minRows={2}
+            placeholder={
+              requestAction === "MARK_PAID"
+                ? "Paid by bank transfer, slip #…"
+                : "Raised in error / rebilling with corrections…"
+            }
+            value={reason}
+            onChange={(e) => setReason(e.currentTarget.value)}
+          />
+          <Group justify="flex-end" gap="sm">
+            <Button
+              variant="default"
+              onClick={closeRequest}
+              disabled={isRequesting}
+            >
+              Cancel
+            </Button>
+            <Button
+              loading={isRequesting}
+              disabled={reason.trim().length < 3}
+              onClick={() =>
+                requestAction &&
+                submitRequest({
+                  invoiceId: invoice.id,
+                  action: requestAction,
+                  reason: reason.trim(),
+                  paymentReference: paymentReference.trim() || undefined,
+                })
+              }
+            >
+              Submit for approval
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
+
+      {/* Checker: decide the request. */}
+      <Modal
+        opened={decideApprove !== null}
+        onClose={closeDecide}
+        title={
+          pendingAction
+            ? `${decideApprove ? "Approve" : "Reject"}: ${ACTION_LABEL[pendingAction.action]} — ${invoice.invoiceNumber}`
+            : ""
+        }
+        centered
+      >
+        <Stack gap="md">
+          {pendingAction ? (
+            <Stack gap={4}>
+              <Text size="sm">
+                <Text component="span" c="dimmed">
+                  Requested reason:{" "}
+                </Text>
+                {pendingAction.reason}
+              </Text>
+              {pendingAction.paymentReference ? (
+                <Text size="sm">
+                  <Text component="span" c="dimmed">
+                    Payment reference:{" "}
+                  </Text>
+                  {pendingAction.paymentReference}
+                </Text>
+              ) : null}
+            </Stack>
+          ) : null}
+          {decideApprove && pendingAction ? (
+            <Text size="sm" c="dimmed">
+              {pendingAction.action === "MARK_PAID"
+                ? `Approving records ${formatMoney(
+                    Number(invoice.balanceAmount ?? invoice.totalAmount),
+                    invoice.currency,
+                  )} as paid offline and settles the invoice's credits.`
+                : "Approving cancels the invoice and returns its credits to the unbilled pool."}
+            </Text>
+          ) : null}
+          <Textarea
+            label={decideApprove ? "Note (optional)" : "Rejection note"}
+            withAsterisk={!decideApprove}
+            minRows={2}
+            value={decisionNote}
+            onChange={(e) => setDecisionNote(e.currentTarget.value)}
+          />
+          <Group justify="flex-end" gap="sm">
+            <Button
+              variant="default"
+              onClick={closeDecide}
+              disabled={isDeciding}
+            >
+              Back
+            </Button>
+            <Button
+              color={decideApprove ? "edr-green" : "red"}
+              loading={isDeciding}
+              disabled={!decideApprove && !decisionNote.trim()}
+              onClick={() =>
+                pendingAction &&
+                decideApprove !== null &&
+                submitDecision({
+                  approvalId: pendingAction.id,
+                  approve: decideApprove,
+                  note: decisionNote.trim() || undefined,
+                })
+              }
+            >
+              {decideApprove ? "Approve & execute" : "Reject request"}
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
+    </>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
index a51a6f135..1f09984a1 100644
--- a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
@@ -36,6 +36,40 @@ export const QUERY_KEYS = {
       ["shipping-line-companies", "detail", id] as const,
   },
 
+  SHIPPING_LINE_CREDITS: {
+    ROOT: ["shipping-line-credits"] as const,
+    invoices: (
+      page: number,
+      pageSize: number,
+      status?: string,
+      shippingLineId?: string,
+    ) =>
+      [
+        "shipping-line-credits",
+        "invoices",
+        shippingLineId ?? "all",
+        page,
+        pageSize,
+        status ?? "all",
+      ] as const,
+    summary: (shippingLineId?: string) =>
+      ["shipping-line-credits", "summary", shippingLineId ?? "all"] as const,
+    list: (
+      page: number,
+      pageSize: number,
+      status?: string,
+      shippingLineId?: string,
+    ) =>
+      [
+        "shipping-line-credits",
+        "list",
+        shippingLineId ?? "all",
+        page,
+        pageSize,
+        status ?? "all",
+      ] as const,
+  },
+
   CUSTOMERS: {
     ROOT: ["customers"] as const,
     stats: ["customers", "stats"] as const,
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index 71f80be3f..ea3d86d4f 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -88,6 +88,22 @@ export const URL_CONSTANTS = {
       `/shipping-line-companies/${id}/resend-activation`,
   },
 
+  /** Finance's view of what shipping lines owe (use now, pay later). */
+  SHIPPING_LINE_CREDITS: {
+    BASE: "/shipping-line-credits",
+    SUMMARY: "/shipping-line-credits/summary",
+    INVOICE: "/shipping-line-credits/invoice",
+    INVOICES: "/shipping-line-credits/invoices",
+    MARK_PAID_REQUEST: (invoiceId: string) =>
+      `/shipping-line-credits/invoices/${invoiceId}/mark-paid-request`,
+    CANCEL_REQUEST: (invoiceId: string) =>
+      `/shipping-line-credits/invoices/${invoiceId}/cancel-request`,
+    APPROVE_ACTION: (approvalId: string) =>
+      `/shipping-line-credits/invoice-actions/${approvalId}/approve`,
+    REJECT_ACTION: (approvalId: string) =>
+      `/shipping-line-credits/invoice-actions/${approvalId}/reject`,
+  },
+
   COMPANIES: {
     BASE: "/companies",
     STATS: "/companies/stats",
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index 8c7a1f84b..73c15fc86 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -129,6 +129,15 @@ export const FREIGHT_PERMS = {
     update: "edr_freight_app:shipping_lines:update",
     resetPassword: "edr_freight_app:shipping_lines:reset-password",
   },
+  shippingLineCredits: {
+    view: "edr_freight_app:shipping_line_credits:view",
+    invoice: "edr_freight_app:shipping_line_credits:invoice",
+    cancel: "edr_freight_app:shipping_line_credits:cancel",
+    invoiceMarkPaid: "edr_freight_app:shipping_line_credits:invoice_mark_paid",
+    invoiceCancel: "edr_freight_app:shipping_line_credits:invoice_cancel",
+    invoiceApprove: "edr_freight_app:shipping_line_credits:invoice_approve",
+    invoiceReject: "edr_freight_app:shipping_line_credits:invoice_reject",
+  },
   payments: {
     view: "edr_freight_app:payments:view",
   },
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
index afa4fa603..9074729f5 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
@@ -21,6 +21,7 @@ import {
   formatMoney,
   humanize,
 } from "@/components/customers";
+import CreditInvoiceActions from "@/components/shipping-lines/CreditInvoiceActions";
 import { api } from "@/services/api";
 import type { Invoice } from "@/types/invoice";
 import {
@@ -58,6 +59,26 @@ export default function InvoicesPanel() {
   const total = data?.total ?? 0;
   const pageCount = Math.max(1, Math.ceil(total / pagination.pageSize));
 
+  // Shipping-line credit invoices carry maker–checker actions (mark paid /
+  // cancel). One batched lookup fetches the visible rows' pending requests.
+  const creditInvoiceIds = useMemo(
+    () =>
+      rows
+        .filter((inv) => inv.source === "shipping_line_credit")
+        .map((inv) => inv.id),
+    [rows],
+  );
+  const { data: pendingActions } = useQuery(
+    api.shippingLineCredits.pendingInvoiceActions.queryOptions({
+      input: { invoiceIds: creditInvoiceIds },
+      enabled: creditInvoiceIds.length > 0,
+    }),
+  );
+  const pendingByInvoice = useMemo(
+    () => new Map((pendingActions ?? []).map((p) => [p.invoiceId, p])),
+    [pendingActions],
+  );
+
   const columns: ColumnDef<Invoice>[] = useMemo(
     () => [
       {
@@ -122,8 +143,30 @@ export default function InvoicesPanel() {
           </Text>
         ),
       },
+      {
+        id: "actions",
+        header: "Actions",
+        cell: ({ row }) => {
+          const inv = row.original;
+          // Only shipping-line credit invoices have manual maker–checker
+          // actions; every other source settles through its own flow.
+          if (inv.source !== "shipping_line_credit") {
+            return (
+              <Text size="sm" c="dimmed">
+                —
+              </Text>
+            );
+          }
+          return (
+            <CreditInvoiceActions
+              invoice={inv}
+              pendingAction={pendingByInvoice.get(inv.id) ?? null}
+            />
+          );
+        },
+      },
     ],
-    [],
+    [pendingByInvoice],
   );
 
   return (
diff --git a/apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCreditInvoicesPanel.tsx b/apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCreditInvoicesPanel.tsx
new file mode 100644
index 000000000..5dba366b6
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCreditInvoicesPanel.tsx
@@ -0,0 +1,279 @@
+import {
+  Badge,
+  Box,
+  Button,
+  Card,
+  Group,
+  Select,
+  Stack,
+  Text,
+} from "@mantine/core";
+import { useQuery } from "@tanstack/react-query";
+import { Calendar, FilterX, RefreshCw, Ship } from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { bookingTable } from "@/components/bookings/booking-ui.styles";
+import { formatDate, formatMoney } from "@/components/customers";
+import CreditInvoiceActions from "@/components/shipping-lines/CreditInvoiceActions";
+import { api } from "@/services/api";
+import type { CreditInvoice } from "@/types/shippingLineCredit";
+import {
+  DataTable,
+  DataTableFooter,
+  usePagination,
+  type ColumnDef,
+} from "@edr/ui-common";
+
+const INVOICE_STATUS_META: Record<string, { label: string; color: string }> = {
+  DRAFT: { label: "Draft", color: "gray" },
+  ISSUED: { label: "Issued", color: "orange" },
+  PENDING: { label: "Pending", color: "orange" },
+  PAYMENT_PROCESSING: { label: "Processing", color: "blue" },
+  PARTIALLY_PAID: { label: "Partially paid", color: "yellow" },
+  PAID: { label: "Paid", color: "green" },
+  OVERDUE: { label: "Overdue", color: "red" },
+  CANCELLED: { label: "Cancelled", color: "gray" },
+  REFUNDED: { label: "Refunded", color: "blue" },
+  EXPIRED: { label: "Expired", color: "red" },
+};
+
+const STATUS_OPTIONS = Object.entries(INVOICE_STATUS_META).map(
+  ([value, meta]) => ({ value, label: meta.label }),
+);
+
+/**
+ * Invoices minted from credit batches. The actions column is the shared
+ * maker–checker component (also embedded on the Finance hub's invoice list):
+ * finance requests mark-paid / cancel, a chief approves or rejects.
+ */
+export default function ShippingLineCreditInvoicesPanel() {
+  const { pagination, setPagination } = usePagination({ pageSize: 10 });
+  const [status, setStatus] = useState<string | null>(null);
+  const [shippingLineId, setShippingLineId] = useState<string | null>(null);
+
+  const { data: companies } = useQuery(
+    api.shippingLineCompanies.list.queryOptions({
+      input: { page: 1, limit: 100 },
+    }),
+  );
+  const lineOptions = useMemo(
+    () =>
+      (companies?.items ?? []).map((sl) => ({ value: sl.id, label: sl.name })),
+    [companies],
+  );
+
+  const { data, isLoading, isError, error, refetch, isFetching } = useQuery(
+    api.shippingLineCredits.listInvoices.queryOptions({
+      input: {
+        page: pagination.pageIndex + 1,
+        pageSize: pagination.pageSize,
+        status: status ?? undefined,
+        shippingLineId: shippingLineId ?? undefined,
+      },
+    }),
+  );
+
+  const rows = data?.items ?? [];
+  const total = data?.total ?? 0;
+  const pageCount = Math.max(1, Math.ceil(total / pagination.pageSize));
+  const activeFilterCount = (shippingLineId ? 1 : 0) + (status ? 1 : 0);
+
+  const resetPage = () =>
+    setPagination({ pageIndex: 0, pageSize: pagination.pageSize });
+
+  const columns: ColumnDef<CreditInvoice>[] = useMemo(
+    () => [
+      {
+        id: "invoice",
+        header: () => <span className={bookingTable.headerCell}>Invoice</span>,
+        cell: ({ row }) => {
+          const inv = row.original;
+          return (
+            <div className="flex items-center gap-3 py-1.5">
+              <div className={bookingTable.rowIcon}>
+                <Ship className="size-4" strokeWidth={1.75} />
+              </div>
+              <div className="min-w-0">
+                <p className="truncate font-mono text-sm font-semibold text-foreground">
+                  {inv.invoiceNumber}
+                </p>
+                <p className="mt-0.5 truncate text-xs text-muted-foreground">
+                  {inv.shippingLineName ?? "—"}
+                </p>
+              </div>
+            </div>
+          );
+        },
+      },
+      {
+        id: "issued",
+        header: () => <span className={bookingTable.headerCell}>Issued</span>,
+        cell: ({ row }) => (
+          <span className="inline-flex items-center gap-1.5 text-sm text-muted-foreground">
+            <Calendar className="size-3.5" />
+            {row.original.issuedAt ? formatDate(row.original.issuedAt) : "—"}
+          </span>
+        ),
+      },
+      {
+        id: "due",
+        header: () => <span className={bookingTable.headerCell}>Due</span>,
+        cell: ({ row }) => (
+          <span className="text-sm text-muted-foreground">
+            {row.original.dueAt ? formatDate(row.original.dueAt) : "—"}
+          </span>
+        ),
+      },
+      {
+        id: "amount",
+        header: () => <span className={bookingTable.headerCell}>Amount</span>,
+        cell: ({ row }) => (
+          <span className="text-sm font-semibold text-foreground">
+            {formatMoney(
+              Number(row.original.totalAmount),
+              row.original.currency,
+            )}
+          </span>
+        ),
+      },
+      {
+        id: "balance",
+        header: () => <span className={bookingTable.headerCell}>Balance</span>,
+        cell: ({ row }) => (
+          <span className="text-sm text-muted-foreground">
+            {formatMoney(
+              Number(row.original.balanceAmount ?? row.original.totalAmount),
+              row.original.currency,
+            )}
+          </span>
+        ),
+      },
+      {
+        id: "status",
+        header: () => <span className={bookingTable.headerCell}>Status</span>,
+        cell: ({ row }) => {
+          const meta = INVOICE_STATUS_META[row.original.status] ?? {
+            label: row.original.status,
+            color: "gray",
+          };
+          return (
+            <Badge variant="light" color={meta.color}>
+              {meta.label}
+            </Badge>
+          );
+        },
+      },
+      {
+        id: "actions",
+        header: () => <span className={bookingTable.headerCell}>Actions</span>,
+        cell: ({ row }) => (
+          <CreditInvoiceActions
+            invoice={row.original}
+            pendingAction={row.original.pendingAction}
+          />
+        ),
+      },
+    ],
+    [],
+  );
+
+  return (
+    <Stack gap="lg">
+      <Card p={0}>
+        <Stack gap={0}>
+          <Box px="md" pt="md" pb="sm" w="100%">
+            <Group justify="space-between" gap="md" wrap="wrap">
+              <Group gap="sm" wrap="wrap">
+                <Select
+                  placeholder="All shipping lines"
+                  data={lineOptions}
+                  value={shippingLineId}
+                  onChange={(v) => {
+                    setShippingLineId(v);
+                    resetPage();
+                  }}
+                  clearable
+                  searchable
+                  radius="lg"
+                  style={{ minWidth: 220 }}
+                />
+                <Select
+                  placeholder="All statuses"
+                  data={STATUS_OPTIONS}
+                  value={status}
+                  onChange={(v) => {
+                    setStatus(v);
+                    resetPage();
+                  }}
+                  clearable
+                  radius="lg"
+                  style={{ minWidth: 160 }}
+                />
+                {activeFilterCount > 0 ? (
+                  <Button
+                    variant="subtle"
+                    color="gray"
+                    radius="lg"
+                    leftSection={<FilterX size={16} />}
+                    onClick={() => {
+                      setShippingLineId(null);
+                      setStatus(null);
+                      resetPage();
+                    }}
+                  >
+                    Clear filters ({activeFilterCount})
+                  </Button>
+                ) : null}
+              </Group>
+              <Group gap="sm" wrap="nowrap">
+                <Text size="sm" c="dimmed">
+                  {total} record{total !== 1 ? "s" : ""}
+                </Text>
+                <Button
+                  variant="default"
+                  size="compact-sm"
+                  leftSection={<RefreshCw size={14} />}
+                  loading={isFetching}
+                  onClick={() => void refetch()}
+                >
+                  Refresh
+                </Button>
+              </Group>
+            </Group>
+          </Box>
+
+          <Box style={{ overflowX: "auto" }} w="100%">
+            <DataTable
+              columns={columns}
+              data={rows}
+              status={isLoading ? "loading" : isError ? "error" : "success"}
+              emptyMessage="No credit invoices yet — generate one from the Credits tab."
+              error={
+                isError
+                  ? {
+                      message: error?.message ?? "Failed to load invoices.",
+                      onRetry: () => void refetch(),
+                    }
+                  : undefined
+              }
+              pagination={{
+                pageIndex: pagination.pageIndex,
+                pageSize: pagination.pageSize,
+                pageCount,
+                totalCount: total,
+              }}
+              tableOptions={{
+                state: { pagination },
+                onPaginationChange: setPagination,
+                manualPagination: true,
+                pageCount,
+              }}
+              containerClassName="border-0 shadow-none bg-transparent"
+              footer={DataTableFooter}
+            />
+          </Box>
+        </Stack>
+      </Card>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCreditsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCreditsPage.tsx
new file mode 100644
index 000000000..aecaab753
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCreditsPage.tsx
@@ -0,0 +1,65 @@
+import { Stack, Tabs } from "@mantine/core";
+import { HandCoins, Receipt } from "lucide-react";
+import { useSearchParams } from "react-router-dom";
+
+import { PageContainer, PageHeader } from "@/components/page";
+
+import ShippingLineCreditInvoicesPanel from "./ShippingLineCreditInvoicesPanel";
+import ShippingLineCreditsPanel from "./ShippingLineCreditsPanel";
+
+/**
+ * Finance's view of what shipping lines owe. Two URL-linkable tabs (?tab=,
+ * FinanceHubPage convention): the credit ledger (select unbilled credits →
+ * generate an invoice) and the invoices minted from it (maker–checker
+ * mark-paid / cancel actions).
+ */
+export default function ShippingLineCreditsPage() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const activeTab =
+    searchParams.get("tab") === "invoices" ? "invoices" : "credits";
+
+  const handleTabChange = (value: string | null) => {
+    if (!value) return;
+    setSearchParams(
+      (prev) => {
+        const next = new URLSearchParams(prev);
+        next.set("tab", value);
+        return next;
+      },
+      { replace: true },
+    );
+  };
+
+  return (
+    <PageContainer>
+      <Stack gap="lg">
+        <PageHeader
+          title="Shipping Line Credits"
+          subtitle={
+            activeTab === "invoices"
+              ? "Invoices billed from credit batches. Manual mark-paid / cancel actions need a second approver."
+              : "What each line owes — outstanding totals and the full credit ledger."
+          }
+        />
+
+        <Tabs value={activeTab} onChange={handleTabChange} keepMounted={false}>
+          <Tabs.List>
+            <Tabs.Tab value="credits" leftSection={<HandCoins size={16} />}>
+              Credits
+            </Tabs.Tab>
+            <Tabs.Tab value="invoices" leftSection={<Receipt size={16} />}>
+              Invoices
+            </Tabs.Tab>
+          </Tabs.List>
+
+          <Tabs.Panel value="credits" pt="lg">
+            <ShippingLineCreditsPanel />
+          </Tabs.Panel>
+          <Tabs.Panel value="invoices" pt="lg">
+            <ShippingLineCreditInvoicesPanel />
+          </Tabs.Panel>
+        </Tabs>
+      </Stack>
+    </PageContainer>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCreditsPanel.tsx b/apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCreditsPanel.tsx
new file mode 100644
index 000000000..b4c01ab43
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/shipping-lines/ShippingLineCreditsPanel.tsx
@@ -0,0 +1,553 @@
+import {
+  Badge,
+  Box,
+  Button,
+  Card,
+  Checkbox,
+  Divider,
+  Group,
+  Modal,
+  NumberInput,
+  Select,
+  Stack,
+  Text,
+} from "@mantine/core";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import {
+  Calendar,
+  Clock,
+  FilterX,
+  HandCoins,
+  Receipt,
+  RefreshCw,
+  Ship,
+} from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { useAuth } from "@/auth/useAuth";
+import { bookingTable } from "@/components/bookings/booking-ui.styles";
+import { formatDate, formatMoney } from "@/components/customers";
+import { KpiStrip } from "@/components/page";
+import { useToast } from "@/hooks/use-toast";
+import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
+import { api } from "@/services/api";
+import type {
+  ShippingLineCredit,
+  ShippingLineCreditStatus,
+} from "@/types/shippingLineCredit";
+import {
+  DataTable,
+  DataTableFooter,
+  usePagination,
+  type ColumnDef,
+} from "@edr/ui-common";
+
+const STATUS_META: Record<
+  ShippingLineCreditStatus,
+  { label: string; color: string }
+> = {
+  UNBILLED: { label: "Unbilled", color: "orange" },
+  BILLED: { label: "Billed", color: "blue" },
+  PAID: { label: "Paid", color: "green" },
+  CANCELLED: { label: "Cancelled", color: "gray" },
+};
+
+const STATUS_OPTIONS = Object.entries(STATUS_META).map(([value, meta]) => ({
+  value,
+  label: meta.label,
+}));
+
+/**
+ * Every shipping line's credits in one list — finance's landing view, styled
+ * to match the booking-requests page. Summary cells total the current filter
+ * scope (all lines by default); the selects narrow both cells and ledger.
+ */
+export default function ShippingLineCreditsPanel() {
+  const { user } = useAuth();
+  const { toast } = useToast();
+  const [shippingLineId, setShippingLineId] = useState<string | null>(null);
+  const [status, setStatus] = useState<ShippingLineCreditStatus | null>(null);
+  const { pagination, setPagination } = usePagination({ pageSize: 10 });
+
+  const canInvoice = hasPermission(
+    user,
+    FREIGHT_PERMS.shippingLineCredits.invoice,
+  );
+
+  // Selection for batch invoicing, kept as id → credit so it survives page
+  // changes and can total itself. One invoice has one payer, so everything
+  // selected must belong to the same shipping line — enforced here so the
+  // API's rejection is never the first time staff hears about it.
+  const [selected, setSelected] = useState<Map<string, ShippingLineCredit>>(
+    new Map(),
+  );
+  const [invoiceOpen, setInvoiceOpen] = useState(false);
+  const [dueInDays, setDueInDays] = useState<number | "">("");
+
+  const selectedCredits = useMemo(() => [...selected.values()], [selected]);
+  const selectedLineId = selectedCredits[0]?.shippingLineCompanyId ?? null;
+  const selectedTotal = selectedCredits.reduce(
+    (sum, c) => sum + Number(c.amount),
+    0,
+  );
+
+  const toggleSelected = (credit: ShippingLineCredit) =>
+    setSelected((prev) => {
+      const next = new Map(prev);
+      if (next.has(credit.id)) next.delete(credit.id);
+      else next.set(credit.id, credit);
+      return next;
+    });
+
+  const clearSelection = () => setSelected(new Map());
+
+  // ponytail: first 100 lines in the picker; server-side search when a real
+  // deployment outgrows that.
+  const { data: companies } = useQuery(
+    api.shippingLineCompanies.list.queryOptions({
+      input: { page: 1, limit: 100 },
+    }),
+  );
+
+  const lineOptions = useMemo(
+    () =>
+      (companies?.items ?? []).map((sl) => ({
+        value: sl.id,
+        label: sl.scacCode ? `${sl.name} (${sl.scacCode})` : sl.name,
+      })),
+    [companies],
+  );
+
+  const {
+    data: summary,
+    isLoading: summaryLoading,
+    refetch: refetchSummary,
+  } = useQuery(
+    api.shippingLineCredits.summary.queryOptions({
+      input: { shippingLineId: shippingLineId ?? undefined },
+    }),
+  );
+
+  const {
+    data: ledger,
+    isLoading,
+    isError,
+    error,
+    refetch,
+    isFetching,
+  } = useQuery(
+    api.shippingLineCredits.list.queryOptions({
+      input: {
+        page: pagination.pageIndex + 1,
+        pageSize: pagination.pageSize,
+        status: status ?? undefined,
+        shippingLineId: shippingLineId ?? undefined,
+      },
+    }),
+  );
+
+  const rows = ledger?.items ?? [];
+  const total = ledger?.total ?? 0;
+  const pageCount = Math.max(1, Math.ceil(total / pagination.pageSize));
+  const activeFilterCount = (shippingLineId ? 1 : 0) + (status ? 1 : 0);
+
+  const resetPage = () =>
+    setPagination({ pageIndex: 0, pageSize: pagination.pageSize });
+
+  const clearFilters = () => {
+    setShippingLineId(null);
+    setStatus(null);
+    resetPage();
+  };
+
+  const handleRefresh = () => {
+    void refetch();
+    void refetchSummary();
+  };
+
+  const { mutate: generateInvoice, isPending: isInvoicing } = useMutation(
+    api.shippingLineCredits.generateInvoice.mutationOptions({
+      onSuccess: (invoice) => {
+        setInvoiceOpen(false);
+        clearSelection();
+        setDueInDays("");
+        toast({
+          title: `Invoice ${invoice.invoiceNumber} generated`,
+          description: `${formatMoney(Number(invoice.totalAmount), invoice.currency)} billed across ${selectedCredits.length} credit${selectedCredits.length === 1 ? "" : "s"}.`,
+        });
+      },
+      onError: (err) => {
+        toast({
+          title: "Could not generate invoice",
+          description: err.message,
+          variant: "destructive",
+        });
+        // A concurrent edit (someone else billed a selected credit) is the
+        // usual cause — resync so stale rows drop out of the list.
+        handleRefresh();
+      },
+    }),
+  );
+
+  const columns: ColumnDef<ShippingLineCredit>[] = useMemo(
+    () => [
+      ...(canInvoice
+        ? [
+            {
+              id: "select",
+              size: 40,
+              header: () => null,
+              cell: ({ row }: { row: { original: ShippingLineCredit } }) => {
+                const credit = row.original;
+                const selectable =
+                  credit.status === "UNBILLED" &&
+                  (selectedLineId === null ||
+                    credit.shippingLineCompanyId === selectedLineId);
+                return (
+                  <Checkbox
+                    size="sm"
+                    checked={selected.has(credit.id)}
+                    disabled={!selectable}
+                    title={
+                      credit.status !== "UNBILLED"
+                        ? "Only unbilled credits can be invoiced"
+                        : !selectable
+                          ? "One invoice has one payer — selection already holds another line's credits"
+                          : undefined
+                    }
+                    onChange={() => toggleSelected(credit)}
+                    aria-label="Select credit for invoicing"
+                  />
+                );
+              },
+            },
+          ]
+        : []),
+      {
+        id: "shippingLine",
+        header: () => (
+          <span className={bookingTable.headerCell}>Shipping line</span>
+        ),
+        cell: ({ row }) => {
+          const credit = row.original;
+          return (
+            <div className="flex items-center gap-3 py-1.5">
+              <div className={bookingTable.rowIcon}>
+                <Ship className="size-4" strokeWidth={1.75} />
+              </div>
+              <div className="min-w-0">
+                <p className="truncate font-medium text-foreground">
+                  {credit.shippingLineCompany?.name ?? "—"}
+                </p>
+                <p className="mt-0.5 truncate font-mono text-xs text-muted-foreground">
+                  {credit.booking?.reference ?? "—"}
+                </p>
+              </div>
+            </div>
+          );
+        },
+      },
+      {
+        id: "description",
+        header: () => (
+          <span className={bookingTable.headerCell}>Description</span>
+        ),
+        cell: ({ row }) => (
+          <span className="block max-w-[16rem] truncate py-1 text-sm text-muted-foreground">
+            {row.original.description ?? "—"}
+          </span>
+        ),
+      },
+      {
+        id: "amount",
+        header: () => <span className={bookingTable.headerCell}>Amount</span>,
+        cell: ({ row }) => (
+          <span className="text-sm font-semibold text-foreground">
+            {formatMoney(Number(row.original.amount), row.original.currency)}
+          </span>
+        ),
+      },
+      {
+        id: "status",
+        header: () => <span className={bookingTable.headerCell}>Status</span>,
+        cell: ({ row }) => {
+          const meta = STATUS_META[row.original.status];
+          return (
+            <Badge variant="light" color={meta.color}>
+              {meta.label}
+            </Badge>
+          );
+        },
+      },
+      {
+        id: "invoice",
+        header: () => <span className={bookingTable.headerCell}>Invoice</span>,
+        cell: ({ row }) => {
+          const inv = row.original.invoice;
+          return inv ? (
+            <span className="truncate font-mono text-xs text-foreground">
+              {inv.invoiceNumber}
+            </span>
+          ) : (
+            <span className="text-xs text-muted-foreground">—</span>
+          );
+        },
+      },
+      {
+        id: "createdAt",
+        header: () => <span className={bookingTable.headerCell}>Recorded</span>,
+        cell: ({ row }) => (
+          <span className="inline-flex items-center gap-1.5 text-sm text-muted-foreground">
+            <Calendar className="size-3.5" />
+            {formatDate(row.original.createdAt)}
+          </span>
+        ),
+      },
+    ],
+    // Selection state drives the checkbox column's checked/disabled rendering.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [canInvoice, selected, selectedLineId],
+  );
+
+  return (
+    <Stack gap="lg">
+      <KpiStrip
+        loading={summaryLoading}
+        items={[
+          {
+            label: "Total outstanding",
+            value: summary
+              ? formatMoney(summary.totalOutstanding, summary.currency)
+              : "—",
+            hint: "unbilled + billed",
+            icon: HandCoins,
+            color: "edr-green",
+          },
+          {
+            label: "Unbilled",
+            value: summary
+              ? formatMoney(summary.unbilledAmount, summary.currency)
+              : "—",
+            hint: summary ? `${summary.unbilledCount} credits` : undefined,
+            icon: Clock,
+            color: "yellow",
+          },
+          {
+            label: "Billed",
+            value: summary
+              ? formatMoney(summary.billedAmount, summary.currency)
+              : "—",
+            hint: summary ? `${summary.billedCount} on invoices` : undefined,
+            icon: Receipt,
+            color: "blue",
+          },
+        ]}
+      />
+
+      <Card p={0}>
+        <Stack gap={0}>
+          <Box px="md" pt="md" pb="sm" w="100%">
+            <Group justify="space-between" gap="md" wrap="wrap">
+              <Group gap="sm" wrap="wrap">
+                <Select
+                  placeholder="All shipping lines"
+                  data={lineOptions}
+                  value={shippingLineId}
+                  onChange={(v) => {
+                    setShippingLineId(v);
+                    resetPage();
+                  }}
+                  clearable
+                  searchable
+                  radius="lg"
+                  style={{ minWidth: 220 }}
+                />
+                <Select
+                  placeholder="All statuses"
+                  data={STATUS_OPTIONS}
+                  value={status}
+                  onChange={(v) => {
+                    setStatus((v as ShippingLineCreditStatus | null) ?? null);
+                    resetPage();
+                  }}
+                  clearable
+                  radius="lg"
+                  style={{ minWidth: 160 }}
+                />
+                {activeFilterCount > 0 ? (
+                  <Button
+                    variant="subtle"
+                    color="gray"
+                    radius="lg"
+                    leftSection={<FilterX size={16} />}
+                    onClick={clearFilters}
+                  >
+                    Clear filters ({activeFilterCount})
+                  </Button>
+                ) : null}
+              </Group>
+              <Group gap="sm" wrap="nowrap">
+                <Text size="sm" c="dimmed">
+                  {total} record{total !== 1 ? "s" : ""}
+                </Text>
+                <Button
+                  variant="default"
+                  size="compact-sm"
+                  leftSection={<RefreshCw size={14} />}
+                  loading={isFetching}
+                  onClick={handleRefresh}
+                >
+                  Refresh
+                </Button>
+              </Group>
+            </Group>
+          </Box>
+
+          {selectedCredits.length > 0 ? (
+            <>
+              <Divider />
+              <Group
+                px="md"
+                py="sm"
+                justify="space-between"
+                wrap="wrap"
+                bg="var(--mantine-color-edr-green-0)"
+              >
+                <Text size="sm" fw={600}>
+                  {selectedCredits.length} credit
+                  {selectedCredits.length === 1 ? "" : "s"} selected ·{" "}
+                  {formatMoney(selectedTotal, selectedCredits[0].currency)}
+                  {" — "}
+                  {selectedCredits[0].shippingLineCompany?.name ?? ""}
+                </Text>
+                <Group gap="sm">
+                  <Button
+                    variant="subtle"
+                    color="gray"
+                    size="compact-sm"
+                    onClick={clearSelection}
+                  >
+                    Clear selection
+                  </Button>
+                  <Button
+                    size="compact-sm"
+                    leftSection={<Receipt size={14} />}
+                    onClick={() => setInvoiceOpen(true)}
+                  >
+                    Generate invoice
+                  </Button>
+                </Group>
+              </Group>
+            </>
+          ) : null}
+
+          <Box style={{ overflowX: "auto" }} w="100%">
+            <DataTable
+              columns={columns}
+              data={rows}
+              status={isLoading ? "loading" : isError ? "error" : "success"}
+              emptyMessage="No credits match this filter."
+              error={
+                isError
+                  ? {
+                      message: error?.message ?? "Failed to load credits.",
+                      onRetry: () => void refetch(),
+                    }
+                  : undefined
+              }
+              pagination={{
+                pageIndex: pagination.pageIndex,
+                pageSize: pagination.pageSize,
+                pageCount,
+                totalCount: total,
+              }}
+              tableOptions={{
+                state: { pagination },
+                onPaginationChange: setPagination,
+                manualPagination: true,
+                pageCount,
+              }}
+              containerClassName="border-0 shadow-none bg-transparent"
+              footer={DataTableFooter}
+            />
+          </Box>
+        </Stack>
+      </Card>
+
+      <Modal
+        opened={invoiceOpen}
+        onClose={() => setInvoiceOpen(false)}
+        title="Generate invoice"
+        centered
+      >
+        <Stack gap="md">
+          <Text size="sm" c="dimmed">
+            One invoice for{" "}
+            <Text component="span" fw={600} c="edr-text">
+              {selectedCredits[0]?.shippingLineCompany?.name ?? "this line"}
+            </Text>{" "}
+            billing the selected credits. The line pays it at any CBE channel —
+            there is no payment window.
+          </Text>
+
+          <Stack gap={6}>
+            {selectedCredits.map((credit) => (
+              <Group key={credit.id} justify="space-between" wrap="nowrap">
+                <Text size="sm" truncate>
+                  {credit.booking?.reference ?? credit.description ?? credit.id}
+                </Text>
+                <Text size="sm" fw={500} style={{ whiteSpace: "nowrap" }}>
+                  {formatMoney(Number(credit.amount), credit.currency)}
+                </Text>
+              </Group>
+            ))}
+            <Divider my={4} />
+            <Group justify="space-between">
+              <Text size="sm" fw={700}>
+                Total
+              </Text>
+              <Text size="sm" fw={700}>
+                {formatMoney(
+                  selectedTotal,
+                  selectedCredits[0]?.currency ?? "ETB",
+                )}
+              </Text>
+            </Group>
+          </Stack>
+
+          <NumberInput
+            label="Due in days"
+            description="Optional — defaults to the standard invoice term."
+            placeholder="14"
+            min={1}
+            value={dueInDays}
+            onChange={(v) => setDueInDays(typeof v === "number" ? v : "")}
+          />
+
+          <Group justify="flex-end" gap="sm">
+            <Button
+              variant="default"
+              onClick={() => setInvoiceOpen(false)}
+              disabled={isInvoicing}
+            >
+              Cancel
+            </Button>
+            <Button
+              loading={isInvoicing}
+              onClick={() =>
+                generateInvoice({
+                  creditIds: selectedCredits.map((c) => c.id),
+                  ...(typeof dueInDays === "number"
+                    ? { dueInDays }
+                    : {}),
+                })
+              }
+            >
+              Generate &amp; issue
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 69e47b8ee..78efb2e4b 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -50,6 +50,14 @@ import type {
   RegisterShippingLineCompanyResult,
   ShippingLineCompany,
 } from "@/types/shippingLineCompany";
+import type {
+  CreditInvoicePendingAction,
+  GeneratedCreditInvoice,
+  OutstandingTotals,
+  PaginatedCreditInvoices,
+  PaginatedShippingLineCredits,
+  ShippingLineCreditStatus,
+} from "@/types/shippingLineCredit";
 import {
   RuleEngineListResult,
   RuleEngineRecord,
@@ -163,6 +171,7 @@ import { containerTypesService } from "./container-types.service";
 import { containerService, type Container } from "./containerService";
 import { customersService } from "./customers.service";
 import { shippingLineCompaniesService } from "./shippingLineCompanies.service";
+import { shippingLineCreditsService } from "./shippingLineCredits.service";
 import { eimsService } from "./eims.service";
 import type { EimsInvoiceStatusView, EimsVerifyResult } from "@/types/eims";
 import { invoicesService } from "./invoices.service";
@@ -2836,6 +2845,123 @@ export const api = {
     ),
   },
 
+  shippingLineCredits: {
+    summary: endpoint<{ shippingLineId?: string }, OutstandingTotals>(
+      "shippingLineCredits",
+      "summary",
+      ({ shippingLineId }) => shippingLineCreditsService.summary(shippingLineId),
+      ({ shippingLineId }) =>
+        QUERY_KEYS.SHIPPING_LINE_CREDITS.summary(shippingLineId),
+    ),
+
+    list: endpoint<
+      {
+        page: number;
+        pageSize: number;
+        status?: ShippingLineCreditStatus;
+        shippingLineId?: string;
+      },
+      PaginatedShippingLineCredits
+    >(
+      "shippingLineCredits",
+      "list",
+      (filter) => shippingLineCreditsService.list(filter),
+      ({ page, pageSize, status, shippingLineId }) =>
+        QUERY_KEYS.SHIPPING_LINE_CREDITS.list(
+          page,
+          pageSize,
+          status,
+          shippingLineId,
+        ),
+    ),
+
+    generateInvoice: endpoint<
+      { creditIds: string[]; dueInDays?: number },
+      GeneratedCreditInvoice
+    >(
+      "shippingLineCredits",
+      "generateInvoice",
+      ({ creditIds, dueInDays }) =>
+        shippingLineCreditsService.generateInvoice(creditIds, dueInDays),
+      undefined,
+      // Billing a batch changes ledger rows, the summary totals and (via the
+      // draft invoice) the invoices list.
+      () => [QUERY_KEYS.SHIPPING_LINE_CREDITS.ROOT, QUERY_KEYS.INVOICES.ROOT],
+    ),
+
+    listInvoices: endpoint<
+      {
+        page: number;
+        pageSize: number;
+        status?: string;
+        shippingLineId?: string;
+      },
+      PaginatedCreditInvoices
+    >(
+      "shippingLineCredits",
+      "listInvoices",
+      (filter) => shippingLineCreditsService.listInvoices(filter),
+      ({ page, pageSize, status, shippingLineId }) =>
+        QUERY_KEYS.SHIPPING_LINE_CREDITS.invoices(
+          page,
+          pageSize,
+          status,
+          shippingLineId,
+        ),
+    ),
+
+    pendingInvoiceActions: endpoint<
+      { invoiceIds: string[] },
+      CreditInvoicePendingAction[]
+    >(
+      "shippingLineCredits",
+      "pendingInvoiceActions",
+      ({ invoiceIds }) =>
+        shippingLineCreditsService.pendingInvoiceActions(invoiceIds),
+      ({ invoiceIds }) =>
+        [
+          "shipping-line-credits",
+          "pending-actions",
+          [...invoiceIds].sort().join(","),
+        ] as const,
+    ),
+
+    requestInvoiceAction: endpoint<
+      {
+        invoiceId: string;
+        action: "MARK_PAID" | "CANCEL";
+        reason: string;
+        paymentReference?: string;
+      },
+      CreditInvoicePendingAction
+    >(
+      "shippingLineCredits",
+      "requestInvoiceAction",
+      ({ invoiceId, action, reason, paymentReference }) =>
+        shippingLineCreditsService.requestInvoiceAction(
+          invoiceId,
+          action,
+          reason,
+          paymentReference,
+        ),
+      undefined,
+      () => [QUERY_KEYS.SHIPPING_LINE_CREDITS.ROOT],
+    ),
+
+    decideInvoiceAction: endpoint<
+      { approvalId: string; approve: boolean; note?: string },
+      CreditInvoicePendingAction
+    >(
+      "shippingLineCredits",
+      "decideInvoiceAction",
+      ({ approvalId, approve, note }) =>
+        shippingLineCreditsService.decideInvoiceAction(approvalId, approve, note),
+      undefined,
+      // Approving executes a billing action, so both surfaces move.
+      () => [QUERY_KEYS.SHIPPING_LINE_CREDITS.ROOT, QUERY_KEYS.INVOICES.ROOT],
+    ),
+  },
+
   customers: {
     stats: endpoint<Record<string, never>, CompanyStats>(
       "customers",
diff --git a/apps/edr-freight-web/backoffice/src/services/shippingLineCredits.service.ts b/apps/edr-freight-web/backoffice/src/services/shippingLineCredits.service.ts
new file mode 100644
index 000000000..7f726a10b
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/services/shippingLineCredits.service.ts
@@ -0,0 +1,131 @@
+import { api as apiClient } from "@/auth/http";
+import { URL_CONSTANTS } from "@/constants/URLS";
+import type {
+  CreditInvoicePendingAction,
+  GeneratedCreditInvoice,
+  OutstandingTotals,
+  PaginatedCreditInvoices,
+  PaginatedShippingLineCredits,
+  ShippingLineCreditStatus,
+} from "@/types/shippingLineCredit";
+
+export interface ShippingLineCreditListFilter {
+  page?: number;
+  pageSize?: number;
+  status?: ShippingLineCreditStatus;
+  /** Narrow to one line; omit for all lines. */
+  shippingLineId?: string;
+}
+
+export const shippingLineCreditsService = {
+  /** Outstanding totals — every line, or one line when an id is given. */
+  summary(shippingLineId?: string): Promise<OutstandingTotals> {
+    return apiClient
+      .get<OutstandingTotals>(URL_CONSTANTS.SHIPPING_LINE_CREDITS.SUMMARY, {
+        params: shippingLineId ? { shippingLineId } : {},
+      })
+      .then((r) => r.data);
+  },
+
+  /** The whole credit ledger, newest first, optionally filtered. */
+  list(
+    filter: ShippingLineCreditListFilter = {},
+  ): Promise<PaginatedShippingLineCredits> {
+    const { page = 1, pageSize = 20, status, shippingLineId } = filter;
+    return apiClient
+      .get<PaginatedShippingLineCredits>(
+        URL_CONSTANTS.SHIPPING_LINE_CREDITS.BASE,
+        {
+          params: {
+            page,
+            pageSize,
+            ...(status ? { status } : {}),
+            ...(shippingLineId ? { shippingLineId } : {}),
+          },
+        },
+      )
+      .then((r) => r.data);
+  },
+
+  /**
+   * Bill a batch of unbilled credits as one invoice. The API enforces that all
+   * credits belong to one shipping line and share one currency.
+   */
+  generateInvoice(
+    creditIds: string[],
+    dueInDays?: number,
+  ): Promise<GeneratedCreditInvoice> {
+    return apiClient
+      .post<GeneratedCreditInvoice>(URL_CONSTANTS.SHIPPING_LINE_CREDITS.INVOICE, {
+        creditIds,
+        ...(dueInDays ? { dueInDays } : {}),
+      })
+      .then((r) => r.data);
+  },
+
+  /** Credit invoices with any pending manual-action request attached. */
+  listInvoices(filter: {
+    page?: number;
+    pageSize?: number;
+    status?: string;
+    shippingLineId?: string;
+  } = {}): Promise<PaginatedCreditInvoices> {
+    const { page = 1, pageSize = 20, status, shippingLineId } = filter;
+    return apiClient
+      .get<PaginatedCreditInvoices>(URL_CONSTANTS.SHIPPING_LINE_CREDITS.INVOICES, {
+        params: {
+          page,
+          pageSize,
+          ...(status ? { status } : {}),
+          ...(shippingLineId ? { shippingLineId } : {}),
+        },
+      })
+      .then((r) => r.data);
+  },
+
+  /** Undecided manual-action requests for a batch of invoice ids. */
+  pendingInvoiceActions(
+    invoiceIds: string[],
+  ): Promise<CreditInvoicePendingAction[]> {
+    if (!invoiceIds.length) return Promise.resolve([]);
+    return apiClient
+      .get<CreditInvoicePendingAction[]>(
+        `${URL_CONSTANTS.SHIPPING_LINE_CREDITS.BASE}/invoice-actions/pending`,
+        { params: { invoiceIds: invoiceIds.join(",") } },
+      )
+      .then((r) => r.data);
+  },
+
+  /** Maker step: raise a mark-paid or cancel request on a credit invoice. */
+  requestInvoiceAction(
+    invoiceId: string,
+    action: "MARK_PAID" | "CANCEL",
+    reason: string,
+    paymentReference?: string,
+  ): Promise<CreditInvoicePendingAction> {
+    const url =
+      action === "MARK_PAID"
+        ? URL_CONSTANTS.SHIPPING_LINE_CREDITS.MARK_PAID_REQUEST(invoiceId)
+        : URL_CONSTANTS.SHIPPING_LINE_CREDITS.CANCEL_REQUEST(invoiceId);
+    return apiClient
+      .post<CreditInvoicePendingAction>(url, {
+        reason,
+        ...(paymentReference ? { paymentReference } : {}),
+      })
+      .then((r) => r.data);
+  },
+
+  /** Decision step: approve (executes) or reject a pending request. */
+  decideInvoiceAction(
+    approvalId: string,
+    approve: boolean,
+    note?: string,
+  ): Promise<CreditInvoicePendingAction> {
+    const url = approve
+      ? URL_CONSTANTS.SHIPPING_LINE_CREDITS.APPROVE_ACTION(approvalId)
+      : URL_CONSTANTS.SHIPPING_LINE_CREDITS.REJECT_ACTION(approvalId);
+    return apiClient
+      .post<CreditInvoicePendingAction>(url, note ? { note } : {})
+      .then((r) => r.data);
+  },
+};
diff --git a/apps/edr-freight-web/backoffice/src/types/booking.ts b/apps/edr-freight-web/backoffice/src/types/booking.ts
index e1c6b2cd6..b4b154800 100644
--- a/apps/edr-freight-web/backoffice/src/types/booking.ts
+++ b/apps/edr-freight-web/backoffice/src/types/booking.ts
@@ -90,6 +90,9 @@ export interface BookingContainerLine {
   containerNumber?: string | null;
   quantity: number;
   vgmPerUnitTons: number;
+  /** How many of this line are hazardous / refrigerated — 0 when none. */
+  hazardousQuantity?: number;
+  reeferQuantity?: number;
   containerType?: {
     id: string;
     code?: string;
@@ -199,6 +202,7 @@ export interface BookingDetail {
   /** Break-bulk (PER_ITEM) only: real total tons — cargoTotalWeightVgm then holds the item count. */
   bulkTotalWeightTons?: number | null;
   isHazardous: boolean;
+  isReefer?: boolean;
   consolidationPartnerId?: string | null;
   consolidationPartner?: BookingNamedRef & { reference?: string } | null;
   priorityScore: number;
diff --git a/apps/edr-freight-web/backoffice/src/types/shippingLineCredit.ts b/apps/edr-freight-web/backoffice/src/types/shippingLineCredit.ts
new file mode 100644
index 000000000..3b7b936e0
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/types/shippingLineCredit.ts
@@ -0,0 +1,96 @@
+/**
+ * The credit ledger for shipping lines — "use the service now, pay later".
+ * Mirrors `shipping-line-credits` API responses.
+ */
+
+export type ShippingLineCreditStatus =
+  | "UNBILLED"
+  | "BILLED"
+  | "PAID"
+  | "CANCELLED";
+
+export interface ShippingLineCredit {
+  id: string;
+  shippingLineCompanyId: string;
+  bookingId: string;
+  /** Numeric column — serialized as a string by the API. */
+  amount: string;
+  currency: string;
+  status: ShippingLineCreditStatus;
+  description: string | null;
+  invoiceId: string | null;
+  billedAt: string | null;
+  paidAt: string | null;
+  cancelledAt: string | null;
+  cancellationReason: string | null;
+  createdAt: string;
+  booking?: { id: string; reference: string } | null;
+  invoice?: { id: string; invoiceNumber: string } | null;
+  shippingLineCompany?: { id: string; name: string } | null;
+}
+
+/** What one shipping line currently owes, split by billing stage. */
+export interface OutstandingTotals {
+  unbilledAmount: number;
+  billedAmount: number;
+  totalOutstanding: number;
+  unbilledCount: number;
+  billedCount: number;
+  currency: string;
+}
+
+export interface PaginatedShippingLineCredits {
+  items: ShippingLineCredit[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+/** The invoice minted from a batch of unbilled credits (subset of fields). */
+export interface GeneratedCreditInvoice {
+  id: string;
+  invoiceNumber: string;
+  totalAmount: string | number;
+  currency: string;
+  status: string;
+  dueDate: string | null;
+}
+
+export type CreditInvoiceActionType = "MARK_PAID" | "CANCEL";
+export type CreditInvoiceActionStatus = "PENDING" | "APPROVED" | "REJECTED";
+
+/** An undecided manual-action request attached to a credit invoice. */
+export interface CreditInvoicePendingAction {
+  id: string;
+  invoiceId: string;
+  action: CreditInvoiceActionType;
+  status: CreditInvoiceActionStatus;
+  requestedBy: string;
+  reason: string;
+  paymentReference: string | null;
+  createdAt: string;
+}
+
+/** A credit invoice row in the staff list, enriched by the API. */
+export interface CreditInvoice {
+  id: string;
+  invoiceNumber: string;
+  status: string;
+  currency: string;
+  totalAmount: string | number;
+  paidAmount: string | number;
+  balanceAmount: string | number;
+  issuedAt: string | null;
+  dueAt: string | null;
+  createdAt: string;
+  shippingLineCompanyId: string | null;
+  shippingLineName: string | null;
+  pendingAction: CreditInvoicePendingAction | null;
+}
+
+export interface PaginatedCreditInvoices {
+  items: CreditInvoice[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
diff --git a/apps/edr-freight-web/portal/src/App.tsx b/apps/edr-freight-web/portal/src/App.tsx
index 38d347d3a..bd20dfc71 100644
--- a/apps/edr-freight-web/portal/src/App.tsx
+++ b/apps/edr-freight-web/portal/src/App.tsx
@@ -62,6 +62,7 @@ import PaymentSuccessPage from "./pages/payments/PaymentSuccessPage";
 import {
   ShippingLineBookingDetailPage,
   ShippingLineBookingsPage,
+  ShippingLineCompletePage,
   ShippingLineHelpPage,
   ShippingLineHomePage,
   ShippingLineInvoicesPage,
@@ -439,10 +440,21 @@ const App = () => {
                   path="/shipping-line/bookings/:id"
                   element={<ShippingLineBookingDetailPage />}
                 />
+                <Route
+                  path="/shipping-line/bookings/:id/complete"
+                  element={<ShippingLineCompletePage />}
+                />
                 <Route
                   path="/shipping-line/invoices"
                   element={<ShippingLineInvoicesPage />}
                 />
+                {/* Same detail component as the customer's /billing/:id — the
+                    API scopes my-invoices to the signed-in payer either way,
+                    and the page derives its back target from the URL. */}
+                <Route
+                  path="/shipping-line/invoices/:id"
+                  element={<InvoiceDetailPage />}
+                />
                 <Route
                   path="/shipping-line/settings"
                   element={<ShippingLineSettingsPage />}
diff --git a/apps/edr-freight-web/portal/src/pages/billing/InvoiceDetailPage.tsx b/apps/edr-freight-web/portal/src/pages/billing/InvoiceDetailPage.tsx
index 78116013e..b42a3cc8e 100644
--- a/apps/edr-freight-web/portal/src/pages/billing/InvoiceDetailPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/billing/InvoiceDetailPage.tsx
@@ -1,5 +1,5 @@
 import { useState } from "react";
-import { useNavigate, useParams } from "react-router-dom";
+import { useLocation, useNavigate, useParams } from "react-router-dom";
 import { useQuery } from "@tanstack/react-query";
 import {
   Alert,
@@ -59,6 +59,11 @@ function MetaItem({ label, value }: { label: string; value: string }) {
 export default function InvoiceDetailPage() {
   const { id = "" } = useParams();
   const navigate = useNavigate();
+  // Mounted at /billing/:id (customer) and /shipping-line/invoices/:id — the
+  // back target follows whichever list the reader came through.
+  const backHref = useLocation().pathname.startsWith("/shipping-line")
+    ? "/shipping-line/invoices"
+    : "/billing";
   const {
     data: invoice,
     isLoading,
@@ -87,7 +92,7 @@ export default function InvoiceDetailPage() {
           variant="subtle"
           color="gray"
           leftSection={<ArrowLeft size={16} />}
-          onClick={() => navigate("/billing")}
+          onClick={() => navigate(backHref)}
           mb="md"
         >
           Back to invoices
@@ -165,7 +170,7 @@ export default function InvoiceDetailPage() {
           variant="subtle"
           color="gray"
           leftSection={<ArrowLeft size={16} />}
-          onClick={() => navigate("/billing")}
+          onClick={() => navigate(backHref)}
           style={{ alignSelf: "flex-start" }}
           styles={{ root: { fontWeight: 600 } }}
         >
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingDetailPage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingDetailPage.tsx
index 669c9d610..9b5d2ac00 100644
--- a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingDetailPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingDetailPage.tsx
@@ -7,6 +7,7 @@ import {
   Loader,
   Modal,
   Stack,
+  Table,
   Tabs,
   Text,
   Textarea,
@@ -19,10 +20,15 @@ import {
   CheckCircle2,
   ClipboardList,
   Clock,
+  Container,
   FileText,
+  Flame,
   Package,
   PackageCheck,
+  Snowflake,
+  Train,
   Upload,
+  Wallet,
 } from "lucide-react";
 import { useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
@@ -45,7 +51,6 @@ import {
   DOC_STATE_COLOR,
   DOC_STATE_LABEL,
 } from "./booking-doc-state";
-import ShippingLineCompleteModal from "./ShippingLineCompleteModal";
 import ShippingLineDocumentsModal from "./ShippingLineDocumentsModal";
 
 /**
@@ -71,7 +76,6 @@ export default function ShippingLineBookingDetailPage() {
   const navigate = useNavigate();
   const queryClient = useQueryClient();
   const [docsOpen, setDocsOpen] = useState(false);
-  const [completeOpen, setCompleteOpen] = useState(false);
   const [cancelOpen, setCancelOpen] = useState(false);
   const [cancelReason, setCancelReason] = useState("");
 
@@ -89,6 +93,14 @@ export default function ShippingLineBookingDetailPage() {
     queryFn: shippingLineBookingsService.myTrains,
   });
 
+  // Operations view: the assigned/requested train and the wagons the batch
+  // engine allocated — feeds the Wagons & Train tab.
+  const operationsQuery = useQuery({
+    queryKey: ["shipping-line-bookings", id, "operations"],
+    queryFn: () => shippingLineBookingsService.operations(id),
+    enabled: Boolean(id),
+  });
+
   const cancelMutation = useMutation({
     mutationFn: () => shippingLineBookingsService.cancel(id, cancelReason),
     onSuccess: () => {
@@ -138,6 +150,16 @@ export default function ShippingLineBookingDetailPage() {
   const wantsUpload = needsUpload(docState);
   const actionNeeded = docState === "ACTION_NEEDED";
 
+  const containers = booking.bookingContainers ?? [];
+  // Booking flag OR any line count — per-line opt-ins must light the badge
+  // even when the booking-level flag lags.
+  const isHazardous =
+    Boolean(booking.isHazardous) ||
+    containers.some((c) => Number(c.hazardousQuantity ?? 0) > 0);
+  const isReefer = containers.some((c) => Number(c.reeferQuantity ?? 0) > 0);
+  const breakdown = booking.pricingBreakdown ?? null;
+  const operations = operationsQuery.data ?? null;
+
   // Mirrors the server's rule: cancellable only before the booking is priced.
   // Kept in sync deliberately — a button the API would reject is worse than no
   // button at all.
@@ -183,6 +205,28 @@ export default function ShippingLineBookingDetailPage() {
                 {DOC_STATE_LABEL[docState]}
               </Badge>
             )}
+            {isHazardous && (
+              <Badge
+                size="sm"
+                variant="filled"
+                radius="sm"
+                color="red"
+                leftSection={<Flame size={11} />}
+              >
+                Hazardous
+              </Badge>
+            )}
+            {isReefer && (
+              <Badge
+                size="sm"
+                variant="filled"
+                radius="sm"
+                color="blue"
+                leftSection={<Snowflake size={11} />}
+              >
+                Refrigerated
+              </Badge>
+            )}
           </Group>
         </Stack>
 
@@ -216,7 +260,9 @@ export default function ShippingLineBookingDetailPage() {
               color="edr-green"
               radius="md"
               leftSection={<PackageCheck size={16} />}
-              onClick={() => setCompleteOpen(true)}
+              onClick={() =>
+                navigate(`/shipping-line/bookings/${booking.id}/complete`)
+              }
             >
               {status === "OPERATION_CHANGES_REQUESTED"
                 ? "Resubmit booking"
@@ -226,6 +272,20 @@ export default function ShippingLineBookingDetailPage() {
         </Group>
       </Group>
 
+      {/* Operations' return note belongs at the top of the page — the line
+          must see what to fix without hunting through the tabs. */}
+      {status === "OPERATION_CHANGES_REQUESTED" && (
+        <Alert
+          color="orange"
+          radius="md"
+          icon={<AlertCircle size={18} />}
+          title="Operations requested changes"
+        >
+          {booking.operationChangeNote?.trim() ||
+            "Operations returned your booking request for changes. Resubmit it with an updated shipment day or cargo."}
+        </Alert>
+      )}
+
       <Tabs defaultValue="documents" keepMounted={false}>
         <Tabs.List>
           <Tabs.Tab
@@ -245,6 +305,15 @@ export default function ShippingLineBookingDetailPage() {
           <Tabs.Tab value="details" leftSection={<Package size={15} />}>
             Booking details
           </Tabs.Tab>
+          <Tabs.Tab value="cargo" leftSection={<Container size={15} />}>
+            Cargo
+          </Tabs.Tab>
+          <Tabs.Tab value="price" leftSection={<Wallet size={15} />}>
+            Price
+          </Tabs.Tab>
+          <Tabs.Tab value="operations" leftSection={<Train size={15} />}>
+            Wagons & Train
+          </Tabs.Tab>
         </Tabs.List>
 
         <Tabs.Panel value="documents" pt="lg">
@@ -280,8 +349,8 @@ export default function ShippingLineBookingDetailPage() {
                 </Alert>
               ) : status === "OPERATION_CHANGES_REQUESTED" ? (
                 <Alert color="orange" radius="md" icon={<AlertCircle size={18} />}>
-                  Operations returned your booking request for changes.
-                  Resubmit it with an updated shipment day or cargo.
+                  {booking.operationChangeNote?.trim() ||
+                    "Operations returned your booking request for changes. Resubmit it with an updated shipment day or cargo."}
                 </Alert>
               ) : (
                 <Alert
@@ -313,7 +382,9 @@ export default function ShippingLineBookingDetailPage() {
                     color="edr-green"
                     radius="md"
                     leftSection={<PackageCheck size={16} />}
-                    onClick={() => setCompleteOpen(true)}
+                    onClick={() =>
+                navigate(`/shipping-line/bookings/${booking.id}/complete`)
+              }
                   >
                     {status === "OPERATION_CHANGES_REQUESTED"
                       ? "Resubmit booking"
@@ -412,11 +483,333 @@ export default function ShippingLineBookingDetailPage() {
                       }`.trim()}
                     />
                   )}
+                  <DetailRow
+                    label="Billing currency"
+                    value={booking.paymentCurrency ?? "ETB"}
+                  />
+                  {booking.cargoFreeText && (
+                    <DetailRow
+                      label="Cargo description"
+                      value={booking.cargoFreeText}
+                    />
+                  )}
                 </Stack>
               </SectionCard>
             }
           />
         </Tabs.Panel>
+
+        <Tabs.Panel value="cargo" pt="lg">
+          <SectionCard>
+            <CardTitle>Cargo</CardTitle>
+            {containers.length === 0 &&
+            !(Number(booking.cargoTotalWeightVgm ?? 0) > 0) ? (
+              <Text fz={13} c="edr-muted" mt="sm">
+                No cargo entered yet — it is added when you complete the
+                booking after your documents are approved.
+              </Text>
+            ) : booking.freightType === "BULK" ? (
+              <Stack gap="xs" mt="sm">
+                <DetailRow
+                  label="Cargo type"
+                  value={booking.cargoType?.cargoTypeName ?? "—"}
+                />
+                <DetailRow
+                  label="Total weight"
+                  value={`${Number(
+                    booking.bulkTotalWeightTons ??
+                      booking.cargoTotalWeightVgm ??
+                      0,
+                  ).toLocaleString()} tons`}
+                />
+                {booking.cargoFreeText && (
+                  <DetailRow
+                    label="Description"
+                    value={booking.cargoFreeText}
+                  />
+                )}
+              </Stack>
+            ) : (
+              <Stack gap="md" mt="sm">
+                <Table verticalSpacing="sm" horizontalSpacing="md">
+                  <Table.Thead>
+                    <Table.Tr>
+                      <Table.Th>Container type</Table.Th>
+                      <Table.Th ta="right">Qty</Table.Th>
+                      <Table.Th ta="right">VGM / unit</Table.Th>
+                      <Table.Th ta="right">Hazardous</Table.Th>
+                      <Table.Th ta="right">Reefer</Table.Th>
+                    </Table.Tr>
+                  </Table.Thead>
+                  <Table.Tbody>
+                    {containers.map((line) => (
+                      <Table.Tr key={line.id}>
+                        <Table.Td>
+                          <Text fw={600} fz={13}>
+                            {line.containerType?.label ??
+                              line.containerType?.code ??
+                              line.containerSize ??
+                              "—"}
+                          </Text>
+                        </Table.Td>
+                        <Table.Td ta="right">{line.quantity}</Table.Td>
+                        <Table.Td ta="right">
+                          {Number(line.vgmPerUnitTons ?? 0)} t
+                        </Table.Td>
+                        <Table.Td ta="right">
+                          {Number(line.hazardousQuantity ?? 0) > 0 ? (
+                            <Text fw={700} c="red" fz={13}>
+                              {line.hazardousQuantity}
+                            </Text>
+                          ) : (
+                            "—"
+                          )}
+                        </Table.Td>
+                        <Table.Td ta="right">
+                          {Number(line.reeferQuantity ?? 0) > 0 ? (
+                            <Text fw={700} c="blue" fz={13}>
+                              {line.reeferQuantity}
+                            </Text>
+                          ) : (
+                            "—"
+                          )}
+                        </Table.Td>
+                      </Table.Tr>
+                    ))}
+                  </Table.Tbody>
+                </Table>
+
+                {/* Per-container manifest, when the numbers were entered. */}
+                {containers.some((l) => (l.units?.length ?? 0) > 0) && (
+                  <>
+                    <CardTitle>Containers</CardTitle>
+                    <Table verticalSpacing="xs" horizontalSpacing="md">
+                      <Table.Thead>
+                        <Table.Tr>
+                          <Table.Th>Container no.</Table.Th>
+                          <Table.Th>Seal</Table.Th>
+                          <Table.Th ta="right">VGM</Table.Th>
+                          <Table.Th>Handling</Table.Th>
+                        </Table.Tr>
+                      </Table.Thead>
+                      <Table.Tbody>
+                        {containers.flatMap((line) =>
+                          (line.units ?? []).map((unit) => (
+                            <Table.Tr key={unit.id}>
+                              <Table.Td>
+                                <Text fw={600} fz={13}>
+                                  {unit.containerNumber ?? "—"}
+                                </Text>
+                              </Table.Td>
+                              <Table.Td>{unit.sealNumber ?? "—"}</Table.Td>
+                              <Table.Td ta="right">
+                                {Number(unit.vgmTons ?? 0)} t
+                              </Table.Td>
+                              <Table.Td>
+                                <Group gap={4}>
+                                  {unit.isHazardous && (
+                                    <Badge size="xs" color="red" variant="filled">
+                                      Hazardous
+                                    </Badge>
+                                  )}
+                                  {unit.isReefer && (
+                                    <Badge size="xs" color="blue" variant="filled">
+                                      Reefer
+                                    </Badge>
+                                  )}
+                                  {!unit.isHazardous && !unit.isReefer && "—"}
+                                </Group>
+                              </Table.Td>
+                            </Table.Tr>
+                          )),
+                        )}
+                      </Table.Tbody>
+                    </Table>
+                  </>
+                )}
+              </Stack>
+            )}
+          </SectionCard>
+        </Tabs.Panel>
+
+        <Tabs.Panel value="price" pt="lg">
+          <SectionCard>
+            <CardTitle>Price</CardTitle>
+            {!breakdown?.lineItems?.length ? (
+              <Text fz={13} c="edr-muted" mt="sm">
+                No price yet — the booking is priced when you complete it.
+              </Text>
+            ) : (
+              <Stack gap="md" mt="sm">
+                <Table verticalSpacing="xs" horizontalSpacing="md">
+                  <Table.Thead>
+                    <Table.Tr>
+                      <Table.Th>Charge</Table.Th>
+                      <Table.Th ta="right">Qty</Table.Th>
+                      <Table.Th ta="right">Amount</Table.Th>
+                    </Table.Tr>
+                  </Table.Thead>
+                  <Table.Tbody>
+                    {breakdown.lineItems.map((item, i) => (
+                      <Table.Tr key={i}>
+                        <Table.Td>
+                          <Text fz={13}>{item.description}</Text>
+                        </Table.Td>
+                        <Table.Td ta="right">
+                          <Text fz={13} c="edr-muted">
+                            {item.quantity ?? 1}
+                          </Text>
+                        </Table.Td>
+                        <Table.Td ta="right">
+                          <Text fz={13} fw={600}>
+                            {Number(item.amount).toLocaleString()}{" "}
+                            {item.currency}
+                          </Text>
+                        </Table.Td>
+                      </Table.Tr>
+                    ))}
+                  </Table.Tbody>
+                </Table>
+                <Group
+                  justify="space-between"
+                  p="sm"
+                  style={{
+                    borderRadius: 10,
+                    background: "var(--mantine-color-teal-0)",
+                  }}
+                >
+                  <Text fw={700}>Total (on credit)</Text>
+                  <Text fw={800} fz={18}>
+                    {Number(breakdown.totalAmount).toLocaleString()}{" "}
+                    {breakdown.currency}
+                  </Text>
+                </Group>
+                <Text fz={12} c="edr-muted">
+                  Charged to your credit account — EDR bills accumulated
+                  charges periodically. Quoted{" "}
+                  {new Date(breakdown.generatedAt).toLocaleString()}.
+                </Text>
+              </Stack>
+            )}
+          </SectionCard>
+        </Tabs.Panel>
+
+        <Tabs.Panel value="operations" pt="lg">
+          <Stack gap="lg">
+            <SectionCard>
+              <CardTitle>Train</CardTitle>
+              {operationsQuery.isLoading ? (
+                <Center py="lg">
+                  <Loader size="sm" />
+                </Center>
+              ) : !operations?.train ? (
+                <Text fz={13} c="edr-muted" mt="sm">
+                  No train yet — Operations assigns one after your booking is
+                  reviewed and batched.
+                </Text>
+              ) : (
+                <Stack gap="xs" mt="sm">
+                  <Group gap={8}>
+                    <Badge
+                      size="sm"
+                      radius="sm"
+                      variant={operations.train.assigned ? "filled" : "light"}
+                      color={operations.train.assigned ? "teal" : "yellow"}
+                    >
+                      {operations.train.assigned ? "Assigned" : "Requested"}
+                    </Badge>
+                    <StatusBadge status={operations.train.status} />
+                  </Group>
+                  <DetailRow
+                    label="Train"
+                    value={
+                      operations.train.trainNumber ??
+                      operations.train.reference ??
+                      "—"
+                    }
+                  />
+                  <DetailRow
+                    label="Route"
+                    value={`${operations.train.originLabel} → ${operations.train.destinationLabel}`}
+                  />
+                  <DetailRow
+                    label="Departure"
+                    value={new Date(
+                      operations.train.scheduledDepartureDate,
+                    ).toLocaleString()}
+                  />
+                  {operations.train.scheduledArrivalDate && (
+                    <DetailRow
+                      label="Arrival"
+                      value={new Date(
+                        operations.train.scheduledArrivalDate,
+                      ).toLocaleString()}
+                    />
+                  )}
+                </Stack>
+              )}
+            </SectionCard>
+
+            <SectionCard>
+              <CardTitle>Wagons</CardTitle>
+              {operationsQuery.isLoading ? (
+                <Center py="lg">
+                  <Loader size="sm" />
+                </Center>
+              ) : !operations?.wagons?.length ? (
+                <Text fz={13} c="edr-muted" mt="sm">
+                  No wagons allocated yet — allocation happens once Operations
+                  accepts your booking and builds the train.
+                </Text>
+              ) : (
+                <Table
+                  verticalSpacing="sm"
+                  horizontalSpacing="md"
+                  mt="sm"
+                  highlightOnHover
+                >
+                  <Table.Thead>
+                    <Table.Tr>
+                      <Table.Th>#</Table.Th>
+                      <Table.Th>Wagon</Table.Th>
+                      <Table.Th>Type</Table.Th>
+                      <Table.Th ta="right">Loaded / capacity</Table.Th>
+                      <Table.Th>Containers</Table.Th>
+                      <Table.Th>Status</Table.Th>
+                    </Table.Tr>
+                  </Table.Thead>
+                  <Table.Tbody>
+                    {operations.wagons.map((wagon) => (
+                      <Table.Tr key={wagon.id}>
+                        <Table.Td>{wagon.sequenceNo ?? "—"}</Table.Td>
+                        <Table.Td>
+                          <Text fw={600} fz={13}>
+                            {wagon.wagonNumber ?? "To be assigned"}
+                          </Text>
+                        </Table.Td>
+                        <Table.Td>{wagon.wagonType ?? "—"}</Table.Td>
+                        <Table.Td ta="right">
+                          {Number(wagon.allocatedWeightTons).toLocaleString()}{" "}
+                          / {Number(wagon.capacityTons).toLocaleString()} t
+                        </Table.Td>
+                        <Table.Td>
+                          {wagon.containerNumbers.length
+                            ? wagon.containerNumbers.join(", ")
+                            : "—"}
+                        </Table.Td>
+                        <Table.Td>
+                          <Badge size="sm" radius="sm" variant="light">
+                            {wagon.status}
+                          </Badge>
+                        </Table.Td>
+                      </Table.Tr>
+                    ))}
+                  </Table.Tbody>
+                </Table>
+              )}
+            </SectionCard>
+          </Stack>
+        </Tabs.Panel>
       </Tabs>
 
       <ShippingLineDocumentsModal
@@ -424,12 +817,6 @@ export default function ShippingLineBookingDetailPage() {
         onClose={() => setDocsOpen(false)}
       />
 
-      <ShippingLineCompleteModal
-        booking={completeOpen ? booking : null}
-        onClose={() => setCompleteOpen(false)}
-        onCompleted={() => setCompleteOpen(false)}
-      />
-
       {/* Cancelling is irreversible, so it asks first rather than firing on the
           button press. The reason is optional but recorded. */}
       <Modal
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
index a67fb4f64..a56e67afa 100644
--- a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
@@ -41,7 +41,6 @@ import {
   DOC_STATE_COLOR,
   DOC_STATE_LABEL,
 } from "./booking-doc-state";
-import ShippingLineCompleteModal from "./ShippingLineCompleteModal";
 import ShippingLineDocumentsModal from "./ShippingLineDocumentsModal";
 import ShippingLineInitiateModal from "./ShippingLineInitiateModal";
 
@@ -74,9 +73,6 @@ export default function ShippingLineBookingsPage() {
   const [docsBooking, setDocsBooking] = useState<ShippingLineBooking | null>(
     null,
   );
-  const [bookBooking, setBookBooking] = useState<ShippingLineBooking | null>(
-    null,
-  );
 
   const bookingsQuery = useQuery({
     queryKey: ["shipping-line-bookings"],
@@ -183,7 +179,9 @@ export default function ShippingLineBookingsPage() {
                 fw={700}
                 fz={13}
                 leftSection={<PackageCheck size={14} />}
-                onClick={() => setBookBooking(booking)}
+                onClick={() =>
+                  navigate(`/shipping-line/bookings/${booking.id}/complete`)
+                }
               >
                 {booking.status === "OPERATION_CHANGES_REQUESTED"
                   ? "Resubmit"
@@ -245,7 +243,9 @@ export default function ShippingLineBookingsPage() {
                 {bookable && (
                   <Menu.Item
                     leftSection={<PackageCheck size={15} />}
-                    onClick={() => setBookBooking(booking)}
+                    onClick={() =>
+                      navigate(`/shipping-line/bookings/${booking.id}/complete`)
+                    }
                   >
                     {booking.status === "OPERATION_CHANGES_REQUESTED"
                       ? "Resubmit booking"
@@ -348,16 +348,6 @@ export default function ShippingLineBookingsPage() {
         booking={docsBooking}
         onClose={() => setDocsBooking(null)}
       />
-
-      <ShippingLineCompleteModal
-        booking={bookBooking}
-        onClose={() => setBookBooking(null)}
-        onCompleted={(booking) => {
-          setBookBooking(null);
-          // Straight into the booking — its status and price just changed.
-          navigate(`/shipping-line/bookings/${booking.id}`);
-        }}
-      />
     </Box>
   );
 }
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineCompleteModal.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineCompleteModal.tsx
deleted file mode 100644
index 370b0ea30..000000000
--- a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineCompleteModal.tsx
+++ /dev/null
@@ -1,372 +0,0 @@
-import {
-  ActionIcon,
-  Alert,
-  Box,
-  Button,
-  Center,
-  Group,
-  Loader,
-  Modal,
-  NumberInput,
-  Select,
-  Stack,
-  Text,
-  Textarea,
-} from "@mantine/core";
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import {
-  AlertCircle,
-  CalendarDays,
-  PackageCheck,
-  Plus,
-  Trash2,
-} from "lucide-react";
-import { useEffect, useMemo, useState } from "react";
-
-import {
-  shippingLineBookingsService,
-  type CompleteBookingContainerLine,
-  type ShippingLineBooking,
-} from "@/services/shipping-line-bookings.service";
-
-const CURRENCIES = [
-  { value: "ETB", label: "ETB" },
-  { value: "USD", label: "USD" },
-];
-
-interface ContainerLineDraft {
-  containerTypeId: string | null;
-  quantity: number | string;
-  vgmPerUnitTons: number | string;
-}
-
-const EMPTY_LINE: ContainerLineDraft = {
-  containerTypeId: null,
-  quantity: 1,
-  vgmPerUnitTons: 0,
-};
-
-/**
- * Complete an approved shipping-line booking — the step a customer does after
- * clearance: enter the cargo and the binding shipment day. The server prices
- * the booking off the line's negotiated rates and puts the charge on the
- * credit ledger (pay-later), so no payment step follows here.
- */
-export default function ShippingLineCompleteModal({
-  booking,
-  onClose,
-  onCompleted,
-}: {
-  /** The booking to complete, or null when the modal is closed. */
-  booking: ShippingLineBooking | null;
-  onClose: () => void;
-  onCompleted: (booking: ShippingLineBooking) => void;
-}) {
-  const queryClient = useQueryClient();
-  const opened = Boolean(booking);
-  const bookingId = booking?.id ?? "";
-  const isContainer = (booking?.freightType ?? "CONTAINER") === "CONTAINER";
-
-  const [scheduledDate, setScheduledDate] = useState<string | null>(null);
-  const [currency, setCurrency] = useState<string>("ETB");
-  const [lines, setLines] = useState<ContainerLineDraft[]>([{ ...EMPTY_LINE }]);
-  const [cargoTypeId, setCargoTypeId] = useState<string | null>(null);
-  const [cargoWeightTons, setCargoWeightTons] = useState<number | string>(0);
-  const [cargoFreeText, setCargoFreeText] = useState("");
-
-  // Fresh sheet each open, prefilled with the day picked at initiate (if any).
-  useEffect(() => {
-    if (opened && booking) {
-      setScheduledDate(
-        booking.scheduledDate
-          ? new Date(booking.scheduledDate).toISOString().slice(0, 10)
-          : null,
-      );
-      setCurrency(booking.paymentCurrency ?? "ETB");
-      setLines([{ ...EMPTY_LINE }]);
-      setCargoTypeId(null);
-      setCargoWeightTons(0);
-      setCargoFreeText("");
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [opened, bookingId]);
-
-  const referenceQuery = useQuery({
-    queryKey: ["shipping-line-reference-data"],
-    queryFn: shippingLineBookingsService.referenceData,
-    enabled: opened,
-  });
-
-  // Only schedule-backed days are offered — same rule the server enforces.
-  const daysQuery = useQuery({
-    queryKey: ["shipping-line-bookings", bookingId, "available-days"],
-    queryFn: () => shippingLineBookingsService.availableDays(bookingId),
-    enabled: opened && Boolean(bookingId),
-  });
-
-  const completeMutation = useMutation({
-    mutationFn: () => {
-      const payload = isContainer
-        ? {
-            scheduledDate: scheduledDate!,
-            paymentCurrency: currency,
-            cargoFreeText: cargoFreeText || undefined,
-            containers: lines
-              .filter((l) => l.containerTypeId && Number(l.quantity) > 0)
-              .map(
-                (l): CompleteBookingContainerLine => ({
-                  containerTypeId: l.containerTypeId!,
-                  quantity: Number(l.quantity),
-                  vgmPerUnitTons: Number(l.vgmPerUnitTons) || 0,
-                }),
-              ),
-          }
-        : {
-            scheduledDate: scheduledDate!,
-            paymentCurrency: currency,
-            cargoFreeText: cargoFreeText || undefined,
-            cargoTypeId: cargoTypeId!,
-            cargoWeightTons: Number(cargoWeightTons),
-          };
-      return shippingLineBookingsService.complete(bookingId, payload);
-    },
-    onSuccess: (updated) => {
-      void queryClient.invalidateQueries({
-        queryKey: ["shipping-line-bookings"],
-      });
-      onCompleted(updated);
-    },
-  });
-
-  const containerTypeOptions = useMemo(
-    () =>
-      (referenceQuery.data?.containerTypes ?? []).map((ct) => ({
-        value: ct.id,
-        label: ct.sizeFt ? `${ct.label} (${ct.sizeFt}ft)` : ct.label,
-      })),
-    [referenceQuery.data],
-  );
-
-  // Grouping headers are rows other rows point at via parentGroupId — only
-  // leaves are bookable cargo.
-  const cargoTypeOptions = useMemo(() => {
-    const all = referenceQuery.data?.cargoTypes ?? [];
-    const parents = new Set(
-      all.map((c) => c.parentGroupId).filter((id): id is string => Boolean(id)),
-    );
-    return all
-      .filter((c) => !parents.has(c.id))
-      .map((c) => ({ value: c.id, label: c.name }));
-  }, [referenceQuery.data]);
-
-  const dayOptions = useMemo(
-    () =>
-      (daysQuery.data?.days ?? []).map((day) => ({
-        value: day,
-        label: new Date(day).toLocaleDateString(undefined, {
-          weekday: "short",
-          year: "numeric",
-          month: "short",
-          day: "numeric",
-        }),
-      })),
-    [daysQuery.data],
-  );
-
-  const validCargo = isContainer
-    ? lines.some((l) => l.containerTypeId && Number(l.quantity) > 0)
-    : Boolean(cargoTypeId) && Number(cargoWeightTons) > 0;
-  const canSubmit = Boolean(scheduledDate) && validCargo;
-
-  const loading = referenceQuery.isLoading || daysQuery.isLoading;
-
-  return (
-    <Modal
-      opened={opened}
-      onClose={onClose}
-      centered
-      size="lg"
-      radius="md"
-      title={
-        <Box>
-          <Text fw={700} fz={16}>
-            Complete booking
-          </Text>
-          <Text fz={12} c="dimmed">
-            Your documents are approved — enter the cargo and shipment day. The
-            charge goes on your credit account.
-          </Text>
-        </Box>
-      }
-      overlayProps={{ blur: 2, backgroundOpacity: 0.55 }}
-    >
-      {loading ? (
-        <Center py="xl">
-          <Loader size="sm" />
-        </Center>
-      ) : (
-        <Stack gap="md">
-          {dayOptions.length === 0 ? (
-            <Alert color="yellow" radius="md" icon={<AlertCircle size={16} />}>
-              No departures are currently open on this route. Please check back
-              or contact Operations.
-            </Alert>
-          ) : (
-            <Select
-              label="Shipment day"
-              description="Only days with an open train departure on your route are offered."
-              placeholder="Pick the shipment day"
-              withAsterisk
-              searchable
-              leftSection={<CalendarDays size={16} />}
-              data={dayOptions}
-              value={scheduledDate}
-              onChange={setScheduledDate}
-              comboboxProps={{ withinPortal: true }}
-            />
-          )}
-
-          {isContainer ? (
-            <Stack gap="xs">
-              <Text fz={13} fw={600}>
-                Containers
-              </Text>
-              {lines.map((line, index) => (
-                <Group key={index} gap="xs" align="flex-end" wrap="nowrap">
-                  <Select
-                    label={index === 0 ? "Container type" : undefined}
-                    placeholder="Type"
-                    searchable
-                    style={{ flex: 2 }}
-                    data={containerTypeOptions}
-                    value={line.containerTypeId}
-                    onChange={(v) =>
-                      setLines((prev) =>
-                        prev.map((l, i) =>
-                          i === index ? { ...l, containerTypeId: v } : l,
-                        ),
-                      )
-                    }
-                    comboboxProps={{ withinPortal: true }}
-                  />
-                  <NumberInput
-                    label={index === 0 ? "Quantity" : undefined}
-                    min={1}
-                    style={{ flex: 1 }}
-                    value={line.quantity}
-                    onChange={(v) =>
-                      setLines((prev) =>
-                        prev.map((l, i) =>
-                          i === index ? { ...l, quantity: v } : l,
-                        ),
-                      )
-                    }
-                  />
-                  <NumberInput
-                    label={index === 0 ? "VGM / unit (tons)" : undefined}
-                    min={0}
-                    decimalScale={3}
-                    style={{ flex: 1 }}
-                    value={line.vgmPerUnitTons}
-                    onChange={(v) =>
-                      setLines((prev) =>
-                        prev.map((l, i) =>
-                          i === index ? { ...l, vgmPerUnitTons: v } : l,
-                        ),
-                      )
-                    }
-                  />
-                  <ActionIcon
-                    variant="subtle"
-                    color="red"
-                    size="lg"
-                    disabled={lines.length === 1}
-                    onClick={() =>
-                      setLines((prev) => prev.filter((_, i) => i !== index))
-                    }
-                    aria-label="Remove line"
-                  >
-                    <Trash2 size={16} />
-                  </ActionIcon>
-                </Group>
-              ))}
-              <Button
-                variant="light"
-                size="compact-sm"
-                w="fit-content"
-                leftSection={<Plus size={14} />}
-                onClick={() => setLines((prev) => [...prev, { ...EMPTY_LINE }])}
-              >
-                Add container line
-              </Button>
-            </Stack>
-          ) : (
-            <Group grow align="flex-start" gap="sm">
-              <Select
-                label="Cargo type"
-                placeholder="Select cargo..."
-                withAsterisk
-                searchable
-                data={cargoTypeOptions}
-                value={cargoTypeId}
-                onChange={setCargoTypeId}
-                comboboxProps={{ withinPortal: true }}
-              />
-              <NumberInput
-                label="Total weight (tons)"
-                withAsterisk
-                min={0}
-                decimalScale={3}
-                value={cargoWeightTons}
-                onChange={setCargoWeightTons}
-              />
-            </Group>
-          )}
-
-          <Group grow align="flex-start" gap="sm">
-            <Select
-              label="Billing currency"
-              data={CURRENCIES}
-              value={currency}
-              onChange={(v) => setCurrency(v ?? "ETB")}
-              comboboxProps={{ withinPortal: true }}
-            />
-            <Textarea
-              label="Cargo description (optional)"
-              placeholder="What the shipment carries"
-              autosize
-              minRows={1}
-              maxRows={3}
-              maxLength={500}
-              value={cargoFreeText}
-              onChange={(e) => setCargoFreeText(e.currentTarget.value)}
-            />
-          </Group>
-
-          {completeMutation.isError && (
-            <Alert color="red" icon={<AlertCircle size={16} />}>
-              {(completeMutation.error as Error)?.message ??
-                "Could not complete the booking."}
-            </Alert>
-          )}
-
-          <Group justify="flex-end" mt="sm" gap="sm">
-            <Button variant="default" radius="md" onClick={onClose}>
-              Cancel
-            </Button>
-            <Button
-              color="edr-green"
-              radius="md"
-              leftSection={<PackageCheck size={16} />}
-              loading={completeMutation.isPending}
-              disabled={!canSubmit}
-              onClick={() => completeMutation.mutate()}
-            >
-              Complete booking
-            </Button>
-          </Group>
-        </Stack>
-      )}
-    </Modal>
-  );
-}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineCompletePage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineCompletePage.tsx
new file mode 100644
index 000000000..c470de35d
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineCompletePage.tsx
@@ -0,0 +1,1516 @@
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type ReactNode,
+} from "react";
+import { useForm, Controller } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useNavigate, useParams } from "react-router-dom";
+import {
+  ActionIcon,
+  Alert,
+  Badge,
+  Box,
+  Button,
+  Center,
+  FileButton,
+  Group,
+  List,
+  Loader,
+  Modal,
+  Paper,
+  Select,
+  Stack,
+  Switch,
+  Table,
+  Text,
+  TextInput,
+  Textarea,
+  Title,
+} from "@mantine/core";
+import {
+  AlertCircle,
+  CalendarDays,
+  CheckCircle2,
+  ChevronLeft,
+  FileDown,
+  FileUp,
+  Flame,
+  MapPin,
+  Package,
+  PackageCheck,
+  Snowflake,
+  Train,
+  X,
+} from "lucide-react";
+
+import { OperationDatePicker } from "@edr/ui-common";
+import {
+  StepCard,
+  StepHeader,
+  StepLabel,
+  fieldStyles,
+} from "../contracts/new-contract-form/shared";
+import {
+  ShipmentFormInputValues,
+  ShipmentFormValues,
+  createShipmentFormSchema,
+  initialShipmentFormValues,
+} from "../contracts/new-shipment-form/schema";
+import {
+  downloadContainerImportTemplate,
+  parseContainerExcel,
+} from "../contracts/new-shipment-form/container-excel";
+import {
+  shippingLineBookingsService,
+  type CompleteBookingContainerLine,
+  type CompleteShippingLineBookingPayload,
+  type ShippingLineBooking,
+  type ShippingLinePriceQuote,
+} from "@/services/shipping-line-bookings.service";
+import { extractApiError } from "@/utils/result";
+
+type ShipmentForm = ReturnType<
+  typeof useForm<ShipmentFormInputValues, any, ShipmentFormValues>
+>;
+
+const SIZES = ["20ft", "40ft"] as const;
+
+/**
+ * Every quantity on this form is a non-negative magnitude. A native number
+ * input's `min` only constrains its stepper, so swallow the minus key before it
+ * can put a negative into the field at all.
+ */
+const blockNegative = (event: KeyboardEvent<HTMLInputElement>) => {
+  if (event.key === "-") event.preventDefault();
+};
+
+const COMPLETABLE_STATUSES = new Set([
+  "CLEARANCE_READY",
+  "OPERATION_CHANGES_REQUESTED",
+]);
+
+/**
+ * Shipping-line booking completion page — a faithful duplicate of the customer
+ * shipment-booking page (contracts/NewShipmentPage): the same Excel
+ * import/template flow, the same per-container rows with hazardous/refrigerated
+ * switches, the same day-picker calendar. Only the plumbing differs: no
+ * contract — cargo posts to the shipping-line completion endpoint, days come
+ * from the line's dedicated trains (or the shared pool when it has none), and
+ * the price lands on the credit ledger instead of an invoice, so there is no
+ * price-confirmation step.
+ */
+export default function ShippingLineCompletePage() {
+  const { id = "" } = useParams();
+  const navigate = useNavigate();
+
+  const bookingQuery = useQuery({
+    queryKey: ["shipping-line-bookings", id],
+    queryFn: () => shippingLineBookingsService.getById(id),
+    enabled: Boolean(id),
+  });
+
+  if (bookingQuery.isLoading) {
+    return (
+      <Center mih={400} p="xl">
+        <Loader color="edr-green" />
+      </Center>
+    );
+  }
+
+  const booking = bookingQuery.data;
+  if (!booking) {
+    return (
+      <Box p="xl">
+        <Paper withBorder radius="lg" p="xl">
+          <Text fw={700} mb="xs">
+            Booking not found
+          </Text>
+          <Button
+            variant="default"
+            onClick={() => navigate("/shipping-line/bookings")}
+          >
+            Back to bookings
+          </Button>
+        </Paper>
+      </Box>
+    );
+  }
+
+  if (!COMPLETABLE_STATUSES.has(booking.status as string)) {
+    return (
+      <Box p="xl">
+        <Alert color="blue" icon={<AlertCircle size={18} />} radius="md">
+          <Text fw={700} mb="xs">
+            This booking cannot be completed yet
+          </Text>
+          <Text size="sm" mb="md">
+            Your documents must be approved by Operations before the cargo and
+            shipment day can be entered.
+          </Text>
+          <Button
+            color="edr-green"
+            radius="md"
+            onClick={() => navigate(`/shipping-line/bookings/${booking.id}`)}
+          >
+            Back to booking
+          </Button>
+        </Alert>
+      </Box>
+    );
+  }
+
+  return <CompleteBookingForm booking={booking} />;
+}
+
+function CompleteBookingForm({ booking }: { booking: ShippingLineBooking }) {
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+  const isContainer = (booking.freightType ?? "CONTAINER") === "CONTAINER";
+  const isResubmit = booking.status === "OPERATION_CHANGES_REQUESTED";
+
+  // Bulk cargo type lives outside the shared schema (customers get it from
+  // their contract) — validated at submit time instead.
+  const [cargoTypeId, setCargoTypeId] = useState<string | null>(null);
+
+  const form = useForm<ShipmentFormInputValues, any, ShipmentFormValues>({
+    defaultValues: {
+      ...initialShipmentFormValues,
+      // Shipping lines are always invoiced in ETB — no currency choice.
+      paymentCurrency: "ETB",
+    },
+    resolver: zodResolver(
+      createShipmentFormSchema({
+        isContainer,
+        // Both handling services are always offered — there is no contract
+        // scope to restrict them; charges apply only to ticked containers.
+        isHazardous: true,
+        isReefer: true,
+        withReturnService: false,
+        unitOfMeasure: "PER_TON",
+        requiresDate: true,
+        requiresTrain: false,
+      }),
+    ),
+    mode: "onChange",
+  });
+
+  const referenceQuery = useQuery({
+    queryKey: ["shipping-line-reference-data"],
+    queryFn: shippingLineBookingsService.referenceData,
+  });
+
+  // 20ft containers ride two per wagon — an odd total can never be planned.
+  const watchedContainers = form.watch("containers");
+  const ft20Total = isContainer
+    ? (watchedContainers ?? [])
+        .filter((l) => l.containerSize === "20ft")
+        .reduce((sum, l) => sum + Number(l.quantity || 0), 0)
+    : 0;
+  const hasOdd20ft = ft20Total % 2 === 1;
+
+  // Two-step submit: the payload is priced first (authoritative quote, saved
+  // server-side with fresh rate snapshots on every preview), the shipping line
+  // confirms the figure, and only then does the booking submit.
+  const [pendingPayload, setPendingPayload] =
+    useState<CompleteShippingLineBookingPayload | null>(null);
+  const [quote, setQuote] = useState<ShippingLinePriceQuote | null>(null);
+
+  const previewMutation = useMutation({
+    mutationFn: (payload: CompleteShippingLineBookingPayload) =>
+      shippingLineBookingsService.pricePreview(booking.id, payload),
+    onSuccess: (result, payload) => {
+      setPendingPayload(payload);
+      setQuote(result);
+    },
+  });
+
+  const submitMutation = useMutation({
+    mutationFn: (payload: CompleteShippingLineBookingPayload) =>
+      shippingLineBookingsService.complete(booking.id, payload),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({
+        queryKey: ["shipping-line-bookings"],
+      });
+      navigate(`/shipping-line/bookings/${booking.id}`);
+    },
+    // A submit failure (day filled up, window closed meanwhile) must not leave
+    // a stale confirm dialog on screen — the error modal takes over.
+    onError: () => {
+      setQuote(null);
+      setPendingPayload(null);
+    },
+  });
+
+  /**
+   * Map a container size to the configured container type: reefer type when
+   * any container on the line is refrigerated, standard type otherwise —
+   * mirroring the server's own size→type resolution for customers.
+   */
+  function buildPayload(
+    values: ShipmentFormValues,
+  ): CompleteShippingLineBookingPayload | { error: string } {
+    const base = {
+      scheduledDate: values.scheduledDate,
+      // Which of the line's trains the booking rides — required by the server
+      // when more than one departs on the chosen day.
+      ...(values.trainScheduleId
+        ? { trainScheduleId: values.trainScheduleId }
+        : {}),
+      ...(values.paymentCurrency
+        ? { paymentCurrency: values.paymentCurrency }
+        : {}),
+      ...(values.cargoDescription?.trim()
+        ? { cargoFreeText: values.cargoDescription.trim() }
+        : {}),
+    };
+    if (!isContainer) {
+      if (!cargoTypeId) return { error: "Select the cargo type." };
+      return {
+        ...base,
+        cargoTypeId,
+        cargoWeightTons: Number(values.cargoWeightTons),
+        bulkHazardousQuantity: Number(values.bulkHazardousQuantity || 0),
+        bulkReeferQuantity: Number(values.bulkReeferQuantity || 0),
+      };
+    }
+    const containers: CompleteBookingContainerLine[] = [];
+    for (const l of values.containers.filter(
+      (l) => Number(l.quantity) >= 1,
+    )) {
+      const totalVgm = l.units.reduce((s, u) => s + Number(u.vgmTons || 0), 0);
+      containers.push({
+        // The size string alone — the server maps it to the configured
+        // container type, so a slow/failed catalog fetch can never block
+        // the submit with a phantom "type not configured" error.
+        containerSize: l.containerSize,
+        quantity: Number(l.quantity),
+        hazardousQuantity: l.units.filter((u) => u.isHazardous).length,
+        reeferQuantity: l.units.filter((u) => u.isReefer).length,
+        vgmPerUnitTons: l.units.length ? totalVgm / l.units.length : 0,
+        units: l.units.map((u) => ({
+          containerNumber: u.containerNumber.trim().toUpperCase(),
+          sealNumber: u.sealNumber || undefined,
+          vgmTons: Number(u.vgmTons),
+          isHazardous: Boolean(u.isHazardous),
+          isReefer: Boolean(u.isReefer),
+        })),
+      });
+    }
+    return { ...base, containers };
+  }
+
+  const [payloadError, setPayloadError] = useState<string | null>(null);
+  const handleSubmit = form.handleSubmit((values) => {
+    if (hasOdd20ft) return;
+    const payload = buildPayload(values);
+    if ("error" in payload) {
+      setPayloadError(payload.error);
+      return;
+    }
+    setPayloadError(null);
+    // Price first — the confirm dialog opens when the quote arrives; the
+    // booking submits only after the shipping line confirms the figure.
+    previewMutation.mutate(payload);
+  });
+
+  const showValidationSummary =
+    form.formState.isSubmitted && !form.formState.isValid;
+
+  return (
+    <Box
+      style={{
+        padding: "28px 0 0",
+        minHeight: "calc(100dvh - var(--app-shell-header-height, 56px))",
+        display: "flex",
+        flexDirection: "column",
+      }}
+    >
+      <Group
+        justify="space-between"
+        px="24px"
+        align="flex-end"
+        wrap="wrap"
+        gap="md"
+        mb="lg"
+      >
+        <Box>
+          <Title order={1} fw={800} fz={26} style={{ letterSpacing: "-0.01em" }}>
+            {isResubmit ? "Change Your Booking" : "Complete Your Booking"}
+          </Title>
+          <Text size="sm" c="edr-muted" mt={4}>
+            {isResubmit
+              ? `Update the details below and pick a new shipment day, then resubmit booking ${booking.reference}.`
+              : `Your documents are approved — enter the cargo details and shipment day for booking ${booking.reference}. The charge goes on your credit account.`}
+          </Text>
+        </Box>
+        <Button
+          variant="default"
+          radius="md"
+          leftSection={<ChevronLeft size={16} />}
+          onClick={() => navigate(`/shipping-line/bookings/${booking.id}`)}
+        >
+          Back to booking
+        </Button>
+      </Group>
+
+      <form
+        className="flex flex-col"
+        style={{ flex: 1 }}
+        onSubmit={(e) => e.preventDefault()}
+      >
+        {/* Errors surface in a modal, not an inline alert: the submit button
+            sits at the bottom of a long form, so a banner at the top scrolls
+            out of sight exactly when the user needs it. */}
+        <Modal
+          opened={Boolean(
+            submitMutation.isError || previewMutation.isError || payloadError,
+          )}
+          onClose={() => {
+            setPayloadError(null);
+            submitMutation.reset();
+            previewMutation.reset();
+          }}
+          centered
+          radius="md"
+          size="lg"
+          title={
+            <Group gap={8}>
+              <AlertCircle size={18} color="var(--mantine-color-red-6)" />
+              <Text fw={700} fz={16}>
+                Booking could not be completed
+              </Text>
+            </Group>
+          }
+          overlayProps={{ blur: 2, backgroundOpacity: 0.55 }}
+        >
+          <Stack gap="md">
+            {(() => {
+              // The server's message, never axios's generic "Request failed
+              // with status code 400" — extractApiError digs it out of the
+              // response body.
+              const message =
+                payloadError ??
+                extractApiError(submitMutation.error ?? previewMutation.error)
+                  .message;
+              // Missing-rate blocks are an EDR setup gap, not a mistake the
+              // shipping line made — lead with plain words and where to go,
+              // then the specifics of what is not priced.
+              const isPricingGap = message.includes("rate is configured");
+              // The server joins multiple pricing blocks with "; " — a list
+              // reads far better than one wall of text.
+              const parts = message
+                .split("; ")
+                .map((p) => p.trim())
+                .filter(Boolean);
+              return (
+                <>
+                  {isPricingGap && (
+                    <Text size="sm" fw={600}>
+                      This booking cannot be completed yet — the price for
+                      your shipment has not been set up. Please contact EDR
+                      support to configure it, or change the options below:
+                    </Text>
+                  )}
+                  {parts.length > 1 ? (
+                    <List spacing="sm" size="sm" c="red.8">
+                      {parts.map((part, i) => (
+                        <List.Item key={i}>{part}</List.Item>
+                      ))}
+                    </List>
+                  ) : (
+                    <Text size="sm" c="red.8">
+                      {message}
+                    </Text>
+                  )}
+                </>
+              );
+            })()}
+            <Group justify="flex-end">
+              <Button
+                variant="default"
+                radius="md"
+                onClick={() => {
+                  setPayloadError(null);
+                  submitMutation.reset();
+                  previewMutation.reset();
+                }}
+              >
+                Close
+              </Button>
+            </Group>
+          </Stack>
+        </Modal>
+
+        {/* Price confirmation: the quote just computed (and snapshotted)
+            server-side. Nothing submits until the figure is confirmed. */}
+        <Modal
+          opened={Boolean(quote)}
+          onClose={() => {
+            setQuote(null);
+            setPendingPayload(null);
+          }}
+          centered
+          radius="md"
+          size="lg"
+          title={
+            <Group gap={8}>
+              <PackageCheck size={18} color="var(--mantine-color-teal-6)" />
+              <Text fw={700} fz={16}>
+                Confirm your booking price
+              </Text>
+            </Group>
+          }
+          overlayProps={{ blur: 2, backgroundOpacity: 0.55 }}
+        >
+          {quote && (
+            <Stack gap="md">
+              <Box style={{ overflowX: "auto" }}>
+                <Table verticalSpacing="xs" horizontalSpacing="md">
+                  <Table.Thead>
+                    <Table.Tr>
+                      <Table.Th>Charge</Table.Th>
+                      <Table.Th ta="right">Qty</Table.Th>
+                      <Table.Th ta="right">Amount</Table.Th>
+                    </Table.Tr>
+                  </Table.Thead>
+                  <Table.Tbody>
+                    {quote.lineItems.map((item, i) => (
+                      <Table.Tr key={i}>
+                        <Table.Td>
+                          <Text size="sm">{item.description}</Text>
+                        </Table.Td>
+                        <Table.Td ta="right">
+                          <Text size="sm" c="dimmed">
+                            {item.quantity ?? 1}
+                          </Text>
+                        </Table.Td>
+                        <Table.Td ta="right">
+                          <Text size="sm" fw={600}>
+                            {Number(item.amount).toLocaleString()}{" "}
+                            {item.currency}
+                          </Text>
+                        </Table.Td>
+                      </Table.Tr>
+                    ))}
+                  </Table.Tbody>
+                </Table>
+              </Box>
+              <Group
+                justify="space-between"
+                p="sm"
+                style={{
+                  borderRadius: 10,
+                  background: "var(--mantine-color-teal-0)",
+                }}
+              >
+                <Text fw={700}>Total</Text>
+                <Text fw={800} fz={18}>
+                  {Number(quote.totalAmount).toLocaleString()} {quote.currency}
+                </Text>
+              </Group>
+              <Text size="xs" c="dimmed">
+                The amount is charged to your credit account — no payment is
+                due now. EDR bills your accumulated charges periodically.
+              </Text>
+              {quote.warnings.length > 0 && (
+                <Alert
+                  color="yellow"
+                  radius="md"
+                  icon={<AlertCircle size={16} />}
+                >
+                  {quote.warnings.join(" ")}
+                </Alert>
+              )}
+              <Group justify="flex-end" gap="sm">
+                <Button
+                  variant="default"
+                  radius="md"
+                  onClick={() => {
+                    setQuote(null);
+                    setPendingPayload(null);
+                  }}
+                >
+                  Go back
+                </Button>
+                <Button
+                  color="edr-green"
+                  radius="md"
+                  leftSection={<PackageCheck size={16} />}
+                  loading={submitMutation.isPending}
+                  onClick={() =>
+                    pendingPayload && submitMutation.mutate(pendingPayload)
+                  }
+                >
+                  Confirm & book
+                </Button>
+              </Group>
+            </Stack>
+          )}
+        </Modal>
+
+        <Box flex={1} p="24px">
+          <Stack gap="lg" className="mx-auto max-w-4xl">
+            <RouteCard booking={booking} />
+            {isContainer ? (
+              <ContainerCargoStep form={form} />
+            ) : (
+              <BulkCargoStep
+                form={form}
+                cargoTypeId={cargoTypeId}
+                onCargoTypeChange={setCargoTypeId}
+                cargoTypes={referenceQuery.data?.cargoTypes ?? []}
+              />
+            )}
+            <ScheduleStep
+              form={form}
+              booking={booking}
+              cargoTypeId={isContainer ? null : cargoTypeId}
+            />
+          </Stack>
+        </Box>
+
+        <Box
+          style={{
+            position: "sticky",
+            bottom: 0,
+            zIndex: 20,
+            borderTop: "1px solid var(--mantine-color-edr-border-0)",
+            backgroundColor: "rgba(255,255,255,0.94)",
+            backdropFilter: "blur(14px)",
+            padding: "16px 24px",
+            marginTop: "auto",
+          }}
+        >
+          <Box className="mx-auto max-w-4xl">
+            {showValidationSummary ? (
+              <Alert
+                color="red"
+                variant="light"
+                radius="md"
+                icon={<AlertCircle size={16} />}
+                mb="sm"
+              >
+                Fix the highlighted fields before completing the booking.
+              </Alert>
+            ) : null}
+            <Group justify="flex-end">
+              <Button
+                type="button"
+                color="edr-green"
+                radius="md"
+                leftSection={<PackageCheck size={16} />}
+                onClick={handleSubmit}
+                loading={previewMutation.isPending || submitMutation.isPending}
+                disabled={hasOdd20ft}
+              >
+                {isResubmit ? "Resubmit booking" : "Complete booking"}
+              </Button>
+            </Group>
+          </Box>
+        </Box>
+      </form>
+    </Box>
+  );
+}
+
+/** The booking's lane — fixed at initiate time from the chosen route. */
+function RouteCard({ booking }: { booking: ShippingLineBooking }) {
+  return (
+    <StepCard>
+      <StepHeader
+        icon={<MapPin size={22} />}
+        title="Route"
+        description="This booking ships on the lane picked when it was initiated."
+      />
+      <Paper withBorder radius="md" p="md" style={{ borderColor: "#E6ECF2" }}>
+        <Text fz={14} fw={600} c="#10202F">
+          {booking.originYard?.label ?? booking.originYard?.code ?? "—"} →{" "}
+          {booking.destinationYard?.label ??
+            booking.destinationYard?.code ??
+            "—"}
+        </Text>
+        <Text fz={12} c="dimmed" mt={2}>
+          {booking.tradeDirection ?? "IMPORT"}
+        </Text>
+      </Paper>
+    </StepCard>
+  );
+}
+
+/** A departure's calendar day in East Africa Time — matches the server's eatDay. */
+function eatDayOf(date: string | Date): string {
+  return new Date(date).toLocaleDateString("en-CA", {
+    timeZone: "Africa/Addis_Ababa",
+  });
+}
+
+function ScheduleStep({
+  form,
+  booking,
+  cargoTypeId,
+}: {
+  form: ShipmentForm;
+  booking: ShippingLineBooking;
+  /** Bulk cargo pick (container bookings pass null) — refines availability. */
+  cargoTypeId: string | null;
+}) {
+  // Days come from the line's dedicated trains (open until each train's
+  // close offset), or the shared pool when the lane has none.
+  const daysQuery = useQuery({
+    queryKey: ["shipping-line-bookings", booking.id, "available-days"],
+    queryFn: () => shippingLineBookingsService.availableDays(booking.id),
+  });
+
+  // Cargo context makes the per-train availability figures real: the wagon
+  // types offered are the ones THIS cargo can ride. Recomputed per render on
+  // purpose — react-hook-form mutates the watched array in place.
+  const isContainer = (booking.freightType ?? "CONTAINER") === "CONTAINER";
+  const containerLines = form.watch("containers") ?? [];
+  const cargo = (() => {
+    if (isContainer) {
+      const sizes = containerLines
+        .filter((l) => Number(l.quantity || 0) >= 1)
+        .map((l) => l.containerSize);
+      const ft20 = containerLines
+        .filter((l) => l.containerSize === "20ft")
+        .reduce((s, l) => s + Number(l.quantity || 0), 0);
+      const ft40 = containerLines
+        .filter((l) => l.containerSize === "40ft")
+        .reduce((s, l) => s + Number(l.quantity || 0), 0);
+      const wagons = Math.ceil(ft20 / 2) + ft40;
+      return {
+        containerSizes: sizes.length ? sizes : undefined,
+        wagons: wagons > 0 ? wagons : undefined,
+      };
+    }
+    return cargoTypeId ? { cargoTypeId } : {};
+  })();
+
+  // The line's OWN departures on this lane, each with per-wagon-type free
+  // space — the pick is "which train", not an abstract calendar day.
+  // Customers never see these trains; the endpoint is shipping-line only.
+  const trainsQuery = useQuery({
+    queryKey: [
+      "shipping-line-bookings",
+      booking.id,
+      "trains",
+      cargo.containerSizes?.join(",") ?? "",
+      (cargo as { cargoTypeId?: string }).cargoTypeId ?? "",
+      (cargo as { wagons?: number }).wagons ?? 0,
+    ],
+    queryFn: () =>
+      shippingLineBookingsService.trainsForDay(booking.id, undefined, cargo),
+  });
+  const options = trainsQuery.data ?? [];
+
+  const openDays = new Set(daysQuery.data?.days ?? []);
+  const selectedTrainId = form.watch("trainScheduleId");
+
+  return (
+    <StepCard>
+      <StepHeader
+        icon={<CalendarDays size={22} />}
+        title="Schedule"
+        description={
+          options.length
+            ? "Pick the train your shipment rides — these departures are dedicated to your company. A booking rides one train."
+            : "Pick the binding shipment day. Only days with a train departure on your route can be selected."
+        }
+      />
+      {/* No currency choice: shipping-line charges always land on the ETB
+          credit ledger — the form defaults paymentCurrency to ETB and the
+          server enforces it. */}
+      <Controller
+        name="scheduledDate"
+        control={form.control}
+        render={({ field, fieldState }) => (
+          <Box>
+            <StepLabel>
+              {options.length ? "Your train *" : "Shipment day *"}
+            </StepLabel>
+            <Box mt={10} w="100%">
+              {trainsQuery.isLoading ? (
+                <Group gap={8} c="dimmed" py="sm">
+                  <Loader size="xs" color="edr-green" />
+                  <Text fz="sm" c="dimmed">
+                    Checking wagon availability on your trains…
+                  </Text>
+                </Group>
+              ) : options.length ? (
+                <Stack gap="sm">
+                  {options.map((option) => {
+                    const day = eatDayOf(option.departure);
+                    const selected = selectedTrainId === option.scheduleId;
+                    // Closed when its own cut-off passed OR the day fell out
+                    // of the bookable set.
+                    const closed = !option.isOpen || !openDays.has(day);
+                    const showFit = (option.neededWagons ?? 0) > 0;
+                    return (
+                      <Paper
+                        key={option.scheduleId}
+                        withBorder
+                        radius="md"
+                        p="md"
+                        onClick={() => {
+                          if (closed) return;
+                          field.onChange(day);
+                          form.setValue("trainScheduleId", option.scheduleId, {
+                            shouldValidate: true,
+                          });
+                        }}
+                        style={{
+                          cursor: closed ? "not-allowed" : "pointer",
+                          opacity: closed ? 0.55 : 1,
+                          borderColor: selected
+                            ? "var(--mantine-color-teal-6)"
+                            : undefined,
+                          borderWidth: selected ? 2 : 1,
+                          background: selected
+                            ? "var(--mantine-color-teal-0)"
+                            : undefined,
+                        }}
+                      >
+                        <Group justify="space-between" wrap="wrap" gap="sm">
+                          <Group gap="sm" align="flex-start">
+                            <Train
+                              size={20}
+                              color={
+                                selected
+                                  ? "var(--mantine-color-teal-7)"
+                                  : "var(--mantine-color-gray-6)"
+                              }
+                            />
+                            <Box>
+                              <Group gap={8}>
+                                <Text fw={700} fz={14}>
+                                  {option.trainNumber ??
+                                    option.trainName ??
+                                    "Train"}
+                                </Text>
+                                {option.trainName && option.trainNumber ? (
+                                  <Text fz={12} c="dimmed">
+                                    {option.trainName}
+                                  </Text>
+                                ) : null}
+                                {closed && (
+                                  <Badge
+                                    size="xs"
+                                    radius="sm"
+                                    color="red"
+                                    variant="light"
+                                  >
+                                    Booking closed
+                                  </Badge>
+                                )}
+                                {!closed && showFit && (
+                                  <Badge
+                                    size="xs"
+                                    radius="sm"
+                                    color={option.fits ? "teal" : "orange"}
+                                    variant="light"
+                                  >
+                                    {option.fits
+                                      ? "Fits your cargo"
+                                      : "Not enough space"}
+                                  </Badge>
+                                )}
+                              </Group>
+                              {/* Free wagons by TYPE — what this train can
+                                  still take for the entered cargo. */}
+                              <Group gap={6} mt={6} wrap="wrap">
+                                {option.byWagonType.length ? (
+                                  option.byWagonType.map((t) => (
+                                    <Badge
+                                      key={t.wagonTypeId ?? "any"}
+                                      size="sm"
+                                      radius="sm"
+                                      variant="outline"
+                                      color={
+                                        t.freeWagons > 0 ? "teal" : "gray"
+                                      }
+                                    >
+                                      {t.code ?? t.name ?? "Wagons"} ·{" "}
+                                      {t.freeWagons} free
+                                    </Badge>
+                                  ))
+                                ) : (
+                                  <Text fz={12} c="dimmed">
+                                    Enter your cargo to see wagon availability
+                                    by type.
+                                  </Text>
+                                )}
+                              </Group>
+                            </Box>
+                          </Group>
+                          <Box ta="right">
+                            <Text fz={13} fw={600}>
+                              Departs{" "}
+                              {new Date(option.departure).toLocaleString(
+                                undefined,
+                                {
+                                  weekday: "short",
+                                  month: "short",
+                                  day: "numeric",
+                                  hour: "2-digit",
+                                  minute: "2-digit",
+                                },
+                              )}
+                            </Text>
+                            {option.bookingClosesAt && (
+                              <Text fz={12} c="dimmed">
+                                Book before{" "}
+                                {new Date(
+                                  option.bookingClosesAt,
+                                ).toLocaleString(undefined, {
+                                  month: "short",
+                                  day: "numeric",
+                                  hour: "2-digit",
+                                  minute: "2-digit",
+                                })}
+                              </Text>
+                            )}
+                          </Box>
+                        </Group>
+                      </Paper>
+                    );
+                  })}
+                </Stack>
+              ) : (
+                <OperationDatePicker
+                  fullWidth
+                  availableDays={daysQuery.data?.days ?? []}
+                  isLoading={daysQuery.isLoading}
+                  emptyMessage="No departures are currently open on this route. Please check back or contact Operations."
+                  value={field.value ?? ""}
+                  onChange={(d) => field.onChange(d)}
+                />
+              )}
+            </Box>
+            {fieldState.error?.message && (
+              <Text fz="xs" c="red" mt={6}>
+                {fieldState.error.message}
+              </Text>
+            )}
+          </Box>
+        )}
+      />
+    </StepCard>
+  );
+}
+
+function ContainerCargoStep({ form }: { form: ShipmentForm }) {
+  // Seed one shipment line per size exactly once.
+  const seededRef = useRef(false);
+  useEffect(() => {
+    if (seededRef.current) return;
+    seededRef.current = true;
+    const existing = form.getValues("containers") ?? [];
+    if (existing.length > 0) return;
+    form.setValue(
+      "containers",
+      SIZES.map((size) => ({
+        containerSize: size,
+        quantity: "0",
+        hazardousQuantity: "0",
+        reeferQuantity: "0",
+        returnQuantity: "0",
+        units: [],
+      })),
+      { shouldValidate: false },
+    );
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const lines = form.watch("containers") ?? [];
+
+  // Excel import: one row per container. All-or-nothing — a file with any bad
+  // row is rejected with row-numbered errors so nothing is silently dropped.
+  const [importErrors, setImportErrors] = useState<string[]>([]);
+  const [importSummary, setImportSummary] = useState<string | null>(null);
+  const importResetRef = useRef<(() => void) | null>(null);
+  const excelOpts = {
+    allowedSizes: [...SIZES],
+    includeHazardous: true,
+    includeReefer: true,
+    includeReturn: false,
+  };
+
+  const handleImportFile = async (file: File | null) => {
+    // Reset the hidden input so re-picking the same (fixed) file re-fires.
+    importResetRef.current?.();
+    if (!file) return;
+    const { rows, errors } = await parseContainerExcel(file, excelOpts);
+    if (errors.length > 0) {
+      setImportSummary(null);
+      setImportErrors(errors);
+      return;
+    }
+    // Replace only the lines for sizes present in the file; a size the file
+    // omits keeps whatever was already entered for it.
+    const current = form.getValues("containers") ?? [];
+    const next = SIZES.map((size) => {
+      const imported = rows.filter((r) => r.containerSize === size);
+      if (imported.length === 0) {
+        return (
+          current.find((l) => l.containerSize === size) ?? {
+            containerSize: size,
+            quantity: "0",
+            hazardousQuantity: "0",
+            reeferQuantity: "0",
+            returnQuantity: "0",
+            units: [],
+          }
+        );
+      }
+      return {
+        containerSize: size,
+        quantity: String(imported.length),
+        hazardousQuantity: String(imported.filter((r) => r.hazardous).length),
+        reeferQuantity: String(imported.filter((r) => r.reefer).length),
+        returnQuantity: "0",
+        // The spreadsheet already marks handling per row — carry it onto the
+        // container it belongs to rather than collapsing it to a line count.
+        units: imported.map((r) => ({
+          containerNumber: r.containerNumber,
+          sealNumber: r.sealNumber,
+          vgmTons: r.vgmTons,
+          isHazardous: Boolean(r.hazardous),
+          isReefer: Boolean(r.reefer),
+          isReturn: false,
+        })),
+      };
+    });
+    form.setValue("containers", next, {
+      shouldValidate: true,
+      shouldDirty: true,
+    });
+    setImportErrors([]);
+    setImportSummary(`Imported ${rows.length} container(s) from ${file.name}.`);
+  };
+
+  return (
+    <StepCard>
+      <StepHeader
+        icon={<Package size={22} />}
+        title="Cargo Details"
+        description="Enter the quantity and per-container details for each size."
+      />
+      <Stack gap={18}>
+        <Paper withBorder radius="md" p="md" style={{ borderColor: "#E6ECF2" }}>
+          <Group justify="space-between" wrap="wrap" gap="sm">
+            <Box>
+              <Text fz={13} fw={600} c="#10202F">
+                Import containers from Excel
+              </Text>
+              <Text fz={12} c="dimmed">
+                One row per container. Importing fills the lines below for the
+                sizes in your file.
+              </Text>
+            </Box>
+            <Group gap="sm">
+              <Button
+                variant="default"
+                size="xs"
+                radius="md"
+                leftSection={<FileDown size={14} />}
+                onClick={() => downloadContainerImportTemplate(excelOpts)}
+              >
+                Download template
+              </Button>
+              <FileButton
+                resetRef={importResetRef}
+                accept=".xlsx,.xls"
+                onChange={handleImportFile}
+              >
+                {(props) => (
+                  <Button
+                    {...props}
+                    size="xs"
+                    radius="md"
+                    color="edr-green"
+                    leftSection={<FileUp size={14} />}
+                  >
+                    Import Excel
+                  </Button>
+                )}
+              </FileButton>
+            </Group>
+          </Group>
+          {importErrors.length > 0 && (
+            <Alert
+              color="red"
+              variant="light"
+              radius="md"
+              icon={<AlertCircle size={16} />}
+              title="Import failed — fix the file and try again"
+              mt="sm"
+            >
+              <Stack gap={4}>
+                {importErrors.slice(0, 8).map((msg, i) => (
+                  <Text key={i} fz="xs">
+                    {msg}
+                  </Text>
+                ))}
+                {importErrors.length > 8 && (
+                  <Text fz="xs" c="dimmed">
+                    …and {importErrors.length - 8} more.
+                  </Text>
+                )}
+              </Stack>
+            </Alert>
+          )}
+          {importSummary && (
+            <Alert
+              color="edr-green"
+              variant="light"
+              radius="md"
+              icon={<CheckCircle2 size={16} />}
+              mt="sm"
+            >
+              <Text fz="xs">{importSummary}</Text>
+            </Alert>
+          )}
+        </Paper>
+        <Controller
+          name="cargoDescription"
+          control={form.control}
+          render={({ field, fieldState }) => (
+            <Textarea
+              label="Cargo description *"
+              description="What do the containers carry on this shipment?"
+              placeholder="e.g. Electronics, garments, machinery spare parts…"
+              value={field.value ?? ""}
+              onChange={(e) => field.onChange(e.currentTarget.value)}
+              onBlur={field.onBlur}
+              error={fieldState.error?.message}
+              radius={10}
+              autosize
+              minRows={2}
+              maxRows={4}
+              styles={fieldStyles}
+            />
+          )}
+        />
+        {lines.map((line, index) => (
+          <ContainerLineEditor
+            key={line.containerSize}
+            form={form}
+            index={index}
+            size={line.containerSize}
+          />
+        ))}
+        {(() => {
+          const ft20 = lines
+            .filter((l) => l.containerSize === "20ft")
+            .reduce((sum, l) => sum + Number(l.quantity || 0), 0);
+          if (ft20 % 2 !== 1) return null;
+          return (
+            <Alert
+              color="red"
+              variant="light"
+              radius="md"
+              icon={<AlertCircle size={16} />}
+              title={`Odd number of 20ft containers (${ft20})`}
+            >
+              <Text fz={13}>
+                20ft containers travel two per wagon, so they must be booked in
+                even numbers. Please add one more 20ft container or remove one
+                (e.g. book {ft20 + 1} or {ft20 - 1} instead of {ft20}) — the
+                booking cannot be submitted with an unpaired 20ft container.
+              </Text>
+            </Alert>
+          );
+        })()}
+      </Stack>
+    </StepCard>
+  );
+}
+
+function BulkCargoStep({
+  form,
+  cargoTypeId,
+  onCargoTypeChange,
+  cargoTypes,
+}: {
+  form: ShipmentForm;
+  cargoTypeId: string | null;
+  onCargoTypeChange: (v: string | null) => void;
+  cargoTypes: {
+    id: string;
+    name: string;
+    parentGroupId: string | null;
+  }[];
+}) {
+  // Grouping headers are rows other rows point at via parentGroupId — only
+  // leaves are bookable cargo.
+  const options = useMemo(() => {
+    const parents = new Set(
+      cargoTypes
+        .map((c) => c.parentGroupId)
+        .filter((id): id is string => Boolean(id)),
+    );
+    return cargoTypes
+      .filter((c) => !parents.has(c.id))
+      .map((c) => ({ value: c.id, label: c.name }));
+  }, [cargoTypes]);
+
+  return (
+    <StepCard>
+      <StepHeader
+        icon={<Package size={22} />}
+        title="Cargo Details"
+        description="Enter the amount you are shipping for this booking."
+      />
+      <Stack gap={14}>
+        <Select
+          label="Cargo type *"
+          placeholder="Select cargo..."
+          searchable
+          data={options}
+          value={cargoTypeId}
+          onChange={onCargoTypeChange}
+          radius={10}
+          styles={fieldStyles}
+          comboboxProps={{ withinPortal: true }}
+        />
+        <Controller
+          name="cargoWeightTons"
+          control={form.control}
+          render={({ field, fieldState }) => (
+            <TextInput
+              {...field}
+              type="number"
+              onKeyDown={blockNegative}
+              label="Total weight (tons) *"
+              placeholder="e.g. 1200"
+              min={0}
+              step={0.01}
+              error={fieldState.error?.message}
+              radius={10}
+              styles={fieldStyles}
+            />
+          )}
+        />
+        <Controller
+          name="bulkHazardousQuantity"
+          control={form.control}
+          render={({ field, fieldState }) => (
+            <TextInput
+              {...field}
+              type="number"
+              onKeyDown={blockNegative}
+              label="Hazardous quantity"
+              min={0}
+              step={1}
+              error={fieldState.error?.message}
+              radius={10}
+              styles={fieldStyles}
+            />
+          )}
+        />
+        <Controller
+          name="bulkReeferQuantity"
+          control={form.control}
+          render={({ field, fieldState }) => (
+            <TextInput
+              {...field}
+              type="number"
+              onKeyDown={blockNegative}
+              label="Refrigerated quantity"
+              min={0}
+              step={1}
+              error={fieldState.error?.message}
+              radius={10}
+              styles={fieldStyles}
+            />
+          )}
+        />
+        <Controller
+          name="cargoDescription"
+          control={form.control}
+          render={({ field }) => (
+            <Textarea
+              label="Cargo description (optional)"
+              placeholder="What the shipment carries"
+              value={field.value ?? ""}
+              onChange={(e) => field.onChange(e.currentTarget.value)}
+              radius={10}
+              autosize
+              minRows={1}
+              maxRows={3}
+              styles={fieldStyles}
+            />
+          )}
+        />
+      </Stack>
+    </StepCard>
+  );
+}
+
+function ContainerLineEditor({
+  form,
+  index,
+  size,
+}: {
+  form: ShipmentForm;
+  index: number;
+  size: "20ft" | "40ft";
+}) {
+  const line = form.watch(`containers.${index}`);
+  const quantity = Number(line?.quantity || 0);
+  const units = line?.units ?? [];
+
+  // Keep the units array length in sync with the entered quantity.
+  const syncUnits = (qty: number) => {
+    const current = form.getValues(`containers.${index}.units`) ?? [];
+    const next = [...current];
+    while (next.length < qty)
+      next.push({
+        containerNumber: "",
+        sealNumber: "",
+        vgmTons: "",
+        isHazardous: false,
+        isReefer: false,
+        isReturn: false,
+      });
+    next.length = Math.max(0, qty);
+    form.setValue(`containers.${index}.units`, next, { shouldValidate: false });
+    syncHandlingCounts(next);
+  };
+
+  // Drop one container row and shrink quantity to match — the inverse of
+  // syncUnits growing the array when quantity goes up.
+  const removeUnit = (unitIdx: number) => {
+    const current = form.getValues(`containers.${index}.units`) ?? [];
+    const next = current.filter((_, j) => j !== unitIdx);
+    form.setValue(`containers.${index}.units`, next, { shouldValidate: false });
+    form.setValue(`containers.${index}.quantity`, String(next.length), {
+      shouldValidate: true,
+    });
+    syncHandlingCounts(next);
+  };
+
+  /**
+   * Line totals are a roll-up of the per-container switches — the count is
+   * however many containers ticked each service. Kept in form state so the
+   * submitted payload stays in step with the switches.
+   */
+  const syncHandlingCounts = (
+    units: Array<{ isHazardous?: boolean; isReefer?: boolean }>,
+  ) => {
+    const set = (
+      key: "hazardousQuantity" | "reeferQuantity",
+      count: number,
+    ) =>
+      form.setValue(`containers.${index}.${key}`, String(count), {
+        shouldDirty: true,
+        shouldValidate: true,
+      });
+    set("hazardousQuantity", units.filter((u) => u.isHazardous).length);
+    set("reeferQuantity", units.filter((u) => u.isReefer).length);
+  };
+
+  /** Flip one container's handling switch, then re-roll the line totals. */
+  const toggleUnitHandling = (
+    unitIndex: number,
+    key: "isHazardous" | "isReefer",
+    on: boolean,
+  ) => {
+    form.setValue(`containers.${index}.units.${unitIndex}.${key}`, on, {
+      shouldDirty: true,
+    });
+    syncHandlingCounts(form.getValues(`containers.${index}.units`) ?? []);
+  };
+
+  const handlingColumns: Array<{
+    key: "isHazardous" | "isReefer";
+    label: string;
+    icon: ReactNode;
+    color: string;
+  }> = [
+    {
+      key: "isHazardous",
+      label: "Hazardous",
+      icon: <Flame size={14} />,
+      color: "#C0392B",
+    },
+    {
+      key: "isReefer",
+      label: "Refrigerated",
+      icon: <Snowflake size={14} />,
+      color: "#2E5B96",
+    },
+  ];
+
+  return (
+    <Box
+      className="rounded-xl"
+      style={{ border: "1px solid #E6ECF2", padding: 16 }}
+    >
+      <Text fz={14} fw={700} c="#10202F" mb={10}>
+        {size} containers
+      </Text>
+      <Box maw={220} mb={14}>
+        <Controller
+          name={`containers.${index}.quantity`}
+          control={form.control}
+          render={({ field, fieldState }) => (
+            <TextInput
+              {...field}
+              type="number"
+              onKeyDown={blockNegative}
+              label="Quantity *"
+              min={0}
+              error={fieldState.error?.message}
+              radius={10}
+              styles={fieldStyles}
+              onChange={(e) => {
+                field.onChange(e.currentTarget.value);
+              }}
+              onBlur={(e) => {
+                field.onBlur();
+                syncUnits(Number(e.currentTarget.value || 0));
+              }}
+            />
+          )}
+        />
+      </Box>
+
+      <StepLabel>Per-container details</StepLabel>
+      {quantity > 0 ? (
+        <Text fz={11} c="#5B6B7B" mt={4}>
+          Tick the services each individual container needs — charges apply only
+          to the containers you tick.
+        </Text>
+      ) : null}
+      <Stack gap={10} mt={8}>
+        {/* Header row — input labels + handling-service labels, one aligned
+            grid shared by every unit row below. */}
+        {Math.max(quantity, units.length) > 0 && (
+          <Group gap={10} wrap="nowrap" align="flex-end">
+            <Text fz={12} fw={600} c="#10202F" style={{ flex: 1 }}>
+              Container number *
+            </Text>
+            <Text fz={12} fw={600} c="#10202F" style={{ flex: 1 }}>
+              Seal number
+            </Text>
+            <Text fz={12} fw={600} c="#10202F" style={{ flex: 1 }}>
+              VGM (tons) *
+            </Text>
+            {handlingColumns.map((col) => (
+              <Group
+                key={col.key}
+                gap={4}
+                wrap="nowrap"
+                justify="center"
+                style={{ width: 96, flexShrink: 0 }}
+              >
+                <span style={{ color: col.color, display: "flex" }}>
+                  {col.icon}
+                </span>
+                <Text fz={12} fw={600} c="#10202F">
+                  {col.label}
+                </Text>
+              </Group>
+            ))}
+          </Group>
+        )}
+        {Array.from({ length: Math.max(quantity, units.length) }).map(
+          (_, u) => (
+            <Group key={u} gap={10} wrap="nowrap" align="flex-start">
+              <Controller
+                name={`containers.${index}.units.${u}.containerNumber`}
+                control={form.control}
+                render={({ field, fieldState }) => (
+                  <TextInput
+                    {...field}
+                    onChange={(e) =>
+                      field.onChange(e.currentTarget.value.toUpperCase())
+                    }
+                    placeholder="e.g. MSCU1234567"
+                    error={fieldState.error?.message}
+                    radius={10}
+                    styles={fieldStyles}
+                    style={{ flex: 1 }}
+                  />
+                )}
+              />
+              <Controller
+                name={`containers.${index}.units.${u}.sealNumber`}
+                control={form.control}
+                render={({ field }) => (
+                  <TextInput
+                    {...field}
+                    placeholder="Optional"
+                    radius={10}
+                    styles={fieldStyles}
+                    style={{ flex: 1 }}
+                  />
+                )}
+              />
+              <Controller
+                name={`containers.${index}.units.${u}.vgmTons`}
+                control={form.control}
+                render={({ field, fieldState }) => (
+                  <TextInput
+                    {...field}
+                    type="number"
+                    onKeyDown={blockNegative}
+                    placeholder="e.g. 24.5"
+                    min={0}
+                    step={0.01}
+                    error={fieldState.error?.message}
+                    radius={10}
+                    styles={fieldStyles}
+                    style={{ flex: 1 }}
+                  />
+                )}
+              />
+              {handlingColumns.map((col) => (
+                <Controller
+                  key={col.key}
+                  name={`containers.${index}.units.${u}.${col.key}`}
+                  control={form.control}
+                  render={({ field }) => (
+                    <Box
+                      style={{
+                        width: 96,
+                        flexShrink: 0,
+                        height: 42,
+                        display: "flex",
+                        alignItems: "center",
+                        justifyContent: "center",
+                      }}
+                    >
+                      <Switch
+                        checked={Boolean(field.value)}
+                        aria-label={`${col.label} — container ${u + 1}`}
+                        onChange={(e) =>
+                          toggleUnitHandling(u, col.key, e.currentTarget.checked)
+                        }
+                        size="sm"
+                      />
+                    </Box>
+                  )}
+                />
+              ))}
+              <ActionIcon
+                variant="subtle"
+                color="red"
+                aria-label={`Remove container ${u + 1}`}
+                onClick={() => removeUnit(u)}
+              >
+                <X size={16} />
+              </ActionIcon>
+            </Group>
+          ),
+        )}
+      </Stack>
+    </Box>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineHomePage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineHomePage.tsx
index 48444820d..4dc00ef39 100644
--- a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineHomePage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineHomePage.tsx
@@ -1,129 +1,795 @@
 import {
   Badge,
-  Card,
-  Center,
+  Box,
+  Button,
+  Grid,
   Group,
-  Loader,
+  Skeleton,
   Stack,
   Text,
-  Title,
 } from "@mantine/core";
 import { useQuery } from "@tanstack/react-query";
-import { ArrowRight, CalendarClock, TrainFront } from "lucide-react";
+import {
+  AlertTriangle,
+  ArrowRight,
+  CalendarClock,
+  Clock3,
+  FileText,
+  FileUp,
+  LifeBuoy,
+  MapPin,
+  Package,
+  PackageCheck,
+  PackagePlus,
+  Receipt,
+  RefreshCw,
+  TrainFront,
+  Upload,
+} from "lucide-react";
+import { useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
 
+import useAuth from "@/hooks/useAuth";
+import { BookingStatusBadge as StatusBadge } from "@/pages/bookings/booking-display";
+import { Card, StatKpi } from "@/pages/MyPortalPage/components";
+import { cv } from "@/pages/MyPortalPage/constants";
 import {
   shippingLineBookingsService,
+  type ShippingLineBooking,
   type ShippingLineTrain,
 } from "@/services/shipping-line-bookings.service";
 
-const STATUS_COLOR: Record<string, string> = {
-  DRAFT: "gray",
-  SCHEDULED: "blue",
-  DISPATCHED: "teal",
-};
+import ShippingLineInitiateModal from "./ShippingLineInitiateModal";
 
-function TrainCard({ train }: { train: ShippingLineTrain }) {
-  const departure = new Date(train.scheduledDepartureDate);
-  return (
-    <Card withBorder radius="md" p="md">
-      <Group justify="space-between" align="flex-start" wrap="wrap" gap="sm">
-        <Stack gap={4}>
-          <Group gap="xs">
-            <TrainFront size={16} />
-            <Text fw={600} fz={14}>
-              {train.trainNumber ?? train.reference ?? "Train"}
-            </Text>
-            {train.reference && train.trainNumber ? (
-              <Text fz={12} c="dimmed">
-                {train.reference}
-              </Text>
-            ) : null}
-            <Badge
-              size="sm"
-              variant="light"
-              color={STATUS_COLOR[train.status] ?? "gray"}
-            >
-              {train.status}
-            </Badge>
-          </Group>
-          <Group gap={6}>
-            <Text fz={13}>{train.originLabel}</Text>
-            <ArrowRight size={13} />
-            <Text fz={13}>{train.destinationLabel}</Text>
-          </Group>
-        </Stack>
-        <Stack gap={2} align="flex-end">
-          <Group gap={6}>
-            <CalendarClock size={14} />
-            <Text fz={13} fw={500}>
-              {departure.toLocaleDateString(undefined, {
-                weekday: "short",
-                year: "numeric",
-                month: "short",
-                day: "numeric",
-              })}
-            </Text>
-          </Group>
-          <Text fz={12} c="dimmed">
-            Departs{" "}
-            {departure.toLocaleTimeString(undefined, {
-              hour: "2-digit",
-              minute: "2-digit",
-            })}
-          </Text>
-        </Stack>
-      </Group>
-    </Card>
-  );
+/* ── Pending-action derivation ─────────────────────────────────────────────
+ * One row per booking that is waiting on the LINE (never on EDR). Priority:
+ * a queried/returned document set outranks everything — it blocks the rest. */
+
+type ActionKind = "fix" | "resubmit" | "book" | "upload";
+
+interface PendingAction {
+  kind: ActionKind;
+  booking: ShippingLineBooking;
+  urgent: boolean;
+  description: string;
 }
 
+const ACTION_META: Record<
+  ActionKind,
+  { icon: typeof FileUp; color: string; button: string }
+> = {
+  fix: { icon: FileUp, color: "red", button: "Fix documents" },
+  resubmit: { icon: RefreshCw, color: "orange", button: "Resubmit" },
+  book: { icon: PackagePlus, color: "violet", button: "Book" },
+  upload: { icon: Upload, color: "blue", button: "Upload documents" },
+};
+
+function deriveActions(bookings: ShippingLineBooking[]): PendingAction[] {
+  const actions: PendingAction[] = [];
+  for (const b of bookings) {
+    const status = b.status as string;
+    if (status === "CANCELLED") continue;
+    if (b.hasQueriedDocuments || status === "CHANGES_REQUESTED") {
+      actions.push({
+        kind: "fix",
+        booking: b,
+        urgent: true,
+        description: "A reviewer queried your documents — fix and re-upload.",
+      });
+    } else if (status === "OPERATION_CHANGES_REQUESTED") {
+      actions.push({
+        kind: "resubmit",
+        booking: b,
+        urgent: true,
+        description:
+          "Operations returned your request — update it and resubmit.",
+      });
+    } else if (status === "CLEARANCE_READY") {
+      actions.push({
+        kind: "book",
+        booking: b,
+        urgent: false,
+        description:
+          "Documents approved — enter the cargo and shipment day to book.",
+      });
+    } else if (status === "AWAITING_DOCUMENTS") {
+      actions.push({
+        kind: "upload",
+        booking: b,
+        urgent: false,
+        description: "Upload your documents to start the review.",
+      });
+    }
+  }
+  return actions.sort((a, b) => Number(b.urgent) - Number(a.urgent));
+}
+
+const laneLabel = (b: ShippingLineBooking) =>
+  `${b.originYard?.label ?? b.originYard?.code ?? "—"} → ${
+    b.destinationYard?.label ?? b.destinationYard?.code ?? "—"
+  }`;
+
+const timeGreeting = () => {
+  const h = new Date().getHours();
+  if (h < 12) return "Good morning";
+  if (h < 18) return "Good afternoon";
+  return "Good evening";
+};
+
+/** Whole days from now to `date`, floored at 0 (today). */
+const daysUntil = (date: string) =>
+  Math.max(
+    0,
+    Math.ceil((new Date(date).getTime() - Date.now()) / 86_400_000),
+  );
+
+/* ── Page ──────────────────────────────────────────────────────────────── */
+
 /**
- * Shipping-line home / dashboard. Deliberately separate from the customer
- * dashboard (`MyPortalPage`): shipping lines have no company, no operational
- * profiles and no contracts, so almost none of that page's data applies.
- *
- * Lists the train departures dedicated to this shipping line — those trains
- * are hidden from customers, so this page (and the booking detail's lane/day
- * match) is where the line sees them.
+ * Shipping-line home. Mirrors the customer dashboard's anatomy — greeting +
+ * primary CTA, KPI band, "needs your attention" queue — but its centrepiece is
+ * the departure board: the line's next dedicated train, which no customer ever
+ * sees, so this page is where it must feel real.
  */
 export default function ShippingLineHomePage() {
+  const navigate = useNavigate();
+  const { shippingLine } = useAuth();
+  // The hook's union type collapses on direct property access; the account is
+  // positively a shipping line on these routes, so the cast is safe.
+  const lineName =
+    (shippingLine as { name?: string } | null)?.name ?? "Shipping line";
+  const [initiateOpen, setInitiateOpen] = useState(false);
+
+  const bookingsQuery = useQuery({
+    queryKey: ["shipping-line-bookings"],
+    queryFn: shippingLineBookingsService.list,
+  });
   const trainsQuery = useQuery({
     queryKey: ["shipping-line-my-trains"],
     queryFn: shippingLineBookingsService.myTrains,
   });
 
+  const bookings = useMemo(
+    () => bookingsQuery.data ?? [],
+    [bookingsQuery.data],
+  );
   const trains = trainsQuery.data ?? [];
+  const actions = useMemo(() => deriveActions(bookings), [bookings]);
+
+  const activeBookings = bookings.filter(
+    (b) => (b.status as string) !== "CANCELLED",
+  );
+  const inReview = bookings.filter(
+    (b) =>
+      !b.hasQueriedDocuments &&
+      ["DOCUMENTS_UNDER_REVIEW", "OPERATION_REQUEST_PENDING"].includes(
+        b.status as string,
+      ),
+  );
+
+  const upcoming = trains.filter(
+    (t) => new Date(t.scheduledDepartureDate).getTime() > Date.now() - 3_600_000,
+  );
+  const nextTrain = upcoming[0] ?? null;
+  const laterTrains = nextTrain ? upcoming.slice(1) : upcoming;
+
+  // Trains this line has BOOKED: allocated ones by trainScheduleId, plus —
+  // before allocation lands — any live booking on the same lane + shipment
+  // day. The hero shows EVERY booked departure of the next booked day, not
+  // just the first train.
+  const isSameDay = (a: string | Date, b: string | Date) =>
+    new Date(a).toDateString() === new Date(b).toDateString();
+  const bookedUpcoming = upcoming.filter((t) =>
+    activeBookings.some(
+      (b) =>
+        b.trainScheduleId === t.id ||
+        (b.scheduledDate &&
+          isSameDay(b.scheduledDate, t.scheduledDepartureDate) &&
+          b.originYard?.id === t.originYardId &&
+          b.destinationYard?.id === t.destinationYardId),
+    ),
+  );
+  const nextBookedDay = bookedUpcoming[0]
+    ? new Date(bookedUpcoming[0].scheduledDepartureDate).toDateString()
+    : null;
+  const nextDayDepartures = nextBookedDay
+    ? bookedUpcoming.filter((t) =>
+        isSameDay(t.scheduledDepartureDate, nextBookedDay),
+      )
+    : [];
+  // Booked departures take the hero; with none, fall back to the line's next
+  // dedicated train so the board never goes blank while trains exist.
+  const heroTrains = nextDayDepartures.length
+    ? nextDayDepartures
+    : nextTrain
+      ? [nextTrain]
+      : [];
+  const heroIsBooked = nextDayDepartures.length > 0;
+  const heroFirst = heroTrains[0] ?? null;
+
+  const goToAction = (a: PendingAction) =>
+    navigate(
+      a.kind === "book" || a.kind === "resubmit"
+        ? `/shipping-line/bookings/${a.booking.id}/complete`
+        : `/shipping-line/bookings/${a.booking.id}`,
+    );
 
   return (
     <Stack gap="lg" p={{ base: 16, sm: 24, lg: 32 }}>
-      <Stack gap={4}>
-        <Title order={2}>Home</Title>
-        <Text c="dimmed" size="sm">
-          Overview of your shipping-line activity.
-        </Text>
-      </Stack>
-
-      <Stack gap="sm">
-        <Text fw={600} fz={15}>
-          Your trains
-        </Text>
-        {trainsQuery.isLoading ? (
-          <Center py="xl">
-            <Loader size="sm" />
-          </Center>
-        ) : trains.length === 0 ? (
-          <Card withBorder radius="md" py={48}>
-            <Stack align="center" gap="xs">
-              <TrainFront size={28} className="text-slate-300" />
-              <Text c="dimmed" size="sm">
-                No trains have been assigned to you yet.
+      {/* Greeting + the one primary action, same shape as the customer home. */}
+      <Group justify="space-between" align="center" gap="md">
+        <Box>
+          <Text size="sm" c="edr-muted">
+            {timeGreeting()}
+          </Text>
+          <Text fz={26} fw={800} c="edr-text" className="tracking-tight" mt={2}>
+            {lineName} ⚓
+          </Text>
+        </Box>
+        <Box
+          component="button"
+          onClick={() => setInitiateOpen(true)}
+          className="w-full cursor-pointer border-none bg-transparent p-0 text-left md:w-auto"
+        >
+          <Group
+            gap={14}
+            align="center"
+            wrap="nowrap"
+            bg="edr-green"
+            px={18}
+            py={14}
+            className="w-full md:w-60! rounded-2xl shadow-[0_6px_10px_-12px_rgba(14,163,83,0.8)]"
+          >
+            <PackagePlus size={22} color="#fff" />
+            <Box className="min-w-0 flex-1">
+              <Text fz={14} fw={700} c="white" lh={1.3}>
+                Initiate a booking
               </Text>
+            </Box>
+            <Box className="flex h-[32px] w-[32px] shrink-0 items-center justify-center rounded-full bg-white">
+              <ArrowRight size={18} color={cv("edr-green.7")} />
+            </Box>
+          </Group>
+        </Box>
+      </Group>
+
+      {/* KPI band — one card, four figures that answer "where do I stand". */}
+      <Card>
+        <Box className="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-4 lg:gap-4">
+          <StatKpi
+            icon={Package}
+            label="Active bookings"
+            value={String(activeBookings.length)}
+            delta=""
+            accent="green"
+            loading={bookingsQuery.isPending}
+          />
+          <StatKpi
+            icon={AlertTriangle}
+            label="Waiting on you"
+            value={String(actions.length)}
+            delta={actions.length > 0 ? "action needed" : "all clear"}
+            accent="amber"
+            deltaTone={actions.length > 0 ? "amber" : "muted"}
+            divider
+            loading={bookingsQuery.isPending}
+          />
+          <StatKpi
+            icon={Clock3}
+            label="In review with EDR"
+            value={String(inReview.length)}
+            delta=""
+            accent="blue"
+            divider
+            loading={bookingsQuery.isPending}
+          />
+          <StatKpi
+            icon={TrainFront}
+            label="Upcoming trains"
+            value={String(upcoming.length)}
+            delta=""
+            accent="slate"
+            divider
+            loading={trainsQuery.isPending}
+          />
+        </Box>
+      </Card>
+
+      {/* Bookings waiting on the line — urgent first, one click to the fix. */}
+      {actions.length > 0 && (
+        <Card padding={0}>
+          <Group justify="space-between" align="center" px={24} pt={20} pb={12}>
+            <Group gap={8}>
+              <AlertTriangle size={18} className="text-amber-500" />
+              <Text fw={700} fz={16} c="edr-text">
+                Needs your attention
+              </Text>
+            </Group>
+            <Badge color="orange" variant="light" radius="sm">
+              {actions.length}
+            </Badge>
+          </Group>
+          <Stack gap={0}>
+            {actions.map((a, i) => {
+              const meta = ACTION_META[a.kind];
+              const Icon = meta.icon;
+              return (
+                <Group
+                  key={a.booking.id}
+                  justify="space-between"
+                  wrap="nowrap"
+                  px={24}
+                  py={14}
+                  style={{
+                    borderTop:
+                      i === 0 ? "none" : "1px solid var(--mantine-color-gray-2)",
+                    cursor: "pointer",
+                  }}
+                  onClick={() => goToAction(a)}
+                  className="hover:bg-edr-soft"
+                >
+                  <Group gap={12} wrap="nowrap" style={{ minWidth: 0 }}>
+                    <Box
+                      style={{
+                        width: 36,
+                        height: 36,
+                        flexShrink: 0,
+                        borderRadius: 10,
+                        display: "flex",
+                        alignItems: "center",
+                        justifyContent: "center",
+                        background: `var(--mantine-color-${meta.color}-light)`,
+                        color: `var(--mantine-color-${meta.color}-filled)`,
+                      }}
+                    >
+                      <Icon size={18} />
+                    </Box>
+                    <Box style={{ minWidth: 0 }}>
+                      <Group gap={8} wrap="nowrap">
+                        <Text fw={600} fz={14} c="edr-text" truncate>
+                          {a.booking.reference}
+                        </Text>
+                        {a.urgent && (
+                          <Badge
+                            size="xs"
+                            color="red"
+                            variant="light"
+                            radius="sm"
+                          >
+                            Action required
+                          </Badge>
+                        )}
+                      </Group>
+                      <Text fz={12.5} c="dimmed" truncate>
+                        {laneLabel(a.booking)} · {a.description}
+                      </Text>
+                    </Box>
+                  </Group>
+                  <Button
+                    size="compact-sm"
+                    variant={a.urgent ? "filled" : "light"}
+                    color={meta.color}
+                    radius="md"
+                  >
+                    {meta.button}
+                  </Button>
+                </Group>
+              );
+            })}
+          </Stack>
+        </Card>
+      )}
+
+      {/* The departure board — every departure the line has BOOKED on its
+          next booked day (falling back to the next dedicated train when
+          nothing is booked yet). These trains are invisible to customers, so
+          this is the one place they surface; give them real presence. */}
+      {heroFirst && (
+        <Box
+          className="rounded-[20px]"
+          p={{ base: 20, sm: 28 }}
+          style={{
+            background: `linear-gradient(120deg, ${cv("edr-green.9")} 0%, ${cv(
+              "edr-green.7",
+            )} 60%, ${cv("edr-green.6")} 100%)`,
+            color: "#fff",
+          }}
+        >
+          <Group justify="space-between" align="flex-end" wrap="wrap" gap="lg">
+            <Box>
+              <Group gap={8} mb={6}>
+                <TrainFront size={16} color="rgba(255,255,255,0.85)" />
+                <Text
+                  fz={11}
+                  fw={700}
+                  tt="uppercase"
+                  style={{ letterSpacing: "0.12em", color: "rgba(255,255,255,0.85)" }}
+                >
+                  {heroIsBooked
+                    ? heroTrains.length > 1
+                      ? "Your booked departures"
+                      : "Your next departure"
+                    : "Your next departure"}
+                </Text>
+                {heroIsBooked && (
+                  <Badge
+                    size="sm"
+                    radius="sm"
+                    variant="white"
+                    color="edr-green"
+                    fw={700}
+                  >
+                    {heroTrains.length > 1
+                      ? `${heroTrains.length} trains`
+                      : "Booked"}
+                  </Badge>
+                )}
+              </Group>
+              <Text fz={{ base: 28, sm: 34 }} fw={800} lh={1.1} c="white">
+                {new Date(heroFirst.scheduledDepartureDate).toLocaleDateString(
+                  undefined,
+                  { weekday: "long", month: "long", day: "numeric" },
+                )}
+              </Text>
+            </Box>
+            <Stack gap={10} align="flex-end">
+              <Group
+                gap={8}
+                px={14}
+                py={8}
+                className="rounded-full"
+                style={{ background: "rgba(255,255,255,0.16)" }}
+              >
+                <CalendarClock size={15} color="#fff" />
+                <Text fz={13} fw={700} c="white">
+                  {daysUntil(heroFirst.scheduledDepartureDate) === 0
+                    ? "Departs today"
+                    : daysUntil(heroFirst.scheduledDepartureDate) === 1
+                      ? "Departs tomorrow"
+                      : `Departs in ${daysUntil(
+                          heroFirst.scheduledDepartureDate,
+                        )} days`}
+                </Text>
+              </Group>
+              {!heroIsBooked && (
+                <Text fz={11.5} style={{ color: "rgba(255,255,255,0.75)" }}>
+                  Departs{" "}
+                  {new Date(
+                    heroFirst.scheduledDepartureDate,
+                  ).toLocaleTimeString(undefined, {
+                    hour: "2-digit",
+                    minute: "2-digit",
+                  })}{" "}
+                  · bookable until the cut-off before departure
+                </Text>
+              )}
             </Stack>
+          </Group>
+
+          {/* Every departure of that day — one row per train. */}
+          <Stack gap={8} mt={16}>
+            {heroTrains.map((t) => (
+              <Group
+                key={t.id}
+                justify="space-between"
+                wrap="wrap"
+                gap="sm"
+                px={14}
+                py={10}
+                className="rounded-xl"
+                style={{ background: "rgba(255,255,255,0.12)" }}
+              >
+                <Group gap={10} wrap="nowrap">
+                  <MapPin size={15} color="rgba(255,255,255,0.85)" />
+                  <Text fz={14} fw={600} style={{ color: "rgba(255,255,255,0.95)" }}>
+                    {t.originLabel} → {t.destinationLabel}
+                    {t.trainNumber
+                      ? ` · Train ${t.trainNumber}`
+                      : t.reference
+                        ? ` · ${t.reference}`
+                        : ""}
+                  </Text>
+                </Group>
+                <Group gap={10}>
+                  <Text fz={13} fw={700} c="white">
+                    {new Date(t.scheduledDepartureDate).toLocaleTimeString(
+                      undefined,
+                      { hour: "2-digit", minute: "2-digit" },
+                    )}
+                  </Text>
+                  <Badge
+                    size="sm"
+                    radius="sm"
+                    variant="white"
+                    color="edr-green"
+                    fw={700}
+                  >
+                    {t.status}
+                  </Badge>
+                </Group>
+              </Group>
+            ))}
+          </Stack>
+        </Box>
+      )}
+
+      {/* Trains + recent bookings, side by side. */}
+      <Grid align="stretch">
+        <Grid.Col span={{ base: 12, lg: 5 }}>
+          <Card padding={0} className="h-full">
+            <Group justify="space-between" px={24} pt={20} pb={12}>
+              <Group gap={8}>
+                <TrainFront size={17} color={cv("edr-green.7")} />
+                <Text fw={700} fz={16} c="edr-text">
+                  Your trains
+                </Text>
+              </Group>
+              <Badge variant="light" color="gray" radius="sm">
+                {upcoming.length}
+              </Badge>
+            </Group>
+            {trainsQuery.isPending ? (
+              <Stack gap={10} px={24} pb={20}>
+                <Skeleton height={54} radius="md" />
+                <Skeleton height={54} radius="md" />
+              </Stack>
+            ) : upcoming.length === 0 ? (
+              <TrainsEmpty />
+            ) : (
+              <Stack gap={0} pb={8}>
+                {(nextTrain ? [nextTrain, ...laterTrains] : laterTrains).map(
+                  (t, i) => (
+                    <TrainRow key={t.id} train={t} first={i === 0} />
+                  ),
+                )}
+              </Stack>
+            )}
           </Card>
-        ) : (
-          trains.map((train) => <TrainCard key={train.id} train={train} />)
-        )}
-      </Stack>
+        </Grid.Col>
+
+        <Grid.Col span={{ base: 12, lg: 7 }}>
+          <Card padding={0} className="h-full">
+            <Group justify="space-between" px={24} pt={20} pb={12}>
+              <Group gap={8}>
+                <FileText size={17} color={cv("edr-blue")} />
+                <Text fw={700} fz={16} c="edr-text">
+                  Recent bookings
+                </Text>
+              </Group>
+              <Button
+                variant="subtle"
+                color="gray"
+                size="compact-sm"
+                rightSection={<ArrowRight size={14} />}
+                onClick={() => navigate("/shipping-line/bookings")}
+              >
+                View all
+              </Button>
+            </Group>
+            {bookingsQuery.isPending ? (
+              <Stack gap={10} px={24} pb={20}>
+                <Skeleton height={54} radius="md" />
+                <Skeleton height={54} radius="md" />
+                <Skeleton height={54} radius="md" />
+              </Stack>
+            ) : bookings.length === 0 ? (
+              <BookingsEmpty onInitiate={() => setInitiateOpen(true)} />
+            ) : (
+              <Stack gap={0} pb={8}>
+                {bookings.slice(0, 6).map((b, i) => (
+                  <Group
+                    key={b.id}
+                    justify="space-between"
+                    wrap="nowrap"
+                    px={24}
+                    py={12}
+                    style={{
+                      borderTop:
+                        i === 0
+                          ? "none"
+                          : "1px solid var(--mantine-color-gray-2)",
+                      cursor: "pointer",
+                    }}
+                    className="hover:bg-edr-soft"
+                    onClick={() => navigate(`/shipping-line/bookings/${b.id}`)}
+                  >
+                    <Box style={{ minWidth: 0 }}>
+                      <Text fw={600} fz={14} c="edr-text" truncate>
+                        {b.reference}
+                      </Text>
+                      <Text fz={12.5} c="dimmed" truncate>
+                        {laneLabel(b)}
+                        {b.scheduledDate
+                          ? ` · ships ${new Date(
+                              b.scheduledDate,
+                            ).toLocaleDateString()}`
+                          : ""}
+                      </Text>
+                    </Box>
+                    <StatusBadge status={b.status as string} />
+                  </Group>
+                ))}
+              </Stack>
+            )}
+          </Card>
+        </Grid.Col>
+      </Grid>
+
+      {/* Quick links — the rest of the portal, one hop away. */}
+      <Box className="grid grid-cols-1 gap-4 sm:grid-cols-3">
+        <QuickLink
+          icon={PackageCheck}
+          title="My bookings"
+          hint="Track every booking and its documents"
+          onClick={() => navigate("/shipping-line/bookings")}
+        />
+        <QuickLink
+          icon={Receipt}
+          title="Invoices"
+          hint="Charges on your credit account"
+          onClick={() => navigate("/shipping-line/invoices")}
+        />
+        <QuickLink
+          icon={LifeBuoy}
+          title="Help & support"
+          hint="Guides and contact channels"
+          onClick={() => navigate("/shipping-line/help")}
+        />
+      </Box>
+
+      <ShippingLineInitiateModal
+        opened={initiateOpen}
+        onClose={() => setInitiateOpen(false)}
+        onCreated={(booking) => {
+          setInitiateOpen(false);
+          navigate(`/shipping-line/bookings/${booking.id}`);
+        }}
+      />
     </Stack>
   );
 }
+
+/* ── Small pieces ──────────────────────────────────────────────────────── */
+
+function TrainRow({
+  train,
+  first,
+}: {
+  train: ShippingLineTrain;
+  first: boolean;
+}) {
+  const departure = new Date(train.scheduledDepartureDate);
+  return (
+    <Group
+      justify="space-between"
+      wrap="nowrap"
+      px={24}
+      py={12}
+      style={{
+        borderTop: first ? "none" : "1px solid var(--mantine-color-gray-2)",
+      }}
+    >
+      <Group gap={12} wrap="nowrap" style={{ minWidth: 0 }}>
+        <Box
+          style={{
+            width: 36,
+            height: 36,
+            flexShrink: 0,
+            borderRadius: 10,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            background: cv("edr-soft"),
+            color: cv("edr-green.7"),
+          }}
+        >
+          <TrainFront size={18} />
+        </Box>
+        <Box style={{ minWidth: 0 }}>
+          <Text fw={600} fz={14} c="edr-text" truncate>
+            {train.trainNumber ?? train.reference ?? "Train"}
+          </Text>
+          <Text fz={12.5} c="dimmed" truncate>
+            {train.originLabel} → {train.destinationLabel}
+          </Text>
+        </Box>
+      </Group>
+      <Box style={{ textAlign: "right", flexShrink: 0 }}>
+        <Text fz={13} fw={600} c="edr-text">
+          {departure.toLocaleDateString(undefined, {
+            month: "short",
+            day: "numeric",
+          })}
+        </Text>
+        <Text fz={11.5} c="dimmed">
+          {departure.toLocaleTimeString(undefined, {
+            hour: "2-digit",
+            minute: "2-digit",
+          })}
+        </Text>
+      </Box>
+    </Group>
+  );
+}
+
+function TrainsEmpty() {
+  return (
+    <Stack align="center" gap={6} py={36} px={24}>
+      <TrainFront size={26} color={cv("edr-slate")} />
+      <Text fz={13.5} c="dimmed" ta="center">
+        No trains assigned to you yet — Operations dedicates departures to your
+        line and they appear here.
+      </Text>
+    </Stack>
+  );
+}
+
+function BookingsEmpty({ onInitiate }: { onInitiate: () => void }) {
+  return (
+    <Stack align="center" gap={10} py={32} px={24}>
+      <Package size={26} color={cv("edr-slate")} />
+      <Text fz={13.5} c="dimmed" ta="center">
+        No bookings yet. Initiate one — you upload documents next, and book the
+        cargo once they are approved.
+      </Text>
+      <Button
+        color="edr-green"
+        radius="md"
+        size="compact-md"
+        leftSection={<PackagePlus size={15} />}
+        onClick={onInitiate}
+      >
+        Initiate a booking
+      </Button>
+    </Stack>
+  );
+}
+
+function QuickLink({
+  icon: Icon,
+  title,
+  hint,
+  onClick,
+}: {
+  icon: typeof Receipt;
+  title: string;
+  hint: string;
+  onClick: () => void;
+}) {
+  return (
+    <Box
+      component="button"
+      onClick={onClick}
+      className="cursor-pointer rounded-[16px] border border-edr-border bg-edr-card p-4 text-left transition-colors hover:bg-edr-soft"
+    >
+      <Group gap={12} wrap="nowrap">
+        <Box
+          style={{
+            width: 38,
+            height: 38,
+            flexShrink: 0,
+            borderRadius: 11,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            background: cv("edr-soft"),
+            color: cv("edr-green.7"),
+          }}
+        >
+          <Icon size={18} />
+        </Box>
+        <Box style={{ minWidth: 0 }}>
+          <Group gap={6} wrap="nowrap">
+            <Text fw={700} fz={14} c="edr-text">
+              {title}
+            </Text>
+            <ArrowRight size={14} color={cv("edr-muted")} />
+          </Group>
+          <Text fz={12} c="dimmed" truncate>
+            {hint}
+          </Text>
+        </Box>
+      </Group>
+    </Box>
+  );
+}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineInvoicesPage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineInvoicesPage.tsx
index 8c0a4cb4a..fd63a288d 100644
--- a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineInvoicesPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineInvoicesPage.tsx
@@ -1,13 +1,231 @@
-import { Receipt } from "lucide-react";
-import ShippingLinePlaceholder from "./ShippingLinePlaceholder";
+import {
+  Alert,
+  Box,
+  Button,
+  Card,
+  Center,
+  Group,
+  Loader,
+  SimpleGrid,
+  Stack,
+  Table,
+  Text,
+  Title,
+} from "@mantine/core";
+import { useQuery } from "@tanstack/react-query";
+import { Freight } from "@edr/types";
+import { ChevronRight, Info, Receipt } from "lucide-react";
+import { useMemo } from "react";
+import { useNavigate } from "react-router-dom";
 
-/** Shipping-line payments / invoices. */
-export default function ShippingLineInvoicesPage() {
+import { formatCurrency } from "@/lib/currency";
+import { api } from "@/services/api";
+import { BORDER, INK, MUTED } from "../contracts/contract-ui";
+import { fmtDate, InvoiceStatusBadge, isPayable } from "../billing/invoice-ui";
+
+function StatBox({ label, value }: { label: string; value: string }) {
   return (
-    <ShippingLinePlaceholder
-      title="Payments"
-      description="Your invoices and payment history."
-      icon={<Receipt size={28} className="text-slate-300" />}
-    />
+    <Card withBorder radius="md" padding="md">
+      <Text
+        fz={11}
+        fw={700}
+        c={MUTED}
+        style={{ textTransform: "uppercase", letterSpacing: "0.05em" }}
+      >
+        {label}
+      </Text>
+      <Text fz={22} fw={800} mt={4} style={{ color: INK }}>
+        {value}
+      </Text>
+    </Card>
+  );
+}
+
+/**
+ * The shipping line's credit invoices — Finance bills batches of the line's
+ * booking charges, and each invoice is payable at any CBE channel whenever the
+ * line chooses; there is no payment window. Detail (which bookings, each
+ * charge, the total) lives one click deeper on the shared invoice detail page.
+ */
+export default function ShippingLineInvoicesPage() {
+  const navigate = useNavigate();
+  const {
+    data: allInvoices,
+    isLoading,
+    isError,
+    refetch,
+  } = useQuery(api.invoices.listMy.queryOptions());
+
+  // Only the credit invoices: a shipping line's bookings are charged through
+  // the credit ledger, so other sources (e.g. a booking's internal draft
+  // invoice) would only double-state the same debt here.
+  const invoices = useMemo(
+    () =>
+      (allInvoices ?? []).filter(
+        (inv) => inv.source === Freight.InvoiceSource.ShippingLineCredit,
+      ),
+    [allInvoices],
+  );
+
+  const openInvoices = invoices.filter((inv) => isPayable(inv.status));
+  const outstanding = openInvoices.reduce(
+    (sum, inv) => sum + Number(inv.balanceAmount ?? inv.totalAmount),
+    0,
+  );
+  const currency = invoices[0]?.currency ?? "ETB";
+
+  return (
+    <Stack gap="lg" p={{ base: 16, sm: 24, lg: 32 }}>
+      <Stack gap={4}>
+        <Title order={2}>Invoices</Title>
+        <Text c="dimmed" size="sm">
+          Your billed freight charges. Pay any open invoice at a CBE branch,
+          the CBE app or USSD using its bill reference — there is no payment
+          deadline window.
+        </Text>
+      </Stack>
+
+      <SimpleGrid cols={{ base: 1, sm: 3 }}>
+        <StatBox
+          label="Outstanding balance"
+          value={formatCurrency(outstanding, currency)}
+        />
+        <StatBox label="Open invoices" value={String(openInvoices.length)} />
+        <StatBox
+          label="Paid invoices"
+          value={String(
+            invoices.filter(
+              (inv) => inv.status === Freight.InvoiceStatus.Paid,
+            ).length,
+          )}
+        />
+      </SimpleGrid>
+
+      {isLoading ? (
+        <Center py={64}>
+          <Loader color="edr-green" />
+        </Center>
+      ) : isError ? (
+        <Alert color="red" title="Could not load invoices">
+          <Group gap="sm">
+            <Text size="sm">Something went wrong.</Text>
+            <Button size="compact-sm" variant="light" onClick={() => refetch()}>
+              Retry
+            </Button>
+          </Group>
+        </Alert>
+      ) : invoices.length === 0 ? (
+        <Card withBorder radius="md" py={64}>
+          <Stack align="center" gap="xs">
+            <Receipt size={28} className="text-slate-300" />
+            <Text c="dimmed" size="sm">
+              No invoices yet. Finance bills your accumulated booking charges
+              in batches — invoices will appear here once issued.
+            </Text>
+          </Stack>
+        </Card>
+      ) : (
+        <Card withBorder radius="md" p={0} style={{ overflow: "hidden" }}>
+          <Box style={{ overflowX: "auto" }}>
+            <Table
+              highlightOnHover
+              verticalSpacing={12}
+              horizontalSpacing={20}
+              styles={{
+                th: {
+                  fontSize: 11,
+                  fontWeight: 700,
+                  letterSpacing: "0.05em",
+                  textTransform: "uppercase",
+                  color: MUTED,
+                  background: "#F8FAFC",
+                  borderBottom: `1px solid ${BORDER}`,
+                  whiteSpace: "nowrap",
+                },
+                td: { borderBottom: `1px solid ${BORDER}` },
+              }}
+            >
+              <Table.Thead>
+                <Table.Tr>
+                  <Table.Th>Invoice</Table.Th>
+                  <Table.Th>Issued</Table.Th>
+                  <Table.Th>Due</Table.Th>
+                  <Table.Th ta="right">Amount</Table.Th>
+                  <Table.Th ta="right">Balance</Table.Th>
+                  <Table.Th>Status</Table.Th>
+                  <Table.Th />
+                </Table.Tr>
+              </Table.Thead>
+              <Table.Tbody>
+                {invoices.map((inv) => (
+                  <Table.Tr
+                    key={inv.id}
+                    style={{ cursor: "pointer" }}
+                    onClick={() =>
+                      navigate(`/shipping-line/invoices/${inv.id}`)
+                    }
+                  >
+                    <Table.Td>
+                      <Text fz={14} fw={700} ff="monospace" style={{ color: INK }}>
+                        {inv.invoiceNumber}
+                      </Text>
+                    </Table.Td>
+                    <Table.Td>
+                      <Text fz={13}>{fmtDate(inv.issuedAt)}</Text>
+                    </Table.Td>
+                    <Table.Td>
+                      <Text fz={13}>{fmtDate(inv.dueAt)}</Text>
+                    </Table.Td>
+                    <Table.Td ta="right">
+                      <Text fz={13} fw={600}>
+                        {formatCurrency(Number(inv.totalAmount), inv.currency)}
+                      </Text>
+                    </Table.Td>
+                    <Table.Td ta="right">
+                      <Text fz={13} fw={600}>
+                        {formatCurrency(
+                          Number(inv.balanceAmount ?? inv.totalAmount),
+                          inv.currency,
+                        )}
+                      </Text>
+                    </Table.Td>
+                    <Table.Td>
+                      <InvoiceStatusBadge status={inv.status} />
+                    </Table.Td>
+                    <Table.Td ta="right">
+                      <Button
+                        size="compact-sm"
+                        variant={isPayable(inv.status) ? "filled" : "light"}
+                        color="edr-green"
+                        rightSection={<ChevronRight size={14} />}
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          navigate(`/shipping-line/invoices/${inv.id}`);
+                        }}
+                      >
+                        {isPayable(inv.status) ? "View & pay" : "View"}
+                      </Button>
+                    </Table.Td>
+                  </Table.Tr>
+                ))}
+              </Table.Tbody>
+            </Table>
+          </Box>
+        </Card>
+      )}
+
+      <Alert
+        icon={<Info size={16} />}
+        color="blue"
+        variant="light"
+        p="sm"
+      >
+        <Text size="sm">
+          Open an invoice and choose <b>Pay</b> → <b>CBE</b> to get its bill
+          reference. Pay against that reference at any CBE branch, in the CBE
+          app or via USSD; the invoice settles automatically once CBE confirms.
+        </Text>
+      </Alert>
+    </Stack>
   );
 }
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/index.ts b/apps/edr-freight-web/portal/src/pages/shipping-line/index.ts
index caaccee22..67557dd25 100644
--- a/apps/edr-freight-web/portal/src/pages/shipping-line/index.ts
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/index.ts
@@ -1,6 +1,7 @@
 export { default as ShippingLineHomePage } from "./ShippingLineHomePage";
 export { default as ShippingLineBookingsPage } from "./ShippingLineBookingsPage";
 export { default as ShippingLineBookingDetailPage } from "./ShippingLineBookingDetailPage";
+export { default as ShippingLineCompletePage } from "./ShippingLineCompletePage";
 export { default as ShippingLineInvoicesPage } from "./ShippingLineInvoicesPage";
 export { default as ShippingLineSettingsPage } from "./ShippingLineSettingsPage";
 export { default as ShippingLineHelpPage } from "./ShippingLineHelpPage";
diff --git a/apps/edr-freight-web/portal/src/services/api.ts b/apps/edr-freight-web/portal/src/services/api.ts
index 0cec830c9..755361520 100644
--- a/apps/edr-freight-web/portal/src/services/api.ts
+++ b/apps/edr-freight-web/portal/src/services/api.ts
@@ -56,6 +56,7 @@ import {
   UpdateDropdownSettingDto,
 } from "@/types/dropdownSettings";
 import type {
+  AccountInfoResponse,
   ChangeRequestResponse,
   CompanyDocument,
   CompanyInfoResponse,
@@ -188,7 +189,7 @@ export const api = {
   },
 
   companies: {
-    getInfo: endpoint<void, CompanyInfoResponse | null>(
+    getInfo: endpoint<void, AccountInfoResponse | null>(
       "companies",
       "getInfo",
       companiesService.getInfo,
diff --git a/apps/edr-freight-web/portal/src/services/shipping-line-bookings.service.ts b/apps/edr-freight-web/portal/src/services/shipping-line-bookings.service.ts
index e7d4906fc..926298dec 100644
--- a/apps/edr-freight-web/portal/src/services/shipping-line-bookings.service.ts
+++ b/apps/edr-freight-web/portal/src/services/shipping-line-bookings.service.ts
@@ -12,17 +12,94 @@ const BASE = "/api/shipping-line-bookings";
 export const SHIPPING_LINE_BOOKING_DOCUMENTS_CODE =
   "shipping_line_booking_documents";
 
+/** One physical container persisted on a booking line. */
+export interface ShippingLineBookingContainerUnit {
+  id: string;
+  containerNumber?: string | null;
+  sealNumber?: string | null;
+  vgmTons?: number;
+  isHazardous?: boolean;
+  isReefer?: boolean;
+}
+
+/** One persisted container line of a completed booking. */
+export interface ShippingLineBookingContainer {
+  id: string;
+  containerSize?: string | null;
+  quantity: number;
+  vgmPerUnitTons?: number;
+  totalVgmTons?: number;
+  hazardousQuantity?: number;
+  reeferQuantity?: number;
+  wagonsRequired?: number;
+  containerType?: {
+    id: string;
+    label?: string | null;
+    code?: string | null;
+    sizeFt?: number | null;
+  } | null;
+  units?: ShippingLineBookingContainerUnit[];
+}
+
 /**
  * A shipping-line booking as the portal sees it.
  *
  * `hasQueriedDocuments` is computed server-side: a reviewer querying a document
  * leaves the booking on DOCUMENTS_UNDER_REVIEW, so the booking status alone
- * cannot tell the UI that the shipping line has something to fix.
+ * cannot tell the UI that the shipping line has something to fix. The cargo
+ * fields are loaded by the detail endpoint for the detail page's cargo tab.
  */
 export type ShippingLineBooking = Freight.IBooking & {
   hasQueriedDocuments?: boolean;
+  /** Operations' note when the request was returned for changes (detail only). */
+  operationChangeNote?: string | null;
+  bookingContainers?: ShippingLineBookingContainer[];
+  cargoType?: { id: string; cargoTypeName?: string | null } | null;
+  cargoFreeText?: string | null;
+  isHazardous?: boolean;
+  cargoTotalWeightVgm?: number;
+  bulkTotalWeightTons?: number | null;
 };
 
+/** The authoritative quote returned by the price-preview endpoint. */
+export interface ShippingLinePriceQuote {
+  totalAmount: number;
+  currency: string;
+  lineItems: Freight.PricingBreakdownLineItem[];
+  warnings: string[];
+}
+
+/** One wagon the batch engine allocated to the booking. */
+export interface ShippingLineBookingWagon {
+  id: string;
+  status: string;
+  loadType?: string | null;
+  allocatedWeightTons: number;
+  sequenceNo: number | null;
+  wagonNumber: string | null;
+  wagonType: string | null;
+  capacityTons: number;
+  containerNumbers: string[];
+}
+
+/** Operations view: the train the booking rides + its allocated wagons. */
+export interface ShippingLineBookingOperations {
+  train: {
+    id: string;
+    reference?: string | null;
+    trainNumber?: string | null;
+    status: string;
+    direction?: string | null;
+    scheduledDepartureDate: string;
+    scheduledArrivalDate?: string | null;
+    originLabel: string;
+    destinationLabel: string;
+    /** true once operations assigned it; false while it is only requested. */
+    assigned: boolean;
+  } | null;
+  wagons: ShippingLineBookingWagon[];
+}
+
 /** A bookable lane. Its direction is frozen server-side from the yards. */
 export interface ShippingLineRouteOption {
   id: string;
@@ -87,12 +164,25 @@ export interface InitiateShippingLineBookingPayload {
 }
 
 /** One container line of a CONTAINER completion. */
+/** One physical container — number, seal, VGM and its handling switches. */
+export interface CompleteBookingContainerUnit {
+  containerNumber: string;
+  sealNumber?: string;
+  vgmTons: number;
+  isHazardous?: boolean;
+  isReefer?: boolean;
+}
+
 export interface CompleteBookingContainerLine {
-  containerTypeId: string;
+  /** Either the type id or a size string ("20ft" | "40ft") — the server resolves size→type. */
+  containerTypeId?: string;
+  containerSize?: string;
   quantity: number;
   vgmPerUnitTons?: number;
   hazardousQuantity?: number;
   reeferQuantity?: number;
+  /** Per-container rows — when sent, the server derives counts/VGM from them. */
+  units?: CompleteBookingContainerUnit[];
 }
 
 /**
@@ -102,10 +192,17 @@ export interface CompleteBookingContainerLine {
  */
 export interface CompleteShippingLineBookingPayload {
   scheduledDate: string;
+  /**
+   * Which dedicated train the booking rides. Required when more than one of
+   * the line's trains departs on the chosen day; implicit with one departure.
+   */
+  trainScheduleId?: string;
   paymentCurrency?: string;
   containers?: CompleteBookingContainerLine[];
   cargoTypeId?: string;
   cargoWeightTons?: number;
+  bulkHazardousQuantity?: number;
+  bulkReeferQuantity?: number;
   cargoFreeText?: string;
 }
 
@@ -153,6 +250,48 @@ export const shippingLineBookingsService = {
     return data.data ?? data;
   },
 
+  /**
+   * The line's dedicated trains for a shipment day, each with per-wagon-type
+   * free space — the completion form's train picker. Cargo context refines
+   * the availability figures.
+   */
+  trainsForDay: async (
+    id: string,
+    date?: string,
+    cargo?: { containerSizes?: string[]; cargoTypeId?: string; wagons?: number },
+  ): Promise<Freight.ExportTrainOption[]> => {
+    const { data } = await client.get(`${BASE}/${id}/trains`, {
+      params: {
+        ...(date ? { date } : {}),
+        ...(cargo?.containerSizes?.length
+          ? { sizes: cargo.containerSizes.join(",") }
+          : {}),
+        ...(cargo?.cargoTypeId ? { cargoTypeId: cargo.cargoTypeId } : {}),
+        ...(cargo?.wagons ? { wagons: cargo.wagons } : {}),
+      },
+    });
+    return data.data ?? data;
+  },
+
+  /**
+   * Authoritative price quote for the completion payload — the same compute
+   * /complete runs. Server saves the breakdown + rate snapshots on the
+   * booking (refreshed on every re-preview); nothing else is persisted.
+   */
+  pricePreview: async (
+    id: string,
+    payload: CompleteShippingLineBookingPayload,
+  ): Promise<ShippingLinePriceQuote> => {
+    const { data } = await client.post(`${BASE}/${id}/price-preview`, payload);
+    return data.data ?? data;
+  },
+
+  /** The train the booking rides + the wagons allocated to it. */
+  operations: async (id: string): Promise<ShippingLineBookingOperations> => {
+    const { data } = await client.get(`${BASE}/${id}/operations`);
+    return data.data ?? data;
+  },
+
   /**
    * Complete an approved (CLEARANCE_READY) booking: cargo + shipment day.
    * The server prices it off the line's negotiated rates, records the charge

From 6cee9a26769014ccfb941efc6aa2cab6264b6e7f Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Thu, 13 Aug 2026 19:13:18 +0000
Subject: [PATCH 088/174] fix:contract page

---
 .../src/pages/contracts/ContractViewPage.tsx  | 58 ++++++++++++++-----
 .../src/pages/contracts/contract-sign-bar.css | 11 ----
 2 files changed, 42 insertions(+), 27 deletions(-)
 delete mode 100644 apps/edr-freight-web/portal/src/pages/contracts/contract-sign-bar.css

diff --git a/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx b/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
index 92b9ed640..312ecb62b 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
@@ -33,8 +33,6 @@ import { contractsService } from "@/services/contracts.service";
 import { api } from "@/services/api";
 import { extractApiError } from "@/utils/result";
 
-import "./contract-sign-bar.css";
-
 const CONSENT_TEXT = "I have read the entire contract and agree to its terms.";
 
 /**
@@ -227,9 +225,29 @@ export default function ContractViewPage() {
   return (
     <Box
       p={{ base: "md", md: "xl" }}
-      pb={data.canSignCustomer ? { base: 220, sm: 160, md: 120 } : undefined}
+      style={{
+        // Lock the page to the viewport so the contract iframe is the ONLY
+        // scroll container — page scroll + iframe scroll together made the
+        // sign flow slippery. The negative margin cancels AppShell.Main's
+        // global 112px bottom clearance (see AppLayout) for this page only;
+        // the sign bar below already keeps content clear of the chat FAB.
+        height: "calc(100dvh - var(--app-shell-header-offset, 72px))",
+        marginBottom: -112,
+        display: "flex",
+        flexDirection: "column",
+      }}
     >
-      <Box maw={920} mx="auto">
+      <Box
+        maw={920}
+        mx="auto"
+        w="100%"
+        style={{
+          flex: 1,
+          minHeight: 0,
+          display: "flex",
+          flexDirection: "column",
+        }}
+      >
         <Group justify="space-between" wrap="wrap" gap="sm" mb="md">
           <Button
             variant="subtle"
@@ -272,15 +290,24 @@ export default function ContractViewPage() {
           </Alert>
         )}
 
-        <Paper withBorder radius="lg" p={0} style={{ overflow: "hidden" }}>
+        <Paper
+          withBorder
+          radius="lg"
+          p={0}
+          // minHeight keeps the document usable on short/landscape viewports;
+          // the page then overflows and window-scrolls a little, which beats
+          // an unreadably squashed iframe.
+          style={{ overflow: "hidden", flex: 1, minHeight: 220 }}
+        >
           <iframe
             ref={iframeRef}
             srcDoc={data.html}
             title="Contract document"
             onLoad={handleIframeLoad}
             style={{
+              display: "block",
               width: "100%",
-              minHeight: "80vh",
+              height: "100%",
               border: "none",
               background: "white",
             }}
@@ -293,19 +320,18 @@ export default function ContractViewPage() {
           withBorder
           radius="lg"
           p="md"
+          mt="md"
+          w="100%"
+          maw={920}
+          mx="auto"
           style={{
-            position: "fixed",
-            bottom: 0,
-            left: "var(--sign-bar-left, 0px)",
-            right: 0,
-            zIndex: 100,
-            borderTop: "1px solid var(--mantine-color-gray-3)",
+            // Above SupportWidget's Affix (zIndex 300) — the fixed chat FAB
+            // shares this bottom-right corner and would otherwise render on
+            // top of the required agree-and-sign bar.
+            position: "relative",
+            zIndex: 301,
             background: "var(--mantine-color-body)",
-            paddingBottom: "max(env(safe-area-inset-bottom, 0px), 16px)",
-            maxHeight: "80vh",
-            overflowY: "auto",
           }}
-          className="contract-sign-bar"
         >
           <Box maw={920} mx="auto">
             <Group justify="flex-start" align="flex-start" wrap="wrap" gap="sm">
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/contract-sign-bar.css b/apps/edr-freight-web/portal/src/pages/contracts/contract-sign-bar.css
deleted file mode 100644
index 270b91e16..000000000
--- a/apps/edr-freight-web/portal/src/pages/contracts/contract-sign-bar.css
+++ /dev/null
@@ -1,11 +0,0 @@
-/* Keeps the fixed sign bar confined to the content area (right of the
-   navbar) instead of spanning the full viewport and drifting off-center. */
-.contract-sign-bar {
-  --sign-bar-left: 0px;
-}
-
-@media (min-width: 48em) {
-  .contract-sign-bar {
-    --sign-bar-left: 260px;
-  }
-}

From 376c23a0adaa21ba17169873bf5b9bf1380811c8 Mon Sep 17 00:00:00 2001
From: Roba Boru <robab@ethiopianairines.com>
Date: Thu, 13 Aug 2026 22:47:22 +0300
Subject: [PATCH 089/174] Updated financial report and sms outside of Ethiopia

---
 .../modules/payments/payments.controller.ts   |   9 +-
 .../src/modules/payments/payments.service.ts  |  13 +-
 .../src/modules/reports/reports.controller.ts |  12 +-
 .../src/modules/reports/reports.service.ts    | 104 +++---
 .../backoffice/src/app/dashboard/page.tsx     |   2 +-
 .../backoffice/src/app/payments/page.tsx      |  66 +++-
 .../src/app/reports/finance/page.tsx          | 327 ++++++++++--------
 .../backoffice/src/lib/api/finance.ts         |  16 +-
 .../src/lib/export/finance-workbook.ts        | 135 +++++---
 .../src/app/booking/passengers/page.tsx       | 110 +++---
 .../portal/src/app/booking/search/page.tsx    |  11 +-
 .../portal/src/components/PackagesSection.tsx |  12 +-
 12 files changed, 509 insertions(+), 308 deletions(-)

diff --git a/apps/edr-passenger-api/src/modules/payments/payments.controller.ts b/apps/edr-passenger-api/src/modules/payments/payments.controller.ts
index 9c1bfa65d..158eacfc7 100644
--- a/apps/edr-passenger-api/src/modules/payments/payments.controller.ts
+++ b/apps/edr-passenger-api/src/modules/payments/payments.controller.ts
@@ -85,14 +85,20 @@ export class PaymentsController {
   @ApiBearerAuth("IAM-auth")
   @ApiOperation({ summary: "Get all payments with filters (staff/admin only)" })
   @ApiQuery({ name: "search", required: false })
-  @ApiQuery({ name: "status", required: false })
+  @ApiQuery({ name: "status", required: false, description: "PaymentIntentStatus value, e.g. SUCCEEDED" })
   @ApiQuery({ name: "method", required: false })
+  @ApiQuery({
+    name: "bookingStatus",
+    required: false,
+    description: "Comma-separated Booking.status values, e.g. CONFIRMED,BOARDED — restricts to payments backing bookings in those states.",
+  })
   @ApiQuery({ name: "page", required: false })
   @ApiQuery({ name: "pageSize", required: false })
   async getAll(
     @Query("search") search?: string,
     @Query("status") status?: string,
     @Query("method") method?: string,
+    @Query("bookingStatus") bookingStatus?: string,
     @Query("page") page?: string,
     @Query("pageSize") pageSize?: string,
   ) {
@@ -100,6 +106,7 @@ export class PaymentsController {
       search,
       status,
       method,
+      bookingStatus,
       page: page ? parseInt(page) : 1,
       pageSize: pageSize ? parseInt(pageSize) : 10,
     });
diff --git a/apps/edr-passenger-api/src/modules/payments/payments.service.ts b/apps/edr-passenger-api/src/modules/payments/payments.service.ts
index 5cd483830..f7c27a2e9 100644
--- a/apps/edr-passenger-api/src/modules/payments/payments.service.ts
+++ b/apps/edr-passenger-api/src/modules/payments/payments.service.ts
@@ -99,10 +99,13 @@ export class PaymentsService {
     search?: string;
     status?: string;
     method?: string;
+    /** Comma-separated Booking.status values, e.g. "CONFIRMED,BOARDED" — lets a caller ask
+     * for exactly the payments that back confirmed revenue, not every payment attempt. */
+    bookingStatus?: string;
     page?: number;
     pageSize?: number;
   }) {
-    const { search, status, method, page = 1, pageSize = 10 } = filters;
+    const { search, status, method, bookingStatus, page = 1, pageSize = 10 } = filters;
     const skip = (page - 1) * pageSize;
 
     const where: any = {};
@@ -118,6 +121,12 @@ export class PaymentsService {
     if (method) {
       where.method = method;
     }
+    if (bookingStatus) {
+      const statuses = bookingStatus.split(",").map((s) => s.trim()).filter(Boolean);
+      if (statuses.length > 0) {
+        where.booking = { status: { in: statuses } };
+      }
+    }
 
     const [items, total] = await Promise.all([
       this.prisma.paymentIntent.findMany({
@@ -133,6 +142,7 @@ export class PaymentsService {
               childCount: true,
               totalMinor: true,
               currency: true,
+              status: true,
               priceTier: { select: { priceMinor: true } },
             },
           },
@@ -172,6 +182,7 @@ export class PaymentsService {
             bookingRef: b?.bookingRef,
             totalMinor: b?.totalMinor,
             currency: b?.currency,
+            status: b?.status,
           },
           amountMinor,
           currency: item.currency,
diff --git a/apps/edr-passenger-api/src/modules/reports/reports.controller.ts b/apps/edr-passenger-api/src/modules/reports/reports.controller.ts
index 2876b2294..6cf12a9f6 100644
--- a/apps/edr-passenger-api/src/modules/reports/reports.controller.ts
+++ b/apps/edr-passenger-api/src/modules/reports/reports.controller.ts
@@ -122,12 +122,16 @@ export class ReportsController {
 
   @Get("finance")
   @ApiOperation({
-    summary: "Finance summary — revenue by period, origin/destination segment, and payment method",
+    summary: "Finance summary — revenue by period, origin/destination segment, payment method, and currency",
     description:
       "Revenue collected in the window (PaymentIntent.paidAt), grouped by day/week/month, origin → " +
-      "destination station pair, and payment method. Filter by originStationId and/or destinationStationId " +
-      "independently to query any station-pair segment (A→B, A→D, B→C), not just a whole predefined route. " +
-      "Returns per-bucket rows plus roll-ups by period, segment, and method for charting.",
+      "destination station pair, payment method, and currency. Amounts are never converted to ETB — a " +
+      "Waafi payment is reported in whatever currency Waafi actually charged, and with no method filter " +
+      "every currency present is listed separately rather than summed. Filter by originStationId and/or " +
+      "destinationStationId independently to query any station-pair segment (A→B, A→D, B→C), not just a " +
+      "whole predefined route. Only counts CONFIRMED/BOARDED bookings with a SUCCEEDED payment — the same " +
+      "revenue definition as the dashboard and /payments confirmed-revenue filter. Returns per-bucket rows " +
+      "plus roll-ups by period, segment, and method for charting.",
   })
   getFinanceSummary(@Query() query: FinanceSummaryQueryDto) {
     return this.service.getFinanceSummary(query);
diff --git a/apps/edr-passenger-api/src/modules/reports/reports.service.ts b/apps/edr-passenger-api/src/modules/reports/reports.service.ts
index bfafe1921..d727014ee 100644
--- a/apps/edr-passenger-api/src/modules/reports/reports.service.ts
+++ b/apps/edr-passenger-api/src/modules/reports/reports.service.ts
@@ -152,8 +152,17 @@ export interface FinanceBucket {
   destinationStationId: string;
   segmentLabel: string;
   method: string;
+  currency: string;
+  bookingCount: number;
+  revenueMinor: number;
+}
+
+export interface FinanceRollupRow {
+  key: string;
+  label: string;
+  currency: string;
+  revenueMinor: number;
   bookingCount: number;
-  revenueEtbMinor: number;
 }
 
 @Injectable()
@@ -1724,8 +1733,20 @@ export class ReportsService {
 
   /**
    * Revenue collected in the window, grouped by reporting period (day/week/month), origin →
-   * destination station pair, and payment method — the shape finance reconciles against
-   * provider settlement statements.
+   * destination station pair, payment method, and currency — the shape finance reconciles
+   * against provider settlement statements.
+   *
+   * Amounts are never converted to ETB. A Waafi payment settles in whatever currency Waafi
+   * actually charged (DJF/USD), not an exchange-rate estimate of its ETB equivalent — so
+   * filtering to one method shows exactly what that method collected, in its own currency,
+   * and leaving every method selected lists each currency's total separately rather than
+   * summing unlike currencies into one converted figure.
+   *
+   * The "actual" amount/currency is `displayTotalMinor`/`displayCurrency` when set, falling
+   * back to `totalMinor`/`currency` — the same resolution `getPaymentDiscrepancyReport` and
+   * `getPaymentsReport` use, because `Booking.currency` is often just the internal ETB
+   * charge basis (many booking-creation paths hardcode it to ETB); the currency the
+   * passenger was actually shown and charged in lives in the display fields.
    *
    * Grouped by the booking's own origin/destination, not the parent Route — a route like
    * "Sebeta - Dire Dawa" has intermediate stops, and a passenger may have booked any
@@ -1734,29 +1755,26 @@ export class ReportsService {
    *
    * Bucketed on `PaymentIntent.paidAt` (cash actually received), not `Booking.createdAt`,
    * so a booking made in one period but paid in another lands in the period it was paid.
+   *
+   * Same revenue definition as `getBackofficeStats` and the `/payments` "confirmed revenue"
+   * filter: `Booking.status` must still be CONFIRMED/BOARDED (a booking that was paid and
+   * later cancelled is not revenue) and `PaymentIntent.status` must be SUCCEEDED, not just
+   * carry a stale `paidAt` from before a cancellation.
    */
   async getFinanceSummary(query: FinanceSummaryQueryDto) {
     const dateFrom = new Date(query.dateFrom + "T00:00:00.000Z");
     const dateTo = new Date(query.dateTo + "T23:59:59.999Z");
     const granularity = query.granularity ?? FinanceGranularity.DAILY;
 
-    const rateRows = await this.prisma.currencyExchangeRate.findMany({
-      where: { toCurrency: "ETB" as any },
-      orderBy: { effectiveDate: "desc" },
-    });
-    const rateToEtb = new Map<string, number>();
-    for (const r of rateRows) {
-      if (!rateToEtb.has(r.fromCurrency)) rateToEtb.set(r.fromCurrency, Number(r.rate));
-    }
-    const toEtbMinor = (minor: number, currency: string): number => {
-      if (currency === "ETB") return minor;
-      const rate = rateToEtb.get(currency);
-      return rate ? Math.round(minor * rate) : minor;
-    };
-
     const bookings = await this.prisma.booking.findMany({
       where: {
+        // Same revenue definition as the dashboard's backoffice-stats and the /payments
+        // "confirmed revenue" filter: the booking must still be CONFIRMED/BOARDED (a booking
+        // that was paid and later cancelled is not revenue) and the payment itself must have
+        // actually succeeded, not just carry a stale paidAt.
+        status: { in: ["CONFIRMED", "BOARDED"] },
         paymentIntent: {
+          status: "SUCCEEDED",
           paidAt: { gte: dateFrom, lte: dateTo },
           ...(query.method ? { method: query.method } : {}),
         },
@@ -1766,6 +1784,8 @@ export class ReportsService {
       select: {
         totalMinor: true,
         currency: true,
+        displayTotalMinor: true,
+        displayCurrency: true,
         originStationId: true,
         destinationStationId: true,
         schedule: { select: { originStationId: true, destinationStationId: true } },
@@ -1795,11 +1815,12 @@ export class ReportsService {
       destinationStationId: string,
       segmentLabel: string,
       method: string,
+      currency: string,
     ): FinanceBucket => {
-      const key = `${period}|${originStationId}|${destinationStationId}|${method}`;
+      const key = `${period}|${originStationId}|${destinationStationId}|${method}|${currency}`;
       let bucket = buckets.get(key);
       if (!bucket) {
-        bucket = { period, originStationId, destinationStationId, segmentLabel, method, bookingCount: 0, revenueEtbMinor: 0 };
+        bucket = { period, originStationId, destinationStationId, segmentLabel, method, currency, bookingCount: 0, revenueMinor: 0 };
         buckets.set(key, bucket);
       }
       return bucket;
@@ -1811,65 +1832,62 @@ export class ReportsService {
       const originStationId = b.originStationId ?? b.schedule.originStationId ?? "UNKNOWN";
       const destinationStationId = b.destinationStationId ?? b.schedule.destinationStationId ?? "UNKNOWN";
       const segmentLabel = `${stationName.get(originStationId) ?? "Unknown"} → ${stationName.get(destinationStationId) ?? "Unknown"}`;
-      const bucket = bucketFor(period, originStationId, destinationStationId, segmentLabel, pi.method);
+      const currency = (b.displayCurrency as string | null) ?? b.currency;
+      const amountMinor = b.displayTotalMinor ?? b.totalMinor;
+      const bucket = bucketFor(period, originStationId, destinationStationId, segmentLabel, pi.method, currency);
       bucket.bookingCount += 1;
-      bucket.revenueEtbMinor += toEtbMinor(b.totalMinor, b.currency);
+      bucket.revenueMinor += amountMinor;
     }
 
     const rows = [...buckets.values()].sort((a, b) =>
       a.period === b.period
-        ? a.segmentLabel.localeCompare(b.segmentLabel) || a.method.localeCompare(b.method)
+        ? a.segmentLabel.localeCompare(b.segmentLabel) || a.method.localeCompare(b.method) || a.currency.localeCompare(b.currency)
         : a.period.localeCompare(b.period),
     );
 
-    const totals = rows.reduce(
-      (acc, r) => {
-        acc.bookingCount += r.bookingCount;
-        acc.revenueEtbMinor += r.revenueEtbMinor;
-        return acc;
-      },
-      { bookingCount: 0, revenueEtbMinor: 0 },
-    );
-
-    const rollUp = (keyOf: (r: FinanceBucket) => string, labelOf: (r: FinanceBucket) => string) => {
-      const map = new Map<string, { key: string; label: string; revenueEtbMinor: number; bookingCount: number }>();
+    const rollUp = (keyOf: (r: FinanceBucket) => string, labelOf: (r: FinanceBucket) => string): FinanceRollupRow[] => {
+      const map = new Map<string, FinanceRollupRow>();
       for (const r of rows) {
         const key = keyOf(r);
         let entry = map.get(key);
         if (!entry) {
-          entry = { key, label: labelOf(r), revenueEtbMinor: 0, bookingCount: 0 };
+          entry = { key, label: labelOf(r), currency: r.currency, revenueMinor: 0, bookingCount: 0 };
           map.set(key, entry);
         }
-        entry.revenueEtbMinor += r.revenueEtbMinor;
+        entry.revenueMinor += r.revenueMinor;
         entry.bookingCount += r.bookingCount;
       }
-      return [...map.values()].sort((a, b) => b.revenueEtbMinor - a.revenueEtbMinor);
+      return [...map.values()].sort((a, b) => b.revenueMinor - a.revenueMinor);
     };
 
+    // Currency is folded into every rollup key so amounts in different currencies are never
+    // summed together — see class-level note on why this endpoint doesn't convert to ETB.
+    const totals = rollUp((r) => r.currency, (r) => r.currency);
+
     return {
       granularity,
       dateFrom: query.dateFrom,
       dateTo: query.dateTo,
-      currency: "ETB",
       totals,
-      byPeriod: rollUp((r) => r.period, (r) => r.period),
-      bySegment: rollUp((r) => `${r.originStationId}|${r.destinationStationId}`, (r) => r.segmentLabel),
-      byMethod: rollUp((r) => r.method, (r) => r.method),
+      byPeriod: rollUp((r) => `${r.period}|${r.currency}`, (r) => r.period),
+      bySegment: rollUp((r) => `${r.originStationId}|${r.destinationStationId}|${r.currency}`, (r) => r.segmentLabel),
+      byMethod: rollUp((r) => `${r.method}|${r.currency}`, (r) => r.method),
       rows,
     };
   }
 
-  /** CSV of the finance summary, one row per period + origin/destination segment + payment method. */
+  /** CSV of the finance summary, one row per period + origin/destination segment + payment method + currency. */
   async exportFinanceSummaryCsv(query: FinanceSummaryQueryDto): Promise<string> {
     const report = await this.getFinanceSummary(query);
 
-    const headers = ["Period", "Origin → Destination", "Payment Method", "Bookings", "Revenue (ETB)"];
+    const headers = ["Period", "Origin → Destination", "Payment Method", "Currency", "Bookings", "Revenue"];
     const rows = report.rows.map((r) => [
       r.period,
       r.segmentLabel,
       r.method,
+      r.currency,
       r.bookingCount,
-      (r.revenueEtbMinor / 100).toFixed(2),
+      (r.revenueMinor / 100).toFixed(2),
     ]);
 
     return [headers, ...rows].map((row) => row.map(toCsvCell).join(",")).join("\n");
diff --git a/apps/edr-passenger-web/backoffice/src/app/dashboard/page.tsx b/apps/edr-passenger-web/backoffice/src/app/dashboard/page.tsx
index 7eede0089..571d63c9d 100644
--- a/apps/edr-passenger-web/backoffice/src/app/dashboard/page.tsx
+++ b/apps/edr-passenger-web/backoffice/src/app/dashboard/page.tsx
@@ -312,7 +312,7 @@ function DashboardPageContent() {
                 </div>
               </div>
               <Link
-                href="/payments"
+                href="/payments?status=SUCCEEDED&bookingStatus=CONFIRMED,BOARDED"
                 className="flex items-center gap-1 text-xs text-primary hover:underline mt-auto pt-1"
               >
                 View payments <ArrowRight className="h-3 w-3" />
diff --git a/apps/edr-passenger-web/backoffice/src/app/payments/page.tsx b/apps/edr-passenger-web/backoffice/src/app/payments/page.tsx
index 9cbfdd4e3..e59a867ed 100644
--- a/apps/edr-passenger-web/backoffice/src/app/payments/page.tsx
+++ b/apps/edr-passenger-web/backoffice/src/app/payments/page.tsx
@@ -1,8 +1,9 @@
 'use client';
 
-import { useState } from 'react';
+import { Suspense, useState } from 'react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { Download, Eye, Trash2, AlertCircle, Send, CheckCircle, XCircle, RotateCcw } from 'lucide-react';
+import { useSearchParams } from 'next/navigation';
+import { Download, Eye, Trash2, AlertCircle, Send, CheckCircle, XCircle, RotateCcw, X } from 'lucide-react';
 import DataTable from '@/components/ui/DataTable';
 import Badge from '@/components/ui/Badge';
 import ActionButton from '@/components/ui/ActionButton';
@@ -22,6 +23,18 @@ import {
 
 type PageTab = 'payments' | 'supplementary';
 
+// PaymentIntentStatus values, as actually defined on the backend — the dropdown used to
+// offer PENDING/COMPLETED/FAILED, none of which are real values, so selecting them just
+// returned nothing.
+const PAYMENT_STATUS_OPTIONS = [
+  { value: 'SUCCEEDED', label: 'Succeeded' },
+  { value: 'PROCESSING', label: 'Processing' },
+  { value: 'REQUIRES_ACTION', label: 'Requires Action' },
+  { value: 'FAILED', label: 'Failed' },
+  { value: 'CANCELLED', label: 'Cancelled' },
+  { value: 'REFUNDED', label: 'Refunded' },
+];
+
 const STATUS_COLORS: Record<string, string> = {
   PENDING: 'warning',
   PAID: 'success',
@@ -42,9 +55,19 @@ const SectionHeader = ({ title }: { title: string }) => (
   </h3>
 );
 
-export default function PaymentsPage() {
+function PaymentsPageContent() {
+  const searchParams = useSearchParams();
+  // A link can pre-filter this page — the dashboard's Revenue card links here with
+  // status=SUCCEEDED&bookingStatus=CONFIRMED,BOARDED so "view payments" shows exactly the
+  // payments that make up that revenue figure, not every payment attempt.
+  const initialBookingStatus = searchParams.get('bookingStatus') ?? '';
   const [pageTab, setPageTab] = useState<PageTab>('payments');
-  const [filters, setFilters] = useState({ search: '', status: '', method: '' });
+  const [filters, setFilters] = useState({
+    search: '',
+    status: searchParams.get('status') ?? '',
+    method: '',
+    bookingStatus: initialBookingStatus,
+  });
   const [selectedPayment, setSelectedPayment] = useState<any>(null);
   const [deleteConfirmOpen, setDeleteConfirmOpen] = useState(false);
   const [paymentToDelete, setPaymentToDelete] = useState<any>(null);
@@ -108,6 +131,7 @@ export default function PaymentsPage() {
       search: filters.search || undefined,
       status: filters.status || undefined,
       method: filters.method || undefined,
+      bookingStatus: filters.bookingStatus || undefined,
     }),
   });
 
@@ -168,7 +192,8 @@ export default function PaymentsPage() {
     { key: 'booking', label: 'Booking', render: (payment: any) => payment.booking?.bookingRef || 'N/A' },
     { key: 'amount', label: 'Amount', render: (payment: any) => formatCurrency(payment.booking?.totalMinor ?? payment.amountMinor, 'ETB') },
     { key: 'method', label: 'Method', render: (payment: any) => <Badge>{payment.method}</Badge> },
-    { key: 'status', label: 'Status', render: (payment: any) => <Badge variant="status" status={payment.status}>{payment.status}</Badge> },
+    { key: 'status', label: 'Payment Status', render: (payment: any) => <Badge variant="status" status={payment.status}>{payment.status}</Badge> },
+    { key: 'bookingStatus', label: 'Booking Status', render: (payment: any) => payment.booking?.status ? <Badge variant="status" status={payment.booking.status}>{payment.booking.status}</Badge> : '—' },
     { key: 'createdAt', label: 'Created', render: (payment: any) => formatDateTime(payment.createdAt) },
   ];
 
@@ -286,18 +311,33 @@ export default function PaymentsPage() {
         {successMessage && (
           <div className="mb-4 rounded-lg bg-green-50 dark:bg-green-900/20 p-4 text-sm text-green-800 dark:text-green-200">✓ {successMessage}</div>
         )}
+        {filters.bookingStatus && (
+          <div className="mb-4 flex items-center justify-between rounded-lg bg-emerald-50 dark:bg-emerald-900/20 p-3 text-sm text-emerald-800 dark:text-emerald-200">
+            <span>
+              Showing payments backing <strong>{filters.bookingStatus.split(',').join(' / ')}</strong> bookings only —
+              the same confirmed revenue the dashboard total is built from.
+            </span>
+            <button
+              type="button"
+              onClick={() => setFilters({ ...filters, status: '', bookingStatus: '' })}
+              className="flex items-center gap-1 font-medium hover:underline shrink-0 ml-3"
+            >
+              <X className="w-3.5 h-3.5" /> Clear
+            </button>
+          </div>
+        )}
         <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
           <div>
             <label className="label">Search</label>
             <input type="text" placeholder="Search..." className="input" value={filters.search} onChange={(e) => setFilters({ ...filters, search: e.target.value })} />
           </div>
           <div>
-            <label className="label">Status</label>
+            <label className="label">Payment Status</label>
             <select className="input" value={filters.status} onChange={(e) => setFilters({ ...filters, status: e.target.value })}>
               <option value="">All Status</option>
-              <option value="PENDING">Pending</option>
-              <option value="COMPLETED">Completed</option>
-              <option value="FAILED">Failed</option>
+              {PAYMENT_STATUS_OPTIONS.map((opt) => (
+                <option key={opt.value} value={opt.value}>{opt.label}</option>
+              ))}
             </select>
           </div>
           <div>
@@ -478,3 +518,11 @@ export default function PaymentsPage() {
     </div>
   );
 }
+
+export default function PaymentsPage() {
+  return (
+    <Suspense fallback={null}>
+      <PaymentsPageContent />
+    </Suspense>
+  );
+}
diff --git a/apps/edr-passenger-web/backoffice/src/app/reports/finance/page.tsx b/apps/edr-passenger-web/backoffice/src/app/reports/finance/page.tsx
index 8e3e2a23b..b83e96ca7 100644
--- a/apps/edr-passenger-web/backoffice/src/app/reports/finance/page.tsx
+++ b/apps/edr-passenger-web/backoffice/src/app/reports/finance/page.tsx
@@ -2,7 +2,7 @@
 
 import { useMemo, useRef, useState } from 'react';
 import { useQuery } from '@tanstack/react-query';
-import { Banknote, BookOpen, FileSpreadsheet, Receipt } from 'lucide-react';
+import { Banknote, BookOpen, FileSpreadsheet } from 'lucide-react';
 import {
   Bar, BarChart, CartesianGrid, Line, LineChart,
   ResponsiveContainer, Tooltip as RechartsTooltip, XAxis, YAxis,
@@ -114,9 +114,12 @@ export default function FinanceReportPage() {
   const [method, setMethod] = useState('');
   const [exporting, setExporting] = useState(false);
 
-  const trendCardRef = useRef<HTMLDivElement>(null);
-  const segmentCardRef = useRef<HTMLDivElement>(null);
-  const methodCardRef = useRef<HTMLDivElement>(null);
+  // Chart cards are captured for the Excel export. There's one Trend/Segment/Method set per
+  // currency (see currencySections below), so refs are keyed by `${currency}-${chart}`.
+  const chartRefs = useRef<Record<string, HTMLDivElement | null>>({});
+  const setChartRef = (key: string) => (el: HTMLDivElement | null) => {
+    chartRefs.current[key] = el;
+  };
 
   const { dateFrom, dateTo } = useMemo(() => {
     const end = new Date();
@@ -192,11 +195,17 @@ export default function FinanceReportPage() {
     if (!data) return;
     setExporting(true);
     try {
-      const [trend, segment, method_] = await Promise.all([
-        captureCard(trendCardRef.current),
-        captureCard(segmentCardRef.current),
-        captureCard(methodCardRef.current),
-      ]);
+      const imagesByCurrency: Record<string, { trend?: ChartImage; segment?: ChartImage; method?: ChartImage }> = {};
+      await Promise.all(
+        currencySections.map(async (section) => {
+          const [trend, segment, methodImg] = await Promise.all([
+            captureCard(chartRefs.current[`${section.currency}-trend`]),
+            captureCard(chartRefs.current[`${section.currency}-segment`]),
+            captureCard(chartRefs.current[`${section.currency}-method`]),
+          ]);
+          imagesByCurrency[section.currency] = { trend, segment, method: methodImg };
+        }),
+      );
 
       const stationLabel = (id: string) => stations.find((s) => s.id === id)?.name ?? 'Any';
 
@@ -212,7 +221,7 @@ export default function FinanceReportPage() {
         },
         methodLabel,
         periodLabel,
-        images: { trend, segment, method: method_ },
+        imagesByCurrency,
       });
 
       const url = URL.createObjectURL(blob);
@@ -226,43 +235,53 @@ export default function FinanceReportPage() {
     }
   };
 
-  const trendData = useMemo(
-    () =>
-      (data?.byPeriod ?? [])
+  const totals = useMemo(
+    () => (data?.totals ?? []).slice().sort((a, b) => b.revenueMinor - a.revenueMinor),
+    [data],
+  );
+  const totalBookings = totals.reduce((sum, t) => sum + t.bookingCount, 0);
+  const hasData = totalBookings > 0;
+
+  // Money is never comparable across currencies, so rather than scoping every chart to
+  // whichever currency happens to be biggest overall (which would silently drop a
+  // currency-specific method like Waafi/DJF from the payment-method breakdown whenever ETB
+  // dominates the total), each currency present gets its own full Trend/Segment/Method set.
+  const currencySections = useMemo(() => {
+    if (!data) return [];
+    return totals.map((t) => {
+      const trendData = data.byPeriod
+        .filter((p) => p.currency === t.currency)
         .slice()
         .sort((a, b) => a.key.localeCompare(b.key))
-        .map((p) => ({
-          label: periodLabel(p.key, data!.granularity),
-          revenue: p.revenueEtbMinor / 100,
-        })),
-    [data],
-  );
+        .map((p) => ({ label: periodLabel(p.label, data.granularity), revenue: p.revenueMinor / 100 }));
 
-  const segmentData = useMemo(
-    () =>
-      (data?.bySegment ?? [])
+      const segmentData = data.bySegment
+        .filter((r) => r.currency === t.currency)
         .slice()
-        .sort((a, b) => b.revenueEtbMinor - a.revenueEtbMinor)
-        .map((r) => ({ label: r.label, revenue: r.revenueEtbMinor })),
-    [data],
-  );
+        .sort((a, b) => b.revenueMinor - a.revenueMinor)
+        .map((r) => ({ label: r.label, revenue: r.revenueMinor }));
 
-  const methodBreakdown = useMemo(() => {
-    const rowsByMethod = data?.byMethod ?? [];
-    const total = rowsByMethod.reduce((sum, r) => sum + r.revenueEtbMinor, 0);
-    return rowsByMethod
-      .slice()
-      .sort((a, b) => PAYMENT_METHOD_ORDER.indexOf(a.key as any) - PAYMENT_METHOD_ORDER.indexOf(b.key as any))
-      .map((r) => ({
-        ...r,
-        color: categoricalColor(palette, PAYMENT_METHOD_ORDER.indexOf(r.key as any)),
-        sharePercent: total > 0 ? (r.revenueEtbMinor / total) * 100 : 0,
-      }));
-  }, [data, palette]);
+      const methodRows = data.byMethod.filter((r) => r.currency === t.currency);
+      const methodTotal = methodRows.reduce((sum, r) => sum + r.revenueMinor, 0);
+      const methodBreakdown = methodRows
+        .slice()
+        .sort((a, b) => PAYMENT_METHOD_ORDER.indexOf(a.label as any) - PAYMENT_METHOD_ORDER.indexOf(b.label as any))
+        .map((r) => ({
+          ...r,
+          color: categoricalColor(palette, PAYMENT_METHOD_ORDER.indexOf(r.label as any)),
+          sharePercent: methodTotal > 0 ? (r.revenueMinor / methodTotal) * 100 : 0,
+        }));
 
-  const totals = data?.totals;
-  const hasData = (totals?.bookingCount ?? 0) > 0;
-  const avgPerBookingMinor = hasData ? Math.round(totals!.revenueEtbMinor / totals!.bookingCount) : 0;
+      return {
+        currency: t.currency,
+        revenueMinor: t.revenueMinor,
+        bookingCount: t.bookingCount,
+        trendData,
+        segmentData,
+        methodBreakdown,
+      };
+    });
+  }, [data, totals, palette]);
 
   return (
     <div className="space-y-6">
@@ -357,18 +376,25 @@ export default function FinanceReportPage() {
         </div>
       ) : (
         <div className={isFetching ? 'opacity-60 transition-opacity space-y-6' : 'space-y-6'}>
-          {/* KPI tiles */}
-          <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
-            <div className="card flex flex-col gap-1">
-              <div className="flex items-center justify-between">
-                <p className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">Revenue</p>
+          {/* Revenue by currency — never summed across currencies, so a Waafi/DJF total and an
+              ETB total each get their own row instead of one converted figure. */}
+          <div className="grid grid-cols-1 lg:grid-cols-3 gap-4">
+            <div className="card lg:col-span-2 flex flex-col gap-2">
+              <div className="flex items-center justify-between mb-1">
+                <p className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">Revenue by Currency</p>
                 <div className="rounded-lg bg-emerald-100 dark:bg-emerald-900/30 p-1.5">
                   <Banknote className="h-4 w-4 text-emerald-600 dark:text-emerald-400" />
                 </div>
               </div>
-              <p className="text-2xl font-bold text-emerald-600 dark:text-emerald-400 tabular-nums mt-1">
-                {formatCurrency(totals!.revenueEtbMinor, 'ETB')}
-              </p>
+              {totals.map((t) => (
+                <div key={t.currency} className="flex items-center justify-between rounded-md bg-muted/20 px-3 py-2">
+                  <span className="text-sm font-medium">{t.currency}</span>
+                  <span className="text-right">
+                    <span className="text-sm font-semibold tabular-nums">{formatCurrency(t.revenueMinor, t.currency)}</span>
+                    <span className="ml-2 text-xs text-muted-foreground tabular-nums">{t.bookingCount.toLocaleString()} bookings</span>
+                  </span>
+                </div>
+              ))}
             </div>
             <div className="card flex flex-col gap-1">
               <div className="flex items-center justify-between">
@@ -377,104 +403,116 @@ export default function FinanceReportPage() {
                   <BookOpen className="h-4 w-4 text-blue-600 dark:text-blue-400" />
                 </div>
               </div>
-              <p className="text-2xl font-bold tabular-nums mt-1">{totals!.bookingCount.toLocaleString()}</p>
+              <p className="text-2xl font-bold tabular-nums mt-1">{totalBookings.toLocaleString()}</p>
+              <p className="text-xs text-muted-foreground mt-auto pt-2 border-t border-border">
+                Across {totals.length} currenc{totals.length === 1 ? 'y' : 'ies'}
+              </p>
             </div>
-            <div className="card flex flex-col gap-1">
-              <div className="flex items-center justify-between">
-                <p className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">Avg. per Booking</p>
-                <div className="rounded-lg bg-amber-100 dark:bg-amber-900/30 p-1.5">
-                  <Receipt className="h-4 w-4 text-amber-600 dark:text-amber-400" />
+          </div>
+
+          {/* One full Trend + Segment + Method set per currency — never scoped to a single
+              "dominant" currency, so a currency-specific method like Waafi/DJF always shows
+              its own numbers instead of being dropped in favor of whichever currency is
+              biggest overall. */}
+          {currencySections.map((section) => (
+            <div key={section.currency} className="space-y-6">
+              <div className="flex items-center gap-3">
+                <h2 className="text-lg font-semibold text-foreground">{section.currency}</h2>
+                <span className="text-xs text-muted-foreground">
+                  {formatCurrency(section.revenueMinor, section.currency)} · {section.bookingCount.toLocaleString()} bookings
+                </span>
+              </div>
+
+              <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+                <div className="card" ref={setChartRef(`${section.currency}-trend`)}>
+                  <h3 className="text-base font-semibold mb-4">
+                    Revenue Trend <span className="text-xs font-normal text-muted-foreground">({section.currency}, {granularity})</span>
+                  </h3>
+                  {section.trendData.length > 0 ? (
+                    <ResponsiveContainer width="100%" height={260}>
+                      <LineChart data={section.trendData}>
+                        <CartesianGrid strokeDasharray="3 3" stroke={palette.grid} />
+                        <XAxis dataKey="label" tick={{ fontSize: 11, fill: palette.textMuted }} />
+                        <YAxis tick={{ fontSize: 11, fill: palette.textMuted }} />
+                        <RechartsTooltip formatter={(value: number) => `${section.currency} ${Math.round(value).toLocaleString()}`} />
+                        <Line type="monotone" dataKey="revenue" name="Revenue" stroke={palette.sequential} dot={{ r: 3 }} strokeWidth={2} />
+                      </LineChart>
+                    </ResponsiveContainer>
+                  ) : (
+                    <div className="h-[260px] flex items-center justify-center text-muted-foreground text-sm">No data for selected range</div>
+                  )}
+                </div>
+
+                <div className="card" ref={setChartRef(`${section.currency}-segment`)}>
+                  <h3 className="text-base font-semibold mb-4">
+                    Revenue by Segment <span className="text-xs font-normal text-muted-foreground">({section.currency})</span>
+                  </h3>
+                  {section.segmentData.length > 0 ? (
+                    <ResponsiveContainer width="100%" height={260}>
+                      <BarChart data={section.segmentData}>
+                        <CartesianGrid strokeDasharray="3 3" stroke={palette.grid} />
+                        <XAxis dataKey="label" tick={{ fontSize: 11, fill: palette.textMuted }} />
+                        <YAxis tick={{ fontSize: 11, fill: palette.textMuted }} />
+                        <RechartsTooltip formatter={(value: number) => `${section.currency} ${Math.round(value).toLocaleString()}`} />
+                        <Bar dataKey="revenue" fill={palette.sequential} radius={[3, 3, 0, 0]} />
+                      </BarChart>
+                    </ResponsiveContainer>
+                  ) : (
+                    <div className="h-[260px] flex items-center justify-center text-muted-foreground text-sm">No data for selected range</div>
+                  )}
                 </div>
               </div>
-              <p className="text-2xl font-bold tabular-nums mt-1">{formatCurrency(avgPerBookingMinor, 'ETB')}</p>
-            </div>
-          </div>
 
-          {/* Trend + route charts */}
-          <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
-            <div className="card" ref={trendCardRef}>
-              <h3 className="text-base font-semibold mb-4">
-                Revenue Trend <span className="text-xs font-normal text-muted-foreground">(ETB, {granularity})</span>
-              </h3>
-              {trendData.length > 0 ? (
-                <ResponsiveContainer width="100%" height={280}>
-                  <LineChart data={trendData}>
-                    <CartesianGrid strokeDasharray="3 3" stroke={palette.grid} />
-                    <XAxis dataKey="label" tick={{ fontSize: 11, fill: palette.textMuted }} />
-                    <YAxis tick={{ fontSize: 11, fill: palette.textMuted }} />
-                    <RechartsTooltip formatter={(value: number) => `ETB ${Math.round(value).toLocaleString()}`} />
-                    <Line type="monotone" dataKey="revenue" name="Revenue" stroke={palette.sequential} dot={{ r: 3 }} strokeWidth={2} />
-                  </LineChart>
-                </ResponsiveContainer>
-              ) : (
-                <div className="h-[280px] flex items-center justify-center text-muted-foreground text-sm">No data for selected range</div>
-              )}
-            </div>
-
-            <div className="card" ref={segmentCardRef}>
-              <h3 className="text-base font-semibold mb-4">Revenue by Segment</h3>
-              {segmentData.length > 0 ? (
-                <ResponsiveContainer width="100%" height={280}>
-                  <BarChart data={segmentData}>
-                    <CartesianGrid strokeDasharray="3 3" stroke={palette.grid} />
-                    <XAxis dataKey="label" tick={{ fontSize: 11, fill: palette.textMuted }} />
-                    <YAxis tick={{ fontSize: 11, fill: palette.textMuted }} />
-                    <RechartsTooltip formatter={(value: number) => `ETB ${Math.round(value).toLocaleString()}`} />
-                    <Bar dataKey="revenue" fill={palette.sequential} radius={[3, 3, 0, 0]} />
-                  </BarChart>
-                </ResponsiveContainer>
-              ) : (
-                <div className="h-[280px] flex items-center justify-center text-muted-foreground text-sm">No data for selected range</div>
-              )}
-            </div>
-          </div>
-
-          {/* Payment method breakdown — part-to-whole stacked bar + legend table */}
-          <div className="card" ref={methodCardRef}>
-            <h3 className="text-base font-semibold text-foreground">Revenue by Payment Method</h3>
-            <p className="text-xs text-muted-foreground mt-1 mb-4">Share of revenue, in ETB</p>
-            <div
-              className="flex w-full h-7 rounded-md overflow-hidden"
-              role="img"
-              aria-label={`Revenue by payment method: ${methodBreakdown
-                .map((m) => `${methodLabel(m.key)} ${m.sharePercent.toFixed(0)}%`)
-                .join(', ')}`}
-            >
-              {methodBreakdown.map((m, i) => (
+              {/* Payment method breakdown — part-to-whole stacked bar + legend table */}
+              <div className="card" ref={setChartRef(`${section.currency}-method`)}>
+                <h3 className="text-base font-semibold text-foreground">
+                  Revenue by Payment Method <span className="text-xs font-normal text-muted-foreground">({section.currency})</span>
+                </h3>
+                <p className="text-xs text-muted-foreground mt-1 mb-4">Share of {section.currency} revenue by method</p>
                 <div
-                  key={m.key}
-                  className="h-full"
-                  style={{ width: `${m.sharePercent}%`, background: m.color, marginRight: i < methodBreakdown.length - 1 ? 2 : 0 }}
-                  title={`${methodLabel(m.key)} — ${formatCurrency(m.revenueEtbMinor, 'ETB')}`}
-                />
-              ))}
+                  className="flex w-full h-7 rounded-md overflow-hidden"
+                  role="img"
+                  aria-label={`${section.currency} revenue by payment method: ${section.methodBreakdown
+                    .map((m) => `${methodLabel(m.label)} ${m.sharePercent.toFixed(0)}%`)
+                    .join(', ')}`}
+                >
+                  {section.methodBreakdown.map((m, i) => (
+                    <div
+                      key={m.key}
+                      className="h-full"
+                      style={{ width: `${m.sharePercent}%`, background: m.color, marginRight: i < section.methodBreakdown.length - 1 ? 2 : 0 }}
+                      title={`${methodLabel(m.label)} — ${formatCurrency(m.revenueMinor, m.currency)}`}
+                    />
+                  ))}
+                </div>
+                <table className="w-full text-sm mt-4">
+                  <thead>
+                    <tr className="text-xs uppercase tracking-wider text-muted-foreground">
+                      <th className="text-left font-medium py-2">Method</th>
+                      <th className="text-right font-medium py-2">Bookings</th>
+                      <th className="text-right font-medium py-2">Share</th>
+                      <th className="text-right font-medium py-2">Revenue</th>
+                    </tr>
+                  </thead>
+                  <tbody className="divide-y divide-border">
+                    {section.methodBreakdown.map((m) => (
+                      <tr key={m.key}>
+                        <td className="py-2">
+                          <span className="flex items-center gap-2">
+                            <span className="h-2.5 w-2.5 rounded-sm shrink-0" style={{ background: m.color }} aria-hidden="true" />
+                            <span className="text-foreground">{methodLabel(m.label)}</span>
+                          </span>
+                        </td>
+                        <td className="py-2 text-right tabular-nums text-muted-foreground">{m.bookingCount.toLocaleString()}</td>
+                        <td className="py-2 text-right tabular-nums text-muted-foreground">{m.sharePercent.toFixed(1)}%</td>
+                        <td className="py-2 text-right tabular-nums text-foreground font-medium">{formatCurrency(m.revenueMinor, m.currency)}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
             </div>
-            <table className="w-full text-sm mt-4">
-              <thead>
-                <tr className="text-xs uppercase tracking-wider text-muted-foreground">
-                  <th className="text-left font-medium py-2">Method</th>
-                  <th className="text-right font-medium py-2">Bookings</th>
-                  <th className="text-right font-medium py-2">Share</th>
-                  <th className="text-right font-medium py-2">Revenue</th>
-                </tr>
-              </thead>
-              <tbody className="divide-y divide-border">
-                {methodBreakdown.map((m) => (
-                  <tr key={m.key}>
-                    <td className="py-2">
-                      <span className="flex items-center gap-2">
-                        <span className="h-2.5 w-2.5 rounded-sm shrink-0" style={{ background: m.color }} aria-hidden="true" />
-                        <span className="text-foreground">{methodLabel(m.key)}</span>
-                      </span>
-                    </td>
-                    <td className="py-2 text-right tabular-nums text-muted-foreground">{m.bookingCount.toLocaleString()}</td>
-                    <td className="py-2 text-right tabular-nums text-muted-foreground">{m.sharePercent.toFixed(1)}%</td>
-                    <td className="py-2 text-right tabular-nums text-foreground font-medium">{formatCurrency(m.revenueEtbMinor, 'ETB')}</td>
-                  </tr>
-                ))}
-              </tbody>
-            </table>
-          </div>
+          ))}
 
           {/* Detail table */}
           <div className="card p-0">
@@ -487,7 +525,7 @@ export default function FinanceReportPage() {
               <table className="w-full text-sm">
                 <thead className="bg-gray-50 dark:bg-gray-800">
                   <tr>
-                    {['Period', 'Segment', 'Method', 'Bookings', 'Revenue'].map((h) => (
+                    {['Period', 'Segment', 'Method', 'Currency', 'Bookings', 'Revenue'].map((h) => (
                       <th key={h} className="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-400 whitespace-nowrap">
                         {h}
                       </th>
@@ -500,13 +538,14 @@ export default function FinanceReportPage() {
                       <td className="px-4 py-3 whitespace-nowrap text-foreground">{periodLabel(r.period, granularity)}</td>
                       <td className="px-4 py-3 whitespace-nowrap text-muted-foreground">{r.segmentLabel}</td>
                       <td className="px-4 py-3 whitespace-nowrap text-muted-foreground">{methodLabel(r.method)}</td>
+                      <td className="px-4 py-3 whitespace-nowrap text-muted-foreground">{r.currency}</td>
                       <td className="px-4 py-3 tabular-nums whitespace-nowrap">{r.bookingCount.toLocaleString()}</td>
-                      <td className="px-4 py-3 tabular-nums whitespace-nowrap font-medium">{formatCurrency(r.revenueEtbMinor, 'ETB')}</td>
+                      <td className="px-4 py-3 tabular-nums whitespace-nowrap font-medium">{formatCurrency(r.revenueMinor, r.currency)}</td>
                     </tr>
                   ))}
                   {pg.paged.length === 0 && (
                     <tr>
-                      <td colSpan={5} className="py-8 text-center text-sm text-muted-foreground">No rows on this page</td>
+                      <td colSpan={6} className="py-8 text-center text-sm text-muted-foreground">No rows on this page</td>
                     </tr>
                   )}
                 </tbody>
diff --git a/apps/edr-passenger-web/backoffice/src/lib/api/finance.ts b/apps/edr-passenger-web/backoffice/src/lib/api/finance.ts
index d99aaeae2..fa0bc943d 100644
--- a/apps/edr-passenger-web/backoffice/src/lib/api/finance.ts
+++ b/apps/edr-passenger-web/backoffice/src/lib/api/finance.ts
@@ -17,28 +17,26 @@ export interface FinanceBucketRow {
   destinationStationId: string;
   segmentLabel: string;
   method: string;
+  currency: string;
   bookingCount: number;
-  revenueEtbMinor: number;
+  revenueMinor: number;
 }
 
+/** One roll-up entry. Amounts are never mixed across currencies — `currency` names which one this row is in. */
 export interface FinanceRollupRow {
   key: string;
   label: string;
-  revenueEtbMinor: number;
+  currency: string;
+  revenueMinor: number;
   bookingCount: number;
 }
 
-export interface FinanceTotals {
-  bookingCount: number;
-  revenueEtbMinor: number;
-}
-
 export interface FinanceSummaryReport {
   granularity: FinanceGranularity;
   dateFrom: string;
   dateTo: string;
-  currency: string;
-  totals: FinanceTotals;
+  /** Grand totals, one entry per currency present — never summed across currencies. */
+  totals: FinanceRollupRow[];
   byPeriod: FinanceRollupRow[];
   bySegment: FinanceRollupRow[];
   byMethod: FinanceRollupRow[];
diff --git a/apps/edr-passenger-web/backoffice/src/lib/export/finance-workbook.ts b/apps/edr-passenger-web/backoffice/src/lib/export/finance-workbook.ts
index da8f172be..066d6b355 100644
--- a/apps/edr-passenger-web/backoffice/src/lib/export/finance-workbook.ts
+++ b/apps/edr-passenger-web/backoffice/src/lib/export/finance-workbook.ts
@@ -12,7 +12,6 @@ const ROW_ALT = 'FFF7F8F7';
 const BORDER = 'FFE2E5E1';
 const WHITE = 'FFFFFFFF';
 
-const CURRENCY_FMT = '"ETB" #,##0.00';
 const THIN_BORDER: Partial<ExcelJS.Borders> = {
   top: { style: 'thin', color: { argb: BORDER } },
   left: { style: 'thin', color: { argb: BORDER } },
@@ -20,6 +19,11 @@ const THIN_BORDER: Partial<ExcelJS.Borders> = {
   right: { style: 'thin', color: { argb: BORDER } },
 };
 
+/** Amounts are never converted between currencies, so every number format names its own currency. */
+function currencyFmt(currency: string): string {
+  return `"${currency}" #,##0.00`;
+}
+
 export interface ChartImage {
   dataUrl: string;
   width: number;
@@ -31,7 +35,8 @@ export interface FinanceWorkbookInput {
   filters: { dateFrom: string; dateTo: string; granularity: FinanceGranularity; originLabel: string; destinationLabel: string; methodLabel: string };
   methodLabel: (method: string) => string;
   periodLabel: (period: string, granularity: FinanceGranularity) => string;
-  images: { trend?: ChartImage; segment?: ChartImage; method?: ChartImage };
+  /** One Trend/Segment/Method image set per currency present — mirrors the on-screen per-currency sections. */
+  imagesByCurrency: Record<string, { trend?: ChartImage; segment?: ChartImage; method?: ChartImage }>;
 }
 
 function styleHeaderCell(cell: ExcelJS.Cell) {
@@ -110,6 +115,18 @@ function kpiCard(ws: ExcelJS.Worksheet, startRow: number, startCol: number, span
   ws.getRow(startRow + 1).height = 26;
 }
 
+/** Lays out KPI cards three to a row (each spanning 2 of 6 columns). Returns the next free row. */
+function kpiRow(ws: ExcelJS.Worksheet, startRow: number, cards: { label: string; value: string; accent: string }[]): number {
+  const perRow = 3;
+  let row = startRow;
+  for (let i = 0; i < cards.length; i += perRow) {
+    const rowCards = cards.slice(i, i + perRow);
+    rowCards.forEach((c, idx) => kpiCard(ws, row, 1 + idx * 2, 2, c.label, c.value, c.accent));
+    row += 3;
+  }
+  return row;
+}
+
 function addImage(wb: ExcelJS.Workbook, ws: ExcelJS.Worksheet, image: ChartImage | undefined, anchorRow: number, heading: string) {
   const headingCell = ws.getCell(anchorRow, 1);
   headingCell.value = heading;
@@ -140,10 +157,13 @@ function addImage(wb: ExcelJS.Workbook, ws: ExcelJS.Worksheet, image: ChartImage
 }
 
 export async function buildFinanceWorkbook(input: FinanceWorkbookInput): Promise<Blob> {
-  const { report, filters, images } = input;
+  const { report, filters, imagesByCurrency } = input;
   const methodLabel = input.methodLabel;
   const periodLabel = input.periodLabel;
 
+  const totals = [...report.totals].sort((a, b) => b.revenueMinor - a.revenueMinor);
+  const totalBookings = totals.reduce((sum, t) => sum + t.bookingCount, 0);
+
   const wb = new ExcelJS.Workbook();
   wb.creator = 'EDR Passenger Backoffice';
   wb.created = new Date();
@@ -159,86 +179,105 @@ export async function buildFinanceWorkbook(input: FinanceWorkbookInput): Promise
     6,
   );
 
-  const avgPerBooking = report.totals.bookingCount > 0 ? report.totals.revenueEtbMinor / report.totals.bookingCount : 0;
-  kpiCard(summary, 4, 1, 2, 'Total Revenue', `ETB ${(report.totals.revenueEtbMinor / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}`, BRAND_DARK);
-  kpiCard(summary, 4, 3, 2, 'Bookings', report.totals.bookingCount.toLocaleString('en-US'), INK);
-  kpiCard(summary, 4, 5, 2, 'Avg. per Booking', `ETB ${(avgPerBooking / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}`, INK);
+  // Amounts are never converted between currencies — each currency present gets its own
+  // card, exactly like the on-screen "Revenue by Currency" breakdown.
+  const revenueCards = totals.map((t) => ({
+    label: `Revenue (${t.currency})`,
+    value: `${t.currency} ${(t.revenueMinor / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}`,
+    accent: BRAND_DARK,
+  }));
+  const cursorAfterKpis = kpiRow(summary, 4, [
+    { label: 'Bookings', value: totalBookings.toLocaleString('en-US'), accent: INK },
+    ...revenueCards,
+  ]);
 
-  let cursor = 7;
-  cursor = addImage(wb, summary, images.trend, cursor, 'Revenue Trend') + 1;
-  cursor = addImage(wb, summary, images.segment, cursor, 'Revenue by Segment') + 1;
-  addImage(wb, summary, images.method, cursor, 'Revenue by Payment Method');
+  // One Trend/Segment/Method chart set per currency, largest currency first — mirrors the
+  // on-screen layout so no currency's payment-method breakdown gets dropped from the file.
+  let cursor = cursorAfterKpis + 1;
+  for (const t of totals) {
+    const images = imagesByCurrency[t.currency] ?? {};
+    cursor = addImage(wb, summary, images.trend, cursor, `Revenue Trend (${t.currency})`) + 1;
+    cursor = addImage(wb, summary, images.segment, cursor, `Revenue by Segment (${t.currency})`) + 1;
+    cursor = addImage(wb, summary, images.method, cursor, `Revenue by Payment Method (${t.currency})`) + 1;
+  }
 
   // ── By Period sheet ──────────────────────────────────────────────────────
   const byPeriod = wb.addWorksheet('By Period', { views: [{ state: 'frozen', ySplit: 1 }] });
-  byPeriod.columns = [{ width: 18 }, { width: 14 }, { width: 20 }];
-  addTableHeader(byPeriod, 1, ['Period', 'Bookings', 'Revenue (ETB)'], new Set([1, 2]));
+  byPeriod.columns = [{ width: 18 }, { width: 12 }, { width: 14 }, { width: 20 }];
+  addTableHeader(byPeriod, 1, ['Period', 'Currency', 'Bookings', 'Revenue'], new Set([1, 2]));
   const periodRows = [...report.byPeriod].sort((a, b) => a.key.localeCompare(b.key));
   periodRows.forEach((p, i) => {
     const r = byPeriod.getRow(i + 2);
-    r.getCell(1).value = periodLabel(p.key, report.granularity);
-    r.getCell(2).value = p.bookingCount;
-    r.getCell(2).alignment = { horizontal: 'right' };
-    r.getCell(3).value = p.revenueEtbMinor / 100;
-    r.getCell(3).numFmt = CURRENCY_FMT;
+    r.getCell(1).value = periodLabel(p.label, report.granularity);
+    r.getCell(2).value = p.currency;
+    r.getCell(3).value = p.bookingCount;
     r.getCell(3).alignment = { horizontal: 'right' };
-    bandRow(byPeriod, i + 2, 3, i % 2 === 1);
+    r.getCell(4).value = p.revenueMinor / 100;
+    r.getCell(4).numFmt = currencyFmt(p.currency);
+    r.getCell(4).alignment = { horizontal: 'right' };
+    bandRow(byPeriod, i + 2, 4, i % 2 === 1);
   });
-  byPeriod.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 3 } };
+  byPeriod.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 4 } };
 
   // ── By Segment sheet ─────────────────────────────────────────────────────
   const bySegment = wb.addWorksheet('By Segment', { views: [{ state: 'frozen', ySplit: 1 }] });
-  bySegment.columns = [{ width: 34 }, { width: 14 }, { width: 20 }];
-  addTableHeader(bySegment, 1, ['Origin → Destination', 'Bookings', 'Revenue (ETB)'], new Set([1, 2]));
+  bySegment.columns = [{ width: 34 }, { width: 12 }, { width: 14 }, { width: 20 }];
+  addTableHeader(bySegment, 1, ['Origin → Destination', 'Currency', 'Bookings', 'Revenue'], new Set([1, 2]));
   report.bySegment.forEach((s, i) => {
     const r = bySegment.getRow(i + 2);
     r.getCell(1).value = s.label;
-    r.getCell(2).value = s.bookingCount;
-    r.getCell(2).alignment = { horizontal: 'right' };
-    r.getCell(3).value = s.revenueEtbMinor / 100;
-    r.getCell(3).numFmt = CURRENCY_FMT;
+    r.getCell(2).value = s.currency;
+    r.getCell(3).value = s.bookingCount;
     r.getCell(3).alignment = { horizontal: 'right' };
-    bandRow(bySegment, i + 2, 3, i % 2 === 1);
+    r.getCell(4).value = s.revenueMinor / 100;
+    r.getCell(4).numFmt = currencyFmt(s.currency);
+    r.getCell(4).alignment = { horizontal: 'right' };
+    bandRow(bySegment, i + 2, 4, i % 2 === 1);
   });
-  bySegment.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 3 } };
+  bySegment.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 4 } };
 
   // ── By Method sheet ──────────────────────────────────────────────────────
+  // Share is computed against the grand total for that same currency (`totals`), never
+  // against a sum spanning multiple currencies.
   const byMethod = wb.addWorksheet('By Method', { views: [{ state: 'frozen', ySplit: 1 }] });
-  byMethod.columns = [{ width: 20 }, { width: 14 }, { width: 20 }, { width: 12 }];
-  addTableHeader(byMethod, 1, ['Payment Method', 'Bookings', 'Revenue (ETB)', 'Share'], new Set([1, 2, 3]));
-  const methodTotal = report.byMethod.reduce((sum, m) => sum + m.revenueEtbMinor, 0);
+  byMethod.columns = [{ width: 20 }, { width: 12 }, { width: 14 }, { width: 20 }, { width: 12 }];
+  addTableHeader(byMethod, 1, ['Payment Method', 'Currency', 'Bookings', 'Revenue', 'Share'], new Set([1, 2, 3]));
+  const totalByCurrency = new Map(totals.map((t) => [t.currency, t.revenueMinor]));
   report.byMethod.forEach((m, i) => {
     const r = byMethod.getRow(i + 2);
-    r.getCell(1).value = methodLabel(m.key);
-    r.getCell(2).value = m.bookingCount;
-    r.getCell(2).alignment = { horizontal: 'right' };
-    r.getCell(3).value = m.revenueEtbMinor / 100;
-    r.getCell(3).numFmt = CURRENCY_FMT;
+    const currencyTotal = totalByCurrency.get(m.currency) ?? 0;
+    r.getCell(1).value = methodLabel(m.label);
+    r.getCell(2).value = m.currency;
+    r.getCell(3).value = m.bookingCount;
     r.getCell(3).alignment = { horizontal: 'right' };
-    r.getCell(4).value = methodTotal > 0 ? m.revenueEtbMinor / methodTotal : 0;
-    r.getCell(4).numFmt = '0.0%';
+    r.getCell(4).value = m.revenueMinor / 100;
+    r.getCell(4).numFmt = currencyFmt(m.currency);
     r.getCell(4).alignment = { horizontal: 'right' };
-    bandRow(byMethod, i + 2, 4, i % 2 === 1);
+    r.getCell(5).value = currencyTotal > 0 ? m.revenueMinor / currencyTotal : 0;
+    r.getCell(5).numFmt = '0.0%';
+    r.getCell(5).alignment = { horizontal: 'right' };
+    bandRow(byMethod, i + 2, 5, i % 2 === 1);
   });
-  byMethod.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 4 } };
+  byMethod.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 5 } };
 
   // ── Detail sheet — every row, unpaginated ───────────────────────────────
   const detail = wb.addWorksheet('Detail', { views: [{ state: 'frozen', ySplit: 1 }] });
-  detail.columns = [{ width: 18 }, { width: 34 }, { width: 18 }, { width: 14 }, { width: 20 }];
-  addTableHeader(detail, 1, ['Period', 'Origin → Destination', 'Payment Method', 'Bookings', 'Revenue (ETB)'], new Set([2, 3]));
+  detail.columns = [{ width: 18 }, { width: 34 }, { width: 18 }, { width: 12 }, { width: 14 }, { width: 20 }];
+  addTableHeader(detail, 1, ['Period', 'Origin → Destination', 'Payment Method', 'Currency', 'Bookings', 'Revenue'], new Set([2, 3]));
   report.rows.forEach((row, i) => {
     const r = detail.getRow(i + 2);
     r.getCell(1).value = periodLabel(row.period, report.granularity);
     r.getCell(2).value = row.segmentLabel;
     r.getCell(3).value = methodLabel(row.method);
-    r.getCell(4).value = row.bookingCount;
-    r.getCell(4).alignment = { horizontal: 'right' };
-    r.getCell(5).value = row.revenueEtbMinor / 100;
-    r.getCell(5).numFmt = CURRENCY_FMT;
+    r.getCell(4).value = row.currency;
+    r.getCell(5).value = row.bookingCount;
     r.getCell(5).alignment = { horizontal: 'right' };
-    bandRow(detail, i + 2, 5, i % 2 === 1);
+    r.getCell(6).value = row.revenueMinor / 100;
+    r.getCell(6).numFmt = currencyFmt(row.currency);
+    r.getCell(6).alignment = { horizontal: 'right' };
+    bandRow(detail, i + 2, 6, i % 2 === 1);
   });
-  detail.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 5 } };
+  detail.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: 6 } };
 
   const buffer = await wb.xlsx.writeBuffer();
   return new Blob([buffer], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
diff --git a/apps/edr-passenger-web/portal/src/app/booking/passengers/page.tsx b/apps/edr-passenger-web/portal/src/app/booking/passengers/page.tsx
index 60cd350a2..722ee75e2 100644
--- a/apps/edr-passenger-web/portal/src/app/booking/passengers/page.tsx
+++ b/apps/edr-passenger-web/portal/src/app/booking/passengers/page.tsx
@@ -3,6 +3,7 @@
 import { useForm, useFieldArray } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
+import { useQuery } from '@tanstack/react-query';
 import { useRouter } from 'next/navigation';
 import { useBookingStore } from '@/lib/booking-store';
 import { useAuthStore } from '@/lib/auth-store';
@@ -614,35 +615,9 @@ const passengerSchema = z.object({
   if (data.gender !== 'Male' && data.gender !== 'Female') {
     ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Gender is required', path: ['gender'] });
   }
-  const isNonEthiopian = data.nationality !== 'ETHIOPIAN' && data.nationality !== 'Ethiopian';
-  if (isNonEthiopian) {
-    const passportNum = data.passportNumber?.trim() ?? '';
-    if (!passportNum) {
-      ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Passport number is required', path: ['passportNumber'] });
-    } else if (/[^A-Za-z0-9]/.test(passportNum)) {
-      ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Passport number must not contain special characters', path: ['passportNumber'] });
-    } else if (passportNum.length < 6 || passportNum.length > 12) {
-      ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Passport number must be between 6 and 12 characters', path: ['passportNumber'] });
-    }
-    if (!data.passportCountry || data.passportCountry.trim().length === 0) {
-      ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Issuing country is required', path: ['passportCountry'] });
-    }
-    if (data.passportIssueDate) {
-      const issue = new Date(data.passportIssueDate);
-      if (!isNaN(issue.getTime()) && issue > new Date()) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Passport issue date cannot be in the future', path: ['passportIssueDate'] });
-      }
-    }
-    if (data.passportExpiryDate) {
-      const expiry = new Date(data.passportExpiryDate);
-      if (!isNaN(expiry.getTime()) && expiry <= new Date()) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Passport expiry date must be in the future', path: ['passportExpiryDate'] });
-      }
-    }
-  }
 });
 
-function createFormSchema(adultCount: number) {
+function createFormSchema(adultCount: number, isOriginOutsideEthiopia: boolean) {
   return z.object({
     passengers: z.array(passengerSchema),
     createAccount: z.boolean(),
@@ -660,6 +635,9 @@ function createFormSchema(adultCount: number) {
             ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid email format', path: ['passengers', i, 'email'] });
           }
         }
+        // Phone format stays scoped to the passenger's actual nationality regardless of the
+        // passport-flow override below — an Ethiopian is still validated against Ethiopian
+        // number ranges even when their origin station forces the foreigner document flow.
         const phoneError = validatePhone(p.phone, p.nationality);
         if (phoneError) {
           ctx.addIssue({ code: z.ZodIssueCode.custom, message: phoneError, path: ['passengers', i, 'phone'] });
@@ -667,11 +645,44 @@ function createFormSchema(adultCount: number) {
       }
 
       const age = calculateAge(p.dateOfBirth);
-      if (age === null) return;
-      if (isAdult && age <= 5) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Adult passengers must be older than 5 years', path: ['passengers', i, 'dateOfBirth'] });
-      } else if (!isAdult && age > 5) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Child passengers must be 5 years old or younger', path: ['passengers', i, 'dateOfBirth'] });
+      if (age !== null) {
+        if (isAdult && age <= 5) {
+          ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Adult passengers must be older than 5 years', path: ['passengers', i, 'dateOfBirth'] });
+        } else if (!isAdult && age > 5) {
+          ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Child passengers must be 5 years old or younger', path: ['passengers', i, 'dateOfBirth'] });
+        }
+      }
+
+      // Fayda's SMS-based OTP only reaches Ethiopian phone numbers inside Ethiopia, so a
+      // passenger boarding from a station outside Ethiopia can't complete it even when their
+      // nationality is Ethiopian — they (like any genuinely non-Ethiopian national) fall back
+      // to the same passport document requirements as a foreigner. Nationality and phone
+      // validation are unaffected by this — only the identity-document requirement changes.
+      const isNonEthiopianNationality = p.nationality !== 'ETHIOPIAN' && p.nationality !== 'Ethiopian';
+      if (isNonEthiopianNationality || isOriginOutsideEthiopia) {
+        const passportNum = p.passportNumber?.trim() ?? '';
+        if (!passportNum) {
+          ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Passport number is required', path: ['passengers', i, 'passportNumber'] });
+        } else if (/[^A-Za-z0-9]/.test(passportNum)) {
+          ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Passport number must not contain special characters', path: ['passengers', i, 'passportNumber'] });
+        } else if (passportNum.length < 6 || passportNum.length > 12) {
+          ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Passport number must be between 6 and 12 characters', path: ['passengers', i, 'passportNumber'] });
+        }
+        if (!p.passportCountry || p.passportCountry.trim().length === 0) {
+          ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Issuing country is required', path: ['passengers', i, 'passportCountry'] });
+        }
+        if (p.passportIssueDate) {
+          const issue = new Date(p.passportIssueDate);
+          if (!isNaN(issue.getTime()) && issue > new Date()) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Passport issue date cannot be in the future', path: ['passengers', i, 'passportIssueDate'] });
+          }
+        }
+        if (p.passportExpiryDate) {
+          const expiry = new Date(p.passportExpiryDate);
+          if (!isNaN(expiry.getTime()) && expiry <= new Date()) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Passport expiry date must be in the future', path: ['passengers', i, 'passportExpiryDate'] });
+          }
+        }
       }
     });
   });
@@ -684,6 +695,16 @@ function PassengersForm() {
   const { searchCriteria, passengers: storedPassengers, setPassengers, setCreateAccount, packageId } = useBookingStore();
   const { user, isAuthenticated, updateUser } = useAuthStore();
   const isInitialized = useAuthStore((s) => s.isInitialized);
+  // Fayda's SMS-based OTP is Ethiopia-only — a passenger boarding from a station outside
+  // Ethiopia can't receive it, so they need the passport flow below even if their nationality
+  // is Ethiopian. Looked up by ID rather than trusting a `country`/`countryCode` field carried
+  // on searchCriteria, since the origin station isn't otherwise threaded through this store.
+  const { data: originStation, isLoading: isOriginStationLoading } = useQuery({
+    queryKey: ['station', searchCriteria?.originStationId],
+    queryFn: () => apiClient.get<{ id: string; countryCode?: string }>(`/stations/${searchCriteria!.originStationId}`),
+    enabled: !!searchCriteria?.originStationId,
+  });
+  const isOriginOutsideEthiopia = !!originStation?.countryCode && originStation.countryCode !== 'ET';
   const [faydaEnabled, setFaydaEnabled] = useState(true);
   // "Skip for now" (bypasses Fayda verification) is only offered on local dev and the
   // staging/test domain — never on an unrecognized host, which would include production.
@@ -715,7 +736,7 @@ function PassengersForm() {
   const adultCount = searchCriteria?.adultCount || 1;
 
   const { register, control, handleSubmit, setValue, watch, formState: { errors } } = useForm<FormData>({
-    resolver: zodResolver(createFormSchema(adultCount) as any),
+    resolver: zodResolver(createFormSchema(adultCount, isOriginOutsideEthiopia) as any),
     mode: 'onChange',
     defaultValues: {
       passengers: Array.from({ length: totalPassengers }, (_, i) => {
@@ -931,6 +952,10 @@ function PassengersForm() {
         setFormInitialized(true);
         return;
       }
+      // Whether the Fayda gate applies below depends on the origin station's country — wait for
+      // that lookup to settle instead of gating on a stale "inside Ethiopia" default, which
+      // would flash the wrong screen for an Ethiopian departing from outside Ethiopia.
+      if (isOriginStationLoading) return;
 
       try {
         // Fetch passenger profile from backend. This may be null (e.g. no Passenger row linked
@@ -953,8 +978,9 @@ function PassengersForm() {
         // A logged-in but NOT Fayda-verified Ethiopian must pass the Fayda gate exactly like a
         // guest. Prefilling their identity and expanding the form would let them submit the
         // booking without ever verifying — only a verified passenger may pass. When Fayda is
-        // globally disabled there is no gate, so the restriction doesn't apply.
-        const mustVerifyFayda = isEthiopian && !isVerified && faydaEnabled;
+        // globally disabled, or the origin station is outside Ethiopia (SMS OTP won't reach
+        // them), there is no gate, so the restriction doesn't apply.
+        const mustVerifyFayda = isEthiopian && !isVerified && faydaEnabled && !isOriginOutsideEthiopia;
 
         // Nationality + contact aren't identity-verifying, so they're safe to prefill either way.
         setValue('passengers.0.nationality', nationality);
@@ -996,7 +1022,7 @@ function PassengersForm() {
     };
 
     populateForm();
-  }, [isInitialized, isAuthenticated, user, searchCriteria, setValue]);
+  }, [isInitialized, isAuthenticated, user, searchCriteria, setValue, isOriginStationLoading, isOriginOutsideEthiopia]);
 
   const openFaydaVerification = async (index: number) => {
     if (typeof window === 'undefined') return;
@@ -1047,7 +1073,7 @@ function PassengersForm() {
       const isEthiopian = p?.nationality === 'ETHIOPIAN';
       const isChildPassenger = i >= adultCount;
       const isLoggedInAndVerified = i === 0 && isAuthenticated && user?.faydaVerified;
-      return isEthiopian && faydaEnabled && !p?.formExpanded && !isLoggedInAndVerified && !isChildPassenger;
+      return isEthiopian && faydaEnabled && !isOriginOutsideEthiopia && !p?.formExpanded && !isLoggedInAndVerified && !isChildPassenger;
     });
     setSubmitError(
       needsFaydaVerification
@@ -1145,14 +1171,18 @@ function PassengersForm() {
           <form onSubmit={handleSubmit(onSubmit, onInvalid)} className="space-y-6">
             {fields.map((field, index) => {
               const isEthiopian = passengers[index]?.nationality === 'ETHIOPIAN';
+              // Fayda only applies to an Ethiopian national whose origin station is inside
+              // Ethiopia — outside it, the SMS OTP never arrives, so they go through the same
+              // passport flow as a foreigner (nationality/phone stay Ethiopian regardless).
+              const eligibleForFayda = isEthiopian && !isOriginOutsideEthiopia;
               const isFormExpanded = passengers[index]?.formExpanded;
               const status = verificationStatus[index];
               const isPrimaryPassenger = index === 0;
               const isChildPassenger = index >= adultCount;
               const isLoggedInAndVerified = isPrimaryPassenger && isAuthenticated && user?.faydaVerified;
               const isLoggedInNotVerified = isPrimaryPassenger && isAuthenticated && !user?.faydaVerified;
-              const showVerifyButton = isEthiopian && faydaEnabled && !isFormExpanded && !isLoggedInAndVerified && !isChildPassenger;
-              const showManualEntryLink = isEthiopian && !faydaEnabled && !isFormExpanded && !isChildPassenger;
+              const showVerifyButton = eligibleForFayda && faydaEnabled && !isFormExpanded && !isLoggedInAndVerified && !isChildPassenger;
+              const showManualEntryLink = eligibleForFayda && !faydaEnabled && !isFormExpanded && !isChildPassenger;
               const isVerifyingThis = verifyingIndex === index;
               const isVerifyingOther = verifyingIndex !== null && verifyingIndex !== index;
               const faydaError = faydaErrors[index];
@@ -1249,7 +1279,7 @@ function PassengersForm() {
                     </div>
                   ) : (
                     <div className="space-y-4">
-                      {isEthiopian ? (
+                      {eligibleForFayda ? (
                         <>
                           {status === 'success' && (
                             <div className="p-3 bg-green-50 dark:bg-green-900/30 border border-green-200 dark:border-green-800 rounded-lg mb-4">
diff --git a/apps/edr-passenger-web/portal/src/app/booking/search/page.tsx b/apps/edr-passenger-web/portal/src/app/booking/search/page.tsx
index 69d3859cf..bb4e2cf12 100644
--- a/apps/edr-passenger-web/portal/src/app/booking/search/page.tsx
+++ b/apps/edr-passenger-web/portal/src/app/booking/search/page.tsx
@@ -612,8 +612,15 @@ export default function SearchPage() {
     queryKey: ["stations"],
     // Bounded so a stalled request surfaces the "Unable to load stations"
     // error below instead of leaving the widget stuck loading indefinitely.
-    queryFn: async () =>
-      (await apiClient.get("/stations", { timeout: 8000 })) as Station[],
+    queryFn: async () => {
+      const res = await apiClient.get<Station[]>("/stations", {
+        timeout: 8000,
+      });
+      // apiClient unwraps `{ success, data }` envelopes, but guard against an
+      // unexpected non-array payload so downstream .find()/.filter() calls
+      // (here and in every StationSelector this list is passed to) never throw.
+      return Array.isArray(res) ? res : [];
+    },
   });
 
   const {
diff --git a/apps/edr-passenger-web/portal/src/components/PackagesSection.tsx b/apps/edr-passenger-web/portal/src/components/PackagesSection.tsx
index 2fdd50518..408dd3f56 100644
--- a/apps/edr-passenger-web/portal/src/components/PackagesSection.tsx
+++ b/apps/edr-passenger-web/portal/src/components/PackagesSection.tsx
@@ -209,7 +209,7 @@ function FeaturedCard({ pkg }: { pkg: HolidayPackage }) {
 
               {/* Name */}
               <h3 className="text-xl md:text-2xl font-extrabold text-gray-900 dark:text-white leading-tight mb-1.5">
-                {pkg.name.trim()}
+                {pkg.name?.trim()}
               </h3>
 
               {/* Route */}
@@ -217,11 +217,11 @@ function FeaturedCard({ pkg }: { pkg: HolidayPackage }) {
                 <div className="flex items-center gap-1.5 text-sm text-gray-500 dark:text-gray-400 mb-5">
                   <Train className="w-3.5 h-3.5 text-primary flex-shrink-0" />
                   <span className="font-medium text-gray-700 dark:text-gray-300">
-                    {origin.name.trim()}
+                    {origin.name?.trim()}
                   </span>
                   <ArrowRight className="w-3 h-3 flex-shrink-0" />
                   <span className="font-medium text-gray-700 dark:text-gray-300">
-                    {dest.name.trim()}
+                    {dest.name?.trim()}
                   </span>
                   {pkg.busTransferIncluded && (
                     <>
@@ -353,16 +353,16 @@ function PackageCard({ pkg }: { pkg: HolidayPackage }) {
         {/* Content */}
         <div className="flex flex-col flex-1 p-4">
           <h3 className="font-bold text-gray-900 dark:text-white text-sm leading-snug mb-2.5 line-clamp-2">
-            {pkg.name.trim()}
+            {pkg.name?.trim()}
           </h3>
 
           {/* Route */}
           {origin && dest && (
             <div className="flex items-center gap-1 text-xs text-gray-500 dark:text-gray-400 mb-2">
               <MapPin className="w-3 h-3 text-primary flex-shrink-0" />
-              <span className="truncate">{origin.name.trim()}</span>
+              <span className="truncate">{origin.name?.trim()}</span>
               <ArrowRight className="w-3 h-3 flex-shrink-0 text-gray-300" />
-              <span className="truncate">{dest.name.trim()}</span>
+              <span className="truncate">{dest.name?.trim()}</span>
             </div>
           )}
 

From aa850146dcf25c810f3e2bb2883299fc9a269635 Mon Sep 17 00:00:00 2001
From: Roba Boru <robab@ethiopianairines.com>
Date: Fri, 14 Aug 2026 08:22:50 +0300
Subject: [PATCH 090/174] Fix price on voucher

---
 .../prisma/fix-payment-method-currency.ts     | 49 +++++++++++++++++++
 .../backoffice/src/app/payments/page.tsx      | 20 ++++++--
 .../portal/src/lib/generate-voucher.ts        | 47 +++++++++++++-----
 3 files changed, 98 insertions(+), 18 deletions(-)
 create mode 100644 apps/edr-passenger-api/prisma/fix-payment-method-currency.ts

diff --git a/apps/edr-passenger-api/prisma/fix-payment-method-currency.ts b/apps/edr-passenger-api/prisma/fix-payment-method-currency.ts
new file mode 100644
index 000000000..8273cb1c2
--- /dev/null
+++ b/apps/edr-passenger-api/prisma/fix-payment-method-currency.ts
@@ -0,0 +1,49 @@
+/**
+ * One-off data fix: corrects PaymentMethod.currency for methods whose settlement currency
+ * was never set at seed time and silently defaulted to the schema's ETB default.
+ *
+ * payments.service.ts's chargeCurrency resolution reads this column directly (see the
+ * comment above `chargeCurrency` in `initiatePayment`): WAAFI settles in DJF, CARD in USD.
+ * With WAAFI stuck on the ETB default, live Waafi payments were charged in ETB instead of
+ * being converted to DJF — not just a mislabeled report. This script only touches the
+ * PaymentMethod config row; it does NOT rewrite any existing PaymentIntent/Booking records,
+ * since correcting historical transaction currency is a financial decision, not a data-fix
+ * this script should make unilaterally.
+ *
+ * Safe to re-run. Only updates rows that already exist; does not create new ones.
+ *
+ * Usage: node --env-file=.env -r ts-node/register prisma/fix-payment-method-currency.ts
+ */
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+const CORRECTIONS: { type: string; currency: string }[] = [
+  { type: 'WAAFI', currency: 'DJF' },
+  { type: 'CARD', currency: 'USD' },
+];
+
+async function main() {
+  for (const { type, currency } of CORRECTIONS) {
+    const existing = await prisma.paymentMethod.findUnique({ where: { type: type as any } });
+    if (!existing) {
+      console.log(`  ⚠️  No PaymentMethod row for ${type} — skipping (nothing to correct).`);
+      continue;
+    }
+    if (existing.currency === currency) {
+      console.log(`  ℹ️  ${type} already set to ${currency} — no change.`);
+      continue;
+    }
+    await prisma.paymentMethod.update({ where: { type: type as any }, data: { currency } });
+    console.log(`  ✅ ${type}: ${existing.currency} → ${currency}`);
+  }
+}
+
+main()
+  .catch((e) => {
+    console.error('❌ fix-payment-method-currency failed:', e);
+    process.exitCode = 1;
+  })
+  .finally(async () => {
+    await prisma.$disconnect();
+  });
diff --git a/apps/edr-passenger-web/backoffice/src/app/payments/page.tsx b/apps/edr-passenger-web/backoffice/src/app/payments/page.tsx
index e59a867ed..0bef617c1 100644
--- a/apps/edr-passenger-web/backoffice/src/app/payments/page.tsx
+++ b/apps/edr-passenger-web/backoffice/src/app/payments/page.tsx
@@ -1,8 +1,8 @@
 'use client';
 
-import { Suspense, useState } from 'react';
+import { Suspense, useEffect, useState } from 'react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { useSearchParams } from 'next/navigation';
+import { useRouter, useSearchParams } from 'next/navigation';
 import { Download, Eye, Trash2, AlertCircle, Send, CheckCircle, XCircle, RotateCcw, X } from 'lucide-react';
 import DataTable from '@/components/ui/DataTable';
 import Badge from '@/components/ui/Badge';
@@ -56,18 +56,28 @@ const SectionHeader = ({ title }: { title: string }) => (
 );
 
 function PaymentsPageContent() {
+  const router = useRouter();
   const searchParams = useSearchParams();
   // A link can pre-filter this page — the dashboard's Revenue card links here with
   // status=SUCCEEDED&bookingStatus=CONFIRMED,BOARDED so "view payments" shows exactly the
   // payments that make up that revenue figure, not every payment attempt.
-  const initialBookingStatus = searchParams.get('bookingStatus') ?? '';
   const [pageTab, setPageTab] = useState<PageTab>('payments');
   const [filters, setFilters] = useState({
     search: '',
     status: searchParams.get('status') ?? '',
     method: '',
-    bookingStatus: initialBookingStatus,
+    bookingStatus: searchParams.get('bookingStatus') ?? '',
   });
+
+  // useState's initializer only runs on first mount — if this page was already mounted from
+  // an earlier visit (e.g. the sidebar link), Next's client-side navigation to a new
+  // ?status=...&bookingStatus=... URL does NOT remount the component, so the filters above
+  // would silently keep whatever was set before. Re-sync whenever the URL itself changes.
+  useEffect(() => {
+    const status = searchParams.get('status') ?? '';
+    const bookingStatus = searchParams.get('bookingStatus') ?? '';
+    setFilters((f) => (f.status === status && f.bookingStatus === bookingStatus ? f : { ...f, status, bookingStatus }));
+  }, [searchParams]);
   const [selectedPayment, setSelectedPayment] = useState<any>(null);
   const [deleteConfirmOpen, setDeleteConfirmOpen] = useState(false);
   const [paymentToDelete, setPaymentToDelete] = useState<any>(null);
@@ -319,7 +329,7 @@ function PaymentsPageContent() {
             </span>
             <button
               type="button"
-              onClick={() => setFilters({ ...filters, status: '', bookingStatus: '' })}
+              onClick={() => { setFilters({ ...filters, status: '', bookingStatus: '' }); router.replace('/payments'); }}
               className="flex items-center gap-1 font-medium hover:underline shrink-0 ml-3"
             >
               <X className="w-3.5 h-3.5" /> Clear
diff --git a/apps/edr-passenger-web/portal/src/lib/generate-voucher.ts b/apps/edr-passenger-web/portal/src/lib/generate-voucher.ts
index abbf6eedf..de306da8f 100644
--- a/apps/edr-passenger-web/portal/src/lib/generate-voucher.ts
+++ b/apps/edr-passenger-web/portal/src/lib/generate-voucher.ts
@@ -455,8 +455,11 @@ interface VoucherData {
   // /bookings/:ref returns one row per passenger PER LEG for round trips (leg 1 =
   // outbound, leg 2 = return), each with that leg's own seat — see bookings.service.ts's
   // getByRef(). dateOfBirth is included purely to disambiguate same-name passengers when
-  // grouping leg rows back into one passenger below.
-  passengers: Array<{ fullName: string; dateOfBirth?: string; category: string; leg?: number; seat?: { number: string; coach: string; seatClass: string } }>;
+  // grouping leg rows back into one passenger below. fareMinor is that specific row's own
+  // fare (ETB minor units) — e.g. a free child's row is 0 even though other passengers on
+  // the same booking paid full fare — mirrored from the same field the booking detail
+  // page's "Fare breakdown" section already reads (booking/detail/page.tsx).
+  passengers: Array<{ fullName: string; dateOfBirth?: string; category: string; leg?: number; fareMinor?: number; seat?: { number: string; coach: string; seatClass: string } }>;
   schedule: VoucherSchedule;
   returnSchedule?: VoucherSchedule | null;
   totalMinor: number;
@@ -475,32 +478,46 @@ interface VoucherData {
 }
 
 export const generateVoucherPDF = async (booking: VoucherData): Promise<void> => {
-  // The amount shown is always a single raw field straight from the API — the settled
-  // payment amount when available, otherwise the booking total — never a derived value
-  // (previously this fell back to Math.round(totalMinor / passengers.length), which
-  // doesn't correspond to any real field and could disagree with what was actually
-  // charged). Same value on every passenger's voucher; no /100, no per-passenger split.
+  // Currency always comes straight from the booking/payment data, never hardcoded — the
+  // settled payment currency when a payment has settled, otherwise the booking's own
+  // display currency (falling back to the internal ETB currency field).
   const settledAmountMinor = booking.payment?.amountMinor;
   const settledCurrency = booking.payment?.currency;
   const useSettledAmount = settledAmountMinor != null && !!settledCurrency;
   // Prefer displayCurrency (passenger's home currency) over the internal ETB currency field.
   const voucherCurrency = useSettledAmount ? settledCurrency! : (booking.displayCurrency || booking.currency || 'ETB');
-  // Use displayTotalMinor when available so the voucher shows the passenger's currency amount.
-  const voucherFareMinor = useSettledAmount ? settledAmountMinor! : (booking.displayTotalMinor ?? booking.totalMinor);
+  // Basis total for the currency this voucher displays — the settled payment amount when
+  // available, otherwise the display-currency total (falling back to the raw ETB total).
+  const voucherBasisTotal = useSettledAmount ? settledAmountMinor! : (booking.displayTotalMinor ?? booking.totalMinor);
+  // Ratio that converts a passenger's own ETB fareMinor into the same currency/amount basis
+  // as voucherBasisTotal above — e.g. if the settled payment is 60% of the ETB total (a
+  // currency conversion), each passenger's own ETB fare is scaled by that same 60% ratio.
+  // This is NOT an equal split: two passengers with different fares still get different
+  // scaled amounts, in exact proportion to what each of them actually paid. Falls back to no
+  // scaling (ratio 1) only when the totals are missing or already equal, mirroring the same
+  // fallback the booking detail page's "Fare breakdown" section uses for this identical ratio.
+  const etbTotalMinor = booking.totalMinor;
+  const fareScaleFactor =
+    !etbTotalMinor || !voucherBasisTotal || etbTotalMinor === voucherBasisTotal
+      ? 1
+      : voucherBasisTotal / etbTotalMinor;
 
   const isRoundTrip = booking.bookingType === 'ROUND_TRIP' && !!booking.returnSchedule;
 
   // Group leg rows back into one entry per real passenger — without this, a round trip
   // produced two half-passenger vouchers (one per leg, each showing only its own leg's
-  // seat) instead of one voucher per passenger covering both legs.
+  // seat) instead of one voucher per passenger covering both legs. Each leg row's own
+  // fareMinor is summed here too, so a round trip's voucher reflects both legs' fares
+  // and a one-way voucher reflects just its single row's fare.
   type SeatInfo = VoucherData['passengers'][number]['seat'];
   const grouped = new Map<
     string,
-    { fullName: string; category: string; outboundSeat?: SeatInfo; returnSeat?: SeatInfo }
+    { fullName: string; category: string; fareMinor: number; outboundSeat?: SeatInfo; returnSeat?: SeatInfo }
   >();
   booking.passengers.forEach((p) => {
     const key = `${p.fullName}|${p.dateOfBirth}|${p.category}`;
-    const entry = grouped.get(key) || { fullName: p.fullName, category: p.category, outboundSeat: undefined, returnSeat: undefined };
+    const entry = grouped.get(key) || { fullName: p.fullName, category: p.category, fareMinor: 0, outboundSeat: undefined, returnSeat: undefined };
+    entry.fareMinor += p.fareMinor ?? 0;
     if (p.leg === 2) entry.returnSeat = p.seat;
     else entry.outboundSeat = p.seat;
     grouped.set(key, entry);
@@ -522,6 +539,10 @@ export const generateVoucherPDF = async (booking: VoucherData): Promise<void> =>
     // if it doesn't match what's actually on file.
     const ticketNumber = matchedTicket?.barcodePayload || 'Not yet issued';
 
+    // This passenger's own fare, scaled onto the same currency/amount basis as the rest of
+    // the voucher — not the booking's overall total, and not an equal share of it.
+    const passengerFareMinor = Math.round(p.fareMinor * fareScaleFactor);
+
     await generatePassengerVoucherPDF({
       bookingRef:           booking.bookingRef,
       ticketNumber,
@@ -536,7 +557,7 @@ export const generateVoucherPDF = async (booking: VoucherData): Promise<void> =>
       outboundCoachNumber:  isRoundTrip ? p.outboundSeat?.coach : undefined,
       inboundSeatNumber:    isRoundTrip ? p.returnSeat?.number : undefined,
       inboundCoachNumber:   isRoundTrip ? p.returnSeat?.coach : undefined,
-      fareMinor:            voucherFareMinor,
+      fareMinor:            passengerFareMinor,
       currency:             voucherCurrency,
       fareIsMajorUnits:     useSettledAmount,
       createdAt:            booking.createdAt,

From ab5a4117df9d22bff2aae3422f2a7a066be868c6 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Fri, 14 Aug 2026 07:04:57 +0000
Subject: [PATCH 091/174] fix: ui

---
 .../pages/customers/CustomerDetailPage.tsx    | 101 +++++++--------
 apps/edr-freight-web/portal/src/App.tsx       | 119 +++++++++---------
 2 files changed, 111 insertions(+), 109 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
index 7107ae7a5..b395cc710 100644
--- a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
@@ -173,7 +173,10 @@ export default function CustomerDetailPage() {
       enabled: Boolean(id),
     }),
   );
-  const contractsQuery = useContractList({ companyId: id, pageSize: 100 }, Boolean(id));
+  const contractsQuery = useContractList(
+    { companyId: id, pageSize: 100 },
+    Boolean(id),
+  );
 
   const { pagination: invoicePagination, setPagination: setInvoicePagination } =
     usePagination({
@@ -462,42 +465,31 @@ export default function CustomerDetailPage() {
 
   const documentColumns: ColumnDef<CustomerDocument>[] = useMemo(
     () => [
-      {
-        id: "name",
-        header: "Document",
-        cell: ({ row }) => {
-          const doc = row.original;
-          return (
-            <Stack gap={2}>
-              <Group gap="sm" wrap="nowrap">
-                <FileText size={16} className="shrink-0 text-edr-muted" />
-                <Text size="sm" c="edr-text" truncate>
-                  {doc.name}
-                </Text>
-                {doc.reviewStatus === "change_requested" && (
-                  <Badge size="xs" color="orange" variant="light">
-                    Change requested
-                  </Badge>
-                )}
-              </Group>
-              {/* The note is the whole point of the request — show it inline so a
-                  second reviewer sees what was already asked for. */}
-              {doc.reviewStatus === "change_requested" && doc.reviewNote && (
-                <Text size="xs" c="dimmed" pl={24}>
-                  {doc.reviewNote}
-                </Text>
-              )}
-            </Stack>
-          );
-        },
-      },
       {
         id: "code",
         header: "Type",
         cell: ({ row }) => (
-          <Text size="sm" c="dimmed">
-            {humanize(row.original.code)}
-          </Text>
+          <Stack gap={2}>
+            <Group gap="sm" wrap="nowrap">
+              <FileText size={16} className="shrink-0 text-edr-muted" />
+              <Text size="sm" c="edr-text" truncate>
+                {humanize(row.original.code)}
+              </Text>
+              {row.original.reviewStatus === "change_requested" && (
+                <Badge size="xs" color="orange" variant="light">
+                  Change requested
+                </Badge>
+              )}
+            </Group>
+            {/* The note is the whole point of the request — show it inline so a
+                  second reviewer sees what was already asked for. */}
+            {row.original.reviewStatus === "change_requested" &&
+              row.original.reviewNote && (
+                <Text size="xs" c="dimmed" pl={24}>
+                  {row.original.reviewNote}
+                </Text>
+              )}
+          </Stack>
         ),
       },
       {
@@ -751,9 +743,8 @@ export default function CustomerDetailPage() {
         ]}
         backTo="/dashboard/customers"
         title={company.name}
-        subtitle={`TIN ${company.tin}${
-          company.country ? ` · ${company.country}` : ""
-        }`}
+        subtitle={`TIN ${company.tin}${company.country ? ` · ${company.country}` : ""
+          }`}
         meta={
           <Group gap="xs" wrap="nowrap">
             <CompanyTypeBadge type={company.type} />
@@ -1247,13 +1238,15 @@ export default function CustomerDetailPage() {
               status={tableStatus(bookingsQuery)}
               emptyMessage="No bookings for this customer."
               containerClassName="border-0 shadow-none bg-transparent"
-              onRowClick={(row) => navigate(`/dashboard/booking-requests/${row.id}`)}
+              onRowClick={(row) =>
+                navigate(`/dashboard/booking-requests/${row.id}`)
+              }
               error={
                 bookingsQuery.isError
                   ? {
-                      message: "Failed to load bookings.",
-                      onRetry: () => void bookingsQuery.refetch(),
-                    }
+                    message: "Failed to load bookings.",
+                    onRetry: () => void bookingsQuery.refetch(),
+                  }
                   : undefined
               }
             />
@@ -1269,13 +1262,15 @@ export default function CustomerDetailPage() {
               status={tableStatus(contractsQuery)}
               emptyMessage="No contracts for this customer."
               containerClassName="border-0 shadow-none bg-transparent"
-              onRowClick={(row) => navigate(`/dashboard/contract-requests/${row.id}`)}
+              onRowClick={(row) =>
+                navigate(`/dashboard/contract-requests/${row.id}`)
+              }
               error={
                 contractsQuery.isError
                   ? {
-                      message: "Failed to load contracts.",
-                      onRetry: () => void contractsQuery.refetch(),
-                    }
+                    message: "Failed to load contracts.",
+                    onRetry: () => void contractsQuery.refetch(),
+                  }
                   : undefined
               }
             />
@@ -1295,9 +1290,9 @@ export default function CustomerDetailPage() {
                 error={
                   documentsQuery.isError
                     ? {
-                        message: "Failed to load documents.",
-                        onRetry: () => void documentsQuery.refetch(),
-                      }
+                      message: "Failed to load documents.",
+                      onRetry: () => void documentsQuery.refetch(),
+                    }
                     : undefined
                 }
               />
@@ -1372,9 +1367,9 @@ export default function CustomerDetailPage() {
               error={
                 paymentsQuery.isError
                   ? {
-                      message: "Failed to load payments.",
-                      onRetry: () => void paymentsQuery.refetch(),
-                    }
+                    message: "Failed to load payments.",
+                    onRetry: () => void paymentsQuery.refetch(),
+                  }
                   : undefined
               }
             />
@@ -1395,9 +1390,9 @@ export default function CustomerDetailPage() {
                 error={
                   invoicesQuery.isError
                     ? {
-                        message: "Failed to load invoices.",
-                        onRetry: () => void invoicesQuery.refetch(),
-                      }
+                      message: "Failed to load invoices.",
+                      onRetry: () => void invoicesQuery.refetch(),
+                    }
                     : undefined
                 }
                 pagination={{
diff --git a/apps/edr-freight-web/portal/src/App.tsx b/apps/edr-freight-web/portal/src/App.tsx
index bd20dfc71..8ab2f60d1 100644
--- a/apps/edr-freight-web/portal/src/App.tsx
+++ b/apps/edr-freight-web/portal/src/App.tsx
@@ -336,6 +336,7 @@ const App = () => {
     createProfile,
     reapplyProfile,
     isAuthenticated,
+    isShippingLine,
   } = useAuth();
 
   // Attribute replays and exceptions to the signed-in user (id/org only).
@@ -410,66 +411,72 @@ const App = () => {
               at their own routes — nothing here is shared with the customer
               branch below beyond the shell component itself. Contracts are
               absent by design: shipping lines request bookings directly. */}
-            <Route element={<RequireShippingLine />}>
-              <Route
-                element={
-                  <AppLayout
-                    title="EDR Freight"
-                    sidebarItems={shippingLineSidebarItems}
-                    activeHref={location.pathname}
-                    onNavigate={navigate}
-                    userName={displayName}
-                    userEmail={userEmail}
-                    // Support chat is company-scoped; a shipping line has no
-                    // company, so every poll would 403.
-                    showSupportWidget={false}
-                  >
-                    <Outlet />
-                  </AppLayout>
-                }
-              >
+            {isShippingLine && (
+              <Route element={<RequireShippingLine />}>
                 <Route
-                  path="/shipping-line"
-                  element={<ShippingLineHomePage />}
-                />
-                <Route
-                  path="/shipping-line/bookings"
-                  element={<ShippingLineBookingsPage />}
-                />
-                <Route
-                  path="/shipping-line/bookings/:id"
-                  element={<ShippingLineBookingDetailPage />}
-                />
-                <Route
-                  path="/shipping-line/bookings/:id/complete"
-                  element={<ShippingLineCompletePage />}
-                />
-                <Route
-                  path="/shipping-line/invoices"
-                  element={<ShippingLineInvoicesPage />}
-                />
-                {/* Same detail component as the customer's /billing/:id — the
+                  element={
+                    <AppLayout
+                      title="EDR Freight"
+                      sidebarItems={shippingLineSidebarItems}
+                      activeHref={location.pathname}
+                      onNavigate={navigate}
+                      userName={displayName}
+                      userEmail={userEmail}
+                      // Support chat is company-scoped; a shipping line has no
+                      // company, so every poll would 403.
+                      showSupportWidget={false}
+                    >
+                      <Outlet />
+                    </AppLayout>
+                  }
+                >
+                  <Route
+                    path="/shipping-line"
+                    element={<ShippingLineHomePage />}
+                  />
+                  <Route
+                    path="/shipping-line/bookings"
+                    element={<ShippingLineBookingsPage />}
+                  />
+                  <Route
+                    path="/shipping-line/bookings/:id"
+                    element={<ShippingLineBookingDetailPage />}
+                  />
+                  <Route
+                    path="/shipping-line/bookings/:id/complete"
+                    element={<ShippingLineCompletePage />}
+                  />
+                  <Route
+                    path="/shipping-line/invoices"
+                    element={<ShippingLineInvoicesPage />}
+                  />
+                  {/* Same detail component as the customer's /billing/:id — the
                     API scopes my-invoices to the signed-in payer either way,
                     and the page derives its back target from the URL. */}
-                <Route
-                  path="/shipping-line/invoices/:id"
-                  element={<InvoiceDetailPage />}
-                />
-                <Route
-                  path="/shipping-line/settings"
-                  element={<ShippingLineSettingsPage />}
-                />
-                <Route
-                  path="/shipping-line/help"
-                  element={<ShippingLineHelpPage />}
-                />
-                {/* Old shared links land on the shipping-line equivalents. */}
-                <Route
-                  path="/settings"
-                  element={<Navigate to="/shipping-line/settings" replace />}
-                />
+                  <Route
+                    path="/shipping-line/invoices/:id"
+                    element={<InvoiceDetailPage />}
+                  />
+                  <Route
+                    path="/shipping-line/settings"
+                    element={<ShippingLineSettingsPage />}
+                  />
+                  <Route
+                    path="/shipping-line/settings"
+                    element={<ShippingLineSettingsPage />}
+                  />
+                  <Route
+                    path="/shipping-line/help"
+                    element={<ShippingLineHelpPage />}
+                  />
+                  {/* Old shared links land on the shipping-line equivalents. */}
+                  <Route
+                    path="/settings"
+                    element={<Navigate to="/shipping-line/settings" replace />}
+                  />
+                </Route>
               </Route>
-            </Route>
+            )}
 
             {/* Customer app — unchanged. */}
             <Route element={<RequireCustomer />}>

From 41f480554c664fb7e7b28c22da9231b90868985f Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Fri, 14 Aug 2026 07:16:19 +0000
Subject: [PATCH 092/174] feat(billing): add PNR row to freight invoice from
 booking payment reference
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PNR isn't a column on Invoice/Payment — it's written onto Booking.pnrCode
when a CBE_BILL payment initiates. toDocumentModel() now looks it up by
invoice.sourceId and adds it to the existing summary grid, shown only
when present.
---
 .../src/modules/billing/billing.service.ts            | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index bc79f8899..5afa30128 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -513,6 +513,17 @@ export class BillingService {
     // MoR EIMS reference — only once actually registered, never a placeholder row.
     if (invoice.eimsIrn) summary.push({ label: "EIMS IRN", value: invoice.eimsIrn });
 
+    // PNR — the CBE_BILL reference the customer pays against, written onto the booking at
+    // payment-initiation time (see initiatePayment()). Not a column on Invoice/Payment, so
+    // look it up by source id; only shown once a payment actually generated one.
+    if (invoice.source === Freight.InvoiceSource.Booking) {
+      const booking = await this.dataSource.getRepository(Booking).findOne({
+        where: { id: invoice.sourceId },
+        select: ["id", "pnrCode"],
+      });
+      if (booking?.pnrCode) summary.push({ label: "PNR", value: booking.pnrCode });
+    }
+
     return {
       kind,
       title,

From daee3eac0ead4ea7d63e0b31de72bfc49fdc98b2 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Fri, 14 Aug 2026 08:17:35 +0000
Subject: [PATCH 093/174] feat(warehouses): pick export train when allocating
 empty return to wagon

Advancing an empty container return to WAGON_ALLOCATED opened no dialog,
so the wagon_allocation_reference column stayed null and nobody knew which
departure carried the empty. Now the action opens a picker of scheduled
EXPORT trains (DRAFT/SCHEDULED) and records the selection.
---
 .../pages/warehouses/ContainerReturnsPage.tsx | 170 +++++++++++++++++-
 1 file changed, 163 insertions(+), 7 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
index f8468181c..11bf69334 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
@@ -37,6 +37,7 @@ import type {
   EmptyContainerReturn,
   EmptyContainerReturnStatus,
 } from "@/types/importOperations";
+import type { TrainScheduleListItem } from "@/types/trainScheduling";
 import { formatDateTime } from "@/lib/format";
 
 type ReturnType = "all" | "edr" | "customer";
@@ -100,6 +101,7 @@ export default function ContainerReturnsPage() {
   const [standaloneModalOpen, setStandaloneModalOpen] = useState(false);
   const [activeKey, setActiveKey] = useState<string | null>(null);
   const [historyRow, setHistoryRow] = useState<any | null>(null);
+  const [allocateRow, setAllocateRow] = useState<EmptyContainerReturn | null>(null);
 
   const { data: unloadedQueue = [], isLoading: queueLoading } = useQuery({
     queryKey: ["import-unloaded-queue"],
@@ -306,15 +308,25 @@ export default function ContainerReturnsPage() {
   });
 
   const advanceStatusMutation = useMutation({
-    mutationFn: (id: string) => {
+    mutationFn: ({
+      id,
+      wagonAllocationReference,
+    }: {
+      id: string;
+      wagonAllocationReference?: string;
+    }) => {
       const current = returnedContainers.find((r: any) => r.id === id);
       const nextIndex = RETURN_STATUS_ORDER.indexOf(current?.status ?? "RETURNED") + 1;
       const status = RETURN_STATUS_ORDER[nextIndex] ?? "COMPLETED";
-      return importOperationsService.updateEmptyReturnStatus(id, { status });
+      return importOperationsService.updateEmptyReturnStatus(id, {
+        status,
+        wagonAllocationReference,
+      });
     },
     onSuccess: () => {
       toast({ title: "Return status updated" });
       qc.invalidateQueries({ queryKey: ["empty-container-returns"] });
+      setAllocateRow(null);
     },
     onError: (error: any) => {
       toast({
@@ -381,9 +393,16 @@ export default function ContainerReturnsPage() {
       id: "status",
       header: "Status",
       cell: ({ row }) => (
-        <Badge size="sm">
-          {RETURN_STATUS_LABEL[row.original.status] ?? row.original.status}
-        </Badge>
+        <Stack gap={2}>
+          <Badge size="sm">
+            {RETURN_STATUS_LABEL[row.original.status] ?? row.original.status}
+          </Badge>
+          {row.original.wagonAllocationReference && (
+            <Text size="xs" c="dimmed">
+              Train {row.original.wagonAllocationReference}
+            </Text>
+          )}
+        </Stack>
       ),
     },
     {
@@ -406,8 +425,15 @@ export default function ContainerReturnsPage() {
               <Button
                 size="xs"
                 variant="light"
-                loading={advanceStatusMutation.isPending && advanceStatusMutation.variables === ret.id}
-                onClick={() => advanceStatusMutation.mutate(ret.id)}
+                loading={
+                  advanceStatusMutation.isPending &&
+                  advanceStatusMutation.variables?.id === ret.id
+                }
+                onClick={() =>
+                  nextStatus === "WAGON_ALLOCATED"
+                    ? setAllocateRow(ret)
+                    : advanceStatusMutation.mutate({ id: ret.id })
+                }
               >
                 Advance to {RETURN_STATUS_LABEL[nextStatus]}
               </Button>
@@ -629,6 +655,19 @@ export default function ContainerReturnsPage() {
         loading={createReturnsMutation.isPending}
       />
 
+      <ExportTrainAllocationModal
+        row={allocateRow}
+        onClose={() => setAllocateRow(null)}
+        onSubmit={(reference) =>
+          allocateRow &&
+          advanceStatusMutation.mutate({
+            id: allocateRow.id,
+            wagonAllocationReference: reference,
+          })
+        }
+        loading={advanceStatusMutation.isPending}
+      />
+
       <Modal opened={!!historyRow} onClose={() => setHistoryRow(null)} title="Status History" size="sm">
         {historyRow && (
           <Stack gap="sm">
@@ -649,6 +688,123 @@ export default function ContainerReturnsPage() {
   );
 }
 
+/**
+ * Empties ride an EXPORT departure back to Djibouti, so wagon allocation picks
+ * from the export schedules that have not left yet (DRAFT/SCHEDULED). The pick
+ * is recorded as the return's `wagonAllocationReference`.
+ */
+function ExportTrainAllocationModal({
+  row,
+  onClose,
+  onSubmit,
+  loading,
+}: {
+  row: EmptyContainerReturn | null;
+  onClose: () => void;
+  onSubmit: (reference: string) => void;
+  loading: boolean;
+}) {
+  const [scheduleId, setScheduleId] = useState<string | null>(null);
+
+  const schedulesQuery = useQuery(
+    api.trainScheduling.scheduleList.queryOptions({
+      input: { filters: { pageSize: 100, sortBy: "scheduledDepartureDate", sortOrder: "ASC" } },
+      enabled: Boolean(row),
+    }),
+  );
+
+  const exportTrains = useMemo(
+    () =>
+      ((schedulesQuery.data?.items ?? []) as TrainScheduleListItem[]).filter(
+        (s) => s.direction === "EXPORT" && (s.status === "DRAFT" || s.status === "SCHEDULED"),
+      ),
+    [schedulesQuery.data],
+  );
+
+  const referenceOf = (train: TrainScheduleListItem) =>
+    train.trainNumber || train.reference || train.id;
+
+  return (
+    <Modal opened={!!row} onClose={onClose} title="Allocate to Export Train" size="lg">
+      {row && (
+        <Stack gap="md">
+          <Text fw={600}>{row.containerNumber}</Text>
+
+          {schedulesQuery.isLoading ? (
+            <Group justify="center" py="md">
+              <Loader size="sm" />
+            </Group>
+          ) : exportTrains.length === 0 ? (
+            <Alert color="gray">No export train is scheduled — create one in Train Scheduling.</Alert>
+          ) : (
+            <Table highlightOnHover>
+              <Table.Thead>
+                <Table.Tr>
+                  <Table.Th w={40} />
+                  <Table.Th>Train</Table.Th>
+                  <Table.Th>Departure</Table.Th>
+                  <Table.Th>Route</Table.Th>
+                  <Table.Th>Wagons</Table.Th>
+                  <Table.Th>Status</Table.Th>
+                </Table.Tr>
+              </Table.Thead>
+              <Table.Tbody>
+                {exportTrains.map((train) => (
+                  <Table.Tr
+                    key={train.id}
+                    onClick={() => setScheduleId(train.id)}
+                    style={{ cursor: "pointer" }}
+                  >
+                    <Table.Td>
+                      <Checkbox
+                        checked={scheduleId === train.id}
+                        onChange={() => setScheduleId(train.id)}
+                      />
+                    </Table.Td>
+                    <Table.Td>
+                      <Text fw={600} size="sm">
+                        {referenceOf(train)}
+                      </Text>
+                    </Table.Td>
+                    <Table.Td>
+                      {train.scheduleDate ? new Date(train.scheduleDate).toLocaleDateString() : "—"}
+                    </Table.Td>
+                    <Table.Td>
+                      {train.origin ?? "—"} → {train.destination ?? "—"}
+                    </Table.Td>
+                    <Table.Td>
+                      {train.wagonsUsed ?? 0}/{train.wagonCount}
+                    </Table.Td>
+                    <Table.Td>
+                      <Badge size="sm">{train.status}</Badge>
+                    </Table.Td>
+                  </Table.Tr>
+                ))}
+              </Table.Tbody>
+            </Table>
+          )}
+
+          <Group justify="flex-end" gap="sm">
+            <Button variant="default" onClick={onClose} disabled={loading}>
+              Cancel
+            </Button>
+            <Button
+              disabled={!scheduleId}
+              loading={loading}
+              onClick={() => {
+                const train = exportTrains.find((t) => t.id === scheduleId);
+                if (train) onSubmit(referenceOf(train));
+              }}
+            >
+              Allocate
+            </Button>
+          </Group>
+        </Stack>
+      )}
+    </Modal>
+  );
+}
+
 interface ContainerReturnModalProps {
   opened: boolean;
   onClose: () => void;

From b4f2ec1c75c32665fa89daaab3b1cb87125eb9af Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Fri, 14 Aug 2026 09:57:20 +0000
Subject: [PATCH 094/174] feat(train-scheduling): load returned empties onto an
 export train

Empties had no way onto a departure: the return record could name a train
but nothing seated it on a wagon. Export schedules now expose a loading
action that packs selected returns onto free wagons at one 40ft or two 20ft
each, enforced both in the picker and in the API (existing empties on the
schedule count against their wagon).

Adds container_size, train_schedule_id and wagon_sequence_no to
freight.empty_container_returns.
---
 .../3540000000000-EmptyReturnTrainLoad.ts     |  35 +++
 .../dto/import-operations.dto.ts              |  55 +++-
 .../empty-container-wagon.util.spec.ts        |  23 ++
 .../empty-container-wagon.util.ts             |  16 ++
 .../entities/empty-container-return.entity.ts |  11 +
 .../import-operations.controller.ts           |   9 +
 .../import-operations.service.ts              |  62 ++++-
 .../LoadEmptyContainersModal.tsx              | 249 ++++++++++++++++++
 .../emptyContainerLoad.util.spec.ts           |  60 +++++
 .../emptyContainerLoad.util.ts                |  54 ++++
 .../backoffice/src/constants/URLS.ts          |   2 +
 .../TrainScheduleV2DetailPage.tsx             |  22 ++
 .../pages/warehouses/ContainerReturnsPage.tsx |   5 +
 .../src/services/importOperations.service.ts  |  11 +
 .../backoffice/src/types/importOperations.ts  |  18 ++
 15 files changed, 630 insertions(+), 2 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3540000000000-EmptyReturnTrainLoad.ts
 create mode 100644 apps/edr-freight-api/src/modules/import-operations/empty-container-wagon.util.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/import-operations/empty-container-wagon.util.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/trainScheduling/LoadEmptyContainersModal.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/trainScheduling/emptyContainerLoad.util.spec.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/trainScheduling/emptyContainerLoad.util.ts

diff --git a/apps/edr-freight-api/src/migrations/3540000000000-EmptyReturnTrainLoad.ts b/apps/edr-freight-api/src/migrations/3540000000000-EmptyReturnTrainLoad.ts
new file mode 100644
index 000000000..55ef08262
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3540000000000-EmptyReturnTrainLoad.ts
@@ -0,0 +1,35 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Empty containers ride an export departure back to Djibouti, so a return now
+ * records which train schedule carries it and on which wagon slot. Size is
+ * captured too: the wagon rule is one 40ft OR two 20ft per wagon, which cannot
+ * be enforced without knowing the box size.
+ */
+export class EmptyReturnTrainLoad3540000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.empty_container_returns
+        ADD COLUMN IF NOT EXISTS container_size character varying(10),
+        ADD COLUMN IF NOT EXISTS train_schedule_id uuid,
+        ADD COLUMN IF NOT EXISTS wagon_sequence_no integer
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_empty_container_returns_train_schedule_id
+        ON freight.empty_container_returns (train_schedule_id)
+        WHERE train_schedule_id IS NOT NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      DROP INDEX IF EXISTS freight.idx_empty_container_returns_train_schedule_id
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.empty_container_returns
+        DROP COLUMN IF EXISTS container_size,
+        DROP COLUMN IF EXISTS train_schedule_id,
+        DROP COLUMN IF EXISTS wagon_sequence_no
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/import-operations/dto/import-operations.dto.ts b/apps/edr-freight-api/src/modules/import-operations/dto/import-operations.dto.ts
index b3ec979b4..9af97f1e8 100644
--- a/apps/edr-freight-api/src/modules/import-operations/dto/import-operations.dto.ts
+++ b/apps/edr-freight-api/src/modules/import-operations/dto/import-operations.dto.ts
@@ -1,5 +1,17 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { IsArray, IsDateString, IsIn, IsOptional, IsString, IsUUID } from 'class-validator';
+import { Type } from 'class-transformer';
+import {
+  ArrayNotEmpty,
+  IsArray,
+  IsDateString,
+  IsIn,
+  IsInt,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Min,
+  ValidateNested,
+} from 'class-validator';
 
 import { DJIBOUTI_INCIDENT_TYPES, type DjiboutiIncidentType } from '../entities/djibouti-incident.entity';
 import {
@@ -120,6 +132,9 @@ export class ImportOperationActionDto {
   notes?: string;
 }
 
+export const EMPTY_CONTAINER_SIZES = ['20', '40'] as const;
+export type EmptyContainerSize = (typeof EMPTY_CONTAINER_SIZES)[number];
+
 export class CreateEmptyContainerReturnDto {
   @ApiProperty()
   @IsString()
@@ -140,6 +155,11 @@ export class CreateEmptyContainerReturnDto {
   @IsDateString()
   returnDate?: string;
 
+  @ApiPropertyOptional({ enum: EMPTY_CONTAINER_SIZES })
+  @IsOptional()
+  @IsIn(EMPTY_CONTAINER_SIZES)
+  containerSize?: EmptyContainerSize;
+
   @ApiPropertyOptional()
   @IsOptional()
   @IsString()
@@ -176,6 +196,39 @@ export class CreateEmptyContainerReturnDto {
   returnedBy?: 'EDR' | 'CUSTOMER';
 }
 
+export class LoadEmptyContainerItemDto {
+  @ApiProperty({ format: 'uuid' })
+  @IsUUID()
+  id!: string;
+
+  @ApiProperty({ enum: EMPTY_CONTAINER_SIZES })
+  @IsIn(EMPTY_CONTAINER_SIZES)
+  containerSize!: EmptyContainerSize;
+
+  @ApiProperty()
+  @IsInt()
+  @Min(1)
+  wagonSequenceNo!: number;
+}
+
+export class LoadEmptyContainersOnTrainDto extends ImportOperationActionDto {
+  @ApiProperty({ format: 'uuid' })
+  @IsUUID()
+  trainScheduleId!: string;
+
+  @ApiPropertyOptional({ description: 'Run number shown on the return record.' })
+  @IsOptional()
+  @IsString()
+  trainNumber?: string;
+
+  @ApiProperty({ type: [LoadEmptyContainerItemDto] })
+  @IsArray()
+  @ArrayNotEmpty()
+  @ValidateNested({ each: true })
+  @Type(() => LoadEmptyContainerItemDto)
+  items!: LoadEmptyContainerItemDto[];
+}
+
 export class UpdateEmptyContainerReturnStatusDto extends ImportOperationActionDto {
   @ApiProperty({ enum: EMPTY_CONTAINER_RETURN_STATUSES })
   @IsIn(EMPTY_CONTAINER_RETURN_STATUSES)
diff --git a/apps/edr-freight-api/src/modules/import-operations/empty-container-wagon.util.spec.ts b/apps/edr-freight-api/src/modules/import-operations/empty-container-wagon.util.spec.ts
new file mode 100644
index 000000000..34fcece4c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/import-operations/empty-container-wagon.util.spec.ts
@@ -0,0 +1,23 @@
+import { assertWagonLoad } from './empty-container-wagon.util';
+
+describe('assertWagonLoad', () => {
+  it('accepts one 40ft or two 20ft per wagon', () => {
+    expect(() =>
+      assertWagonLoad(
+        new Map([
+          [1, ['40']],
+          [2, ['20', '20']],
+          [3, ['20']],
+        ]),
+      ),
+    ).not.toThrow();
+  });
+
+  it('rejects a 40ft sharing a wagon', () => {
+    expect(() => assertWagonLoad(new Map([[4, ['40', '20']]]))).toThrow(/Wagon 4/);
+  });
+
+  it('rejects three containers on a wagon', () => {
+    expect(() => assertWagonLoad(new Map([[5, ['20', '20', '20']]]))).toThrow(/Wagon 5/);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/import-operations/empty-container-wagon.util.ts b/apps/edr-freight-api/src/modules/import-operations/empty-container-wagon.util.ts
new file mode 100644
index 000000000..bc82db3ee
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/import-operations/empty-container-wagon.util.ts
@@ -0,0 +1,16 @@
+import { BadRequestException } from '@nestjs/common';
+
+/**
+ * A wagon carries ONE 40ft OR TWO 20ft empties — never a mix, never three.
+ * Throws on the first wagon that breaks the rule.
+ */
+export function assertWagonLoad(sizesByWagon: Map<number, string[]>): void {
+  for (const [wagon, sizes] of sizesByWagon) {
+    const has40 = sizes.some((size) => size === '40');
+    if ((has40 && sizes.length > 1) || sizes.length > 2) {
+      throw new BadRequestException(
+        `Wagon ${wagon} takes one 40ft or two 20ft containers — got ${sizes.join('ft + ')}ft`,
+      );
+    }
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/import-operations/entities/empty-container-return.entity.ts b/apps/edr-freight-api/src/modules/import-operations/entities/empty-container-return.entity.ts
index 2538a204b..263dd30d2 100644
--- a/apps/edr-freight-api/src/modules/import-operations/entities/empty-container-return.entity.ts
+++ b/apps/edr-freight-api/src/modules/import-operations/entities/empty-container-return.entity.ts
@@ -51,6 +51,17 @@ export class EmptyContainerReturn extends BaseEntity {
   @Column({ name: 'wagon_allocation_reference', type: 'varchar', length: 120, nullable: true })
   wagonAllocationReference?: string | null;
 
+  /** '20' or '40' — drives the one-40ft-or-two-20ft-per-wagon loading rule. */
+  @Column({ name: 'container_size', type: 'varchar', length: 10, nullable: true })
+  containerSize?: string | null;
+
+  /** Export departure carrying this empty back to Djibouti. */
+  @Column({ name: 'train_schedule_id', type: 'uuid', nullable: true })
+  trainScheduleId?: string | null;
+
+  @Column({ name: 'wagon_sequence_no', type: 'int', nullable: true })
+  wagonSequenceNo?: number | null;
+
   @Column({ name: 'performed_by', type: 'varchar', length: 120, nullable: true })
   performedBy?: string | null;
 
diff --git a/apps/edr-freight-api/src/modules/import-operations/import-operations.controller.ts b/apps/edr-freight-api/src/modules/import-operations/import-operations.controller.ts
index 15e5404a7..c631bef92 100644
--- a/apps/edr-freight-api/src/modules/import-operations/import-operations.controller.ts
+++ b/apps/edr-freight-api/src/modules/import-operations/import-operations.controller.ts
@@ -8,6 +8,7 @@ import {
   CreateDjiboutiIncidentDto,
   CreateEmptyContainerReturnDto,
   ImportOperationActionDto,
+  LoadEmptyContainersOnTrainDto,
   RecordDeclarationDto,
   UpdateEmptyContainerReturnStatusDto,
   UploadImportCustomsDocumentDto,
@@ -104,6 +105,14 @@ export class ImportOperationsController {
     return this.service.createEmptyReturn(dto);
   }
 
+  @Post('empty-container-returns/load-on-train')
+  @ApiOperation({
+    summary: 'Load returned empties onto an export train (1×40ft or 2×20ft per wagon)',
+  })
+  loadEmptyReturnsOnTrain(@Body() dto: LoadEmptyContainersOnTrainDto) {
+    return this.service.loadEmptyReturnsOnTrain(dto);
+  }
+
   @Post('empty-container-returns/:id/status')
   @ApiOperation({ summary: 'Batch 16: advance empty container return workflow' })
   updateEmptyReturnStatus(
diff --git a/apps/edr-freight-api/src/modules/import-operations/import-operations.service.ts b/apps/edr-freight-api/src/modules/import-operations/import-operations.service.ts
index bd40e2ab1..28eb4e44f 100644
--- a/apps/edr-freight-api/src/modules/import-operations/import-operations.service.ts
+++ b/apps/edr-freight-api/src/modules/import-operations/import-operations.service.ts
@@ -1,11 +1,12 @@
 import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
-import { Repository } from 'typeorm';
+import { In, Repository } from 'typeorm';
 
 import {
   CreateDjiboutiIncidentDto,
   CreateEmptyContainerReturnDto,
   ImportOperationActionDto,
+  LoadEmptyContainersOnTrainDto,
   RecordDeclarationDto,
   AssignCustomsRiskDto,
   UpdateEmptyContainerReturnStatusDto,
@@ -15,6 +16,7 @@ import {
   DjiboutiIncident,
   type DjiboutiIncidentType,
 } from './entities/djibouti-incident.entity';
+import { assertWagonLoad } from './empty-container-wagon.util';
 import { EmptyContainerReturn } from './entities/empty-container-return.entity';
 import {
   ImportCustomsFinalization,
@@ -156,6 +158,7 @@ export class ImportOperationsService {
         bookingId: dto.bookingId ?? null,
         customerId: dto.customerId ?? null,
         returnDate,
+        containerSize: dto.containerSize ?? null,
         facility: dto.facility ?? null,
         yard: dto.yard ?? null,
         zone: dto.zone ?? null,
@@ -170,6 +173,63 @@ export class ImportOperationsService {
     );
   }
 
+  /**
+   * Load returned empties onto an export departure. A wagon takes ONE 40ft or
+   * TWO 20ft — never a mix, never three. Empties already sitting on a wagon of
+   * the same schedule count against that wagon, so incremental loads cannot
+   * quietly double-book a slot.
+   *
+   * ponytail: does not check the wagon is free of cargo bookings — the loading
+   * UI picks only unallocated wagons from the schedule's plan. Cross-check here
+   * if empties ever get loaded from another client.
+   */
+  async loadEmptyReturnsOnTrain(dto: LoadEmptyContainersOnTrainDto) {
+    const ids = dto.items.map((item) => item.id);
+    const rows = await this.emptyReturns.find({ where: { id: In(ids) } });
+    const missing = ids.filter((id) => !rows.some((row) => row.id === id));
+    if (missing.length) {
+      throw new NotFoundException(`Empty container return(s) not found: ${missing.join(', ')}`);
+    }
+
+    const alreadyOnTrain = await this.emptyReturns.find({
+      where: { trainScheduleId: dto.trainScheduleId },
+    });
+    const byWagon = new Map<number, string[]>();
+    for (const row of alreadyOnTrain) {
+      if (row.wagonSequenceNo == null || ids.includes(row.id)) continue;
+      byWagon.set(row.wagonSequenceNo, [
+        ...(byWagon.get(row.wagonSequenceNo) ?? []),
+        row.containerSize ?? '40',
+      ]);
+    }
+    for (const item of dto.items) {
+      byWagon.set(item.wagonSequenceNo, [
+        ...(byWagon.get(item.wagonSequenceNo) ?? []),
+        item.containerSize,
+      ]);
+    }
+    assertWagonLoad(byWagon);
+
+    const changedAt = new Date().toISOString();
+    for (const item of dto.items) {
+      const row = rows.find((candidate) => candidate.id === item.id)!;
+      await this.emptyReturns.update(item.id, {
+        status: 'WAGON_ALLOCATED',
+        containerSize: item.containerSize,
+        trainScheduleId: dto.trainScheduleId,
+        wagonSequenceNo: item.wagonSequenceNo,
+        wagonAllocationReference: dto.trainNumber ?? dto.trainScheduleId,
+        performedBy: dto.performedBy ?? row.performedBy ?? null,
+        statusHistory: [
+          ...(row.statusHistory ?? []),
+          { status: 'WAGON_ALLOCATED' as const, changedAt, performedBy: dto.performedBy ?? null },
+        ],
+      });
+    }
+
+    return this.emptyReturns.find({ where: { trainScheduleId: dto.trainScheduleId } });
+  }
+
   async updateEmptyReturnStatus(id: string, dto: UpdateEmptyContainerReturnStatusDto) {
     const row = await this.emptyReturns.findOne({ where: { id } });
     if (!row) {
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/LoadEmptyContainersModal.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/LoadEmptyContainersModal.tsx
new file mode 100644
index 000000000..eadd18f85
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/LoadEmptyContainersModal.tsx
@@ -0,0 +1,249 @@
+import { useMemo, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  Alert,
+  Badge,
+  Button,
+  Checkbox,
+  Group,
+  Loader,
+  Modal,
+  SegmentedControl,
+  Stack,
+  Table,
+  Text,
+} from "@mantine/core";
+
+import { useToast } from "@/hooks/use-toast";
+import { importOperationsService } from "@/services/importOperations.service";
+import type {
+  EmptyContainerReturn,
+  EmptyContainerSize,
+} from "@/types/importOperations";
+import type { TrainScheduleDetail } from "@/types/trainScheduling";
+import { packEmptiesOntoWagons, wagonsNeeded } from "./emptyContainerLoad.util";
+
+/** Empties still on the ground — past these the box has already left the yard. */
+const LOADABLE_STATUSES = ["RETURNED", "ASSIGNED_STORAGE", "DOCUMENTATION_CLEARED"];
+
+interface LoadEmptyContainersModalProps {
+  opened: boolean;
+  onClose: () => void;
+  schedule: TrainScheduleDetail;
+}
+
+/**
+ * Loads returned empty containers onto an export departure. Wagons are filled
+ * one 40ft OR two 20ft each (see `packEmptiesOntoWagons`), drawing only on
+ * wagons of this train that carry no cargo booking and no empty already.
+ */
+export function LoadEmptyContainersModal({
+  opened,
+  onClose,
+  schedule,
+}: LoadEmptyContainersModalProps) {
+  const { toast } = useToast();
+  const qc = useQueryClient();
+  const [selected, setSelected] = useState<string[]>([]);
+  const [sizeOverrides, setSizeOverrides] = useState<Record<string, EmptyContainerSize>>({});
+
+  const returnsQuery = useQuery({
+    queryKey: ["empty-container-returns"],
+    queryFn: () => importOperationsService.listEmptyReturns(),
+    enabled: opened,
+  });
+
+  const returns = returnsQuery.data ?? [];
+  const loaded = useMemo(
+    () => returns.filter((ret) => ret.trainScheduleId === schedule.id),
+    [returns, schedule.id],
+  );
+  const available = useMemo(
+    () =>
+      returns.filter(
+        (ret) => !ret.trainScheduleId && LOADABLE_STATUSES.includes(ret.status),
+      ),
+    [returns],
+  );
+
+  const sizeOf = (ret: EmptyContainerReturn): EmptyContainerSize =>
+    sizeOverrides[ret.id] ?? (ret.containerSize === "20" ? "20" : "40");
+
+  // A wagon is up for grabs when no booking rides it and no empty sits on it.
+  const freeWagons = useMemo(() => {
+    const takenByEmpties = new Set(
+      loaded.map((ret) => ret.wagonSequenceNo).filter((no): no is number => no != null),
+    );
+    return (schedule.trainSet?.wagons ?? [])
+      .filter((wagon) => !wagon.allocations?.length && !takenByEmpties.has(wagon.sequenceNo))
+      .map((wagon) => wagon.sequenceNo)
+      .sort((a, b) => a - b);
+  }, [schedule.trainSet?.wagons, loaded]);
+
+  const picks = useMemo(
+    () =>
+      available
+        .filter((ret) => selected.includes(ret.id))
+        .map((ret) => ({ id: ret.id, containerSize: sizeOf(ret) })),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [available, selected, sizeOverrides],
+  );
+  const needed = wagonsNeeded(picks);
+  const { assignments, unplaced } = packEmptiesOntoWagons(picks, freeWagons);
+
+  const load = useMutation({
+    mutationFn: () =>
+      importOperationsService.loadEmptyContainersOnTrain({
+        trainScheduleId: schedule.id,
+        trainNumber: schedule.trainNumber ?? undefined,
+        items: assignments,
+      }),
+    onSuccess: () => {
+      toast({ title: `${assignments.length} empty container(s) loaded` });
+      qc.invalidateQueries({ queryKey: ["empty-container-returns"] });
+      qc.invalidateQueries({ queryKey: ["train-scheduling"] });
+      setSelected([]);
+      onClose();
+    },
+    onError: (error: any) => {
+      toast({
+        variant: "destructive",
+        title: "Failed to load empty containers",
+        description: error?.response?.data?.message || error?.message,
+      });
+    },
+  });
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      title="Load Empty Containers"
+      size="xl"
+    >
+      <Stack gap="md">
+        <Text size="sm" c="dimmed">
+          One 40ft or two 20ft containers per wagon. {freeWagons.length} free wagon
+          {freeWagons.length === 1 ? "" : "s"} on this train.
+        </Text>
+
+        {loaded.length > 0 ? (
+          <Alert color="gray" title={`${loaded.length} empty container(s) already loaded`}>
+            <Group gap="xs">
+              {loaded.map((ret) => (
+                <Badge key={ret.id} size="sm" variant="light">
+                  {ret.containerNumber} · wagon {ret.wagonSequenceNo ?? "—"}
+                </Badge>
+              ))}
+            </Group>
+          </Alert>
+        ) : null}
+
+        {returnsQuery.isLoading ? (
+          <Group justify="center" py="md">
+            <Loader size="sm" />
+          </Group>
+        ) : available.length === 0 ? (
+          <Alert color="gray">
+            No returned empty containers are waiting — record returns in Container Returns.
+          </Alert>
+        ) : (
+          <Table.ScrollContainer minWidth={700}>
+            <Table highlightOnHover>
+              <Table.Thead>
+                <Table.Tr>
+                  <Table.Th w={40} />
+                  <Table.Th>Container</Table.Th>
+                  <Table.Th>Size</Table.Th>
+                  <Table.Th>Facility</Table.Th>
+                  <Table.Th>Returned</Table.Th>
+                  <Table.Th>Status</Table.Th>
+                </Table.Tr>
+              </Table.Thead>
+              <Table.Tbody>
+                {available.map((ret) => {
+                  const checked = selected.includes(ret.id);
+                  return (
+                    <Table.Tr key={ret.id}>
+                      <Table.Td>
+                        <Checkbox
+                          checked={checked}
+                          onChange={(event) =>
+                            setSelected(
+                              event.currentTarget.checked
+                                ? [...selected, ret.id]
+                                : selected.filter((id) => id !== ret.id),
+                            )
+                          }
+                        />
+                      </Table.Td>
+                      <Table.Td>
+                        <Text fw={600} size="sm">
+                          {ret.containerNumber}
+                        </Text>
+                      </Table.Td>
+                      <Table.Td>
+                        {/* Legacy returns carry no size — the operator sets it here
+                            because the wagon rule cannot be applied without it. */}
+                        <SegmentedControl
+                          size="xs"
+                          value={sizeOf(ret)}
+                          onChange={(value) =>
+                            setSizeOverrides({
+                              ...sizeOverrides,
+                              [ret.id]: value as EmptyContainerSize,
+                            })
+                          }
+                          data={[
+                            { label: "20ft", value: "20" },
+                            { label: "40ft", value: "40" },
+                          ]}
+                        />
+                      </Table.Td>
+                      <Table.Td>{ret.facility ?? "—"}</Table.Td>
+                      <Table.Td>
+                        {ret.returnDate ? new Date(ret.returnDate).toLocaleDateString() : "—"}
+                      </Table.Td>
+                      <Table.Td>
+                        <Badge size="sm" variant="light">
+                          {ret.status}
+                        </Badge>
+                      </Table.Td>
+                    </Table.Tr>
+                  );
+                })}
+              </Table.Tbody>
+            </Table>
+          </Table.ScrollContainer>
+        )}
+
+        {unplaced.length > 0 ? (
+          <Alert color="red">
+            {needed} wagon(s) needed but only {freeWagons.length} free — unselect{" "}
+            {unplaced.length} container(s) or add wagons to the consist.
+          </Alert>
+        ) : picks.length > 0 ? (
+          <Text size="sm">
+            {picks.length} container(s) → wagons{" "}
+            {[...new Set(assignments.map((a) => a.wagonSequenceNo))].join(", ")}
+          </Text>
+        ) : null}
+
+        <Group justify="flex-end" gap="sm">
+          <Button variant="default" onClick={onClose} disabled={load.isPending}>
+            Cancel
+          </Button>
+          <Button
+            disabled={!picks.length || unplaced.length > 0}
+            loading={load.isPending}
+            onClick={() => load.mutate()}
+          >
+            Load {picks.length || ""} on train
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
+
+export default LoadEmptyContainersModal;
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/emptyContainerLoad.util.spec.ts b/apps/edr-freight-web/backoffice/src/components/trainScheduling/emptyContainerLoad.util.spec.ts
new file mode 100644
index 000000000..9094f3139
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/emptyContainerLoad.util.spec.ts
@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { packEmptiesOntoWagons, wagonsNeeded, type EmptyLoadPick } from './emptyContainerLoad.util';
+
+const pick = (id: string, containerSize: '20' | '40'): EmptyLoadPick => ({ id, containerSize });
+
+describe('emptyContainerLoad.util', () => {
+  it('gives each 40ft its own wagon', () => {
+    const { assignments, unplaced } = packEmptiesOntoWagons(
+      [pick('a', '40'), pick('b', '40')],
+      [1, 2, 3],
+    );
+    expect(unplaced).toEqual([]);
+    expect(assignments.map((a) => a.wagonSequenceNo)).toEqual([1, 2]);
+  });
+
+  it('pairs 20ft two to a wagon, last odd one alone', () => {
+    const { assignments } = packEmptiesOntoWagons(
+      [pick('a', '20'), pick('b', '20'), pick('c', '20')],
+      [4, 5],
+    );
+    expect(assignments.map((a) => [a.id, a.wagonSequenceNo])).toEqual([
+      ['a', 4],
+      ['b', 4],
+      ['c', 5],
+    ]);
+  });
+
+  it('never mixes a 40ft and a 20ft on one wagon', () => {
+    const { assignments } = packEmptiesOntoWagons(
+      [pick('a', '20'), pick('b', '40'), pick('c', '20')],
+      [1, 2],
+    );
+    const bySizeOnWagon = new Map<number, string[]>();
+    for (const a of assignments) {
+      bySizeOnWagon.set(a.wagonSequenceNo, [
+        ...(bySizeOnWagon.get(a.wagonSequenceNo) ?? []),
+        a.containerSize,
+      ]);
+    }
+    for (const sizes of bySizeOnWagon.values()) {
+      expect(sizes.includes('40') ? sizes.length : 0).toBeLessThan(2);
+      expect(sizes.length).toBeLessThanOrEqual(2);
+    }
+  });
+
+  it('reports picks that ran out of wagons instead of dropping them', () => {
+    const { assignments, unplaced } = packEmptiesOntoWagons(
+      [pick('a', '40'), pick('b', '40'), pick('c', '20'), pick('d', '20')],
+      [7],
+    );
+    expect(assignments).toHaveLength(1);
+    expect(unplaced.map((p) => p.id)).toEqual(['b', 'c', 'd']);
+  });
+
+  it('counts wagons needed', () => {
+    expect(wagonsNeeded([])).toBe(0);
+    expect(wagonsNeeded([pick('a', '40'), pick('b', '20'), pick('c', '20')])).toBe(2);
+    expect(wagonsNeeded([pick('a', '20')])).toBe(1);
+  });
+});
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/emptyContainerLoad.util.ts b/apps/edr-freight-web/backoffice/src/components/trainScheduling/emptyContainerLoad.util.ts
new file mode 100644
index 000000000..588fe7649
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/emptyContainerLoad.util.ts
@@ -0,0 +1,54 @@
+import type { EmptyContainerSize } from "@/types/importOperations";
+
+export interface EmptyLoadPick {
+  id: string;
+  containerSize: EmptyContainerSize;
+}
+
+export interface EmptyLoadAssignment extends EmptyLoadPick {
+  wagonSequenceNo: number;
+}
+
+/**
+ * Fill wagons with the picked empties: a wagon takes ONE 40ft or TWO 20ft,
+ * never a mix. 40ft boxes are seated first so a half-filled 20ft wagon can
+ * never block them, and the 20s pair up behind them.
+ *
+ * `freeWagons` is the caller's ordered list of wagon sequence numbers with no
+ * cargo allocation. Returns the assignments that fit plus the picks that had
+ * no wagon left — the caller surfaces the shortfall instead of silently
+ * dropping boxes.
+ */
+export function packEmptiesOntoWagons(
+  picks: EmptyLoadPick[],
+  freeWagons: number[],
+): { assignments: EmptyLoadAssignment[]; unplaced: EmptyLoadPick[] } {
+  const forty = picks.filter((pick) => pick.containerSize === "40");
+  const twenty = picks.filter((pick) => pick.containerSize === "20");
+
+  const assignments: EmptyLoadAssignment[] = [];
+  const unplaced: EmptyLoadPick[] = [];
+  const wagons = [...freeWagons];
+
+  for (const pick of forty) {
+    const wagon = wagons.shift();
+    if (wagon == null) unplaced.push(pick);
+    else assignments.push({ ...pick, wagonSequenceNo: wagon });
+  }
+
+  for (let index = 0; index < twenty.length; index += 2) {
+    const pair = twenty.slice(index, index + 2);
+    const wagon = wagons.shift();
+    if (wagon == null) unplaced.push(...pair);
+    else assignments.push(...pair.map((pick) => ({ ...pick, wagonSequenceNo: wagon })));
+  }
+
+  return { assignments, unplaced };
+}
+
+/** Wagons the picks consume, whether or not enough are free. */
+export function wagonsNeeded(picks: EmptyLoadPick[]): number {
+  const forty = picks.filter((pick) => pick.containerSize === "40").length;
+  const twenty = picks.length - forty;
+  return forty + Math.ceil(twenty / 2);
+}
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index fd115e97d..2a9f40ebd 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -733,6 +733,8 @@ export const URL_CONSTANTS = {
     EMPTY_CONTAINER_RETURNS: "/import-operations/empty-container-returns",
     EMPTY_CONTAINER_RETURN_STATUS: (id: string) =>
       `/import-operations/empty-container-returns/${id}/status`,
+    EMPTY_CONTAINER_RETURNS_LOAD_ON_TRAIN:
+      "/import-operations/empty-container-returns/load-on-train",
   },
 
   VEHICLES: {
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
index acfc3c375..ef9171d0d 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
@@ -57,6 +57,7 @@ import { ContainerPlacementGrid } from "@/components/trainScheduling/ContainerPl
 import { FleetAvailabilitySummary } from "@/components/trainScheduling/FleetAvailabilitySummary";
 import { IntercityRideAlongPanel } from "@/components/trainScheduling/IntercityRideAlongPanel";
 import { LegCapacityPanel } from "@/components/trainScheduling/LegCapacityPanel";
+import { LoadEmptyContainersModal } from "@/components/trainScheduling/LoadEmptyContainersModal";
 import MergeScheduleTrainModal from "@/components/trainScheduling/MergeScheduleTrainModal";
 import ScheduleHistoryPanel from "@/components/trainScheduling/ScheduleHistoryPanel";
 // import { ImportLoadingConfirmationPanel } from "@/components/trainScheduling/ImportLoadingConfirmationPanel";
@@ -126,6 +127,7 @@ export default function TrainScheduleV2DetailPage() {
   const [dispatchConfirmOpen, setDispatchConfirmOpen] = useState(false);
   const [switchTarget, setSwitchTarget] = useState<EligibleContainerBooking | null>(null);
   const [visualization3DOpen, setVisualization3DOpen] = useState(false);
+  const [loadEmptiesOpen, setLoadEmptiesOpen] = useState(false);
   const autoPreviewedRef = useRef(false);
 
   const detailQuery = useQuery(
@@ -967,6 +969,20 @@ export default function TrainScheduleV2DetailPage() {
                 Merge
               </Button>
             ) : null}
+            {/* Empties ride an export departure back to Djibouti — offered only
+                while the train can still take load. */}
+            {schedule.direction === "EXPORT" &&
+            ["DRAFT", "SCHEDULED"].includes(schedule.status) ? (
+              <Button
+                variant="light"
+                color="edr-green"
+                size="compact-sm"
+                leftSection={<ContainerIcon size={14} />}
+                onClick={() => setLoadEmptiesOpen(true)}
+              >
+                Load Empty Container
+              </Button>
+            ) : null}
             {(schedule.trainSet?.wagons?.length ?? 0) > 0 ? (
               <Button
                 variant="gradient"
@@ -1365,6 +1381,12 @@ export default function TrainScheduleV2DetailPage() {
         onSaved={() => void detailQuery.refetch()}
       />
 
+      <LoadEmptyContainersModal
+        opened={loadEmptiesOpen}
+        onClose={() => setLoadEmptiesOpen(false)}
+        schedule={schedule}
+      />
+
       <MergeScheduleTrainModal
         scheduleId={scheduleId ?? null}
         currentTrainId={schedule.trainSet?.trainId ?? null}
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
index 11bf69334..0510ca997 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
@@ -36,6 +36,7 @@ import { importOperationsService } from "@/services/importOperations.service";
 import type {
   EmptyContainerReturn,
   EmptyContainerReturnStatus,
+  EmptyContainerSize,
 } from "@/types/importOperations";
 import type { TrainScheduleListItem } from "@/types/trainScheduling";
 import { formatDateTime } from "@/lib/format";
@@ -267,6 +268,7 @@ export default function ContainerReturnsPage() {
         returnType: "EDR" | "CUSTOMER";
         containers: Array<{
           containerNumber: string;
+          containerSize?: EmptyContainerSize;
           returnDate: string;
           warehouse: string;
           condition?: string;
@@ -279,6 +281,7 @@ export default function ContainerReturnsPage() {
         for (const container of truck.containers) {
           const result = await importOperationsService.createEmptyReturn({
             containerNumber: container.containerNumber,
+            containerSize: container.containerSize,
             returnDate: new Date(container.returnDate).toISOString(),
             bookingId: truck.bookingId,
             customerId: truck.customerId ?? undefined,
@@ -844,6 +847,8 @@ function ContainerReturnModal({ opened, onClose, group, onSubmit, loading }: Con
       .filter((c) => selectedContainers.includes(c.key))
       .map((c) => ({
         containerNumber: c.containerNumber,
+        // Inventory records "20ft"/"40ft"; the wagon rule only needs the number.
+        containerSize: c.size?.includes("40") ? ("40" as const) : c.size ? ("20" as const) : undefined,
         returnDate,
         warehouse: selectedWarehouse?.name || warehouse,
         condition: condition || undefined,
diff --git a/apps/edr-freight-web/backoffice/src/services/importOperations.service.ts b/apps/edr-freight-web/backoffice/src/services/importOperations.service.ts
index 1025cd417..308388379 100644
--- a/apps/edr-freight-web/backoffice/src/services/importOperations.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/importOperations.service.ts
@@ -5,6 +5,7 @@ import type {
   AssignCustomsRiskPayload,
   CreateDjiboutiIncidentPayload,
   CreateEmptyContainerReturnPayload,
+  LoadEmptyContainersOnTrainPayload,
   DjiboutiIncident,
   EmptyContainerReturn,
   ImportCustomsFinalization,
@@ -123,6 +124,16 @@ export const importOperationsService = {
     return unwrap(response.data);
   },
 
+  loadEmptyContainersOnTrain: async (
+    payload: LoadEmptyContainersOnTrainPayload,
+  ): Promise<EmptyContainerReturn[]> => {
+    const response = await client.post<EmptyContainerReturn[]>(
+      URL_CONSTANTS.IMPORT_OPERATIONS.EMPTY_CONTAINER_RETURNS_LOAD_ON_TRAIN,
+      payload,
+    );
+    return unwrap(response.data);
+  },
+
   updateEmptyReturnStatus: async (
     id: string,
     payload: UpdateEmptyContainerReturnStatusPayload,
diff --git a/apps/edr-freight-web/backoffice/src/types/importOperations.ts b/apps/edr-freight-web/backoffice/src/types/importOperations.ts
index ff5c1901f..ee8314d01 100644
--- a/apps/edr-freight-web/backoffice/src/types/importOperations.ts
+++ b/apps/edr-freight-web/backoffice/src/types/importOperations.ts
@@ -101,6 +101,11 @@ export interface EmptyContainerReturn {
   handoverNote: string | null;
   status: EmptyContainerReturnStatus;
   wagonAllocationReference: string | null;
+  /** '20' or '40' — one 40ft OR two 20ft ride a wagon. */
+  containerSize: EmptyContainerSize | null;
+  /** Export departure this empty is loaded on, once allocated. */
+  trainScheduleId: string | null;
+  wagonSequenceNo: number | null;
   performedBy: string | null;
   returnedBy: 'EDR' | 'CUSTOMER' | null;
   statusHistory: Array<{
@@ -110,8 +115,11 @@ export interface EmptyContainerReturn {
   }>;
 }
 
+export type EmptyContainerSize = '20' | '40';
+
 export interface CreateEmptyContainerReturnPayload {
   containerNumber: string;
+  containerSize?: EmptyContainerSize;
   bookingId?: string;
   customerId?: string;
   returnDate?: string;
@@ -124,6 +132,16 @@ export interface CreateEmptyContainerReturnPayload {
   returnedBy?: 'EDR' | 'CUSTOMER';
 }
 
+export interface LoadEmptyContainersOnTrainPayload extends ImportOperationActionPayload {
+  trainScheduleId: string;
+  trainNumber?: string;
+  items: Array<{
+    id: string;
+    containerSize: EmptyContainerSize;
+    wagonSequenceNo: number;
+  }>;
+}
+
 export interface UpdateEmptyContainerReturnStatusPayload extends ImportOperationActionPayload {
   status: EmptyContainerReturnStatus;
   wagonAllocationReference?: string;

From 1adc19baef205a42e4ea16712cc672dd1ca771aa Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Fri, 14 Aug 2026 11:30:25 +0000
Subject: [PATCH 095/174] feat(train-scheduling): show loaded empties on the
 marshalling document
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Empty containers loaded onto an export departure carry no booking and no
wagon allocation, so their wagons printed as EMPTY — no cargo allocated —
staff checking the paper against the consist found boxes the list denied.
Those wagons now print the container numbers with cargo type EMPTY
CONTAINER, count toward the 40ft/20ft tallies, and get their own summary
tile; only genuinely bare wagons keep the empty wording.
---
 .../services/train-scheduling.service.spec.ts | 30 ++++++++++
 .../services/train-scheduling.service.ts      | 56 ++++++++++++++++++-
 2 files changed, 84 insertions(+), 2 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
index 10ebaf6ee..43a169058 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
@@ -1132,6 +1132,36 @@ describe('TrainSchedulingService', () => {
       expect(html).toContain('2 (1 empty)');
     });
 
+    it('lists loaded empty containers by number and states they are empty', () => {
+      const schedule = {
+        id: 'schedule-1',
+        trainNumber: '8301',
+        direction: 'EXPORT',
+        trainSet: {
+          wagons: [makeWagon(1, 'W-001', []), makeWagon(2, 'W-002', []), makeWagon(3, 'W-003', [])],
+        },
+        scheduleBookings: [],
+      };
+
+      const html = (service as never as {
+        buildExportLoadListHtml: (s: unknown, o?: unknown) => string;
+      }).buildExportLoadListHtml(schedule, {
+        emptyContainers: [
+          { containerNumber: 'CMU9876543', containerSize: '40', wagonSequenceNo: 1 },
+          { containerNumber: 'TEMU1112223', containerSize: '20', wagonSequenceNo: 2 },
+          { containerNumber: 'TEMU4445556', containerSize: '20', wagonSequenceNo: 2 },
+        ],
+      });
+
+      expect(html).toContain('CMU9876543');
+      expect(html).toContain('TEMU1112223, TEMU4445556');
+      expect(html.match(/EMPTY CONTAINER/g)).toHaveLength(2);
+      // Wagon 3 carries nothing at all, so it keeps the bare-wagon wording.
+      expect(html.match(/EMPTY — no cargo allocated/g)).toHaveLength(1);
+      expect(html).toContain('3 (1 empty)');
+      expect(html).toContain('<span>Empty containers</span><strong>3</strong>');
+    });
+
     it('renders wagons in consist order regardless of the order the relation returns', () => {
       const schedule = {
         id: 'schedule-1',
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index 12fb3dec6..780d65305 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -91,6 +91,7 @@ import {
   ImportDjiboutiOperation,
   type ImportDjiboutiDocumentType,
 } from '../entities/import-djibouti-operation.entity';
+import { EmptyContainerReturn } from '../../import-operations/entities/empty-container-return.entity';
 import {
   ImportDjiboutiActionDto,
   UploadImportDjiboutiDocumentDto,
@@ -3106,6 +3107,7 @@ export class TrainSchedulingService {
     }
 
     const html = this.buildExportLoadListHtml(schedule, {
+      emptyContainers: await this.loadedEmptyContainers(scheduleId),
       logoImageUrl: await this.logoSettings.getLogoImageUrl(),
     });
     // Styled table-aware fallback (marshalling grid) — see importLoadListDocument.
@@ -3179,6 +3181,7 @@ export class TrainSchedulingService {
       positionLabel,
       wagons,
       unassignedBookings,
+      emptyContainers: await this.loadedEmptyContainers(scheduleId),
       logoImageUrl: await this.logoSettings.getLogoImageUrl(),
     });
     // Styled table-aware fallback (marshalling grid) — see importLoadListDocument.
@@ -3216,6 +3219,18 @@ export class TrainSchedulingService {
     return null;
   }
 
+  /**
+   * Empty containers riding this departure back to Djibouti. They carry no
+   * booking and no wagon allocation, so the marshalling document would show
+   * their wagons as bare — staff checking the paper against the train would
+   * find boxes that the list denies are there.
+   */
+  private loadedEmptyContainers(scheduleId: string): Promise<EmptyContainerReturn[]> {
+    return this.dataSource
+      .getRepository(EmptyContainerReturn)
+      .find({ where: { trainScheduleId: scheduleId } });
+  }
+
   private buildExportLoadListHtml(
     schedule: TrainSchedule,
     opts?: {
@@ -3223,6 +3238,7 @@ export class TrainSchedulingService {
       positionLabel?: string;
       wagons?: TrainSetWagon[];
       unassignedBookings?: Booking[];
+      emptyContainers?: EmptyContainerReturn[];
       logoImageUrl?: string | null;
     },
   ): string {
@@ -3241,6 +3257,16 @@ export class TrainSchedulingService {
     const wagons = [...(opts?.wagons ?? schedule.trainSet?.wagons ?? [])].sort(
       (a, b) => Number(a.sequenceNo ?? 0) - Number(b.sequenceNo ?? 0),
     );
+    // Empties sit on wagons that carry no booking allocation, keyed by the wagon
+    // slot recorded when they were loaded.
+    const emptiesByWagon = new Map<number, EmptyContainerReturn[]>();
+    for (const empty of opts?.emptyContainers ?? []) {
+      if (empty.wagonSequenceNo == null) continue;
+      emptiesByWagon.set(empty.wagonSequenceNo, [
+        ...(emptiesByWagon.get(empty.wagonSequenceNo) ?? []),
+        empty,
+      ]);
+    }
     const rows = wagons
       .flatMap((wagon) => {
         // Wagon identity is the same on every row the wagon produces, loaded or not.
@@ -3255,6 +3281,21 @@ export class TrainSchedulingService {
         // check this document against the physical train — a wagon with no row
         // reads as a wagon that is not there, and the count stops matching.
         if (allocations.length === 0) {
+          const empties = emptiesByWagon.get(Number(wagon.sequenceNo)) ?? [];
+          // Empty boxes returning to Djibouti: numbers listed like any other
+          // container, state spelled out so nobody reads them as laden.
+          if (empties.length) {
+            return [
+              `<tr>
+            ${wagonCells}
+            <td>EMPTY CONTAINER</td>
+            <td>-</td>
+            <td>${esc(empties.map((empty) => empty.containerNumber).filter(Boolean).join(', '))}</td>
+            <td>-</td>
+            <td>-</td>
+          </tr>`,
+            ];
+          }
           return [
             `<tr class="empty">
             ${wagonCells}
@@ -3305,14 +3346,19 @@ export class TrainSchedulingService {
           })
           .join('')
       : '';
-    const emptyWagons = wagons.filter((wagon) => (wagon.allocations ?? []).length === 0).length;
+    const emptyWagons = wagons.filter(
+      (wagon) =>
+        (wagon.allocations ?? []).length === 0 &&
+        !emptiesByWagon.get(Number(wagon.sequenceNo))?.length,
+    ).length;
     const totalWeight = wagons.reduce(
       (sum, wagon) =>
         sum + (wagon.allocations ?? []).reduce((wagonSum, allocation) => wagonSum + Number(allocation.allocatedWeightTons || 0), 0),
       0,
     );
 
-    // Container count summary (40ft, 20ft)
+    // Container count summary (40ft, 20ft) — empties returning to Djibouti are
+    // physically on the train, so they count, and are called out on their own tile.
     let count40ft = 0, count20ft = 0;
     wagons.forEach((wagon) => {
       (wagon.allocations ?? []).forEach((allocation) => {
@@ -3323,6 +3369,11 @@ export class TrainSchedulingService {
         });
       });
     });
+    const emptyContainers = [...emptiesByWagon.values()].flat();
+    for (const empty of emptyContainers) {
+      if (empty.containerSize?.includes('20')) count20ft++;
+      else count40ft++;
+    }
 
     return `<!doctype html>
 <html>
@@ -3378,6 +3429,7 @@ export class TrainSchedulingService {
     <div class="tile"><span>Containers 40ft</span><strong>${esc(count40ft)}</strong></div>
     <div class="tile"><span>Containers 20ft</span><strong>${esc(count20ft)}</strong></div>
     <div class="tile"><span>Total containers</span><strong>${esc(count40ft + count20ft)}</strong></div>
+    ${emptyContainers.length ? `<div class="tile"><span>Empty containers</span><strong>${esc(emptyContainers.length)}</strong></div>` : ''}
     <div class="tile"><span>Prepared person</span><strong>${esc(schedule.preparedByUserId)}</strong></div>
     <div class="tile"><span>Check person</span><strong>${esc(schedule.checkedByUserId)}</strong></div>
     <div class="tile"><span>Wagons</span><strong>${esc(wagons.length)}${emptyWagons ? ` (${emptyWagons} empty)` : ''}</strong></div>

From 4a4d3077d7f880a95c72f6f90a4dbccb17382c84 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Fri, 14 Aug 2026 13:18:46 +0000
Subject: [PATCH 096/174] feat: Stripe-style filter bar for freight backoffice
 (pilot: contracts)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the ad-hoc filter controls with a URL-linkable pill filter bar:
each filter is a pill that opens a type-aware popover (text/enum/date/
number/boolean, each with the right operator set), overflow filters live
behind a searchable "More filters" menu, sorting is a separate control,
and filter state round-trips through the URL query string (shareable,
back/forward-safe, backward compatible with existing ?statuses=A,B links).

Frontend (apps/edr-freight-web/backoffice/src/components/filters/):
- FilterDef schema + a pure url.ts codec (parse/serialize/toApiParams),
  with a 24-case round-trip + malformed-input test suite
- useFilters hook driving react-query params straight from useSearchParams,
  debounced search, saved views in localStorage (@mantine/hooks
  useLocalStorage), page-reset-on-filter-change baked into one
  setSearchParams call instead of a separate effect
- FilterBar/FilterPill/OperatorSelect/MoreFiltersMenu/SortControl +
  per-type popover bodies (Mantine)
- ContractRequestsPage migrated end to end as the pilot

Backend (apps/edr-freight-api):
- pagination.util: applySort() — whitelisted sortBy resolved against a
  per-module column map (never interpolated), with a mandatory `id ASC`
  tiebreaker so paginating a non-unique sort can't drop/duplicate rows
- facets.util: computeFacets() — one GROUP BY per enum column, each
  omitting its own predicate, so picking a value doesn't hide its siblings
- contracts/bookings: list-summary now returns real filter-scoped facet
  counts (contracts' getStatusCounts was unfiltered/global; superseded)
- deleted drivers/vehicles findAllWithFilters — dead code that
  interpolated an unwhitelisted sortBy straight into orderBy()
- migration: missing bookings(status)/wagons(status) indexes +
  (created_at DESC, id ASC) partials on the hot list tables

UI polish pass: inactive pill uses the opaque "default" variant instead
of a faint tinted outline, active pill uses "light" not "filled", larger
X hit target, applied filters sort first, sort control separated behind
a divider on the right and wraps independently from the filter row,
popover option rows are fully clickable (count moved inside the native
label) with bigger hit area and font, fixed a real date-filter bug where
the calendar's own portal falsely registered as an "outside click" and
closed the popover, and fixed a timezone bug where bare YYYY-MM-DD
strings were parsed as UTC instead of local time (shifts a day for EAT).

Not in this commit: rollout to the other ~59 list pages, the Ethiopian-
calendar DateBody branch, and the Family-B (client-side) bridge mode —
tracked in the filter-bar plan.
---
 .../src/common/dto/pagination-query.dto.ts    |  12 +
 .../src/common/utils/facets.util.ts           |  48 +++
 .../src/common/utils/pagination.util.spec.ts  |  76 ++++
 .../src/common/utils/pagination.util.ts       |  29 ++
 .../3540000000000-FilterableListIndexes.ts    |  56 +++
 .../modules/bookings/bookings.repository.ts   |  54 ++-
 .../src/modules/bookings/bookings.service.ts  |   5 +-
 .../bookings/dto/booking-list-summary.dto.ts  |  15 +
 .../modules/contracts/contracts.repository.ts |  49 ++-
 .../modules/contracts/contracts.service.ts    |  12 +-
 .../dto/contract-list-summary.dto.ts          |  18 +
 .../src/modules/drivers/drivers.repository.ts |  46 ---
 .../modules/vehicles/vehicles.repository.ts   |  46 ---
 .../src/components/filters/FilterBar.tsx      | 121 ++++++
 .../src/components/filters/FilterPill.tsx     |  88 +++++
 .../components/filters/MoreFiltersMenu.tsx    |  82 +++++
 .../src/components/filters/OperatorSelect.tsx |  25 ++
 .../src/components/filters/SavedViews.tsx     | 107 ++++++
 .../src/components/filters/SortControl.tsx    |  40 ++
 .../components/filters/bodies/BooleanBody.tsx |  32 ++
 .../components/filters/bodies/DateBody.tsx    |  87 +++++
 .../components/filters/bodies/EnumBody.tsx    | 128 +++++++
 .../components/filters/bodies/NumberBody.tsx  |  39 ++
 .../components/filters/bodies/TextBody.tsx    |  39 ++
 .../src/components/filters/dates.ts           |  31 ++
 .../src/components/filters/index.ts           |  10 +
 .../src/components/filters/types.ts           | 101 +++++
 .../src/components/filters/url.test.ts        | 170 +++++++++
 .../backoffice/src/components/filters/url.ts  | 117 ++++++
 .../src/components/filters/useFilters.ts      | 219 +++++++++++
 .../pages/contracts/ContractRequestsPage.tsx  | 346 +++++-------------
 .../src/services/contracts.service.ts         |   7 +
 32 files changed, 1879 insertions(+), 376 deletions(-)
 create mode 100644 apps/edr-freight-api/src/common/utils/facets.util.ts
 create mode 100644 apps/edr-freight-api/src/common/utils/pagination.util.spec.ts
 create mode 100644 apps/edr-freight-api/src/migrations/3540000000000-FilterableListIndexes.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/MoreFiltersMenu.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/OperatorSelect.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/SavedViews.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/SortControl.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/bodies/BooleanBody.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/bodies/DateBody.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/bodies/EnumBody.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/bodies/NumberBody.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/bodies/TextBody.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/dates.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/index.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/types.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/url.test.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/url.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/useFilters.ts

diff --git a/apps/edr-freight-api/src/common/dto/pagination-query.dto.ts b/apps/edr-freight-api/src/common/dto/pagination-query.dto.ts
index 997ced76d..e705b019d 100644
--- a/apps/edr-freight-api/src/common/dto/pagination-query.dto.ts
+++ b/apps/edr-freight-api/src/common/dto/pagination-query.dto.ts
@@ -41,4 +41,16 @@ export class PaginationQueryDto {
   @Transform(({ value }) => String(value).toUpperCase())
   @IsIn(['ASC', 'DESC'])
   sortOrder?: 'ASC' | 'DESC';
+
+  /**
+   * Column to sort by, as a public field name (not a raw SQL column). The
+   * actual whitelist lives in `applySort`'s `sortable` map at each call site,
+   * not here — a per-DTO `@IsIn` is opt-in and has been forgotten before.
+   * An unrecognized value falls back silently rather than 400ing, so a stale
+   * bookmark or shared link never breaks.
+   */
+  @ApiPropertyOptional({ description: 'Public field name; unknown values fall back to the endpoint default.' })
+  @IsOptional()
+  @Transform(({ value }) => (typeof value === 'string' && value.trim() ? value.trim() : undefined))
+  sortBy?: string;
 }
diff --git a/apps/edr-freight-api/src/common/utils/facets.util.ts b/apps/edr-freight-api/src/common/utils/facets.util.ts
new file mode 100644
index 000000000..bc80c4b93
--- /dev/null
+++ b/apps/edr-freight-api/src/common/utils/facets.util.ts
@@ -0,0 +1,48 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+export interface FacetBucket {
+  value: string;
+  count: number;
+}
+
+/**
+ * One `GROUP BY` query per faceted column, each with every OTHER active
+ * filter applied but its OWN predicate omitted. That omission is the point:
+ * with `status=SUBMITTED` selected, the status facet still reports
+ * `APPROVED: 8` so the user can switch, while the freightType facet reflects
+ * only the SUBMITTED-scoped set. Omit `search` from nothing — it's a scope,
+ * not a pill, and stays applied in every facet.
+ *
+ * Capped at 50 buckets per column — FK-id facets (warehouseId, yardId) can
+ * have real cardinality; beyond 50 the frontend should fall back to a
+ * typeahead instead of a checkbox list. Never facet a column whose popover
+ * would need its own search box (references, plate numbers, free text).
+ *
+ * @param base          builds a FRESH query builder (soft-delete guard only,
+ *                       no filters) — called once per facet column.
+ * @param applyFilters  applies every filter to `qb`, using `omit` to skip
+ *                       one column's own predicate.
+ * @param columns       facet key -> "alias.column" SQL reference.
+ */
+export async function computeFacets<T extends ObjectLiteral>(
+  base: () => SelectQueryBuilder<T>,
+  applyFilters: (qb: SelectQueryBuilder<T>, omit?: string) => void,
+  columns: Record<string, string>,
+): Promise<Record<string, FacetBucket[]>> {
+  const entries = await Promise.all(
+    Object.entries(columns).map(async ([key, column]) => {
+      const qb = base();
+      applyFilters(qb, key);
+      const rows = await qb
+        .select(column, 'value')
+        .addSelect('COUNT(*)::int', 'count')
+        .andWhere(`${column} IS NOT NULL`)
+        .groupBy(column)
+        .orderBy('count', 'DESC')
+        .limit(50)
+        .getRawMany<{ value: string; count: number }>();
+      return [key, rows.map((r) => ({ value: String(r.value), count: Number(r.count) }))] as const;
+    }),
+  );
+  return Object.fromEntries(entries);
+}
diff --git a/apps/edr-freight-api/src/common/utils/pagination.util.spec.ts b/apps/edr-freight-api/src/common/utils/pagination.util.spec.ts
new file mode 100644
index 000000000..05bfe7585
--- /dev/null
+++ b/apps/edr-freight-api/src/common/utils/pagination.util.spec.ts
@@ -0,0 +1,76 @@
+import { SelectQueryBuilder } from 'typeorm';
+import { applySort, buildPaginationMeta, normalizePagination } from './pagination.util';
+
+/** Minimal fake — just enough of the SelectQueryBuilder chain applySort touches. */
+function fakeQb() {
+  const calls: Array<{ method: string; args: unknown[] }> = [];
+  const qb = {
+    alias: 'contract',
+    orderBy(...args: unknown[]) {
+      calls.push({ method: 'orderBy', args });
+      return qb;
+    },
+    addOrderBy(...args: unknown[]) {
+      calls.push({ method: 'addOrderBy', args });
+      return qb;
+    },
+  };
+  return { qb: qb as unknown as SelectQueryBuilder<any>, calls };
+}
+
+const SORTABLE = {
+  createdAt: 'contract.createdAt',
+  contractValidUntil: 'contract.contractValidUntil',
+};
+
+describe('applySort', () => {
+  it('resolves a whitelisted sortBy to its column', () => {
+    const { qb, calls } = fakeQb();
+    applySort(qb, { sortBy: 'contractValidUntil', sortOrder: 'ASC' }, SORTABLE, 'createdAt');
+    expect(calls[0]).toEqual({
+      method: 'orderBy',
+      args: ['contract.contractValidUntil', 'ASC'],
+    });
+  });
+
+  it('falls back to the default column for an unknown sortBy instead of throwing', () => {
+    const { qb, calls } = fakeQb();
+    // A stale bookmark or shared link naming a removed/renamed column must
+    // never 400 — it should silently behave as if sortBy were absent.
+    expect(() =>
+      applySort(qb, { sortBy: "id; DROP TABLE contracts; --" }, SORTABLE, 'createdAt'),
+    ).not.toThrow();
+    expect(calls[0]).toEqual({ method: 'orderBy', args: ['contract.createdAt', 'DESC'] });
+  });
+
+  it('defaults sortOrder to DESC when absent or not ASC', () => {
+    const { qb, calls } = fakeQb();
+    applySort(qb, {}, SORTABLE, 'createdAt');
+    expect(calls[0]).toEqual({ method: 'orderBy', args: ['contract.createdAt', 'DESC'] });
+  });
+
+  it('always appends an id ASC tiebreaker', () => {
+    const { qb, calls } = fakeQb();
+    applySort(qb, { sortBy: 'createdAt' }, SORTABLE, 'createdAt');
+    expect(calls[1]).toEqual({ method: 'addOrderBy', args: ['contract.id', 'ASC'] });
+  });
+});
+
+describe('normalizePagination / buildPaginationMeta', () => {
+  it('clamps page to >= 1 and pageSize to the configured max', () => {
+    const p = normalizePagination({ page: 0, pageSize: 999 }, { maxPageSize: 100 });
+    expect(p).toEqual({ page: 1, pageSize: 100, skip: 0, take: 100 });
+  });
+
+  it('computes hasNextPage/hasPreviousPage from total', () => {
+    const meta = buildPaginationMeta(45, 2, 20);
+    expect(meta).toEqual({
+      page: 2,
+      pageSize: 20,
+      total: 45,
+      totalPages: 3,
+      hasNextPage: true,
+      hasPreviousPage: true,
+    });
+  });
+});
diff --git a/apps/edr-freight-api/src/common/utils/pagination.util.ts b/apps/edr-freight-api/src/common/utils/pagination.util.ts
index 310b2da6d..ca4ed35a1 100644
--- a/apps/edr-freight-api/src/common/utils/pagination.util.ts
+++ b/apps/edr-freight-api/src/common/utils/pagination.util.ts
@@ -83,3 +83,32 @@ export function paginateArray<T>(
     meta: buildPaginationMeta(rows.length, page, pageSize),
   };
 }
+
+/**
+ * Apply `ORDER BY` from a query DTO's `sortBy`/`sortOrder`, resolved against a
+ * whitelist — never interpolate `sortBy` into a query builder directly, it is
+ * unvalidated user input and an unwhitelisted `orderBy(\`alias.${sortBy}\`)`
+ * is a SQL-injection primitive (see the deleted `findAllWithFilters` methods
+ * on drivers/vehicles repositories, which had exactly that bug).
+ *
+ * An unknown `sortBy` falls back to `fallback` instead of throwing — a stale
+ * bookmark or shared link should never 400.
+ *
+ * Always appends `id ASC` as a tiebreaker: sorting by a non-unique column
+ * (status, createdAt on bulk-imported rows) without one can drop or
+ * duplicate rows across pages once LIMIT/OFFSET is involved.
+ *
+ * @param sortable  public sort key -> "alias.column" SQL reference. Also
+ *   doubles as the Swagger enum / frontend's sortable-column list.
+ * @param fallback  a key that must exist in `sortable`.
+ */
+export function applySort<T extends ObjectLiteral>(
+  qb: SelectQueryBuilder<T>,
+  query: { sortBy?: string; sortOrder?: 'ASC' | 'DESC' },
+  sortable: Record<string, string>,
+  fallback: string,
+): SelectQueryBuilder<T> {
+  const column = (query.sortBy && sortable[query.sortBy]) || sortable[fallback];
+  qb.orderBy(column, query.sortOrder === 'ASC' ? 'ASC' : 'DESC');
+  return qb.addOrderBy(`${qb.alias}.id`, 'ASC');
+}
diff --git a/apps/edr-freight-api/src/migrations/3540000000000-FilterableListIndexes.ts b/apps/edr-freight-api/src/migrations/3540000000000-FilterableListIndexes.ts
new file mode 100644
index 000000000..1569b13d0
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3540000000000-FilterableListIndexes.ts
@@ -0,0 +1,56 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Supports the Stripe-style pill filter bar: every list it lands on filters
+ * and sorts server-side now. `@Index` decorators alone do nothing —
+ * `synchronize: false` means an index exists only if a migration created it
+ * (see the `RepairSynchronizeDrift`-style gaps this closes).
+ *
+ * `idx_warehouse_inventory_status` already exists (FreightBaseline). Bookings
+ * and wagons have no plain `status` index — `idx_bookings_route_day` and
+ * `idx_wagons_readiness` only cover `status` as a trailing/partial column,
+ * not a standalone `WHERE status = $1`, and `status` is the single
+ * most-filtered column on both lists (bookings: 37 values).
+ *
+ * `(created_at DESC, id ASC)` partials match the default sort + id
+ * tiebreaker `applySort` now appends everywhere, and none of these tables
+ * had a created_at index at all.
+ */
+export class FilterableListIndexes3540000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_bookings_status
+        ON freight.bookings USING btree (status)
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_wagons_status
+        ON freight.wagons USING btree (status)
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_contracts_created_at_id
+        ON freight.contracts (created_at DESC, id ASC) WHERE deleted_at IS NULL
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_bookings_created_at_id
+        ON freight.bookings (created_at DESC, id ASC) WHERE deleted_at IS NULL
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_warehouse_inventory_created_at_id
+        ON freight.warehouse_inventory (created_at DESC, id ASC) WHERE deleted_at IS NULL
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_wagons_created_at_id
+        ON freight.wagons (created_at DESC, id ASC) WHERE deleted_at IS NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP INDEX IF EXISTS freight.idx_wagons_created_at_id`);
+    await queryRunner.query(`DROP INDEX IF EXISTS freight.idx_warehouse_inventory_created_at_id`);
+    await queryRunner.query(`DROP INDEX IF EXISTS freight.idx_bookings_created_at_id`);
+    await queryRunner.query(`DROP INDEX IF EXISTS freight.idx_contracts_created_at_id`);
+    await queryRunner.query(`DROP INDEX IF EXISTS freight.idx_wagons_status`);
+    await queryRunner.query(`DROP INDEX IF EXISTS freight.idx_bookings_status`);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
index ea1523882..c029e36d4 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
@@ -12,6 +12,7 @@ import {
   SelectQueryBuilder,
 } from 'typeorm';
 
+import { computeFacets, FacetBucket } from '../../common/utils/facets.util';
 import { wagonsPerUnitForSize } from '../rule-engine/container-type.util';
 import { ContainerType } from '../rule-engine/entities/container-type.entity';
 import { Contract } from '../contracts/entities/contract.entity';
@@ -857,6 +858,29 @@ export class BookingsRepository extends BaseRepository<Booking> {
     };
   }
 
+  /**
+   * Facet counts for the filter bar's enum popovers: one `GROUP BY` per
+   * column, each with every OTHER active filter applied but its own
+   * predicate omitted (see `applyListFilters`'s `omit` param). `bookingType`
+   * is derived from `contract_kind` (see the comment in `applyListFilters`),
+   * not a plain column, so it facets on the same CASE expression the filter
+   * itself applies.
+   */
+  async getFacets(options: BookingListFilterOptions): Promise<Record<string, FacetBucket[]>> {
+    return computeFacets(
+      () => this.repository.createQueryBuilder('booking').where('booking.deleted_at IS NULL'),
+      (qb, omit) => this.applyListFilters(qb, options, omit as keyof BookingListFilterOptions),
+      {
+        status: 'booking.status',
+        freightType: 'booking.freight_type',
+        tradeDirection: 'booking.trade_direction',
+        paymentStatus: 'booking.payment_status',
+        bookingType:
+          "CASE WHEN booking.contract_kind = 'GENERAL' THEN 'GENERAL_CONTRACT' ELSE 'ONE_TIME' END",
+      },
+    );
+  }
+
   async getStatusCounts(): Promise<Record<string, number>> {
     const rows = await this.repository
       .createQueryBuilder('booking')
@@ -915,16 +939,24 @@ export class BookingsRepository extends BaseRepository<Booking> {
     return { inQueue, onThisPage, needsAction, urgent };
   }
 
+  /**
+   * @param omit  skip this one predicate — used by `getFacets` so a facet's
+   *   own filter doesn't hide its own sibling values. Every other caller
+   *   (list, summary metrics) passes nothing.
+   */
   private applyListFilters(
     qb: SelectQueryBuilder<Booking>,
     options: BookingListFilterOptions,
+    omit?: keyof BookingListFilterOptions | 'status',
   ): void {
-    if (options.statuses?.length) {
-      qb.andWhere('booking.status IN (:...statuses)', {
-        statuses: options.statuses,
-      });
-    } else if (options.status) {
-      qb.andWhere('booking.status = :status', { status: options.status });
+    if (omit !== 'status') {
+      if (options.statuses?.length) {
+        qb.andWhere('booking.status IN (:...statuses)', {
+          statuses: options.statuses,
+        });
+      } else if (options.status) {
+        qb.andWhere('booking.status = :status', { status: options.status });
+      }
     }
 
     if (options.companyId) {
@@ -957,12 +989,12 @@ export class BookingsRepository extends BaseRepository<Booking> {
         cargoTypeId: options.cargoTypeId,
       });
     }
-    if (options.freightType) {
+    if (omit !== 'freightType' && options.freightType) {
       qb.andWhere('booking.freight_type = :freightType', {
         freightType: options.freightType,
       });
     }
-    if (options.bookingType) {
+    if (omit !== 'bookingType' && options.bookingType) {
       // The stored booking_type column is 'ONE_TIME' for every row (contract
       // drawdowns included — see contract-booking.service create), so the
       // one-time vs general split keys on the denormalized contract_kind:
@@ -1011,12 +1043,12 @@ export class BookingsRepository extends BaseRepository<Booking> {
     } else if (options.isGovernment === 'false') {
       qb.andWhere('booking.is_government = FALSE');
     }
-    if (options.tradeDirection) {
+    if (omit !== 'tradeDirection' && options.tradeDirection) {
       qb.andWhere('booking.trade_direction = :tradeDirection', {
         tradeDirection: options.tradeDirection,
       });
     }
-    if (options.tradeDirections) {
+    if (omit !== 'tradeDirection' && options.tradeDirections) {
       applyDirectionScope(qb, 'booking.trade_direction', options.tradeDirections);
     }
     if (options.paymentCurrency) {
@@ -1024,7 +1056,7 @@ export class BookingsRepository extends BaseRepository<Booking> {
         paymentCurrency: options.paymentCurrency,
       });
     }
-    if (options.paymentStatus) {
+    if (omit !== 'paymentStatus' && options.paymentStatus) {
       qb.andWhere('booking.payment_status = :paymentStatus', {
         paymentStatus: options.paymentStatus,
       });
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
index 4f26c4415..a9e9dfc34 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
@@ -2051,8 +2051,9 @@ export class BookingsService {
       consolidationPaired: filter.consolidationPaired,
     };
 
-    const [statusCounts, metrics] = await Promise.all([
+    const [statusCounts, facets, metrics] = await Promise.all([
       this.bookingsRepository.getStatusCounts(),
+      this.bookingsRepository.getFacets(listFilter),
       this.bookingsRepository.getListSummaryMetrics({
         ...listFilter,
         page,
@@ -2064,7 +2065,9 @@ export class BookingsService {
 
     return {
       metrics,
+      // Tabs stay unfiltered (whole-set) on purpose — see the DTO comment.
       tabs: mapStatusCountsToTabs(statusCounts),
+      facets,
     };
   }
 
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/booking-list-summary.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/booking-list-summary.dto.ts
index 30ca4bdb7..582cde166 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/booking-list-summary.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/booking-list-summary.dto.ts
@@ -1,4 +1,5 @@
 import { ApiProperty } from '@nestjs/swagger';
+import { FacetBucket } from '../../../common/utils/facets.util';
 
 export class BookingListSummaryMetricsDto {
   @ApiProperty({ example: 42 })
@@ -31,4 +32,18 @@ export class BookingListSummaryDto {
 
   @ApiProperty({ type: BookingListSummaryTabsDto })
   tabs!: BookingListSummaryTabsDto;
+
+  /**
+   * Per-column value counts for the filter bar's enum popovers, scoped to
+   * every OTHER currently-active filter (own predicate omitted per column —
+   * see `BookingsRepository.getFacets`). Unlike `tabs`, which is
+   * deliberately unfiltered so tab counts stay stable while you filter
+   * within a tab, these move with the filter set.
+   */
+  @ApiProperty({
+    description: 'Facet counts keyed by filter field, for the pill filter bar',
+    type: 'object',
+    additionalProperties: { type: 'array', items: { type: 'object' } },
+  })
+  facets!: Record<string, FacetBucket[]>;
 }
diff --git a/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts b/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
index 3e76581a8..f618986c4 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
@@ -3,6 +3,7 @@ import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { DataSource, In, IsNull, Repository, SelectQueryBuilder } from 'typeorm';
 
+import { computeFacets, FacetBucket } from '../../common/utils/facets.util';
 import { Booking } from '../bookings/entities/booking.entity';
 import { FileRecord } from '../files/entities/file.entity';
 import { applyDirectionScope } from '../user-trade-access/trade-scope.util';
@@ -416,14 +417,22 @@ export class ContractsRepository extends BaseRepository<Contract> {
     return { inQueue, onThisPage, needsAction };
   }
 
+  /**
+   * @param omit  skip this one predicate — used by `getFacets` so a facet's
+   *   own filter doesn't hide its own sibling values (see class doc on
+   *   `getFacets`). Every other list/summary/count caller passes nothing.
+   */
   private applyListFilters(
     qb: SelectQueryBuilder<Contract>,
     options: ContractListFilterOptions,
+    omit?: keyof ContractListFilterOptions | 'status',
   ): void {
-    if (options.statuses?.length) {
-      qb.andWhere('contract.status IN (:...statuses)', { statuses: options.statuses });
-    } else if (options.status) {
-      qb.andWhere('contract.status = :status', { status: options.status });
+    if (omit !== 'status') {
+      if (options.statuses?.length) {
+        qb.andWhere('contract.status IN (:...statuses)', { statuses: options.statuses });
+      } else if (options.status) {
+        qb.andWhere('contract.status = :status', { status: options.status });
+      }
     }
     if (options.companyId) {
       qb.andWhere('contract.company_id = :companyId', { companyId: options.companyId });
@@ -433,7 +442,7 @@ export class ContractsRepository extends BaseRepository<Contract> {
         companyProfileId: options.companyProfileId,
       });
     }
-    if (options.contractKind) {
+    if (omit !== 'contractKind' && options.contractKind) {
       qb.andWhere('contract.contract_kind = :contractKind', {
         contractKind: options.contractKind,
       });
@@ -454,20 +463,20 @@ export class ContractsRepository extends BaseRepository<Contract> {
         serviceTypeId: options.serviceTypeId,
       });
     }
-    if (options.freightType) {
+    if (omit !== 'freightType' && options.freightType) {
       qb.andWhere('contract.freight_type = :freightType', {
         freightType: options.freightType,
       });
     }
-    if (options.tradeDirection) {
+    if (omit !== 'tradeDirection' && options.tradeDirection) {
       qb.andWhere('contract.trade_direction = :tradeDirection', {
         tradeDirection: options.tradeDirection,
       });
     }
-    if (options.tradeDirections) {
+    if (omit !== 'tradeDirection' && options.tradeDirections) {
       applyDirectionScope(qb, 'contract.trade_direction', options.tradeDirections);
     }
-    if (options.paymentCurrency) {
+    if (omit !== 'paymentCurrency' && options.paymentCurrency) {
       qb.andWhere('contract.payment_currency = :paymentCurrency', {
         paymentCurrency: options.paymentCurrency,
       });
@@ -482,6 +491,28 @@ export class ContractsRepository extends BaseRepository<Contract> {
     }
   }
 
+  /**
+   * Facet counts for the filter bar's enum popovers: one `GROUP BY` per
+   * column, each with every OTHER active filter applied but its own
+   * predicate omitted — so selecting `status=SUBMITTED` still shows
+   * `APPROVED: 8` in the status popover (to switch), while the freightType
+   * popover reflects only the SUBMITTED-scoped set. Supersedes
+   * `getStatusCounts`, which ignores the active filter entirely.
+   */
+  async getFacets(options: ContractListFilterOptions): Promise<Record<string, FacetBucket[]>> {
+    return computeFacets(
+      () => this.repository.createQueryBuilder('contract').where('contract.deleted_at IS NULL'),
+      (qb, omit) => this.applyListFilters(qb, options, omit as keyof ContractListFilterOptions),
+      {
+        status: 'contract.status',
+        contractKind: 'contract.contract_kind',
+        freightType: 'contract.freight_type',
+        tradeDirection: 'contract.trade_direction',
+        paymentCurrency: 'contract.payment_currency',
+      },
+    );
+  }
+
   // ── Approval steps ─────────────────────────────────────────────────────────
 
   /** Lowest-order pending approval step (sequential enforcement). */
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 cacfb5732..5798d44ef 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
@@ -791,8 +791,8 @@ export class ContractsService {
       createdTo: filter.createdTo,
     };
 
-    const [statusCounts, metrics] = await Promise.all([
-      this.contractsRepository.getStatusCounts(),
+    const [facets, metrics] = await Promise.all([
+      this.contractsRepository.getFacets(listFilter),
       this.contractsRepository.getListSummaryMetrics({
         ...listFilter,
         page,
@@ -801,7 +801,13 @@ export class ContractsService {
       }),
     ]);
 
-    return { metrics, statusCounts };
+    // statusCounts kept for existing callers; now filter-scoped like every
+    // other facet instead of the unfiltered global count `getStatusCounts` gave.
+    const statusCounts = Object.fromEntries(
+      (facets.status ?? []).map((b) => [b.value, b.count]),
+    );
+
+    return { metrics, statusCounts, facets };
   }
 
   /** Get a single contract by ID with relations and signed file URLs. */
diff --git a/apps/edr-freight-api/src/modules/contracts/dto/contract-list-summary.dto.ts b/apps/edr-freight-api/src/modules/contracts/dto/contract-list-summary.dto.ts
index 78b7d97c6..12e4e5aca 100644
--- a/apps/edr-freight-api/src/modules/contracts/dto/contract-list-summary.dto.ts
+++ b/apps/edr-freight-api/src/modules/contracts/dto/contract-list-summary.dto.ts
@@ -1,4 +1,5 @@
 import { ApiProperty } from '@nestjs/swagger';
+import { FacetBucket } from '../../../common/utils/facets.util';
 
 export class ContractListSummaryMetricsDto {
   @ApiProperty({ example: 42 })
@@ -15,6 +16,23 @@ export class ContractListSummaryDto {
   @ApiProperty({ type: ContractListSummaryMetricsDto })
   metrics!: ContractListSummaryMetricsDto;
 
+  /** @deprecated use `facets.status` — kept for existing callers, computed
+   * from the same filter-scoped query now instead of `getStatusCounts`'s
+   * unfiltered global count. */
   @ApiProperty({ description: 'Count per contract status', type: 'object', additionalProperties: { type: 'number' } })
   statusCounts!: Record<string, number>;
+
+  /**
+   * Per-column value counts for the filter bar's enum popovers, scoped to
+   * every OTHER currently-active filter (each column's own predicate is
+   * omitted from its own count — see `ContractsRepository.getFacets`).
+   * Absent/omitted keys mean the frontend falls back to its static option
+   * list with no counts, never an error.
+   */
+  @ApiProperty({
+    description: 'Facet counts keyed by filter field, for the pill filter bar',
+    type: 'object',
+    additionalProperties: { type: 'array', items: { type: 'object' } },
+  })
+  facets!: Record<string, FacetBucket[]>;
 }
diff --git a/apps/edr-freight-api/src/modules/drivers/drivers.repository.ts b/apps/edr-freight-api/src/modules/drivers/drivers.repository.ts
index 64be88b61..d6ff938f1 100644
--- a/apps/edr-freight-api/src/modules/drivers/drivers.repository.ts
+++ b/apps/edr-freight-api/src/modules/drivers/drivers.repository.ts
@@ -29,52 +29,6 @@ export class DriversRepository extends BaseRepository<Driver> {
     return this.repository.findOne({ where: { id } });
   }
 
-  async findAllWithFilters(query: {
-    page?: number;
-    pageSize?: number;
-    search?: string;
-    status?: string;
-    sortBy?: string;
-    sortOrder?: 'ASC' | 'DESC';
-  }) {
-    const page = query.page || 1;
-    const pageSize = query.pageSize || 10;
-    const skip = (page - 1) * pageSize;
-
-    let queryBuilder = this.repository.createQueryBuilder('driver');
-
-    if (query.search) {
-      queryBuilder = queryBuilder.where(
-        '(driver.firstName ILIKE :search OR driver.lastName ILIKE :search OR driver.email ILIKE :search OR driver.phoneNumber ILIKE :search OR driver.licenseNumber ILIKE :search)',
-        { search: `%${query.search}%` },
-      );
-    }
-
-    if (query.status) {
-      queryBuilder = queryBuilder.andWhere('driver.status = :status', {
-        status: query.status,
-      });
-    }
-
-    const sortBy = query.sortBy || 'createdAt';
-    const sortOrder = query.sortOrder || 'DESC';
-
-    queryBuilder = queryBuilder
-      .orderBy(`driver.${sortBy}`, sortOrder)
-      .skip(skip)
-      .take(pageSize);
-
-    const [data, total] = await queryBuilder.getManyAndCount();
-
-    return {
-      data,
-      total,
-      page,
-      pageSize,
-      totalPages: Math.ceil(total / pageSize),
-    };
-  }
-
   async createDriver(driverData: any): Promise<Driver> {
     const driver = this.repository.create(driverData);
     const result = await this.repository.save(driver);
diff --git a/apps/edr-freight-api/src/modules/vehicles/vehicles.repository.ts b/apps/edr-freight-api/src/modules/vehicles/vehicles.repository.ts
index 1080480fa..c5af8cee2 100644
--- a/apps/edr-freight-api/src/modules/vehicles/vehicles.repository.ts
+++ b/apps/edr-freight-api/src/modules/vehicles/vehicles.repository.ts
@@ -21,52 +21,6 @@ export class VehiclesRepository extends BaseRepository<Vehicle> {
     return this.repository.findOne({ where: { id } });
   }
 
-  async findAllWithFilters(query: {
-    page?: number;
-    pageSize?: number;
-    search?: string;
-    status?: string;
-    sortBy?: string;
-    sortOrder?: 'ASC' | 'DESC';
-  }) {
-    const page = query.page || 1;
-    const pageSize = query.pageSize || 10;
-    const skip = (page - 1) * pageSize;
-
-    let queryBuilder = this.repository.createQueryBuilder('vehicle');
-
-    if (query.search) {
-      queryBuilder = queryBuilder.where(
-        '(vehicle.plateNumber ILIKE :search OR vehicle.manufacturer ILIKE :search OR vehicle.model ILIKE :search)',
-        { search: `%${query.search}%` },
-      );
-    }
-
-    if (query.status) {
-      queryBuilder = queryBuilder.andWhere('vehicle.status = :status', {
-        status: query.status,
-      });
-    }
-
-    const sortBy = query.sortBy || 'createdAt';
-    const sortOrder = query.sortOrder || 'DESC';
-
-    queryBuilder = queryBuilder
-      .orderBy(`vehicle.${sortBy}`, sortOrder)
-      .skip(skip)
-      .take(pageSize);
-
-    const [data, total] = await queryBuilder.getManyAndCount();
-
-    return {
-      data,
-      total,
-      page,
-      pageSize,
-      totalPages: Math.ceil(total / pageSize),
-    };
-  }
-
   async createVehicle(vehicleData: Partial<Vehicle>): Promise<Vehicle> {
     const vehicle = this.repository.create(vehicleData);
     return this.repository.save(vehicle);
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx b/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
new file mode 100644
index 000000000..96aaaa22d
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
@@ -0,0 +1,121 @@
+import { useState, type ReactNode } from "react";
+import { Anchor, Divider, Group, TextInput } from "@mantine/core";
+import { Search, Trash2 } from "lucide-react";
+
+import type { FilterDef, SortOption } from "./types";
+import type { UseFilters } from "./useFilters";
+import { FilterPill } from "./FilterPill";
+import { MoreFiltersMenu } from "./MoreFiltersMenu";
+import { SavedViews } from "./SavedViews";
+import { SortControl } from "./SortControl";
+
+export interface FilterBarProps {
+  defs: FilterDef[];
+  controls: UseFilters;
+  searchPlaceholder?: string;
+  showSearch?: boolean;
+  /** value already "field:DIR" — the page's existing SORT_OPTIONS, moved not rewritten. */
+  sortOptions?: SortOption[];
+  /** localStorage namespace for saved views. Omit to hide the control. */
+  viewId?: string;
+  /** Escape hatch: tabs, row count, a "New" button — rendered at the far right. */
+  children?: ReactNode;
+}
+
+export function FilterBar({
+  defs,
+  controls,
+  searchPlaceholder = "Search…",
+  showSearch = true,
+  sortOptions,
+  viewId,
+  children,
+}: FilterBarProps) {
+  // Filters just picked from "More filters" render as an already-open pill
+  // until the popover closes, then fall back to the ordinary pinned/active split.
+  const [justPicked, setJustPicked] = useState<string[]>([]);
+
+  const pinned = defs.filter((d) => !d.secondary || controls.values[d.key] || justPicked.includes(d.key));
+  const secondary = defs.filter((d) => !pinned.includes(d));
+  // Applied filters read first, left to right — a stable partition keeps
+  // each group in its original def order rather than resorting on every apply.
+  const orderedPinned = [
+    ...pinned.filter((d) => controls.values[d.key]),
+    ...pinned.filter((d) => !controls.values[d.key]),
+  ];
+
+  return (
+    // Two independent flex zones, not one big wrapping Group: the left side
+    // (search + pills + more filters + clear) wraps to as many lines as it
+    // needs; the right side (sort) stays put on the first line — `nowrap` +
+    // `flexShrink: 0` on the right zone stop it from ever getting pushed
+    // down when the left side overflows.
+    <div style={{ display: "flex", alignItems: "flex-start", gap: 8, flexWrap: "nowrap" }}>
+      <Group gap="xs" wrap="wrap" align="center" style={{ flex: 1, minWidth: 0 }}>
+        {viewId && (
+          <SavedViews
+            viewId={viewId}
+            currentQueryString={controls.currentQueryString}
+            applyQueryString={controls.applyQueryString}
+          />
+        )}
+
+        {showSearch && (
+          <TextInput
+            placeholder={searchPlaceholder}
+            leftSection={<Search size={14} />}
+            value={controls.searchText}
+            onChange={(e) => controls.setSearchText(e.currentTarget.value)}
+            size="xs"
+            radius="lg"
+            style={{ minWidth: 220 }}
+          />
+        )}
+
+        {orderedPinned.map((def) => (
+          <FilterPill
+            key={def.key}
+            def={def}
+            value={controls.values[def.key]}
+            onChange={(v) => controls.setFilter(def.key, v)}
+            autoOpen={justPicked.includes(def.key)}
+          />
+        ))}
+
+        <MoreFiltersMenu
+          defs={secondary}
+          onPick={(key) => setJustPicked((prev) => [...prev, key])}
+        />
+
+        {controls.activeCount > 0 && (
+          <Anchor
+            size="xs"
+            c="red.6"
+            underline="never"
+            onClick={() => {
+              controls.clearFilters();
+              setJustPicked([]);
+            }}
+            style={{ display: "inline-flex", alignItems: "center", gap: 4 }}
+          >
+            <Trash2 size={13} />
+            Clear
+          </Anchor>
+        )}
+      </Group>
+
+      {/* Sorting is a different kind of control (view order, not scope) —
+          cut off from the filter pills by a vertical divider and pinned to
+          the right, independent of how the left side wraps. */}
+      <Group gap="xs" wrap="nowrap" style={{ flexShrink: 0 }}>
+        {children}
+        {sortOptions && sortOptions.length > 0 && (
+          <>
+            <Divider orientation="vertical" />
+            <SortControl options={sortOptions} value={controls.sort} onChange={controls.setSort} />
+          </>
+        )}
+      </Group>
+    </div>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx b/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx
new file mode 100644
index 000000000..40ba372f8
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx
@@ -0,0 +1,88 @@
+import { useState } from "react";
+import { ActionIcon, Button, Popover } from "@mantine/core";
+import { Plus, X } from "lucide-react";
+
+import type { FilterDef, FilterValue } from "./types";
+import { BooleanBody } from "./bodies/BooleanBody";
+import { DateBody } from "./bodies/DateBody";
+import { EnumBody } from "./bodies/EnumBody";
+import { NumberBody } from "./bodies/NumberBody";
+import { TextBody } from "./bodies/TextBody";
+
+const BODIES: Record<FilterDef["type"], React.ComponentType<any>> = {
+  text: TextBody,
+  enum: EnumBody,
+  date: DateBody,
+  number: NumberBody,
+  boolean: BooleanBody,
+};
+
+function formatValue(def: FilterDef, value: FilterValue): string {
+  if (def.format) return def.format(value, def);
+  if (def.type === "enum") {
+    const labels = value.v.map((v) => def.options.find((o) => o.value === v)?.label ?? v);
+    return labels.join(", ");
+  }
+  if (def.type === "date" && value.v.length === 2) {
+    return `${value.v[0].slice(0, 10)} → ${value.v[1].slice(0, 10)}`;
+  }
+  return value.v.join(", ");
+}
+
+export interface FilterPillProps {
+  def: FilterDef;
+  value: FilterValue | undefined;
+  onChange: (v: FilterValue | undefined) => void;
+  /** Opened immediately (used when picked from "More filters"). */
+  autoOpen?: boolean;
+}
+
+export function FilterPill({ def, value, onChange, autoOpen }: FilterPillProps) {
+  const [opened, setOpened] = useState(Boolean(autoOpen));
+  const Body = BODIES[def.type];
+  const active = Boolean(value);
+
+  return (
+    <Popover position="bottom-start" withinPortal shadow="md" opened={opened} onChange={setOpened}>
+      <Popover.Target>
+        <Button
+          size="xs"
+          radius="xl"
+          // Inactive: "default" variant (solid border, opaque text) reads far
+          // less faint than a color-tinted outline — dashed border is the only
+          // thing marking it as "not set yet". Active: "light" (soft tinted
+          // fill), not "filled" — a whole row of solid green buttons was the
+          // "too loud" complaint; light keeps the active/inactive contrast
+          // without shouting.
+          variant={active ? "light" : "default"}
+          color={active ? "edr-green" : undefined}
+          styles={active ? undefined : { root: { borderStyle: "dashed" } }}
+          leftSection={!active && <Plus size={12} />}
+          rightSection={
+            active && (
+              <ActionIcon
+                component="span"
+                size={16}
+                radius="xl"
+                variant="subtle"
+                color="edr-green"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onChange(undefined);
+                }}
+              >
+                <X size={12} />
+              </ActionIcon>
+            )
+          }
+          onClick={() => setOpened((o) => !o)}
+        >
+          {active ? `${def.label} | ${formatValue(def, value!)}` : def.label}
+        </Button>
+      </Popover.Target>
+      <Popover.Dropdown miw={260} p="xs">
+        <Body def={def} value={value} onChange={onChange} onClose={() => setOpened(false)} />
+      </Popover.Dropdown>
+    </Popover>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/MoreFiltersMenu.tsx b/apps/edr-freight-web/backoffice/src/components/filters/MoreFiltersMenu.tsx
new file mode 100644
index 000000000..2dc6c1240
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/MoreFiltersMenu.tsx
@@ -0,0 +1,82 @@
+import { useMemo, useState } from "react";
+import { Button, Popover, ScrollArea, Stack, Text, TextInput, UnstyledButton } from "@mantine/core";
+import { Plus, Search } from "lucide-react";
+
+import type { FilterDef } from "./types";
+
+export interface MoreFiltersMenuProps {
+  defs: FilterDef[];
+  /** Called with the picked def's key — the caller pins it and opens its popover. */
+  onPick: (key: string) => void;
+}
+
+/** Searchable list over the page's secondary/inactive filters. Plain filter + list,
+ * not cmdk — a handful of static strings doesn't need a Combobox store. */
+export function MoreFiltersMenu({ defs, onPick }: MoreFiltersMenuProps) {
+  const [opened, setOpened] = useState(false);
+  const [query, setQuery] = useState("");
+
+  const visible = useMemo(
+    () => defs.filter((d) => d.label.toLowerCase().includes(query.toLowerCase())),
+    [defs, query],
+  );
+
+  if (defs.length === 0) return null;
+
+  return (
+    <Popover position="bottom-start" withinPortal shadow="md" opened={opened} onChange={setOpened}>
+      <Popover.Target>
+        <Button
+          size="xs"
+          radius="xl"
+          variant="outline"
+          color="gray"
+          leftSection={<Plus size={16} />}
+          onClick={() => setOpened((o) => !o)}
+        >
+          More filters
+        </Button>
+      </Popover.Target>
+      <Popover.Dropdown miw={220} p="xs">
+        <Stack gap="xs">
+          <TextInput
+            placeholder="Search filters…"
+            leftSection={<Search size={14} />}
+            value={query}
+            onChange={(e) => setQuery(e.currentTarget.value)}
+            size="sm"
+            autoFocus
+          />
+          <ScrollArea.Autosize mah={280}>
+            <Stack gap={2}>
+              {visible.map((d) => (
+                <UnstyledButton
+                  key={d.key}
+                  px="xs"
+                  py={6}
+                  className="hover:bg-gray-100 transition-colors"
+                  style={{ borderRadius: 6, display: "flex", alignItems: "center", gap: 8 }}
+                  onClick={() => {
+                    setOpened(false);
+                    setQuery("");
+                    onPick(d.key);
+                  }}
+                >
+                  <Plus size={14} className="text-[var(--mantine-color-edr-green-6)]" />
+                  <Text size="sm" c="edr-green.7">
+                    {d.label}
+                  </Text>
+                </UnstyledButton>
+              ))}
+              {visible.length === 0 && (
+                <Text size="xs" c="dimmed" px="xs" py={6}>
+                  No matching filters
+                </Text>
+              )}
+            </Stack>
+          </ScrollArea.Autosize>
+        </Stack>
+      </Popover.Dropdown>
+    </Popover>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/OperatorSelect.tsx b/apps/edr-freight-web/backoffice/src/components/filters/OperatorSelect.tsx
new file mode 100644
index 000000000..a769ebf93
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/OperatorSelect.tsx
@@ -0,0 +1,25 @@
+import { SegmentedControl } from "@mantine/core";
+import { DEFAULT_OP, OPERATOR_LABELS, type FilterDef, type Operator } from "./types";
+
+export interface OperatorSelectProps {
+  def: FilterDef;
+  value: Operator;
+  onChange: (op: Operator) => void;
+}
+
+/** Renders nothing when a def has <= 1 operator — most defs, by design: type-aware
+ * operators are a capability, not a dropdown forced into every popover. */
+export function OperatorSelect({ def, value, onChange }: OperatorSelectProps) {
+  const operators = def.operators ?? [DEFAULT_OP[def.type]];
+  if (operators.length <= 1) return null;
+  return (
+    <SegmentedControl
+      size="sm"
+      fullWidth
+      value={value}
+      onChange={(v) => onChange(v as Operator)}
+      data={operators.map((op) => ({ value: op, label: OPERATOR_LABELS[op] }))}
+      mb="xs"
+    />
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/SavedViews.tsx b/apps/edr-freight-web/backoffice/src/components/filters/SavedViews.tsx
new file mode 100644
index 000000000..826356159
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/SavedViews.tsx
@@ -0,0 +1,107 @@
+import { useState } from "react";
+import { ActionIcon, Button, Menu, Modal, Stack, Text, TextInput } from "@mantine/core";
+import { useLocalStorage } from "@mantine/hooks";
+import { Bookmark, Check, Save, Trash2 } from "lucide-react";
+
+interface SavedView {
+  id: string;
+  name: string;
+  query: string;
+}
+
+export interface SavedViewsProps {
+  /** localStorage namespace — one page, not one user (single staff login per
+   * browser profile). ponytail: add ":<userId>" if shared-terminal login appears. */
+  viewId: string;
+  currentQueryString: () => string;
+  applyQueryString: (query: string) => void;
+}
+
+/** URL always wins: this menu only ever WRITES the URL, on click. Nothing
+ * reads a saved view at mount, so a shared link always beats a saved view —
+ * there is no "which one applies" branch to get wrong. */
+export function SavedViews({ viewId, currentQueryString, applyQueryString }: SavedViewsProps) {
+  const [views, setViews] = useLocalStorage<SavedView[]>({
+    key: `edr:saved-views:${viewId}`,
+    defaultValue: [],
+  });
+  const [saveOpen, setSaveOpen] = useState(false);
+  const [name, setName] = useState("");
+
+  const activeQuery = currentQueryString();
+  const active = views.find((v) => v.query === activeQuery);
+
+  const save = () => {
+    if (!name.trim()) return;
+    setViews((prev) => [
+      ...prev,
+      { id: crypto.randomUUID(), name: name.trim(), query: currentQueryString() },
+    ]);
+    setName("");
+    setSaveOpen(false);
+  };
+
+  const remove = (id: string) => setViews((prev) => prev.filter((v) => v.id !== id));
+
+  return (
+    <>
+      <Menu position="bottom-start" withinPortal shadow="md">
+        <Menu.Target>
+          <Button size="xs" variant="subtle" color="gray" leftSection={<Bookmark size={14} />}>
+            {active?.name ?? "All"}
+          </Button>
+        </Menu.Target>
+        <Menu.Dropdown miw={220}>
+          {views.length === 0 && (
+            <Menu.Item disabled>
+              <Text size="xs" c="dimmed">
+                No saved views yet
+              </Text>
+            </Menu.Item>
+          )}
+          {views.map((v) => (
+            <Menu.Item
+              key={v.id}
+              leftSection={v.id === active?.id ? <Check size={14} /> : <span style={{ width: 14 }} />}
+              rightSection={
+                <ActionIcon
+                  size="xs"
+                  color="red"
+                  variant="subtle"
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    remove(v.id);
+                  }}
+                >
+                  <Trash2 size={12} />
+                </ActionIcon>
+              }
+              onClick={() => applyQueryString(v.query)}
+            >
+              {v.name}
+            </Menu.Item>
+          ))}
+          <Menu.Divider />
+          <Menu.Item leftSection={<Save size={14} />} onClick={() => setSaveOpen(true)}>
+            Save current view…
+          </Menu.Item>
+        </Menu.Dropdown>
+      </Menu>
+
+      <Modal opened={saveOpen} onClose={() => setSaveOpen(false)} title="Save current view" size="sm">
+        <Stack gap="sm">
+          <TextInput
+            placeholder="View name"
+            value={name}
+            onChange={(e) => setName(e.currentTarget.value)}
+            onKeyDown={(e) => e.key === "Enter" && save()}
+            autoFocus
+          />
+          <Button onClick={save} disabled={!name.trim()}>
+            Save
+          </Button>
+        </Stack>
+      </Modal>
+    </>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/SortControl.tsx b/apps/edr-freight-web/backoffice/src/components/filters/SortControl.tsx
new file mode 100644
index 000000000..cdb9dde33
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/SortControl.tsx
@@ -0,0 +1,40 @@
+import { Button, Menu } from "@mantine/core";
+import { ArrowUpDown, Check } from "lucide-react";
+
+import type { SortOption } from "./types";
+
+export interface SortControlProps {
+  options: SortOption[];
+  value: string;
+  onChange: (value: string) => void;
+}
+
+/** A control, not a form field — Menu (not Select) gives the check-mark +
+ * trigger-label read Stripe's sort control has. Rendered only when a page
+ * passes sortOptions; inventing options for an endpoint without sortBy
+ * support would ship a control that silently does nothing. */
+export function SortControl({ options, value, onChange }: SortControlProps) {
+  if (options.length === 0) return null;
+  const current = options.find((o) => o.value === value);
+
+  return (
+    <Menu position="bottom-end" withinPortal shadow="md">
+      <Menu.Target>
+        <Button size="xs" variant="outline" color="gray" leftSection={<ArrowUpDown size={14} />}>
+          {current?.label ?? "Sort"}
+        </Button>
+      </Menu.Target>
+      <Menu.Dropdown>
+        {options.map((o) => (
+          <Menu.Item
+            key={o.value}
+            leftSection={o.value === value ? <Check size={14} /> : <span style={{ width: 14 }} />}
+            onClick={() => onChange(o.value)}
+          >
+            {o.label}
+          </Menu.Item>
+        ))}
+      </Menu.Dropdown>
+    </Menu>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/bodies/BooleanBody.tsx b/apps/edr-freight-web/backoffice/src/components/filters/bodies/BooleanBody.tsx
new file mode 100644
index 000000000..fc59fa3bb
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/bodies/BooleanBody.tsx
@@ -0,0 +1,32 @@
+import { useState } from "react";
+import { Button, Radio, Stack } from "@mantine/core";
+
+import { DEFAULT_OP } from "../types";
+import type { BooleanFilterDef, Operator } from "../types";
+import { OperatorSelect } from "../OperatorSelect";
+import type { FilterBodyProps } from "./TextBody";
+
+export function BooleanBody({ def, value, onChange, onClose }: FilterBodyProps<BooleanFilterDef>) {
+  const [op, setOp] = useState<Operator>(value?.op ?? DEFAULT_OP.boolean);
+  const [v, setV] = useState(value?.v[0] ?? "");
+
+  const apply = () => {
+    onChange(v ? { op, v: [v] } : undefined);
+    onClose();
+  };
+
+  return (
+    <Stack gap="xs">
+      <OperatorSelect def={def} value={op} onChange={setOp} />
+      <Radio.Group value={v} onChange={setV}>
+        <Stack gap={6}>
+          <Radio value="true" label={def.trueLabel ?? "Yes"} size="sm" />
+          <Radio value="false" label={def.falseLabel ?? "No"} size="sm" />
+        </Stack>
+      </Radio.Group>
+      <Button size="sm" onClick={apply}>
+        Apply
+      </Button>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/bodies/DateBody.tsx b/apps/edr-freight-web/backoffice/src/components/filters/bodies/DateBody.tsx
new file mode 100644
index 000000000..a7c90c8c9
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/bodies/DateBody.tsx
@@ -0,0 +1,87 @@
+import { useState } from "react";
+import { Button, Stack } from "@mantine/core";
+import { DatePickerInput } from "@mantine/dates";
+
+import { getDateRangePresets } from "@/components/common/dateRangePresets";
+import { startOfDayIso, endOfDayIso, parseDateStr } from "../dates";
+import { DEFAULT_OP } from "../types";
+import type { DateFilterDef, Operator } from "../types";
+import { OperatorSelect } from "../OperatorSelect";
+import type { FilterBodyProps } from "./TextBody";
+
+// ponytail: Gregorian only. Record-management pages need the Ethiopian
+// calendar (see shared/common/form/fields/AmharicDatePicker.tsx) — add an
+// i18n.language !== "en" branch here when this body is first wired into a
+// record-management page (Phase 4 of the filter-bar rollout).
+export function DateBody({ def, value, onChange, onClose }: FilterBodyProps<DateFilterDef>) {
+  const [op, setOp] = useState<Operator>(value?.op ?? DEFAULT_OP.date);
+  // Mantine 9's date inputs speak `YYYY-MM-DD` strings, not Date objects.
+  const [from, setFrom] = useState<string | null>(value?.v[0]?.slice(0, 10) ?? null);
+  const [to, setTo] = useState<string | null>(value?.v[1]?.slice(0, 10) ?? null);
+
+  const apply = () => {
+    if (op === "between") {
+      onChange(
+        from && to
+          ? { op, v: [startOfDayIso(parseDateStr(from)), endOfDayIso(parseDateStr(to))] }
+          : undefined,
+      );
+    } else {
+      onChange(
+        from
+          ? {
+              op,
+              v: [
+                op === "before"
+                  ? startOfDayIso(parseDateStr(from))
+                  : endOfDayIso(parseDateStr(from)),
+              ],
+            }
+          : undefined,
+      );
+    }
+    onClose();
+  };
+
+  // This popover already lives inside FilterPill's own Popover. Mantine's
+  // DatePickerInput opens ITS calendar in a separate portal by default, so a
+  // click on a day registers as "outside" the outer Popover and closes the
+  // whole filter before the range can be picked (or Apply reached) — the
+  // reported "date picker doesn't work". Keeping the calendar un-portalled
+  // renders it inside the outer popover's own DOM subtree instead, so
+  // outside-click detection sees it as inside.
+  const nestedPopoverProps = { withinPortal: false } as const;
+
+  return (
+    <Stack gap="xs">
+      <OperatorSelect def={def} value={op} onChange={setOp} />
+      {op === "between" ? (
+        <DatePickerInput
+          type="range"
+          placeholder="Any"
+          value={[from, to]}
+          onChange={([f, t]) => {
+            setFrom(f);
+            setTo(t);
+          }}
+          presets={getDateRangePresets()}
+          popoverProps={nestedPopoverProps}
+          clearable
+          autoFocus
+        />
+      ) : (
+        <DatePickerInput
+          placeholder="Any"
+          value={from}
+          onChange={setFrom}
+          popoverProps={nestedPopoverProps}
+          clearable
+          autoFocus
+        />
+      )}
+      <Button size="sm" onClick={apply} disabled={op === "between" ? !(from && to) : !from}>
+        Apply
+      </Button>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/bodies/EnumBody.tsx b/apps/edr-freight-web/backoffice/src/components/filters/bodies/EnumBody.tsx
new file mode 100644
index 000000000..459246dff
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/bodies/EnumBody.tsx
@@ -0,0 +1,128 @@
+import { useMemo, useState } from "react";
+import { Button, Checkbox, Group, Radio, Stack, Text, TextInput, UnstyledButton } from "@mantine/core";
+import { Search } from "lucide-react";
+
+import { DEFAULT_OP } from "../types";
+import type { EnumFilterDef, Operator } from "../types";
+import { OperatorSelect } from "../OperatorSelect";
+import type { FilterBodyProps } from "./TextBody";
+
+/** How many options before a search box appears above the list. */
+const SEARCH_THRESHOLD = 8;
+
+/**
+ * Stretches the Checkbox/Radio's native <label> across the full popover
+ * width and pads it, so the clickable/tappable area is the whole row —
+ * not just the ~14px input square — plus a hover cue. `body`/`labelWrapper`
+ * are Mantine's part names for this; `cursor: pointer` on the row (not just
+ * the input) makes the affordance visible before you even click.
+ */
+const ROW_STYLES = {
+  root: { padding: "10px 10px", borderRadius: 6 },
+  body: { alignItems: "center" as const },
+  labelWrapper: { flex: 1 },
+  label: { cursor: "pointer", paddingLeft: 8 },
+};
+
+function OptionLabel({ label, count }: { label: string; count?: number }) {
+  return (
+    <Group justify="space-between" wrap="nowrap" gap="sm">
+      <Text size="sm">{label}</Text>
+      {count !== undefined && (
+        <Text size="sm" c="dimmed">
+          {count}
+        </Text>
+      )}
+    </Group>
+  );
+}
+
+export function EnumBody({ def, value, onChange, onClose }: FilterBodyProps<EnumFilterDef>) {
+  const [op, setOp] = useState<Operator>(value?.op ?? DEFAULT_OP.enum);
+  const [selected, setSelected] = useState<string[]>(value?.v ?? []);
+  const [query, setQuery] = useState("");
+  const [showAll, setShowAll] = useState(false);
+  const multiple = def.multiple ?? true;
+
+  const visible = useMemo(() => {
+    const byQuery = query
+      ? def.options.filter((o) => o.label.toLowerCase().includes(query.toLowerCase()))
+      : def.options;
+    if (!def.counts || showAll) return byQuery;
+    // Hide zero-count options, but never hide one the user already picked —
+    // otherwise a filter that narrows to zero rows becomes impossible to un-select.
+    return byQuery.filter((o) => (def.counts![o.value] ?? 0) > 0 || selected.includes(o.value));
+  }, [def.options, def.counts, query, showAll, selected]);
+
+  const hiddenCount = def.options.length - visible.length;
+
+  const apply = () => {
+    onChange(selected.length ? { op, v: selected } : undefined);
+    onClose();
+  };
+
+  return (
+    <Stack gap="xs">
+      <OperatorSelect def={def} value={op} onChange={setOp} />
+      {def.options.length > SEARCH_THRESHOLD && (
+        <TextInput
+          placeholder="Search options…"
+          leftSection={<Search size={14} />}
+          value={query}
+          onChange={(e) => setQuery(e.currentTarget.value)}
+          size="sm"
+        />
+      )}
+      <Stack gap={0} mah={260} style={{ overflowY: "auto" }}>
+        {multiple ? (
+          <Checkbox.Group value={selected} onChange={setSelected} aria-label={`Filter by ${def.label}`}>
+            <Stack gap={0}>
+              {visible.map((o) => (
+                <Checkbox
+                  key={o.value}
+                  value={o.value}
+                  size="sm"
+                  // The count sits INSIDE the label, so it's part of the
+                  // native <label> the input is bound to — clicking it (not
+                  // just the tiny checkbox square) toggles the option too.
+                  label={<OptionLabel label={o.label} count={def.counts?.[o.value]} />}
+                  styles={ROW_STYLES}
+                  classNames={{ root: "hover:bg-gray-100 transition-colors" }}
+                />
+              ))}
+            </Stack>
+          </Checkbox.Group>
+        ) : (
+          <Radio.Group
+            value={selected[0] ?? ""}
+            onChange={(v) => setSelected(v ? [v] : [])}
+            aria-label={`Filter by ${def.label}`}
+          >
+            <Stack gap={0}>
+              {visible.map((o) => (
+                <Radio
+                  key={o.value}
+                  value={o.value}
+                  size="sm"
+                  label={<OptionLabel label={o.label} count={def.counts?.[o.value]} />}
+                  styles={ROW_STYLES}
+                  classNames={{ root: "hover:bg-gray-100 transition-colors" }}
+                />
+              ))}
+            </Stack>
+          </Radio.Group>
+        )}
+        {!showAll && hiddenCount > 0 && (
+          <UnstyledButton onClick={() => setShowAll(true)}>
+            <Text size="sm" c="edr-green.6">
+              Show all {def.options.length} options
+            </Text>
+          </UnstyledButton>
+        )}
+      </Stack>
+      <Button size="sm" onClick={apply}>
+        Apply
+      </Button>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/bodies/NumberBody.tsx b/apps/edr-freight-web/backoffice/src/components/filters/bodies/NumberBody.tsx
new file mode 100644
index 000000000..59ef66b9e
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/bodies/NumberBody.tsx
@@ -0,0 +1,39 @@
+import { useState } from "react";
+import { Button, Group, NumberInput, Stack } from "@mantine/core";
+
+import { DEFAULT_OP } from "../types";
+import type { NumberFilterDef, Operator } from "../types";
+import { OperatorSelect } from "../OperatorSelect";
+import type { FilterBodyProps } from "./TextBody";
+
+export function NumberBody({ def, value, onChange, onClose }: FilterBodyProps<NumberFilterDef>) {
+  const [op, setOp] = useState<Operator>(value?.op ?? DEFAULT_OP.number);
+  const [from, setFrom] = useState<number | "">(value?.v[0] ? Number(value.v[0]) : "");
+  const [to, setTo] = useState<number | "">(op === "between" ? (Number(value?.v[1]) || "") : "");
+
+  const apply = () => {
+    if (op === "between") {
+      onChange(from !== "" && to !== "" ? { op, v: [String(from), String(to)] } : undefined);
+    } else {
+      onChange(from !== "" ? { op, v: [String(from)] } : undefined);
+    }
+    onClose();
+  };
+
+  return (
+    <Stack gap="xs">
+      <OperatorSelect def={def} value={op} onChange={setOp} />
+      {op === "between" ? (
+        <Group gap="xs" wrap="nowrap">
+          <NumberInput placeholder="Min" value={from} onChange={(v) => setFrom(v as number | "")} rightSection={def.unit} autoFocus />
+          <NumberInput placeholder="Max" value={to} onChange={(v) => setTo(v as number | "")} rightSection={def.unit} />
+        </Group>
+      ) : (
+        <NumberInput placeholder="Value" value={from} onChange={(v) => setFrom(v as number | "")} rightSection={def.unit} autoFocus />
+      )}
+      <Button size="sm" onClick={apply}>
+        Apply
+      </Button>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/bodies/TextBody.tsx b/apps/edr-freight-web/backoffice/src/components/filters/bodies/TextBody.tsx
new file mode 100644
index 000000000..7685ad4ae
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/bodies/TextBody.tsx
@@ -0,0 +1,39 @@
+import { useState } from "react";
+import { Button, Stack, TextInput } from "@mantine/core";
+
+import { DEFAULT_OP } from "../types";
+import type { TextFilterDef, FilterValue, Operator } from "../types";
+import { OperatorSelect } from "../OperatorSelect";
+
+export interface FilterBodyProps<Def> {
+  def: Def;
+  value: FilterValue | undefined;
+  onChange: (v: FilterValue | undefined) => void;
+  onClose: () => void;
+}
+
+export function TextBody({ def, value, onChange, onClose }: FilterBodyProps<TextFilterDef>) {
+  const [op, setOp] = useState<Operator>(value?.op ?? DEFAULT_OP.text);
+  const [text, setText] = useState(value?.v[0] ?? "");
+
+  const apply = () => {
+    onChange(text.trim() ? { op, v: [text.trim()] } : undefined);
+    onClose();
+  };
+
+  return (
+    <Stack gap="xs">
+      <OperatorSelect def={def} value={op} onChange={setOp} />
+      <TextInput
+        placeholder={def.placeholder ?? `Filter by ${def.label.toLowerCase()}…`}
+        value={text}
+        onChange={(e) => setText(e.currentTarget.value)}
+        onKeyDown={(e) => e.key === "Enter" && apply()}
+        autoFocus
+      />
+      <Button size="sm" onClick={apply}>
+        Apply
+      </Button>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/dates.ts b/apps/edr-freight-web/backoffice/src/components/filters/dates.ts
new file mode 100644
index 000000000..f85fc31d0
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/dates.ts
@@ -0,0 +1,31 @@
+/** Local start-of-day -> ISO, for inclusive "from" date filters. Lifted out of
+ * ContractRequestsPage (where it was duplicated into BookingRequestsPage) so
+ * every date filter shares one definition. */
+export function startOfDayIso(d: Date): string {
+  const x = new Date(d);
+  x.setHours(0, 0, 0, 0);
+  return x.toISOString();
+}
+
+/** Local end-of-day -> ISO, for inclusive "to" date filters. */
+export function endOfDayIso(d: Date): string {
+  const x = new Date(d);
+  x.setHours(23, 59, 59, 999);
+  return x.toISOString();
+}
+
+/**
+ * Parse a `YYYY-MM-DD` date-picker string into a LOCAL-midnight Date.
+ *
+ * `new Date("2026-01-01")` is a date-ONLY ISO string, which the spec parses
+ * as UTC midnight, not local midnight. For anyone east of UTC (Ethiopia is
+ * UTC+3) that instant already falls on the PREVIOUS local day, so
+ * `startOfDayIso`/`endOfDayIso` built from it silently shift the picked date
+ * back by one — the picker looks fine, the filtered results are wrong. This
+ * constructor form (`new Date(y, m, d)`) is local by definition; use it for
+ * every date-only string instead of `new Date(dateString)`.
+ */
+export function parseDateStr(dateStr: string): Date {
+  const [y, m, d] = dateStr.split("-").map(Number);
+  return new Date(y, (m || 1) - 1, d || 1);
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/index.ts b/apps/edr-freight-web/backoffice/src/components/filters/index.ts
new file mode 100644
index 000000000..78fceb9ff
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/index.ts
@@ -0,0 +1,10 @@
+export * from "./types";
+export * from "./url";
+export * from "./dates";
+export * from "./useFilters";
+export { FilterBar } from "./FilterBar";
+export type { FilterBarProps } from "./FilterBar";
+export { FilterPill } from "./FilterPill";
+export { SortControl } from "./SortControl";
+export { SavedViews } from "./SavedViews";
+export { MoreFiltersMenu } from "./MoreFiltersMenu";
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/types.ts b/apps/edr-freight-web/backoffice/src/components/filters/types.ts
new file mode 100644
index 000000000..597d74f6f
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/types.ts
@@ -0,0 +1,101 @@
+export type FilterType = "text" | "enum" | "date" | "number" | "boolean";
+
+export type Operator = "is" | "isNot" | "contains" | "between" | "before" | "after";
+
+/** Operator implied by a filter's type when the def doesn't say otherwise. */
+export const DEFAULT_OP: Record<FilterType, Operator> = {
+  text: "contains",
+  enum: "is",
+  date: "between",
+  number: "is",
+  boolean: "is",
+};
+
+export const OPERATOR_LABELS: Record<Operator, string> = {
+  is: "is",
+  isNot: "is not",
+  contains: "contains",
+  between: "is between",
+  before: "is before",
+  after: "is after",
+};
+
+/**
+ * A filter's current value. `v` holds:
+ * - 1 entry for is / isNot / contains / before / after
+ * - 2 entries for between (range)
+ * - n entries for a multi-select enum (isAnyOf is expressed as op "is" + n values)
+ */
+export interface FilterValue {
+  op: Operator;
+  v: string[];
+}
+
+export interface FilterOption {
+  value: string;
+  label: string;
+}
+
+export interface FacetBucket {
+  value: string;
+  count: number;
+}
+
+interface FilterDefBase {
+  /** URL key and, by default, the API param name. */
+  key: string;
+  /** Plain string — the caller applies i18n's t() before passing it in. */
+  label: string;
+  type: FilterType;
+  /** Defaults to `[DEFAULT_OP[type]]`. Widen only where the endpoint implements it. */
+  operators?: Operator[];
+  /** Pill text override. Default: "Label | value(s)". */
+  format?: (v: FilterValue, def: FilterDef) => string;
+  /** Map to API query params. Default `{ [key]: v.join(",") }`. */
+  toParams?: (v: FilterValue) => Record<string, string | undefined>;
+  /** Lives behind "More filters" until it has a value. Default false. */
+  secondary?: boolean;
+}
+
+export interface TextFilterDef extends FilterDefBase {
+  type: "text";
+  placeholder?: string;
+}
+
+export interface EnumFilterDef extends FilterDefBase {
+  type: "enum";
+  options: FilterOption[];
+  /** Default true — checkbox list. false renders a single-select radio list. */
+  multiple?: boolean;
+  /** value -> count in the current (filtered) result set. Absent = no counts, hide nothing. */
+  counts?: Record<string, number>;
+}
+
+export interface DateFilterDef extends FilterDefBase {
+  type: "date";
+  calendar?: "gregorian" | "ethiopian";
+}
+
+export interface NumberFilterDef extends FilterDefBase {
+  type: "number";
+  unit?: string;
+}
+
+export interface BooleanFilterDef extends FilterDefBase {
+  type: "boolean";
+  trueLabel?: string;
+  falseLabel?: string;
+}
+
+export type FilterDef =
+  | TextFilterDef
+  | EnumFilterDef
+  | DateFilterDef
+  | NumberFilterDef
+  | BooleanFilterDef;
+
+/** A page's sort options — value is already `"field:DIR"`, the codebase's existing convention. */
+export interface SortOption {
+  value: string;
+  label: string;
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/url.test.ts b/apps/edr-freight-web/backoffice/src/components/filters/url.test.ts
new file mode 100644
index 000000000..55cc42bf2
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/url.test.ts
@@ -0,0 +1,170 @@
+import { describe, expect, it } from "vitest";
+
+import type { FilterDef, FilterValue } from "./types";
+import {
+  decodeFilterValue,
+  encodeFilterValue,
+  parseFilters,
+  parseSort,
+  toApiParams,
+  writeFilter,
+} from "./url";
+
+const STATUS: FilterDef = {
+  key: "statuses",
+  label: "Status",
+  type: "enum",
+  options: [
+    { value: "ACTIVE", label: "Active" },
+    { value: "DRAFT", label: "Draft" },
+  ],
+};
+
+const DIRECTION: FilterDef = {
+  key: "tradeDirection",
+  label: "Direction",
+  type: "enum",
+  multiple: false,
+  options: [{ value: "IMPORT", label: "Import" }],
+};
+
+const SEARCH: FilterDef = { key: "q", label: "Search", type: "text" };
+
+const CREATED: FilterDef = {
+  key: "created",
+  label: "Created",
+  type: "date",
+  toParams: ({ v }) => ({ createdFrom: v[0], createdTo: v[1] }),
+};
+
+describe("encodeFilterValue / decodeFilterValue round-trip", () => {
+  const cases: Array<{ name: string; type: FilterDef["type"]; value: FilterValue }> = [
+    { name: "text contains (default op omitted)", type: "text", value: { op: "contains", v: ["maersk"] } },
+    { name: "enum is (default op omitted, multi value)", type: "enum", value: { op: "is", v: ["ACTIVE", "DRAFT"] } },
+    { name: "enum isNot (non-default op prefixed)", type: "enum", value: { op: "isNot", v: ["GOV"] } },
+    { name: "date between (default op omitted)", type: "date", value: { op: "between", v: ["2026-01-01", "2026-03-01"] } },
+    { name: "date before (non-default op prefixed)", type: "date", value: { op: "before", v: ["2026-01-01"] } },
+    { name: "number is", type: "number", value: { op: "is", v: ["42"] } },
+    { name: "boolean is", type: "boolean", value: { op: "is", v: ["true"] } },
+  ];
+
+  for (const { name, type, value } of cases) {
+    it(`round-trips: ${name}`, () => {
+      const encoded = encodeFilterValue(type, value);
+      const decoded = decodeFilterValue(type, encoded);
+      expect(decoded).toEqual(value);
+    });
+  }
+
+  it("omits the operator prefix only when it is the type default", () => {
+    expect(encodeFilterValue("enum", { op: "is", v: ["ACTIVE"] })).toBe("ACTIVE");
+    expect(encodeFilterValue("enum", { op: "isNot", v: ["ACTIVE"] })).toBe("isNot:ACTIVE");
+  });
+
+  it("never comma-splits a text value, so a literal comma survives", () => {
+    const encoded = encodeFilterValue("text", { op: "contains", v: ["Addis, Ethiopia"] });
+    expect(decodeFilterValue("text", encoded)).toEqual({ op: "contains", v: ["Addis, Ethiopia"] });
+  });
+});
+
+describe("decodeFilterValue malformed-input tolerance", () => {
+  it("returns null for an empty string", () => {
+    expect(decodeFilterValue("text", "")).toBeNull();
+  });
+
+  it("does not treat an unknown prefix as an operator", () => {
+    // "foo" isn't a known Operator, so "foo:bar" is a literal text value, not op:value.
+    expect(decodeFilterValue("text", "foo:bar")).toEqual({ op: "contains", v: ["foo:bar"] });
+  });
+
+  it("degrades a one-sided 'between' to null (not applied) instead of guessing a half-open range", () => {
+    expect(decodeFilterValue("date", "between:2026-01-01")).toBeNull();
+  });
+
+  it("never throws on garbage input", () => {
+    expect(() => decodeFilterValue("enum", "isNot:")).not.toThrow();
+    expect(() => decodeFilterValue("date", "between:")).not.toThrow();
+    expect(() => decodeFilterValue("number", ":::")).not.toThrow();
+  });
+});
+
+describe("parseFilters / writeFilter", () => {
+  it("parses only the defs present, ignoring unrelated params", () => {
+    const params = new URLSearchParams("statuses=ACTIVE,DRAFT&unrelated=x&q=addis");
+    const values = parseFilters([STATUS, SEARCH], params);
+    expect(values).toEqual({
+      statuses: { op: "is", v: ["ACTIVE", "DRAFT"] },
+      q: { op: "contains", v: ["addis"] },
+    });
+  });
+
+  it("writeFilter deletes the param when value is undefined", () => {
+    const params = new URLSearchParams("statuses=ACTIVE");
+    const next = writeFilter(params, STATUS, undefined);
+    expect(next.has("statuses")).toBe(false);
+  });
+
+  it("writeFilter round-trips through parseFilters", () => {
+    const value: FilterValue = { op: "is", v: ["IMPORT"] };
+    const next = writeFilter(new URLSearchParams(), DIRECTION, value);
+    expect(parseFilters([DIRECTION], next)).toEqual({ tradeDirection: value });
+  });
+
+  it("namespaces keys when ns is given, so two tables on one page don't collide", () => {
+    const next = writeFilter(new URLSearchParams(), STATUS, { op: "is", v: ["ACTIVE"] }, "a");
+    expect(next.get("a.statuses")).toBe("ACTIVE");
+    expect(parseFilters([STATUS], new URLSearchParams(), "b")).toEqual({});
+  });
+});
+
+describe("existing deep-link backward compatibility", () => {
+  it("parses the BookingRequestsPage-style ?statuses=A,B&tradeDirection=IMPORT link unchanged", () => {
+    const params = new URLSearchParams("statuses=SUBMITTED,APPROVED&tradeDirection=IMPORT");
+    expect(parseFilters([STATUS, DIRECTION], params)).toEqual({
+      statuses: { op: "is", v: ["SUBMITTED", "APPROVED"] },
+      tradeDirection: { op: "is", v: ["IMPORT"] },
+    });
+  });
+});
+
+describe("parseSort", () => {
+  const options = [
+    { value: "createdAt:DESC", label: "Newest first" },
+    { value: "createdAt:ASC", label: "Oldest first" },
+  ];
+
+  it("returns the fallback when sort is absent", () => {
+    expect(parseSort(new URLSearchParams(), options, "createdAt:DESC")).toBe("createdAt:DESC");
+  });
+
+  it("returns the fallback for an unrecognized sort value", () => {
+    expect(parseSort(new URLSearchParams("sort=bogus:DESC"), options, "createdAt:DESC")).toBe(
+      "createdAt:DESC",
+    );
+  });
+
+  it("returns the URL value when it is a known option", () => {
+    expect(parseSort(new URLSearchParams("sort=createdAt:ASC"), options, "createdAt:DESC")).toBe(
+      "createdAt:ASC",
+    );
+  });
+});
+
+describe("toApiParams", () => {
+  it("uses the default mapping (key: joined csv) when toParams is absent", () => {
+    const values = { statuses: { op: "is" as const, v: ["ACTIVE", "DRAFT"] } };
+    expect(toApiParams([STATUS], values)).toEqual({ statuses: "ACTIVE,DRAFT" });
+  });
+
+  it("uses a custom toParams to reproduce an existing API's exact param names", () => {
+    const values = { created: { op: "between" as const, v: ["2026-01-01", "2026-03-01"] } };
+    expect(toApiParams([CREATED], values)).toEqual({
+      createdFrom: "2026-01-01",
+      createdTo: "2026-03-01",
+    });
+  });
+
+  it("omits defs with no value", () => {
+    expect(toApiParams([STATUS, SEARCH], {})).toEqual({});
+  });
+});
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/url.ts b/apps/edr-freight-web/backoffice/src/components/filters/url.ts
new file mode 100644
index 000000000..014ca5540
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/url.ts
@@ -0,0 +1,117 @@
+import { DEFAULT_OP, type FilterDef, type FilterValue, type Operator } from "./types";
+
+const OPERATORS: readonly Operator[] = ["is", "isNot", "contains", "between", "before", "after"];
+
+/**
+ * Encode one filter value as `[op:]csv`, omitting the operator prefix when it
+ * matches the type's default — that keeps the common case short and, more
+ * importantly, keeps the existing `?statuses=A,B` deep links this app already
+ * generates (e.g. the header document-review alarm) parsing identically.
+ *
+ * `,` and `:` are structural inside an encoded value. A `text` filter is
+ * never comma-split (its `v` always has exactly one entry), which is what
+ * lets a free-text search contain a literal comma safely.
+ * ponytail: if a value ever legitimately needs a literal "op:" prefix or a
+ * comma inside a multi-value filter, switch that filter to a JSON-in-one-param
+ * encoding rather than trying to escape these two characters.
+ */
+export function encodeFilterValue(type: FilterDef["type"], value: FilterValue): string {
+  const csv = value.v.map(encodeURIComponent).join(",");
+  return value.op === DEFAULT_OP[type] ? csv : `${value.op}:${csv}`;
+}
+
+/** Inverse of `encodeFilterValue`. Returns null for anything malformed — a bad
+ * URL is user input and must degrade to "filter not applied", never throw. */
+export function decodeFilterValue(type: FilterDef["type"], raw: string): FilterValue | null {
+  if (!raw) return null;
+  const firstColon = raw.indexOf(":");
+  let op: Operator = DEFAULT_OP[type];
+  let rest = raw;
+  if (firstColon > 0) {
+    const prefix = raw.slice(0, firstColon);
+    if ((OPERATORS as string[]).includes(prefix)) {
+      op = prefix as Operator;
+      rest = raw.slice(firstColon + 1);
+    }
+  }
+  // Text filters are single-value and never comma-split, so a literal comma
+  // in a search term round-trips unchanged.
+  const v =
+    type === "text"
+      ? [decodeURIComponent(rest)]
+      : rest.split(",").filter(Boolean).map(decodeURIComponent);
+  if (v.length === 0) return null;
+  // A malformed range (wrong arity) has no safe single-sided interpretation —
+  // "between:2026-01-01" doesn't say whether that's the from or the to — so
+  // it degrades to "filter not applied" rather than guessing a half-open range.
+  if (op === "between" && v.length !== 2) return null;
+  return { op, v };
+}
+
+/** Every FilterDef's current value, parsed from the URL. Unknown/malformed entries are dropped. */
+export function parseFilters(
+  defs: FilterDef[],
+  params: URLSearchParams,
+  ns?: string,
+): Record<string, FilterValue> {
+  const out: Record<string, FilterValue> = {};
+  for (const def of defs) {
+    const raw = params.get(nsKey(def.key, ns));
+    if (!raw) continue;
+    const value = decodeFilterValue(def.type, raw);
+    if (value) out[def.key] = value;
+  }
+  return out;
+}
+
+/** Write (or delete) one filter's value into a URLSearchParams, returning a new instance. */
+export function writeFilter(
+  params: URLSearchParams,
+  def: FilterDef,
+  value: FilterValue | undefined,
+  ns?: string,
+): URLSearchParams {
+  const next = new URLSearchParams(params);
+  const key = nsKey(def.key, ns);
+  if (!value || value.v.length === 0) next.delete(key);
+  else next.set(key, encodeFilterValue(def.type, value));
+  return next;
+}
+
+function nsKey(key: string, ns?: string): string {
+  return ns ? `${ns}.${key}` : key;
+}
+
+/** `?sort=field:DIR` -> `"field:DIR"`, defaulting when absent/unrecognized. */
+export function parseSort(params: URLSearchParams, options: { value: string }[], fallback: string): string {
+  const raw = params.get("sort");
+  if (raw && options.some((o) => o.value === raw)) return raw;
+  return fallback;
+}
+
+/**
+ * Flatten every def's parsed value into the flat param object a page's
+ * react-query filter object / axios params already expect. `toParams`
+ * defaults to `{ [key]: v.join(",") }`, which reproduces exactly what
+ * `?statuses=A,B` meant before this bar existed.
+ */
+export function toApiParams(
+  defs: FilterDef[],
+  values: Record<string, FilterValue>,
+): Record<string, string | undefined> {
+  const out: Record<string, string | undefined> = {};
+  for (const def of defs) {
+    const value = values[def.key];
+    if (!value) continue;
+    const mapped = def.toParams ? def.toParams(value) : { [def.key]: value.v.join(",") };
+    Object.assign(out, mapped);
+  }
+  return out;
+}
+
+/** Delete emptystring/undefined/null entries — never send them, never write them to the URL. */
+export function cleanParams<T extends Record<string, unknown>>(params: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(params).filter(([, v]) => v !== undefined && v !== null && v !== ""),
+  ) as Partial<T>;
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/useFilters.ts b/apps/edr-freight-web/backoffice/src/components/filters/useFilters.ts
new file mode 100644
index 000000000..c7fe5a2cd
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/useFilters.ts
@@ -0,0 +1,219 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useSearchParams } from "react-router-dom";
+import { useDebouncedValue } from "@mantine/hooks";
+
+import type { DataTablePagination, DataTableProps } from "@edr/ui-common";
+import type { FilterDef, FilterValue } from "./types";
+import { cleanParams, parseFilters, toApiParams, writeFilter } from "./url";
+
+export interface UseFiltersOptions {
+  /** value = "field:DIR", matching the codebase's existing sort convention. */
+  defaultSort?: string;
+  pageSize?: number;
+  /** "page" (freight: {page,pageSize}) or "skip" (record-management: {skip,take}). */
+  paginationStyle?: "page" | "skip";
+  /** Namespaces URL keys ("<ns>.<key>") for pages with two independent tables. */
+  ns?: string;
+  /** Search box debounce, ms. */
+  searchDebounceMs?: number;
+}
+
+export interface UseFilters {
+  values: Record<string, FilterValue>;
+  /** Flat params ready for the react-query key + axios `params` — IS the query key input. */
+  params: Record<string, string | number>;
+  sort: string;
+  page: number;
+  pageSize: number;
+  searchText: string;
+  setSearchText: (s: string) => void;
+  setFilter: (key: string, value: FilterValue | undefined) => void;
+  removeFilter: (key: string) => void;
+  clearFilters: () => void;
+  setSort: (s: string) => void;
+  setPage: (p: number) => void;
+  activeCount: number;
+  /** Spread onto <DataTable/>. Same shape useListControls.tableProps returns today. */
+  tableProps: (total: number) => Pick<DataTableProps<any, any>, "pagination" | "tableOptions">;
+  /** Replace the whole URL (saved-view restore). Pushes, so Back undoes it. */
+  applyQueryString: (query: string) => void;
+  /** Current filter state as a raw query string, for saving as a view (page stripped). */
+  currentQueryString: () => string;
+}
+
+const DEFAULT_PAGE_SIZE = 10;
+
+export function useFilters(defs: FilterDef[], options: UseFiltersOptions = {}): UseFilters {
+  const {
+    defaultSort = "",
+    pageSize: defaultPageSize = DEFAULT_PAGE_SIZE,
+    paginationStyle = "page",
+    ns,
+    searchDebounceMs = 300,
+  } = options;
+
+  const [sp, setSp] = useSearchParams();
+  const searchKey = ns ? `${ns}.q` : "q";
+  const pageKey = ns ? `${ns}.page` : "page";
+
+  const values = useMemo(() => parseFilters(defs, sp, ns), [defs, sp, ns]);
+  const sort = sp.get(ns ? `${ns}.sort` : "sort") ?? defaultSort;
+  const page = Math.max(1, Number(sp.get(pageKey)) || 1);
+  const pageSize = defaultPageSize;
+
+  // Free text: local draft debounced into the URL with `replace`, so typing
+  // leaves exactly one history entry instead of one per keystroke.
+  const [searchText, setSearchTextState] = useState(() => sp.get(searchKey) ?? "");
+  const [debouncedSearch] = useDebouncedValue(searchText, searchDebounceMs);
+
+  useEffect(() => {
+    const urlValue = sp.get(searchKey) ?? "";
+    if (urlValue === debouncedSearch) return;
+    setSp(
+      (prev) => {
+        const next = new URLSearchParams(prev);
+        if (debouncedSearch) next.set(searchKey, debouncedSearch);
+        else next.delete(searchKey);
+        next.delete(pageKey);
+        return next;
+      },
+      { replace: true },
+    );
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [debouncedSearch]);
+
+  useEffect(() => {
+    // External navigation (back/forward, saved-view restore, deep link) —
+    // sync the local draft from the URL. Comparing against the debounced
+    // value (not `searchText`) is what stops this from clobbering an
+    // in-flight keystroke: mid-type, urlValue !== debouncedSearch is expected.
+    const urlValue = sp.get(searchKey) ?? "";
+    if (urlValue !== debouncedSearch) setSearchTextState(urlValue);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sp]);
+
+  const setFilter = useCallback(
+    (key: string, value: FilterValue | undefined) => {
+      const def = defs.find((d) => d.key === key);
+      if (!def) return;
+      setSp((prev) => {
+        const next = writeFilter(prev, def, value, ns);
+        next.delete(pageKey);
+        return next;
+      });
+    },
+    [defs, ns, pageKey, setSp],
+  );
+
+  const removeFilter = useCallback((key: string) => setFilter(key, undefined), [setFilter]);
+
+  const clearFilters = useCallback(() => {
+    setSp((prev) => {
+      const next = new URLSearchParams(prev);
+      for (const def of defs) next.delete(ns ? `${ns}.${def.key}` : def.key);
+      next.delete(searchKey);
+      next.delete(pageKey);
+      return next;
+    });
+    setSearchTextState("");
+  }, [defs, ns, pageKey, searchKey, setSp]);
+
+  const setSort = useCallback(
+    (value: string) => {
+      setSp((prev) => {
+        const next = new URLSearchParams(prev);
+        const key = ns ? `${ns}.sort` : "sort";
+        if (value === defaultSort) next.delete(key);
+        else next.set(key, value);
+        next.delete(pageKey);
+        return next;
+      });
+    },
+    [defaultSort, ns, pageKey, setSp],
+  );
+
+  const setPage = useCallback(
+    (p: number) => {
+      setSp((prev) => {
+        const next = new URLSearchParams(prev);
+        if (p <= 1) next.delete(pageKey);
+        else next.set(pageKey, String(p));
+        return next;
+      });
+    },
+    [pageKey, setSp],
+  );
+
+  const params = useMemo(() => {
+    const filterParams = toApiParams(defs, values);
+    const base: Record<string, string | number | undefined> =
+      paginationStyle === "skip"
+        ? { skip: (page - 1) * pageSize, take: pageSize }
+        : { page, pageSize };
+    if (debouncedSearch) base.search = debouncedSearch;
+    if (sort) {
+      if (paginationStyle === "skip") base.orderBy = sort;
+      else {
+        const [sortBy, sortOrder] = sort.split(":");
+        base.sortBy = sortBy;
+        base.sortOrder = sortOrder;
+      }
+    }
+    return cleanParams({ ...filterParams, ...base }) as Record<string, string | number>;
+  }, [defs, values, paginationStyle, page, pageSize, debouncedSearch, sort]);
+
+  const activeCount = Object.keys(values).length + (debouncedSearch ? 1 : 0);
+
+  const tableProps = useCallback(
+    (total: number): Pick<DataTableProps<any, any>, "pagination" | "tableOptions"> => {
+      const pageCount = Math.max(1, Math.ceil(total / pageSize));
+      const pagination: DataTablePagination = { pageIndex: page - 1, pageSize, pageCount, totalCount: total };
+      return {
+        pagination,
+        tableOptions: {
+          manualPagination: true,
+          pageCount,
+          state: { pagination: { pageIndex: page - 1, pageSize } },
+          onPaginationChange: (updater) => {
+            const current = { pageIndex: page - 1, pageSize };
+            const next = typeof updater === "function" ? updater(current) : updater;
+            setPage(next.pageIndex + 1);
+          },
+        },
+      };
+    },
+    [page, pageSize, setPage],
+  );
+
+  const applyQueryString = useCallback(
+    (query: string) => setSp(new URLSearchParams(query)),
+    [setSp],
+  );
+
+  const currentQueryString = useCallback(() => {
+    const next = new URLSearchParams(sp);
+    next.delete(pageKey);
+    return next.toString();
+  }, [sp, pageKey]);
+
+  return {
+    values,
+    params,
+    sort,
+    page,
+    pageSize,
+    searchText,
+    setSearchText: setSearchTextState,
+    setFilter,
+    removeFilter,
+    clearFilters,
+    setSort,
+    setPage,
+    activeCount,
+    tableProps,
+    applyQueryString,
+    currentQueryString,
+  };
+}
+
+export { toApiParams } from "./url";
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
index cade8cc34..e50a090a2 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
@@ -3,20 +3,11 @@ import { useMyTradeAccess } from "@/hooks/useMyTradeAccess";
 import {
   ActionIcon,
   Box,
-  Button,
   Card,
-  Collapse,
-  Group,
-  MultiSelect,
-  Select,
   Stack,
   Text,
-  TextInput,
   ThemeIcon,
 } from "@mantine/core";
-import { DatePickerInput } from "@mantine/dates";
-import { getDateRangePresets } from "@/components/common/dateRangePresets";
-import { useDebouncedValue } from "@mantine/hooks";
 import {
   AlertTriangle,
   ArrowRight,
@@ -24,20 +15,16 @@ import {
   CheckCircle2,
   Clock,
   FileText,
-  FilterX,
   Inbox,
   LayoutList,
   RefreshCw,
   Repeat,
-  Search,
   User,
-  X,
 } from "lucide-react";
-import { useCallback, useMemo, useState, type ReactNode } from "react";
+import { useCallback, useMemo, type ReactNode } from "react";
 import { useNavigate } from "react-router-dom";
 
 import { ContractStatusBadge } from "@/components/contracts/ContractStatusBadge";
-import { FilterToggle } from "@/components/common/FilterToggle";
 import { bookingTable } from "@/components/bookings/booking-ui.styles";
 import { KpiStrip, PageContainer, PageHeader } from "@/components/page";
 import {
@@ -61,9 +48,9 @@ import {
   Badge,
   DataTable,
   DataTableFooter,
-  usePagination,
   type ColumnDef,
 } from "@edr/ui-common";
+import { FilterBar, useFilters, type FilterDef } from "@/components/filters";
 
 /** Every filterable status — the pill tabs are gone, so the select carries them all. */
 const STATUS_OPTIONS = CONTRACT_LIST_TABS.flatMap((t) => t.statuses ?? []).map(
@@ -112,99 +99,74 @@ const COLUMN_META = {
   cellClassName: "whitespace-normal break-words align-top",
 };
 
-/** Local start-of-day → ISO, for inclusive "from" date filters. */
-function startOfDayIso(d: Date): string {
-  const x = new Date(d);
-  x.setHours(0, 0, 0, 0);
-  return x.toISOString();
-}
-
-/** Local end-of-day → ISO, for inclusive "to" date filters. */
-function endOfDayIso(d: Date): string {
-  const x = new Date(d);
-  x.setHours(23, 59, 59, 999);
-  return x.toISOString();
-}
-
 export default function ContractRequestsPage() {
   const navigate = useNavigate();
-  const { pagination, setPagination } = usePagination({ pageSize: 10 });
-  const [query, setQuery] = useState("");
-  const [debouncedQuery] = useDebouncedValue(query, 300);
-  // Filter controls (empty/null = "all").
-  const [statusFilter, setStatusFilter] = useState<string[]>([]);
   const { filterOptions } = useMyTradeAccess();
-  const [directionFilter, setDirectionFilter] = useState<string | null>(null);
-  const [freightTypeFilter, setFreightTypeFilter] = useState<string | null>(
-    null,
+
+  // Static shape only (no facet counts) — this is what useFilters needs to
+  // parse the URL and build API params. Counts are attached separately below,
+  // for rendering only, once the summary query (which itself depends on
+  // these params) has resolved.
+  const filterDefs: FilterDef[] = useMemo(
+    () => [
+      { key: "statuses", label: "Status", type: "enum", options: STATUS_OPTIONS },
+      {
+        key: "contractKind",
+        label: "Kind",
+        type: "enum",
+        multiple: false,
+        options: CONTRACT_KIND_OPTIONS,
+      },
+      {
+        key: "tradeDirection",
+        label: "Direction",
+        type: "enum",
+        multiple: false,
+        options: filterOptions(TRADE_DIRECTION_OPTIONS),
+        secondary: true,
+      },
+      {
+        key: "freightType",
+        label: "Freight",
+        type: "enum",
+        multiple: false,
+        options: FREIGHT_TYPE_OPTIONS,
+        secondary: true,
+      },
+      {
+        key: "paymentCurrency",
+        label: "Currency",
+        type: "enum",
+        multiple: false,
+        options: CURRENCY_OPTIONS,
+        secondary: true,
+      },
+      {
+        key: "created",
+        label: "Created",
+        type: "date",
+        secondary: true,
+        // DateBody already converts to start/end-of-day ISO before calling
+        // onChange, so this just routes to the API's existing param names.
+        toParams: ({ v }) => ({ createdFrom: v[0], createdTo: v[1] }),
+      },
+    ],
+    [filterOptions],
   );
-  const [kindFilter, setKindFilter] = useState<string | null>(null);
-  const [currencyFilter, setCurrencyFilter] = useState<string | null>(null);
-  const [createdFrom, setCreatedFrom] = useState<Date | null>(null);
-  const [createdTo, setCreatedTo] = useState<Date | null>(null);
-  const [sort, setSort] = useState<string>("createdAt:DESC");
-  // All filters start empty (no URL params on this page), so collapsed is safe.
-  const [showAdvanced, setShowAdvanced] = useState(false);
 
-  const resetPage = useCallback(() => {
-    setPagination({ pageIndex: 0, pageSize: pagination.pageSize });
-  }, [setPagination, pagination.pageSize]);
+  const controls = useFilters(filterDefs, {
+    defaultSort: "createdAt:DESC",
+    pageSize: 10,
+  });
 
-  const filter: ContractListFilter = useMemo(() => {
-    const [sortBy, sortOrder] = sort.split(":") as [string, "ASC" | "DESC"];
-    return {
-      page: pagination.pageIndex + 1,
-      pageSize: pagination.pageSize,
-      sortBy,
-      sortOrder,
+  const filter: ContractListFilter = useMemo(
+    () => ({
+      ...(controls.params as unknown as ContractListFilter),
       // Kept as the React Query cache-key discriminator (tabs themselves are gone).
       tab: "all",
-      // Server-side free-text search (contract reference, customer name).
-      ...(debouncedQuery.trim() ? { search: debouncedQuery.trim() } : {}),
-      ...(statusFilter.length ? { statuses: statusFilter.join(",") } : {}),
-      ...(directionFilter ? { tradeDirection: directionFilter } : {}),
-      ...(freightTypeFilter ? { freightType: freightTypeFilter } : {}),
-      ...(kindFilter ? { contractKind: kindFilter } : {}),
-      ...(currencyFilter ? { paymentCurrency: currencyFilter } : {}),
-      ...(createdFrom ? { createdFrom: startOfDayIso(createdFrom) } : {}),
-      ...(createdTo ? { createdTo: endOfDayIso(createdTo) } : {}),
-    };
-  }, [
-    pagination.pageIndex,
-    pagination.pageSize,
-    debouncedQuery,
-    statusFilter,
-    directionFilter,
-    freightTypeFilter,
-    kindFilter,
-    currencyFilter,
-    createdFrom,
-    createdTo,
-    sort,
-  ]);
-
-  const activeFilterCount =
-    (statusFilter.length ? 1 : 0) +
-    (directionFilter ? 1 : 0) +
-    (freightTypeFilter ? 1 : 0) +
-    (kindFilter ? 1 : 0) +
-    (currencyFilter ? 1 : 0) +
-    (createdFrom || createdTo ? 1 : 0);
-
-  // Badge on the advanced-filters toggle — active filters hidden behind it.
-  const advancedFilterCount =
-    activeFilterCount - (statusFilter.length ? 1 : 0) - (kindFilter ? 1 : 0);
-
-  const clearFilters = useCallback(() => {
-    setStatusFilter([]);
-    setDirectionFilter(null);
-    setFreightTypeFilter(null);
-    setKindFilter(null);
-    setCurrencyFilter(null);
-    setCreatedFrom(null);
-    setCreatedTo(null);
-    setPagination({ pageIndex: 0, pageSize: pagination.pageSize });
-  }, [setPagination, pagination.pageSize]);
+    }),
+    [controls.params],
+  );
 
   const { data, isLoading, isError, refetch, isFetching } =
     useContractList(filter);
@@ -214,13 +176,27 @@ export default function ContractRequestsPage() {
     refetch: refetchSummary,
   } = useContractListSummary(filter);
 
+  const statusCounts = useMemo(
+    () => Object.fromEntries((summary?.facets?.status ?? []).map((b) => [b.value, b.count])),
+    [summary?.facets],
+  );
+
+  // filterDefs + counts, for the bar to render. Kept separate from filterDefs
+  // itself so the URL-parsing hook above never has to wait on this query.
+  const defs: FilterDef[] = useMemo(
+    () =>
+      filterDefs.map((d) =>
+        d.key === "statuses" && d.type === "enum" ? { ...d, counts: statusCounts } : d,
+      ),
+    [filterDefs, statusCounts],
+  );
+
   const rows = useMemo(
     () => (data?.items ?? []).map(toContractListRow),
     [data?.items],
   );
 
   const total = data?.total ?? 0;
-  const pageCount = Math.max(1, Math.ceil(total / pagination.pageSize));
   const showEmpty = !isLoading && !isError && rows.length === 0;
 
   const metrics = summary?.metrics;
@@ -450,153 +426,14 @@ export default function ContractRequestsPage() {
 
         <Card p={0}>
           <Stack gap={0}>
-            <Box px="md" pt="md" pb="sm" w="100%">
-              <Stack gap="sm">
-                <Group gap="sm" wrap="wrap">
-                  <TextInput
-                    placeholder="Search reference or customer…"
-                    leftSection={<Search size={18} />}
-                    value={query}
-                    onChange={(e) => {
-                      setQuery(e.target.value);
-                      resetPage();
-                    }}
-                    rightSection={
-                      query && (
-                        <ActionIcon
-                          size="sm"
-                          color="gray"
-                          radius="md"
-                          variant="transparent"
-                          onClick={() => {
-                            setQuery("");
-                            resetPage();
-                          }}
-                        >
-                          <X size={16} />
-                        </ActionIcon>
-                      )
-                    }
-                    style={{ flex: 1, minWidth: "200px" }}
-                    radius="lg"
-                  />
-                  <Select
-                    data={SORT_OPTIONS}
-                    value={sort}
-                    onChange={(v) => {
-                      setSort(v ?? "createdAt:DESC");
-                      resetPage();
-                    }}
-                    allowDeselect={false}
-                    radius="lg"
-                    style={{ minWidth: 170 }}
-                    aria-label="Sort contracts"
-                  />
-                  <MultiSelect
-                    placeholder={
-                      statusFilter.length ? undefined : "All statuses"
-                    }
-                    data={STATUS_OPTIONS}
-                    value={statusFilter}
-                    onChange={(v) => {
-                      setStatusFilter(v);
-                      resetPage();
-                    }}
-                    clearable
-                    searchable
-                    radius="lg"
-                    style={{ minWidth: 220 }}
-                    aria-label="Filter by status"
-                  />
-                  <Select
-                    placeholder="All kinds"
-                    data={CONTRACT_KIND_OPTIONS}
-                    value={kindFilter}
-                    onChange={(v) => {
-                      setKindFilter(v);
-                      resetPage();
-                    }}
-                    clearable
-                    radius="lg"
-                    style={{ minWidth: 160 }}
-                    aria-label="Filter by contract kind"
-                  />
-                  <FilterToggle
-                    count={advancedFilterCount}
-                    expanded={showAdvanced}
-                    onClick={() => setShowAdvanced((v) => !v)}
-                  />
-                  {activeFilterCount > 0 ? (
-                    <Button
-                      variant="subtle"
-                      color="gray"
-                      radius="lg"
-                      leftSection={<FilterX size={16} />}
-                      onClick={clearFilters}
-                    >
-                      Clear filters ({activeFilterCount})
-                    </Button>
-                  ) : null}
-                </Group>
-                <Collapse expanded={showAdvanced}>
-                <Group gap="sm" wrap="wrap">
-                  <Select
-                    placeholder="All directions"
-                    data={filterOptions(TRADE_DIRECTION_OPTIONS)}
-                    value={directionFilter}
-                    onChange={(v) => {
-                      setDirectionFilter(v);
-                      resetPage();
-                    }}
-                    clearable
-                    radius="lg"
-                    style={{ minWidth: 150 }}
-                    aria-label="Filter by trade direction"
-                  />
-                  <Select
-                    placeholder="All freight types"
-                    data={FREIGHT_TYPE_OPTIONS}
-                    value={freightTypeFilter}
-                    onChange={(v) => {
-                      setFreightTypeFilter(v);
-                      resetPage();
-                    }}
-                    clearable
-                    radius="lg"
-                    style={{ minWidth: 160 }}
-                    aria-label="Filter by freight type"
-                  />
-                  <Select
-                    placeholder="All currencies"
-                    data={CURRENCY_OPTIONS}
-                    value={currencyFilter}
-                    onChange={(v) => {
-                      setCurrencyFilter(v);
-                      resetPage();
-                    }}
-                    clearable
-                    radius="lg"
-                    style={{ minWidth: 140 }}
-                    aria-label="Filter by payment currency"
-                  />
-                  <DatePickerInput
-                    type="range"
-                    placeholder="Created date range"
-                    value={[createdFrom, createdTo]}
-                    onChange={([from, to]) => {
-                      setCreatedFrom(from ? new Date(from) : null);
-                      setCreatedTo(to ? new Date(to) : null);
-                      resetPage();
-                    }}
-                    presets={getDateRangePresets()}
-                    clearable
-                    radius="lg"
-                    style={{ minWidth: 220 }}
-                    aria-label="Created date range"
-                  />
-                </Group>
-                </Collapse>
-              </Stack>
+            <Box px="md" pt="sm" pb="xs" w="100%">
+              <FilterBar
+                defs={defs}
+                controls={controls}
+                searchPlaceholder="Search reference or customer…"
+                sortOptions={SORT_OPTIONS}
+                viewId="contract-requests"
+              />
             </Box>
 
             {showEmpty ? (
@@ -615,18 +452,7 @@ export default function ContractRequestsPage() {
                     isLoading ? "loading" : isError ? "error" : "success"
                   }
                   onRowClick={handleRowClick}
-                  pagination={{
-                    pageIndex: pagination.pageIndex,
-                    pageSize: pagination.pageSize,
-                    pageCount,
-                    totalCount: total,
-                  }}
-                  tableOptions={{
-                    state: { pagination },
-                    onPaginationChange: setPagination,
-                    manualPagination: true,
-                    pageCount,
-                  }}
+                  {...controls.tableProps(total)}
                   // table-fixed makes the per-column widths stick; without
                   // it auto-layout re-widens columns once cells wrap.
                   containerClassName="border-0 shadow-none bg-transparent [&_table]:table-fixed [&_table]:min-w-[960px]"
diff --git a/apps/edr-freight-web/backoffice/src/services/contracts.service.ts b/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
index 69ee89ca5..01dbadac7 100644
--- a/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
@@ -91,6 +91,13 @@ export interface ContractListSummaryTabs {
 export interface ContractListSummary {
   metrics: ContractListSummaryMetrics;
   tabs: ContractListSummaryTabs;
+  /**
+   * Per-column value counts for the filter bar's enum popovers, scoped to
+   * every OTHER currently-active filter. Optional: pages built before the
+   * pill filter bar don't read it, and it degrades gracefully — an absent
+   * key just means that popover shows no counts.
+   */
+  facets?: Record<string, { value: string; count: number }[]>;
 }
 
 export interface ContractView {

From bec9575311d61323207ef58109776c26b563040a Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Fri, 14 Aug 2026 13:48:54 +0000
Subject: [PATCH 097/174] refactor(filter-bar): saved views as auto-named
 cards, not a name-prompt menu
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the modal "type a name to save" flow with a one-click Save that
auto-generates the label from the active filters (describeQuery, reusing
the same formatter FilterPill uses for pill text — one source of truth,
nothing to type, nothing to fall out of sync). Saved views render as a
grid of cards at the top of the filter bar instead of being buried in a
dropdown.

- useSavedViews: localStorage state, extracted so FilterBar owns one
  instance instead of two components each subscribing separately
- SaveViewButton: filled (not outline) since it's the one action-y
  control among a row of filter pills; flashes to a disabled "Saved" +
  checkmark state for 1.5s on click, in addition to the corner toast —
  the toast alone wasn't registering as feedback
- SavedViewCards: click to apply, per-card delete, active one highlighted
- moved from the wrapping filter-pill row into the pinned right-hand zone
  (with sort) behind its own divider, so it can't shove pills around
- Save icon: BookmarkPlus -> Save (floppy disk reads as "save" faster)
- More filters button: outline/gray -> default variant — same low-
  contrast-outline problem the inactive filter pill had
- Clear button font bumped xs -> sm to match the rest of the bar
---
 .../src/components/filters/FilterBar.tsx      |  55 ++++++---
 .../src/components/filters/FilterPill.tsx     |  15 +--
 .../components/filters/MoreFiltersMenu.tsx    |   5 +-
 .../src/components/filters/SaveViewButton.tsx |  46 ++++++++
 .../src/components/filters/SavedViewCards.tsx |  67 +++++++++++
 .../src/components/filters/SavedViews.tsx     | 107 ------------------
 .../src/components/filters/format.ts          |  36 ++++++
 .../src/components/filters/index.ts           |   5 +-
 .../src/components/filters/useSavedViews.ts   |  32 ++++++
 9 files changed, 227 insertions(+), 141 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/SaveViewButton.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/SavedViewCards.tsx
 delete mode 100644 apps/edr-freight-web/backoffice/src/components/filters/SavedViews.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/format.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/useSavedViews.ts

diff --git a/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx b/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
index 96aaaa22d..154ce3155 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
@@ -6,8 +6,10 @@ import type { FilterDef, SortOption } from "./types";
 import type { UseFilters } from "./useFilters";
 import { FilterPill } from "./FilterPill";
 import { MoreFiltersMenu } from "./MoreFiltersMenu";
-import { SavedViews } from "./SavedViews";
+import { SaveViewButton } from "./SaveViewButton";
+import { SavedViewCards } from "./SavedViewCards";
 import { SortControl } from "./SortControl";
+import { useSavedViews } from "./useSavedViews";
 
 export interface FilterBarProps {
   defs: FilterDef[];
@@ -44,22 +46,32 @@ export function FilterBar({
     ...pinned.filter((d) => !controls.values[d.key]),
   ];
 
-  return (
-    // Two independent flex zones, not one big wrapping Group: the left side
-    // (search + pills + more filters + clear) wraps to as many lines as it
-    // needs; the right side (sort) stays put on the first line — `nowrap` +
-    // `flexShrink: 0` on the right zone stop it from ever getting pushed
-    // down when the left side overflows.
-    <div style={{ display: "flex", alignItems: "flex-start", gap: 8, flexWrap: "nowrap" }}>
-      <Group gap="xs" wrap="wrap" align="center" style={{ flex: 1, minWidth: 0 }}>
-        {viewId && (
-          <SavedViews
-            viewId={viewId}
-            currentQueryString={controls.currentQueryString}
-            applyQueryString={controls.applyQueryString}
-          />
-        )}
+  // Unconditional call (rules of hooks) — viewId is a per-page constant, and
+  // the hook is a no-op storage key when saved views aren't wired up.
+  const savedViews = useSavedViews(viewId ?? "__unset__");
+  const activeQuery = controls.currentQueryString();
+  const hasMatchingView = savedViews.views.some((v) => v.query === activeQuery);
+  const canSaveView = Boolean(viewId) && activeQuery.length > 0 && !hasMatchingView;
 
+  return (
+    <div>
+      {viewId && (
+        <SavedViewCards
+          defs={defs}
+          views={savedViews.views}
+          activeQuery={activeQuery}
+          applyQueryString={controls.applyQueryString}
+          onRemove={savedViews.remove}
+        />
+      )}
+
+      {/* Two independent flex zones, not one big wrapping Group: the left side
+          (search + pills + more filters + clear) wraps to as many lines as it
+          needs; the right side (sort) stays put on the first line — `nowrap` +
+          `flexShrink: 0` on the right zone stop it from ever getting pushed
+          down when the left side overflows. */}
+      <div style={{ display: "flex", alignItems: "flex-start", gap: 8, flexWrap: "nowrap" }}>
+      <Group gap="xs" wrap="wrap" align="center" style={{ flex: 1, minWidth: 0 }}>
         {showSearch && (
           <TextInput
             placeholder={searchPlaceholder}
@@ -89,7 +101,7 @@ export function FilterBar({
 
         {controls.activeCount > 0 && (
           <Anchor
-            size="xs"
+            size="sm"
             c="red.6"
             underline="never"
             onClick={() => {
@@ -98,7 +110,7 @@ export function FilterBar({
             }}
             style={{ display: "inline-flex", alignItems: "center", gap: 4 }}
           >
-            <Trash2 size={13} />
+            <Trash2 size={14} />
             Clear
           </Anchor>
         )}
@@ -115,7 +127,14 @@ export function FilterBar({
             <SortControl options={sortOptions} value={controls.sort} onChange={controls.setSort} />
           </>
         )}
+        {canSaveView && (
+          <>
+            <Divider orientation="vertical" />
+            <SaveViewButton defs={defs} query={activeQuery} onSave={savedViews.save} />
+          </>
+        )}
       </Group>
+      </div>
     </div>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx b/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx
index 40ba372f8..7a4a76998 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx
@@ -3,6 +3,7 @@ import { ActionIcon, Button, Popover } from "@mantine/core";
 import { Plus, X } from "lucide-react";
 
 import type { FilterDef, FilterValue } from "./types";
+import { formatFilterValue } from "./format";
 import { BooleanBody } from "./bodies/BooleanBody";
 import { DateBody } from "./bodies/DateBody";
 import { EnumBody } from "./bodies/EnumBody";
@@ -17,18 +18,6 @@ const BODIES: Record<FilterDef["type"], React.ComponentType<any>> = {
   boolean: BooleanBody,
 };
 
-function formatValue(def: FilterDef, value: FilterValue): string {
-  if (def.format) return def.format(value, def);
-  if (def.type === "enum") {
-    const labels = value.v.map((v) => def.options.find((o) => o.value === v)?.label ?? v);
-    return labels.join(", ");
-  }
-  if (def.type === "date" && value.v.length === 2) {
-    return `${value.v[0].slice(0, 10)} → ${value.v[1].slice(0, 10)}`;
-  }
-  return value.v.join(", ");
-}
-
 export interface FilterPillProps {
   def: FilterDef;
   value: FilterValue | undefined;
@@ -77,7 +66,7 @@ export function FilterPill({ def, value, onChange, autoOpen }: FilterPillProps)
           }
           onClick={() => setOpened((o) => !o)}
         >
-          {active ? `${def.label} | ${formatValue(def, value!)}` : def.label}
+          {active ? `${def.label} | ${formatFilterValue(def, value!)}` : def.label}
         </Button>
       </Popover.Target>
       <Popover.Dropdown miw={260} p="xs">
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/MoreFiltersMenu.tsx b/apps/edr-freight-web/backoffice/src/components/filters/MoreFiltersMenu.tsx
index 2dc6c1240..c557bbbc3 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/MoreFiltersMenu.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/MoreFiltersMenu.tsx
@@ -29,8 +29,9 @@ export function MoreFiltersMenu({ defs, onPick }: MoreFiltersMenuProps) {
         <Button
           size="xs"
           radius="xl"
-          variant="outline"
-          color="gray"
+          // "default" (opaque border + solid text), not "outline" (faint
+          // color-tinted border/text) — same fix as the inactive filter pill.
+          variant="default"
           leftSection={<Plus size={16} />}
           onClick={() => setOpened((o) => !o)}
         >
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/SaveViewButton.tsx b/apps/edr-freight-web/backoffice/src/components/filters/SaveViewButton.tsx
new file mode 100644
index 000000000..54db1da70
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/SaveViewButton.tsx
@@ -0,0 +1,46 @@
+import { useState } from "react";
+import { Button } from "@mantine/core";
+import { Check, Save } from "lucide-react";
+
+import { useToast } from "@/hooks/use-toast";
+import type { FilterDef } from "./types";
+import { describeQuery } from "./format";
+import type { SavedView } from "./useSavedViews";
+
+export interface SaveViewButtonProps {
+  defs: FilterDef[];
+  query: string;
+  onSave: (query: string) => SavedView;
+}
+
+/** Filled, not outline — this is the one action-y button in the bar (every
+ * other control here is a filter), so it needs to actually look like a
+ * button. One click, no name prompt: the card grid's label is generated
+ * from the active filters (see `describeQuery`). */
+export function SaveViewButton({ defs, query, onSave }: SaveViewButtonProps) {
+  const { toast } = useToast();
+  const [justSaved, setJustSaved] = useState(false);
+
+  const handleSave = () => {
+    onSave(query);
+    toast({ title: "View saved", description: describeQuery(defs, query), duration: 4000 });
+    // The toast is in the corner; this flash is right where the eye already
+    // is — the actual confirmation that "the saving" registered.
+    setJustSaved(true);
+    setTimeout(() => setJustSaved(false), 1500);
+  };
+
+  return (
+    <Button
+      size="sm"
+      radius="xl"
+      variant="filled"
+      color={justSaved ? "teal" : "edr-green"}
+      leftSection={justSaved ? <Check size={15} /> : <Save size={15} />}
+      onClick={handleSave}
+      disabled={justSaved}
+    >
+      {justSaved ? "Saved" : "Save"}
+    </Button>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/SavedViewCards.tsx b/apps/edr-freight-web/backoffice/src/components/filters/SavedViewCards.tsx
new file mode 100644
index 000000000..bce4c235e
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/SavedViewCards.tsx
@@ -0,0 +1,67 @@
+import { ActionIcon, Card, SimpleGrid, Text } from "@mantine/core";
+import { Trash2 } from "lucide-react";
+
+import { useToast } from "@/hooks/use-toast";
+import type { FilterDef } from "./types";
+import { describeQuery } from "./format";
+import type { SavedView } from "./useSavedViews";
+
+export interface SavedViewCardsProps {
+  defs: FilterDef[];
+  views: SavedView[];
+  activeQuery: string;
+  applyQueryString: (query: string) => void;
+  onRemove: (id: string) => void;
+}
+
+/** Saved views up front as a grid of cards — not one more item buried in a
+ * dropdown nobody opens. Renders nothing until there's at least one saved. */
+export function SavedViewCards({ defs, views, activeQuery, applyQueryString, onRemove }: SavedViewCardsProps) {
+  const { toast } = useToast();
+  if (views.length === 0) return null;
+
+  return (
+    <SimpleGrid cols={{ base: 2, sm: 3, md: 4, lg: 5 }} spacing="xs" mb="sm">
+      {views.map((v) => {
+        const active = v.query === activeQuery;
+        const label = describeQuery(defs, v.query);
+        return (
+          <Card
+            key={v.id}
+            withBorder
+            padding="xs"
+            radius="md"
+            onClick={() => {
+              applyQueryString(v.query);
+              toast({ title: `Switched to "${label}"` });
+            }}
+            style={{
+              cursor: "pointer",
+              borderColor: active ? "var(--mantine-color-edr-green-6)" : undefined,
+              borderWidth: active ? 2 : 1,
+              backgroundColor: active ? "var(--mantine-color-edr-green-0)" : undefined,
+            }}
+          >
+            <div style={{ display: "flex", alignItems: "flex-start", justifyContent: "space-between", gap: 6 }}>
+              <Text size="xs" fw={500} lineClamp={2} style={{ flex: 1 }}>
+                {label}
+              </Text>
+              <ActionIcon
+                size="xs"
+                color="red"
+                variant="subtle"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onRemove(v.id);
+                  toast({ title: "View deleted", description: label, variant: "destructive" });
+                }}
+              >
+                <Trash2 size={12} />
+              </ActionIcon>
+            </div>
+          </Card>
+        );
+      })}
+    </SimpleGrid>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/SavedViews.tsx b/apps/edr-freight-web/backoffice/src/components/filters/SavedViews.tsx
deleted file mode 100644
index 826356159..000000000
--- a/apps/edr-freight-web/backoffice/src/components/filters/SavedViews.tsx
+++ /dev/null
@@ -1,107 +0,0 @@
-import { useState } from "react";
-import { ActionIcon, Button, Menu, Modal, Stack, Text, TextInput } from "@mantine/core";
-import { useLocalStorage } from "@mantine/hooks";
-import { Bookmark, Check, Save, Trash2 } from "lucide-react";
-
-interface SavedView {
-  id: string;
-  name: string;
-  query: string;
-}
-
-export interface SavedViewsProps {
-  /** localStorage namespace — one page, not one user (single staff login per
-   * browser profile). ponytail: add ":<userId>" if shared-terminal login appears. */
-  viewId: string;
-  currentQueryString: () => string;
-  applyQueryString: (query: string) => void;
-}
-
-/** URL always wins: this menu only ever WRITES the URL, on click. Nothing
- * reads a saved view at mount, so a shared link always beats a saved view —
- * there is no "which one applies" branch to get wrong. */
-export function SavedViews({ viewId, currentQueryString, applyQueryString }: SavedViewsProps) {
-  const [views, setViews] = useLocalStorage<SavedView[]>({
-    key: `edr:saved-views:${viewId}`,
-    defaultValue: [],
-  });
-  const [saveOpen, setSaveOpen] = useState(false);
-  const [name, setName] = useState("");
-
-  const activeQuery = currentQueryString();
-  const active = views.find((v) => v.query === activeQuery);
-
-  const save = () => {
-    if (!name.trim()) return;
-    setViews((prev) => [
-      ...prev,
-      { id: crypto.randomUUID(), name: name.trim(), query: currentQueryString() },
-    ]);
-    setName("");
-    setSaveOpen(false);
-  };
-
-  const remove = (id: string) => setViews((prev) => prev.filter((v) => v.id !== id));
-
-  return (
-    <>
-      <Menu position="bottom-start" withinPortal shadow="md">
-        <Menu.Target>
-          <Button size="xs" variant="subtle" color="gray" leftSection={<Bookmark size={14} />}>
-            {active?.name ?? "All"}
-          </Button>
-        </Menu.Target>
-        <Menu.Dropdown miw={220}>
-          {views.length === 0 && (
-            <Menu.Item disabled>
-              <Text size="xs" c="dimmed">
-                No saved views yet
-              </Text>
-            </Menu.Item>
-          )}
-          {views.map((v) => (
-            <Menu.Item
-              key={v.id}
-              leftSection={v.id === active?.id ? <Check size={14} /> : <span style={{ width: 14 }} />}
-              rightSection={
-                <ActionIcon
-                  size="xs"
-                  color="red"
-                  variant="subtle"
-                  onClick={(e) => {
-                    e.stopPropagation();
-                    remove(v.id);
-                  }}
-                >
-                  <Trash2 size={12} />
-                </ActionIcon>
-              }
-              onClick={() => applyQueryString(v.query)}
-            >
-              {v.name}
-            </Menu.Item>
-          ))}
-          <Menu.Divider />
-          <Menu.Item leftSection={<Save size={14} />} onClick={() => setSaveOpen(true)}>
-            Save current view…
-          </Menu.Item>
-        </Menu.Dropdown>
-      </Menu>
-
-      <Modal opened={saveOpen} onClose={() => setSaveOpen(false)} title="Save current view" size="sm">
-        <Stack gap="sm">
-          <TextInput
-            placeholder="View name"
-            value={name}
-            onChange={(e) => setName(e.currentTarget.value)}
-            onKeyDown={(e) => e.key === "Enter" && save()}
-            autoFocus
-          />
-          <Button onClick={save} disabled={!name.trim()}>
-            Save
-          </Button>
-        </Stack>
-      </Modal>
-    </>
-  );
-}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/format.ts b/apps/edr-freight-web/backoffice/src/components/filters/format.ts
new file mode 100644
index 000000000..c3ca16798
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/format.ts
@@ -0,0 +1,36 @@
+import { parseFilters } from "./url";
+import type { FilterDef, FilterValue } from "./types";
+
+/** Human-readable text for one filter's current value — same text a
+ * FilterPill shows, and what a saved view's auto-generated label is built
+ * from, so both read identically with zero duplicated logic. */
+export function formatFilterValue(def: FilterDef, value: FilterValue): string {
+  if (def.format) return def.format(value, def);
+  if (def.type === "enum") {
+    const labels = value.v.map((v) => def.options.find((o) => o.value === v)?.label ?? v);
+    return labels.join(", ");
+  }
+  if (def.type === "date" && value.v.length === 2) {
+    return `${value.v[0].slice(0, 10)} → ${value.v[1].slice(0, 10)}`;
+  }
+  return value.v.join(", ");
+}
+
+/**
+ * Auto-generated label for a saved view — "Status: Active, Draft · Direction:
+ * Import" — built straight from the filters it holds, instead of asking the
+ * user to type a name (which drifts out of sync with what the view actually
+ * filters the moment they edit it). Falls back to "All" when nothing decodes,
+ * though a view is only ever offered for saving with at least one active filter.
+ *
+ * Namespace-aware pages (`useFilters({ ns })`, for a second table on the same
+ * page) aren't decoded here — every current saved-view page is single-table.
+ * Thread `ns` through if/when that changes.
+ */
+export function describeQuery(defs: FilterDef[], query: string): string {
+  const values = parseFilters(defs, new URLSearchParams(query));
+  const parts = defs
+    .filter((d) => values[d.key])
+    .map((d) => `${d.label}: ${formatFilterValue(d, values[d.key])}`);
+  return parts.length ? parts.join(" · ") : "All";
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/index.ts b/apps/edr-freight-web/backoffice/src/components/filters/index.ts
index 78fceb9ff..0e3e533bd 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/index.ts
+++ b/apps/edr-freight-web/backoffice/src/components/filters/index.ts
@@ -1,10 +1,13 @@
 export * from "./types";
 export * from "./url";
 export * from "./dates";
+export * from "./format";
 export * from "./useFilters";
+export * from "./useSavedViews";
 export { FilterBar } from "./FilterBar";
 export type { FilterBarProps } from "./FilterBar";
 export { FilterPill } from "./FilterPill";
 export { SortControl } from "./SortControl";
-export { SavedViews } from "./SavedViews";
+export { SaveViewButton } from "./SaveViewButton";
+export { SavedViewCards } from "./SavedViewCards";
 export { MoreFiltersMenu } from "./MoreFiltersMenu";
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/useSavedViews.ts b/apps/edr-freight-web/backoffice/src/components/filters/useSavedViews.ts
new file mode 100644
index 000000000..f08738562
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/useSavedViews.ts
@@ -0,0 +1,32 @@
+import { useLocalStorage } from "@mantine/hooks";
+
+export interface SavedView {
+  id: string;
+  /** Raw query string ("statuses=ACTIVE&sort=createdAt:DESC") — the label is
+   * derived from this at render time (see format.ts's describeQuery), so
+   * there's nothing else to keep in sync. */
+  query: string;
+  savedAt: number;
+}
+
+/**
+ * localStorage namespace is per PAGE (viewId), not per user — this is a
+ * backoffice, one staff login per browser profile.
+ * ponytail: add ":<userId>" if shared-terminal login appears.
+ */
+export function useSavedViews(viewId: string) {
+  const [views, setViews] = useLocalStorage<SavedView[]>({
+    key: `edr:saved-views:${viewId}`,
+    defaultValue: [],
+  });
+
+  const save = (query: string): SavedView => {
+    const view: SavedView = { id: crypto.randomUUID(), query, savedAt: Date.now() };
+    setViews((prev) => [...prev, view]);
+    return view;
+  };
+
+  const remove = (id: string) => setViews((prev) => prev.filter((v) => v.id !== id));
+
+  return { views, save, remove };
+}

From 524f9aab56632799e6e26da328ef1c3d05c5c42b Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Fri, 14 Aug 2026 13:51:48 +0000
Subject: [PATCH 098/174] fix(filter-bar): responsive layout broken on narrow
 viewports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The two-zone layout (left: filters, right: sort+save) hardcoded
flexWrap: "nowrap" on the outer container so the right zone would never
get pushed below the left on desktop. On a phone that's the same
two-column squeeze with no room for either side: the search box and
right-hand controls got clipped/overlapped instead of stacking.

- outer container: flex-col below the `sm` breakpoint (stacks to two full-
  width rows), flex-row + nowrap at `sm` and up (the original two-zone,
  right-pinned behavior)
- right zone swapped from <Group wrap="nowrap"> to a plain div with
  Tailwind classes — Group's `wrap` prop sets an inline flex-wrap style,
  which always wins over a `sm:flex-nowrap` class regardless of
  breakpoint, so the old responsive attempt could never have worked
- search input's hardcoded minWidth: 220 (wider than a lot of phones)
  dropped to a shrinkable 160
- saved-view card grid: base 2 columns forced text-clipping card overflow
  on a phone; base is now 1, growing to 2+ only once there's room
---
 .../src/components/filters/FilterBar.tsx      | 30 ++++++++++++-------
 .../src/components/filters/SavedViewCards.tsx |  5 +++-
 2 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx b/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
index 154ce3155..a712d189e 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
@@ -65,13 +65,17 @@ export function FilterBar({
         />
       )}
 
-      {/* Two independent flex zones, not one big wrapping Group: the left side
-          (search + pills + more filters + clear) wraps to as many lines as it
-          needs; the right side (sort) stays put on the first line — `nowrap` +
-          `flexShrink: 0` on the right zone stop it from ever getting pushed
-          down when the left side overflows. */}
-      <div style={{ display: "flex", alignItems: "flex-start", gap: 8, flexWrap: "nowrap" }}>
-      <Group gap="xs" wrap="wrap" align="center" style={{ flex: 1, minWidth: 0 }}>
+      {/*
+        Two independent zones on wide screens — left (search + pills + more
+        filters + clear) wraps to as many lines as it needs, right (sort +
+        save) stays pinned on the first line via `sm:flex-nowrap` +
+        `sm:shrink-0`. `nowrap` unconditionally (the old inline style) forced
+        that same two-column layout on a phone too: neither zone had room and
+        both got squeezed/clipped. Below the `sm` breakpoint this stacks to a
+        single column instead — full-width left row, full-width right row.
+      */}
+      <div className="flex flex-col sm:flex-row sm:flex-nowrap items-start gap-2">
+      <Group gap="xs" wrap="wrap" align="center" className="flex-1 min-w-0 w-full">
         {showSearch && (
           <TextInput
             placeholder={searchPlaceholder}
@@ -80,7 +84,7 @@ export function FilterBar({
             onChange={(e) => controls.setSearchText(e.currentTarget.value)}
             size="xs"
             radius="lg"
-            style={{ minWidth: 220 }}
+            style={{ minWidth: 160, flex: "1 1 160px" }}
           />
         )}
 
@@ -119,7 +123,13 @@ export function FilterBar({
       {/* Sorting is a different kind of control (view order, not scope) —
           cut off from the filter pills by a vertical divider and pinned to
           the right, independent of how the left side wraps. */}
-      <Group gap="xs" wrap="nowrap" style={{ flexShrink: 0 }}>
+      {/*
+        Plain div, not <Group>: Group's `wrap` prop sets an inline
+        flex-wrap style, which always beats a Tailwind class regardless of
+        breakpoint — `sm:flex-nowrap` would never win against `wrap="wrap"`.
+        Wrap on mobile (own row, room is tight), pinned nowrap from `sm` up.
+      */}
+      <div className="flex flex-wrap sm:flex-nowrap items-center gap-2 shrink-0">
         {children}
         {sortOptions && sortOptions.length > 0 && (
           <>
@@ -133,7 +143,7 @@ export function FilterBar({
             <SaveViewButton defs={defs} query={activeQuery} onSave={savedViews.save} />
           </>
         )}
-      </Group>
+      </div>
       </div>
     </div>
   );
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/SavedViewCards.tsx b/apps/edr-freight-web/backoffice/src/components/filters/SavedViewCards.tsx
index bce4c235e..9cf8c40be 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/SavedViewCards.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/SavedViewCards.tsx
@@ -21,7 +21,10 @@ export function SavedViewCards({ defs, views, activeQuery, applyQueryString, onR
   if (views.length === 0) return null;
 
   return (
-    <SimpleGrid cols={{ base: 2, sm: 3, md: 4, lg: 5 }} spacing="xs" mb="sm">
+    // base: 1 — a phone-width viewport forcing 2 columns is what clipped
+    // card text and overflowed the row; one full-width card per row until
+    // there's actually room for more.
+    <SimpleGrid cols={{ base: 1, xs: 2, sm: 3, md: 4, lg: 5 }} spacing="xs" mb="sm">
       {views.map((v) => {
         const active = v.query === activeQuery;
         const label = describeQuery(defs, v.query);

From d94c444a51552b691f15621bf231bb58c23f98be Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Fri, 14 Aug 2026 14:03:33 +0000
Subject: [PATCH 099/174] feat(filter-bar): fix pageSize bug, add client
 bridge, migrate 4 more pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

fix(useFilters): pageSize was a hardcoded constant, never read from the
URL, with no setter — the DataTable/RuleEngineListFooter page-size
dropdown silently did nothing on every page using the filter bar,
including the already-shipped ContractRequestsPage pilot. Added a `size`
URL param (mirrors `page`), `setPageSize`, and wired
`tableProps().onPaginationChange` to route page-size vs page-index
changes to the right setter instead of only ever calling setPage().

feat(clientFilter): applyClientFilters — the Family-B bridge the plan
called for. Generalizes ListControls'/useListControls' one hardcoded
search box + one date range to every FilterDef, matched against
`row[def.key]`. Reuses matchesDayRange/toDayString from
hooks/useListControls.ts (imported, not duplicated) so the inclusive-
range/timezone-safe semantics stay defined in exactly one place. Lets a
page ship the full pill-bar UI immediately and flip to server-side
filtering later by deleting one function call — no endpoint changes
required up front.

Migrated to the filter bar (mechanical, pattern established by
ContractRequestsPage):
- WarehouseInvoicesPage, LoadedInventoryPage, TrucksOnSitePage — Family B
  (ListControls/useListControls → FilterBar + applyClientFilters)
- CustomersPage — Family A (useState bag → useFilters), no filter pills
  needed here (search + sort only), the SegmentedControl "view" stays
  page-level tab state (like ContractStatusTabs), not a filter pill —
  it now resets the page via controls.setPage(1) on change, the same
  hazard useFilters already guards its own filters against
---
 .../src/components/filters/clientFilter.ts    | 93 +++++++++++++++++
 .../src/components/filters/index.ts           |  1 +
 .../src/components/filters/useFilters.ts      | 23 ++++-
 .../src/pages/customers/CustomersPage.tsx     | 99 +++++--------------
 .../pages/warehouses/LoadedInventoryPage.tsx  | 40 ++++----
 .../src/pages/warehouses/TrucksOnSitePage.tsx | 58 ++++++-----
 .../warehouses/WarehouseInvoicesPage.tsx      | 67 +++++++------
 7 files changed, 234 insertions(+), 147 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/clientFilter.ts

diff --git a/apps/edr-freight-web/backoffice/src/components/filters/clientFilter.ts b/apps/edr-freight-web/backoffice/src/components/filters/clientFilter.ts
new file mode 100644
index 000000000..ae0034cbb
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/clientFilter.ts
@@ -0,0 +1,93 @@
+import { matchesDayRange, toDayString } from "@/hooks/useListControls";
+import type { FilterDef, FilterValue } from "./types";
+
+export { matchesDayRange, toDayString };
+
+const readField = (row: unknown, key: string): unknown =>
+  row && typeof row === "object" ? (row as Record<string, unknown>)[key] : undefined;
+
+export interface ClientFilterOptions<T> {
+  /** Row fields matched against the free-text search box. */
+  searchKeys?: (keyof T)[];
+  /** Custom search extractor when the value isn't a top-level field. */
+  searchValue?: (row: T) => string;
+}
+
+/**
+ * Client-side bridge for pages whose endpoint doesn't (yet) accept
+ * filter/sort/pagination params — the Family-B pages this app inherited from
+ * `ListControls`/`useListControls`. Same idea, generalized: instead of one
+ * hardcoded search box + one date range, every `FilterDef` is matched
+ * against `row[def.key]` (override the def's `key` to line up with the row
+ * shape, or filter/map the rows before calling this).
+ *
+ * Flip a page to server mode later by deleting the `applyClientFilters` call
+ * and passing `controls.params` straight to the API — `useFilters`'s output
+ * shape doesn't change either way.
+ *
+ * ponytail: linear scan per keystroke, no debounce — matches
+ * `useListControls`'s existing behavior at this data size (~1k rows,
+ * `useListControls.ts:4-18`). Move to server-side filtering if a list
+ * outgrows that.
+ */
+export function applyClientFilters<T>(
+  rows: T[],
+  defs: FilterDef[],
+  values: Record<string, FilterValue>,
+  searchText: string,
+  options: ClientFilterOptions<T> = {},
+): T[] {
+  const term = searchText.trim().toLowerCase();
+  const { searchKeys = [], searchValue } = options;
+
+  return rows.filter((row) => {
+    if (term) {
+      const haystack = searchValue
+        ? searchValue(row)
+        : searchKeys.map((k) => String(readField(row, String(k)) ?? "")).join(" ");
+      if (!haystack.toLowerCase().includes(term)) return false;
+    }
+    for (const def of defs) {
+      const value = values[def.key];
+      if (!value) continue;
+      if (!matchesFilter(def, value, readField(row, def.key))) return false;
+    }
+    return true;
+  });
+}
+
+function matchesFilter(def: FilterDef, value: FilterValue, raw: unknown): boolean {
+  switch (def.type) {
+    case "enum": {
+      const inSet = value.v.includes(String(raw ?? ""));
+      return value.op === "isNot" ? !inSet : inSet;
+    }
+    case "date": {
+      if (value.op === "between") {
+        return matchesDayRange(raw, value.v[0]?.slice(0, 10) ?? null, value.v[1]?.slice(0, 10) ?? null);
+      }
+      const day = toDayString(raw);
+      const target = value.v[0]?.slice(0, 10);
+      if (!day || !target) return false;
+      return value.op === "before" ? day <= target : day >= target;
+    }
+    case "number": {
+      const num = Number(raw);
+      if (Number.isNaN(num)) return false;
+      if (value.op === "between") {
+        const [min, max] = value.v.map(Number);
+        return num >= min && num <= max;
+      }
+      return value.op === "isNot" ? num !== Number(value.v[0]) : num === Number(value.v[0]);
+    }
+    case "boolean":
+      return Boolean(raw) === (value.v[0] === "true");
+    case "text": {
+      const rawStr = String(raw ?? "").toLowerCase();
+      const target = (value.v[0] ?? "").toLowerCase();
+      return value.op === "isNot" ? !rawStr.includes(target) : rawStr.includes(target);
+    }
+    default:
+      return true;
+  }
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/index.ts b/apps/edr-freight-web/backoffice/src/components/filters/index.ts
index 0e3e533bd..5fe7702f3 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/index.ts
+++ b/apps/edr-freight-web/backoffice/src/components/filters/index.ts
@@ -2,6 +2,7 @@ export * from "./types";
 export * from "./url";
 export * from "./dates";
 export * from "./format";
+export * from "./clientFilter";
 export * from "./useFilters";
 export * from "./useSavedViews";
 export { FilterBar } from "./FilterBar";
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/useFilters.ts b/apps/edr-freight-web/backoffice/src/components/filters/useFilters.ts
index c7fe5a2cd..7c4dfbf43 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/useFilters.ts
+++ b/apps/edr-freight-web/backoffice/src/components/filters/useFilters.ts
@@ -32,6 +32,7 @@ export interface UseFilters {
   clearFilters: () => void;
   setSort: (s: string) => void;
   setPage: (p: number) => void;
+  setPageSize: (size: number) => void;
   activeCount: number;
   /** Spread onto <DataTable/>. Same shape useListControls.tableProps returns today. */
   tableProps: (total: number) => Pick<DataTableProps<any, any>, "pagination" | "tableOptions">;
@@ -55,11 +56,12 @@ export function useFilters(defs: FilterDef[], options: UseFiltersOptions = {}):
   const [sp, setSp] = useSearchParams();
   const searchKey = ns ? `${ns}.q` : "q";
   const pageKey = ns ? `${ns}.page` : "page";
+  const sizeKey = ns ? `${ns}.size` : "size";
 
   const values = useMemo(() => parseFilters(defs, sp, ns), [defs, sp, ns]);
   const sort = sp.get(ns ? `${ns}.sort` : "sort") ?? defaultSort;
   const page = Math.max(1, Number(sp.get(pageKey)) || 1);
-  const pageSize = defaultPageSize;
+  const pageSize = Math.max(1, Number(sp.get(sizeKey)) || defaultPageSize);
 
   // Free text: local draft debounced into the URL with `replace`, so typing
   // leaves exactly one history entry instead of one per keystroke.
@@ -144,6 +146,19 @@ export function useFilters(defs: FilterDef[], options: UseFiltersOptions = {}):
     [pageKey, setSp],
   );
 
+  const setPageSize = useCallback(
+    (size: number) => {
+      setSp((prev) => {
+        const next = new URLSearchParams(prev);
+        if (size === defaultPageSize) next.delete(sizeKey);
+        else next.set(sizeKey, String(size));
+        next.delete(pageKey); // a different page size invalidates the current page index
+        return next;
+      });
+    },
+    [defaultPageSize, sizeKey, pageKey, setSp],
+  );
+
   const params = useMemo(() => {
     const filterParams = toApiParams(defs, values);
     const base: Record<string, string | number | undefined> =
@@ -177,12 +192,13 @@ export function useFilters(defs: FilterDef[], options: UseFiltersOptions = {}):
           onPaginationChange: (updater) => {
             const current = { pageIndex: page - 1, pageSize };
             const next = typeof updater === "function" ? updater(current) : updater;
-            setPage(next.pageIndex + 1);
+            if (next.pageSize !== pageSize) setPageSize(next.pageSize);
+            else if (next.pageIndex !== current.pageIndex) setPage(next.pageIndex + 1);
           },
         },
       };
     },
-    [page, pageSize, setPage],
+    [page, pageSize, setPage, setPageSize],
   );
 
   const applyQueryString = useCallback(
@@ -209,6 +225,7 @@ export function useFilters(defs: FilterDef[], options: UseFiltersOptions = {}):
     clearFilters,
     setSort,
     setPage,
+    setPageSize,
     activeCount,
     tableProps,
     applyQueryString,
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 23120f98f..91bb72fdc 100644
--- a/apps/edr-freight-web/backoffice/src/pages/customers/CustomersPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/customers/CustomersPage.tsx
@@ -5,13 +5,10 @@ import {
   Card,
   Group,
   SegmentedControl,
-  Select,
   Stack,
   Text,
-  TextInput,
   Tooltip,
 } from "@mantine/core";
-import { useDebouncedValue } from "@mantine/hooks";
 import { useQuery } from "@tanstack/react-query";
 import {
   Building2,
@@ -22,10 +19,8 @@ import {
   Mail,
   Phone,
   RefreshCw,
-  Search,
   ShieldOff,
   Users,
-  X,
 } from "lucide-react";
 import { useMemo, useState } from "react";
 import { useNavigate } from "react-router-dom";
@@ -40,12 +35,8 @@ import { KpiStrip, PageContainer, PageHeader } from "@/components/page";
 import { api } from "@/services/api";
 import type { Company, CompanyStatus } from "@/types/customer";
 import { isOnboardingDraft } from "@/types/customer";
-import {
-  DataTable,
-  DataTableFooter,
-  usePagination,
-  type ColumnDef,
-} from "@edr/ui-common";
+import { DataTable, DataTableFooter, type ColumnDef } from "@edr/ui-common";
+import { FilterBar, useFilters, type FilterDef } from "@/components/filters";
 
 /**
  * The list's segmented views. "Pending approval" means submitted-and-awaiting-
@@ -92,28 +83,29 @@ const SORT_OPTIONS = [
   { value: "name:DESC", label: "Name (Z–A)" },
 ] as const;
 
+/** No filter pills — search/sort/page are the only real filter dimensions;
+ * `view` below is a tab (mutually exclusive, navigational), not a filter. */
+const NO_FILTER_DEFS: FilterDef[] = [];
+
 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>("review:DESC");
+  const controls = useFilters(NO_FILTER_DEFS, { defaultSort: "review:DESC", pageSize: 10 });
 
   const filter = useMemo(() => {
-    const [sortBy, sortOrder] = sort.split(":") as [
+    const [sortBy, sortOrder] = controls.sort.split(":") as [
       "review" | "name" | "createdAt" | "updatedAt",
       "ASC" | "DESC",
     ];
     return {
-      page: pagination.pageIndex + 1,
-      pageSize: pagination.pageSize,
-      search: debouncedQuery,
+      page: controls.page,
+      pageSize: controls.pageSize,
+      search: String(controls.params.search ?? ""),
       sortBy,
       sortOrder,
       ...VIEW_FILTERS[view],
     };
-  }, [pagination.pageIndex, pagination.pageSize, debouncedQuery, view, sort]);
+  }, [controls.page, controls.pageSize, controls.params.search, controls.sort, view]);
 
   const { data: stats } = useQuery(
     api.customers.stats.queryOptions({ input: {} }),
@@ -125,7 +117,6 @@ export default function CustomersPage() {
 
   const rows = data?.items ?? [];
   const total = data?.total ?? 0;
-  const pageCount = Math.max(1, Math.ceil(total / pagination.pageSize));
 
   const columns: ColumnDef<Company>[] = useMemo(
     () => [
@@ -295,35 +286,24 @@ export default function CustomersPage() {
       <Card p={0}>
         <Stack gap={0}>
           <Box px="md" pt="md" pb="sm" w="100%">
-            <Group justify="space-between" gap="md" wrap="wrap">
-              <TextInput
-                placeholder="Search by company, TIN, email or profile reference…"
-                leftSection={<Search size={18} />}
-                value={query}
-                onChange={(e) => setQuery(e.target.value)}
-                rightSection={
-                  query ? (
-                    <ActionIcon
-                      size="sm"
-                      color="gray"
-                      radius="md"
-                      variant="transparent"
-                      onClick={() => setQuery("")}
-                    >
-                      <X size={16} />
-                    </ActionIcon>
-                  ) : null
-                }
-                style={{ flex: 1, minWidth: "240px" }}
-                radius="lg"
-              />
+            <FilterBar
+              defs={NO_FILTER_DEFS}
+              controls={controls}
+              searchPlaceholder="Search by company, TIN, email or profile reference…"
+              sortOptions={SORT_OPTIONS.map((o) => ({ ...o }))}
+              viewId="customers"
+            >
               <SegmentedControl
                 size="sm"
                 radius="md"
                 value={view}
                 onChange={(v) => {
+                  // `view` lives outside useFilters (it's a tab, not a
+                  // filter pill), so switching it needs its own page reset —
+                  // the same "stranded on page 5" hazard useFilters guards
+                  // against for its own filters.
                   setView(v as CustomerView);
-                  setPagination((prev) => ({ ...prev, pageIndex: 0 }));
+                  controls.setPage(1);
                 }}
                 data={[
                   { label: "All", value: "all" },
@@ -333,21 +313,7 @@ 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 }))}
-              />
-            </Group>
+            </FilterBar>
           </Box>
 
           <Box style={{ overflowX: "auto" }} w="100%">
@@ -358,7 +324,7 @@ export default function CustomersPage() {
                 status={isLoading ? "loading" : isError ? "error" : "success"}
                 onRowClick={(row) => navigate(`/dashboard/customers/${row.id}`)}
                 emptyMessage={
-                  debouncedQuery
+                  controls.searchText
                     ? "No companies match your search."
                     : "No companies yet."
                 }
@@ -370,18 +336,7 @@ export default function CustomersPage() {
                     }
                     : undefined
                 }
-                pagination={{
-                  pageIndex: pagination.pageIndex,
-                  pageSize: pagination.pageSize,
-                  pageCount,
-                  totalCount: total,
-                }}
-                tableOptions={{
-                  state: { pagination },
-                  onPaginationChange: setPagination,
-                  manualPagination: true,
-                  pageCount,
-                }}
+                {...controls.tableProps(total)}
                 containerClassName="border-0 shadow-none bg-transparent"
                 footer={DataTableFooter}
               />
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/LoadedInventoryPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/LoadedInventoryPage.tsx
index dbf7b14e3..d3a249395 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/LoadedInventoryPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/LoadedInventoryPage.tsx
@@ -1,7 +1,6 @@
 import { Badge, Card, Group, Text } from '@mantine/core';
 import { DataTable, type ColumnDef } from '@edr/ui-common';
-import ListControls from '@/components/common/ListControls';
-import { useListControls } from '@/hooks/useListControls';
+import { applyClientFilters, FilterBar, useFilters, type FilterDef } from '@/components/filters';
 
 import { PageContainer, PageHeader } from '@/components/page';
 import { useQuery } from '@tanstack/react-query';
@@ -63,16 +62,27 @@ const columns: ColumnDef<Loading>[] = [
   },
 ];
 
+const LOADING_FILTER_DEFS: FilterDef[] = [{ key: 'loadedAt', label: 'Loaded', type: 'date' }];
+
 /** Record of every inventory item loaded onto a wagon. */
 export default function LoadedInventoryPage() {
   const { data, isLoading } = useQuery(
     api.warehouses.loadings.queryOptions({ input: {} }),
   );
   const loadings = data ?? [];
-  const controls = useListControls(loadings, {
-    searchKeys: ['wagonNumber'],
-    dateKey: 'loadedAt',
-  });
+  const controls = useFilters(LOADING_FILTER_DEFS, { pageSize: 10 });
+  // Endpoint takes no params at all — everything filters client-side.
+  const filteredLoadings = applyClientFilters(
+    loadings,
+    LOADING_FILTER_DEFS,
+    controls.values,
+    controls.searchText,
+    { searchKeys: ['wagonNumber'] },
+  );
+  const pagedLoadings = filteredLoadings.slice(
+    (controls.page - 1) * controls.pageSize,
+    controls.page * controls.pageSize,
+  );
 
   return (
     <PageContainer>
@@ -90,24 +100,18 @@ export default function LoadedInventoryPage() {
           />
         ) : (
           <>
-            <ListControls
-              search={controls.search}
-              onSearchChange={controls.setSearch}
+            <FilterBar
+              defs={LOADING_FILTER_DEFS}
+              controls={controls}
               searchPlaceholder="Search by wagon…"
-              dateFrom={controls.dateFrom}
-              onDateFromChange={controls.setDateFrom}
-              dateTo={controls.dateTo}
-              onDateToChange={controls.setDateTo}
-              dateLabel="Loaded"
-              hasFilters={controls.hasFilters}
-              onReset={controls.reset}
+              viewId="loaded-inventory"
             />
             <DataTable
               columns={columns}
-              data={controls.pagedRows}
+              data={pagedLoadings}
               status={isLoading ? 'loading' : 'success'}
               containerClassName="border-0 shadow-none"
-              {...controls.tableProps}
+              {...controls.tableProps(filteredLoadings.length)}
             />
           </>
         )}
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/TrucksOnSitePage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/TrucksOnSitePage.tsx
index d30f9144b..39f7daac4 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/TrucksOnSitePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/TrucksOnSitePage.tsx
@@ -11,11 +11,10 @@ import {
 } from "@mantine/core";
 
 import { PageContainer, PageHeader } from "@/components/page";
-import ListControls from "@/components/common/ListControls";
 // Generic list footer — already shared by the fleet and train-scheduling lists
 // despite the ruleEngine path; reused here rather than adding a second one.
 import RuleEngineListFooter from "@/components/ruleEngine/RuleEngineListFooter";
-import { useListControls } from "@/hooks/useListControls";
+import { applyClientFilters, FilterBar, useFilters, type FilterDef } from "@/components/filters";
 import { useTrucksOnSite } from "@/hooks/useWarehouses";
 import type { TruckOnSite } from "@/types/warehouse";
 import { formatDateTime } from "@/lib/format";
@@ -142,10 +141,14 @@ function Rows({ rows }: { rows: TruckOnSite[] }) {
   );
 }
 
+const TRUCK_FILTER_DEFS: FilterDef[] = [{ key: "arrivedAt", label: "Arrived", type: "date" }];
+
 export default function TrucksOnSitePage() {
   const { data: trucks = [], isLoading } = useTrucksOnSite();
   // The dashboard's "Trucks on-site" card counts only arrived trucks, so it
-  // deep-links here with ?scope=ON_SITE to land on the matching tab.
+  // deep-links here with ?scope=ON_SITE to land on the matching tab. Read
+  // once at mount, same as before — scope/source stay page-level tab state
+  // (mutually exclusive, dashboard-linked), not filter pills.
   const [searchParams] = useSearchParams();
   const scopeParam = searchParams.get("scope");
   const [scope, setScope] = useState<"ALL" | "ON_SITE" | "INBOUND">(
@@ -153,7 +156,7 @@ export default function TrucksOnSitePage() {
   );
   const [source, setSource] = useState<"ALL" | "CUSTOMER" | "EDR">("ALL");
 
-  // Scope/source are page filters and run first; the shared control then does
+  // Scope/source are page filters and run first; the filter bar then does
   // search + arrival-date range + pagination over what they leave.
   const scoped = useMemo(
     () =>
@@ -163,10 +166,14 @@ export default function TrucksOnSitePage() {
     [trucks, scope, source],
   );
 
-  const controls = useListControls(scoped, {
+  const controls = useFilters(TRUCK_FILTER_DEFS, { pageSize: 10 });
+  const filteredTrucks = applyClientFilters(scoped, TRUCK_FILTER_DEFS, controls.values, controls.searchText, {
     searchKeys: ["plateNumber", "driverName", "bookingReference", "customerName", "containers"],
-    dateKey: "arrivedAt",
   });
+  const pagedTrucks = filteredTrucks.slice(
+    (controls.page - 1) * controls.pageSize,
+    controls.page * controls.pageSize,
+  );
 
   const onSiteCount = trucks.filter((t) => t.status === "ON_SITE").length;
   const inboundCount = trucks.length - onSiteCount;
@@ -185,7 +192,10 @@ export default function TrucksOnSitePage() {
           <SegmentedControl
             size="xs"
             value={scope}
-            onChange={(v) => setScope(v as typeof scope)}
+            onChange={(v) => {
+              setScope(v as typeof scope);
+              controls.setPage(1);
+            }}
             data={[
               { label: `All (${trucks.length})`, value: "ALL" },
               { label: `On site (${onSiteCount})`, value: "ON_SITE" },
@@ -195,7 +205,10 @@ export default function TrucksOnSitePage() {
           <SegmentedControl
             size="xs"
             value={source}
-            onChange={(v) => setSource(v as typeof source)}
+            onChange={(v) => {
+              setSource(v as typeof source);
+              controls.setPage(1);
+            }}
             data={[
               { label: "All", value: "ALL" },
               { label: `Customer (${customerCount})`, value: "CUSTOMER" },
@@ -205,30 +218,29 @@ export default function TrucksOnSitePage() {
         </Group>
       </Group>
 
-      <ListControls
-        search={controls.search}
-        onSearchChange={controls.setSearch}
+      <FilterBar
+        defs={TRUCK_FILTER_DEFS}
+        controls={controls}
         searchPlaceholder="Plate, driver, booking, container…"
-        dateFrom={controls.dateFrom}
-        onDateFromChange={controls.setDateFrom}
-        dateTo={controls.dateTo}
-        onDateToChange={controls.setDateTo}
-        dateLabel="Arrived"
-        hasFilters={controls.hasFilters}
-        onReset={controls.reset}
+        viewId="trucks-on-site"
       />
 
       {isLoading ? (
         <Text size="sm">Loading…</Text>
       ) : (
         <>
-          <Rows rows={controls.pagedRows} />
+          <Rows rows={pagedTrucks} />
           <RuleEngineListFooter
-            pagination={controls.pagination}
-            pageCount={controls.pageCount}
-            totalCount={controls.totalCount}
+            pagination={{ pageIndex: controls.page - 1, pageSize: controls.pageSize }}
+            pageCount={Math.max(1, Math.ceil(filteredTrucks.length / controls.pageSize))}
+            totalCount={filteredTrucks.length}
             itemLabel="trucks"
-            onPaginationChange={controls.setPagination}
+            onPaginationChange={(updater) => {
+              const current = { pageIndex: controls.page - 1, pageSize: controls.pageSize };
+              const next = typeof updater === "function" ? updater(current) : updater;
+              if (next.pageSize !== controls.pageSize) controls.setPageSize(next.pageSize);
+              else controls.setPage(next.pageIndex + 1);
+            }}
           />
         </>
       )}
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseInvoicesPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseInvoicesPage.tsx
index 17becfaa6..974755a71 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseInvoicesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseInvoicesPage.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import {
   ActionIcon,
   Badge,
@@ -18,8 +18,7 @@ import {
 import { Ban, CreditCard, DoorOpen, Download, ExternalLink, Eye, Receipt } from 'lucide-react';
 import { useNavigate } from 'react-router-dom';
 import { DataTable, type ColumnDef } from '@edr/ui-common';
-import ListControls from '@/components/common/ListControls';
-import { useListControls } from '@/hooks/useListControls';
+import { applyClientFilters, FilterBar, useFilters, type FilterDef } from '@/components/filters';
 
 import { PageContainer, PageHeader } from '@/components/page';
 import { AccrualDashboard } from '@/components/warehouses';
@@ -54,9 +53,21 @@ const STATUS_COLOR: Record<WarehouseInvoiceStatus, string> = {
 const fmt = (n: number, c: string) => formatMoney(n, c, 2);
 const fmtDate = (d?: string | null) => (d ? new Date(d).toLocaleDateString() : '—');
 
+const INVOICE_FILTER_DEFS: FilterDef[] = [
+  {
+    key: 'status',
+    label: 'Status',
+    type: 'enum',
+    multiple: false,
+    options: WAREHOUSE_INVOICE_STATUSES.map((s) => ({ value: s, label: s.replace(/_/g, ' ') })),
+  },
+  { key: 'issuedAt', label: 'Issued', type: 'date' },
+];
+
 export default function WarehouseInvoicesPage() {
-  const [status, setStatus] = useState<WarehouseInvoiceStatus | null>(null);
   const [detailId, setDetailId] = useState<string | null>(null);
+  const controls = useFilters(INVOICE_FILTER_DEFS, { pageSize: 10 });
+  const status = (controls.values.status?.v[0] as WarehouseInvoiceStatus | undefined) ?? null;
 
   const { data, isLoading } = useQuery(
     api.warehouses.invoices.queryOptions({
@@ -65,10 +76,20 @@ export default function WarehouseInvoicesPage() {
   );
   const invoices = data ?? [];
 
-  const controls = useListControls(invoices, {
-    searchKeys: ['invoiceNumber', 'bookingReference', 'customerName', 'containerNumber'],
-    dateKey: 'issuedAt',
-  });
+  // Endpoint only filters by `status`; search + issued-date range are
+  // applied client-side (the client bridge — see components/filters/clientFilter.ts).
+  // Flip to server mode by deleting this call once the endpoint takes more params.
+  const filteredInvoices = applyClientFilters(
+    invoices,
+    INVOICE_FILTER_DEFS,
+    controls.values,
+    controls.searchText,
+    { searchKeys: ['invoiceNumber', 'bookingReference', 'customerName', 'containerNumber'] },
+  );
+  const pagedInvoices = useMemo(
+    () => filteredInvoices.slice((controls.page - 1) * controls.pageSize, controls.page * controls.pageSize),
+    [filteredInvoices, controls.page, controls.pageSize],
+  );
 
   const invoiceColumns: ColumnDef<WarehouseFeeInvoice>[] = [
     {
@@ -135,36 +156,20 @@ export default function WarehouseInvoicesPage() {
       </Stack>
 
       <Card>
-        <ListControls
-          search={controls.search}
-          onSearchChange={controls.setSearch}
+        <FilterBar
+          defs={INVOICE_FILTER_DEFS}
+          controls={controls}
           searchPlaceholder="Search invoice no / booking / customer"
-          dateFrom={controls.dateFrom}
-          onDateFromChange={controls.setDateFrom}
-          dateTo={controls.dateTo}
-          onDateToChange={controls.setDateTo}
-          dateLabel="Issued"
-          hasFilters={controls.hasFilters}
-          onReset={controls.reset}
-        >
-          <Select
-            label="Status"
-            placeholder="All statuses"
-            data={WAREHOUSE_INVOICE_STATUSES.map((s) => ({ value: s, label: s.replace(/_/g, ' ') }))}
-            value={status}
-            onChange={(v) => setStatus((v as WarehouseInvoiceStatus) ?? null)}
-            clearable
-            w={200}
-          />
-        </ListControls>
+          viewId="warehouse-invoices"
+        />
 
         <DataTable
           columns={invoiceColumns}
-          data={controls.pagedRows}
+          data={pagedInvoices}
           status={isLoading ? 'loading' : 'success'}
           emptyMessage="No invoices found."
           containerClassName="border-0 shadow-none"
-          {...controls.tableProps}
+          {...controls.tableProps(filteredInvoices.length)}
         />
       </Card>
 

From fa32fa6a96ec146f360cbb534d4c3e73f3dbd979 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Fri, 14 Aug 2026 14:08:08 +0000
Subject: [PATCH 100/174] feat(filter-bar): migrate BookingRequestsPage
 (richest Family A page)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

13 useState fields -> 11 FilterDef entries + useFilters. Notable pieces:

- the deep-link-follow useEffect is gone entirely — controls.values reads
  live off the URL every render, so a link opened while the page is
  already mounted (the header document-review alarm) just works, and
  every filter auto-pins its own pill once it has a value (FilterBar's
  secondary/pinned split), so a deep link can never land behind "More
  filters" hidden. Confirmed the encoding stays back-compatible with the
  existing ?statuses=A,B&tradeDirection=IMPORT links via url.test.ts.
- "Paid, not allocated" (a checkbox that overrides the payment-status
  filter) became a boolean FilterDef with a custom toParams — ordered
  after paymentStatus in the defs array so its toParams wins on merge,
  matching the original override semantics exactly.
- booking kind and status stay pinned pills (always visible, matching the
  old primary row); direction/freight/payment/ownership/yards/dates are
  secondary (behind "More filters", matching the old advanced collapse).
---
 .../pages/bookings/BookingRequestsPage.tsx    | 439 +++---------------
 1 file changed, 65 insertions(+), 374 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
index 4bd84a247..cef8ca21a 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
@@ -1,44 +1,32 @@
 import { useMyTradeAccess } from "@/hooks/useMyTradeAccess";
 import {
-  ActionIcon,
   Box,
   Button,
   Card,
-  Checkbox,
-  Collapse,
   Group,
   Modal,
-  MultiSelect,
-  Select,
   Stack,
   Text,
-  TextInput,
 } from "@mantine/core";
-import { DatePickerInput } from "@mantine/dates";
-import { getDateRangePresets } from "@/components/common/dateRangePresets";
-import { useDebouncedValue } from "@mantine/hooks";
 import {
   AlertTriangle,
   ArrowRight,
   Calendar,
   CheckCircle2,
   Clock,
-  FilterX,
   LayoutList,
   Package,
   Plus,
   RefreshCw,
-  Search,
   User,
-  X,
 } from "lucide-react";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useNavigate, useSearchParams } from "react-router-dom";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { useNavigate } from "react-router-dom";
 import { useQuery } from "@tanstack/react-query";
 
 import { BookingActionsMenu } from "@/components/bookings/BookingActionsMenu";
-import { FilterToggle } from "@/components/common/FilterToggle";
 import { formatDate, humanize } from "@/lib/format";
+import { FilterBar, useFilters, type FilterDef } from "@/components/filters";
 import { BookingPriorityBadge } from "@/components/bookings/BookingPriorityBadge";
 import { BookingStatusBadge } from "@/components/bookings/BookingStatusBadge";
 // BookingStatusTabs / Operations* queues removed — replaced by booking-kind tabs.
@@ -63,7 +51,6 @@ import {
   Badge,
   DataTable,
   DataTableFooter,
-  usePagination,
   type ColumnDef,
 } from "@edr/ui-common";
 
@@ -104,61 +91,11 @@ const OWNERSHIP_OPTIONS = [
   { value: "false", label: "Private" },
 ];
 
-/** Local start-of-day → ISO, for inclusive "from" date filters. */
-function startOfDayIso(d: Date): string {
-  const x = new Date(d);
-  x.setHours(0, 0, 0, 0);
-  return x.toISOString();
-}
-
-/** Local end-of-day → ISO, for inclusive "to" date filters. */
-function endOfDayIso(d: Date): string {
-  const x = new Date(d);
-  x.setHours(23, 59, 59, 999);
-  return x.toISOString();
-}
-
 export default function BookingRequestsPage() {
   const navigate = useNavigate();
-  // Deep links land here pre-filtered (?statuses=A,B&tradeDirection=IMPORT) —
-  // the header's document-review alarm opens exactly the undecided requests it
-  // is counting down for. Read once as the initial state so staff can then
-  // change the filters like any other visit.
-  const [searchParams] = useSearchParams();
-  const { pagination, setPagination } = usePagination({ pageSize: 10 });
-  const [query, setQuery] = useState("");
-  const [debouncedQuery] = useDebouncedValue(query, 300);
-  // Booking kind is a filter now — one list holds both kinds (null = "all").
-  const [kindFilter, setKindFilter] = useState<BookingKind | null>(null);
-  // Filter controls (empty/null = "all").
-  const paramStatuses = searchParams.get("statuses") ?? "";
-  const paramDirection = searchParams.get("tradeDirection");
-  const [statusFilter, setStatusFilter] = useState<string[]>(() =>
-    paramStatuses.split(",").filter(Boolean),
-  );
   const { filterOptions } = useMyTradeAccess();
-  const [directionFilter, setDirectionFilter] = useState<string | null>(
-    paramDirection,
-  );
-  const [freightTypeFilter, setFreightTypeFilter] = useState<string | null>(null);
-  const [paymentStatusFilter, setPaymentStatusFilter] = useState<string | null>(null);
-  const [ownershipFilter, setOwnershipFilter] = useState<string | null>(null);
-  const [originYardFilter, setOriginYardFilter] = useState<string | null>(null);
-  const [destinationYardFilter, setDestinationYardFilter] = useState<string | null>(null);
-  const [createdFrom, setCreatedFrom] = useState<Date | null>(null);
-  const [createdTo, setCreatedTo] = useState<Date | null>(null);
-  const [scheduledFrom, setScheduledFrom] = useState<Date | null>(null);
-  const [scheduledTo, setScheduledTo] = useState<Date | null>(null);
-  // Direction is the only deep-linkable advanced filter — open the panel so a
-  // deep link never hides its own filter.
-  const [showAdvanced, setShowAdvanced] = useState(() =>
-    Boolean(paramDirection),
-  );
   const [allocateOpen, setAllocateOpen] = useState(false);
   const [allocateIds, setAllocateIds] = useState<string[]>([]);
-  // Paid bookings with no train attached (staff removed them or a sweep
-  // detached them) — the queue the per-row Allocate action works through.
-  const [paidUnallocated, setPaidUnallocated] = useState(false);
   const [allocatingId, setAllocatingId] = useState<string | null>(null);
   const [otherDayModal, setOtherDayModal] = useState<{
     booking: BookingListRow;
@@ -173,77 +110,6 @@ export default function BookingRequestsPage() {
     }, 400);
   }, []);
 
-  // Follow the URL when a deep link arrives while the page is already open
-  // (clicking the header alarm from this very list). Same-value writes are
-  // dropped so a manual filter change is never undone.
-  useEffect(() => {
-    const next = paramStatuses.split(",").filter(Boolean);
-    setStatusFilter((prev) => (prev.join(",") === next.join(",") ? prev : next));
-    setDirectionFilter(paramDirection);
-    if (paramDirection) setShowAdvanced(true);
-  }, [paramStatuses, paramDirection]);
-
-  const filter: BookingListFilter = useMemo(() => {
-    return {
-      page: pagination.pageIndex + 1,
-      pageSize: pagination.pageSize,
-      sortBy: "createdAt",
-      sortOrder: "DESC",
-      // React Query cache key per kind selection ("ALL" when unfiltered).
-      tab: kindFilter ?? "ALL",
-      ...(kindFilter ? { bookingType: kindFilter } : {}),
-      // Server-side free-text search (booking ref, customer, contract ref).
-      ...(debouncedQuery.trim() ? { search: debouncedQuery.trim() } : {}),
-      ...(statusFilter.length ? { statuses: statusFilter.join(",") } : {}),
-      ...(directionFilter ? { tradeDirection: directionFilter } : {}),
-      ...(freightTypeFilter ? { freightType: freightTypeFilter } : {}),
-      ...(paymentStatusFilter ? { paymentStatus: paymentStatusFilter } : {}),
-      // Wins over the payment-status select — the queue is by definition PAID.
-      ...(paidUnallocated
-        ? { paymentStatus: "PAID", assignedToSchedule: "false" as const }
-        : {}),
-      ...(ownershipFilter
-        ? { isGovernment: ownershipFilter as "true" | "false" }
-        : {}),
-      ...(originYardFilter ? { originYardId: originYardFilter } : {}),
-      ...(destinationYardFilter
-        ? { destinationYardId: destinationYardFilter }
-        : {}),
-      ...(createdFrom ? { createdFrom: startOfDayIso(createdFrom) } : {}),
-      ...(createdTo ? { createdTo: endOfDayIso(createdTo) } : {}),
-      ...(scheduledFrom ? { scheduledFrom: startOfDayIso(scheduledFrom) } : {}),
-      ...(scheduledTo ? { scheduledTo: endOfDayIso(scheduledTo) } : {}),
-    };
-  }, [
-    pagination.pageIndex,
-    pagination.pageSize,
-    kindFilter,
-    debouncedQuery,
-    statusFilter,
-    directionFilter,
-    freightTypeFilter,
-    paymentStatusFilter,
-    paidUnallocated,
-    ownershipFilter,
-    originYardFilter,
-    destinationYardFilter,
-    createdFrom,
-    createdTo,
-    scheduledFrom,
-    scheduledTo,
-  ]);
-
-  const { data, isLoading, isError, refetch, isFetching } = useBookingList(filter);
-  const primaryAllocateId = allocateIds[0];
-  const { data: allocateBooking } = useBookingDetail(
-    allocateOpen ? primaryAllocateId : undefined,
-  );
-  const {
-    data: summary,
-    isLoading: summaryLoading,
-    refetch: refetchSummary,
-  } = useBookingListSummary(filter);
-
   // Yard options for the origin/destination filters (shared routes reference list).
   const { data: yardRefs } = useQuery(
     api.routes.yards.queryOptions({ staleTime: 5 * 60_000 }),
@@ -257,43 +123,62 @@ export default function BookingRequestsPage() {
     [yardRefs],
   );
 
-  const resetPage = useCallback(() => {
-    setPagination({ pageIndex: 0, pageSize: pagination.pageSize });
-  }, [setPagination, pagination.pageSize]);
+  // Deep links land here pre-filtered (?statuses=A,B&tradeDirection=IMPORT) —
+  // the header's document-review alarm opens exactly the undecided requests
+  // it is counting down for. No sync effect needed any more: controls.values
+  // reads live off the URL every render, so a link opened while this page is
+  // already mounted just works, and every filter — direction included —
+  // auto-pins its own pill the moment it has a value (FilterBar's `secondary`
+  // split), so a deep link can never land behind "More filters" unseen.
+  const bookingFilterDefs: FilterDef[] = useMemo(
+    () => [
+      { key: "bookingType", label: "Kind", type: "enum", multiple: false, options: BOOKING_KIND_OPTIONS },
+      { key: "statuses", label: "Status", type: "enum", options: STATUS_OPTIONS },
+      {
+        key: "tradeDirection", label: "Direction", type: "enum", multiple: false,
+        options: filterOptions(TRADE_DIRECTION_OPTIONS), secondary: true,
+      },
+      { key: "freightType", label: "Freight", type: "enum", multiple: false, options: FREIGHT_TYPE_OPTIONS, secondary: true },
+      { key: "paymentStatus", label: "Payment", type: "enum", multiple: false, options: PAYMENT_STATUS_OPTIONS, secondary: true },
+      {
+        // Wins over the `paymentStatus` filter above — the queue is by
+        // definition PAID — because it's later in this array: toApiParams
+        // merges defs in order, so a later toParams overwrites an earlier one.
+        key: "paidUnallocated", label: "Allocation", type: "boolean", secondary: true,
+        trueLabel: "Paid, not allocated",
+        toParams: (v) => (v.v[0] === "true" ? { paymentStatus: "PAID", assignedToSchedule: "false" } : {}),
+      },
+      { key: "isGovernment", label: "Ownership", type: "enum", multiple: false, options: OWNERSHIP_OPTIONS, secondary: true },
+      { key: "originYardId", label: "Origin", type: "enum", multiple: false, options: yardOptions, secondary: true },
+      { key: "destinationYardId", label: "Destination", type: "enum", multiple: false, options: yardOptions, secondary: true },
+      { key: "created", label: "Created", type: "date", secondary: true, toParams: ({ v }) => ({ createdFrom: v[0], createdTo: v[1] }) },
+      { key: "scheduled", label: "Scheduled", type: "date", secondary: true, toParams: ({ v }) => ({ scheduledFrom: v[0], scheduledTo: v[1] }) },
+    ],
+    [filterOptions, yardOptions],
+  );
 
-  const activeFilterCount =
-    (kindFilter ? 1 : 0) +
-    (statusFilter.length ? 1 : 0) +
-    (directionFilter ? 1 : 0) +
-    (freightTypeFilter ? 1 : 0) +
-    (paymentStatusFilter ? 1 : 0) +
-    (paidUnallocated ? 1 : 0) +
-    (ownershipFilter ? 1 : 0) +
-    (originYardFilter ? 1 : 0) +
-    (destinationYardFilter ? 1 : 0) +
-    (createdFrom || createdTo ? 1 : 0) +
-    (scheduledFrom || scheduledTo ? 1 : 0);
+  const controls = useFilters(bookingFilterDefs, { defaultSort: "createdAt:DESC", pageSize: 10 });
 
-  // Badge on the advanced-filters toggle — active filters hidden behind it.
-  const advancedFilterCount =
-    activeFilterCount - (kindFilter ? 1 : 0) - (statusFilter.length ? 1 : 0);
+  const filter: BookingListFilter = useMemo(
+    () => ({
+      ...(controls.params as unknown as BookingListFilter),
+      // React Query cache key per kind selection ("ALL" when unfiltered) —
+      // kept as a param the API ignores, matching the pre-migration cache key.
+      tab: (controls.values.bookingType?.v[0] as BookingKind | undefined) ?? "ALL",
+    }),
+    [controls.params, controls.values.bookingType],
+  );
 
-  const clearFilters = useCallback(() => {
-    setKindFilter(null);
-    setStatusFilter([]);
-    setDirectionFilter(null);
-    setFreightTypeFilter(null);
-    setPaymentStatusFilter(null);
-    setPaidUnallocated(false);
-    setOwnershipFilter(null);
-    setOriginYardFilter(null);
-    setDestinationYardFilter(null);
-    setCreatedFrom(null);
-    setCreatedTo(null);
-    setScheduledFrom(null);
-    setScheduledTo(null);
-    resetPage();
-  }, [resetPage]);
+  const { data, isLoading, isError, refetch, isFetching } = useBookingList(filter);
+  const primaryAllocateId = allocateIds[0];
+  const { data: allocateBooking } = useBookingDetail(
+    allocateOpen ? primaryAllocateId : undefined,
+  );
+  const {
+    data: summary,
+    isLoading: summaryLoading,
+    refetch: refetchSummary,
+  } = useBookingListSummary(filter);
 
   // Search is applied server-side (via the `search` filter param) — no
   // client-side filtering here.
@@ -303,8 +188,7 @@ export default function BookingRequestsPage() {
   );
 
   const total = data?.total ?? 0;
-  const pageCount = Math.max(1, Math.ceil(total / pagination.pageSize));
-  const hasSearch = query.trim().length > 0;
+  const hasSearch = controls.searchText.trim().length > 0;
   const showEmpty = !isLoading && !isError && rows.length === 0;
 
   const metrics = summary?.metrics;
@@ -585,195 +469,13 @@ export default function BookingRequestsPage() {
 
           <Card p={0}>
             <Stack gap={0}>
-              <Box px="md" pt="md" pb="sm" w="100%">
-                <Stack gap="sm">
-                  <Group gap="sm" wrap="wrap">
-                    <TextInput
-                      placeholder="Search booking, contract or customer…"
-                      leftSection={<Search size={18} />}
-                      value={query}
-                      onChange={(e) => {
-                        setQuery(e.target.value);
-                        resetPage();
-                      }}
-                      rightSection={
-                        query && (
-                          <ActionIcon
-                            size="sm"
-                            color="gray"
-                            radius="md"
-                            variant="transparent"
-                            onClick={() => {
-                              setQuery("");
-                              resetPage();
-                            }}
-                          >
-                            <X size={16} />
-                          </ActionIcon>
-                        )
-                      }
-                      style={{ flex: 1, minWidth: "200px" }}
-                      radius="lg"
-                    />
-                    <Select
-                      placeholder="All booking types"
-                      data={BOOKING_KIND_OPTIONS}
-                      value={kindFilter}
-                      onChange={(v) => {
-                        setKindFilter((v as BookingKind | null) ?? null);
-                        resetPage();
-                      }}
-                      clearable
-                      radius="lg"
-                      style={{ minWidth: 190 }}
-                    />
-                    <MultiSelect
-                      placeholder={statusFilter.length ? undefined : "All statuses"}
-                      data={STATUS_OPTIONS}
-                      value={statusFilter}
-                      onChange={(v) => {
-                        setStatusFilter(v);
-                        resetPage();
-                      }}
-                      clearable
-                      searchable
-                      radius="lg"
-                      style={{ minWidth: 220 }}
-                    />
-                    <FilterToggle
-                      count={advancedFilterCount}
-                      expanded={showAdvanced}
-                      onClick={() => setShowAdvanced((v) => !v)}
-                    />
-                    {activeFilterCount > 0 ? (
-                      <Button
-                        variant="subtle"
-                        color="gray"
-                        radius="lg"
-                        leftSection={<FilterX size={16} />}
-                        onClick={clearFilters}
-                      >
-                        Clear filters ({activeFilterCount})
-                      </Button>
-                    ) : null}
-                  </Group>
-                  <Collapse expanded={showAdvanced}>
-                  <Group gap="sm" wrap="wrap">
-                    <Select
-                      placeholder="All origins"
-                      data={yardOptions}
-                      value={originYardFilter}
-                      onChange={(v) => {
-                        setOriginYardFilter(v);
-                        resetPage();
-                      }}
-                      clearable
-                      searchable
-                      radius="lg"
-                      style={{ minWidth: 180 }}
-                    />
-                    <Select
-                      placeholder="All destinations"
-                      data={yardOptions}
-                      value={destinationYardFilter}
-                      onChange={(v) => {
-                        setDestinationYardFilter(v);
-                        resetPage();
-                      }}
-                      clearable
-                      searchable
-                      radius="lg"
-                      style={{ minWidth: 180 }}
-                    />
-                    <Select
-                      placeholder="All directions"
-                      data={filterOptions(TRADE_DIRECTION_OPTIONS)}
-                      value={directionFilter}
-                      onChange={(v) => {
-                        setDirectionFilter(v);
-                        resetPage();
-                      }}
-                      clearable
-                      radius="lg"
-                      style={{ minWidth: 150 }}
-                    />
-                    <Select
-                      placeholder="All freight types"
-                      data={FREIGHT_TYPE_OPTIONS}
-                      value={freightTypeFilter}
-                      onChange={(v) => {
-                        setFreightTypeFilter(v);
-                        resetPage();
-                      }}
-                      clearable
-                      radius="lg"
-                      style={{ minWidth: 150 }}
-                    />
-                    <Select
-                      placeholder="All payment statuses"
-                      data={PAYMENT_STATUS_OPTIONS}
-                      value={paymentStatusFilter}
-                      onChange={(v) => {
-                        setPaymentStatusFilter(v);
-                        resetPage();
-                      }}
-                      clearable
-                      radius="lg"
-                      style={{ minWidth: 180 }}
-                    />
-                    <Checkbox
-                      label="Paid, not allocated"
-                      checked={paidUnallocated}
-                      onChange={(e) => {
-                        setPaidUnallocated(e.currentTarget.checked);
-                        resetPage();
-                      }}
-                      radius="sm"
-                      style={{ alignSelf: "center" }}
-                    />
-                    <Select
-                      placeholder="Gov / Private"
-                      data={OWNERSHIP_OPTIONS}
-                      value={ownershipFilter}
-                      onChange={(v) => {
-                        setOwnershipFilter(v);
-                        resetPage();
-                      }}
-                      clearable
-                      radius="lg"
-                      style={{ minWidth: 140 }}
-                    />
-                    <DatePickerInput
-                      type="range"
-                      placeholder="Created date range"
-                      value={[createdFrom, createdTo]}
-                      onChange={([from, to]) => {
-                        setCreatedFrom(from ? new Date(from) : null);
-                        setCreatedTo(to ? new Date(to) : null);
-                        resetPage();
-                      }}
-                      presets={getDateRangePresets()}
-                      clearable
-                      radius="lg"
-                      style={{ minWidth: 220 }}
-                    />
-                    <DatePickerInput
-                      type="range"
-                      placeholder="Scheduled date range"
-                      value={[scheduledFrom, scheduledTo]}
-                      onChange={([from, to]) => {
-                        setScheduledFrom(from ? new Date(from) : null);
-                        setScheduledTo(to ? new Date(to) : null);
-                        resetPage();
-                      }}
-                      presets={getDateRangePresets()}
-                      clearable
-                      radius="lg"
-                      style={{ minWidth: 230 }}
-                    />
-                  </Group>
-                  </Collapse>
-                </Stack>
+              <Box px="md" pt="sm" pb="xs" w="100%">
+                <FilterBar
+                  defs={bookingFilterDefs}
+                  controls={controls}
+                  searchPlaceholder="Search booking, contract or customer…"
+                  viewId="booking-requests"
+                />
               </Box>
 
               {showEmpty ? (
@@ -791,18 +493,7 @@ export default function BookingRequestsPage() {
                     data={rows}
                     status={isLoading ? "loading" : isError ? "error" : "success"}
                     onRowClick={handleRowClick}
-                    pagination={{
-                      pageIndex: pagination.pageIndex,
-                      pageSize: pagination.pageSize,
-                      pageCount,
-                      totalCount: total,
-                    }}
-                    tableOptions={{
-                      state: { pagination },
-                      onPaginationChange: setPagination,
-                      manualPagination: true,
-                      pageCount,
-                    }}
+                    {...controls.tableProps(total)}
                     containerClassName="border-0 shadow-none bg-transparent"
                     footer={DataTableFooter}
                   />

From e5e75b4166ba981bd37388380a023d08ddc6ffe6 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Fri, 14 Aug 2026 14:13:11 +0000
Subject: [PATCH 101/174] feat(filter-bar): migrate 3 more fleet pages, extract
 footer adapter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ruleEngineFooterProps.ts: toRuleEngineFooterProps() — the
  useFilters-to-RuleEngineListFooter pagination adapter had already been
  hand-written twice (TrucksOnSitePage, CompliancePage) with the same
  pageSize-drop risk useFilters itself just had fixed; extracted before a
  third copy could drift.
- CompliancePage, FuelPurchasePage, IncidentsPage: ListControls ->
  FilterBar + applyClientFilters, same mechanical pattern as the
  warehouse pages (search + one date range, endpoints take no params at
  all per the inventory sweep — confirmed correct bucket, not assumed).
---
 .../src/components/filters/index.ts           |  1 +
 .../filters/ruleEngineFooterProps.ts          | 32 +++++++++++++
 .../src/pages/fleet/CompliancePage.tsx        | 48 +++++++++++--------
 .../src/pages/fleet/FuelPurchasePage.tsx      | 48 +++++++++++--------
 .../src/pages/fleet/IncidentsPage.tsx         | 48 +++++++++++--------
 .../src/pages/warehouses/TrucksOnSitePage.tsx | 18 ++++---
 6 files changed, 122 insertions(+), 73 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/ruleEngineFooterProps.ts

diff --git a/apps/edr-freight-web/backoffice/src/components/filters/index.ts b/apps/edr-freight-web/backoffice/src/components/filters/index.ts
index 5fe7702f3..ea2c28fb2 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/index.ts
+++ b/apps/edr-freight-web/backoffice/src/components/filters/index.ts
@@ -3,6 +3,7 @@ export * from "./url";
 export * from "./dates";
 export * from "./format";
 export * from "./clientFilter";
+export * from "./ruleEngineFooterProps";
 export * from "./useFilters";
 export * from "./useSavedViews";
 export { FilterBar } from "./FilterBar";
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/ruleEngineFooterProps.ts b/apps/edr-freight-web/backoffice/src/components/filters/ruleEngineFooterProps.ts
new file mode 100644
index 000000000..e8cd32dab
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/ruleEngineFooterProps.ts
@@ -0,0 +1,32 @@
+import type { OnChangeFn, PaginationState } from "@edr/ui-common";
+import type { UseFilters } from "./useFilters";
+
+/**
+ * Adapts `useFilters`'s URL-backed page/pageSize to `RuleEngineListFooter`'s
+ * prop shape, for the client-bridge pages that render a plain `<Table>` +
+ * that footer instead of `<DataTable>` (which has `tableProps()` for this).
+ * Routes page-index vs page-size changes to the right setter — the same
+ * pageSize-gets-silently-dropped bug `tableProps()` had before it was fixed.
+ */
+export function toRuleEngineFooterProps(
+  controls: Pick<UseFilters, "page" | "pageSize" | "setPage" | "setPageSize">,
+  totalCount: number,
+): {
+  pagination: PaginationState;
+  pageCount: number;
+  totalCount: number;
+  onPaginationChange: OnChangeFn<PaginationState>;
+} {
+  const { page, pageSize, setPage, setPageSize } = controls;
+  return {
+    pagination: { pageIndex: page - 1, pageSize },
+    pageCount: Math.max(1, Math.ceil(totalCount / pageSize)),
+    totalCount,
+    onPaginationChange: (updater) => {
+      const current = { pageIndex: page - 1, pageSize };
+      const next = typeof updater === "function" ? updater(current) : updater;
+      if (next.pageSize !== pageSize) setPageSize(next.pageSize);
+      else if (next.pageIndex !== current.pageIndex) setPage(next.pageIndex + 1);
+    },
+  };
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/fleet/CompliancePage.tsx b/apps/edr-freight-web/backoffice/src/pages/fleet/CompliancePage.tsx
index f31bf5e76..9cb305bbb 100644
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/CompliancePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/CompliancePage.tsx
@@ -18,11 +18,16 @@ import {
 } from "@mantine/core";
 import { Plus, AlertTriangle } from "lucide-react";
 import Breadcrumbs from "@/components/ui/Breadcrumbs";
-import ListControls from "@/components/common/ListControls";
 // Generic list footer — already shared by the fleet and train-scheduling lists
 // despite the ruleEngine path.
 import RuleEngineListFooter from "@/components/ruleEngine/RuleEngineListFooter";
-import { useListControls } from "@/hooks/useListControls";
+import {
+  applyClientFilters,
+  FilterBar,
+  toRuleEngineFooterProps,
+  useFilters,
+  type FilterDef,
+} from "@/components/filters";
 import { useToast } from "@/hooks/use-toast";
 import {
   complianceService,
@@ -52,6 +57,8 @@ const statusColor = (status: ComplianceRecord["status"]) => {
 const formatDate = (value?: string | null) =>
   value ? new Date(value).toLocaleDateString() : "—";
 
+const COMPLIANCE_FILTER_DEFS: FilterDef[] = [{ key: "expiryDate", label: "Expiry", type: "date" }];
+
 const emptyForm = {
   vehicleId: "",
   type: "INSPECTION" as ComplianceType,
@@ -91,10 +98,18 @@ export default function CompliancePage() {
     },
   });
 
-  const controls = useListControls(records as ComplianceRecord[], {
-    searchKeys: ["type", "status", "documentNumber"],
-    dateKey: "expiryDate",
-  });
+  const controls = useFilters(COMPLIANCE_FILTER_DEFS, { pageSize: 10 });
+  const filteredRecords = applyClientFilters(
+    records as ComplianceRecord[],
+    COMPLIANCE_FILTER_DEFS,
+    controls.values,
+    controls.searchText,
+    { searchKeys: ["type", "status", "documentNumber"] },
+  );
+  const pagedRecords = filteredRecords.slice(
+    (controls.page - 1) * controls.pageSize,
+    controls.page * controls.pageSize,
+  );
 
   const createMutation = useMutation({
     mutationFn: async (data: typeof formData) => {
@@ -220,17 +235,11 @@ export default function CompliancePage() {
         Compliance Records
       </Title>
       <Card withBorder>
-        <ListControls
-          search={controls.search}
-          onSearchChange={controls.setSearch}
+        <FilterBar
+          defs={COMPLIANCE_FILTER_DEFS}
+          controls={controls}
           searchPlaceholder="Search type, status, document no…"
-          dateFrom={controls.dateFrom}
-          onDateFromChange={controls.setDateFrom}
-          dateTo={controls.dateTo}
-          onDateToChange={controls.setDateTo}
-          dateLabel="Expiry"
-          hasFilters={controls.hasFilters}
-          onReset={controls.reset}
+          viewId="fleet-compliance"
         />
         <Table striped highlightOnHover>
           <Table.Thead>
@@ -261,7 +270,7 @@ export default function CompliancePage() {
                 </Table.Td>
               </Table.Tr>
             ) : null}
-            {controls.pagedRows.map((record) => (
+            {pagedRecords.map((record) => (
               <Table.Tr key={record.id}>
                 <Table.Td>{vehicleLabel(record)}</Table.Td>
                 <Table.Td>
@@ -282,11 +291,8 @@ export default function CompliancePage() {
           </Table.Tbody>
         </Table>
         <RuleEngineListFooter
-          pagination={controls.pagination}
-          pageCount={controls.pageCount}
-          totalCount={controls.totalCount}
           itemLabel="records"
-          onPaginationChange={controls.setPagination}
+          {...toRuleEngineFooterProps(controls, filteredRecords.length)}
         />
       </Card>
 
diff --git a/apps/edr-freight-web/backoffice/src/pages/fleet/FuelPurchasePage.tsx b/apps/edr-freight-web/backoffice/src/pages/fleet/FuelPurchasePage.tsx
index 8ecedd712..ec9c93482 100644
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/FuelPurchasePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/FuelPurchasePage.tsx
@@ -19,11 +19,16 @@ import {
 } from "@mantine/core";
 import { Plus } from "lucide-react";
 import Breadcrumbs from "@/components/ui/Breadcrumbs";
-import ListControls from "@/components/common/ListControls";
 // Generic list footer — already shared by the fleet and train-scheduling lists
 // despite the ruleEngine path.
 import RuleEngineListFooter from "@/components/ruleEngine/RuleEngineListFooter";
-import { useListControls } from "@/hooks/useListControls";
+import {
+  applyClientFilters,
+  FilterBar,
+  toRuleEngineFooterProps,
+  useFilters,
+  type FilterDef,
+} from "@/components/filters";
 import { useToast } from "@/hooks/use-toast";
 import { api } from "@/auth/http";
 import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
@@ -45,6 +50,8 @@ interface FuelPurchase {
 }
 
 
+const FUEL_FILTER_DEFS: FilterDef[] = [{ key: "purchaseDate", label: "Purchased", type: "date" }];
+
 export default function FuelPurchasePage() {
   const { toast } = useToast();
   const qc = useQueryClient();
@@ -123,10 +130,18 @@ export default function FuelPurchasePage() {
   const totalCost = formData.liters * formData.costPerLiter;
 
   // Aggregate stats (guarded against divide-by-zero when there are no purchases)
-  const controls = useListControls(purchasesData as FuelPurchase[], {
-    searchKeys: ["fuelStation", "paymentMethod"],
-    dateKey: "purchaseDate",
-  });
+  const controls = useFilters(FUEL_FILTER_DEFS, { pageSize: 10 });
+  const filteredPurchases = applyClientFilters(
+    purchasesData as FuelPurchase[],
+    FUEL_FILTER_DEFS,
+    controls.values,
+    controls.searchText,
+    { searchKeys: ["fuelStation", "paymentMethod"] },
+  );
+  const pagedPurchases = filteredPurchases.slice(
+    (controls.page - 1) * controls.pageSize,
+    controls.page * controls.pageSize,
+  );
 
   const totalLiters = (purchasesData as FuelPurchase[]).reduce(
     (sum, p) => sum + Number(p.liters),
@@ -195,17 +210,11 @@ export default function FuelPurchasePage() {
 
       {/* Purchases Table */}
       <Card withBorder>
-        <ListControls
-          search={controls.search}
-          onSearchChange={controls.setSearch}
+        <FilterBar
+          defs={FUEL_FILTER_DEFS}
+          controls={controls}
           searchPlaceholder="Search station or payment method…"
-          dateFrom={controls.dateFrom}
-          onDateFromChange={controls.setDateFrom}
-          dateTo={controls.dateTo}
-          onDateToChange={controls.setDateTo}
-          dateLabel="Purchased"
-          hasFilters={controls.hasFilters}
-          onReset={controls.reset}
+          viewId="fleet-fuel-purchases"
         />
         <Table striped highlightOnHover>
           <Table.Thead>
@@ -237,7 +246,7 @@ export default function FuelPurchasePage() {
                 </Table.Td>
               </Table.Tr>
             ) : null}
-            {controls.pagedRows.map((purchase) => (
+            {pagedPurchases.map((purchase) => (
               <Table.Tr key={purchase.id}>
                 <Table.Td>{(purchase as any).vehicle?.registrationNumber || (purchase as any).vehicle?.plateNumber || purchase.vehicleId}</Table.Td>
                 <Table.Td>{new Date(purchase.purchaseDate).toLocaleDateString()}</Table.Td>
@@ -253,11 +262,8 @@ export default function FuelPurchasePage() {
           </Table.Tbody>
         </Table>
         <RuleEngineListFooter
-          pagination={controls.pagination}
-          pageCount={controls.pageCount}
-          totalCount={controls.totalCount}
           itemLabel="purchases"
-          onPaginationChange={controls.setPagination}
+          {...toRuleEngineFooterProps(controls, filteredPurchases.length)}
         />
       </Card>
 
diff --git a/apps/edr-freight-web/backoffice/src/pages/fleet/IncidentsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/fleet/IncidentsPage.tsx
index 6276091b8..62c3d9e01 100644
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/IncidentsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/IncidentsPage.tsx
@@ -20,11 +20,16 @@ import {
 } from "@mantine/core";
 import { Plus } from "lucide-react";
 import Breadcrumbs from "@/components/ui/Breadcrumbs";
-import ListControls from "@/components/common/ListControls";
 // Generic list footer — already shared by the fleet and train-scheduling lists
 // despite the ruleEngine path.
 import RuleEngineListFooter from "@/components/ruleEngine/RuleEngineListFooter";
-import { useListControls } from "@/hooks/useListControls";
+import {
+  applyClientFilters,
+  FilterBar,
+  toRuleEngineFooterProps,
+  useFilters,
+  type FilterDef,
+} from "@/components/filters";
 import { useToast } from "@/hooks/use-toast";
 import {
   incidentsService,
@@ -89,6 +94,8 @@ const initialForm = {
   reportedBy: "",
 };
 
+const INCIDENT_FILTER_DEFS: FilterDef[] = [{ key: "occurredAt", label: "Occurred", type: "date" }];
+
 export default function IncidentsPage() {
   const { toast } = useToast();
   const qc = useQueryClient();
@@ -166,10 +173,18 @@ export default function IncidentsPage() {
     })) || [];
 
   const incidents = incidentsData as Incident[];
-  const controls = useListControls(incidents, {
-    searchKeys: ["type", "severity", "status"],
-    dateKey: "occurredAt",
-  });
+  const controls = useFilters(INCIDENT_FILTER_DEFS, { pageSize: 10 });
+  const filteredIncidents = applyClientFilters(
+    incidents,
+    INCIDENT_FILTER_DEFS,
+    controls.values,
+    controls.searchText,
+    { searchKeys: ["type", "severity", "status"] },
+  );
+  const pagedIncidents = filteredIncidents.slice(
+    (controls.page - 1) * controls.pageSize,
+    controls.page * controls.pageSize,
+  );
   const totalCount = incidents.length;
   const openCount = incidents.filter((i) => OPEN_STATUSES.includes(i.status)).length;
   const underReviewCount = incidents.filter((i) => i.status === "UNDER_REVIEW").length;
@@ -246,17 +261,11 @@ export default function IncidentsPage() {
 
       {/* Incidents Table */}
       <Card withBorder>
-        <ListControls
-          search={controls.search}
-          onSearchChange={controls.setSearch}
+        <FilterBar
+          defs={INCIDENT_FILTER_DEFS}
+          controls={controls}
           searchPlaceholder="Search type, severity, status…"
-          dateFrom={controls.dateFrom}
-          onDateFromChange={controls.setDateFrom}
-          dateTo={controls.dateTo}
-          onDateToChange={controls.setDateTo}
-          dateLabel="Occurred"
-          hasFilters={controls.hasFilters}
-          onReset={controls.reset}
+          viewId="fleet-incidents"
         />
         <Table striped highlightOnHover>
           <Table.Thead>
@@ -288,7 +297,7 @@ export default function IncidentsPage() {
                 </Table.Td>
               </Table.Tr>
             ) : null}
-            {controls.pagedRows.map((incident) => (
+            {pagedIncidents.map((incident) => (
               <Table.Tr key={incident.id}>
                 <Table.Td>{new Date(incident.occurredAt).toLocaleDateString()}</Table.Td>
                 <Table.Td>
@@ -316,11 +325,8 @@ export default function IncidentsPage() {
           </Table.Tbody>
         </Table>
         <RuleEngineListFooter
-          pagination={controls.pagination}
-          pageCount={controls.pageCount}
-          totalCount={controls.totalCount}
           itemLabel="incidents"
-          onPaginationChange={controls.setPagination}
+          {...toRuleEngineFooterProps(controls, filteredIncidents.length)}
         />
       </Card>
 
diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/TrucksOnSitePage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/TrucksOnSitePage.tsx
index 39f7daac4..7ddcef866 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/TrucksOnSitePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/TrucksOnSitePage.tsx
@@ -14,7 +14,13 @@ import { PageContainer, PageHeader } from "@/components/page";
 // Generic list footer — already shared by the fleet and train-scheduling lists
 // despite the ruleEngine path; reused here rather than adding a second one.
 import RuleEngineListFooter from "@/components/ruleEngine/RuleEngineListFooter";
-import { applyClientFilters, FilterBar, useFilters, type FilterDef } from "@/components/filters";
+import {
+  applyClientFilters,
+  FilterBar,
+  toRuleEngineFooterProps,
+  useFilters,
+  type FilterDef,
+} from "@/components/filters";
 import { useTrucksOnSite } from "@/hooks/useWarehouses";
 import type { TruckOnSite } from "@/types/warehouse";
 import { formatDateTime } from "@/lib/format";
@@ -231,16 +237,8 @@ export default function TrucksOnSitePage() {
         <>
           <Rows rows={pagedTrucks} />
           <RuleEngineListFooter
-            pagination={{ pageIndex: controls.page - 1, pageSize: controls.pageSize }}
-            pageCount={Math.max(1, Math.ceil(filteredTrucks.length / controls.pageSize))}
-            totalCount={filteredTrucks.length}
             itemLabel="trucks"
-            onPaginationChange={(updater) => {
-              const current = { pageIndex: controls.page - 1, pageSize: controls.pageSize };
-              const next = typeof updater === "function" ? updater(current) : updater;
-              if (next.pageSize !== controls.pageSize) controls.setPageSize(next.pageSize);
-              else controls.setPage(next.pageIndex + 1);
-            }}
+            {...toRuleEngineFooterProps(controls, filteredTrucks.length)}
           />
         </>
       )}

From 839dfdbae36bc39f87c7bf01a3d9bd595ae4876e Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 15 Aug 2026 07:23:43 +0000
Subject: [PATCH 102/174] feat(filters): route filter, select-styled trigger,
 tune default pin set
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New "route" FilterType: RouteBody popover (searchable origin +
  destination selects, apply once both are picked), wired into
  ContractRequestsPage and BookingRequestsPage. Bookings already had
  server-side originYardId/destinationYardId; contracts gets both new
  (contract_routes is one-to-many, so origin/destination are separate
  EXISTS subqueries, not a join).
- Inactive FilterPill trigger restyled to read like a closed Mantine
  Select (opaque solid border, trailing chevron) instead of a dashed
  "+" pill — trigger only, popover body/position unchanged.
- Search box text set to regular weight.
- A couple more filters (Direction, Freight) pinned by default per
  page on top of the existing always-pinned ones; the rest stay behind
  More filters.
---
 .../modules/contracts/contracts.repository.ts | 21 ++++++++
 .../modules/contracts/contracts.service.ts    |  4 ++
 .../contracts/dto/filter-contract.dto.ts      | 16 ++++++
 .../src/components/filters/FilterBar.tsx      |  1 +
 .../src/components/filters/FilterPill.tsx     | 28 +++++++----
 .../components/filters/bodies/RouteBody.tsx   | 50 +++++++++++++++++++
 .../src/components/filters/format.ts          |  4 ++
 .../src/components/filters/types.ts           | 18 ++++++-
 .../pages/bookings/BookingRequestsPage.tsx    | 10 ++--
 .../pages/contracts/ContractRequestsPage.tsx  | 24 +++++++--
 10 files changed, 157 insertions(+), 19 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/filters/bodies/RouteBody.tsx

diff --git a/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts b/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
index f618986c4..d89d43250 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
@@ -48,6 +48,8 @@ export interface ContractListFilterOptions {
   hasClearanceDocuments?: boolean;
   createdFrom?: string;
   createdTo?: string;
+  originYardId?: string;
+  destinationYardId?: string;
 }
 
 @Injectable()
@@ -489,6 +491,25 @@ export class ContractsRepository extends BaseRepository<Contract> {
     if (options.createdTo) {
       qb.andWhere('contract.created_at <= :createdTo', { createdTo: options.createdTo });
     }
+    // Routes are one-to-many (a contract can list several lanes), so origin
+    // and destination each need their own EXISTS — a plain join would
+    // duplicate the contract row per matching route.
+    if (omit !== 'originYardId' && options.originYardId) {
+      qb.andWhere(
+        'EXISTS (SELECT 1 FROM freight.contract_routes cr_o ' +
+          'WHERE cr_o.contract_id = contract.id AND cr_o.deleted_at IS NULL ' +
+          'AND cr_o.origin_yard_id = :originYardId)',
+        { originYardId: options.originYardId },
+      );
+    }
+    if (omit !== 'destinationYardId' && options.destinationYardId) {
+      qb.andWhere(
+        'EXISTS (SELECT 1 FROM freight.contract_routes cr_d ' +
+          'WHERE cr_d.contract_id = contract.id AND cr_d.deleted_at IS NULL ' +
+          'AND cr_d.destination_yard_id = :destinationYardId)',
+        { destinationYardId: options.destinationYardId },
+      );
+    }
   }
 
   /**
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 5798d44ef..3411414e9 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.service.ts
@@ -768,6 +768,8 @@ export class ContractsService {
       paymentCurrency: filter.paymentCurrency,
       createdFrom: filter.createdFrom,
       createdTo: filter.createdTo,
+      originYardId: filter.originYardId,
+      destinationYardId: filter.destinationYardId,
       search: filter.search,
       sortBy: filter.sortBy,
       sortOrder: filter.sortOrder,
@@ -789,6 +791,8 @@ export class ContractsService {
       paymentCurrency: filter.paymentCurrency,
       createdFrom: filter.createdFrom,
       createdTo: filter.createdTo,
+      originYardId: filter.originYardId,
+      destinationYardId: filter.destinationYardId,
     };
 
     const [facets, metrics] = await Promise.all([
diff --git a/apps/edr-freight-api/src/modules/contracts/dto/filter-contract.dto.ts b/apps/edr-freight-api/src/modules/contracts/dto/filter-contract.dto.ts
index 8950e7eb3..a03d52afb 100644
--- a/apps/edr-freight-api/src/modules/contracts/dto/filter-contract.dto.ts
+++ b/apps/edr-freight-api/src/modules/contracts/dto/filter-contract.dto.ts
@@ -61,6 +61,22 @@ export class FilterContractDto {
   @IsIn([...PAYMENT_CURRENCIES])
   paymentCurrency?: string;
 
+  @ApiPropertyOptional({
+    format: 'uuid',
+    description: 'Only contracts with a route starting at this yard.',
+  })
+  @IsOptional()
+  @IsUUID()
+  originYardId?: string;
+
+  @ApiPropertyOptional({
+    format: 'uuid',
+    description: 'Only contracts with a route ending at this yard.',
+  })
+  @IsOptional()
+  @IsUUID()
+  destinationYardId?: string;
+
   @ApiPropertyOptional({ description: 'Filter contracts created on/after this date (ISO)' })
   @IsOptional()
   @IsDateString()
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx b/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
index a712d189e..6a0aaac96 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
@@ -84,6 +84,7 @@ export function FilterBar({
             onChange={(e) => controls.setSearchText(e.currentTarget.value)}
             size="xs"
             radius="lg"
+            styles={{ input: { fontWeight: 400 } }}
             style={{ minWidth: 160, flex: "1 1 160px" }}
           />
         )}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx b/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx
index 7a4a76998..0275f67ad 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx
@@ -1,6 +1,6 @@
 import { useState } from "react";
 import { ActionIcon, Button, Popover } from "@mantine/core";
-import { Plus, X } from "lucide-react";
+import { ChevronDown, X } from "lucide-react";
 
 import type { FilterDef, FilterValue } from "./types";
 import { formatFilterValue } from "./format";
@@ -8,6 +8,7 @@ import { BooleanBody } from "./bodies/BooleanBody";
 import { DateBody } from "./bodies/DateBody";
 import { EnumBody } from "./bodies/EnumBody";
 import { NumberBody } from "./bodies/NumberBody";
+import { RouteBody } from "./bodies/RouteBody";
 import { TextBody } from "./bodies/TextBody";
 
 const BODIES: Record<FilterDef["type"], React.ComponentType<any>> = {
@@ -16,6 +17,7 @@ const BODIES: Record<FilterDef["type"], React.ComponentType<any>> = {
   date: DateBody,
   number: NumberBody,
   boolean: BooleanBody,
+  route: RouteBody,
 };
 
 export interface FilterPillProps {
@@ -37,18 +39,22 @@ export function FilterPill({ def, value, onChange, autoOpen }: FilterPillProps)
         <Button
           size="xs"
           radius="xl"
-          // Inactive: "default" variant (solid border, opaque text) reads far
-          // less faint than a color-tinted outline — dashed border is the only
-          // thing marking it as "not set yet". Active: "light" (soft tinted
-          // fill), not "filled" — a whole row of solid green buttons was the
-          // "too loud" complaint; light keeps the active/inactive contrast
-          // without shouting.
+          // Inactive: styled like a closed Mantine Select trigger — solid
+          // (opaque, not dashed) border, label + trailing chevron, no leading
+          // "+" — just a smaller/pill-shaped version of that same control.
+          // Active: "light" (soft tinted fill), not "filled" — a whole row of
+          // solid green buttons was the "too loud" complaint; light keeps the
+          // active/inactive contrast without shouting. Popover side/position
+          // is untouched either way.
           variant={active ? "light" : "default"}
           color={active ? "edr-green" : undefined}
-          styles={active ? undefined : { root: { borderStyle: "dashed" } }}
-          leftSection={!active && <Plus size={12} />}
+          styles={
+            active
+              ? undefined
+              : { root: { borderColor: "var(--mantine-color-gray-6)", color: "var(--mantine-color-gray-9)" } }
+          }
           rightSection={
-            active && (
+            active ? (
               <ActionIcon
                 component="span"
                 size={16}
@@ -62,6 +68,8 @@ export function FilterPill({ def, value, onChange, autoOpen }: FilterPillProps)
               >
                 <X size={12} />
               </ActionIcon>
+            ) : (
+              <ChevronDown size={14} />
             )
           }
           onClick={() => setOpened((o) => !o)}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/bodies/RouteBody.tsx b/apps/edr-freight-web/backoffice/src/components/filters/bodies/RouteBody.tsx
new file mode 100644
index 000000000..9e86199a9
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/filters/bodies/RouteBody.tsx
@@ -0,0 +1,50 @@
+import { useState } from "react";
+import { Button, Select, Stack } from "@mantine/core";
+import { ArrowRight } from "lucide-react";
+
+import type { RouteFilterDef } from "../types";
+import type { FilterBodyProps } from "./TextBody";
+
+/**
+ * Origin + destination picked together, each a searchable `Select` over the
+ * page's yard list — typing filters by yard name, same as any Mantine
+ * Select. No `OperatorSelect`: a route pair has exactly one operator ("is"),
+ * which is why DEFAULT_OP.route is the only entry the generic bar needs.
+ */
+export function RouteBody({ def, value, onChange, onClose }: FilterBodyProps<RouteFilterDef>) {
+  const [origin, setOrigin] = useState<string | null>(value?.v[0] ?? null);
+  const [destination, setDestination] = useState<string | null>(value?.v[1] ?? null);
+
+  const apply = () => {
+    onChange(origin && destination ? { op: "is", v: [origin, destination] } : undefined);
+    onClose();
+  };
+
+  return (
+    <Stack gap="xs" w={240}>
+      <Select
+        label="Origin"
+        placeholder="Any"
+        data={def.options}
+        value={origin}
+        onChange={setOrigin}
+        searchable
+        clearable
+        autoFocus
+      />
+      <ArrowRight size={14} className="text-gray-400" style={{ alignSelf: "center" }} />
+      <Select
+        label="Destination"
+        placeholder="Any"
+        data={def.options}
+        value={destination}
+        onChange={setDestination}
+        searchable
+        clearable
+      />
+      <Button size="sm" onClick={apply} disabled={!(origin && destination)}>
+        Apply
+      </Button>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/format.ts b/apps/edr-freight-web/backoffice/src/components/filters/format.ts
index c3ca16798..24489abf8 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/format.ts
+++ b/apps/edr-freight-web/backoffice/src/components/filters/format.ts
@@ -13,6 +13,10 @@ export function formatFilterValue(def: FilterDef, value: FilterValue): string {
   if (def.type === "date" && value.v.length === 2) {
     return `${value.v[0].slice(0, 10)} → ${value.v[1].slice(0, 10)}`;
   }
+  if (def.type === "route" && value.v.length === 2) {
+    const label = (id: string) => def.options.find((o) => o.value === id)?.label ?? id;
+    return `${label(value.v[0])} → ${label(value.v[1])}`;
+  }
   return value.v.join(", ");
 }
 
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/types.ts b/apps/edr-freight-web/backoffice/src/components/filters/types.ts
index 597d74f6f..9f0c35d43 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/types.ts
+++ b/apps/edr-freight-web/backoffice/src/components/filters/types.ts
@@ -1,4 +1,4 @@
-export type FilterType = "text" | "enum" | "date" | "number" | "boolean";
+export type FilterType = "text" | "enum" | "date" | "number" | "boolean" | "route";
 
 export type Operator = "is" | "isNot" | "contains" | "between" | "before" | "after";
 
@@ -9,6 +9,7 @@ export const DEFAULT_OP: Record<FilterType, Operator> = {
   date: "between",
   number: "is",
   boolean: "is",
+  route: "is",
 };
 
 export const OPERATOR_LABELS: Record<Operator, string> = {
@@ -87,12 +88,25 @@ export interface BooleanFilterDef extends FilterDefBase {
   falseLabel?: string;
 }
 
+/**
+ * Origin + destination picked together as one pill — `v` is always the
+ * 2-slot pair `[originYardId, destinationYardId]`, never partial (the body's
+ * Apply button stays disabled until both sides are chosen, same rule
+ * `DateBody` uses for a `between` range). One shared `options` list drives
+ * both selects.
+ */
+export interface RouteFilterDef extends FilterDefBase {
+  type: "route";
+  options: FilterOption[];
+}
+
 export type FilterDef =
   | TextFilterDef
   | EnumFilterDef
   | DateFilterDef
   | NumberFilterDef
-  | BooleanFilterDef;
+  | BooleanFilterDef
+  | RouteFilterDef;
 
 /** A page's sort options — value is already `"field:DIR"`, the codebase's existing convention. */
 export interface SortOption {
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
index cef8ca21a..c1b5c85ac 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
@@ -136,9 +136,9 @@ export default function BookingRequestsPage() {
       { key: "statuses", label: "Status", type: "enum", options: STATUS_OPTIONS },
       {
         key: "tradeDirection", label: "Direction", type: "enum", multiple: false,
-        options: filterOptions(TRADE_DIRECTION_OPTIONS), secondary: true,
+        options: filterOptions(TRADE_DIRECTION_OPTIONS),
       },
-      { key: "freightType", label: "Freight", type: "enum", multiple: false, options: FREIGHT_TYPE_OPTIONS, secondary: true },
+      { key: "freightType", label: "Freight", type: "enum", multiple: false, options: FREIGHT_TYPE_OPTIONS },
       { key: "paymentStatus", label: "Payment", type: "enum", multiple: false, options: PAYMENT_STATUS_OPTIONS, secondary: true },
       {
         // Wins over the `paymentStatus` filter above — the queue is by
@@ -149,8 +149,10 @@ export default function BookingRequestsPage() {
         toParams: (v) => (v.v[0] === "true" ? { paymentStatus: "PAID", assignedToSchedule: "false" } : {}),
       },
       { key: "isGovernment", label: "Ownership", type: "enum", multiple: false, options: OWNERSHIP_OPTIONS, secondary: true },
-      { key: "originYardId", label: "Origin", type: "enum", multiple: false, options: yardOptions, secondary: true },
-      { key: "destinationYardId", label: "Destination", type: "enum", multiple: false, options: yardOptions, secondary: true },
+      {
+        key: "route", label: "Route", type: "route", options: yardOptions, secondary: true,
+        toParams: ({ v }) => ({ originYardId: v[0], destinationYardId: v[1] }),
+      },
       { key: "created", label: "Created", type: "date", secondary: true, toParams: ({ v }) => ({ createdFrom: v[0], createdTo: v[1] }) },
       { key: "scheduled", label: "Scheduled", type: "date", secondary: true, toParams: ({ v }) => ({ scheduledFrom: v[0], scheduledTo: v[1] }) },
     ],
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
index e50a090a2..969c97d0c 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
@@ -23,6 +23,8 @@ import {
 } from "lucide-react";
 import { useCallback, useMemo, type ReactNode } from "react";
 import { useNavigate } from "react-router-dom";
+import { useQuery } from "@tanstack/react-query";
+import { api } from "@/services/api";
 
 import { ContractStatusBadge } from "@/components/contracts/ContractStatusBadge";
 import { bookingTable } from "@/components/bookings/booking-ui.styles";
@@ -103,6 +105,16 @@ export default function ContractRequestsPage() {
   const navigate = useNavigate();
   const { filterOptions } = useMyTradeAccess();
 
+  // Yard options for the route filter (shared routes reference list, same
+  // query BookingRequestsPage uses).
+  const { data: yardRefs } = useQuery(
+    api.routes.yards.queryOptions({ staleTime: 5 * 60_000 }),
+  );
+  const yardOptions = useMemo(
+    () => (yardRefs ?? []).map((y) => ({ value: y.id, label: y.label ?? y.code })),
+    [yardRefs],
+  );
+
   // Static shape only (no facet counts) — this is what useFilters needs to
   // parse the URL and build API params. Counts are attached separately below,
   // for rendering only, once the summary query (which itself depends on
@@ -123,7 +135,6 @@ export default function ContractRequestsPage() {
         type: "enum",
         multiple: false,
         options: filterOptions(TRADE_DIRECTION_OPTIONS),
-        secondary: true,
       },
       {
         key: "freightType",
@@ -131,7 +142,6 @@ export default function ContractRequestsPage() {
         type: "enum",
         multiple: false,
         options: FREIGHT_TYPE_OPTIONS,
-        secondary: true,
       },
       {
         key: "paymentCurrency",
@@ -150,8 +160,16 @@ export default function ContractRequestsPage() {
         // onChange, so this just routes to the API's existing param names.
         toParams: ({ v }) => ({ createdFrom: v[0], createdTo: v[1] }),
       },
+      {
+        key: "route",
+        label: "Route",
+        type: "route",
+        options: yardOptions,
+        secondary: true,
+        toParams: ({ v }) => ({ originYardId: v[0], destinationYardId: v[1] }),
+      },
     ],
-    [filterOptions],
+    [filterOptions, yardOptions],
   );
 
   const controls = useFilters(filterDefs, {

From 4b4ab21ea1a2725b589934261201e34534f028d4 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 15 Aug 2026 07:31:19 +0000
Subject: [PATCH 103/174] fix(filters): auto-apply radios, route popover bug,
 date operators, polish
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Radio-based filters (single-select enum, boolean) apply the instant
  an option is picked and close — no Apply click needed. Checkbox
  (multi-select) keeps the explicit Apply, since picking several is a
  multi-step gesture.
- Route filter's Select dropdowns portal separately by default, so a
  click landed as "outside" the outer pill popover and closed it
  before a pick registered — same class of bug DateBody had.
  `comboboxProps={{ withinPortal: false }}` fixes it.
- Route filter now pinned by default on both pages instead of behind
  More filters.
- Date filter: widened to before/between/after (repository already
  applies each bound independently) via a new `dateRangeParams`
  helper — the old positional `{v[0]:from, v[1]:to}` mapping silently
  put a "before" pick in the from param. Added a calendar icon + sm
  sizing, and a wider popover so the range presets sidebar has room.
- Pill's clear (X) button enlarged; search box border/text opacity
  strengthened to match the pill trigger restyle.
---
 .../src/components/filters/FilterBar.tsx      | 11 ++++++++-
 .../src/components/filters/FilterPill.tsx     | 10 +++++---
 .../components/filters/bodies/BooleanBody.tsx | 14 +++++------
 .../components/filters/bodies/DateBody.tsx    |  5 ++++
 .../components/filters/bodies/EnumBody.tsx    | 23 ++++++++++++++-----
 .../components/filters/bodies/RouteBody.tsx   |  9 ++++++++
 .../src/components/filters/dates.ts           | 20 ++++++++++++++++
 .../pages/bookings/BookingRequestsPage.tsx    | 16 +++++++++----
 .../pages/contracts/ContractRequestsPage.tsx  | 11 +++++----
 9 files changed, 93 insertions(+), 26 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx b/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
index 6a0aaac96..e42b70252 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/FilterBar.tsx
@@ -84,7 +84,16 @@ export function FilterBar({
             onChange={(e) => controls.setSearchText(e.currentTarget.value)}
             size="xs"
             radius="lg"
-            styles={{ input: { fontWeight: 400 } }}
+            // Regular weight (not the Button-driven 600 the rest of the bar
+            // uses) and a solid, fully-opaque border/text — same "opaque, not
+            // faint" fix the inactive pill trigger got.
+            styles={{
+              input: {
+                fontWeight: 400,
+                borderColor: "var(--mantine-color-gray-6)",
+                color: "var(--mantine-color-gray-9)",
+              },
+            }}
             style={{ minWidth: 160, flex: "1 1 160px" }}
           />
         )}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx b/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx
index 0275f67ad..af97d2fcf 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/FilterPill.tsx
@@ -20,6 +20,10 @@ const BODIES: Record<FilterDef["type"], React.ComponentType<any>> = {
   route: RouteBody,
 };
 
+// Most bodies fit a narrow popover; a date range needs room for the presets
+// sidebar next to the calendar, so it gets a wider minimum.
+const DROPDOWN_WIDTH: Partial<Record<FilterDef["type"], number>> = { date: 340 };
+
 export interface FilterPillProps {
   def: FilterDef;
   value: FilterValue | undefined;
@@ -57,7 +61,7 @@ export function FilterPill({ def, value, onChange, autoOpen }: FilterPillProps)
             active ? (
               <ActionIcon
                 component="span"
-                size={16}
+                size={22}
                 radius="xl"
                 variant="subtle"
                 color="edr-green"
@@ -66,7 +70,7 @@ export function FilterPill({ def, value, onChange, autoOpen }: FilterPillProps)
                   onChange(undefined);
                 }}
               >
-                <X size={12} />
+                <X size={16} />
               </ActionIcon>
             ) : (
               <ChevronDown size={14} />
@@ -77,7 +81,7 @@ export function FilterPill({ def, value, onChange, autoOpen }: FilterPillProps)
           {active ? `${def.label} | ${formatFilterValue(def, value!)}` : def.label}
         </Button>
       </Popover.Target>
-      <Popover.Dropdown miw={260} p="xs">
+      <Popover.Dropdown miw={DROPDOWN_WIDTH[def.type] ?? 260} p="xs">
         <Body def={def} value={value} onChange={onChange} onClose={() => setOpened(false)} />
       </Popover.Dropdown>
     </Popover>
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/bodies/BooleanBody.tsx b/apps/edr-freight-web/backoffice/src/components/filters/bodies/BooleanBody.tsx
index fc59fa3bb..cd9f8ed11 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/bodies/BooleanBody.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/bodies/BooleanBody.tsx
@@ -1,5 +1,5 @@
 import { useState } from "react";
-import { Button, Radio, Stack } from "@mantine/core";
+import { Radio, Stack } from "@mantine/core";
 
 import { DEFAULT_OP } from "../types";
 import type { BooleanFilterDef, Operator } from "../types";
@@ -10,23 +10,23 @@ export function BooleanBody({ def, value, onChange, onClose }: FilterBodyProps<B
   const [op, setOp] = useState<Operator>(value?.op ?? DEFAULT_OP.boolean);
   const [v, setV] = useState(value?.v[0] ?? "");
 
-  const apply = () => {
-    onChange(v ? { op, v: [v] } : undefined);
+  // Two mutually-exclusive options — apply the moment one is picked, same as
+  // EnumBody's single-select radio. No Apply button needed.
+  const pick = (next: string) => {
+    setV(next);
+    onChange({ op, v: [next] });
     onClose();
   };
 
   return (
     <Stack gap="xs">
       <OperatorSelect def={def} value={op} onChange={setOp} />
-      <Radio.Group value={v} onChange={setV}>
+      <Radio.Group value={v} onChange={pick}>
         <Stack gap={6}>
           <Radio value="true" label={def.trueLabel ?? "Yes"} size="sm" />
           <Radio value="false" label={def.falseLabel ?? "No"} size="sm" />
         </Stack>
       </Radio.Group>
-      <Button size="sm" onClick={apply}>
-        Apply
-      </Button>
     </Stack>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/bodies/DateBody.tsx b/apps/edr-freight-web/backoffice/src/components/filters/bodies/DateBody.tsx
index a7c90c8c9..b2032170d 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/bodies/DateBody.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/bodies/DateBody.tsx
@@ -1,6 +1,7 @@
 import { useState } from "react";
 import { Button, Stack } from "@mantine/core";
 import { DatePickerInput } from "@mantine/dates";
+import { CalendarDays } from "lucide-react";
 
 import { getDateRangePresets } from "@/components/common/dateRangePresets";
 import { startOfDayIso, endOfDayIso, parseDateStr } from "../dates";
@@ -58,6 +59,8 @@ export function DateBody({ def, value, onChange, onClose }: FilterBodyProps<Date
       {op === "between" ? (
         <DatePickerInput
           type="range"
+          size="sm"
+          leftSection={<CalendarDays size={14} />}
           placeholder="Any"
           value={[from, to]}
           onChange={([f, t]) => {
@@ -71,6 +74,8 @@ export function DateBody({ def, value, onChange, onClose }: FilterBodyProps<Date
         />
       ) : (
         <DatePickerInput
+          size="sm"
+          leftSection={<CalendarDays size={14} />}
           placeholder="Any"
           value={from}
           onChange={setFrom}
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/bodies/EnumBody.tsx b/apps/edr-freight-web/backoffice/src/components/filters/bodies/EnumBody.tsx
index 459246dff..3bc352dcb 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/bodies/EnumBody.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/bodies/EnumBody.tsx
@@ -56,11 +56,20 @@ export function EnumBody({ def, value, onChange, onClose }: FilterBodyProps<Enum
 
   const hiddenCount = def.options.length - visible.length;
 
-  const apply = () => {
-    onChange(selected.length ? { op, v: selected } : undefined);
+  const apply = (v: string[] = selected) => {
+    onChange(v.length ? { op, v } : undefined);
     onClose();
   };
 
+  // Single-select is a radio pick, not a build-up-a-set gesture — apply the
+  // instant one is chosen, same as picking an option in a plain Select.
+  // Checkbox (multiple) still needs the explicit Apply: picking several
+  // options is a multi-step gesture the popover shouldn't close mid-way through.
+  const applyRadio = (v: string) => {
+    setSelected([v]);
+    apply([v]);
+  };
+
   return (
     <Stack gap="xs">
       <OperatorSelect def={def} value={op} onChange={setOp} />
@@ -95,7 +104,7 @@ export function EnumBody({ def, value, onChange, onClose }: FilterBodyProps<Enum
         ) : (
           <Radio.Group
             value={selected[0] ?? ""}
-            onChange={(v) => setSelected(v ? [v] : [])}
+            onChange={(v) => v && applyRadio(v)}
             aria-label={`Filter by ${def.label}`}
           >
             <Stack gap={0}>
@@ -120,9 +129,11 @@ export function EnumBody({ def, value, onChange, onClose }: FilterBodyProps<Enum
           </UnstyledButton>
         )}
       </Stack>
-      <Button size="sm" onClick={apply}>
-        Apply
-      </Button>
+      {multiple && (
+        <Button size="sm" onClick={() => apply()}>
+          Apply
+        </Button>
+      )}
     </Stack>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/bodies/RouteBody.tsx b/apps/edr-freight-web/backoffice/src/components/filters/bodies/RouteBody.tsx
index 9e86199a9..55097b05b 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/bodies/RouteBody.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/bodies/RouteBody.tsx
@@ -20,6 +20,13 @@ export function RouteBody({ def, value, onChange, onClose }: FilterBodyProps<Rou
     onClose();
   };
 
+  // This popover already lives inside FilterPill's own Popover. A Select's
+  // dropdown portals separately by default, so a click on an option registers
+  // as "outside" the outer Popover and closes the whole filter before a pick
+  // lands — same nested-portal bug DateBody had. Un-portalling keeps it
+  // inside the outer popover's DOM subtree instead.
+  const comboboxProps = { withinPortal: false } as const;
+
   return (
     <Stack gap="xs" w={240}>
       <Select
@@ -28,6 +35,7 @@ export function RouteBody({ def, value, onChange, onClose }: FilterBodyProps<Rou
         data={def.options}
         value={origin}
         onChange={setOrigin}
+        comboboxProps={comboboxProps}
         searchable
         clearable
         autoFocus
@@ -39,6 +47,7 @@ export function RouteBody({ def, value, onChange, onClose }: FilterBodyProps<Rou
         data={def.options}
         value={destination}
         onChange={setDestination}
+        comboboxProps={comboboxProps}
         searchable
         clearable
       />
diff --git a/apps/edr-freight-web/backoffice/src/components/filters/dates.ts b/apps/edr-freight-web/backoffice/src/components/filters/dates.ts
index f85fc31d0..b51ef493c 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/dates.ts
+++ b/apps/edr-freight-web/backoffice/src/components/filters/dates.ts
@@ -1,3 +1,5 @@
+import type { FilterValue } from "./types";
+
 /** Local start-of-day -> ISO, for inclusive "from" date filters. Lifted out of
  * ContractRequestsPage (where it was duplicated into BookingRequestsPage) so
  * every date filter shares one definition. */
@@ -29,3 +31,21 @@ export function parseDateStr(dateStr: string): Date {
   const [y, m, d] = dateStr.split("-").map(Number);
   return new Date(y, (m || 1) - 1, d || 1);
 }
+
+/**
+ * `toParams` for a date `FilterDef` widened to `["between", "before", "after"]`
+ * operators. `DateBody` always emits a single-element `v` for before/after —
+ * a plain positional `{[fromKey]: v[0], [toKey]: v[1]}` mapping (the
+ * between-only default) would wrongly land a "before" pick in `fromKey`
+ * instead of `toKey`. This routes each operator to the right bound.
+ */
+export function dateRangeParams(
+  fromKey: string,
+  toKey: string,
+): (v: FilterValue) => Record<string, string | undefined> {
+  return (value) => {
+    if (value.op === "before") return { [toKey]: value.v[0] };
+    if (value.op === "after") return { [fromKey]: value.v[0] };
+    return { [fromKey]: value.v[0], [toKey]: value.v[1] };
+  };
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
index c1b5c85ac..b41367619 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
@@ -26,7 +26,7 @@ import { useQuery } from "@tanstack/react-query";
 
 import { BookingActionsMenu } from "@/components/bookings/BookingActionsMenu";
 import { formatDate, humanize } from "@/lib/format";
-import { FilterBar, useFilters, type FilterDef } from "@/components/filters";
+import { FilterBar, dateRangeParams, useFilters, type FilterDef } from "@/components/filters";
 import { BookingPriorityBadge } from "@/components/bookings/BookingPriorityBadge";
 import { BookingStatusBadge } from "@/components/bookings/BookingStatusBadge";
 // BookingStatusTabs / Operations* queues removed — replaced by booking-kind tabs.
@@ -150,11 +150,19 @@ export default function BookingRequestsPage() {
       },
       { key: "isGovernment", label: "Ownership", type: "enum", multiple: false, options: OWNERSHIP_OPTIONS, secondary: true },
       {
-        key: "route", label: "Route", type: "route", options: yardOptions, secondary: true,
+        key: "route", label: "Route", type: "route", options: yardOptions,
         toParams: ({ v }) => ({ originYardId: v[0], destinationYardId: v[1] }),
       },
-      { key: "created", label: "Created", type: "date", secondary: true, toParams: ({ v }) => ({ createdFrom: v[0], createdTo: v[1] }) },
-      { key: "scheduled", label: "Scheduled", type: "date", secondary: true, toParams: ({ v }) => ({ scheduledFrom: v[0], scheduledTo: v[1] }) },
+      {
+        key: "created", label: "Created", type: "date", secondary: true,
+        operators: ["between", "before", "after"],
+        toParams: dateRangeParams("createdFrom", "createdTo"),
+      },
+      {
+        key: "scheduled", label: "Scheduled", type: "date", secondary: true,
+        operators: ["between", "before", "after"],
+        toParams: dateRangeParams("scheduledFrom", "scheduledTo"),
+      },
     ],
     [filterOptions, yardOptions],
   );
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
index 969c97d0c..cf87a1e1b 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
@@ -52,7 +52,7 @@ import {
   DataTableFooter,
   type ColumnDef,
 } from "@edr/ui-common";
-import { FilterBar, useFilters, type FilterDef } from "@/components/filters";
+import { FilterBar, dateRangeParams, useFilters, type FilterDef } from "@/components/filters";
 
 /** Every filterable status — the pill tabs are gone, so the select carries them all. */
 const STATUS_OPTIONS = CONTRACT_LIST_TABS.flatMap((t) => t.statuses ?? []).map(
@@ -156,16 +156,17 @@ export default function ContractRequestsPage() {
         label: "Created",
         type: "date",
         secondary: true,
-        // DateBody already converts to start/end-of-day ISO before calling
-        // onChange, so this just routes to the API's existing param names.
-        toParams: ({ v }) => ({ createdFrom: v[0], createdTo: v[1] }),
+        // Before/after are safe to expose: the repository applies
+        // createdFrom/createdTo independently, so a single-sided bound
+        // already works server-side.
+        operators: ["between", "before", "after"],
+        toParams: dateRangeParams("createdFrom", "createdTo"),
       },
       {
         key: "route",
         label: "Route",
         type: "route",
         options: yardOptions,
-        secondary: true,
         toParams: ({ v }) => ({ originYardId: v[0], destinationYardId: v[1] }),
       },
     ],

From 6c4969f3fd62d9d7a7972714081d0aff4997a2cf Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 15 Aug 2026 07:51:31 +0000
Subject: [PATCH 104/174] feat(filters): migrate FleetCrudPages to the pill
 filter bar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers 6 pages at once: the shared FleetCrudPage<T> factory
(TrainMasterDataPage, WagonsCrudPage, ContainersCrudPage,
CargoesCrudPage, LocomotivesCrudPage) plus the standalone
WagonTypesCrudPage.

- FleetCrudPage gains an optional `statusOptions` prop; when passed it
  builds a Status enum FilterDef and swaps the old plain search Input
  for FilterBar + useFilters + applyClientFilters (client-bridge —
  these endpoints return bare arrays). Status option lists sourced
  from the actual entity/enum definitions, not guessed, and reused in
  each page's create/edit form Select instead of duplicating them.
  Column-header click-to-sort is untouched (separate mechanism).
- WagonTypesCrudPage (hand-rolled, not on the factory) gets a boolean
  Active/Inactive filter the same way, replacing its search-text hack
  that string-matched "active"/"inactive" against the query.
---
 .../src/pages/fleet/FleetCrudPages.tsx        | 165 +++++++++++-------
 1 file changed, 101 insertions(+), 64 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/pages/fleet/FleetCrudPages.tsx b/apps/edr-freight-web/backoffice/src/pages/fleet/FleetCrudPages.tsx
index 74ea2c3eb..cf86434ea 100644
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/FleetCrudPages.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/FleetCrudPages.tsx
@@ -1,5 +1,5 @@
 import { useMutation, useQuery } from '@tanstack/react-query';
-import { Edit, Eye, Plus, Search, Trash2 } from 'lucide-react';
+import { Edit, Eye, Plus, Trash2 } from 'lucide-react';
 import { FormEvent, ReactNode, useMemo, useState } from 'react';
 
 import { api } from '@/services/api';
@@ -44,6 +44,13 @@ import type { Train } from '@/services/trains.service';
 import type { WagonType } from '@/services/wagon-types.service';
 import type { Wagon } from '@/services/wagon.service';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@edr/ui-common';
+import {
+    applyClientFilters,
+    FilterBar,
+    useFilters,
+    type FilterDef,
+    type FilterOption,
+} from '@/components/filters';
 
 type FormValue = string | number | boolean | string[];
 
@@ -86,6 +93,8 @@ type FleetCrudPageProps<T extends { id: string }> = {
   hideViewAction?: boolean;
   /** Optional custom actions rendered before the view/edit/delete buttons in each row. */
   rowActions?: (item: T) => React.ReactNode;
+  /** Enables the Status filter pill; the item's `status` field is matched against these. */
+  statusOptions?: FilterOption[];
 };
 
 const normalizePayload = (values: Record<string, FormValue>) =>
@@ -172,9 +181,16 @@ function FleetCrudPage<T extends { id: string }>({
   removeSuccessMessage,
   hideViewAction = false,
   rowActions,
+  statusOptions,
 }: FleetCrudPageProps<T>) {
-  const [search, setSearch] = useState('');
-  const [page, setPage] = useState(1);
+  const filterDefs: FilterDef[] = useMemo(
+    () =>
+      statusOptions
+        ? [{ key: 'status', label: 'Status', type: 'enum', multiple: false, options: statusOptions }]
+        : [],
+    [statusOptions],
+  );
+  const controls = useFilters(filterDefs, { pageSize: 10 });
   const [sortKey, setSortKey] = useState<string>('');
   const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc');
   const [formOpen, setFormOpen] = useState(false);
@@ -184,11 +200,13 @@ function FleetCrudPage<T extends { id: string }>({
   const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({});
   const { toast } = useToast();
 
-  const filtered = useMemo(() => {
-    const query = search.trim().toLowerCase();
-    if (!query) return data ?? [];
-    return (data ?? []).filter((item) => searchText(item).toLowerCase().includes(query));
-  }, [data, search, searchText]);
+  const filtered = useMemo(
+    () =>
+      applyClientFilters(data ?? [], filterDefs, controls.values, controls.searchText, {
+        searchValue: searchText,
+      }),
+    [data, filterDefs, controls.values, controls.searchText, searchText],
+  );
   const sorted = useMemo(() => {
     if (!sortKey) return filtered;
     return [...filtered].sort((a, b) => {
@@ -198,12 +216,13 @@ function FleetCrudPage<T extends { id: string }>({
       return sortDirection === 'asc' ? result : -result;
     });
   }, [filtered, sortDirection, sortKey]);
-  const pageSize = 10;
+  const pageSize = controls.pageSize;
+  const page = controls.page;
   const pageCount = Math.max(1, Math.ceil(sorted.length / pageSize));
   const paged = sorted.slice((page - 1) * pageSize, page * pageSize);
 
   const toggleSort = (key: string) => {
-    setPage(1);
+    controls.setPage(1);
     if (sortKey === key) {
       setSortDirection((current) => (current === 'asc' ? 'desc' : 'asc'));
       return;
@@ -298,18 +317,11 @@ function FleetCrudPage<T extends { id: string }>({
         </Button>
       </div>
 
-      <div className="flex max-w-md items-center gap-2 rounded-md border bg-background px-3">
-        <Search className="size-4 text-muted-foreground" />
-        <Input
-          className="border-0 px-0 shadow-none focus-visible:ring-0"
-          placeholder={`Search ${title.toLowerCase()}`}
-          value={search}
-          onChange={(event) => {
-            setSearch(event.target.value);
-            setPage(1);
-          }}
-        />
-      </div>
+      <FilterBar
+        defs={filterDefs}
+        controls={controls}
+        searchPlaceholder={`Search ${title.toLowerCase()}`}
+      />
 
       <div className="overflow-hidden rounded-lg border bg-card">
         <Table>
@@ -379,10 +391,10 @@ function FleetCrudPage<T extends { id: string }>({
           Showing {sorted.length === 0 ? 0 : (page - 1) * pageSize + 1}-{Math.min(page * pageSize, sorted.length)} of {sorted.length}
         </span>
         <div className="flex gap-2">
-          <Button variant="outline" size="sm" disabled={page === 1} onClick={() => setPage((current) => current - 1)}>
+          <Button variant="outline" size="sm" disabled={page === 1} onClick={() => controls.setPage(page - 1)}>
             Previous
           </Button>
-          <Button variant="outline" size="sm" disabled={page === pageCount} onClick={() => setPage((current) => current + 1)}>
+          <Button variant="outline" size="sm" disabled={page === pageCount} onClick={() => controls.setPage(page + 1)}>
             Next
           </Button>
         </div>
@@ -487,6 +499,47 @@ const statusBadge = (status?: string) => <Badge variant="outline">{status ?? '-'
 const optionLabel = (options: { value: string; label: string }[], value?: string | null) =>
   options.find((option) => option.value === value)?.label ?? value ?? '-';
 
+const TRAIN_STATUS_OPTIONS: FilterOption[] = [
+  { value: 'AVAILABLE', label: 'Available' },
+  { value: 'SCHEDULED', label: 'Scheduled' },
+  { value: 'IN_SERVICE', label: 'In service' },
+  { value: 'UNDER_MAINTENANCE', label: 'Under maintenance' },
+  { value: 'OUT_OF_SERVICE', label: 'Out of service' },
+  { value: 'DEACTIVATED', label: 'Deactivated' },
+];
+
+const WAGON_STATUS_OPTIONS: FilterOption[] = [
+  { value: 'AVAILABLE', label: 'Available' },
+  { value: 'IMPORT_READY', label: 'Import ready' },
+  { value: 'EXPORT_READY', label: 'Export ready' },
+  { value: 'ASSIGNED', label: 'Assigned' },
+  { value: 'MAINTENANCE', label: 'Maintenance' },
+  { value: 'DETAINED', label: 'Detained' },
+];
+
+const CONTAINER_STATUS_OPTIONS: FilterOption[] = [
+  { value: 'AVAILABLE', label: 'Available' },
+  { value: 'LOADED', label: 'Loaded' },
+  { value: 'IN_TRANSIT', label: 'In transit' },
+  { value: 'MAINTENANCE', label: 'Maintenance' },
+  { value: 'DAMAGED', label: 'Damaged' },
+];
+
+const CARGO_STATUS_OPTIONS: FilterOption[] = [
+  { value: 'PENDING', label: 'Pending' },
+  { value: 'LOADED', label: 'Loaded' },
+  { value: 'IN_TRANSIT', label: 'In transit' },
+  { value: 'DELIVERED', label: 'Delivered' },
+  { value: 'UNLOADED', label: 'Unloaded' },
+];
+
+const LOCOMOTIVE_STATUS_OPTIONS: FilterOption[] = [
+  { value: 'AVAILABLE', label: 'Available' },
+  { value: 'MAINTENANCE', label: 'Maintenance' },
+  { value: 'ASSIGNED', label: 'Assigned' },
+  { value: 'OUT_OF_SERVICE', label: 'Out of service' },
+];
+
 export function TrainMasterDataPage() {
   const query = useQuery(api.trains.list.queryOptions());
   return (
@@ -499,6 +552,7 @@ export function TrainMasterDataPage() {
       create={useMutation(api.trains.create.mutationOptions())}
       update={useMutation(api.trains.update.mutationOptions())}
       remove={useMutation(api.trains.remove.mutationOptions())}
+      statusOptions={TRAIN_STATUS_OPTIONS}
       searchText={(train) => [train.code, train.trainNumber, train.trainName, train.status].join(' ')}
       columns={[
         { key: 'code', label: 'Code' },
@@ -522,14 +576,17 @@ export function TrainMasterDataPage() {
   );
 }
 
+const WAGON_TYPE_FILTER_DEFS: FilterDef[] = [
+  { key: 'isActive', label: 'Status', type: 'boolean', trueLabel: 'Active', falseLabel: 'Inactive' },
+];
+
 export function WagonTypesCrudPage() {
   const query = useQuery(api.wagonTypes.list.queryOptions());
   const create = useMutation(api.wagonTypes.create.mutationOptions());
   const update = useMutation(api.wagonTypes.update.mutationOptions());
   const remove = useMutation(api.wagonTypes.remove.mutationOptions());
   const { toast } = useToast();
-  const [search, setSearch] = useState('');
-  const [page, setPage] = useState(1);
+  const controls = useFilters(WAGON_TYPE_FILTER_DEFS, { pageSize: 10 });
   const [sortKey, setSortKey] = useState<keyof WagonType>('code');
   const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc');
   const [formOpen, setFormOpen] = useState(false);
@@ -546,18 +603,15 @@ export function WagonTypesCrudPage() {
   });
   const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({});
 
-  const pageSize = 10;
-  const filtered = useMemo(() => {
-    const queryText = search.trim().toLowerCase();
-    const rows = query.data ?? [];
-    if (!queryText) return rows;
-    return rows.filter((type) =>
-      [type.code, type.name, type.supportedLoadTypes?.join(' '), type.isActive ? 'active' : 'inactive']
-        .join(' ')
-        .toLowerCase()
-        .includes(queryText),
-    );
-  }, [query.data, search]);
+  const pageSize = controls.pageSize;
+  const page = controls.page;
+  const filtered = useMemo(
+    () =>
+      applyClientFilters(query.data ?? [], WAGON_TYPE_FILTER_DEFS, controls.values, controls.searchText, {
+        searchValue: (type) => [type.code, type.name, type.supportedLoadTypes?.join(' ')].join(' '),
+      }),
+    [query.data, controls.values, controls.searchText],
+  );
 
   const sorted = useMemo(() => {
     return [...filtered].sort((left, right) => {
@@ -573,7 +627,7 @@ export function WagonTypesCrudPage() {
   const isSaving = create.isPending || update.isPending;
 
   const toggleSort = (key: keyof WagonType) => {
-    setPage(1);
+    controls.setPage(1);
     if (sortKey === key) {
       setSortDirection((current) => (current === 'asc' ? 'desc' : 'asc'));
       return;
@@ -689,16 +743,7 @@ export function WagonTypesCrudPage() {
           </MantineButton>
         </Group>
 
-        <TextInput
-          maw={420}
-          leftSection={<Search size={16} />}
-          placeholder="Search wagon types"
-          value={search}
-          onChange={(event) => {
-            setSearch(event.currentTarget.value);
-            setPage(1);
-          }}
-        />
+        <FilterBar defs={WAGON_TYPE_FILTER_DEFS} controls={controls} searchPlaceholder="Search wagon types" />
 
         <Paper withBorder radius="md">
           <ScrollArea>
@@ -789,7 +834,7 @@ export function WagonTypesCrudPage() {
             Showing {sorted.length === 0 ? 0 : (page - 1) * pageSize + 1}-{Math.min(page * pageSize, sorted.length)} of{' '}
             {sorted.length}
           </Text>
-          <Pagination total={pageCount} value={page} onChange={setPage} size="sm" />
+          <Pagination total={pageCount} value={page} onChange={controls.setPage} size="sm" />
         </Group>
       </Stack>
 
@@ -906,6 +951,7 @@ export function WagonsCrudPage() {
       create={useMutation(api.wagons.create.mutationOptions())}
       update={useMutation(api.wagons.update.mutationOptions())}
       remove={useMutation(api.wagons.remove.mutationOptions())}
+      statusOptions={WAGON_STATUS_OPTIONS}
       searchText={(wagon) => [
         wagon.wagonNumber,
         wagon.wagonTypeId,
@@ -959,14 +1005,7 @@ export function WagonsCrudPage() {
           key: 'status',
           label: 'Status',
           type: 'select',
-          options: [
-            { value: 'AVAILABLE', label: 'Available' },
-            { value: 'IMPORT_READY', label: 'Import ready' },
-            { value: 'EXPORT_READY', label: 'Export ready' },
-            { value: 'ASSIGNED', label: 'Assigned' },
-            { value: 'MAINTENANCE', label: 'Maintenance' },
-            { value: 'DETAINED', label: 'Detained' },
-          ],
+          options: WAGON_STATUS_OPTIONS,
         },
         { key: 'notes', label: 'Notes' },
       ]}
@@ -999,6 +1038,7 @@ export function ContainersCrudPage() {
       create={useMutation(api.containers.create.mutationOptions())}
       update={useMutation(api.containers.update.mutationOptions())}
       remove={useMutation(api.containers.remove.mutationOptions())}
+      statusOptions={CONTAINER_STATUS_OPTIONS}
       searchText={(container) => [container.containerNumber, container.containerTypeId, container.wagonId, container.status].join(' ')}
       columns={[
         { key: 'containerNumber', label: 'Number' },
@@ -1058,6 +1098,7 @@ export function CargoesCrudPage() {
       create={useMutation(api.cargoes.create.mutationOptions())}
       update={useMutation(api.cargoes.update.mutationOptions())}
       remove={useMutation(api.cargoes.remove.mutationOptions())}
+      statusOptions={CARGO_STATUS_OPTIONS}
       searchText={(cargo) => [cargo.cargoReference, cargo.description, cargo.containerId, cargo.status].join(' ')}
       columns={[
         { key: 'cargoReference', label: 'Reference' },
@@ -1122,6 +1163,7 @@ export function LocomotivesCrudPage() {
       removeActionLabel="Decommission"
       removeConfirmMessage="Decommission this locomotive?"
       removeSuccessMessage="Locomotive decommissioned"
+      statusOptions={LOCOMOTIVE_STATUS_OPTIONS}
       searchText={(locomotive) =>
         [
           locomotive.code,
@@ -1166,12 +1208,7 @@ export function LocomotivesCrudPage() {
           label: 'Status',
           type: 'select',
           required: true,
-          options: [
-            { value: 'AVAILABLE', label: 'Available' },
-            { value: 'MAINTENANCE', label: 'Maintenance' },
-            { value: 'ASSIGNED', label: 'Assigned' },
-            { value: 'OUT_OF_SERVICE', label: 'Out of service' },
-          ],
+          options: LOCOMOTIVE_STATUS_OPTIONS,
         },
         { key: 'maxPullWeightTons', label: 'Max pulling weight (tons)', type: 'number', required: true },
         { key: 'maxTrainLengthMeters', label: 'Max train length (meters)', type: 'number', required: true },

From 69805315d96ebe95debb57c2c86f049ffeb7d044 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 15 Aug 2026 08:07:06 +0000
Subject: [PATCH 105/174] feat: dev and staging bypass

---
 apps/edr-freight-api/.env.example             |  6 ++
 .../src/common/dev-bypass.util.ts             | 13 ++++
 .../src/modules/otp/otp.service.ts            | 26 ++++++-
 .../src/modules/payment/payment.service.ts    | 75 ++++++++++++-------
 .../modules/verifayda/verifayda.service.ts    | 25 +++++++
 .../src/components/FaydaVerifyPanel.tsx       | 21 ++++++
 .../portal/src/utils/dev-bypass.ts            |  4 +
 apps/edr-freight-web/portal/src/vite-env.d.ts |  2 +
 8 files changed, 142 insertions(+), 30 deletions(-)
 create mode 100644 apps/edr-freight-api/src/common/dev-bypass.util.ts
 create mode 100644 apps/edr-freight-web/portal/src/utils/dev-bypass.ts

diff --git a/apps/edr-freight-api/.env.example b/apps/edr-freight-api/.env.example
index 5a145a0db..d2359dd97 100644
--- a/apps/edr-freight-api/.env.example
+++ b/apps/edr-freight-api/.env.example
@@ -1,4 +1,10 @@
 # Copy to .env for local/docker compose (not committed).
+
+# Set to "dev" or "staging" to bypass OTP (fixed code 000000 also accepted),
+# payment (invoice auto-marked paid on initiate, no gateway call) and Fayda
+# (canned verified profile, no eSignet call). Leave unset in production.
+ENV=
+
 PORT=3001
 # @tria-plc/auditlog's client interceptor stamps every AuditLog row's
 # `application` from this env var directly, bypassing MezgebModule.forRoot's
diff --git a/apps/edr-freight-api/src/common/dev-bypass.util.ts b/apps/edr-freight-api/src/common/dev-bypass.util.ts
new file mode 100644
index 000000000..5e6e39e8d
--- /dev/null
+++ b/apps/edr-freight-api/src/common/dev-bypass.util.ts
@@ -0,0 +1,13 @@
+/**
+ * Dev/staging bypass gate for OTP, payment and Fayda verification.
+ *
+ * Gated purely on `ENV` (dev|staging) — never on NODE_ENV, so it can't be
+ * mistaken for a prod-vs-non-prod switch. `ENV` is simply left unset in
+ * production, so this is always false there.
+ */
+export function isBypassEnv(): boolean {
+  return ["dev", "staging"].includes(process.env.ENV ?? "");
+}
+
+/** Fixed code accepted in addition to the real one when isBypassEnv(). */
+export const DEV_BYPASS_OTP = "000000";
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 42d46226a..b27520c25 100644
--- a/apps/edr-freight-api/src/modules/otp/otp.service.ts
+++ b/apps/edr-freight-api/src/modules/otp/otp.service.ts
@@ -8,6 +8,7 @@ import { OtpRepository } from "./otp.repository";
 
 import { NotificationsService } from "../notifications/notifications.service";
 import { EmailClientService } from "../notifications/email-client.service";
+import { isBypassEnv, DEV_BYPASS_OTP } from "../../common/dev-bypass.util";
 
 /**
  * Where a code goes. At least one of phone/email must be set — enforced by the
@@ -146,6 +147,21 @@ export class OtpService {
         `otp.issue channels=${channels.join("+")} target=${label} action=${rotated ? "rotate" : "create"}`,
       );
 
+      // Dev/staging only: the row above still exists (so a real code would
+      // still verify), but skip the real SMS/email send — no carrier cost, no
+      // dependency on RabbitMQ/the mail relay being up. Verify with the fixed
+      // DEV_BYPASS_OTP code instead of whatever landed in the row.
+      if (isBypassEnv()) {
+        this.logger.warn(
+          `otp.dispatch.bypassed target=${label} — dev/staging, no real SMS/email sent (verify with ${DEV_BYPASS_OTP})`,
+        );
+        return {
+          success: true,
+          delivered: true,
+          message: "OTP sent successfully",
+        };
+      }
+
       // 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
@@ -394,7 +410,10 @@ export class OtpService {
 
     // invalid otp — per-target attempt cap so a 6-digit code can't be
     // brute-forced within its TTL; the code is burned once the budget is spent.
-    if (otpData.otp !== otp) {
+    // Dev/staging only: a fixed code verifies any pending OTP row without
+    // knowing the real one — the row still has to exist (sendOtp still runs).
+    const bypassed = isBypassEnv() && otp === DEV_BYPASS_OTP;
+    if (otpData.otp !== otp && !bypassed) {
       const attempts = (this.actionAttempts.get(key) ?? 0) + 1;
       if (attempts >= this.MAX_ACTION_ATTEMPTS) {
         await this.otpRepository.deleteOtp(otpData);
@@ -482,7 +501,10 @@ export class OtpService {
       );
     }
 
-    if (otpData.otp !== otp) {
+    // Dev/staging only: a fixed code verifies any pending OTP row without
+    // knowing the real one — the row still has to exist (sendOtp still runs).
+    const bypassed = isBypassEnv() && otp === DEV_BYPASS_OTP;
+    if (otpData.otp !== otp && !bypassed) {
       const attempts = (this.actionAttempts.get(key) ?? 0) + 1;
 
       if (attempts >= this.MAX_ACTION_ATTEMPTS) {
diff --git a/apps/edr-freight-api/src/modules/payment/payment.service.ts b/apps/edr-freight-api/src/modules/payment/payment.service.ts
index 037e188f8..168fa3df4 100644
--- a/apps/edr-freight-api/src/modules/payment/payment.service.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.service.ts
@@ -31,6 +31,7 @@ import {
   IntentStatusDto,
   PaymentPlatformDto,
 } from "./payments.dto";
+import { isBypassEnv } from "../../common/dev-bypass.util";
 
 /** Everything the gateway needs to open an intent. Amount/currency are supplied by
  *  the caller (billing) — this service never derives them from a domain record. */
@@ -256,34 +257,52 @@ export class PaymentService {
         );
       }
 
-      const snapshot = await this.paymentClient.initiate({
-        service: PaymentServiceEnum.FREIGHT,
-        referenceType: PaymentReferenceType.SHIPMENT,
-        referenceId: input.referenceId,
-        orderRef: input.orderRef,
-        // CBE_BILL must carry the REAL amount: /cbe/payment verifies what the customer was
-        // debited against the intent amount, so the dev shortcut would break it.
-        // CAC bank rejects amounts below 10 (DJF bounds 10–100,000), so its dev
-        // shortcut floor is 10, not 1.
-        // amountMinor: isCbeBill
-        //   ? input.amountMinor
-        //   : input.method === ProviderMethod.CAC_BANK
-        //     ? 10
-        //     : 1,
-        amountMinor: input.amountMinor,
-        currency: input.currency,
-        provider: input.method as ProviderMethod,
-        platform: input.platform,
-        payerAccount: input.payerAccount,
-        payerName: input.payerName,
-        expiresAt: input.expiresAt,
-        // bookingId lets the success page ack the redirect (→ PAYMENT_PROCESSING).
-        returnUrl:
-          input.returnUrl ??
-          `https://edrfreight.triaplc.com/payment/success?bookingId=${encodeURIComponent(input.referenceId)}`,
-        failureUrl:
-          input.failureUrl ?? "https://edrfreight.triaplc.com/payment/failure",
-      });
+      // Dev/staging only: skip the real gateway call entirely and report an
+      // immediate SUCCEEDED snapshot — everything below (upsert, settle,
+      // billing notify) runs exactly as it would for a real synchronous
+      // provider success.
+      const snapshot: PaymentIntentSnapshot = isBypassEnv()
+        ? {
+            intentId: `bypass-${input.referenceId}`,
+            service: PaymentServiceEnum.FREIGHT,
+            referenceType: PaymentReferenceType.SHIPMENT,
+            referenceId: input.referenceId,
+            merchantOrderId: input.orderRef,
+            provider: input.method as ProviderMethod,
+            status: ProviderPaymentStatus.SUCCEEDED,
+            amountMinor: input.amountMinor,
+            currency: input.currency,
+            providerTxnId: `bypass-${input.referenceId}`,
+            paidAt: new Date().toISOString(),
+          }
+        : await this.paymentClient.initiate({
+            service: PaymentServiceEnum.FREIGHT,
+            referenceType: PaymentReferenceType.SHIPMENT,
+            referenceId: input.referenceId,
+            orderRef: input.orderRef,
+            // CBE_BILL must carry the REAL amount: /cbe/payment verifies what the customer was
+            // debited against the intent amount, so the dev shortcut would break it.
+            // CAC bank rejects amounts below 10 (DJF bounds 10–100,000), so its dev
+            // shortcut floor is 10, not 1.
+            // amountMinor: isCbeBill
+            //   ? input.amountMinor
+            //   : input.method === ProviderMethod.CAC_BANK
+            //     ? 10
+            //     : 1,
+            amountMinor: input.amountMinor,
+            currency: input.currency,
+            provider: input.method as ProviderMethod,
+            platform: input.platform,
+            payerAccount: input.payerAccount,
+            payerName: input.payerName,
+            expiresAt: input.expiresAt,
+            // bookingId lets the success page ack the redirect (→ PAYMENT_PROCESSING).
+            returnUrl:
+              input.returnUrl ??
+              `https://edrfreight.triaplc.com/payment/success?bookingId=${encodeURIComponent(input.referenceId)}`,
+            failureUrl:
+              input.failureUrl ?? "https://edrfreight.triaplc.com/payment/failure",
+          });
 
       const immediateSuccess =
         snapshot.status === ProviderPaymentStatus.SUCCEEDED;
diff --git a/apps/edr-freight-api/src/modules/verifayda/verifayda.service.ts b/apps/edr-freight-api/src/modules/verifayda/verifayda.service.ts
index af627f25a..298cae11e 100644
--- a/apps/edr-freight-api/src/modules/verifayda/verifayda.service.ts
+++ b/apps/edr-freight-api/src/modules/verifayda/verifayda.service.ts
@@ -28,6 +28,11 @@ import {
   NormalizedFaydaUserInfo,
   VerifaydaPurpose,
 } from './verifayda.types';
+import { randomUUID } from 'node:crypto';
+import { isBypassEnv } from '../../common/dev-bypass.util';
+
+/** Sentinel `code` that skips the real eSignet exchange in dev/staging. */
+export const DEV_BYPASS_FAYDA_CODE = 'DEV_BYPASS';
 
 export interface StartVerificationInput {
   purpose: VerifaydaPurpose;
@@ -143,6 +148,26 @@ export class VerifaydaService {
   async completeVerification(
     query: VerifaydaCallbackDto,
   ): Promise<CompleteVerificationResult> {
+    // Dev/staging only: caller sends the sentinel code instead of a real
+    // eSignet redirect — skip the token exchange/session entirely and hand
+    // back a canned VERIFY result. `sub` is unique per call so binding both
+    // owner and PoA in the same bypass session doesn't collide.
+    if (isBypassEnv() && query.code === DEV_BYPASS_FAYDA_CODE) {
+      this.logger.warn('Fayda verification BYPASSED (dev/staging)');
+      return {
+        purpose: 'VERIFY',
+        verified: true,
+        sub: `dev-bypass-${randomUUID()}`,
+        fullName: 'Dev Bypass User',
+        email: 'dev-bypass@example.com',
+        phoneNumber: '+251900000000',
+        birthdate: '1990-01-01',
+        gender: 'M',
+        address: 'Dev Bypass Address',
+        userDataSaved: false,
+      };
+    }
+
     if (query.error) {
       this.logger.warn(`Fayda callback returned error: ${query.error}`);
       if (query.state) {
diff --git a/apps/edr-freight-web/portal/src/components/FaydaVerifyPanel.tsx b/apps/edr-freight-web/portal/src/components/FaydaVerifyPanel.tsx
index 4e6921e14..71cef57da 100644
--- a/apps/edr-freight-web/portal/src/components/FaydaVerifyPanel.tsx
+++ b/apps/edr-freight-web/portal/src/components/FaydaVerifyPanel.tsx
@@ -25,6 +25,10 @@ import {
   type IdentitySubject,
   type IdentityVerificationState,
 } from "@/services/verifayda.service";
+import { isBypassEnv } from "@/utils/dev-bypass";
+
+/** Sentinel code that skips the real eSignet exchange in dev/staging (see api's DEV_BYPASS_FAYDA_CODE). */
+const DEV_BYPASS_FAYDA_CODE = "DEV_BYPASS";
 
 interface FaydaVerifyPanelProps {
   subject: IdentitySubject;
@@ -80,6 +84,23 @@ export default function FaydaVerifyPanel({
     setError(null);
     setLoading(true);
     try {
+      // Dev/staging only: send the tab straight to /fayda/callback with the
+      // sentinel code instead of round-tripping through eSignet — that page's
+      // existing completeIdentity()/navigate-back logic runs unchanged.
+      if (isBypassEnv()) {
+        stashPendingVerification({
+          subject,
+          returnTo:
+            window.location.pathname +
+            window.location.search +
+            window.location.hash,
+        });
+        window.location.assign(
+          `/fayda/callback?code=${DEV_BYPASS_FAYDA_CODE}&state=bypass`,
+        );
+        return;
+      }
+
       const authorizationUrl = await verifaydaService.start();
       // Record who is being verified and where to come back to before the tab
       // leaves — /fayda/callback has no other way to know either.
diff --git a/apps/edr-freight-web/portal/src/utils/dev-bypass.ts b/apps/edr-freight-web/portal/src/utils/dev-bypass.ts
new file mode 100644
index 000000000..69eb23242
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/utils/dev-bypass.ts
@@ -0,0 +1,4 @@
+/** True when VITE_ENV is "dev" or "staging" — mirrors the API's ENV gate. */
+export function isBypassEnv(): boolean {
+  return ["dev", "staging"].includes(import.meta.env.VITE_ENV ?? "");
+}
diff --git a/apps/edr-freight-web/portal/src/vite-env.d.ts b/apps/edr-freight-web/portal/src/vite-env.d.ts
index a4955ecee..6a93b9e75 100644
--- a/apps/edr-freight-web/portal/src/vite-env.d.ts
+++ b/apps/edr-freight-web/portal/src/vite-env.d.ts
@@ -23,6 +23,8 @@ interface ImportMetaEnv {
   readonly VITE_POSTHOG_KEY?: string;
   /** Self-hosted PostHog instance URL. */
   readonly VITE_POSTHOG_HOST?: string;
+  /** "dev" | "staging" — enables the OTP/payment/Fayda bypass. Unset in prod. */
+  readonly VITE_ENV?: string;
 }
 
 interface ImportMeta {

From 83d9265e85bb828e747705183097b8fde1e5eb60 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Fri, 14 Aug 2026 13:51:00 +0000
Subject: [PATCH 106/174] Credit and Debt plus reason attribute inide register

---
 .../3550000000000-EimsDebitCreditNotes.ts     | 28 ++++++++++
 .../billing/eims-invoice.mapper.spec.ts       | 53 +++++++++++++++++++
 .../modules/billing/eims-invoice.mapper.ts    | 51 ++++++++++++++++--
 .../billing/entities/invoice.entity.ts        | 23 ++++++++
 .../src/modules/eims/eims-invoice-context.ts  |  9 ++++
 .../eims-invoice-registration.service.spec.ts | 52 ++++++++++++++++++
 .../eims/eims-invoice-registration.service.ts | 27 +++++++++-
 7 files changed, 237 insertions(+), 6 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3550000000000-EimsDebitCreditNotes.ts

diff --git a/apps/edr-freight-api/src/migrations/3550000000000-EimsDebitCreditNotes.ts b/apps/edr-freight-api/src/migrations/3550000000000-EimsDebitCreditNotes.ts
new file mode 100644
index 000000000..cf36df757
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3550000000000-EimsDebitCreditNotes.ts
@@ -0,0 +1,28 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Debit/credit note filing — confirmed directly by MoR support: same `/v1/register` endpoint,
+ * distinguished by `DocumentDetails.Type` ("DEB"/"CRE") + a `Reason`, linked to the original
+ * invoice via `ReferenceDetails.RelatedDocument`. See `Invoice.eimsDocumentType`.
+ */
+export class EimsDebitCreditNotes3550000000000 implements MigrationInterface {
+  name = "EimsDebitCreditNotes3550000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+      ADD COLUMN IF NOT EXISTS eims_document_type varchar(8) NOT NULL DEFAULT 'INV',
+      ADD COLUMN IF NOT EXISTS eims_reason text,
+      ADD COLUMN IF NOT EXISTS related_invoice_id uuid REFERENCES freight.invoices(id)
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+      DROP COLUMN IF EXISTS eims_document_type,
+      DROP COLUMN IF EXISTS eims_reason,
+      DROP COLUMN IF EXISTS related_invoice_id
+    `);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts
index 927e2efec..7406613fc 100644
--- a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts
@@ -212,6 +212,59 @@ describe("toEimsInvoice", () => {
     expect(() => toEimsInvoice(invoice({ issuedAt: null }), seller, context())).toThrow(/not issued/);
   });
 
+  describe("debit/credit notes — confirmed by MoR support, same /v1/register endpoint", () => {
+    it("defaults DocumentDetails.Type to INV with no Reason field", () => {
+      const doc = toEimsInvoice(invoice(), seller, context());
+      expect(doc.DocumentDetails.Type).toBe("INV");
+      expect(doc.DocumentDetails).not.toHaveProperty("Reason");
+    });
+
+    it("files a credit note with Type, Reason and RelatedDocument", () => {
+      const doc = toEimsInvoice(
+        invoice(),
+        seller,
+        context({
+          documentType: "CRE",
+          reason: "Overbilled freight charge",
+          relatedDocument: "9fe9bbbece6ab76c112b617534e6aac7aa8b819d5be79f4d3d088ed2e887b2e0",
+        }),
+      );
+      expect(doc.DocumentDetails).toMatchObject({ Type: "CRE", Reason: "Overbilled freight charge" });
+      expect(doc.ReferenceDetails.RelatedDocument).toBe(
+        "9fe9bbbece6ab76c112b617534e6aac7aa8b819d5be79f4d3d088ed2e887b2e0",
+      );
+    });
+
+    it("files a debit note the same way", () => {
+      const doc = toEimsInvoice(
+        invoice(),
+        seller,
+        context({ documentType: "DEB", reason: "Additional handling fee", relatedDocument: "IRN-1" }),
+      );
+      expect(doc.DocumentDetails).toMatchObject({ Type: "DEB", Reason: "Additional handling fee" });
+    });
+
+    it("throws when a credit/debit note has no reason", () => {
+      expect(() =>
+        toEimsInvoice(
+          invoice(),
+          seller,
+          context({ documentType: "CRE", reason: null, relatedDocument: "IRN-1" }),
+        ),
+      ).toThrow(/needs a reason/);
+    });
+
+    it("throws when a credit/debit note has no relatedDocument", () => {
+      expect(() =>
+        toEimsInvoice(
+          invoice(),
+          seller,
+          context({ documentType: "CRE", reason: "Overbilled", relatedDocument: null }),
+        ),
+      ).toThrow(/needs.*relatedDocument/);
+    });
+  });
+
   it("throws when the lines do not sum to the invoice total", () => {
     expect(() => toEimsInvoice(invoice({ totalAmount: "9000.00" }), seller, context())).toThrow(
       /lines sum to 11000 but the invoice total is 9000/,
diff --git a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
index fb7f2f145..582e3d326 100644
--- a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
+++ b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
@@ -20,8 +20,15 @@ import { round2 } from "./invoice-settlement.util";
 /** Only proven-required constant: the 400 SCHEMA ERROR sample rejects a payload without it. */
 const EIMS_VERSION = "1";
 
-/** The only `DocumentDetails.Type` observed in the supplied material. */
-const EIMS_DOCUMENT_TYPE = "INV";
+/**
+ * `DocumentDetails.Type`. `"INV"` is the only value observed in the collection; `"DEB"`/`"CRE"`
+ * (debit/credit note) were confirmed directly by MoR support — same `/v1/register` endpoint, no
+ * separate API. MoR's answer, verbatim: "the same endpoint used for registration should be used
+ * ... within the Document Detail object, you should specify DEB for a debit note, CRE for a
+ * credit note... add a Reason attribute under document detail object".
+ */
+export const EIMS_DOCUMENT_TYPES = ["INV", "DEB", "CRE"] as const;
+export type EimsDocumentType = (typeof EIMS_DOCUMENT_TYPES)[number];
 
 export interface EimsBuyerDetails {
   City: string | null;
@@ -60,7 +67,9 @@ export interface EimsDocumentDetails {
   DocumentNumber: string;
   /** Observed format `dd-MM-yyyyTHH:mm:ss`. Rule seen in the collection: within 3 days of now. */
   Date: string;
-  Type: string;
+  Type: EimsDocumentType;
+  /** Only for DEB/CRE, per MoR support — why the debit/credit note was issued. Absent for INV. */
+  Reason?: string;
 }
 
 export interface EimsInvoiceItem {
@@ -212,7 +221,18 @@ export interface EimsMapperContext {
   unitDefault: string;
   incomeWithholdValue: number;
   transactionWithholdValue: number;
-  /** Null for an ordinary invoice; set only for a real related-document case. */
+  /**
+   * `DocumentDetails.Type`. Defaults to `"INV"`. For `"DEB"`/`"CRE"` both `reason` and
+   * `relatedDocument` become required — confirmed directly by MoR support, not the collection.
+   */
+  documentType?: EimsDocumentType;
+  /** Required when `documentType` is `"DEB"`/`"CRE"` — why the note was issued. Unused for INV. */
+  reason?: string | null;
+  /**
+   * `ReferenceDetails.RelatedDocument`. Null for an ordinary invoice; required for a DEB/CRE —
+   * the original registered invoice's IRN, per MoR's own IRC-P06/P07 checklist ("credit memo
+   * from a registered invoice").
+   */
   relatedDocument?: string | null;
   /** MoR numeric country code for the buyer; our DB stores the country name. */
   buyerCountryCode?: string | null;
@@ -326,6 +346,26 @@ export function toEimsInvoice(
     );
   }
 
+  const documentType = context.documentType ?? "INV";
+  if (!EIMS_DOCUMENT_TYPES.includes(documentType)) {
+    throw new Error(
+      `EIMS mapping: invoice ${invoice.invoiceNumber} has documentType "${documentType}", must be one of ${EIMS_DOCUMENT_TYPES.join(", ")}`,
+    );
+  }
+  if (documentType !== "INV") {
+    if (!context.reason?.trim()) {
+      throw new Error(
+        `EIMS mapping: invoice ${invoice.invoiceNumber} is a ${documentType} (debit/credit note) and needs a reason`,
+      );
+    }
+    if (!context.relatedDocument?.trim()) {
+      throw new Error(
+        `EIMS mapping: invoice ${invoice.invoiceNumber} is a ${documentType} (debit/credit note) and needs ` +
+          "relatedDocument — the original registered invoice's IRN",
+      );
+    }
+  }
+
   const issuedAt = invoice.issuedAt instanceof Date ? invoice.issuedAt : new Date(invoice.issuedAt);
   if (Number.isNaN(issuedAt.getTime())) {
     throw new Error(`EIMS mapping: invoice ${invoice.invoiceNumber} has an unparseable issuedAt`);
@@ -430,7 +470,8 @@ export function toEimsInvoice(
     DocumentDetails: {
       DocumentNumber: context.documentNumber,
       Date: (context.formatDate ?? formatEimsDate)(issuedAt),
-      Type: EIMS_DOCUMENT_TYPE,
+      Type: documentType,
+      ...(documentType !== "INV" ? { Reason: context.reason! } : {}),
     },
     ItemList,
     PaymentDetails: { Mode: context.payment.mode, PaymentTerm: context.payment.term },
diff --git a/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts b/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
index 7d0ff34c4..43b6e3271 100644
--- a/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
+++ b/apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts
@@ -180,4 +180,27 @@ export class Invoice extends BaseEntity {
 
   @Column({ name: "eims_cancellation_remark", type: "text", nullable: true })
   eimsCancellationRemark?: string | null;
+
+  /**
+   * `DocumentDetails.Type` to file this invoice as — "INV" (default), "DEB" or "CRE". Confirmed
+   * by MoR support directly (not the collection): debit/credit notes go through this same
+   * `/v1/register` endpoint, distinguished only by `Type` + `Reason`, linked via
+   * `ReferenceDetails.RelatedDocument` to the original invoice's IRN. This module does not create
+   * debit/credit note invoices — that is a freight-workflow decision — it only files one
+   * correctly once these columns are set on an existing row.
+   */
+  @Column({ name: "eims_document_type", type: "varchar", length: 8, default: "INV" })
+  eimsDocumentType!: string;
+
+  /** Required by MoR when `eimsDocumentType` is DEB/CRE — why the note was issued. */
+  @Column({ name: "eims_reason", type: "text", nullable: true })
+  eimsReason?: string | null;
+
+  /** The original registered invoice this debit/credit note adjusts. Required for DEB/CRE. */
+  @Column({ name: "related_invoice_id", type: "uuid", nullable: true })
+  relatedInvoiceId?: string | null;
+
+  @ManyToOne(() => Invoice)
+  @JoinColumn({ name: "related_invoice_id" })
+  relatedInvoice?: Invoice | null;
 }
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts
index 8e7be0197..b77804eda 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts
@@ -157,6 +157,12 @@ export interface EimsContextInput {
   session: EimsSessionContext;
   /** Required when the invoice currency is not ETB. */
   exchangeRate?: number | null;
+  /** `DocumentDetails.Type` — defaults to "INV" in the mapper when omitted. */
+  documentType?: EimsMapperContext["documentType"];
+  /** Required (by the mapper) when documentType is DEB/CRE. */
+  reason?: string | null;
+  /** `ReferenceDetails.RelatedDocument` — the original invoice's IRN, required for DEB/CRE. */
+  relatedDocument?: string | null;
 }
 
 export function buildEimsContext(config: EimsConfig, input: EimsContextInput): EimsMapperContext {
@@ -206,5 +212,8 @@ export function buildEimsContext(config: EimsConfig, input: EimsContextInput): E
     buyerIdType: invoice.buyerIdType,
     buyerIdNumber: invoice.buyerIdNumber,
     exchangeRate: input.exchangeRate ?? null,
+    documentType: input.documentType,
+    reason: input.reason ?? null,
+    relatedDocument: input.relatedDocument ?? null,
   };
 }
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
index 8c2a33cfc..36c355bed 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
@@ -295,6 +295,58 @@ describe("EimsInvoiceRegistrationService.registerInvoiceWithEims", () => {
     expect(request.SourceSystem.SystemNumber).toBe(SYSTEM_NUMBER);
   });
 
+  it("files a credit note with Type/Reason/RelatedDocument from the invoice row", async () => {
+    const original = invoiceRow({
+      id: "original-invoice",
+      invoiceNumber: "INV-20260807-00001",
+      eimsIrn: IRN,
+    });
+    const db = new FakeDb([
+      invoiceRow({
+        eimsDocumentType: "CRE",
+        eimsReason: "Overbilled freight charge",
+        relatedInvoice: original,
+      } as Partial<Invoice>),
+    ]);
+    const postSigned = jest.fn().mockResolvedValue(okResponse());
+
+    await build(db, postSigned).registerInvoiceWithEims(INVOICE_ID);
+
+    const request = postSigned.mock.calls[0][1] as EimsInvoiceRequest;
+    expect(request.DocumentDetails).toMatchObject({ Type: "CRE", Reason: "Overbilled freight charge" });
+    expect(request.ReferenceDetails.RelatedDocument).toBe(IRN);
+  });
+
+  it("refuses a credit/debit note whose related invoice was never registered, before touching a counter", async () => {
+    const original = invoiceRow({ id: "original-invoice", eimsIrn: null });
+    const db = new FakeDb([
+      invoiceRow({
+        eimsDocumentType: "DEB",
+        eimsReason: "Additional handling",
+        relatedInvoice: original,
+      } as Partial<Invoice>),
+    ]);
+    const postSigned = jest.fn();
+
+    await expect(build(db, postSigned).registerInvoiceWithEims(INVOICE_ID)).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+    expect(postSigned).not.toHaveBeenCalled();
+    expect(db.state).toMatchObject({ nextInvoiceCounter: 7 }); // unchanged — never reserved
+  });
+
+  it("refuses a credit/debit note with no related invoice set at all", async () => {
+    const db = new FakeDb([
+      invoiceRow({ eimsDocumentType: "CRE", eimsReason: "x", relatedInvoice: null } as Partial<Invoice>),
+    ]);
+    const postSigned = jest.fn();
+
+    await expect(build(db, postSigned).registerInvoiceWithEims(INVOICE_ID)).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+    expect(postSigned).not.toHaveBeenCalled();
+  });
+
   it("takes SourceSystem from the token session, not from configuration", async () => {
     const db = new FakeDb([invoiceRow()]);
     const postSigned = jest.fn().mockResolvedValue(okResponse());
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
index 317f4ec65..ab9f953c5 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
@@ -13,6 +13,7 @@ import type { QueryDeepPartialEntity } from "typeorm/query-builder/QueryPartialE
 import { EimsConfig } from "../../config/eims.config";
 import { Invoice } from "../billing/entities/invoice.entity";
 import {
+  EimsDocumentType,
   EimsInvoiceRequest,
   EimsMapperLine,
   toEimsInvoice,
@@ -96,6 +97,27 @@ export class EimsInvoiceRegistrationService {
     const invoice = await this.loadInvoiceForMapping(invoiceId);
     if (invoice.eimsIrn) return this.toView(invoice);
 
+    // Debit/credit notes (confirmed by MoR support: same endpoint, Type DEB/CRE + Reason,
+    // ReferenceDetails.RelatedDocument = the original's IRN) must fail here — before a counter is
+    // touched — if the original was never actually registered.
+    const documentType = (invoice.eimsDocumentType as EimsDocumentType | undefined) ?? "INV";
+    let relatedDocument: string | null = null;
+    if (documentType !== "INV") {
+      if (!invoice.relatedInvoice) {
+        throw new BadRequestException({
+          code: "EIMS_RELATED_INVOICE_REQUIRED",
+          message: `Invoice ${invoice.invoiceNumber} is a ${documentType} but has no related invoice set.`,
+        });
+      }
+      if (!invoice.relatedInvoice.eimsIrn) {
+        throw new BadRequestException({
+          code: "EIMS_RELATED_INVOICE_NOT_REGISTERED",
+          message: `Invoice ${invoice.invoiceNumber} is a ${documentType} against invoice ${invoice.relatedInvoice.invoiceNumber}, which was never registered with EIMS — nothing to reference.`,
+        });
+      }
+      relatedDocument = invoice.relatedInvoice.eimsIrn;
+    }
+
     // Authenticate before reserving: the source system comes from the token, and the state row is
     // keyed by it. A login failure here costs nothing — no counter has been consumed yet.
     const session = await this.auth.getSessionContext();
@@ -114,6 +136,9 @@ export class EimsInvoiceRegistrationService {
         invoiceCounter: reservation.invoiceCounter,
         previousIrn: reservation.previousIrn,
         session,
+        documentType,
+        reason: invoice.eimsReason,
+        relatedDocument,
       }),
     );
 
@@ -639,7 +664,7 @@ export class EimsInvoiceRegistrationService {
   ): Promise<Invoice & { lines: EimsMapperLine[] }> {
     const invoice = await this.dataSource.getRepository(Invoice).findOne({
       where: { id: invoiceId },
-      relations: { company: true, companyProfile: true },
+      relations: { company: true, companyProfile: true, relatedInvoice: true },
     });
     if (!invoice) throw new NotFoundException(`Invoice ${invoiceId} not found`);
 

From 87c51d76763f108ab4ffc2c086ae51594ae4f39b Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Sat, 15 Aug 2026 06:44:34 +0000
Subject: [PATCH 107/174] fix(eims): drain pre-reservation rejections in
 auto-submit sweep
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A BadRequestException thrown before reserve() (config assertion, DEB/CRE
validation) left the invoice NOT_SUBMITTED with nothing persisted, so the
same row was retried every tick forever — a permanent head-of-line block on
every invoice behind it. Now marked FAILED, guarded by a fresh status
re-read so a reservation's own SUBMITTING/UNKNOWN/blocked state is never
clobbered.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../eims/eims-auto-submit.service.spec.ts     | 48 ++++++++++++++-
 .../modules/eims/eims-auto-submit.service.ts  | 61 ++++++++++++++++---
 2 files changed, 98 insertions(+), 11 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/eims/eims-auto-submit.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-auto-submit.service.spec.ts
index 6246d5a89..9b3bb5183 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-auto-submit.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-auto-submit.service.spec.ts
@@ -1,3 +1,4 @@
+import { BadRequestException } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { DataSource } from "typeorm";
 
@@ -12,6 +13,9 @@ const INVOICE_ID = "11111111-1111-4111-8111-111111111111";
 /**
  * `query` is answered by shape: the first call is the system-state guard, the second is the
  * candidate lookup. Keeps the fake honest about the order the service actually asks in.
+ *
+ * `managerRow` backs `dataSource.manager.findOne`/`.update` — only exercised by the
+ * pre-reservation-rejection path (`failStalledCandidate`), so it defaults to the candidate itself.
  */
 const build = (
   opts: {
@@ -19,6 +23,7 @@ const build = (
     state?: { in_flight_invoice_id?: string | null; blocked_reason?: string | null };
     candidate?: { id: string; invoiceNumber: string } | null;
     register?: jest.Mock;
+    managerRow?: { eimsStatus: EimsInvoiceStatus } | null;
   } = {},
 ) => {
   const register =
@@ -34,12 +39,17 @@ const build = (
     return Promise.resolve(opts.candidate === undefined ? [] : opts.candidate ? [opts.candidate] : []);
   });
 
+  const managerUpdate = jest.fn().mockResolvedValue(undefined);
+  const managerFindOne = jest
+    .fn()
+    .mockResolvedValue(opts.managerRow === undefined ? { eimsStatus: EimsInvoiceStatus.NotSubmitted } : opts.managerRow);
+
   const service = new EimsAutoSubmitService(
-    { query } as unknown as DataSource,
+    { query, manager: { findOne: managerFindOne, update: managerUpdate } } as unknown as DataSource,
     { get: () => eimsConfig({ autoSubmit: true, ...opts.cfg }) } as unknown as ConfigService,
     { registerInvoiceWithEims: register } as unknown as EimsInvoiceRegistrationService,
   );
-  return { service, register, query };
+  return { service, register, query, managerUpdate, managerFindOne };
 };
 
 const candidate = { id: INVOICE_ID, invoiceNumber: "INV-20260807-00006" };
@@ -121,6 +131,40 @@ describe("EimsAutoSubmitService.tick", () => {
     expect(register).toHaveBeenCalledTimes(1);
   });
 
+  it("drains a pre-reservation rejection so the sweep advances, without touching the DB row's own reservation state", async () => {
+    const register = jest
+      .fn()
+      .mockRejectedValue(new BadRequestException({ code: "EIMS_RELATED_INVOICE_REQUIRED", message: "no related invoice" }));
+    const { service, managerFindOne, managerUpdate } = build({ candidate, register });
+
+    await expect(service.tick()).resolves.toBeUndefined();
+
+    expect(managerFindOne).toHaveBeenCalledTimes(1);
+    expect(managerUpdate).toHaveBeenCalledWith(
+      expect.anything(),
+      INVOICE_ID,
+      expect.objectContaining({
+        eimsStatus: EimsInvoiceStatus.Failed,
+        eimsLastError: expect.objectContaining({ message: "no related invoice" }),
+      }),
+    );
+  });
+
+  it("leaves a row alone if it already moved past NOT_SUBMITTED by the time the rejection is handled", async () => {
+    const register = jest
+      .fn()
+      .mockRejectedValue(new BadRequestException({ code: "EIMS_RELATED_INVOICE_REQUIRED", message: "no related invoice" }));
+    const { service, managerUpdate } = build({
+      candidate,
+      register,
+      managerRow: { eimsStatus: EimsInvoiceStatus.Submitting },
+    });
+
+    await expect(service.tick()).resolves.toBeUndefined();
+
+    expect(managerUpdate).not.toHaveBeenCalled();
+  });
+
   it("does not start a second tick while one is still filing", async () => {
     let release: () => void = () => {};
     const register = jest.fn().mockImplementation(
diff --git a/apps/edr-freight-api/src/modules/eims/eims-auto-submit.service.ts b/apps/edr-freight-api/src/modules/eims/eims-auto-submit.service.ts
index fb5a0d1f6..bad283817 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-auto-submit.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-auto-submit.service.ts
@@ -1,12 +1,14 @@
-import { Injectable, Logger } from "@nestjs/common";
+import { BadRequestException, Injectable, Logger } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { Cron } from "@nestjs/schedule";
 import { InjectDataSource } from "@nestjs/typeorm";
 import { DataSource } from "typeorm";
+import type { QueryDeepPartialEntity } from "typeorm/query-builder/QueryPartialEntity.js";
 
 import { EimsConfig } from "../../config/eims.config";
+import { Invoice } from "../billing/entities/invoice.entity";
 import { EimsInvoiceRegistrationService } from "./eims-invoice-registration.service";
-import { EimsInvoiceStatus } from "./eims-registration.types";
+import { EimsInvoiceError, EimsInvoiceStatus } from "./eims-registration.types";
 
 /**
  * Files issued invoices with MoR EIMS on a timer.
@@ -67,21 +69,62 @@ export class EimsAutoSubmitService {
       const candidate = await this.nextCandidate();
       if (!candidate) return;
 
-      const view = await this.registration.registerInvoiceWithEims(candidate.id);
-      this.logger.log(
-        `EIMS auto-submit: invoice ${candidate.invoiceNumber} -> ${view.eimsStatus}` +
-          (view.eimsIrn ? ` (IRN ${view.eimsIrn})` : ""),
-      );
+      try {
+        const view = await this.registration.registerInvoiceWithEims(candidate.id);
+        this.logger.log(
+          `EIMS auto-submit: invoice ${candidate.invoiceNumber} -> ${view.eimsStatus}` +
+            (view.eimsIrn ? ` (IRN ${view.eimsIrn})` : ""),
+        );
+      } catch (err) {
+        // Every other failure path inside registerInvoiceWithEims persists FAILED/UNKNOWN itself
+        // (settleFailure) before throwing. A BadRequestException is the one exception: it is only
+        // ever thrown *before* a reservation is taken (config assertion, DEB/CRE validation), so
+        // nothing is persisted — left alone, this candidate is picked again next tick forever, a
+        // permanent head-of-line block on every invoice behind it. Drain it instead.
+        if (err instanceof BadRequestException) {
+          await this.failStalledCandidate(candidate, err);
+        } else {
+          throw err;
+        }
+      }
     } catch (err) {
       // Never let a filing failure kill the job. The outcome is already persisted on the invoice
-      // (FAILED or UNKNOWN with the gateway's own message), and a blocked system number stops the
-      // next tick at the guard above.
+      // (FAILED or UNKNOWN with the gateway's own message, or drained by failStalledCandidate
+      // above), and a blocked system number stops the next tick at the guard above.
       this.logger.error(`EIMS auto-submit tick failed: ${(err as Error).message}`);
     } finally {
       this.running = false;
     }
   }
 
+  /**
+   * Mark a pre-reservation rejection as FAILED so the sweep advances past it — but only if the
+   * invoice is still exactly where this tick left it. A reservation's own transactions
+   * (SUBMITTING/UNKNOWN, or a system-wide block) are authoritative; this must never clobber them,
+   * so the status is re-read fresh rather than trusted from the stale `candidate` row.
+   */
+  private async failStalledCandidate(
+    candidate: { id: string; invoiceNumber: string },
+    err: BadRequestException,
+  ): Promise<void> {
+    const current = await this.dataSource.manager.findOne(Invoice, { where: { id: candidate.id } });
+    if (current?.eimsStatus !== EimsInvoiceStatus.NotSubmitted) {
+      this.logger.warn(
+        `EIMS auto-submit: invoice ${candidate.invoiceNumber} rejected before reservation, but is ` +
+          `no longer NOT_SUBMITTED (${current?.eimsStatus ?? "not found"}) — leaving state untouched.`,
+      );
+      return;
+    }
+    const lastError: EimsInvoiceError = { kind: "VALIDATION", message: err.message, at: new Date().toISOString() };
+    await this.dataSource.manager.update(Invoice, candidate.id, {
+      eimsStatus: EimsInvoiceStatus.Failed,
+      eimsLastError: lastError,
+    } as QueryDeepPartialEntity<Invoice>);
+    this.logger.error(
+      `EIMS auto-submit: invoice ${candidate.invoiceNumber} rejected before reservation: ${err.message}`,
+    );
+  }
+
   /** Why filing is currently impossible for this system number, or null when it is free. */
   private async systemBlockReason(): Promise<string | null> {
     const rows: { in_flight_invoice_id: string | null; blocked_reason: string | null }[] =

From d66cfe23286f4cc83054bd94f4cc7d6cbbeb5ed4 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Sat, 15 Aug 2026 06:44:41 +0000
Subject: [PATCH 108/174] feat(billing): issue credit/debit memos against
 registered invoices
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

POST billing/invoices/:id/memo files a MoR DEB/CRE memo by reusing
createInvoice unchanged. sourceId is the original invoice's own id, not its
source's — this structurally keeps memos out of findPayable/expirePayable/
billQuery's sourceId-keyed lookups regardless of status. Credit notes are
created settled; debit notes are created open/unpaid as a genuine new
receivable, not force-settled. memoIssue is granted to the chief position,
not the general finance role.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../src/modules/billing/billing.controller.ts |  12 ++
 .../modules/billing/billing.service.spec.ts   | 153 ++++++++++++++++++
 .../src/modules/billing/billing.service.ts    | 152 +++++++++++++++--
 .../src/modules/billing/dto/issue-memo.dto.ts |  71 ++++++++
 .../src/seed/freight-permissions.registry.ts  |  25 ++-
 5 files changed, 396 insertions(+), 17 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/billing/dto/issue-memo.dto.ts

diff --git a/apps/edr-freight-api/src/modules/billing/billing.controller.ts b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
index 5bf1448fd..e65f301b2 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.controller.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
@@ -29,6 +29,7 @@ import { actorLabel } from "../warehouses/current-actor.util";
 import { UserTradeAccessService } from "../user-trade-access/user-trade-access.service";
 import { BillingService } from "./billing.service";
 import { FilterInvoiceDto } from "./dto/filter-invoice.dto";
+import { IssueMemoDto } from "./dto/issue-memo.dto";
 
 @ApiTags("billing")
 @Controller("billing")
@@ -38,6 +39,7 @@ import { FilterInvoiceDto } from "./dto/filter-invoice.dto";
   FREIGHT_PERMS.invoices.view,
   FREIGHT_PERMS.invoices.export,
   FREIGHT_PERMS.invoices.confirmOffline,
+  FREIGHT_PERMS.invoices.memoIssue,
 ])
 @ApiBearerAuth()
 export class BillingController {
@@ -99,6 +101,16 @@ export class BillingController {
     });
   }
 
+  @Post("invoices/:id/memo")
+  @BookingStaff(FREIGHT_PERMS.invoices.memoIssue)
+  @ApiOperation({
+    summary:
+      "Issue a credit or debit memo against a registered invoice (MoR DEB/CRE). Filing-equivalent — the auto-submit sweep picks it up like any other issued invoice.",
+  })
+  issueMemo(@Param("id", ParseUUIDPipe) id: string, @Body() dto: IssueMemoDto) {
+    return this.billingService.issueMemo(id, dto);
+  }
+
   @Get("invoices/:id/document")
   @BookingStaff(FREIGHT_PERMS.invoices.export)
   @ApiOperation({ summary: "Download the sealed invoice PDF" })
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index d9eef5a43..7148fa987 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -119,6 +119,159 @@ describe("BillingService.generateInvoice", () => {
   });
 });
 
+describe("BillingService.issueMemo", () => {
+  const ORIGINAL_ID = "original-invoice-1";
+
+  function originalInvoice(overrides: Record<string, unknown> = {}) {
+    return {
+      id: ORIGINAL_ID,
+      invoiceNumber: "INV-20260807-00042",
+      eimsIrn: "irn-value",
+      eimsDocumentType: "INV",
+      eimsStatus: "REGISTERED",
+      source: Freight.InvoiceSource.Booking,
+      sourceId: "booking-1",
+      companyId: "company-1",
+      companyProfileId: "profile-1",
+      shippingLineCompanyId: null,
+      currency: "ETB",
+      totalAmount: 1500,
+      lines: [
+        { chargeType: "RAIL_FREIGHT", description: "Rail freight", quantity: 2, unitRate: 500, amount: 1000, currency: "ETB", metadata: null },
+        { chargeType: "HAZARD_SURCHARGE", description: "Hazard surcharge", quantity: 2, unitRate: 250, amount: 500, currency: "ETB", metadata: null },
+      ],
+      ...overrides,
+    };
+  }
+
+  function build(original: ReturnType<typeof originalInvoice>) {
+    const savedLines: unknown[] = [];
+    const manager = makeManager(savedLines);
+    const dataSource = {
+      transaction: jest.fn().mockImplementation((cb: (mg: unknown) => unknown) => cb(manager)),
+      manager,
+    };
+    const invoices = { findById: jest.fn().mockResolvedValue(original) };
+    const invoiceLines = { findAll: jest.fn().mockResolvedValue(original.lines) };
+    const service = new BillingService(
+      dataSource as never,
+      invoices as never,
+      invoiceLines as never,
+      makeEvents() as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      { get: () => undefined } as never,
+    );
+    return { service, manager, savedLines };
+  }
+
+  it("creates a settled credit memo copying the original's lines, linked via relatedInvoiceId", async () => {
+    const { service, savedLines } = build(originalInvoice());
+
+    const memo = await service.issueMemo(ORIGINAL_ID, { type: "CRE", reason: "Overbilled freight charge" });
+
+    expect(memo.invoiceNumber).toMatch(/^CRE-\d{8}-00001$/);
+    expect(memo.totalAmount).toBe(1500);
+    expect(memo.status).toBe(Freight.InvoiceStatus.Paid);
+    expect((memo as unknown as Record<string, unknown>).eimsDocumentType).toBe("CRE");
+    expect((memo as unknown as Record<string, unknown>).eimsReason).toBe("Overbilled freight charge");
+    expect((memo as unknown as Record<string, unknown>).relatedInvoiceId).toBe(ORIGINAL_ID);
+    expect((memo as unknown as Record<string, unknown>).paidAmount).toBe(1500);
+    expect((memo as unknown as Record<string, unknown>).balanceAmount).toBe(0);
+    expect(savedLines).toHaveLength(2);
+  });
+
+  it("creates an open, unpaid debit memo — a genuine new receivable, not force-settled", async () => {
+    const { service } = build(originalInvoice());
+
+    const memo = await service.issueMemo(ORIGINAL_ID, { type: "DEB", reason: "Additional handling fee" });
+
+    expect(memo.invoiceNumber).toMatch(/^DEB-\d{8}-00001$/);
+    expect(memo.status).toBe(Freight.InvoiceStatus.Pending);
+    expect(memo.balanceAmount).toBe(1500);
+    expect(memo.paidAmount).toBe(0);
+  });
+
+  it("keys the memo's sourceId to the original invoice's own id, not the original's sourceId", async () => {
+    const { service } = build(originalInvoice());
+
+    const memo = await service.issueMemo(ORIGINAL_ID, { type: "CRE", reason: "test" });
+
+    expect(memo.sourceId).toBe(ORIGINAL_ID);
+    expect(memo.sourceId).not.toBe("booking-1");
+  });
+
+  it("allows a partial memo with explicit lines instead of copying the original", async () => {
+    const { service } = build(originalInvoice());
+
+    const memo = await service.issueMemo(ORIGINAL_ID, {
+      type: "CRE",
+      reason: "Partial credit",
+      lines: [{ chargeType: "RAIL_FREIGHT", quantity: 1, unitRate: 200, amount: 200 }],
+    });
+
+    expect(memo.totalAmount).toBe(200);
+  });
+
+  it("refuses a memo against an invoice never registered with EIMS", async () => {
+    const { service } = build(originalInvoice({ eimsIrn: null }));
+
+    await expect(service.issueMemo(ORIGINAL_ID, { type: "CRE", reason: "x" })).rejects.toMatchObject({
+      response: expect.objectContaining({ code: "EIMS_RELATED_INVOICE_NOT_REGISTERED" }),
+    });
+  });
+
+  it("refuses a memo against a memo", async () => {
+    const { service } = build(originalInvoice({ eimsDocumentType: "CRE" }));
+
+    await expect(service.issueMemo(ORIGINAL_ID, { type: "DEB", reason: "x" })).rejects.toThrow(
+      "cannot issue a memo against a memo",
+    );
+  });
+
+  it("refuses a memo against an EIMS-cancelled invoice", async () => {
+    const { service } = build(originalInvoice({ eimsStatus: "CANCELLED" }));
+
+    await expect(service.issueMemo(ORIGINAL_ID, { type: "CRE", reason: "x" })).rejects.toThrow(
+      "cancelled with EIMS",
+    );
+  });
+
+  it("refuses a credit memo whose total exceeds the original", async () => {
+    const { service } = build(originalInvoice({ totalAmount: 1500 }));
+
+    await expect(
+      service.issueMemo(ORIGINAL_ID, {
+        type: "CRE",
+        reason: "too much",
+        lines: [{ chargeType: "RAIL_FREIGHT", quantity: 1, unitRate: 2000, amount: 2000 }],
+      }),
+    ).rejects.toThrow(/exceeds/);
+  });
+
+  it("does NOT bound a debit memo by the original's total — it is a new charge, not a refund", async () => {
+    const { service } = build(originalInvoice({ totalAmount: 1500 }));
+
+    const memo = await service.issueMemo(ORIGINAL_ID, {
+      type: "DEB",
+      reason: "additional charge",
+      lines: [{ chargeType: "RAIL_FREIGHT", quantity: 1, unitRate: 5000, amount: 5000 }],
+    });
+
+    expect(memo.totalAmount).toBe(5000);
+  });
+
+  it("refuses a blank reason", async () => {
+    const { service } = build(originalInvoice());
+
+    await expect(service.issueMemo(ORIGINAL_ID, { type: "CRE", reason: "   " })).rejects.toThrow(
+      "requires a reason",
+    );
+  });
+});
+
 describe("BillingService.markInvoiceAsPaid", () => {
   it("marks the invoice PAID, stamps amounts/paidAt, links the payment, and emits ${source}.invoice.paid", async () => {
     const open = {
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 5afa30128..a0f25f88b 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -18,6 +18,7 @@ import { Booking } from "../bookings/entities/booking.entity";
 import { ShippingLineCompany } from "../shipping-lines/entities/shipping-line-company.entity";
 import { EimsConfig } from "../../config/eims.config";
 import { CompaniesService } from "../companies/companies.service";
+import { EimsInvoiceStatus } from "../eims/eims-registration.types";
 import { FilesService } from "../files/files.service";
 import { applyBookingRefDirectionScope } from "../user-trade-access/trade-scope.util";
 import { PaymentService } from "../payment/payment.service";
@@ -25,6 +26,7 @@ import { InitiateResponseDto, IntentStatusDto } from "../payment/payments.dto";
 import {
   InvoiceDocumentModel,
   InvoiceDocumentService,
+  pngDataUrl,
 } from "./documents/invoice-document.service";
 import { InvoiceLine } from "./entities/invoice-line.entity";
 import { Invoice, InvoicePayment } from "./entities/invoice.entity";
@@ -145,6 +147,18 @@ export interface GenerateInvoiceInput {
   status?: Freight.InvoiceStatus;
 }
 
+/** MoR `DocumentDetails.Type` for a memo — see `EIMS_DOCUMENT_TYPES` in `eims-invoice.mapper.ts`. */
+export type MemoType = "CRE" | "DEB";
+
+/** Everything needed to issue a credit or debit memo against an already-registered invoice. */
+export interface IssueMemoInput {
+  type: MemoType;
+  /** Why the memo was issued — required by MoR as `DocumentDetails.Reason`. */
+  reason: string;
+  /** Omit to copy every line of the original verbatim (a full reversal/charge, the common case). */
+  lines?: InvoiceLineInput[];
+}
+
 /** Payload broadcast on `${source}.invoice.<event>`. */
 export interface InvoiceEventPayload {
   invoiceId: string;
@@ -418,15 +432,6 @@ export class BillingService {
     );
   }
 
-  /**
-   * `Invoice.eimsSignedQr` is already a base64 PNG straight from MoR — confirmed against the
-   * Postman collection's `register` response (`signedQR` decodes to a PNG magic-byte header),
-   * not a payload we encode ourselves. Wrapped in a data URL, nothing more.
-   */
-  private renderEimsQr(signedQr: string): string {
-    return `data:image/png;base64,${signedQr}`;
-  }
-
   /** Route + wagon count summary rows for a booking-sourced invoice; empty for every other source. */
   private async bookingSummaryRows(
     invoice: Invoice,
@@ -542,7 +547,7 @@ export class BillingService {
         currency: l.currency,
       })),
       totals,
-      qrImageUrl: invoice.eimsSignedQr ? this.renderEimsQr(invoice.eimsSignedQr) : null,
+      qrImageUrl: invoice.eimsSignedQr ? pngDataUrl(invoice.eimsSignedQr) : null,
     };
   }
 
@@ -709,11 +714,16 @@ export class BillingService {
 
   // ── Generation ───────────────────────────────────────────────────────────────
 
-  /** `<CODE>-YYYYMMDD-00001` — sequential per day & prefix, within the active transaction. */
-  private nextInvoiceNumber(mg: EntityManager): Promise<string> {
+  /**
+   * `<CODE>-YYYYMMDD-00001` — sequential per day & prefix, within the active transaction. `code`
+   * defaults to `INV`; a memo (`issueMemo`) uses `CRE`/`DEB` instead, which is its own independent
+   * daily sequence (different prefix hashes to a different advisory lock, see
+   * `nextDailyInvoiceNumber`) — not a collision risk with ordinary invoice numbers.
+   */
+  private nextInvoiceNumber(mg: EntityManager, code = "INV"): Promise<string> {
     return nextDailyInvoiceNumber(mg, {
       table: "freight.invoices",
-      code: "INV",
+      code,
     });
   }
 
@@ -736,9 +746,123 @@ export class BillingService {
     return manager ? run(manager) : this.dataSource.transaction(run);
   }
 
+  /**
+   * Issue a credit or debit memo against an already-registered invoice, per MoR's confirmed
+   * DEB/CRE filing mechanism (same `/v1/register` endpoint, `DocumentDetails.Type` + `Reason`,
+   * `ReferenceDetails.RelatedDocument` — see `eims-invoice.mapper.ts`). Reuses `createInvoice`
+   * unchanged: it has no side effects (no events, no notifications, no payment records — every
+   * event in this service fires from `runTransition` on a *transition*, not on create), so a memo
+   * is just an ordinary invoice with three extra columns set.
+   *
+   * `sourceId` is deliberately the *original invoice's own id*, not the original's `sourceId`
+   * (e.g. a booking id): `findPayable`, `expirePayable` and `billQuery` all resolve by
+   * `sourceId` with no `type` filter, so a memo sharing the booking's `sourceId` would be the
+   * newest matching row and could hijack a payer's balance at a CBE teller. An invoice's own
+   * `id` is never a value those lookups are ever queried with, so this isolates a memo from all
+   * of them regardless of its status — no `type`-based exclusion needed anywhere else.
+   *
+   * A credit note is created settled (PAID, balance 0) — nothing is ever collected against it, so
+   * leaving it payable would only add a phantom receivable that no payment flow will ever close.
+   * A debit note genuinely IS a new receivable and is created open/unpaid like any ordinary
+   * invoice (`createInvoice`'s own defaults: PENDING, `balanceAmount = totalAmount`) — it is
+   * findable and collectible through the normal invoice list/detail/payment tooling, safe from
+   * the CBE/booking-linked lookups above for the `sourceId` reason just given.
+   */
+  async issueMemo(
+    originalId: string,
+    input: IssueMemoInput,
+  ): Promise<Invoice & { lines: InvoiceLine[] }> {
+    const reason = input.reason?.trim();
+    if (!reason) {
+      throw new BadRequestException("A memo requires a reason.");
+    }
+
+    const original = await this.findById(originalId);
+    if (!original.eimsIrn) {
+      throw new BadRequestException({
+        code: "EIMS_RELATED_INVOICE_NOT_REGISTERED",
+        message: `Invoice ${original.invoiceNumber} was never registered with EIMS — nothing to reference.`,
+      });
+    }
+    if (original.eimsDocumentType && original.eimsDocumentType !== "INV") {
+      throw new BadRequestException(
+        `Invoice ${original.invoiceNumber} is itself a ${original.eimsDocumentType} — cannot issue a memo against a memo.`,
+      );
+    }
+    if (original.eimsStatus === EimsInvoiceStatus.Cancelled) {
+      throw new BadRequestException(
+        `Invoice ${original.invoiceNumber} was cancelled with EIMS — nothing to adjust.`,
+      );
+    }
+
+    const sourceLines = input.lines?.length ? input.lines : original.lines;
+    const lines: InvoiceLineInput[] = sourceLines.map((l) => ({
+      chargeType: l.chargeType,
+      description: l.description,
+      quantity: Number(l.quantity),
+      unitRate: Number(l.unitRate),
+      amount: Number(l.amount),
+      currency: l.currency,
+      metadata: l.metadata ?? null,
+    }));
+
+    const total = round2(lines.reduce((sum, l) => sum + Number(l.amount ?? 0), 0));
+    if (!(total > 0)) {
+      throw new BadRequestException("A memo must have a positive total.");
+    }
+    // Only a credit note is bounded by the original — it can only give back what was charged. A
+    // debit note is an additional charge, not a refund, so no such ceiling applies to it (do not
+    // assume the credit-note ceiling is correct for DEB).
+    if (input.type === "CRE" && total > Number(original.totalAmount)) {
+      throw new BadRequestException(
+        `Credit memo total (${total}) exceeds invoice ${original.invoiceNumber}'s total (${original.totalAmount}).`,
+      );
+    }
+
+    const code = input.type === "CRE" ? "CRE" : "DEB";
+    const settled = input.type === "CRE";
+
+    return this.dataSource.transaction(async (mg) => {
+      const memo = await this.createInvoice(
+        {
+          source: original.source as Freight.InvoiceSource,
+          sourceId: original.id,
+          type: input.type === "CRE" ? "credit_note" : "debit_note",
+          companyId: original.companyId,
+          companyProfileId: original.companyProfileId,
+          shippingLineCompanyId: original.shippingLineCompanyId,
+          lines,
+          currency: original.currency,
+          subtotalAmount: total,
+          taxAmount: 0,
+          totalAmount: total,
+          ...(settled ? { status: Freight.InvoiceStatus.Paid, dueAt: new Date() } : {}),
+        },
+        mg,
+        code,
+      );
+
+      const patch: Record<string, unknown> = {
+        eimsDocumentType: input.type,
+        eimsReason: reason,
+        relatedInvoiceId: original.id,
+        ...(settled
+          ? { paidAmount: memo.totalAmount, balanceAmount: 0, paidAt: new Date() }
+          : {}),
+      };
+      await mg.update(Invoice, memo.id, patch);
+
+      this.logger.log(
+        `Issued ${input.type} memo ${memo.invoiceNumber} (${memo.id}) against invoice ${original.invoiceNumber}`,
+      );
+      return { ...memo, ...patch } as Invoice & { lines: InvoiceLine[] };
+    });
+  }
+
   private async createInvoice(
     input: GenerateInvoiceInput,
     mg: EntityManager,
+    code = "INV",
   ): Promise<Invoice & { lines: InvoiceLine[] }> {
     const currency = input.currency ?? "ETB";
     const status = input.status ?? Freight.InvoiceStatus.Pending;
@@ -786,7 +910,7 @@ export class BillingService {
         (input.dueInDays ?? DEFAULT_DUE_DAYS) * 24 * 60 * 60 * 1000,
       );
 
-    const invoiceNumber = await this.nextInvoiceNumber(mg);
+    const invoiceNumber = await this.nextInvoiceNumber(mg, code);
 
     const invoice = await mg.save(
       mg.create(Invoice, {
diff --git a/apps/edr-freight-api/src/modules/billing/dto/issue-memo.dto.ts b/apps/edr-freight-api/src/modules/billing/dto/issue-memo.dto.ts
new file mode 100644
index 000000000..c80657155
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/dto/issue-memo.dto.ts
@@ -0,0 +1,71 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { Type } from "class-transformer";
+import {
+  IsArray,
+  IsIn,
+  IsNumber,
+  IsObject,
+  IsOptional,
+  IsString,
+  Length,
+  ValidateNested,
+} from "class-validator";
+
+/** One line on a memo; omit the whole `lines` array on the parent DTO to copy the original's. */
+export class MemoLineDto {
+  @ApiProperty()
+  @IsString()
+  chargeType!: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  description?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsNumber()
+  quantity?: number;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsNumber()
+  unitRate?: number;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsNumber()
+  amount?: number;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  currency?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsObject()
+  metadata?: Record<string, unknown>;
+}
+
+/** `POST billing/invoices/:id/memo` body — see `BillingService.issueMemo`. */
+export class IssueMemoDto {
+  @ApiProperty({ enum: ["CRE", "DEB"], description: "MoR DocumentDetails.Type for the memo." })
+  @IsIn(["CRE", "DEB"])
+  type!: "CRE" | "DEB";
+
+  @ApiProperty({ description: "Why the memo was issued — MoR DocumentDetails.Reason." })
+  @IsString()
+  @Length(1, 500)
+  reason!: string;
+
+  @ApiPropertyOptional({
+    type: [MemoLineDto],
+    description: "Omit to copy every line of the original invoice verbatim.",
+  })
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => MemoLineDto)
+  lines?: MemoLineDto[];
+}
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index adbd22584..9e905df6d 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -569,6 +569,14 @@ export const FINANCE_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:invoices:eims_receipt_register",
     "Register a sales or withholding receipt with MoR EIMS",
   ),
+  // Issuing a credit/debit memo is itself filing-equivalent — auto-submit picks it up like any
+  // other issued invoice — so it carries the same restricted grant as the eims_* actions above,
+  // not invoices:export.
+  perm(
+    "d2b00001-0001-4000-8000-00000000000a",
+    "edr_freight_app:invoices:memo_issue",
+    "Issue a credit or debit memo against a registered invoice",
+  ),
   // USD bookings are paid by bank transfer; Finance uploads the slip and settles
   // the invoice. Moves money state, so it is its own grant, not part of view.
   perm(
@@ -1874,6 +1882,7 @@ export const FREIGHT_PERMS = {
     eimsResolve: "edr_freight_app:invoices:eims_resolve",
     eimsCancel: "edr_freight_app:invoices:eims_cancel",
     eimsReceiptRegister: "edr_freight_app:invoices:eims_receipt_register",
+    memoIssue: "edr_freight_app:invoices:memo_issue",
     confirmOffline: "edr_freight_app:invoices:confirm_offline",
   },
   firstMile: {
@@ -2406,9 +2415,11 @@ export const ROLE_PERMISSION_PRESETS = {
     FREIGHT_PERMS.invoices.view,
     FREIGHT_PERMS.invoices.export,
     // Deliberately NOT granted here: invoices:eims_register, eims_resolve, eims_cancel,
-    // eims_receipt_register. Invoices are filed with MoR by the workflow, not by a person, so
-    // filing is not a Finance job function — the endpoints exist for controlled testing and
-    // exceptional operations, and are assigned to named admins rather than a role preset.
+    // eims_receipt_register, eims:memo_issue. Automatic filing needs no human permission at all
+    // (the cron sweep runs as the system); these are the *manual* exceptional-operations
+    // endpoints, and stay off the general Finance role. They are granted to the `chief` position
+    // instead — see below — the same maker–checker split already used for shipping-line credit
+    // mark-paid/cancel (Finance raises, chief decides).
     FREIGHT_PERMS.payments.view,
     FREIGHT_PERMS.bookings.wagonCancellationView,
     // Shipping-line credit ledger is a Finance surface: bill batches into
@@ -2519,6 +2530,14 @@ export const POSITION_PERMISSION_PRESETS = {
     FREIGHT_PERMS.bookings.governmentExpedite,
     FREIGHT_PERMS.invoices.view,
     FREIGHT_PERMS.invoices.export,
+    // Manual MoR EIMS actions and credit/debit memo issuance: kept off the general Finance role
+    // (see that preset's comment) and granted here instead — the chief is already the decision
+    // side of every other sensitive finance action (mark-paid/cancel approval below), and these
+    // are irreversible-at-MoR or receivable-creating in the same way.
+    FREIGHT_PERMS.invoices.eimsCancel,
+    FREIGHT_PERMS.invoices.eimsResolve,
+    FREIGHT_PERMS.invoices.eimsReceiptRegister,
+    FREIGHT_PERMS.invoices.memoIssue,
     FREIGHT_PERMS.payments.view,
     // Decision side of the credit-invoice two-step: finance raises
     // mark-paid/cancel requests, the chief approves or rejects them.

From 8e70352407ff65193652f876890cd7d7a2766490 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Sat, 15 Aug 2026 06:44:53 +0000
Subject: [PATCH 109/174] feat(eims): printable receipt PDF with RRN and QR

eims-receipt-document.mapper.ts maps an EimsReceipt onto the shared
InvoiceDocumentModel layout, reading amounts back out of the stored request
body. Refuses to render anything not REGISTERED. GET
invoices/:id/eims/receipts/:receiptId/document, scoped to the invoice.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../documents/invoice-document.service.ts     |   9 ++
 .../modules/eims/eims-invoice.controller.ts   |  16 ++-
 .../eims/eims-receipt-document.mapper.ts      | 107 ++++++++++++++++++
 .../modules/eims/eims-receipt.service.spec.ts |  80 ++++++++++++-
 .../src/modules/eims/eims-receipt.service.ts  |  28 +++++
 .../src/modules/eims/eims.module.ts           |   4 +
 6 files changed, 239 insertions(+), 5 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/eims/eims-receipt-document.mapper.ts

diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
index f6b264636..2d5e97e92 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
@@ -18,6 +18,15 @@ import {
 
 export type InvoiceDocumentKind = "INVOICE" | "RECEIPT";
 
+/**
+ * MoR returns `signedQR`/`qr` as a base64 PNG already rendered server-side — confirmed against the
+ * Postman collection's `register` response (`signedQR` decodes to a PNG magic-byte header), not a
+ * payload we encode ourselves. Wrap, don't encode. Shared by `Invoice.eimsSignedQr`
+ * (`BillingService`) and `EimsReceipt.qr` (`eims-receipt-document.mapper.ts`) — same convention,
+ * same gateway.
+ */
+export const pngDataUrl = (base64: string): string => `data:image/png;base64,${base64}`;
+
 /** One billed line on the document (charge type / fee type agnostic). */
 export interface InvoiceDocumentLine {
   description: string | null;
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts
index c02c7870e..7d417551f 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts
@@ -1,8 +1,10 @@
-import { Body, Controller, Get, Param, ParseUUIDPipe, Post } from "@nestjs/common";
+import { Body, Controller, Get, Param, ParseUUIDPipe, Post, Res } from "@nestjs/common";
 import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
+import type { Response } from "express";
 
 import { BookingStaff } from "../../common/booking-guards";
 import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
+import { sendPdf } from "../billing/billing.controller";
 import { CancelEimsRegistrationDto } from "./dto/cancel-eims-registration.dto";
 import { RegisterSalesReceiptDto } from "./dto/register-sales-receipt.dto";
 import { RegisterWithholdingReceiptDto } from "./dto/register-withholding-receipt.dto";
@@ -110,4 +112,16 @@ export class EimsInvoiceController {
   listReceipts(@Param("id", ParseUUIDPipe) id: string) {
     return this.receipts.listReceipts(id);
   }
+
+  @Get(":id/eims/receipts/:receiptId/document")
+  @BookingStaff(FREIGHT_PERMS.invoices.export)
+  @ApiOperation({ summary: "Download the sealed receipt PDF (RRN + QR) for a filed EIMS receipt" })
+  async receiptDocument(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Param("receiptId", ParseUUIDPipe) receiptId: string,
+    @Res() res: Response,
+  ) {
+    const { filename, buffer } = await this.receipts.document(id, receiptId);
+    sendPdf(res, filename, buffer);
+  }
 }
diff --git a/apps/edr-freight-api/src/modules/eims/eims-receipt-document.mapper.ts b/apps/edr-freight-api/src/modules/eims/eims-receipt-document.mapper.ts
new file mode 100644
index 000000000..841bfcc54
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/eims-receipt-document.mapper.ts
@@ -0,0 +1,107 @@
+import { Invoice } from "../billing/entities/invoice.entity";
+import {
+  InvoiceDocumentModel,
+  pngDataUrl,
+} from "../billing/documents/invoice-document.service";
+import { EimsReceipt, EimsReceiptStatus } from "./entities/eims-receipt.entity";
+import { EimsSalesReceiptRequest, EimsWithholdReceiptRequest } from "./eims-receipt.types";
+
+/**
+ * Maps a filed `EimsReceipt` onto the shared invoice/receipt document layout — mirrors
+ * `eims-invoice.mapper.ts`'s role for `/v1/register`: a pure function, no I/O.
+ *
+ * The amounts (collected amount, mode of payment, withholding amount) live only in
+ * `receipt.request` — the exact body this app sent, typed and written in exactly one place
+ * (`EimsReceiptService`). Reading it back is a cast, not a new source of truth; real columns
+ * would mean a migration + backfill for data already present in a stable shape.
+ *
+ * Throws rather than returning a model for anything not actually filed: a sealed, stamped PDF
+ * for a receipt MoR rejected, never acknowledged, or whose request was somehow never recorded
+ * would read as a genuine tax document. Callers (`EimsReceiptService.document`) let this throw
+ * surface as a 400 — there is nothing sensible to render instead.
+ */
+export function toReceiptDocumentModel(receipt: EimsReceipt, invoice: Invoice): InvoiceDocumentModel {
+  if (receipt.status !== EimsReceiptStatus.Registered) {
+    throw new Error(
+      `Receipt ${receipt.receiptNumber} is ${receipt.status}, not REGISTERED — refusing to print an unfiled receipt.`,
+    );
+  }
+  if (!receipt.request) {
+    throw new Error(`Receipt ${receipt.receiptNumber} has no stored request body — cannot render its amounts.`);
+  }
+
+  const isSales = receipt.kind === "SALES";
+
+  if (isSales) {
+    const req = receipt.request as unknown as EimsSalesReceiptRequest;
+    return build(receipt, invoice, {
+      title: "Sales Receipt",
+      currency: req.ReceiptCurrency,
+      amountLabel: "Collected",
+      lineDescription: `Payment received against invoice ${invoice.invoiceNumber}`,
+      amount: req.CollectedAmount,
+      // A sales receipt is a real payment — this is the one case the shared layout's own default
+      // ("EDR PAID" for kind RECEIPT) is already correct, but set it explicitly so it never drifts
+      // if that default changes for an unrelated reason.
+      sealText: "EDR PAID",
+      extraSummary: [{ label: "Mode of payment", value: req.TransactionDetails.ModeOfPayment }],
+    });
+  }
+
+  const req = receipt.request as unknown as EimsWithholdReceiptRequest;
+  return build(receipt, invoice, {
+    title: "Withholding Receipt",
+    currency: req.InvoiceDetail.Currency,
+    amountLabel: "Withheld",
+    lineDescription: `Withholding (${req.WithholdDetail.Type}) against invoice ${invoice.invoiceNumber}`,
+    amount: req.WithholdDetail.WithholdingAmount,
+    // A withholding receipt is not a payment — the shared layout's "EDR PAID" default would be
+    // wrong here, so this is the one case that MUST override it.
+    sealText: "EDR",
+    extraSummary: [{ label: "Withholding type", value: req.WithholdDetail.Type }],
+  });
+}
+
+function build(
+  receipt: EimsReceipt,
+  invoice: Invoice,
+  opts: {
+    title: string;
+    currency: string;
+    amountLabel: string;
+    lineDescription: string;
+    amount: number;
+    sealText: string;
+    extraSummary: Array<{ label: string; value: string | null }>;
+  },
+): InvoiceDocumentModel {
+  return {
+    kind: "RECEIPT",
+    title: opts.title,
+    documentNumber: receipt.receiptNumber,
+    issuedAt: receipt.submittedAt ?? null,
+    status: receipt.status,
+    currency: opts.currency,
+    summary: [
+      { label: "Invoice", value: invoice.invoiceNumber },
+      { label: "Invoice IRN", value: invoice.eimsIrn ?? null },
+      { label: "RRN", value: receipt.rrn ?? null },
+      { label: "Ack status", value: receipt.ackStatus ?? null },
+      ...opts.extraSummary,
+    ],
+    // No line items on a receipt — one synthetic line, since buildHtml renders the line table
+    // unconditionally and an empty `lines: []` would print a header-only empty table.
+    lines: [
+      {
+        description: opts.lineDescription,
+        quantity: 1,
+        unitRate: opts.amount,
+        amount: opts.amount,
+        currency: opts.currency,
+      },
+    ],
+    totals: [{ label: opts.amountLabel, amount: opts.amount, grand: true }],
+    sealText: opts.sealText,
+    qrImageUrl: receipt.qr ? pngDataUrl(receipt.qr) : null,
+  };
+}
diff --git a/apps/edr-freight-api/src/modules/eims/eims-receipt.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-receipt.service.spec.ts
index b9b59cc27..93f50e827 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-receipt.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-receipt.service.spec.ts
@@ -4,6 +4,7 @@ import { DataSource } from "typeorm";
 
 import { EimsConfig } from "../../config/eims.config";
 import { Invoice } from "../billing/entities/invoice.entity";
+import { InvoiceDocumentService } from "../billing/documents/invoice-document.service";
 import { NotificationsService } from "../notifications/notifications.service";
 import { EimsAuthService } from "./eims-auth.service";
 import { EimsClientService } from "./eims-client.service";
@@ -40,10 +41,16 @@ class FakeDb {
   }
 
   private manager = {
-    findOne: async (entity: unknown, options: { where: { id: string } }) =>
-      entity === Invoice
-        ? (this.invoices.get(options.where.id) ?? null)
-        : (this.receipts.get(options.where.id) ?? null),
+    findOne: async (
+      entity: unknown,
+      options: { where: { id?: string; invoiceId?: string } },
+    ) => {
+      if (entity === Invoice) return this.invoices.get(options.where.id!) ?? null;
+      const receipt = options.where.id ? this.receipts.get(options.where.id) : undefined;
+      if (!receipt) return null;
+      if (options.where.invoiceId && receipt.invoiceId !== options.where.invoiceId) return null;
+      return receipt;
+    },
     find: async (_entity: unknown, options: { where: { invoiceId: string } }) =>
       [...this.receipts.values()].filter((r) => r.invoiceId === options.where.invoiceId),
     save: async (_entity: unknown, data: Record<string, unknown>) => {
@@ -71,6 +78,7 @@ const build = (
   db: FakeDb,
   postBearer: jest.Mock,
   directSend: jest.Mock = jest.fn().mockResolvedValue(undefined),
+  documents: { render: jest.Mock } = { render: jest.fn() },
 ) =>
   new EimsReceiptService(
     db.asDataSource(),
@@ -78,6 +86,7 @@ const build = (
     { postBearer } as unknown as EimsClientService,
     { getSessionContext: jest.fn().mockResolvedValue(SESSION) } as unknown as EimsAuthService,
     { directSend } as unknown as NotificationsService,
+    documents as unknown as InvoiceDocumentService,
   );
 
 const okResponse = (over: Record<string, unknown> = {}) => ({
@@ -229,3 +238,66 @@ describe("EimsReceiptService.listReceipts", () => {
     expect(list).toHaveLength(2);
   });
 });
+
+describe("EimsReceiptService.document", () => {
+  it("renders a sealed PDF for a registered sales receipt, with RRN and QR in the model", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const documents = { render: jest.fn().mockResolvedValue({ filename: "x.pdf", buffer: Buffer.from("") }) };
+    const service = build(db, jest.fn().mockResolvedValue(okResponse()), undefined, documents);
+    const receipt = await service.registerSalesReceipt(INVOICE_ID, {
+      modeOfPayment: "CASH",
+      collectedAmount: 500,
+    } as never);
+
+    await service.document(INVOICE_ID, receipt.id);
+
+    expect(documents.render).toHaveBeenCalledTimes(1);
+    const model = documents.render.mock.calls[0][0];
+    expect(model.kind).toBe("RECEIPT");
+    expect(model.qrImageUrl).toBe("data:image/png;base64,iVBORw0KGgo...");
+    expect(model.summary).toContainEqual({ label: "RRN", value: "rrn-value" });
+    expect(model.lines[0].amount).toBe(500);
+    expect(model.sealText).toBe("EDR PAID");
+  });
+
+  it("renders a withholding receipt with the withheld amount and a non-PAID seal", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const documents = { render: jest.fn().mockResolvedValue({ filename: "x.pdf", buffer: Buffer.from("") }) };
+    const service = build(db, jest.fn().mockResolvedValue(okResponse()), undefined, documents);
+    const receipt = await service.registerWithholdingReceipt(INVOICE_ID, {
+      type: "TWHT",
+      preTaxAmount: 1000,
+      withholdingAmount: 20,
+    } as never);
+
+    await service.document(INVOICE_ID, receipt.id);
+
+    const model = documents.render.mock.calls[0][0];
+    expect(model.lines[0].amount).toBe(20);
+    expect(model.sealText).toBe("EDR");
+    expect(model.sealText).not.toContain("PAID");
+  });
+
+  it("refuses to render a receipt that was never acknowledged by MoR", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postBearer = jest.fn().mockRejectedValue(new EimsApiException("TIMEOUT", "EIMS receipt timed out"));
+    const documents = { render: jest.fn() };
+    const service = build(db, postBearer, undefined, documents);
+    await expect(
+      service.registerSalesReceipt(INVOICE_ID, { modeOfPayment: "CASH" } as never),
+    ).rejects.toBeInstanceOf(EimsApiException);
+    const [receipt] = [...db.receipts.values()];
+
+    await expect(service.document(INVOICE_ID, receipt.id as string)).rejects.toBeInstanceOf(BadRequestException);
+    expect(documents.render).not.toHaveBeenCalled();
+  });
+
+  it("scopes the lookup to the given invoice — a receipt from another invoice is not found", async () => {
+    const OTHER_INVOICE_ID = "22222222-2222-4222-8222-222222222222";
+    const db = new FakeDb([invoiceRow(), invoiceRow({ id: OTHER_INVOICE_ID })]);
+    const service = build(db, jest.fn().mockResolvedValue(okResponse()));
+    const receipt = await service.registerSalesReceipt(INVOICE_ID, { modeOfPayment: "CASH" } as never);
+
+    await expect(service.document(OTHER_INVOICE_ID, receipt.id)).rejects.toThrow(/not found/);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/eims/eims-receipt.service.ts b/apps/edr-freight-api/src/modules/eims/eims-receipt.service.ts
index dfbbd688b..2bdb6cbe2 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-receipt.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-receipt.service.ts
@@ -6,11 +6,13 @@ import type { QueryDeepPartialEntity } from "typeorm/query-builder/QueryPartialE
 
 import { EimsConfig } from "../../config/eims.config";
 import { Invoice } from "../billing/entities/invoice.entity";
+import { InvoiceDocumentService } from "../billing/documents/invoice-document.service";
 import { NotificationsService } from "../notifications/notifications.service";
 import { sendCompanyChannels } from "../notifications/notify-company.util";
 import { EimsAuthService } from "./eims-auth.service";
 import { EimsClientService } from "./eims-client.service";
 import { EimsApiException } from "./eims.errors";
+import { toReceiptDocumentModel } from "./eims-receipt-document.mapper";
 import { EimsReceipt, EimsReceiptKind, EimsReceiptStatus } from "./entities/eims-receipt.entity";
 import { RegisterSalesReceiptDto } from "./dto/register-sales-receipt.dto";
 import { RegisterWithholdingReceiptDto } from "./dto/register-withholding-receipt.dto";
@@ -52,6 +54,7 @@ export class EimsReceiptService {
     private readonly client: EimsClientService,
     private readonly auth: EimsAuthService,
     private readonly notifications: NotificationsService,
+    private readonly documents: InvoiceDocumentService,
   ) {}
 
   private get cfg(): EimsConfig {
@@ -154,6 +157,31 @@ export class EimsReceiptService {
     });
   }
 
+  /**
+   * Sealed PDF for one filed receipt (RRN + QR), scoped to the invoice it belongs to. Not on
+   * `loadRegisteredInvoice` — a receipt refused/never-acknowledged by MoR must not render as a
+   * sealed tax document, and `toReceiptDocumentModel` is the one place that guards it.
+   */
+  async document(invoiceId: string, receiptId: string): Promise<{ filename: string; buffer: Buffer }> {
+    const receipt = await this.dataSource.manager.findOne(EimsReceipt, {
+      where: { id: receiptId, invoiceId },
+    });
+    if (!receipt) throw new NotFoundException(`Receipt ${receiptId} not found on invoice ${invoiceId}`);
+    const invoice = await this.dataSource.manager.findOne(Invoice, { where: { id: invoiceId } });
+    if (!invoice) throw new NotFoundException(`Invoice ${invoiceId} not found`);
+
+    let model: ReturnType<typeof toReceiptDocumentModel>;
+    try {
+      model = toReceiptDocumentModel(receipt, invoice);
+    } catch (err) {
+      // Only the mapper's own refusals (not-yet-registered, missing request body) become a 400 —
+      // a genuine PDF-render failure below is left to surface as whatever InvoiceDocumentService
+      // itself throws.
+      throw new BadRequestException((err as Error).message);
+    }
+    return this.documents.render(model);
+  }
+
   // ── internals ────────────────────────────────────────────────────────────────────────────────
 
   private async submit(
diff --git a/apps/edr-freight-api/src/modules/eims/eims.module.ts b/apps/edr-freight-api/src/modules/eims/eims.module.ts
index 7aa59b3ef..0ee22ec88 100644
--- a/apps/edr-freight-api/src/modules/eims/eims.module.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims.module.ts
@@ -3,6 +3,7 @@ import { Module } from "@nestjs/common";
 import { TypeOrmModule } from "@nestjs/typeorm";
 
 import { Invoice } from "../billing/entities/invoice.entity";
+import { DocumentsModule } from "../billing/documents/documents.module";
 import { NotificationInboxModule } from "../notification-inbox/notification-inbox.module";
 import { NotificationsModule } from "../notifications/notifications.module";
 import { EimsAuthService } from "./eims-auth.service";
@@ -29,6 +30,9 @@ import { EimsSystemState } from "./entities/eims-system-state.entity";
     TypeOrmModule.forFeature([EimsSystemState, Invoice, EimsReceipt]),
     NotificationInboxModule,
     NotificationsModule,
+    // For EimsReceiptService.document() — the shared sealed invoice/receipt PDF layout. No domain
+    // deps of its own (StampSettingsService/LogoSettingsService are both @Global), so no cycle.
+    DocumentsModule,
   ],
   controllers: [EimsInvoiceController],
   providers: [

From 47c2e8283936e9a43bcfda418b1cfcfb29cf2548 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Sat, 15 Aug 2026 06:45:00 +0000
Subject: [PATCH 110/174] feat(freight-backoffice): EIMS cancel/receipt/memo
 actions in filing card

Adds cancel, sales/withholding receipt filing + listing + PDF download, and
credit/debit memo issuance to EimsFilingCard, each gated on its own
permission.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../components/invoices/EimsFilingCard.tsx    | 495 ++++++++++++++++--
 .../backoffice/src/constants/QUERY_KEYS.ts    |   1 +
 .../backoffice/src/constants/URLS.ts          |   7 +
 .../backoffice/src/lib/permissions.ts         |  10 +-
 .../backoffice/src/services/api.ts            |  47 +-
 .../backoffice/src/services/eims.service.ts   |  48 +-
 .../src/services/invoices.service.ts          |  10 +
 .../backoffice/src/types/eims.ts              |  13 +
 8 files changed, 593 insertions(+), 38 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/components/invoices/EimsFilingCard.tsx b/apps/edr-freight-web/backoffice/src/components/invoices/EimsFilingCard.tsx
index ba507513c..c668c0570 100644
--- a/apps/edr-freight-web/backoffice/src/components/invoices/EimsFilingCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/invoices/EimsFilingCard.tsx
@@ -1,11 +1,30 @@
-import { Alert, Badge, Button, Card, Group, SimpleGrid, Stack, Text } from "@mantine/core";
+import { useState } from "react";
+import {
+  Alert,
+  Badge,
+  Button,
+  Card,
+  Group,
+  Modal,
+  NumberInput,
+  Radio,
+  Select,
+  SimpleGrid,
+  Stack,
+  Table,
+  Text,
+  Textarea,
+  TextInput,
+} from "@mantine/core";
 import { useMutation, useQuery } from "@tanstack/react-query";
-import { AlertTriangle, RefreshCw, Send, ShieldCheck } from "lucide-react";
+import { AlertTriangle, Ban, Download, FileText, RefreshCw, Send, ShieldCheck } from "lucide-react";
 
 import { useAuth } from "@/auth/useAuth";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import { api } from "@/services/api";
-import type { EimsInvoiceStatus } from "@/types/eims";
+import { eimsService } from "@/services/eims.service";
+import { openPdfBlob } from "@/components/warehouses/pdf";
+import { EIMS_MODE_OF_PAYMENT, type EimsInvoiceStatus, type EimsModeOfPayment } from "@/types/eims";
 import { useToast } from "@/hooks/use-toast";
 
 const STATUS_COLOR: Record<EimsInvoiceStatus, string> = {
@@ -14,6 +33,7 @@ const STATUS_COLOR: Record<EimsInvoiceStatus, string> = {
   REGISTERED: "edr-green",
   FAILED: "red",
   UNKNOWN: "orange",
+  CANCELLED: "gray",
 };
 
 const STATUS_LABEL: Record<EimsInvoiceStatus, string> = {
@@ -22,6 +42,7 @@ const STATUS_LABEL: Record<EimsInvoiceStatus, string> = {
   REGISTERED: "Filed",
   FAILED: "Rejected",
   UNKNOWN: "Unacknowledged",
+  CANCELLED: "Cancelled",
 };
 
 function Field({ label, value }: { label: string; value?: string | number | null }) {
@@ -37,6 +58,367 @@ function Field({ label, value }: { label: string; value?: string | number | null
   );
 }
 
+/** Reason codes from the collection docs, e.g. "1" (Duplicate), "6" (Calculation Error). */
+const CANCEL_REASON_CODES = [
+  { value: "1", label: "1 — Duplicate" },
+  { value: "2", label: "2 — Buyer request" },
+  { value: "3", label: "3 — Data entry error" },
+  { value: "6", label: "6 — Calculation error" },
+];
+
+function CancelModal({
+  invoiceId,
+  opened,
+  onClose,
+}: {
+  invoiceId: string;
+  opened: boolean;
+  onClose: () => void;
+}) {
+  const { toast } = useToast();
+  const [reasonCode, setReasonCode] = useState<string | null>(null);
+  const [remark, setRemark] = useState("");
+
+  const cancel = useMutation(
+    api.invoices.eimsCancel.mutationOptions({
+      onSuccess: () => {
+        onClose();
+        toast({ title: "Cancelled with MoR" });
+      },
+      onError: (error) => toast({ title: "Could not cancel", description: error.message, variant: "destructive" }),
+    }),
+  );
+
+  return (
+    <Modal opened={opened} onClose={onClose} title="Cancel EIMS registration" centered>
+      <Stack gap="md">
+        <Text size="sm" c="dimmed">
+          Cancels this invoice&apos;s registered document at MoR. Irreversible — an already-cancelled
+          invoice refuses a second attempt.
+        </Text>
+        <Select
+          label="Reason code"
+          withAsterisk
+          data={CANCEL_REASON_CODES}
+          value={reasonCode}
+          onChange={setReasonCode}
+          placeholder="Select a reason"
+        />
+        <Textarea
+          label="Remark"
+          placeholder="Optional note"
+          value={remark}
+          onChange={(e) => setRemark(e.currentTarget.value)}
+          autosize
+          minRows={2}
+        />
+        <Button
+          color="red"
+          leftSection={<Ban size={16} />}
+          loading={cancel.isPending}
+          disabled={!reasonCode}
+          onClick={() => cancel.mutate({ id: invoiceId, reasonCode: reasonCode!, remark: remark.trim() || undefined })}
+        >
+          Cancel with MoR
+        </Button>
+      </Stack>
+    </Modal>
+  );
+}
+
+function SalesReceiptModal({
+  invoiceId,
+  opened,
+  onClose,
+}: {
+  invoiceId: string;
+  opened: boolean;
+  onClose: () => void;
+}) {
+  const { toast } = useToast();
+  const [modeOfPayment, setModeOfPayment] = useState<EimsModeOfPayment | null>(null);
+  const [collectedAmount, setCollectedAmount] = useState<number | "">("");
+  const [reason, setReason] = useState("");
+
+  const register = useMutation(
+    api.invoices.eimsRegisterSalesReceipt.mutationOptions({
+      onSuccess: (receipt) => {
+        onClose();
+        toast({ title: "Sales receipt filed", description: `RRN ${receipt.rrn ?? "—"}` });
+      },
+      onError: (error) => toast({ title: "Could not file receipt", description: error.message, variant: "destructive" }),
+    }),
+  );
+
+  return (
+    <Modal opened={opened} onClose={onClose} title="File sales receipt" centered>
+      <Stack gap="md">
+        <Select
+          label="Mode of payment"
+          withAsterisk
+          data={EIMS_MODE_OF_PAYMENT.map((v) => ({ value: v, label: v }))}
+          value={modeOfPayment}
+          onChange={(v) => setModeOfPayment(v as EimsModeOfPayment)}
+          placeholder="Select"
+        />
+        <NumberInput
+          label="Collected amount"
+          placeholder="Defaults to the invoice's paid amount"
+          min={0}
+          decimalScale={2}
+          value={collectedAmount}
+          onChange={(v) => setCollectedAmount(v === "" ? "" : Number(v))}
+        />
+        <TextInput
+          label="Reason"
+          placeholder='Defaults to "Payment received"'
+          value={reason}
+          onChange={(e) => setReason(e.currentTarget.value)}
+        />
+        <Button
+          color="edr-green"
+          leftSection={<Send size={16} />}
+          loading={register.isPending}
+          disabled={!modeOfPayment}
+          onClick={() =>
+            register.mutate({
+              id: invoiceId,
+              modeOfPayment: modeOfPayment!,
+              collectedAmount: collectedAmount === "" ? undefined : collectedAmount,
+              reason: reason.trim() || undefined,
+            })
+          }
+        >
+          File with MoR
+        </Button>
+      </Stack>
+    </Modal>
+  );
+}
+
+function WithholdingReceiptModal({
+  invoiceId,
+  opened,
+  onClose,
+}: {
+  invoiceId: string;
+  opened: boolean;
+  onClose: () => void;
+}) {
+  const { toast } = useToast();
+  const [type, setType] = useState("TWHT");
+  const [preTaxAmount, setPreTaxAmount] = useState<number | "">("");
+  const [withholdingAmount, setWithholdingAmount] = useState<number | "">("");
+  const [reason, setReason] = useState("");
+
+  const register = useMutation(
+    api.invoices.eimsRegisterWithholdingReceipt.mutationOptions({
+      onSuccess: (receipt) => {
+        onClose();
+        toast({ title: "Withholding receipt filed", description: `RRN ${receipt.rrn ?? "—"}` });
+      },
+      onError: (error) => toast({ title: "Could not file receipt", description: error.message, variant: "destructive" }),
+    }),
+  );
+
+  const valid = preTaxAmount !== "" && withholdingAmount !== "";
+
+  return (
+    <Modal opened={opened} onClose={onClose} title="File withholding receipt" centered>
+      <Stack gap="md">
+        <TextInput label="Type" withAsterisk value={type} onChange={(e) => setType(e.currentTarget.value)} />
+        <NumberInput
+          label="Pre-tax amount"
+          withAsterisk
+          min={0}
+          decimalScale={2}
+          value={preTaxAmount}
+          onChange={(v) => setPreTaxAmount(v === "" ? "" : Number(v))}
+        />
+        <NumberInput
+          label="Withholding amount"
+          withAsterisk
+          min={0}
+          decimalScale={2}
+          value={withholdingAmount}
+          onChange={(v) => setWithholdingAmount(v === "" ? "" : Number(v))}
+        />
+        <TextInput
+          label="Reason"
+          placeholder='Defaults to "Withholding"'
+          value={reason}
+          onChange={(e) => setReason(e.currentTarget.value)}
+        />
+        <Button
+          color="edr-green"
+          leftSection={<Send size={16} />}
+          loading={register.isPending}
+          disabled={!valid}
+          onClick={() =>
+            register.mutate({
+              id: invoiceId,
+              type,
+              preTaxAmount: preTaxAmount as number,
+              withholdingAmount: withholdingAmount as number,
+              reason: reason.trim() || undefined,
+            })
+          }
+        >
+          File with MoR
+        </Button>
+      </Stack>
+    </Modal>
+  );
+}
+
+function MemoModal({
+  invoiceId,
+  opened,
+  onClose,
+}: {
+  invoiceId: string;
+  opened: boolean;
+  onClose: () => void;
+}) {
+  const { toast } = useToast();
+  const [type, setType] = useState<"CRE" | "DEB">("CRE");
+  const [reason, setReason] = useState("");
+
+  const issue = useMutation(
+    api.invoices.issueMemo.mutationOptions({
+      onSuccess: (memo) => {
+        onClose();
+        toast({ title: "Memo issued", description: `${memo.invoiceNumber} — file it with MoR separately` });
+      },
+      onError: (error) => toast({ title: "Could not issue memo", description: error.message, variant: "destructive" }),
+    }),
+  );
+
+  return (
+    <Modal opened={opened} onClose={onClose} title="Issue credit/debit memo" centered>
+      <Stack gap="md">
+        <Text size="sm" c="dimmed">
+          Creates a new invoice linked to this one, with every line copied verbatim. Filing it with
+          MoR is a separate step — it does not happen automatically here.
+        </Text>
+        <Radio.Group value={type} onChange={(v) => setType(v as "CRE" | "DEB")} label="Type">
+          <Stack gap="xs" mt="xs">
+            <Radio value="CRE" label="Credit memo" description="Reduces what the buyer owes; created settled." />
+            <Radio value="DEB" label="Debit memo" description="An additional charge; created as a new open invoice." />
+          </Stack>
+        </Radio.Group>
+        <Textarea
+          label="Reason"
+          withAsterisk
+          placeholder="Why this memo is being issued"
+          value={reason}
+          onChange={(e) => setReason(e.currentTarget.value)}
+          autosize
+          minRows={2}
+        />
+        <Button
+          color="edr-green"
+          loading={issue.isPending}
+          disabled={!reason.trim()}
+          onClick={() => issue.mutate({ id: invoiceId, type, reason: reason.trim() })}
+        >
+          Issue memo
+        </Button>
+      </Stack>
+    </Modal>
+  );
+}
+
+function ReceiptsSection({ invoiceId, canFile }: { invoiceId: string; canFile: boolean }) {
+  const { toast } = useToast();
+  const { data: receipts } = useQuery(api.invoices.eimsReceipts.queryOptions({ input: { id: invoiceId } }));
+  const [salesOpen, setSalesOpen] = useState(false);
+  const [withholdingOpen, setWithholdingOpen] = useState(false);
+  const [downloadingId, setDownloadingId] = useState<string | null>(null);
+
+  const download = async (receiptId: string, receiptNumber: string) => {
+    setDownloadingId(receiptId);
+    try {
+      const { data } = await eimsService.downloadReceiptDocument(invoiceId, receiptId);
+      openPdfBlob(data, `${receiptNumber}.pdf`);
+    } catch (error) {
+      toast({
+        title: "Could not download receipt",
+        description: error instanceof Error ? error.message : undefined,
+        variant: "destructive",
+      });
+    } finally {
+      setDownloadingId(null);
+    }
+  };
+
+  return (
+    <Stack gap="sm">
+      <Group justify="space-between">
+        <Text fw={600} size="sm" c="edr-text">
+          Receipts
+        </Text>
+        {canFile && (
+          <Group gap="xs">
+            <Button size="xs" variant="light" onClick={() => setSalesOpen(true)}>
+              File sales receipt
+            </Button>
+            <Button size="xs" variant="light" onClick={() => setWithholdingOpen(true)}>
+              File withholding receipt
+            </Button>
+          </Group>
+        )}
+      </Group>
+
+      {receipts && receipts.length > 0 ? (
+        <Table striped withTableBorder={false} verticalSpacing="xs">
+          <Table.Thead>
+            <Table.Tr>
+              <Table.Th>Kind</Table.Th>
+              <Table.Th>Status</Table.Th>
+              <Table.Th>RRN</Table.Th>
+              <Table.Th />
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            {receipts.map((r) => (
+              <Table.Tr key={r.id}>
+                <Table.Td>{r.kind}</Table.Td>
+                <Table.Td>
+                  <Badge color={STATUS_COLOR[r.status] ?? "gray"} variant="light" size="sm">
+                    {STATUS_LABEL[r.status] ?? r.status}
+                  </Badge>
+                </Table.Td>
+                <Table.Td style={{ fontFamily: "monospace" }}>{r.rrn ?? "—"}</Table.Td>
+                <Table.Td>
+                  {r.status === "REGISTERED" && (
+                    <Button
+                      size="xs"
+                      variant="subtle"
+                      leftSection={<Download size={14} />}
+                      loading={downloadingId === r.id}
+                      onClick={() => void download(r.id, r.receiptNumber)}
+                    >
+                      PDF
+                    </Button>
+                  )}
+                </Table.Td>
+              </Table.Tr>
+            ))}
+          </Table.Tbody>
+        </Table>
+      ) : (
+        <Text size="sm" c="dimmed">
+          No receipts filed yet.
+        </Text>
+      )}
+
+      <SalesReceiptModal invoiceId={invoiceId} opened={salesOpen} onClose={() => setSalesOpen(false)} />
+      <WithholdingReceiptModal invoiceId={invoiceId} opened={withholdingOpen} onClose={() => setWithholdingOpen(false)} />
+    </Stack>
+  );
+}
+
 /**
  * MoR EIMS filing state for one invoice, with the manual actions.
  *
@@ -48,6 +430,12 @@ export function EimsFilingCard({ invoiceId }: { invoiceId: string }) {
   const { user } = useAuth();
   const { toast } = useToast();
   const canFile = hasPermission(user, FREIGHT_PERMS.invoices.eimsRegister);
+  const canCancel = hasPermission(user, FREIGHT_PERMS.invoices.eimsCancel);
+  const canFileReceipt = hasPermission(user, FREIGHT_PERMS.invoices.eimsReceiptRegister);
+  const canIssueMemo = hasPermission(user, FREIGHT_PERMS.invoices.memoIssue);
+
+  const [cancelOpen, setCancelOpen] = useState(false);
+  const [memoOpen, setMemoOpen] = useState(false);
 
   const { data: eims, isLoading } = useQuery(
     api.invoices.eimsStatus.queryOptions({ input: { id: invoiceId }, enabled: Boolean(invoiceId) }),
@@ -118,39 +506,78 @@ export function EimsFilingCard({ invoiceId }: { invoiceId: string }) {
           </Alert>
         )}
 
-        {canFile && (
-          <Group gap="sm">
-            {/* UNKNOWN is never re-filed from here: resubmitting risks a duplicate registration. */}
-            {status !== "REGISTERED" && status !== "UNKNOWN" && (
-              <Button
-                size="xs"
-                variant="light"
-                radius="md"
-                loading={register.isPending}
-                disabled={busy}
-                leftSection={status === "FAILED" ? <RefreshCw size={14} /> : <Send size={14} />}
-                onClick={() => register.mutate({ id: invoiceId })}
-              >
-                {status === "FAILED" ? "File again" : "File with MoR"}
-              </Button>
-            )}
-
-            {eims.eimsIrn && (
-              <Button
-                size="xs"
-                variant="light"
-                radius="md"
-                loading={verify.isPending}
-                disabled={busy}
-                leftSection={<ShieldCheck size={14} />}
-                onClick={() => verify.mutate({ id: invoiceId })}
-              >
-                Verify with MoR
-              </Button>
-            )}
-          </Group>
+        {status === "CANCELLED" && (
+          <Alert color="gray" icon={<Ban size={16} />} title="Cancelled with MoR">
+            {eims.eimsCancellationDate ? `Confirmed ${eims.eimsCancellationDate}. ` : ""}
+            {eims.eimsCancellationRemark}
+          </Alert>
         )}
+
+        <Group gap="sm">
+          {canFile && (
+            <>
+              {/* UNKNOWN is never re-filed from here: resubmitting risks a duplicate registration. */}
+              {status !== "REGISTERED" && status !== "UNKNOWN" && status !== "CANCELLED" && (
+                <Button
+                  size="xs"
+                  variant="light"
+                  radius="md"
+                  loading={register.isPending}
+                  disabled={busy}
+                  leftSection={status === "FAILED" ? <RefreshCw size={14} /> : <Send size={14} />}
+                  onClick={() => register.mutate({ id: invoiceId })}
+                >
+                  {status === "FAILED" ? "File again" : "File with MoR"}
+                </Button>
+              )}
+
+              {eims.eimsIrn && (
+                <Button
+                  size="xs"
+                  variant="light"
+                  radius="md"
+                  loading={verify.isPending}
+                  disabled={busy}
+                  leftSection={<ShieldCheck size={14} />}
+                  onClick={() => verify.mutate({ id: invoiceId })}
+                >
+                  Verify with MoR
+                </Button>
+              )}
+            </>
+          )}
+
+          {canCancel && eims.eimsIrn && status !== "CANCELLED" && (
+            <Button
+              size="xs"
+              variant="light"
+              color="red"
+              radius="md"
+              leftSection={<Ban size={14} />}
+              onClick={() => setCancelOpen(true)}
+            >
+              Cancel with MoR
+            </Button>
+          )}
+
+          {canIssueMemo && status === "REGISTERED" && (
+            <Button
+              size="xs"
+              variant="light"
+              radius="md"
+              leftSection={<FileText size={14} />}
+              onClick={() => setMemoOpen(true)}
+            >
+              Issue credit/debit memo
+            </Button>
+          )}
+        </Group>
+
+        {eims.eimsIrn && <ReceiptsSection invoiceId={invoiceId} canFile={canFileReceipt} />}
       </Stack>
+
+      <CancelModal invoiceId={invoiceId} opened={cancelOpen} onClose={() => setCancelOpen(false)} />
+      <MemoModal invoiceId={invoiceId} opened={memoOpen} onClose={() => setMemoOpen(false)} />
     </Card>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
index f160a70ff..67d8107d1 100644
--- a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
@@ -96,6 +96,7 @@ export const QUERY_KEYS = {
     offlineUsd: (filter?: InvoiceListFilter) =>
       ["invoices", "offline-usd", filter ?? {}] as const,
     eimsStatus: (id: string) => ["invoices", "eims", id] as const,
+    eimsReceipts: (id: string) => ["invoices", "eims", id, "receipts"] as const,
   },
 
   BOOKINGS: {
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index 2a9f40ebd..160271671 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -136,6 +136,7 @@ export const URL_CONSTANTS = {
     INVOICES: "/billing/invoices",
     INVOICE_BY_ID: (id: string) => `/billing/invoices/${id}`,
     INVOICE_DOCUMENT: (id: string) => `/billing/invoices/${id}/document`,
+    INVOICE_MEMO: (id: string) => `/billing/invoices/${id}/memo`,
     OFFLINE_USD: "/billing/offline-usd",
     CONFIRM_OFFLINE: (id: string) => `/billing/invoices/${id}/confirm-offline`,
   },
@@ -146,6 +147,12 @@ export const URL_CONSTANTS = {
     REGISTER: (id: string) => `/invoices/${id}/eims/register`,
     VERIFY: (id: string) => `/invoices/${id}/eims/verify`,
     RESOLVE: (id: string) => `/invoices/${id}/eims/resolve`,
+    CANCEL: (id: string) => `/invoices/${id}/eims/cancel`,
+    RECEIPT_SALES: (id: string) => `/invoices/${id}/eims/receipt/sales`,
+    RECEIPT_WITHHOLDING: (id: string) => `/invoices/${id}/eims/receipt/withholding`,
+    RECEIPTS: (id: string) => `/invoices/${id}/eims/receipts`,
+    RECEIPT_DOCUMENT: (id: string, receiptId: string) =>
+      `/invoices/${id}/eims/receipts/${receiptId}/document`,
   },
 
   CUSTOMERS_API: {
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index 73c15fc86..fe4d4fff9 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -145,10 +145,16 @@ export const FREIGHT_PERMS = {
     view: "edr_freight_app:invoices:view",
     export: "edr_freight_app:invoices:export",
     confirmOffline: "edr_freight_app:invoices:confirm_offline",
-    // Filing with MoR EIMS. Held by named admins rather than a role preset: registration is
-    // irreversible at the tax authority, and resolving clears a system-wide filing block.
+    // Filing with MoR EIMS. Off the general Finance role — automatic filing needs no permission
+    // at all (the cron sweep runs as the system); these are the manual, exceptional-operations
+    // actions, granted to the `chief` position (maker-checker, same as shipping-line credit
+    // mark-paid/cancel approval) rather than every Finance user.
     eimsRegister: "edr_freight_app:invoices:eims_register",
     eimsResolve: "edr_freight_app:invoices:eims_resolve",
+    eimsCancel: "edr_freight_app:invoices:eims_cancel",
+    eimsReceiptRegister: "edr_freight_app:invoices:eims_receipt_register",
+    // Issuing a credit/debit memo is filing-equivalent — same restricted grant as the eims_* keys.
+    memoIssue: "edr_freight_app:invoices:memo_issue",
   },
   firstMile: {
     view: "edr_freight_app:first_mile:view",
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 78efb2e4b..31db24d0d 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -173,7 +173,7 @@ import { customersService } from "./customers.service";
 import { shippingLineCompaniesService } from "./shippingLineCompanies.service";
 import { shippingLineCreditsService } from "./shippingLineCredits.service";
 import { eimsService } from "./eims.service";
-import type { EimsInvoiceStatusView, EimsVerifyResult } from "@/types/eims";
+import type { EimsInvoiceStatusView, EimsModeOfPayment, EimsReceiptView, EimsVerifyResult } from "@/types/eims";
 import { invoicesService } from "./invoices.service";
 import { dropdownSettingsService } from "./dropdownSettings.service";
 import { fileUploadSettingsService } from "./fileUploadSettings.service";
@@ -3189,6 +3189,51 @@ export const api = {
       undefined,
       ({ id }) => [QUERY_KEYS.INVOICES.eimsStatus(id), QUERY_KEYS.INVOICES.byId(id)],
     ),
+
+    eimsCancel: endpoint<{ id: string; reasonCode: string; remark?: string }, EimsInvoiceStatusView>(
+      "invoices",
+      "eimsCancel",
+      ({ id, reasonCode, remark }) => eimsService.cancel(id, { reasonCode, remark }),
+      undefined,
+      ({ id }) => [QUERY_KEYS.INVOICES.eimsStatus(id), QUERY_KEYS.INVOICES.byId(id)],
+    ),
+
+    eimsReceipts: endpoint<{ id: string }, EimsReceiptView[]>(
+      "invoices",
+      "eimsReceipts",
+      ({ id }) => eimsService.listReceipts(id),
+      ({ id }) => QUERY_KEYS.INVOICES.eimsReceipts(id),
+    ),
+
+    eimsRegisterSalesReceipt: endpoint<
+      { id: string; modeOfPayment: EimsModeOfPayment; reason?: string; collectedAmount?: number },
+      EimsReceiptView
+    >(
+      "invoices",
+      "eimsRegisterSalesReceipt",
+      ({ id, ...input }) => eimsService.registerSalesReceipt(id, input),
+      undefined,
+      ({ id }) => [QUERY_KEYS.INVOICES.eimsReceipts(id)],
+    ),
+
+    eimsRegisterWithholdingReceipt: endpoint<
+      { id: string; type: string; preTaxAmount: number; withholdingAmount: number; reason?: string },
+      EimsReceiptView
+    >(
+      "invoices",
+      "eimsRegisterWithholdingReceipt",
+      ({ id, ...input }) => eimsService.registerWithholdingReceipt(id, input),
+      undefined,
+      ({ id }) => [QUERY_KEYS.INVOICES.eimsReceipts(id)],
+    ),
+
+    issueMemo: endpoint<{ id: string; type: "CRE" | "DEB"; reason: string }, Invoice>(
+      "invoices",
+      "issueMemo",
+      ({ id, ...input }) => invoicesService.issueMemo(id, input),
+      undefined,
+      () => [QUERY_KEYS.INVOICES.ROOT],
+    ),
   },
 
   overview: {
diff --git a/apps/edr-freight-web/backoffice/src/services/eims.service.ts b/apps/edr-freight-web/backoffice/src/services/eims.service.ts
index 6f99aaa3f..610ed4920 100644
--- a/apps/edr-freight-web/backoffice/src/services/eims.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/eims.service.ts
@@ -1,6 +1,11 @@
 import { api as apiClient } from "@/auth/http";
 import { URL_CONSTANTS } from "@/constants/URLS";
-import type { EimsInvoiceStatusView, EimsVerifyResult } from "@/types/eims";
+import type {
+  EimsInvoiceStatusView,
+  EimsModeOfPayment,
+  EimsReceiptView,
+  EimsVerifyResult,
+} from "@/types/eims";
 
 /**
  * MoR EIMS filing actions on an invoice.
@@ -36,4 +41,45 @@ export const eimsService = {
       .post<EimsInvoiceStatusView>(URL_CONSTANTS.EIMS.RESOLVE(invoiceId), input)
       .then((r) => r.data);
   },
+
+  /** Cancel the invoice's registered EIMS document. Refuses (409) an already-cancelled one. */
+  cancel(
+    invoiceId: string,
+    input: { reasonCode: string; remark?: string },
+  ): Promise<EimsInvoiceStatusView> {
+    return apiClient
+      .post<EimsInvoiceStatusView>(URL_CONSTANTS.EIMS.CANCEL(invoiceId), input)
+      .then((r) => r.data);
+  },
+
+  registerSalesReceipt(
+    invoiceId: string,
+    input: { modeOfPayment: EimsModeOfPayment; reason?: string; collectedAmount?: number },
+  ): Promise<EimsReceiptView> {
+    return apiClient
+      .post<EimsReceiptView>(URL_CONSTANTS.EIMS.RECEIPT_SALES(invoiceId), input)
+      .then((r) => r.data);
+  },
+
+  registerWithholdingReceipt(
+    invoiceId: string,
+    input: { type: string; preTaxAmount: number; withholdingAmount: number; reason?: string },
+  ): Promise<EimsReceiptView> {
+    return apiClient
+      .post<EimsReceiptView>(URL_CONSTANTS.EIMS.RECEIPT_WITHHOLDING(invoiceId), input)
+      .then((r) => r.data);
+  },
+
+  listReceipts(invoiceId: string): Promise<EimsReceiptView[]> {
+    return apiClient
+      .get<EimsReceiptView[]>(URL_CONSTANTS.EIMS.RECEIPTS(invoiceId))
+      .then((r) => r.data);
+  },
+
+  /** Blob download — same pattern as `invoicesService.downloadDocument`. */
+  downloadReceiptDocument(invoiceId: string, receiptId: string) {
+    return apiClient.get<Blob>(URL_CONSTANTS.EIMS.RECEIPT_DOCUMENT(invoiceId, receiptId), {
+      responseType: "blob",
+    });
+  },
 };
diff --git a/apps/edr-freight-web/backoffice/src/services/invoices.service.ts b/apps/edr-freight-web/backoffice/src/services/invoices.service.ts
index 18febdf7b..145c0be4a 100644
--- a/apps/edr-freight-web/backoffice/src/services/invoices.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/invoices.service.ts
@@ -35,6 +35,16 @@ export const invoicesService = {
     });
   },
 
+  /** Issue a credit/debit memo against a registered invoice (MoR DEB/CRE) — filing-equivalent. */
+  issueMemo(
+    id: string,
+    input: { type: "CRE" | "DEB"; reason: string },
+  ): Promise<Invoice> {
+    return apiClient
+      .post<Invoice>(URL_CONSTANTS.BILLING.INVOICE_MEMO(id), input)
+      .then((r) => r.data);
+  },
+
   /** Finance worklist: USD invoices awaiting bank-transfer confirmation. */
   listOfflineUsd(
     filter: InvoiceListFilter,
diff --git a/apps/edr-freight-web/backoffice/src/types/eims.ts b/apps/edr-freight-web/backoffice/src/types/eims.ts
index c7c2e088f..bc2c10c17 100644
--- a/apps/edr-freight-web/backoffice/src/types/eims.ts
+++ b/apps/edr-freight-web/backoffice/src/types/eims.ts
@@ -65,3 +65,16 @@ export interface EimsVerifyResult {
     [section: string]: unknown;
   };
 }
+
+/** MoR `ModeOfPayment` enum — confirmed by a live schema error, verbatim spelling/casing. */
+export const EIMS_MODE_OF_PAYMENT = [
+  "CASH",
+  "CHEQUE",
+  "CPO",
+  "Local Bank Transfer",
+  "SWIFT",
+  "Wire Transfer",
+  "Letter of Credit",
+  "Card",
+] as const;
+export type EimsModeOfPayment = (typeof EIMS_MODE_OF_PAYMENT)[number];

From d40c340e1ce347caad77c9c50e607bfbba6e6af9 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Sat, 15 Aug 2026 08:05:58 +0000
Subject: [PATCH 111/174] feat(billing): 80mm thermal invoice layout (ADD-P001)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

GET billing/invoices/:id/document?format=thermal renders a dedicated 80mm
receipt template (72mm printable, 4mm margins each side), not a CSS variant
of the A4 layout — the A4 CSS is absolutely-positioned/fixed-px, tuned for a
210mm page, and doesn't reflow at thermal width. No seal (not a thermal
convention, renders badly on 1-bit thermal heads); line items stack
(description, then qty x rate = amount) instead of a table, since a real
table leaves ~10-14 chars for description at this width.

PdfRenderService gains a thermal render path: full 80mm-width viewport,
content height measured via page.evaluate after settle (continuous-roll
receipts have no fixed page length), and a noFallback option — a Chromium
failure throws a clear error instead of silently degrading to the generic
A4/no-QR fallback, which would hand back a different document than what was
asked for. The frontend surfaces that as a toast pointing at the existing A4
download.

format is strictly validated (a4|thermal only, BadRequestException
otherwise), not silently coerced.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../src/modules/billing/billing.controller.ts |  17 +-
 .../modules/billing/billing.service.spec.ts   |  25 ++-
 .../src/modules/billing/billing.service.ts    |  18 ++-
 .../invoice-document.service.spec.ts          |  43 +++++
 .../documents/invoice-document.service.ts     | 147 ++++++++++++++++--
 .../billing/documents/pdf-render.service.ts   |  81 +++++++++-
 .../src/pages/invoices/InvoiceDetailPage.tsx  |  65 ++++++--
 .../src/services/invoices.service.ts          |   4 +-
 8 files changed, 353 insertions(+), 47 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/billing/billing.controller.ts b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
index e65f301b2..02da40a4a 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.controller.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
@@ -1,4 +1,5 @@
 import {
+  BadRequestException,
   Body,
   Controller,
   Get,
@@ -113,9 +114,19 @@ export class BillingController {
 
   @Get("invoices/:id/document")
   @BookingStaff(FREIGHT_PERMS.invoices.export)
-  @ApiOperation({ summary: "Download the sealed invoice PDF" })
-  async document(@Param("id", ParseUUIDPipe) id: string, @Res() res: Response) {
-    const { filename, buffer } = await this.billingService.document(id);
+  @ApiOperation({
+    summary:
+      'Download the sealed invoice PDF. ?format=a4 (default) or ?format=thermal for the 80mm thermal layout (ADD-P001).',
+  })
+  async document(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Query("format") format: string | undefined,
+    @Res() res: Response,
+  ) {
+    if (format !== undefined && format !== "a4" && format !== "thermal") {
+      throw new BadRequestException(`Unsupported format "${format}" — use "a4" or "thermal".`);
+    }
+    const { filename, buffer } = await this.billingService.document(id, format === "thermal" ? "thermal" : "a4");
     sendPdf(res, filename, buffer);
   }
 
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index 7148fa987..243b1ee4d 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -927,6 +927,7 @@ describe("BillingService.document", () => {
 
   const build = (invoice: Record<string, unknown>) => {
     const render = jest.fn().mockResolvedValue({ filename: "x.pdf", buffer: Buffer.from("") });
+    const renderThermal = jest.fn().mockResolvedValue({ filename: "x-thermal.pdf", buffer: Buffer.from("") });
     const service = new BillingService(
       {} as never,
       { findById: jest.fn().mockResolvedValue(invoice) } as never,
@@ -934,7 +935,7 @@ describe("BillingService.document", () => {
       {} as never,
       {} as never,
       {} as never,
-      { render } as never,
+      { render, renderThermal } as never,
       {} as never,
       {
         get: (key: string) =>
@@ -943,7 +944,7 @@ describe("BillingService.document", () => {
             : undefined,
       } as never, // config
     );
-    return { service, render };
+    return { service, render, renderThermal };
   };
 
   it("adds no EIMS IRN row and no QR for an unregistered invoice", async () => {
@@ -1000,4 +1001,24 @@ describe("BillingService.document", () => {
     expect(model.summary).toContainEqual({ label: "EIMS IRN", value: "IRN-123" });
     expect(model.qrImageUrl).toBe("data:image/png;base64,signed-payload");
   });
+
+  it("calls render (not renderThermal) for the default format", async () => {
+    const { service, render, renderThermal } = build(invoiceRow());
+    jest.spyOn(service as never, "toDocumentModel").mockResolvedValue({} as never);
+
+    await service.document("inv-1");
+
+    expect(render).toHaveBeenCalledTimes(1);
+    expect(renderThermal).not.toHaveBeenCalled();
+  });
+
+  it("calls renderThermal (not render) for format 'thermal'", async () => {
+    const { service, render, renderThermal } = build(invoiceRow());
+    jest.spyOn(service as never, "toDocumentModel").mockResolvedValue({} as never);
+
+    await service.document("inv-1", "thermal");
+
+    expect(renderThermal).toHaveBeenCalledTimes(1);
+    expect(render).not.toHaveBeenCalled();
+  });
 });
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index a0f25f88b..49227efc9 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -411,12 +411,20 @@ export class BillingService {
 
   // ── Documents (central PDF) ──────────────────────────────────────────────────
 
-  /** Sealed PDF invoice for any source, rendered by the shared document service. */
-  async document(id: string): Promise<{ filename: string; buffer: Buffer }> {
+  /**
+   * Sealed PDF invoice for any source, rendered by the shared document service. `format`
+   * validation (rejecting anything but `"a4"`/`"thermal"`) is the controller's job — an input
+   * boundary check, not a business rule.
+   */
+  async document(
+    id: string,
+    format: "a4" | "thermal" = "a4",
+  ): Promise<{ filename: string; buffer: Buffer }> {
     const invoice = await this.findById(id);
-    return this.invoiceDocuments.render(
-      await this.toDocumentModel(invoice, "INVOICE"),
-    );
+    const model = await this.toDocumentModel(invoice, "INVOICE");
+    return format === "thermal"
+      ? this.invoiceDocuments.renderThermal(model)
+      : this.invoiceDocuments.render(model);
   }
 
   /** Sealed PDF receipt; available once any payment has been recorded. */
diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
index bc5250888..ebdf51be1 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
@@ -44,3 +44,46 @@ describe("InvoiceDocumentService.buildHtml — EIMS QR", () => {
     );
   });
 });
+
+describe("InvoiceDocumentService.buildThermalHtml", () => {
+  const service = new InvoiceDocumentService({} as never, {} as never, {} as never);
+
+  it("renders no seal markup at all — dropped for thermal, not shrunk", () => {
+    const html = service.buildThermalHtml(model());
+    expect(html).not.toContain('class="seal"');
+    expect(html).not.toContain("seal-image");
+  });
+
+  it("renders the QR image when qrImageUrl is set, centered rather than absolutely positioned", () => {
+    const html = service.buildThermalHtml(model({ qrImageUrl: "data:image/png;base64,QR" }));
+    expect(html).toContain('class="qr"');
+    expect(html).toContain('src="data:image/png;base64,QR"');
+    expect(html).not.toContain("position: absolute");
+  });
+
+  it("wraps a long IRN summary value rather than truncating it", () => {
+    const irn = "9fe9bbbece6ab76c112b617534e6aac7aa8b819d5be79f4d3d088ed2e887b2e0";
+    const html = service.buildThermalHtml(model({ summary: [{ label: "EIMS IRN", value: irn }] }));
+    expect(html).toContain(irn);
+    expect(html).toContain("overflow-wrap: anywhere");
+  });
+
+  it("renders a line item as stacked description + qty x rate = amount, not a table row", () => {
+    const html = service.buildThermalHtml(
+      model({
+        lines: [{ description: "40ft container rail freight", quantity: 12, unitRate: 245683.95, amount: 2948207.4 }],
+      }),
+    );
+    expect(html).not.toContain("<table");
+    expect(html).not.toContain("<td");
+    expect(html).toContain("40ft container rail freight");
+    expect(html).toContain("12 x");
+    expect(html).toContain("2,948,207.4 Birr (ETB)");
+  });
+
+  it("uses fluid, full-width layout — no fixed-px A4 geometry", () => {
+    const html = service.buildThermalHtml(model());
+    expect(html).not.toContain("width: 330px");
+    expect(html).not.toContain("right: 160px");
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
index 2d5e97e92..0f8e4ee71 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
@@ -27,6 +27,27 @@ export type InvoiceDocumentKind = "INVOICE" | "RECEIPT";
  */
 export const pngDataUrl = (base64: string): string => `data:image/png;base64,${base64}`;
 
+// ── Shared HTML-builder helpers (buildHtml + buildThermalHtml) ──────────────────────────────────
+// `buildFallbackPdf`'s own currency/money/date closures are a deliberately different, already-
+// established convention (bare "ETB" vs "Birr (ETB)") for the vector renderer — not touched here.
+
+function esc(value: unknown): string {
+  return String(value ?? "-")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function money(amount: unknown, currency: string): string {
+  return `${Number(amount ?? 0).toLocaleString()} ${currency === "ETB" ? "Birr (ETB)" : currency}`;
+}
+
+function formatDate(value: unknown): string {
+  return value ? new Date(value as string | Date).toLocaleDateString("en-GB") : "-";
+}
+
 /** One billed line on the document (charge type / fee type agnostic). */
 export interface InvoiceDocumentLine {
   description: string | null;
@@ -129,6 +150,117 @@ export class InvoiceDocumentService {
     };
   }
 
+  /**
+   * 80mm thermal invoice (ADD-P001) — physical page is the 80mm roll width; content stays within
+   * `THERMAL_MARGIN_MM` of each edge via `PdfRenderService`'s margin, not a narrower page, since
+   * thermal print mechanisms have a dead zone at the roll edge they can't reach either way.
+   *
+   * A genuinely different template from `buildHtml`, not a CSS variant of it: the A4 layout is
+   * absolutely-positioned and fixed-px (`.seal{right:28px}`, `.qr{right:160px}`,
+   * `.totals{width:330px}`), tuned for a 210mm page — none of it reflows at 72mm printable width.
+   * No seal here at all (a decorative wet-ink-style stamp is an A4/laser convention; no real POS
+   * thermal receipt carries one, and thermal heads render rotated circles badly) and line items
+   * are stacked (description, then `qty x rate = amount` below it) rather than a table — a real
+   * multi-column table leaves ~10-14 chars for description at this width, truncating almost every
+   * line, which stacking avoids entirely. No Chromium-less fallback — see `renderThermal`.
+   */
+  async renderThermal(model: InvoiceDocumentModel): Promise<{ filename: string; buffer: Buffer }> {
+    const logoImageUrl =
+      model.logoImageUrl !== undefined ? model.logoImageUrl : await this.logoSettings.getLogoImageUrl();
+    // Seal deliberately dropped — never fetched, so no stampSettings call either.
+    const resolvedModel: InvoiceDocumentModel = { ...model, logoImageUrl, stampImageUrl: null };
+
+    const html = this.buildThermalHtml(resolvedModel);
+    return {
+      filename: `${this.safeFilename(model.documentNumber)}-thermal.pdf`,
+      buffer: await this.pdf.htmlToPdfBuffer(html, {
+        label: `${model.title} thermal invoice`,
+        thermal: true,
+        // A generic A4-shaped, QR-less fallback is not an acceptable stand-in for "the thermal
+        // printer output" — fail loudly instead; the caller has the A4 download to fall back to.
+        noFallback: true,
+      }),
+    };
+  }
+
+  buildThermalHtml(model: InvoiceDocumentModel): string {
+    const heading = `${model.title} ${model.kind === "RECEIPT" ? "Receipt" : "Invoice"}`;
+    const logoInner = logoMarkup(model.logoImageUrl, "thermal-logo");
+
+    const summaryRows = model.summary
+      .map(
+        (row) =>
+          `<div class="row"><span class="label">${esc(row.label)}</span><span class="value">${esc(row.value)}</span></div>`,
+      )
+      .join("");
+
+    const itemBlocks = model.lines
+      .map((item) => {
+        const currency = item.currency ?? model.currency;
+        return `<div class="item">
+        <div class="item-desc">${esc(item.description)}</div>
+        <div class="item-calc">${esc(item.quantity ?? 0)} x ${esc(money(item.unitRate, currency))} = <strong>${esc(money(item.amount, currency))}</strong></div>
+      </div>`;
+      })
+      .join("");
+
+    const totalRows = model.totals
+      .map(
+        (total) =>
+          `<div class="total-row${total.grand ? " grand" : ""}"><span>${esc(total.label)}</span><strong>${esc(money(total.amount, model.currency))}</strong></div>`,
+      )
+      .join("");
+
+    const qrMarkup = model.qrImageUrl
+      ? `<div class="qr"><img src="${esc(model.qrImageUrl)}" alt="EIMS verification QR" /><div class="qr-caption">Scan to verify (MoR EIMS)</div></div>`
+      : "";
+
+    return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>${esc(heading)}</title>
+  <style>
+    body { font-family: Arial, sans-serif; font-size: 9px; color: #0f172a; margin: 0; }
+    .doc { width: 100%; box-sizing: border-box; }
+    .thermal-logo { display: block; max-height: 28px; max-width: 100%; object-fit: contain; margin: 0 auto 4px; }
+    .brand { text-align: center; font-size: 9px; text-transform: uppercase; letter-spacing: .05em; }
+    .title { text-align: center; font-size: 13px; font-weight: 800; margin: 2px 0; }
+    .meta { text-align: center; font-size: 8px; color: #475569; margin-bottom: 4px; }
+    .rule { border-top: 1px dashed #334155; margin: 6px 0; }
+    .row { display: flex; justify-content: space-between; gap: 6px; font-family: monospace; font-size: 8.5px; padding: 1px 0; }
+    .row .label { color: #64748b; white-space: nowrap; }
+    .row .value { text-align: right; overflow-wrap: anywhere; }
+    .item { margin: 4px 0; }
+    .item-desc { font-size: 9px; overflow-wrap: anywhere; }
+    .item-calc { text-align: right; font-family: monospace; font-size: 8.5px; }
+    .total-row { display: flex; justify-content: space-between; font-size: 9px; padding: 2px 0; }
+    .total-row.grand { font-size: 11px; font-weight: 800; border-top: 1px solid #0f172a; margin-top: 3px; padding-top: 4px; }
+    .qr { text-align: center; margin: 8px 0; }
+    .qr img { width: 150px; height: 150px; }
+    .qr-caption { font-size: 7px; color: #64748b; margin-top: 2px; }
+    .footer { text-align: center; font-size: 7px; color: #94a3b8; margin-top: 8px; }
+  </style>
+</head>
+<body>
+  <div class="doc">
+    ${logoInner}
+    <div class="brand">Ethio-Djibouti Railway S.C.</div>
+    <div class="title">${esc(heading)}</div>
+    <div class="meta">${esc(model.documentNumber)} &middot; ${esc(formatDate(model.issuedAt))}</div>
+    <div class="rule"></div>
+    ${summaryRows}
+    <div class="rule"></div>
+    ${itemBlocks}
+    <div class="rule"></div>
+    ${totalRows}
+    ${qrMarkup}
+    <div class="footer">Thank you</div>
+  </div>
+</body>
+</html>`;
+  }
+
   /**
    * Vector-drawn styled invoice/receipt used when headless Chromium is
    * unavailable. Mirrors the HTML layout closely enough to pass as the same
@@ -250,18 +382,7 @@ export class InvoiceDocumentService {
   }
 
   buildHtml(model: InvoiceDocumentModel): string {
-    const esc = (value: unknown) =>
-      String(value ?? "-")
-        .replace(/&/g, "&amp;")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;")
-        .replace(/'/g, "&#39;");
-    const money = (amount: unknown, currency = model.currency) =>
-      `${Number(amount ?? 0).toLocaleString()} ${currency === "ETB" ? "Birr (ETB)" : currency}`;
-    const date = (value: unknown) =>
-      value ? new Date(value as string | Date).toLocaleDateString("en-GB") : "-";
-
+    const date = formatDate;
     const showCategory = Boolean(model.categoryHeader);
     const sealText =
       model.sealText ?? (model.kind === "RECEIPT" || model.status === "PAID" ? "EDR PAID" : "EDR");
@@ -292,7 +413,7 @@ export class InvoiceDocumentService {
     const totalRows = model.totals
       .map(
         (total) =>
-          `<div class="total-row${total.grand ? " grand" : ""}"><span>${esc(total.label)}</span><strong>${esc(money(total.amount))}</strong></div>`,
+          `<div class="total-row${total.grand ? " grand" : ""}"><span>${esc(total.label)}</span><strong>${esc(money(total.amount, model.currency))}</strong></div>`,
       )
       .join("");
 
diff --git a/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts b/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts
index e8c3de792..21676c160 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts
@@ -15,15 +15,43 @@ const PDF_PRINT_STYLES = `
   }
 </style>`;
 
+/**
+ * Physical roll width. Content stays within `THERMAL_MARGIN_MM` of each edge — every mainstream
+ * ESC/POS thermal head (Epson TM-T88, Star, Bixolon) has a dead zone near the edge of an 80mm roll
+ * it physically can't reach, so the page itself must stay 80mm (matching the roll the printer
+ * driver expects) with the safe area carved out by margin, not by shrinking the page.
+ */
+const THERMAL_PAGE_WIDTH_MM = 80;
+const THERMAL_MARGIN_MM = 4;
+/** Extra length past the measured content, so the cut isn't flush against the last line. */
+const THERMAL_FEED_MM = 6;
+/** Guard against a runaway line-item list producing an absurd page. */
+const THERMAL_MAX_HEIGHT_MM = 1500;
+
 export interface PdfRenderOptions {
   /** Label used in logs to identify the document kind. */
   label?: string;
   /** Landscape A4 instead of the default portrait — wide tables need it. */
   landscape?: boolean;
+  /**
+   * Render as an 80mm continuous thermal receipt instead of a fixed A4 page: content width is
+   * measured and the page height grows to fit it, rather than a fixed page with the format's
+   * `format: "A4"`.
+   */
+  thermal?: boolean;
+  /**
+   * Refuse to degrade to a fallback PDF on failure — throw instead. For a thermal request, a
+   * generic A4-shaped, QR-less fallback is not an acceptable stand-in for "the thermal printer
+   * output" (it silently hands back a different document shape than what was asked for); the
+   * caller has an existing A4 download to point the user at instead. Ignored when `fallback` is
+   * also supplied — an explicit fallback always wins.
+   */
+  noFallback?: boolean;
   /**
    * Degraded renderer used when Chromium is unavailable. Receives the
    * print-prepared HTML and must return a valid PDF buffer (≥ 2KB, `%PDF-`
-   * header). When omitted, a generic single-page fallback is produced.
+   * header). When omitted (and `noFallback` is not set), a generic single-page fallback is
+   * produced.
    */
   fallback?: (preparedHtml: string) => Buffer;
 }
@@ -54,17 +82,31 @@ export class PdfRenderService {
       const browser = await puppeteer.default.launch(launchOptions);
       try {
         const page = await browser.newPage();
-        await page.setViewport({ width: 794, height: 1123, deviceScaleFactor: 1 });
+        const thermal = opts.thermal ?? false;
+        const viewportWidth = thermal ? Math.round((THERMAL_PAGE_WIDTH_MM / 25.4) * 96) : 794;
+        await page.setViewport({ width: viewportWidth, height: 1123, deviceScaleFactor: 1 });
         await page.setContent(preparedHtml, { waitUntil: "load", timeout: 60_000 });
         await page.emulateMediaType("print");
         await new Promise((resolve) => setTimeout(resolve, 250));
 
-        const pdf = await page.pdf({
-          format: "A4",
-          landscape: opts.landscape ?? false,
-          printBackground: true,
-          margin: { top: "16mm", bottom: "18mm", left: "14mm", right: "14mm" },
-        });
+        const pdf = thermal
+          ? await page.pdf({
+              width: `${THERMAL_PAGE_WIDTH_MM}mm`,
+              height: `${await this.thermalContentHeightMm(page)}mm`,
+              printBackground: true,
+              margin: {
+                top: `${THERMAL_MARGIN_MM}mm`,
+                bottom: `${THERMAL_MARGIN_MM + THERMAL_FEED_MM}mm`,
+                left: `${THERMAL_MARGIN_MM}mm`,
+                right: `${THERMAL_MARGIN_MM}mm`,
+              },
+            })
+          : await page.pdf({
+              format: "A4",
+              landscape: opts.landscape ?? false,
+              printBackground: true,
+              margin: { top: "16mm", bottom: "18mm", left: "14mm", right: "14mm" },
+            });
 
         const buffer = Buffer.from(pdf);
         if (!this.isValidPdf(buffer)) {
@@ -79,6 +121,15 @@ export class PdfRenderService {
       }
     } catch (error) {
       this.logger.error(`${label} PDF failed (executable=${executablePath ?? "default"}): ${error}`);
+      if (!opts.fallback && opts.noFallback) {
+        // A generic A4-shaped, QR-less fallback is not an acceptable stand-in for "the thermal
+        // printer output" — it silently hands back a different document than what was asked for.
+        // Fail loudly instead; the caller already has a working A4 download to fall back to.
+        throw new InternalServerErrorException(
+          `${label} could not be generated — thermal rendering requires Chromium. ` +
+            "Ensure Chromium is installed or set PUPPETEER_EXECUTABLE_PATH, or download the A4 PDF instead.",
+        );
+      }
       const fallback = (opts.fallback ?? ((h) => this.genericFallbackPdf(h)))(preparedHtml);
       if (this.isValidPdf(fallback)) {
         this.logger.warn(
@@ -92,6 +143,20 @@ export class PdfRenderService {
     }
   }
 
+  /**
+   * Thermal receipts are continuous-roll — there is no fixed page height. Measures the rendered
+   * content's actual height and adds feed clearance, so the PDF page is exactly as long as the
+   * receipt, not a fixed A4-length page with blank space at the bottom.
+   */
+  private async thermalContentHeightMm(page: import("puppeteer").Page): Promise<number> {
+    // String form, not a typed closure: this project's tsconfig has no `dom` lib, so `document`
+    // isn't a known global to type-check against — the string is evaluated in the page's own
+    // browser context regardless, same as the closure form would be.
+    const scrollPx = (await page.evaluate("document.documentElement.scrollHeight")) as number;
+    const contentMm = (scrollPx / 96) * 25.4 + THERMAL_MARGIN_MM * 2 + THERMAL_FEED_MM;
+    return Math.min(THERMAL_MAX_HEIGHT_MM, contentMm);
+  }
+
   private injectPdfPrintStyles(html: string): string {
     if (html.includes("edr-pdf-print-fix")) return html;
     if (html.includes("</head>")) {
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoiceDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoiceDetailPage.tsx
index ef7f9d086..18161d960 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoiceDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoiceDetailPage.tsx
@@ -8,16 +8,18 @@ import {
   Grid,
   Group,
   Loader,
+  Menu,
   SimpleGrid,
   Stack,
   Table,
   Text,
 } from "@mantine/core";
 import { useQuery } from "@tanstack/react-query";
-import { ArrowLeft, Building2, Download, FileText } from "lucide-react";
+import { ArrowLeft, Building2, Download, FileText, Printer } from "lucide-react";
 import { useAuth } from "@/auth/useAuth";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import { EimsFilingCard } from "@/components/invoices/EimsFilingCard";
+import { useToast } from "@/hooks/use-toast";
 import { useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
 
@@ -145,6 +147,7 @@ export default function InvoiceDetailPage() {
   const canExport = hasPermission(user, FREIGHT_PERMS.invoices.export);
   const { id } = useParams<{ id: string }>();
   const navigate = useNavigate();
+  const { toast } = useToast();
   const [downloading, setDownloading] = useState(false);
 
   const { data: invoice, isLoading } = useQuery(
@@ -154,12 +157,27 @@ export default function InvoiceDetailPage() {
     }),
   );
 
-  const downloadDocument = async () => {
+  const downloadDocument = async (format?: "a4" | "thermal") => {
     if (!id) return;
     setDownloading(true);
     try {
-      const { data } = await invoicesService.downloadDocument(id);
-      openPdfBlob(data, `${invoice?.invoiceNumber ?? "invoice"}.pdf`);
+      const { data } = await invoicesService.downloadDocument(id, format);
+      const suffix = format === "thermal" ? "-thermal" : "";
+      openPdfBlob(data, `${invoice?.invoiceNumber ?? "invoice"}${suffix}.pdf`);
+    } catch (error) {
+      // Thermal rendering deliberately fails loudly rather than silently returning an A4-shaped,
+      // QR-less document (see PdfRenderService's `noFallback`) — surface that here rather than
+      // let it become a silent unhandled rejection with just a spinner stopping.
+      toast({
+        title: format === "thermal" ? "Could not generate the thermal invoice" : "Could not download the invoice",
+        description:
+          format === "thermal"
+            ? "Thermal rendering requires Chromium on the server. The A4 PDF is still available."
+            : error instanceof Error
+              ? error.message
+              : undefined,
+        variant: "destructive",
+      });
     } finally {
       setDownloading(false);
     }
@@ -202,17 +220,34 @@ export default function InvoiceDetailPage() {
         subtitle={humanize(invoice.source)}
         meta={<InvoiceStatusBadge status={invoice.status} />}
         action={
-          <ActionIcon
-            variant="default"
-            size="lg"
-            radius="md"
-            aria-label="Download invoice"
-            disabled={!canExport}
-            loading={downloading}
-            onClick={() => void downloadDocument()}
-          >
-            <Download size={16} />
-          </ActionIcon>
+          <Menu position="bottom-end" withinPortal>
+            <Menu.Target>
+              <ActionIcon
+                variant="default"
+                size="lg"
+                radius="md"
+                aria-label="Download invoice"
+                disabled={!canExport}
+                loading={downloading}
+              >
+                <Download size={16} />
+              </ActionIcon>
+            </Menu.Target>
+            <Menu.Dropdown>
+              <Menu.Item
+                leftSection={<Download size={14} />}
+                onClick={() => void downloadDocument("a4")}
+              >
+                Download PDF (A4)
+              </Menu.Item>
+              <Menu.Item
+                leftSection={<Printer size={14} />}
+                onClick={() => void downloadDocument("thermal")}
+              >
+                Download thermal invoice (80mm)
+              </Menu.Item>
+            </Menu.Dropdown>
+          </Menu>
         }
       />
 
diff --git a/apps/edr-freight-web/backoffice/src/services/invoices.service.ts b/apps/edr-freight-web/backoffice/src/services/invoices.service.ts
index 145c0be4a..8c45bf9a3 100644
--- a/apps/edr-freight-web/backoffice/src/services/invoices.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/invoices.service.ts
@@ -29,9 +29,11 @@ export const invoicesService = {
       .then((r) => r.data);
   },
 
-  downloadDocument(id: string) {
+  /** `format` omitted or "a4" → standard A4 PDF; "thermal" → 80mm thermal layout (ADD-P001). */
+  downloadDocument(id: string, format?: "a4" | "thermal") {
     return apiClient.get<Blob>(URL_CONSTANTS.BILLING.INVOICE_DOCUMENT(id), {
       responseType: "blob",
+      params: format ? { format } : undefined,
     });
   },
 

From 8ba8376f45f0e035ab5618b07c4f6da5f1191870 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 15 Aug 2026 08:39:59 +0000
Subject: [PATCH 112/174] feat(filters): migrate FleetResourcePage to the pill
 filter bar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The real live fleet page — FleetCrudPages.tsx (previous commit) turned
out to be dead code; every fleet route (locomotives/trains/wagons/
containers/cargoes/vehicles/drivers) actually renders this one,
config-driven off resources.ts. Highest-leverage single file in the
remaining inventory: 7 routes at once.

- filterDefs are built per slug from `config.listFilters` (status/yard/
  wagon type/train…, wired to real server params via each def's
  default `{key: value}` toParams) plus a "Registered" date range. The
  3 slugs with no server list filters (trains/containers/cargoes) fall
  back to a plain client-only Status filter off a fixed enum, not
  "whatever status exists in the currently-loaded rows" — the latter
  would be circular (filterDefs feeds useFilters, which feeds the
  query that produces those rows).
- serverListFilters/pagedFilters derive straight from `controls.params`
  instead of hand-picking each field off local state — the def keys
  already match the API's param names, so this is mostly free.
- filteredRows keeps the original's exact "usesServerListFilters ⇒
  trust the server, don't re-check client-side" short-circuit — some
  server list filters (a wagon's `trainNumber` matches either of two
  different columns) aren't expressible as a plain client-side field
  equality, and re-applying them would silently break.
- Pagination moved from a local `usePagination()` (component state) to
  useFilters' URL-backed page/pageSize — the whole point of this pass.
  DataTable takes `controls.tableProps(total)` directly; FleetCardGrid
  (not a DataTable) is fed the same pieces by hand.
- The two manual "reset on slug/filter change" effects are dropped —
  a same-app nav Link to a bare path already clears the query string,
  and useFilters already deletes `page` on every filter/search change.
- FleetToolbar's view-mode SegmentedControl moves into FilterBar's
  `children` slot; its search/filters props are no longer used here.
---
 .../src/pages/fleet/FleetResourcePage.tsx     | 399 ++++++++----------
 1 file changed, 168 insertions(+), 231 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx b/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
index d837ee712..23dc6b76b 100644
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
@@ -1,7 +1,5 @@
 import type { ColumnDef } from "@edr/ui-common";
-import { Box, Button, Card, Container, Group, Modal, Select, Stack, Text, TextInput, Title } from "@mantine/core";
-import { DatePickerInput } from "@mantine/dates";
-import { getDateRangePresets } from "@/components/common/dateRangePresets";
+import { Box, Button, Card, Container, Group, Modal, SegmentedControl, Select, Stack, Text, TextInput, Title } from "@mantine/core";
 import { keepPreviousData, useMutation, useQuery } from "@tanstack/react-query";
 
 import { api } from "@/services/api";
@@ -13,7 +11,7 @@ import {
   FREIGHT_PERMS,
 } from "@/lib/permissions";
 import Breadcrumbs from "@/components/ui/Breadcrumbs";
-import { Inbox, Plus, Warehouse } from "lucide-react";
+import { Inbox, LayoutGrid, Plus, Table2, Warehouse } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
 import { Link, Navigate, useLocation } from "react-router-dom";
 
@@ -21,13 +19,12 @@ import FleetCardGrid from "@/components/fleet/FleetCardGrid";
 import FleetFormDialog from "@/components/fleet/FleetFormDialog";
 import FleetHistoryModal from "@/components/fleet/FleetHistoryModal";
 import FleetRecordActions from "@/components/fleet/FleetRecordActions";
-import FleetToolbar from "@/components/fleet/FleetToolbar";
 import { matchesDayRange } from "@/hooks/useListControls";
 import WagonMovementHistoryModal from "@/components/fleet/WagonMovementHistoryModal";
 import WagonStatusActions from "@/components/wagons/WagonStatusActions";
 import WagonYardWorkspaceModal from "@/components/wagons/WagonYardWorkspaceModal";
 import { formatFleetCell, registerFleetOptionLabels } from "@/components/fleet/fleetFormat";
-import { useFleetViewMode } from "@/components/fleet/useFleetViewMode";
+import { useFleetViewMode, type FleetViewMode } from "@/components/fleet/useFleetViewMode";
 import { ruleEngineTable } from "@/components/ruleEngine/ruleEngineStyles";
 import { useToast } from "@/hooks/use-toast";
 import {
@@ -43,11 +40,46 @@ import {
   type FleetListFilters,
   type FleetRecord,
 } from "@/services/fleet/fleet.service";
-import { DataTable, DataTableFooter, usePagination } from "@edr/ui-common";
-import { useDebouncedValue } from "@mantine/hooks";
+import { DataTable, DataTableFooter } from "@edr/ui-common";
+import { dateRangeParams, FilterBar, useFilters, type FilterDef, type FilterOption } from "@/components/filters";
 
 const DEFAULT_SLUG: FleetResourceSlug = "locomotives";
 
+const SERVER_FILTERED_SLUGS: FleetResourceSlug[] = ["wagons", "locomotives", "vehicles", "drivers"];
+
+// trains/containers/cargoes have no server-side `listFilters` config (see
+// resources.ts) — they get a plain client-only Status filter instead, off a
+// fixed enum rather than "whatever status happens to exist in the currently
+// loaded rows" (which would create a circular dependency: filterDefs feeds
+// useFilters, which feeds the query that produces those rows).
+const TRAIN_STATUS_OPTIONS: FilterOption[] = [
+  { value: "AVAILABLE", label: "Available" },
+  { value: "SCHEDULED", label: "Scheduled" },
+  { value: "IN_SERVICE", label: "In service" },
+  { value: "UNDER_MAINTENANCE", label: "Under maintenance" },
+  { value: "OUT_OF_SERVICE", label: "Out of service" },
+  { value: "DEACTIVATED", label: "Deactivated" },
+];
+const CONTAINER_STATUS_OPTIONS: FilterOption[] = [
+  { value: "AVAILABLE", label: "Available" },
+  { value: "LOADED", label: "Loaded" },
+  { value: "IN_TRANSIT", label: "In transit" },
+  { value: "MAINTENANCE", label: "Maintenance" },
+  { value: "DAMAGED", label: "Damaged" },
+];
+const CARGO_STATUS_OPTIONS: FilterOption[] = [
+  { value: "PENDING", label: "Pending" },
+  { value: "LOADED", label: "Loaded" },
+  { value: "IN_TRANSIT", label: "In transit" },
+  { value: "DELIVERED", label: "Delivered" },
+  { value: "UNLOADED", label: "Unloaded" },
+];
+const FALLBACK_STATUS_OPTIONS: Partial<Record<FleetResourceSlug, FilterOption[]>> = {
+  trains: TRAIN_STATUS_OPTIONS,
+  containers: CONTAINER_STATUS_OPTIONS,
+  cargoes: CARGO_STATUS_OPTIONS,
+};
+
 const FleetResourcePage = () => {
   const location = useLocation();
   const slug = getFleetSlugFromPath(location.pathname) ?? DEFAULT_SLUG;
@@ -70,18 +102,9 @@ const FleetResourcePage = () => {
     hasPermission(user, FREIGHT_PERMS.wagons.transferFulfill) ||
     hasPermission(user, FREIGHT_PERMS.wagons.transferHistoryAll);
 
-  const { pagination, setPagination } = usePagination({ pageSize: 10 });
-  const [search, setSearch] = useState("");
-  const [debouncedSearch] = useDebouncedValue(search, 300);
   // Wagons and locomotives page in the database; the rest still list in full
   // and page in the browser (see `pagedHandlers` in fleet.service).
   const serverPaged = isFleetServerPaginated(slug);
-  const [statusFilter, setStatusFilter] = useState("ALL");
-  // Registration date range. Server-side list filters (status/yard/train) are
-  // applied by the API; this narrows what comes back, alongside search.
-  const [dateFrom, setDateFrom] = useState<string | null>(null);
-  const [dateTo, setDateTo] = useState<string | null>(null);
-  const [listFilterValues, setListFilterValues] = useState<Record<string, string>>({});
   const [formOpen, setFormOpen] = useState(false);
   const [editing, setEditing] = useState<FleetRecord | null>(null);
   const [removeTarget, setRemoveTarget] = useState<FleetRecord | null>(null);
@@ -95,77 +118,6 @@ const FleetResourcePage = () => {
   const [wagonWorkspaceOpen, setWagonWorkspaceOpen] = useState(false);
   const { viewMode, setViewMode } = useFleetViewMode(slug);
 
-  const serverListFilters = useMemo((): FleetListFilters | undefined => {
-    const serverFilteredSlugs: FleetResourceSlug[] = ["wagons", "locomotives", "vehicles", "drivers"];
-    if (!serverFilteredSlugs.includes(slug)) return undefined;
-    const filters: FleetListFilters = {};
-    const status = listFilterValues.status;
-    const currentYardId = listFilterValues.currentYardId;
-    const availability = listFilterValues.availability;
-    const trainNumber = listFilterValues.trainNumber;
-    const trainId = listFilterValues.trainId;
-    if (status && status !== "ALL") {
-      (filters as { status?: string }).status = status;
-    }
-    if (currentYardId && currentYardId !== "ALL") {
-      filters.currentYardId = currentYardId;
-    }
-    if (availability && availability !== "ALL") {
-      (filters as { availability?: string }).availability = availability;
-    }
-    if (trainNumber && trainNumber !== "ALL") {
-      (filters as { trainNumber?: string }).trainNumber = trainNumber;
-    }
-    if (trainId && trainId !== "ALL") {
-      filters.trainId = trainId;
-    }
-    // Wagons only: narrow the fleet to one wagon type (the API filters on it).
-    const wagonTypeId = listFilterValues.wagonTypeId;
-    if (wagonTypeId && wagonTypeId !== "ALL") {
-      (filters as { wagonTypeId?: string }).wagonTypeId = wagonTypeId;
-    }
-    // The plain locomotives list has no server-side search — its page window
-    // does, so the term is only sent on the paginated path.
-    if ((serverPaged || slug !== "locomotives") && debouncedSearch.trim()) {
-      filters.search = debouncedSearch.trim();
-    }
-    return filters;
-  }, [slug, listFilterValues, debouncedSearch, serverPaged]);
-
-  // On the server-paged path the page window, the search and the registration
-  // date range are all resolved by the API — nothing is filtered client-side.
-  const pagedFilters = useMemo(
-    (): FleetListFilters => ({
-      ...serverListFilters,
-      page: pagination.pageIndex + 1,
-      pageSize: pagination.pageSize,
-      ...(dateFrom ? { createdFrom: dateFrom } : {}),
-      ...(dateTo ? { createdTo: dateTo } : {}),
-    }),
-    [serverListFilters, pagination.pageIndex, pagination.pageSize, dateFrom, dateTo],
-  );
-
-  const listQuery = useQuery({
-    ...api.fleet.list.queryOptions({ input: { slug, filters: serverListFilters } }),
-    enabled: !serverPaged,
-  });
-  const pagedQuery = useQuery({
-    ...api.fleet.listPaged.queryOptions({ input: { slug, filters: pagedFilters } }),
-    enabled: serverPaged,
-    placeholderData: keepPreviousData,
-  });
-
-  const activeQuery = serverPaged ? pagedQuery : listQuery;
-  const { isLoading, isError, error } = activeQuery;
-  const allRows = useMemo(
-    () => (serverPaged ? (pagedQuery.data?.items ?? []) : (listQuery.data ?? [])),
-    [serverPaged, pagedQuery.data, listQuery.data],
-  );
-  const create = useMutation(api.fleet.create.mutationOptions());
-  const update = useMutation(api.fleet.update.mutationOptions());
-  const remove = useMutation(api.fleet.remove.mutationOptions());
-  const purge = useMutation(api.fleet.purge.mutationOptions());
-
   const { data: wagonTypes = [], isLoading: wagonTypesLoading } = useQuery(
     api.wagonTypes.list.queryOptions(),
   );
@@ -202,40 +154,8 @@ const FleetResourcePage = () => {
     enabled: slug === "wagons",
   });
 
-  useEffect(() => {
-    setPagination((prev) => ({ pageIndex: 0, pageSize: prev.pageSize }));
-    setSearch("");
-    setStatusFilter("ALL");
-    setListFilterValues({});
-  }, [slug, setPagination]);
-
-  useEffect(() => {
-    setPagination((prev) => ({ pageIndex: 0, pageSize: prev.pageSize }));
-  }, [search, listFilterValues, dateFrom, dateTo, setPagination]);
-
-  const hasStatusColumn = Boolean(config?.columns.some((col) => col.accessorKey === "status"));
   const usesServerListFilters = Boolean(config?.listFilters?.length);
 
-  const statusFilterOptions = useMemo(() => {
-    if (!hasStatusColumn || usesServerListFilters) return [];
-    if (slug === "vehicles" || slug === "drivers") {
-      return [
-        { value: "ALL", label: "All statuses" },
-        { value: "ACTIVE", label: "Active" },
-        { value: "INACTIVE", label: "Inactive" },
-      ];
-    }
-    const statuses = new Set(
-      allRows
-        .map((row) => String((row as unknown as Record<string, unknown>).status ?? ""))
-        .filter(Boolean),
-    );
-    return [
-      { value: "ALL", label: "All statuses" },
-      ...[...statuses].sort().map((status) => ({ value: status, label: status })),
-    ];
-  }, [allRows, hasStatusColumn, usesServerListFilters, slug]);
-
   const dynamicOptions = useMemo(() => {
     const wagonTypeOpts = (wagonTypes as Array<{ id: string; code: string; name?: string }>).map(
       (t) => ({ value: t.id, label: `${t.code}${t.name ? ` - ${t.name}` : ""}` }),
@@ -291,25 +211,78 @@ const FleetResourcePage = () => {
     };
   }, [wagonTypes, containerTypes, cargoTypes, truckTypes, wagons, containers, yards, trains]);
 
-  const listFilterSelects = useMemo(() => {
-    if (!config?.listFilters?.length) return null;
-    return config.listFilters.map((filter) => {
-      const dynamicOpts = filter.dynamicOptions
-        ? (dynamicOptions[filter.dynamicOptions] ?? [])
-        : [];
-      const staticOpts =
-        filter.options?.map((opt) => ({ value: opt.value, label: opt.label })) ?? [];
-      const opts = filter.dynamicOptions ? dynamicOpts : staticOpts;
-      return {
-        ...filter,
-        value: listFilterValues[filter.key] ?? "ALL",
-        data: [
-          { value: "ALL", label: filter.allLabel ?? `All ${filter.label.toLowerCase()}` },
-          ...opts,
-        ],
-      };
-    });
-  }, [config?.listFilters, listFilterValues, dynamicOptions]);
+  // One pill per configured server list filter (status/yard/wagon type/train…),
+  // built off `config.listFilters` — same source the old plain `<Select>` row
+  // read, just reshaped into FilterDefs. Falls back to a plain client-only
+  // Status filter for the 3 slugs with no server-side list filters at all.
+  const filterDefs: FilterDef[] = useMemo(() => {
+    const dateDef: FilterDef = {
+      key: "created",
+      label: "Registered",
+      type: "date",
+      secondary: true,
+      toParams: dateRangeParams("createdFrom", "createdTo"),
+    };
+    if (config?.listFilters?.length) {
+      return [
+        ...config.listFilters.map((filter): FilterDef => ({
+          key: filter.key,
+          label: filter.label,
+          type: "enum",
+          multiple: false,
+          options: filter.dynamicOptions
+            ? (dynamicOptions[filter.dynamicOptions] ?? [])
+            : (filter.options ?? []),
+        })),
+        dateDef,
+      ];
+    }
+    const fallback = FALLBACK_STATUS_OPTIONS[slug];
+    return fallback
+      ? [{ key: "status", label: "Status", type: "enum", multiple: false, options: fallback }, dateDef]
+      : [dateDef];
+  }, [config, dynamicOptions, slug]);
+
+  const controls = useFilters(filterDefs, { pageSize: 10 });
+
+  // On the server-paged path the page window, the search and the registration
+  // date range are all resolved by the API — nothing is filtered client-side.
+  // `controls.params` already carries every filter's mapped param name (status/
+  // currentYardId/wagonTypeId/… default to `{key: value}`, "created" maps to
+  // createdFrom/createdTo) plus search/page/pageSize — it IS the paged filter
+  // object; the unpaged one is the same minus pagination and the date range
+  // (which stays client-only for the non-server-paged slugs, see below).
+  const serverListFilters = useMemo((): FleetListFilters | undefined => {
+    if (!SERVER_FILTERED_SLUGS.includes(slug)) return undefined;
+    const { page: _page, pageSize: _pageSize, createdFrom: _cf, createdTo: _ct, ...rest } = controls.params;
+    return rest as FleetListFilters;
+  }, [slug, controls.params]);
+
+  const pagedFilters = useMemo(
+    (): FleetListFilters => controls.params as unknown as FleetListFilters,
+    [controls.params],
+  );
+
+  const listQuery = useQuery({
+    ...api.fleet.list.queryOptions({ input: { slug, filters: serverListFilters } }),
+    enabled: !serverPaged,
+  });
+  const pagedQuery = useQuery({
+    ...api.fleet.listPaged.queryOptions({ input: { slug, filters: pagedFilters } }),
+    enabled: serverPaged,
+    placeholderData: keepPreviousData,
+  });
+
+  const activeQuery = serverPaged ? pagedQuery : listQuery;
+  const { isLoading, isError, error } = activeQuery;
+  const allRows = useMemo(
+    () => (serverPaged ? (pagedQuery.data?.items ?? []) : (listQuery.data ?? [])),
+    [serverPaged, pagedQuery.data, listQuery.data],
+  );
+  const create = useMutation(api.fleet.create.mutationOptions());
+  const update = useMutation(api.fleet.update.mutationOptions());
+  const remove = useMutation(api.fleet.remove.mutationOptions());
+  const purge = useMutation(api.fleet.purge.mutationOptions());
 
   useEffect(() => {
     registerFleetOptionLabels("wagonTypeId", dynamicOptions.wagonTypes);
@@ -349,16 +322,22 @@ const FleetResourcePage = () => {
     // The API already applied every filter and cut the page — re-filtering here
     // would drop rows the server deliberately returned.
     if (serverPaged) return allRows;
-    const term = search.trim().toLowerCase();
     return allRows.filter((row) => {
       const record = row as unknown as Record<string, unknown>;
       // The date range applies even when the API already filtered the list —
       // it is not one of the server-side filters.
-      if (!matchesDayRange(record.createdAt, dateFrom, dateTo)) return false;
-      if (usesServerListFilters) return true;
-      if (statusFilter !== "ALL" && String(record.status ?? "") !== statusFilter) {
+      const created = controls.values.created;
+      if (created && !matchesDayRange(record.createdAt, created.v[0]?.slice(0, 10) ?? null, created.v[1]?.slice(0, 10) ?? null)) {
         return false;
       }
+      // Every other filter (status/yard/wagon type/…) was already applied
+      // server-side for these slugs — re-checking here against a plain field
+      // equality would be wrong for one (a wagon's "trainNumber" filter
+      // matches either of two DIFFERENT columns server-side, not one).
+      if (usesServerListFilters) return true;
+      const status = controls.values.status;
+      if (status && String(record.status ?? "") !== status.v[0]) return false;
+      const term = controls.searchText.trim().toLowerCase();
       if (!term) return true;
       return config.searchKeys.some((key) =>
         String(record[key] ?? "")
@@ -366,19 +345,23 @@ const FleetResourcePage = () => {
           .includes(term),
       );
     });
-  }, [allRows, search, statusFilter, config, usesServerListFilters, dateFrom, dateTo, serverPaged]);
+  }, [allRows, config, usesServerListFilters, controls.values, controls.searchText, serverPaged]);
 
   const totalCount = serverPaged
     ? (pagedQuery.data?.meta.total ?? 0)
     : filteredRows.length;
   const pageCount = serverPaged
     ? Math.max(1, pagedQuery.data?.meta.totalPages ?? 1)
-    : Math.max(1, Math.ceil(filteredRows.length / pagination.pageSize));
+    : Math.max(1, Math.ceil(filteredRows.length / controls.pageSize));
   const pagedRows = useMemo(() => {
     if (serverPaged) return filteredRows;
-    const start = pagination.pageIndex * pagination.pageSize;
-    return filteredRows.slice(start, start + pagination.pageSize);
-  }, [filteredRows, pagination.pageIndex, pagination.pageSize, serverPaged]);
+    const start = (controls.page - 1) * controls.pageSize;
+    return filteredRows.slice(start, start + controls.pageSize);
+  }, [filteredRows, controls.page, controls.pageSize, serverPaged]);
+
+  // Same {pagination, tableOptions} shape DataTable takes directly; FleetCardGrid
+  // (not a DataTable) just needs the raw pieces out of it below.
+  const { pagination: dtPagination, tableOptions: dtTableOptions } = controls.tableProps(totalCount);
 
   const columns = useMemo((): ColumnDef<FleetRecord>[] => {
     if (!config) return [];
@@ -604,77 +587,41 @@ const FleetResourcePage = () => {
       <Card radius="lg" padding={0} withBorder style={{ borderColor: "var(--mantine-color-gray-2)" }}>
         <Stack gap={0}>
           <Box px="md" pt="md" pb="md" w="100%" style={{ borderBottom: "1px solid var(--mantine-color-gray-2)" }}>
-            <FleetToolbar
-              search={search}
-              onSearchChange={setSearch}
+            <FilterBar
+              defs={filterDefs}
+              controls={controls}
               searchPlaceholder={config.searchPlaceholder}
               showSearch={config.supportsSearch}
-              viewMode={viewMode}
-              onViewModeChange={setViewMode}
-              filters={
-                <Group gap="sm" wrap="wrap" align="center">
-                  <DatePickerInput
-                    type="range"
-                    aria-label="Created date range"
-                    placeholder="Created date range"
-                    value={[dateFrom, dateTo]}
-                    onChange={([from, to]) => {
-                      setDateFrom(from);
-                      setDateTo(to);
-                    }}
-                    presets={getDateRangePresets()}
-                    clearable
-                    size="sm"
-                    radius="lg"
-                    w={240}
-                  />
-                {listFilterSelects ? (
-                  <Group gap="sm" wrap="wrap" align="center">
-                    {listFilterSelects.map((filter) => (
-                      <Select
-                        key={filter.key}
-                        aria-label={filter.label}
-                        placeholder={filter.data[0]?.label ?? filter.label}
-                        data={filter.data}
-                        value={filter.value}
-                        onChange={(value) => {
-                          setListFilterValues((prev) => ({
-                            ...prev,
-                            [filter.key]: value ?? "ALL",
-                          }));
-                          setPagination((prev) => ({ ...prev, pageIndex: 0 }));
-                        }}
-                        size="sm"
-                        radius="lg"
-                        w={200}
-                        searchable={filter.data.length > 8}
-                        comboboxProps={{ withinPortal: true }}
-                        styles={{ input: { borderColor: "var(--mantine-color-gray-3)" } }}
-                      />
-                    ))}
-                  </Group>
-                ) : hasStatusColumn && statusFilterOptions.length > 1 ? (
-                  <Group gap={4} wrap="wrap">
-                    <Text size="xs" fw={500} c="dimmed">Status:</Text>
-                    <Group gap={4} wrap="wrap">
-                      {[{ value: "ALL", label: "All" }, ...statusFilterOptions].map((option) => (
-                        <Button
-                          key={option.value}
-                          size="xs"
-                          radius="md"
-                          variant={statusFilter === option.value ? "filled" : "outline"}
-                          styles={{ label: { fontWeight: 500 } }}
-                          onClick={() => setStatusFilter(option.value)}
-                        >
-                          {option.label}
-                        </Button>
-                      ))}
-                    </Group>
-                  </Group>
-                ) : null}
-                </Group>
-              }
-            />
+              viewId={`fleet-${slug}`}
+            >
+              <SegmentedControl
+                value={viewMode}
+                onChange={(value) => setViewMode(value as FleetViewMode)}
+                size="sm"
+                radius="lg"
+                data={[
+                  {
+                    value: "table",
+                    label: (
+                      <Group gap={6} justify="center" wrap="nowrap">
+                        <Table2 size={14} />
+                        <span>Table</span>
+                      </Group>
+                    ),
+                  },
+                  {
+                    value: "cards",
+                    label: (
+                      <Group gap={6} justify="center" wrap="nowrap">
+                        <LayoutGrid size={14} />
+                        <span>Cards</span>
+                      </Group>
+                    ),
+                  },
+                ]}
+                styles={{ root: { background: "var(--mantine-color-gray-1)" } }}
+              />
+            </FilterBar>
           </Box>
 
           {viewMode === "table" ? (
@@ -696,18 +643,8 @@ const FleetResourcePage = () => {
                     : undefined
                 }
                 emptyMessage={`No ${itemLabel} found`}
-                pagination={{
-                  pageIndex: pagination.pageIndex,
-                  pageSize: pagination.pageSize,
-                  pageCount,
-                  totalCount,
-                }}
-                tableOptions={{
-                  manualPagination: true,
-                  pageCount,
-                  state: { pagination },
-                  onPaginationChange: setPagination,
-                }}
+                pagination={dtPagination}
+                tableOptions={dtTableOptions}
                 containerClassName="border-0 shadow-none bg-transparent"
                 footer={({ table, pagination: footerPagination }) => (
                   <DataTableFooter
@@ -724,10 +661,10 @@ const FleetResourcePage = () => {
               rows={pagedRows}
               status={tableStatus}
               emptyMessage={`No ${itemLabel} found`}
-              pagination={pagination}
+              pagination={{ pageIndex: controls.page - 1, pageSize: controls.pageSize }}
               pageCount={pageCount}
               totalCount={totalCount}
-              onPaginationChange={setPagination}
+              onPaginationChange={dtTableOptions!.onPaginationChange!}
               onEdit={
                 canUpdate
                   ? (record) => {

From aae0066a5d9ea4eed84ecaa9e317bfba3cbe16ca Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Sat, 15 Aug 2026 08:42:14 +0000
Subject: [PATCH 113/174] feat(filters): migrate ClearanceDocumentsPage to the
 pill filter bar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mechanical Family-A port — same server contract BookingRequestsPage
already uses (tradeDirection/freightType/isGovernment/createdFrom/
createdTo/search/page/pageSize all already accepted).

One wrinkle: this hub has no true "unfiltered" state — it always
scopes to a fixed 4-status baseline (customsClearingEnabled=false
self-clearance bookings), with the old status Select's "All statuses"
row just being that baseline spelled out as an option. Modeled as a
normal optional Status enum pill (4 individual statuses, no synthetic
"All" entry) whose absence falls back to the baseline in the query
build, not in the filter defs themselves — `customsClearingEnabled`
stays a fixed, non-user-facing param the same way.
---
 .../contracts/ClearanceDocumentsPage.tsx      | 249 +++++-------------
 1 file changed, 62 insertions(+), 187 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx
index 029c53dd2..766f7c897 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx
@@ -3,34 +3,28 @@ import {
   ActionIcon,
   Box,
   Card,
-  Group,
-  Select,
   Stack,
   Text,
-  TextInput,
   ThemeIcon,
 } from "@mantine/core";
-import { DatePickerInput } from "@mantine/dates";
-import { getDateRangePresets } from "@/components/common/dateRangePresets";
-import { useDebouncedValue } from "@mantine/hooks";
 import { keepPreviousData, useQuery } from "@tanstack/react-query";
-import { FileText, Inbox, RefreshCw, Search, User, X } from "lucide-react";
-import { useCallback, useMemo, useState } from "react";
+import { FileText, Inbox, RefreshCw, User } from "lucide-react";
+import { useMemo } from "react";
 import { useNavigate } from "react-router-dom";
 
 import { BookingStatusBadge } from "@/components/bookings/BookingStatusBadge";
 import { ContractReferenceLink } from "@/components/bookings/ContractReferenceLink";
 import { bookingTable } from "@/components/bookings/booking-ui.styles";
 import { PageContainer, PageHeader } from "@/components/page";
-import { bookingsService } from "@/services/bookings.service";
+import { bookingsService, type BookingListFilter } from "@/services/bookings.service";
 import type { BookingDetail } from "@/types/booking";
 import {
   Badge,
   DataTable,
   DataTableFooter,
-  usePagination,
   type ColumnDef,
 } from "@edr/ui-common";
+import { dateRangeParams, FilterBar, useFilters, type FilterDef } from "@/components/filters";
 
 /**
  * Operations "Clearance Documents" hub — the worklist for self-clearance
@@ -43,16 +37,14 @@ import {
 const PAGE_SIZE = 10;
 
 /**
- * Status filter options (values = `statuses` param). FULLY_EXECUTED is the
- * post-approval status of intercity (domestic) bookings — kept in the list as
- * history, otherwise an approved intercity row vanishes from the hub.
+ * The hub's baseline scope — FULLY_EXECUTED is the post-approval status of
+ * intercity (domestic) bookings, kept in as history so an approved intercity
+ * row doesn't just vanish. Sent whenever the Status pill has no narrower pick.
  */
-const BOOKING_STATUS_OPTIONS = [
-  {
-    value:
-      "AWAITING_DOCUMENTS,DOCUMENTS_UNDER_REVIEW,CLEARANCE_READY,FULLY_EXECUTED",
-    label: "All statuses",
-  },
+const DEFAULT_STATUSES =
+  "AWAITING_DOCUMENTS,DOCUMENTS_UNDER_REVIEW,CLEARANCE_READY,FULLY_EXECUTED";
+
+const STATUS_OPTIONS = [
   { value: "AWAITING_DOCUMENTS", label: "Awaiting documents" },
   { value: "DOCUMENTS_UNDER_REVIEW", label: "Under review" },
   { value: "CLEARANCE_READY", label: "Clearance ready" },
@@ -75,72 +67,58 @@ const OWNERSHIP_OPTIONS = [
   { value: "false", label: "Private" },
 ];
 
-function startOfDayIso(d: Date): string {
-  const x = new Date(d);
-  x.setHours(0, 0, 0, 0);
-  return x.toISOString();
-}
-
-function endOfDayIso(d: Date): string {
-  const x = new Date(d);
-  x.setHours(23, 59, 59, 999);
-  return x.toISOString();
-}
-
 export default function ClearanceDocumentsPage() {
   const navigate = useNavigate();
-  const [query, setQuery] = useState("");
-  const [debouncedQuery] = useDebouncedValue(query, 300);
-  const [bookingStatuses, setBookingStatuses] = useState(
-    BOOKING_STATUS_OPTIONS[0].value,
-  );
   const { filterOptions } = useMyTradeAccess();
-  const [directionFilter, setDirectionFilter] = useState<string | null>(null);
-  const [freightTypeFilter, setFreightTypeFilter] = useState<string | null>(null);
-  const [ownershipFilter, setOwnershipFilter] = useState<string | null>(null);
-  const [createdFrom, setCreatedFrom] = useState<Date | null>(null);
-  const [createdTo, setCreatedTo] = useState<Date | null>(null);
-  const { pagination, setPagination } = usePagination({ pageSize: PAGE_SIZE });
 
-  const search = debouncedQuery.trim() || undefined;
+  const filterDefs: FilterDef[] = useMemo(
+    () => [
+      {
+        key: "status",
+        label: "Status",
+        type: "enum",
+        multiple: false,
+        options: STATUS_OPTIONS,
+        // No pick ⇒ no `statuses` param at all; the query fills in
+        // DEFAULT_STATUSES itself, same as the old Select's "All statuses" row.
+        toParams: ({ v }) => ({ statuses: v[0] }),
+      },
+      {
+        key: "tradeDirection",
+        label: "Direction",
+        type: "enum",
+        multiple: false,
+        options: filterOptions(TRADE_DIRECTION_OPTIONS),
+      },
+      { key: "freightType", label: "Freight", type: "enum", multiple: false, options: FREIGHT_TYPE_OPTIONS },
+      { key: "isGovernment", label: "Ownership", type: "enum", multiple: false, options: OWNERSHIP_OPTIONS },
+      {
+        key: "created",
+        label: "Created",
+        type: "date",
+        toParams: dateRangeParams("createdFrom", "createdTo"),
+      },
+    ],
+    [filterOptions],
+  );
 
-  const resetPage = useCallback(() => {
-    setPagination({ pageIndex: 0, pageSize: PAGE_SIZE });
-  }, [setPagination]);
+  const controls = useFilters(filterDefs, { pageSize: PAGE_SIZE });
 
-  const page = pagination.pageIndex + 1;
+  const filter: BookingListFilter = useMemo(
+    () => ({
+      ...(controls.params as unknown as BookingListFilter),
+      // Self-clearance instances carry bookingType=ONE_TIME whatever their
+      // contract kind, so customsClearingEnabled=false + the status scope
+      // above are what isolate exactly this worklist.
+      customsClearingEnabled: "false",
+      statuses: (controls.params.statuses as string | undefined) ?? DEFAULT_STATUSES,
+    }),
+    [controls.params],
+  );
 
   const bookingsQuery = useQuery({
-    queryKey: [
-      "clearance-documents",
-      "bookings",
-      bookingStatuses,
-      directionFilter,
-      freightTypeFilter,
-      ownershipFilter,
-      createdFrom,
-      createdTo,
-      page,
-      search,
-    ],
-    queryFn: () =>
-      // Self-clearance instances carry bookingType=ONE_TIME whatever their
-      // contract kind, so customsClearingEnabled=false + the three per-booking
-      // clearance statuses are what isolate exactly this worklist.
-      bookingsService.list({
-        statuses: bookingStatuses,
-        customsClearingEnabled: "false",
-        page,
-        pageSize: PAGE_SIZE,
-        search,
-        ...(directionFilter ? { tradeDirection: directionFilter } : {}),
-        ...(freightTypeFilter ? { freightType: freightTypeFilter } : {}),
-        ...(ownershipFilter
-          ? { isGovernment: ownershipFilter as "true" | "false" }
-          : {}),
-        ...(createdFrom ? { createdFrom: startOfDayIso(createdFrom) } : {}),
-        ...(createdTo ? { createdTo: endOfDayIso(createdTo) } : {}),
-      }),
+    queryKey: ["clearance-documents", "bookings", filter],
+    queryFn: () => bookingsService.list(filter),
     placeholderData: keepPreviousData,
   });
 
@@ -233,7 +211,6 @@ export default function ClearanceDocumentsPage() {
   );
 
   const total = bookingsQuery.data?.total ?? 0;
-  const pageCount = Math.max(1, Math.ceil(total / PAGE_SIZE));
   const showEmpty =
     !bookingsQuery.isLoading && !bookingsQuery.isError && bookingRows.length === 0;
   const tableStatus = bookingsQuery.isLoading
@@ -265,103 +242,12 @@ export default function ClearanceDocumentsPage() {
         <Card p={0}>
           <Stack gap={0}>
             <Box px="md" pt="md" pb="sm" w="100%">
-              <Group justify="space-between" gap="md" wrap="wrap">
-                <TextInput
-                  placeholder="Search booking, contract or customer…"
-                  leftSection={<Search size={18} />}
-                  value={query}
-                  onChange={(e) => {
-                    setQuery(e.target.value);
-                    resetPage();
-                  }}
-                  rightSection={
-                    query && (
-                      <ActionIcon
-                        size="sm"
-                        color="gray"
-                        radius="md"
-                        variant="transparent"
-                        onClick={() => {
-                          setQuery("");
-                          resetPage();
-                        }}
-                      >
-                        <X size={16} />
-                      </ActionIcon>
-                    )
-                  }
-                  style={{ flex: 1, minWidth: "200px" }}
-                  radius="lg"
-                />
-                <Select
-                  data={BOOKING_STATUS_OPTIONS}
-                  value={bookingStatuses}
-                  onChange={(v) => {
-                    setBookingStatuses(v ?? BOOKING_STATUS_OPTIONS[0].value);
-                    resetPage();
-                  }}
-                  allowDeselect={false}
-                  radius="lg"
-                  w={220}
-                  aria-label="Filter by status"
-                />
-              </Group>
-              <Group gap="sm" mt="sm" wrap="wrap">
-                <Select
-                  placeholder="Direction"
-                  data={filterOptions(TRADE_DIRECTION_OPTIONS)}
-                  value={directionFilter}
-                  onChange={(v) => {
-                    setDirectionFilter(v);
-                    resetPage();
-                  }}
-                  clearable
-                  radius="lg"
-                  style={{ minWidth: 130 }}
-                  aria-label="Filter by direction"
-                />
-                <Select
-                  placeholder="Freight type"
-                  data={FREIGHT_TYPE_OPTIONS}
-                  value={freightTypeFilter}
-                  onChange={(v) => {
-                    setFreightTypeFilter(v);
-                    resetPage();
-                  }}
-                  clearable
-                  radius="lg"
-                  style={{ minWidth: 140 }}
-                  aria-label="Filter by freight type"
-                />
-                <Select
-                  placeholder="Gov / Private"
-                  data={OWNERSHIP_OPTIONS}
-                  value={ownershipFilter}
-                  onChange={(v) => {
-                    setOwnershipFilter(v);
-                    resetPage();
-                  }}
-                  clearable
-                  radius="lg"
-                  style={{ minWidth: 140 }}
-                  aria-label="Filter by ownership"
-                />
-                <DatePickerInput
-                  type="range"
-                  placeholder="Created date range"
-                  value={[createdFrom, createdTo]}
-                  onChange={([from, to]) => {
-                    setCreatedFrom(from ? new Date(from) : null);
-                    setCreatedTo(to ? new Date(to) : null);
-                    resetPage();
-                  }}
-                  presets={getDateRangePresets()}
-                  clearable
-                  radius="lg"
-                  style={{ minWidth: 220 }}
-                  aria-label="Created date range"
-                />
-              </Group>
+              <FilterBar
+                defs={filterDefs}
+                controls={controls}
+                searchPlaceholder="Search booking, contract or customer…"
+                viewId="clearance-documents"
+              />
             </Box>
 
             {showEmpty ? (
@@ -384,18 +270,7 @@ export default function ClearanceDocumentsPage() {
                       state: { from: "/dashboard/contracts/clearance-documents" },
                     })
                   }
-                  pagination={{
-                    pageIndex: pagination.pageIndex,
-                    pageSize: pagination.pageSize,
-                    pageCount,
-                    totalCount: total,
-                  }}
-                  tableOptions={{
-                    state: { pagination },
-                    onPaginationChange: setPagination,
-                    manualPagination: true,
-                    pageCount,
-                  }}
+                  {...controls.tableProps(total)}
                   containerClassName="border-0 shadow-none bg-transparent [&_th]:max-w-[100px] [&_td]:max-w-[100px] [&_td]:break-words"
                   footer={DataTableFooter}
                 />

From c9c2d4dcb3855576558166d68cc0e82422719105 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Sat, 15 Aug 2026 08:53:24 +0000
Subject: [PATCH 114/174] booking cancellation

---
 apps/edr-freight-api/.q.mjs                   |   9 +
 .../src/modules/billing/billing.controller.ts |  17 ++
 .../src/modules/billing/billing.service.ts    |  90 +++++--
 ...booking-wagon-cancellation.service.spec.ts |  42 ++++
 .../booking-wagon-cancellation.service.ts     | 225 ++++++++++++++----
 .../rule-engine/dto/create-rate.dto.ts        |   2 +-
 .../entities/rate-unit.util.spec.ts           |  16 ++
 .../rule-engine/entities/rate-unit.util.ts    |   9 +-
 .../rule-engine/services/rates.service.ts     |  78 +++---
 .../services/train-scheduling.service.ts      |  45 +++-
 .../ruleEngine/RuleEngineFormDialog.tsx       |   2 +-
 .../backoffice/src/constants/QUERY_KEYS.ts    |   2 +
 .../backoffice/src/constants/URLS.ts          |   1 +
 .../src/pages/invoices/FinanceHubPage.tsx     |  22 +-
 .../src/pages/invoices/InvoicesPage.tsx       |  57 ++++-
 .../src/pages/ruleEngine/config/resources.ts  |  47 ++--
 .../TrainScheduleV2ListPage.tsx               |  23 +-
 .../backoffice/src/services/api.ts            |  11 +
 .../src/services/invoices.service.ts          |  12 +
 .../backoffice/src/types/invoice.ts           |   3 +
 .../backoffice/src/types/trainScheduling.ts   |   3 +
 .../BookingDetailPage/ReadonlyBookingView.tsx |   9 +-
 .../components/WagonCancellationCard.tsx      |  30 ++-
 .../components/WagonsTab.tsx                  |  11 +-
 .../src/pages/bookings/BookingsListPage.tsx   |  40 +++-
 .../src/pages/bookings/RebookWagonsButton.tsx | 108 +++++++++
 26 files changed, 751 insertions(+), 163 deletions(-)
 create mode 100644 apps/edr-freight-api/.q.mjs
 create mode 100644 apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.spec.ts
 create mode 100644 apps/edr-freight-web/portal/src/pages/bookings/RebookWagonsButton.tsx

diff --git a/apps/edr-freight-api/.q.mjs b/apps/edr-freight-api/.q.mjs
new file mode 100644
index 000000000..b2b454075
--- /dev/null
+++ b/apps/edr-freight-api/.q.mjs
@@ -0,0 +1,9 @@
+import pg from 'pg';
+import fs from 'fs';
+const env = Object.fromEntries(fs.readFileSync('.env','utf8').split('\n').filter(l=>/^[A-Z_]+=/.test(l)).map(l=>{const i=l.indexOf('=');return [l.slice(0,i),l.slice(i+1).replace(/^"|"$/g,'')]}));
+const c = new pg.Client({host:env.DB_HOST,port:+env.DB_PORT,database:env.DB_NAME,user:env.DB_USER,password:env.DB_PASSWORD});
+await c.connect();
+const sql = process.argv[2];
+const r = await c.query(sql);
+console.log(JSON.stringify(r.rows,null,1));
+await c.end();
diff --git a/apps/edr-freight-api/src/modules/billing/billing.controller.ts b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
index 5bf1448fd..ad9bbe713 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.controller.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
@@ -63,6 +63,23 @@ export class BillingController {
     });
   }
 
+  @Get("invoices/summary")
+  @ApiOperation({
+    summary:
+      "Total collected (paidAmount) across every filtered invoice, grouped by currency",
+  })
+  async collectedSummary(
+    @Query() query: FilterInvoiceDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    const allowed =
+      await this.userTradeAccessService.resolveAllowedDirections(user);
+    return this.billingService.collectedSummary({
+      ...query,
+      tradeDirections: allowed ?? undefined,
+    });
+  }
+
   @Get("invoices/:id")
   @ApiOperation({ summary: "Get an invoice with its line items" })
   findById(@Param("id", ParseUUIDPipe) id: string) {
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 5afa30128..78b210a61 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -10,7 +10,7 @@ import {
 } from "@nestjs/common";
 import { EventEmitter2 } from "@nestjs/event-emitter";
 import { logCtx } from "@edr/api-common";
-import { DataSource, EntityManager, In } from "typeorm";
+import { DataSource, EntityManager, In, SelectQueryBuilder } from "typeorm";
 
 import { Booking } from "../bookings/entities/booking.entity";
 // Entity-only import (no module edge): portal reads resolve shipping-line
@@ -192,6 +192,40 @@ export class BillingService {
    * company (customer detail "Invoices" tab) and/or status/search (global
    * invoices page).
    */
+  /** Same list filters `findAllPaginated` and `collectedSummary` both narrow by. */
+  private applyInvoiceFilters(
+    qb: SelectQueryBuilder<Invoice>,
+    filter: {
+      companyId?: string;
+      status?: Freight.InvoiceStatus;
+      search?: string;
+      tradeDirections?: string[];
+    },
+  ) {
+    if (filter.companyId) {
+      qb.andWhere("invoice.companyId = :companyId", {
+        companyId: filter.companyId,
+      });
+    }
+    if (filter.status) {
+      qb.andWhere("invoice.status = :status", { status: filter.status });
+    }
+    if (filter.search) {
+      qb.andWhere(
+        "(invoice.invoiceNumber ILIKE :search OR invoice.sourceId ILIKE :search)",
+        { search: `%${filter.search}%` },
+      );
+    }
+    if (filter.tradeDirections) {
+      applyBookingRefDirectionScope(
+        qb,
+        "invoice.source_id",
+        filter.tradeDirections,
+      );
+    }
+    return qb;
+  }
+
   async findAllPaginated(
     filter: {
       companyId?: string;
@@ -215,33 +249,43 @@ export class BillingService {
       .skip((page - 1) * pageSize)
       .take(pageSize);
 
-    if (filter.companyId) {
-      qb.andWhere("invoice.companyId = :companyId", {
-        companyId: filter.companyId,
-      });
-    }
-    if (filter.status) {
-      qb.andWhere("invoice.status = :status", { status: filter.status });
-    }
-    if (filter.search) {
-      qb.andWhere(
-        "(invoice.invoiceNumber ILIKE :search OR invoice.sourceId ILIKE :search)",
-        { search: `%${filter.search}%` },
-      );
-    }
-
-    if (filter.tradeDirections) {
-      applyBookingRefDirectionScope(
-        qb,
-        "invoice.source_id",
-        filter.tradeDirections,
-      );
-    }
+    this.applyInvoiceFilters(qb, filter);
 
     const [items, total] = await qb.getManyAndCount();
     return { items, total };
   }
 
+  /**
+   * Total collected (`paidAmount`) across every invoice matching the same
+   * filters as `findAllPaginated`, grouped by currency — unpaginated, so the
+   * invoices summary card reflects the whole filtered set, not just the
+   * visible page.
+   */
+  async collectedSummary(
+    filter: {
+      companyId?: string;
+      status?: Freight.InvoiceStatus;
+      search?: string;
+      tradeDirections?: string[];
+    } = {},
+  ): Promise<Record<string, number>> {
+    const qb = this.dataSource
+      .getRepository(Invoice)
+      .createQueryBuilder("invoice")
+      .select("invoice.currency", "currency")
+      .addSelect("SUM(invoice.paidAmount)", "collected")
+      .groupBy("invoice.currency");
+
+    this.applyInvoiceFilters(qb, filter);
+
+    const rows: { currency: string; collected: string }[] =
+      await qb.getRawMany();
+
+    return Object.fromEntries(
+      rows.map((row) => [row.currency, Number(row.collected) || 0]),
+    );
+  }
+
   /**
    * Finance's offline-settlement worklist: USD invoices (paid by bank transfer,
    * never through the gateway), open ones by default or a single status when
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.spec.ts b/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.spec.ts
new file mode 100644
index 000000000..8babc8c2e
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.spec.ts
@@ -0,0 +1,42 @@
+import { BadRequestException } from '@nestjs/common';
+
+import { BookingWagonCancellationService } from './booking-wagon-cancellation.service';
+
+/**
+ * Sizing of a bulk quantity cut (no DB touched on this branch): a whole-booking
+ * cut is allowed and takes the exact cargo total; over-cut is rejected; a
+ * partial cut stays proportional.
+ */
+describe('BookingWagonCancellationService.resolveRequestedCut (bulk)', () => {
+  const svc = Object.create(BookingWagonCancellationService.prototype) as {
+    resolveRequestedCut(booking: unknown, dto: unknown): Promise<{
+      wagons: number;
+      weightTons: number;
+      quantities: { bulkTons?: number };
+    }>;
+  };
+  const booking = {
+    id: 'b1',
+    freightType: 'BULK',
+    wagonsRequired: 4,
+    cargoTotalWeightVgm: 250.5,
+    bulkTotalWeightTons: null,
+  };
+
+  it('cancels every wagon with the exact total tonnage', async () => {
+    const cut = await svc.resolveRequestedCut(booking, { wagons: 4 });
+    expect(cut).toEqual({ wagons: 4, weightTons: 250.5, quantities: { bulkTons: 250.5 } });
+  });
+
+  it('rejects more wagons than the booking has', async () => {
+    await expect(svc.resolveRequestedCut(booking, { wagons: 5 })).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+  });
+
+  it('sizes a partial cut proportionally', async () => {
+    const cut = await svc.resolveRequestedCut(booking, { wagons: 1 });
+    expect(cut.wagons).toBe(1);
+    expect(cut.weightTons).toBeCloseTo(62.625, 3);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts
index b62fdfca0..418fbd5c6 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts
@@ -7,8 +7,9 @@ import {
   Logger,
   NotFoundException,
 } from '@nestjs/common';
+import { ExchangeService } from '@edr/api-common';
 import { Freight, NotificationAudience, NotificationType } from '@edr/types';
-import { DataSource, EntityManager, In } from 'typeorm';
+import { DataSource, EntityManager, In, IsNull } from 'typeorm';
 
 import { BillingService } from '../billing/billing.service';
 import { ContractBookingService } from '../contracts/contract-booking.service';
@@ -18,9 +19,11 @@ import { ClearanceMilestone } from '../contracts/entities/clearance-milestone.en
 import { FirstMileService } from '../first-mile/first-mile.service';
 import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
 import { wagonsPerUnitForSize } from '../rule-engine/container-type.util';
+import { ContainerType } from '../rule-engine/entities/container-type.entity';
 import { Rate } from '../rule-engine/entities/rate.entity';
 import { BookingBatchService } from '../train-scheduling/booking-batch.service';
 import { TrainSchedulingService } from '../train-scheduling/services/train-scheduling.service';
+import { TrainScheduleBooking } from '../train-schedules/entities/train-schedule-booking.entity';
 import { WagonAllocationBulkLoad } from '../train-schedules/entities/wagon-allocation-bulk-load.entity';
 import { WagonAllocationContainerItem } from '../train-schedules/entities/wagon-allocation-container-item.entity';
 import { WagonBookingAllocation } from '../train-schedules/entities/wagon-booking-allocation.entity';
@@ -46,8 +49,9 @@ import {
 /**
  * rates.rate_type of the cancellation fee — an existing rate-engine type
  * (trigger CANCELLATION, never auto-applied to booking pricing). Staff
- * configure it in the normal rates UI; the wagon flow requires the PER_WAGON
- * unit so the fee scales with the cancelled wagon count.
+ * configure it in the normal rates UI, one PER_WAGON rate per trade direction
+ * + cargo kind + type (20ft / 40ft container type, or bulk commodity), so the
+ * fee scales with the cancelled wagon count and differs by what was booked.
  */
 export const WAGON_CANCELLATION_FEE_RATE_TYPE = 'CANCELLATION_FEE';
 /** invoices.type of the fee invoice — the settlement branch key in BookingInvoiceService. */
@@ -62,8 +66,20 @@ interface RequestedCut {
   quantities: CancelledQuantities;
 }
 
+/** The priced fee for a cut: total, currency and the rate(s) it came from. */
+interface PricedFee {
+  amount: number;
+  currency: string;
+  /** Effective per-wagon fee (amount / wagons) — one number for the customer. */
+  perWagon: number;
+  /** Rate rows used; the first is recorded on the ledger row. */
+  rates: Rate[];
+}
+
 /**
- * Partial wagon cancellation on a PAID booking, with a rebooking credit.
+ * Wagon cancellation on a PAID booking (partial or whole), with a rebooking
+ * credit. Cutting every wagon ends the source booking CANCELLED at T2; the
+ * credit then rebooks as a fresh booking under the same contract.
  *
  * Lifecycle (one ledger row per cycle, see BookingWagonCancellation):
  *  T1 request  — validate + price the fee, open the fee invoice. Nothing else
@@ -91,6 +107,7 @@ export class BookingWagonCancellationService {
     private readonly repo: BookingWagonCancellationsRepository,
     private readonly bookingsRepository: BookingsRepository,
     private readonly billing: BillingService,
+    private readonly exchangeService: ExchangeService,
     @Inject(forwardRef(() => ContractBookingService))
     private readonly contractBooking: ContractBookingService,
     @Inject(forwardRef(() => ClearanceMilestoneService))
@@ -120,14 +137,13 @@ export class BookingWagonCancellationService {
   }> {
     const booking = await this.loadCancellableBooking(bookingId);
     const cut = await this.resolveRequestedCut(booking, dto);
-    const rate = await this.feeRate();
-    const feeAmount = round2(Number(rate.rateValue) * cut.wagons);
+    const fee = await this.priceFee(booking, cut);
     return {
       wagons: cut.wagons,
       weightTons: cut.weightTons,
-      feePerWagon: Number(rate.rateValue),
-      feeAmount,
-      feeCurrency: rate.currency,
+      feePerWagon: fee.perWagon,
+      feeAmount: fee.amount,
+      feeCurrency: fee.currency,
       creditAmount: this.creditFor(booking, cut.wagons),
     };
   }
@@ -146,8 +162,8 @@ export class BookingWagonCancellationService {
     }
 
     const cut = await this.resolveRequestedCut(booking, dto);
-    const rate = await this.feeRate();
-    const feeAmount = round2(Number(rate.rateValue) * cut.wagons);
+    const fee = await this.priceFee(booking, cut);
+    const feeAmount = fee.amount;
     const creditAmount = this.creditFor(booking, cut.wagons);
 
     const row = await this.repo.create({
@@ -156,9 +172,11 @@ export class BookingWagonCancellationService {
       weightTons: cut.weightTons,
       cancelledQuantities: cut.quantities,
       creditAmount,
-      feeRateId: rate.id,
+      // ponytail: one FK for a mixed-size container cut records the first
+      // size's rate; the invoice line carries the effective per-wagon fee.
+      feeRateId: fee.rates[0].id,
       feeAmount,
-      feeCurrency: rate.currency,
+      feeCurrency: fee.currency,
       status: 'FEE_PENDING',
       reason: dto.reason ?? null,
       requestedByUserId: userId ?? null,
@@ -173,15 +191,15 @@ export class BookingWagonCancellationService {
       type: WAGON_CANCEL_FEE_INVOICE_TYPE,
       companyId: booking.companyId,
       companyProfileId: booking.companyProfileId,
-      currency: rate.currency,
+      currency: fee.currency,
       lines: [
         {
           chargeType: 'CANCELLATION_FEE',
           description: `Wagon cancellation fee — ${cut.wagons} wagon(s) of booking ${booking.reference}`,
           quantity: cut.wagons,
-          unitRate: Number(rate.rateValue),
+          unitRate: fee.perWagon,
           amount: feeAmount,
-          currency: rate.currency,
+          currency: fee.currency,
           metadata: { wagonCancellationId: row.id },
         },
       ],
@@ -343,12 +361,28 @@ export class BookingWagonCancellationService {
       const preSplitQuantities =
         booking.preSplitQuantities ?? (await this.currentQuantities(manager, booking, droppedWeight));
 
+      // Whole-booking cut: nothing is left to ship, so the booking ends
+      // CANCELLED (frees the contract slot/cap for the rebook) and drops off its
+      // train. The credit row still points at it for T3.
+      const wagonsLeft = round2(
+        Number(booking.wagonsRequired ?? 0) - Number(row.wagonsCancelled),
+      );
+      const isFull = wagonsLeft <= 0;
       await manager.getRepository(Booking).update(booking.id, {
-        wagonsRequired: round2(Number(booking.wagonsRequired ?? 0) - Number(row.wagonsCancelled)),
-        cargoTotalWeightVgm: round3(Number(booking.cargoTotalWeightVgm) - droppedWeight),
-        totalAmount: round2(Number(booking.totalAmount) - Number(row.creditAmount)),
+        wagonsRequired: Math.max(0, wagonsLeft),
+        cargoTotalWeightVgm: Math.max(
+          0,
+          round3(Number(booking.cargoTotalWeightVgm) - droppedWeight),
+        ),
+        totalAmount: Math.max(
+          0,
+          round2(Number(booking.totalAmount) - Number(row.creditAmount)),
+        ),
         isSplit: true,
         preSplitQuantities,
+        ...(isFull
+          ? { status: 'CANCELLED', trainScheduleId: null, requestedTrainScheduleId: null }
+          : {}),
       } as never);
 
       await manager.getRepository(BookingWagonCancellation).update(row.id, {
@@ -360,11 +394,15 @@ export class BookingWagonCancellationService {
     });
 
     const booking = await this.bookingsRepository.findById(row.bookingId);
+    if (booking?.status === 'CANCELLED') await this.detachFromSchedule(booking);
     if (booking) {
+      const whole = booking.status === 'CANCELLED';
       this.notifyCustomer(
         booking,
-        'Wagon cancellation confirmed',
-        `${row.wagonsCancelled} wagon(s) of ${booking.reference} are cancelled. Your paid freight is kept as credit — rebook any day while your contract is valid.`,
+        whole ? 'Booking cancelled — credit available' : 'Wagon cancellation confirmed',
+        whole
+          ? `All wagons of ${booking.reference} are cancelled. Your paid freight is kept as credit — rebook any day while your contract is valid.`
+          : `${row.wagonsCancelled} wagon(s) of ${booking.reference} are cancelled. Your paid freight is kept as credit — rebook any day while your contract is valid.`,
       );
     }
     this.logger.log(
@@ -372,6 +410,33 @@ export class BookingWagonCancellationService {
     );
   }
 
+  /**
+   * Whole-booking cut: take the cancelled booking OFF its train entirely —
+   * schedule link, leftover wagon slots, window status — via the ops unassign
+   * path (no "removed from train" notice: the customer cancelled it). A stale
+   * link would keep showing the booking on the schedule AND poison every later
+   * auto wagon allocation on that train (the whole-train re-plan rejects a
+   * CANCELLED booking). Then re-run allocation so bookings held back by it
+   * (e.g. the rebooked credit) get their wagons.
+   */
+  private async detachFromSchedule(booking: Booking): Promise<void> {
+    const links = await this.dataSource
+      .getRepository(TrainScheduleBooking)
+      .find({ where: { bookingId: booking.id } });
+    for (const link of links) {
+      try {
+        await this.trainScheduling.unassignBooking(link.trainScheduleId, booking.id, undefined, {
+          notifyCustomer: false,
+        });
+        await this.trainScheduling.tryAutoWagonAllocation(link.trainScheduleId);
+      } catch (err) {
+        this.logger.error(
+          `Detach of cancelled booking ${booking.reference} from schedule ${link.trainScheduleId} failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
   // ── T3: rebook ──────────────────────────────────────────────────────────────
 
   async rebook(
@@ -401,6 +466,8 @@ export class BookingWagonCancellationService {
     }
 
     const createDto = this.buildRebookDto(row, dto.scheduledDate);
+    // Same currency as the source booking — the credit is in it.
+    createDto.paymentCurrency = source.paymentCurrency ?? undefined;
     const created = await this.contractBooking.createUnderContract(
       source.contractId,
       createDto,
@@ -413,9 +480,13 @@ export class BookingWagonCancellationService {
 
     // The freight is already paid (credit) — mark PAID and let the existing
     // paid-booking machinery place it. No invoice is generated for it.
+    // Its price IS the credit (already paid, in the source currency) — not a
+    // fresh live-rate quote; a later cut of the rebooked booking credits from it.
     await this.dataSource.getRepository(Booking).update(newBookingId, {
       paymentStatus: 'PAID',
       status: 'PAID',
+      totalAmount: Number(row.creditAmount),
+      paymentCurrency: source.paymentCurrency,
     });
     await this.copyClearanceState(source, newBookingId);
 
@@ -539,9 +610,9 @@ export class BookingWagonCancellationService {
         wagons += cut.quantity * wagonsPerUnitForSize(Number(cut.containerSize));
       }
       wagons = round2(wagons);
-      if (wagons >= totalWagons) {
+      if (wagons > totalWagons) {
         throw new BadRequestException(
-          'That would cancel the whole booking — use booking cancellation instead of a partial wagon cancel.',
+          `Cannot cancel ${wagons} wagon(s) — the booking only has ${totalWagons}.`,
         );
       }
       // Snapshot the LIFO-picked physical units up front (read-only — cargo is
@@ -577,9 +648,11 @@ export class BookingWagonCancellationService {
           }
         }
       }
-      const weightShare = round3(
-        Number(booking.cargoTotalWeightVgm) * (wagons / totalWagons),
-      );
+      // Whole-booking cut takes the exact total, no ratio rounding.
+      const weightShare =
+        wagons >= totalWagons
+          ? round3(Number(booking.cargoTotalWeightVgm))
+          : round3(Number(booking.cargoTotalWeightVgm) * (wagons / totalWagons));
       return {
         wagons,
         weightTons: weightShare,
@@ -594,17 +667,19 @@ export class BookingWagonCancellationService {
     if (!wagons || wagons <= 0) {
       throw new BadRequestException('Specify how many wagons to cancel.');
     }
-    if (wagons >= totalWagons) {
+    if (wagons > totalWagons) {
       throw new BadRequestException(
-        'That would cancel the whole booking — use booking cancellation instead of a partial wagon cancel.',
+        `Cannot cancel ${wagons} wagon(s) — the booking only has ${totalWagons}.`,
       );
     }
+    // Whole-booking cut: all cargo, exactly. Otherwise proportional sizing.
     // ponytail: proportional sizing (tons/wagon = total/wagons). PER_ITEM item
     // rounding happens here too; switch to items_per_wagon_map sizing if bulk
     // PER_ITEM cancels ever need to be exact per item.
-    let tons = Number(booking.cargoTotalWeightVgm) * (wagons / totalWagons);
+    const isFull = wagons >= totalWagons;
+    let tons = Number(booking.cargoTotalWeightVgm) * (isFull ? 1 : wagons / totalWagons);
     const isPerItem = booking.bulkTotalWeightTons != null;
-    tons = isPerItem ? Math.floor(tons) : round3(tons);
+    tons = isPerItem && !isFull ? Math.floor(tons) : round3(tons);
     if (tons <= 0) {
       throw new BadRequestException('The requested cut is too small to release cargo.');
     }
@@ -641,19 +716,23 @@ export class BookingWagonCancellationService {
     }
 
     const wagons = allocations.length;
-    if (wagons >= totalWagons) {
+    if (wagons > totalWagons) {
       throw new BadRequestException(
-        'That would cancel the whole booking — use booking cancellation instead of a partial wagon cancel.',
+        `Cannot cancel ${wagons} wagon(s) — the booking only has ${totalWagons}.`,
       );
     }
+    const isFull = wagons >= totalWagons;
 
     if (booking.freightType !== 'CONTAINER') {
       const allocated = allocations.reduce(
         (s, a) => s + Number(a.allocatedWeightTons || 0),
         0,
       );
-      const tons =
-        allocated > 0
+      // Whole-booking cut takes the exact total; partial takes the wagons'
+      // allocated tonnage (ratio fallback when nothing is allocated yet).
+      const tons = isFull
+        ? round3(Number(booking.cargoTotalWeightVgm))
+        : allocated > 0
           ? round3(allocated)
           : round3(Number(booking.cargoTotalWeightVgm) * (wagons / totalWagons));
       return {
@@ -714,21 +793,83 @@ export class BookingWagonCancellationService {
     return round2(Number(booking.totalAmount) * (wagons / totalWagons));
   }
 
-  private async feeRate(): Promise<Rate> {
-    const rate = await this.dataSource.getRepository(Rate).findOne({
+  /**
+   * Price the cut off the LIVE per-wagon cancellation rates for the booking's
+   * trade direction. Bulk bills the rate scoped to the booking's commodity ×
+   * cancelled wagons; a container cut bills each size at its own container
+   * type's rate × the wagons that size occupies (two 20ft share one). A
+   * booking owned by a shipping line prices off that line's rates only —
+   * standard rates are never a fallback, matching booking pricing.
+   */
+  private async priceFee(booking: Booking, cut: RequestedCut): Promise<PricedFee> {
+    const raw = await this.priceFeeInRateCurrency(booking, cut);
+    // Bill in the booking's own currency (rates are configured in USD; ETB
+    // bookings pay ETB) — same USD→ETB conversion booking pricing applies.
+    const target = booking.paymentCurrency === 'ETB' ? 'ETB' : 'USD';
+    const from = raw.currency === 'ETB' ? 'ETB' : 'USD';
+    if (from === target) return raw;
+    const fx = await this.exchangeService.getRate(from, target);
+    return {
+      ...raw,
+      amount: round2(raw.amount * fx),
+      perWagon: round2(raw.perWagon * fx),
+      currency: target,
+    };
+  }
+
+  private async priceFeeInRateCurrency(
+    booking: Booking,
+    cut: RequestedCut,
+  ): Promise<PricedFee> {
+    const rates = await this.dataSource.getRepository(Rate).find({
       where: {
         rateType: WAGON_CANCELLATION_FEE_RATE_TYPE,
         rateUnit: 'PER_WAGON',
         status: 'LIVE',
+        tradeDirection: booking.tradeDirection,
+        shippingLineCompanyId: booking.shippingLineCompanyId ?? IsNull(),
       },
       order: { createdAt: 'DESC' },
     });
-    if (!rate) {
-      throw new BadRequestException(
-        'No LIVE per-wagon CANCELLATION_FEE rate is configured — ask EDR to set it in the rate engine (unit PER_WAGON).',
+    const missing = (scope: string): BadRequestException =>
+      new BadRequestException(
+        `No LIVE per-wagon cancellation fee is configured for ${scope} on ${booking.tradeDirection} — ask EDR to set it in the rate engine (surcharge: Cancellation).`,
       );
+
+    if (booking.freightType !== 'CONTAINER') {
+      const rate = rates.find(
+        (r) => !r.containerTypeId && !!r.cargoTypeId && r.cargoTypeId === booking.cargoTypeId,
+      );
+      if (!rate) throw missing(`bulk cargo type ${booking.cargoType?.cargoTypeName ?? booking.cargoTypeId ?? '?'}`);
+      const amount = round2(Number(rate.rateValue) * cut.wagons);
+      return { amount, currency: rate.currency, perWagon: Number(rate.rateValue), rates: [rate] };
     }
-    return rate;
+
+    // Container: split the cancelled wagons across sizes in proportion to the
+    // wagon-space each size's units occupy, so the total always equals
+    // cut.wagons (whole wagons on an allocation cut, fractional on a quantity cut).
+    const bySize = Object.entries(cut.quantities.bySize ?? {}).filter(([, qty]) => qty > 0);
+    const spaceOf = ([size, qty]: [string, number]) => qty * wagonsPerUnitForSize(Number(size));
+    const totalSpace = bySize.reduce((s, e) => s + spaceOf(e), 0);
+    if (!bySize.length || totalSpace <= 0) throw missing('containers');
+    const containerTypes = await this.dataSource.getRepository(ContainerType).find();
+    const used: Rate[] = [];
+    let amount = 0;
+    let currency = '';
+    for (const entry of bySize) {
+      const [size] = entry;
+      const sizeFt = Number(size);
+      const typeIds = new Set(
+        containerTypes.filter((ct) => Number(ct.sizeFt) === sizeFt).map((ct) => ct.id),
+      );
+      const rate = rates.find((r) => !!r.containerTypeId && typeIds.has(r.containerTypeId));
+      if (!rate) throw missing(`${sizeFt || '?'}ft containers`);
+      currency = rate.currency;
+      used.push(rate);
+      amount += Number(rate.rateValue) * cut.wagons * (spaceOf(entry) / totalSpace);
+    }
+    amount = round2(amount);
+    return { amount, currency, perWagon: round2(amount / cut.wagons), rates: used };
   }
 
   /**
@@ -902,9 +1043,9 @@ export class BookingWagonCancellationService {
     booking: Booking,
     tons: number,
   ): Promise<void> {
-    if (tons >= Number(booking.cargoTotalWeightVgm)) {
+    if (tons > Number(booking.cargoTotalWeightVgm)) {
       throw new BadRequestException(
-        'Booking changed since the request: the cut no longer leaves any cargo.',
+        'Booking changed since the request: the cut exceeds the cargo left on the booking.',
       );
     }
     if (booking.bulkTotalWeightTons != null) {
diff --git a/apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts b/apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts
index 73ae42a0d..bca8ab278 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts
@@ -53,7 +53,7 @@ export class CreateRateDto {
   @ApiPropertyOptional({
     enum: CARGO_KINDS,
     description:
-      'Whether a customs clearance rate covers containers or bulk. Required when trigger = CUSTOMS_CLEARANCE. Not stored — container fees carry a containerTypeId, bulk fees none.',
+      'Whether a customs clearance / cancellation rate covers containers or bulk. Required when trigger = CUSTOMS_CLEARANCE or CANCELLATION. Not stored — container fees carry a containerTypeId, bulk fees a cargoTypeId.',
   })
   @IsOptional()
   @IsIn([...CARGO_KINDS])
diff --git a/apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.spec.ts b/apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.spec.ts
index e44dcdb5f..39d6174de 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.spec.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.spec.ts
@@ -61,6 +61,22 @@ describe("allowedRateUnits — bulk unit of measure", () => {
     ).toEqual(["PER_TON"]);
   });
 
+  it("bills the wagon cancellation fee per wagon only, whatever the cargo kind", () => {
+    for (const cargoKind of ["CONTAINER", "BULK"] as const) {
+      expect(
+        allowedRateUnits({ appliesTo: "OTHER", trigger: "CANCELLATION", cargoKind }),
+      ).toEqual(["PER_WAGON"]);
+    }
+    expect(
+      allowedRateUnits({
+        appliesTo: "OTHER",
+        trigger: "CANCELLATION",
+        cargoKind: "BULK",
+        cargoUnitOfMeasure: "PER_ITEM",
+      }),
+    ).toEqual(["PER_WAGON"]);
+  });
+
   it("treats per-ton and per-item as the same booking quantity", () => {
     expect(isBulkQuantityUnit("PER_TON")).toBe(true);
     expect(isBulkQuantityUnit("PER_ITEM")).toBe(true);
diff --git a/apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.ts b/apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.ts
index 3d5b1401e..5adf225ca 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.ts
@@ -16,8 +16,7 @@ export const isBulkQuantityUnit = (unit: string): boolean =>
  * Which rate units make sense for a given rate shape. The weighting basis is
  * driven by the *type* of thing being billed — a container leg bills per
  * container, bulk freight per ton, an intercity move can be per-km, a
- * cancellation is a flat/per-invoice fee, and overweight is always per excess
- * ton. This keeps the rate table dynamic yet non-conflicting: the admin can
+ * cancellation is a per-wagon fee, and overweight is always per excess ton. This keeps the rate table dynamic yet non-conflicting: the admin can
  * only pick a unit the pricing engine knows how to apply.
  *
  * A rate scoped to a break-bulk commodity (unit_of_measure = PER_ITEM) offers
@@ -29,7 +28,7 @@ export const isBulkQuantityUnit = (unit: string): boolean =>
 export function allowedRateUnits(input: {
   appliesTo: RateAppliesTo;
   trigger: RateTrigger;
-  /** CUSTOMS_CLEARANCE only: which cargo kind the fee covers. */
+  /** CUSTOMS_CLEARANCE / CANCELLATION only: which cargo kind the fee covers. */
   cargoKind?: 'CONTAINER' | 'BULK' | null;
   /** Unit of measure of the bulk commodity the rate is scoped to, when any. */
   cargoUnitOfMeasure?: CargoUom;
@@ -64,7 +63,9 @@ function unitsForShape(input: {
         // wagon the empties ride back on, or a flat fee.
         return ['PER_CONTAINER', 'PER_WAGON', 'FLAT'];
       case 'CANCELLATION':
-        return ['FLAT', 'PER_INVOICE'];
+        // Wagon cancellation fee — scales with the cancelled wagon count, so
+        // per wagon is the only unit the wagon-cancel flow can apply.
+        return ['PER_WAGON'];
       case 'CUSTOMS_CLEARANCE':
         // Sold per cargo kind: container fees bill per box or per wagon, bulk
         // fees per ton or per wagon. Billed on the booking invoice.
diff --git a/apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts b/apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts
index 1902a757a..977a31718 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts
@@ -25,6 +25,19 @@ import { IYardsRepository, YARDS_REPOSITORY } from '../interfaces/yards.reposito
 
 /** Categories priced per rail leg — they carry an origin → destination yard pair. */
 const BASE_FREIGHT_CATEGORIES: readonly Rate['appliesTo'][] = ['BULK', 'CONTAINER', 'INTERCITY'];
+/**
+ * Surcharges sold per cargo kind: the admin says container or bulk, a
+ * container fee then names its container type and a bulk fee its commodity.
+ */
+const CARGO_KIND_TRIGGERS: readonly Rate['trigger'][] = ['CUSTOMS_CLEARANCE', 'CANCELLATION'];
+/** Surcharges that keep a trade direction (everything else is direction-agnostic). */
+const DIRECTED_SURCHARGE_TRIGGERS: readonly Rate['trigger'][] = [
+  'CUSTOMS_CLEARANCE',
+  'CANCELLATION',
+  'WITH_RETURN',
+  'LASHING',
+  'FUEL',
+];
 
 /** The yard pair a rate scopes to, already validated against its direction. */
 interface YardScope {
@@ -152,7 +165,11 @@ export class RatesService {
     appliesTo: Rate['appliesTo'],
     trigger: Rate['trigger'],
   ): boolean {
-    return this.isRouteScoped(appliesTo, trigger) || trigger === 'LASHING';
+    return (
+      this.isRouteScoped(appliesTo, trigger) ||
+      trigger === 'LASHING' ||
+      trigger === 'CANCELLATION'
+    );
   }
 
   /**
@@ -244,10 +261,13 @@ export class RatesService {
   }): void {
     const { appliesTo, trigger, tradeDirection, intercityKind, cargoKind } = input;
     const { containerTypeId, cargoTypeId } = input;
-    if (trigger === 'CUSTOMS_CLEARANCE') {
+    if (trigger === 'CUSTOMS_CLEARANCE' || trigger === 'CANCELLATION') {
+      // Both fees are sold per direction + cargo kind + type: customs clearance
+      // per lane, the wagon cancellation fee per direction only.
+      const fee = trigger === 'CANCELLATION' ? 'cancellation fee' : 'customs clearance';
       if (tradeDirection !== 'IMPORT' && tradeDirection !== 'EXPORT') {
         throw new BadRequestException(
-          'A customs clearance rate must say whether it covers IMPORT or EXPORT.',
+          `A ${fee} rate must say whether it covers IMPORT or EXPORT.`,
         );
       }
       // Sold per cargo kind: a container fee names the container type it covers
@@ -255,29 +275,29 @@ export class RatesService {
       // that absence is what marks it as the bulk fee.
       if (cargoKind !== 'CONTAINER' && cargoKind !== 'BULK') {
         throw new BadRequestException(
-          'A customs clearance rate must say whether it covers containers or bulk.',
+          `A ${fee} rate must say whether it covers containers or bulk.`,
         );
       }
       if (cargoKind === 'CONTAINER' && !containerTypeId) {
         throw new BadRequestException(
-          'A container customs clearance rate must name the container type it covers.',
+          `A container ${fee} rate must name the container type it covers.`,
         );
       }
       if (cargoKind === 'BULK' && containerTypeId) {
         throw new BadRequestException(
-          'A bulk customs clearance rate cannot be scoped to a container type.',
+          `A bulk ${fee} rate cannot be scoped to a container type.`,
         );
       }
-      // The bulk customs fee names the commodity it covers (sugar and
-      // fertilizer clear differently).
+      // The bulk fee names the commodity it covers (sugar and fertilizer
+      // clear — and cancel — differently).
       if (cargoKind === 'BULK' && !cargoTypeId) {
         throw new BadRequestException(
-          'A bulk customs clearance rate must name the bulk cargo type it covers.',
+          `A bulk ${fee} rate must name the bulk cargo type it covers.`,
         );
       }
       if (cargoKind === 'CONTAINER' && cargoTypeId) {
         throw new BadRequestException(
-          'A container customs clearance rate cannot be scoped to a bulk cargo type.',
+          `A container ${fee} rate cannot be scoped to a bulk cargo type.`,
         );
       }
       return;
@@ -547,22 +567,21 @@ export class RatesService {
     const trigger = dto.trigger as Rate['trigger'];
     // Surcharges (trigger ≠ ALWAYS) carry no direction/scope — clear them so
     // the engine never accidentally narrows a surcharge by container/direction.
-    // Exceptions: customs clearance and empty-container return keep direction +
-    // container type — both are sold per lane (and per container type).
+    // Exceptions: the directed surcharges (customs clearance, cancellation,
+    // empty-container return, lashing, fuel) keep direction + cargo scope.
     const isSurcharge = trigger !== 'ALWAYS';
-    const cargoKind =
-      trigger === 'CUSTOMS_CLEARANCE'
-        ? ((dto.cargoKind as 'CONTAINER' | 'BULK' | undefined) ?? null)
-        : null;
+    const cargoKind = CARGO_KIND_TRIGGERS.includes(trigger)
+      ? ((dto.cargoKind as 'CONTAINER' | 'BULK' | undefined) ?? null)
+      : null;
     const containerTypeId =
       trigger === 'WITH_RETURN' ||
-      (trigger === 'CUSTOMS_CLEARANCE' && cargoKind === 'CONTAINER')
+      (CARGO_KIND_TRIGGERS.includes(trigger) && cargoKind === 'CONTAINER')
         ? (dto.containerTypeId ?? null)
         : isSurcharge
           ? null
           : (dto.containerTypeId ?? null);
     const cargoTypeId =
-      (trigger === 'CUSTOMS_CLEARANCE' && cargoKind === 'BULK') ||
+      (CARGO_KIND_TRIGGERS.includes(trigger) && cargoKind === 'BULK') ||
       trigger === 'LASHING' ||
       trigger === 'FUEL'
         ? (dto.cargoTypeId ?? null)
@@ -574,10 +593,7 @@ export class RatesService {
     // intercity lane is stored as DOMESTIC, since appliesTo = OTHER says
     // nothing about the direction.)
     const tradeDirection =
-      trigger === 'CUSTOMS_CLEARANCE' ||
-      trigger === 'WITH_RETURN' ||
-      trigger === 'LASHING' ||
-      trigger === 'FUEL'
+      DIRECTED_SURCHARGE_TRIGGERS.includes(trigger)
         ? (dto.tradeDirection ?? null)
         : isSurcharge || appliesTo === 'INTERCITY'
           ? null
@@ -758,16 +774,15 @@ export class RatesService {
 
     // A patch that leaves the cargo kind unsaid keeps the one the rate already
     // has — read back off its container scope (container fees carry the type).
-    const cargoKind =
-      trigger !== 'CUSTOMS_CLEARANCE'
-        ? null
-        : ((dto.cargoKind as 'CONTAINER' | 'BULK' | undefined) ??
-          (existing.containerTypeId ? 'CONTAINER' : 'BULK'));
+    const cargoKind = !CARGO_KIND_TRIGGERS.includes(trigger)
+      ? null
+      : ((dto.cargoKind as 'CONTAINER' | 'BULK' | undefined) ??
+        (existing.containerTypeId ? 'CONTAINER' : 'BULK'));
 
     const keepsContainerType =
       !isSurcharge ||
       trigger === 'WITH_RETURN' ||
-      (trigger === 'CUSTOMS_CLEARANCE' && cargoKind === 'CONTAINER');
+      (CARGO_KIND_TRIGGERS.includes(trigger) && cargoKind === 'CONTAINER');
     const containerTypeId = !keepsContainerType
       ? null
       : dto.containerTypeId !== undefined
@@ -775,7 +790,7 @@ export class RatesService {
         : existing.containerTypeId;
     const keepsCargoType =
       !isSurcharge ||
-      (trigger === 'CUSTOMS_CLEARANCE' && cargoKind === 'BULK') ||
+      (CARGO_KIND_TRIGGERS.includes(trigger) && cargoKind === 'BULK') ||
       trigger === 'LASHING' ||
       trigger === 'FUEL';
     const cargoTypeId = !keepsCargoType
@@ -784,10 +799,7 @@ export class RatesService {
         ? dto.cargoTypeId
         : existing.cargoTypeId;
     const tradeDirection =
-      trigger === 'CUSTOMS_CLEARANCE' ||
-      trigger === 'WITH_RETURN' ||
-      trigger === 'LASHING' ||
-      trigger === 'FUEL'
+      DIRECTED_SURCHARGE_TRIGGERS.includes(trigger)
         ? dto.tradeDirection !== undefined
           ? dto.tradeDirection
           : existing.tradeDirection
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index 780d65305..73eb6fc31 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -2160,7 +2160,15 @@ export class TrainSchedulingService {
     return { ...detail, warnings, deferredBookings };
   }
 
-  async unassignBooking(scheduleId: string, bookingId: string, userId?: string) {
+  async unassignBooking(
+    scheduleId: string,
+    bookingId: string,
+    userId?: string,
+    opts: {
+      /** false = system detach (e.g. booking cancelled) — no "removed from train, rebook" notice. */
+      notifyCustomer?: boolean;
+    } = {},
+  ) {
     const schedule = await this.trainSchedulesRepository.findByIdWithFullGraph(scheduleId);
     if (!schedule) {
       throw new NotFoundException(`Train schedule ${scheduleId} not found`);
@@ -2287,7 +2295,9 @@ export class TrainSchedulingService {
     const removedBooking = await this.dataSource
       .getRepository(Booking)
       .findOne({ where: { id: bookingId }, relations: { company: true } });
-    if (removedBooking) this.bookingNotifier.removedFromTrain(removedBooking);
+    if (removedBooking && opts.notifyCustomer !== false) {
+      this.bookingNotifier.removedFromTrain(removedBooking);
+    }
     this.logger.log(
       `Booking ${bookingReference} removed from schedule ${scheduleId} by user ${userId ?? 'unknown'} — customer notified to reschedule or cancel.`,
     );
@@ -4409,6 +4419,7 @@ export class TrainSchedulingService {
         originStation: true,
         destinationStation: true,
         scheduleBookings: { booking: true },
+        shippingLineCompany: true,
       },
       order: { [sortBy]: sortOrder } as never,
       skip,
@@ -6107,6 +6118,10 @@ export class TrainSchedulingService {
       origin: schedule.originStation?.label ?? schedule.originStation?.code ?? null,
       destination:
         schedule.destinationStation?.label ?? schedule.destinationStation?.code ?? null,
+      // Dedicated shipping-line departure (hidden from customers) — the list
+      // highlights these rows so staff can tell them apart at a glance.
+      shippingLineCompanyId: schedule.shippingLineCompanyId ?? null,
+      shippingLineCompanyName: schedule.shippingLineCompany?.name ?? null,
       // Built train (Train Builder) behind this departure, when scheduled by train.
       train: schedule.trainSet?.train
         ? {
@@ -8997,8 +9012,14 @@ export class TrainSchedulingService {
     }
 
     const allocRepo = this.dataSource.getRepository(WagonBookingAllocation);
+    // Cargo type → allowed wagon types rides along: for bulk, the commodity's
+    // own wagon-type list (the planner's rule) decides, not only the wagon
+    // type's generic supportedLoadTypes.
     const loadAllocations = (trainSetWagonId: string) =>
-      allocRepo.find({ where: { trainSetWagonId } });
+      allocRepo.find({
+        where: { trainSetWagonId },
+        relations: { booking: { cargoType: { wagonTypes: true } } },
+      });
     const sourceAllocs = await loadAllocations(source.id);
     if (!sourceAllocs.length) {
       throw new BadRequestException('Source wagon has no load to move');
@@ -9043,10 +9064,25 @@ export class TrainSchedulingService {
       slot.physicalWagon?.wagonNumber ?? `#${slot.sequenceNo}`;
     const wagonLabel = (slot: TrainSetWagon | null, wagon: Wagon | null) =>
       slot ? slotLabel(slot) : (wagon?.wagonNumber ?? 'the target wagon');
+    // Bulk is allowed on a wagon type when every bulk load's cargo type lists
+    // it (cargo-type ↔ wagon-type config, same rule the wagon planner uses).
+    const bulkCargoAllows = (allocs: WagonBookingAllocation[], wagonTypeId?: string) => {
+      const bulk = allocs.filter((a) => (a.loadType ?? 'CONTAINER').toUpperCase() === 'BULK');
+      return (
+        !!wagonTypeId &&
+        bulk.length > 0 &&
+        bulk.every((a) =>
+          (a.booking?.cargoType?.wagonTypes ?? []).some((wt) => wt.id === wagonTypeId),
+        )
+      );
+    };
     const checkReceives = (
       allocs: WagonBookingAllocation[],
       label: string,
-      wagonType: { code?: string; supportedLoadTypes?: string[]; supportsContainer?: boolean } | null | undefined,
+      wagonType:
+        | { id?: string; code?: string; supportedLoadTypes?: string[]; supportsContainer?: boolean }
+        | null
+        | undefined,
       capacityTons: number,
     ) => {
       const incoming = loadTypesOf(allocs);
@@ -9057,6 +9093,7 @@ export class TrainSchedulingService {
           const ok =
             supported.includes(loadType) ||
             (loadType === 'CONTAINER' && wagonType.supportsContainer) ||
+            (loadType === 'BULK' && bulkCargoAllows(allocs, wagonType.id)) ||
             supported.length === 0;
           if (!ok) {
             throw new BadRequestException(
diff --git a/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx b/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx
index e05e00917..8c67b9eb3 100644
--- a/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/ruleEngine/RuleEngineFormDialog.tsx
@@ -256,7 +256,7 @@ const RuleEngineFormDialog = ({
         next.containerTypeId = "";
         next.cargoTypeId = "";
       }
-      // Cargo kind (customs / lashing) decides both the container-type scope
+      // Cargo kind (customs / cancellation) decides both the container-type scope
       // and the legal units (container → per box/wagon, bulk → per ton/wagon).
       if (name === "cargoKind") {
         next.containerTypeId = "";
diff --git a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
index f160a70ff..26db519ba 100644
--- a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
@@ -95,6 +95,8 @@ export const QUERY_KEYS = {
     byId: (id: string) => ["invoices", "detail", id] as const,
     offlineUsd: (filter?: InvoiceListFilter) =>
       ["invoices", "offline-usd", filter ?? {}] as const,
+    summary: (filter?: Omit<InvoiceListFilter, "page" | "pageSize">) =>
+      ["invoices", "summary", filter ?? {}] as const,
     eimsStatus: (id: string) => ["invoices", "eims", id] as const,
   },
 
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index 2a9f40ebd..df19cfd60 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -134,6 +134,7 @@ export const URL_CONSTANTS = {
 
   BILLING: {
     INVOICES: "/billing/invoices",
+    INVOICES_SUMMARY: "/billing/invoices/summary",
     INVOICE_BY_ID: (id: string) => `/billing/invoices/${id}`,
     INVOICE_DOCUMENT: (id: string) => `/billing/invoices/${id}/document`,
     OFFLINE_USD: "/billing/offline-usd",
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx
index bd5169262..261889d0b 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx
@@ -1,5 +1,5 @@
 import { Tabs } from "@mantine/core";
-import { Landmark, Receipt, Wallet } from "lucide-react";
+import { Landmark, Receipt } from "lucide-react";
 import { useSearchParams } from "react-router-dom";
 
 import { useAuth } from "@/auth/useAuth";
@@ -8,13 +8,15 @@ import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 
 import InvoicesPanel from "./InvoicesPage";
 import UsdPaymentsPanel from "./UsdPaymentsPage";
-import PaymentsPanel from "../payments/PaymentsPage";
 
 /**
- * Invoices, Payments, and USD Payments used to be three separate routes/pages
- * with near-identical chrome. They're merged here as URL-linkable tabs
- * (`?tab=`) on one page — each tab keeps the permission it was individually
- * gated on before, and just doesn't render if the user lacks it.
+ * Invoices and USD Payments used to be separate routes/pages with
+ * near-identical chrome. They're merged here as URL-linkable tabs (`?tab=`)
+ * on one page — each tab keeps the permission it was individually gated on
+ * before, and just doesn't render if the user lacks it.
+ *
+ * The Payments tab was removed; its summary (total collected, ETB/USD) now
+ * lives as a card at the top of the Invoices tab instead.
  */
 const TABS = [
   {
@@ -26,14 +28,6 @@ const TABS = [
       "Every invoice issued across bookings, warehouse fees and clearance charges.",
     Panel: InvoicesPanel,
   },
-  {
-    key: "payments",
-    label: "Payments",
-    icon: Wallet,
-    permission: FREIGHT_PERMS.payments.view,
-    subtitle: "View and reconcile booking payment transactions.",
-    Panel: PaymentsPanel,
-  },
   {
     key: "usd-payments",
     label: "USD Payments",
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
index e93521a35..ce42e8953 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
@@ -5,6 +5,7 @@ import {
   Card,
   Group,
   SegmentedControl,
+  SimpleGrid,
   Stack,
   Text,
   TextInput,
@@ -22,6 +23,7 @@ import {
   humanize,
 } from "@/components/customers";
 import CreditInvoiceActions from "@/components/shipping-lines/CreditInvoiceActions";
+import { useExchangeSettingsQuery } from "@/hooks/useExchangeSettings";
 import { api } from "@/services/api";
 import type { Invoice } from "@/types/invoice";
 import {
@@ -79,6 +81,21 @@ export default function InvoicesPanel() {
     [pendingActions],
   );
 
+  // Summary card: total collected (paidAmount) across every invoice matching
+  // the current search/status filters, not just the visible page.
+  const { data: summary } = useQuery(
+    api.invoices.collectedSummary.queryOptions({
+      input: {
+        filter: { search: debouncedQuery, status: statusFilter || undefined },
+      },
+    }),
+  );
+  const { data: exchangeSettings } = useExchangeSettingsQuery();
+  const etbCollected = summary?.ETB ?? 0;
+  const usdCollected = summary?.USD ?? 0;
+  const rate = exchangeSettings?.feed?.rate ?? exchangeSettings?.fallbackRate;
+  const etbFromUsd = rate ? usdCollected * rate : null;
+
   const columns: ColumnDef<Invoice>[] = useMemo(
     () => [
       {
@@ -170,7 +187,42 @@ export default function InvoicesPanel() {
   );
 
   return (
-    <Card p={0}>
+    <Stack gap="md">
+      <SimpleGrid cols={{ base: 1, sm: 3 }}>
+        <Card withBorder radius="md" padding="md">
+          <Text size="xs" c="dimmed" fw={600} tt="uppercase">
+            Total collected
+          </Text>
+          <Text size="xl" fw={700} c="edr-text">
+            {etbFromUsd !== null
+              ? formatMoney(etbCollected + etbFromUsd, "ETB")
+              : formatMoney(etbCollected, "ETB")}
+          </Text>
+          <Text size="xs" c="dimmed">
+            {etbFromUsd !== null
+              ? `Includes ${formatMoney(usdCollected, "USD")} converted @ ${rate} ETB/USD`
+              : "USD rate unavailable — ETB collected only"}
+          </Text>
+        </Card>
+        <Card withBorder radius="md" padding="md">
+          <Text size="xs" c="dimmed" fw={600} tt="uppercase">
+            Collected — ETB only
+          </Text>
+          <Text size="xl" fw={700} c="edr-text">
+            {formatMoney(etbCollected, "ETB")}
+          </Text>
+        </Card>
+        <Card withBorder radius="md" padding="md">
+          <Text size="xs" c="dimmed" fw={600} tt="uppercase">
+            Collected — USD only
+          </Text>
+          <Text size="xl" fw={700} c="edr-text">
+            {formatMoney(usdCollected, "USD")}
+          </Text>
+        </Card>
+      </SimpleGrid>
+
+      <Card p={0}>
       <Stack gap={0}>
         <Box px="md" pt="md" pb="sm" w="100%">
           <Group justify="space-between" gap="md" wrap="wrap">
@@ -264,6 +316,7 @@ export default function InvoicesPanel() {
           </Box>
         </Box>
       </Stack>
-    </Card>
+      </Card>
+    </Stack>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts
index aaddfe926..4ff9aa3fb 100644
--- a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts
+++ b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/config/resources.ts
@@ -187,7 +187,7 @@ const RATE_TRIGGERS = [
   { label: "Shipping line mapped", value: "SHIPPING_LINE" },
   { label: "Penalty", value: "CONSOLIDATION" },
   { label: "Lashing (bulk, per cargo type)", value: "LASHING" },
-  { label: "Cancellation", value: "CANCELLATION" },
+  { label: "Cancellation (per wagon, per direction + cargo type)", value: "CANCELLATION" },
   { label: "Shipping line extra fee (PIL)", value: "PIL_EXTRA_FEE" },
   { label: "Customs clearance service fee (billed with the booking)", value: "CUSTOMS_CLEARANCE" },
   { label: "Fuel (per lane + cargo type)", value: "FUEL" },
@@ -265,6 +265,13 @@ const isRouteScopedRate = (values: Record<string, unknown>) =>
   (String(values.appliesTo ?? "") === "OTHER" &&
     ["CUSTOMS_CLEARANCE", "WITH_RETURN", "FUEL"].includes(String(values.trigger ?? "")));
 
+/**
+ * Surcharges sold per cargo kind: the admin says container or bulk, then names
+ * the container type or bulk commodity the fee covers.
+ */
+const isCargoKindTrigger = (values: Record<string, unknown>) =>
+  ["CUSTOMS_CLEARANCE", "CANCELLATION"].includes(String(values.trigger ?? ""));
+
 const unitOption = (value: string) => ({ label: value.replace(/_/g, " "), value });
 
 /**
@@ -304,7 +311,8 @@ const unitsForShape = (
         // Container-only service — per returned container, per wagon, or flat.
         return ["PER_CONTAINER", "PER_WAGON", "FLAT"];
       case "CANCELLATION":
-        return ["FLAT", "PER_INVOICE"];
+        // Wagon cancellation fee — scales with the cancelled wagons only.
+        return ["PER_WAGON"];
       case "CUSTOMS_CLEARANCE":
         // Per cargo kind: container fees per box/wagon, bulk per ton/wagon.
         return cargoKind === "BULK"
@@ -1054,9 +1062,10 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         showIf: (v) =>
           hasShippingLine(v) && v.shippingLineRateKind === "SURCHARGE",
       },
-      // ── Trade direction — Bulk & Container base freight, plus the route-
-      // scoped surcharges (customs clearance; empty-container return, which is
-      // import-only for now so export is not offered) ────────────────────────
+      // ── Trade direction — Bulk & Container base freight, plus the directed
+      // surcharges (customs clearance, cancellation, lashing, fuel; empty-
+      // container return, which is import-only for now so export is not
+      // offered) ─────────────────────────────────────────────────────────────
       {
         name: "tradeDirection",
         label: "Trade direction",
@@ -1074,9 +1083,13 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
           !isShippingLineRate(v) &&
           (["BULK", "CONTAINER"].includes(String(v.appliesTo ?? "")) ||
             (String(v.appliesTo ?? "") === "OTHER" &&
-              ["CUSTOMS_CLEARANCE", "WITH_RETURN", "LASHING", "FUEL"].includes(
-                String(v.trigger ?? ""),
-              ))),
+              [
+                "CUSTOMS_CLEARANCE",
+                "CANCELLATION",
+                "WITH_RETURN",
+                "LASHING",
+                "FUEL",
+              ].includes(String(v.trigger ?? "")))),
       },
       // Shipping lines only ever ship import — the export leg is sold through
       // the customer's contract — so the direction is stated, not asked. Shown
@@ -1097,8 +1110,9 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         computeValue: () => "IMPORT",
         showIf: hasShippingLine,
       },
-      // ── Cargo kind — customs clearance is priced separately for containers
-      // (one rate per container type) and bulk ───────────────────────────────
+      // ── Cargo kind — customs clearance and the cancellation fee are priced
+      // separately for containers (one rate per container type) and bulk (one
+      // rate per commodity) ──────────────────────────────────────────────────
       {
         name: "cargoKind",
         label: "Cargo kind",
@@ -1107,11 +1121,10 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         options: INTERCITY_KINDS,
         placeholder: "Is this fee for containers or bulk?",
         description:
-          "Container fees bill per box or wagon (one rate per container type); bulk fees bill per ton or wagon.",
-        showIf: (v) =>
-          v.appliesTo === "OTHER" && v.trigger === "CUSTOMS_CLEARANCE",
+          "Container fees are set per container type; bulk fees per commodity. Customs: container per box or wagon, bulk per ton or wagon. Cancellation: per wagon.",
+        showIf: (v) => v.appliesTo === "OTHER" && isCargoKindTrigger(v),
         // Not a stored column: a container fee carries its containerTypeId, a
-        // bulk fee carries none.
+        // bulk fee its cargoTypeId.
         getInitialValue: (record) =>
           record.containerTypeId ? "CONTAINER" : "BULK",
       },
@@ -1124,10 +1137,10 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         placeholder: "Which container type this fee covers",
         showIf: (v) =>
           v.appliesTo === "OTHER" &&
-          v.trigger === "CUSTOMS_CLEARANCE" &&
+          isCargoKindTrigger(v) &&
           v.cargoKind === "CONTAINER",
       },
-      // ── Bulk cargo type — the bulk customs fee names its commodity ────────
+      // ── Bulk cargo type — the bulk fee names its commodity ────────────────
       {
         name: "cargoTypeId",
         label: "Bulk cargo type",
@@ -1136,7 +1149,7 @@ export const RULE_ENGINE_RESOURCES: RuleEngineResourceConfig[] = [
         placeholder: "Which bulk commodity this fee covers",
         showIf: (v) =>
           v.appliesTo === "OTHER" &&
-          v.trigger === "CUSTOMS_CLEARANCE" &&
+          isCargoKindTrigger(v) &&
           v.cargoKind === "BULK",
       },
       // ── Cargo type — a fuel rate names the commodity it covers (different
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 cfe1cc016..a659f31fa 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
@@ -362,6 +362,7 @@ export default function TrainScheduleV2ListPage() {
                   {row.original.direction}
                 </Badge>
               ) : null}
+              <ShippingLineBadge schedule={row.original} />
             </Group>
             <Box maw={220}>
               <RouteCorridor
@@ -742,7 +743,11 @@ export default function TrainScheduleV2ListPage() {
               onRowClick={(schedule) =>
                 navigate(`/dashboard/operations/train-scheduling-v2/${schedule.id}`)
               }
-              rowStyle={(schedule) => directionRowStyle(schedule.direction)}
+              rowStyle={(schedule) =>
+                schedule.shippingLineCompanyId
+                  ? SHIPPING_LINE_ROW_STYLE
+                  : directionRowStyle(schedule.direction)
+              }
               error={
                 schedulesQuery.isError
                   ? {
@@ -1052,6 +1057,20 @@ export default function TrainScheduleV2ListPage() {
  * bookings that have not paid yet — that space is claimed, so it is not
  * bookable.
  */
+/** Green tint for departures dedicated to a shipping line (overrides direction tint). */
+const SHIPPING_LINE_ROW_STYLE = {
+  backgroundColor: "var(--mantine-color-edr-green-0)",
+} as const;
+
+function ShippingLineBadge({ schedule }: { schedule: TrainScheduleListItem }) {
+  if (!schedule.shippingLineCompanyId) return null;
+  return (
+    <Badge size="xs" variant="light" color="edr-green">
+      {schedule.shippingLineCompanyName ?? "Shipping line"}
+    </Badge>
+  );
+}
+
 function WagonChips({ schedule }: { schedule: TrainScheduleListItem }) {
   // Pre-deploy API rows carry only wagonCount; fall back so the chip still
   // renders rather than reading 0 used on every train.
@@ -1133,6 +1152,7 @@ function ScheduleCard({
       withBorder
       onClick={onOpen}
       className="cursor-pointer overflow-hidden transition-[transform,border-color] duration-150 hover:-translate-y-0.5 hover:border-edr-primary!"
+      style={schedule.shippingLineCompanyId ? SHIPPING_LINE_ROW_STYLE : undefined}
     >
       <Stack gap="sm" p="md">
         <Group justify="space-between" align="flex-start" wrap="nowrap">
@@ -1182,6 +1202,7 @@ function ScheduleCard({
                 {schedule.direction}
               </Badge>
             ) : null}
+            <ShippingLineBadge schedule={schedule} />
           </Group>
           <Group gap={6} wrap="nowrap">
             <MetricChip value={schedule.bookingsCount} label="bkg" />
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 78efb2e4b..2c06700d2 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -39,6 +39,7 @@ import type {
 } from "@/types/fileUploadSettings";
 import type {
   Invoice,
+  InvoiceCollectedSummary,
   InvoiceListFilter,
   PaginatedInvoices,
   PaginatedOfflineUsdInvoices,
@@ -3137,6 +3138,16 @@ export const api = {
       ({ id }) => QUERY_KEYS.INVOICES.byId(id),
     ),
 
+    collectedSummary: endpoint<
+      { filter: Omit<InvoiceListFilter, "page" | "pageSize"> },
+      InvoiceCollectedSummary
+    >(
+      "invoices",
+      "collectedSummary",
+      ({ filter }) => invoicesService.collectedSummary(filter),
+      ({ filter }) => QUERY_KEYS.INVOICES.summary(filter),
+    ),
+
     listOfflineUsd: endpoint<
       { filter: InvoiceListFilter },
       PaginatedOfflineUsdInvoices
diff --git a/apps/edr-freight-web/backoffice/src/services/invoices.service.ts b/apps/edr-freight-web/backoffice/src/services/invoices.service.ts
index 18febdf7b..073afca12 100644
--- a/apps/edr-freight-web/backoffice/src/services/invoices.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/invoices.service.ts
@@ -2,6 +2,7 @@ import { api as apiClient } from "@/auth/http";
 import { URL_CONSTANTS } from "@/constants/URLS";
 import type {
   Invoice,
+  InvoiceCollectedSummary,
   InvoiceListFilter,
   PaginatedInvoices,
   PaginatedOfflineUsdInvoices,
@@ -23,6 +24,17 @@ export const invoicesService = {
       .then((r) => r.data);
   },
 
+  /** Total collected (paidAmount) across every filtered invoice, by currency. */
+  collectedSummary(
+    filter: Omit<InvoiceListFilter, "page" | "pageSize">,
+  ): Promise<InvoiceCollectedSummary> {
+    return apiClient
+      .get<InvoiceCollectedSummary>(URL_CONSTANTS.BILLING.INVOICES_SUMMARY, {
+        params: cleanParams(filter),
+      })
+      .then((r) => r.data);
+  },
+
   getById(id: string): Promise<Invoice> {
     return apiClient
       .get<Invoice>(URL_CONSTANTS.BILLING.INVOICE_BY_ID(id))
diff --git a/apps/edr-freight-web/backoffice/src/types/invoice.ts b/apps/edr-freight-web/backoffice/src/types/invoice.ts
index 14c99eb50..696a403ee 100644
--- a/apps/edr-freight-web/backoffice/src/types/invoice.ts
+++ b/apps/edr-freight-web/backoffice/src/types/invoice.ts
@@ -39,3 +39,6 @@ export interface PaginatedOfflineUsdInvoices {
   items: OfflineUsdInvoice[];
   total: number;
 }
+
+/** Total collected (`paidAmount`) across every filtered invoice, keyed by currency. */
+export type InvoiceCollectedSummary = Record<string, number>;
diff --git a/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts b/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
index 921f0c793..2c49769fc 100644
--- a/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
+++ b/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
@@ -196,6 +196,9 @@ export interface TrainScheduleListItem {
   origin: string | null;
   destination: string | null;
   freightType?: FreightType | null;
+  /** Set when the departure is dedicated to one shipping line (hidden from customers). */
+  shippingLineCompanyId?: string | null;
+  shippingLineCompanyName?: string | null;
   /** Built train (Train Builder) behind this departure, when scheduled by train. */
   train?: {
     id: string;
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/ReadonlyBookingView.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/ReadonlyBookingView.tsx
index 0ff719a7c..0ecd16ef4 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/ReadonlyBookingView.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/ReadonlyBookingView.tsx
@@ -158,7 +158,9 @@ export function ReadonlyBookingView({
   // the customer. Hide the customer's rebook everywhere and tell them GL will
   // handle it. Non-customs bookings stay self-service.
   const isCustoms = Boolean(booking.customsClearingEnabled);
-  const canSelfRebook = !isCustoms;
+  // A PAID booking cancelled through wagon cancellation rebooks via its credit
+  // (WagonCancellationCard), not the fresh-booking rebook link.
+  const canSelfRebook = !isCustoms && booking.paymentStatus !== "PAID";
   const isPendingConsolidation = status === "PENDING_CONSOLIDATION";
   const isClearance = [
     "AWAITING_DOCUMENTS",
@@ -219,7 +221,9 @@ export function ReadonlyBookingView({
           subtitle={
             status === "REJECTED"
               ? "This booking request has been rejected."
-              : "This booking process has been terminated."
+              : booking.paymentStatus === "PAID"
+                ? "All wagons were cancelled. Your paid freight is held as a credit — rebook it from the Wagon Cancellation card below."
+                : "This booking process has been terminated."
           }
           reason={booking.latestChangeRequestNote}
           onRebook={canSelfRebook ? onRebook : undefined}
@@ -348,6 +352,7 @@ export function ReadonlyBookingView({
           <Tabs.Panel value="wagons">
             <WagonsTab
               bookingId={booking.id}
+              currency={booking.paymentCurrency}
               cancellable={
                 booking.status === "PAID" &&
                 booking.paymentStatus === "PAID" &&
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx
index 05e7ed8d8..f75972f28 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx
@@ -76,7 +76,7 @@ const apiErrorMessage = (error: unknown, fallback: string) => {
 const th = { color: "#9AA8B5", fontSize: 11 } as const;
 
 /**
- * Partial wagon cancellation on a PAID contract booking: request a cut (fee
+ * Wagon cancellation (partial or whole) on a PAID contract booking: request a cut (fee
  * previewed first), pay the cancellation fee, then rebook the freed credit
  * onto another shipment day — plus the booking's cancellation history.
  * Wagons leave the schedule at request time; the fee settles the credit.
@@ -90,10 +90,13 @@ export function WagonCancellationCard({
 }) {
   const navigate = useNavigate();
   const status = booking.status as string;
-  const eligible =
-    status === "PAID" &&
-    (booking.paymentStatus as string) === "PAID" &&
-    !!booking.contractId;
+  const paidContract =
+    (booking.paymentStatus as string) === "PAID" && !!booking.contractId;
+  // New cuts only on a live PAID booking; a booking fully cancelled through
+  // this flow (status CANCELLED) still shows the card so its credit can be
+  // paid for / rebooked.
+  const canRequest = status === "PAID" && paidContract;
+  const eligible = paidContract && (status === "PAID" || status === "CANCELLED");
 
   const isBulk = booking.freightType === "BULK";
   const detail = booking as BookingDetail;
@@ -226,12 +229,13 @@ export function WagonCancellationCard({
   });
 
   if (!eligible) return null;
+  if (!canRequest && !ownRows.length) return null;
 
   return (
     <SectionCard>
       <Group justify="space-between" align="center" mb="sm">
         <CardTitle>Wagon Cancellation</CardTitle>
-        {!openRow && !creditRow && (
+        {canRequest && !openRow && !creditRow && (
           <Button
             variant="default"
             radius="md"
@@ -305,9 +309,9 @@ export function WagonCancellationCard({
         </Stack>
       ) : (
         <Text fz={13} c="#475569">
-          Need fewer wagons than you paid for? Cancel part of this booking for
-          a per-wagon fee — the freed freight amount becomes a credit you can
-          rebook onto another shipment day.
+          Need fewer wagons than you paid for — or none? Cancel part or all of
+          this booking for a per-wagon fee — the freed freight amount becomes a
+          credit you can rebook onto another shipment day.
         </Text>
       )}
 
@@ -401,16 +405,16 @@ export function WagonCancellationCard({
               {booking.reference}
             </Text>{" "}
             to cancel. A per-wagon fee applies; once it&apos;s paid the wagons
-            are released and the freed amount becomes a rebooking credit. At
-            least one wagon must remain — to cancel everything, cancel the
-            whole booking instead.
+            are released and the freed amount becomes a rebooking credit.
+            Cancelling every wagon cancels the whole booking — the full freight
+            amount becomes your credit.
           </Text>
 
           {isBulk ? (
             <NumberInput
               label="Wagons to cancel"
               min={1}
-              max={wagonsRequired > 1 ? wagonsRequired - 1 : undefined}
+              max={wagonsRequired > 0 ? wagonsRequired : undefined}
               allowDecimal={false}
               value={wagons}
               onChange={(v) => {
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonsTab.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonsTab.tsx
index 89df714d6..bb775555f 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonsTab.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonsTab.tsx
@@ -462,10 +462,13 @@ function WagonCard({
  */
 export function WagonsTab({
   bookingId,
+  currency,
   cancellable,
   onCancellationRequested,
 }: {
   bookingId: string;
+  /** Booking payment currency — labels the rebooking credit. */
+  currency?: string;
   /** PAID contract booking — specific wagons may be selected for cancellation. */
   cancellable?: boolean;
   onCancellationRequested?: () => void;
@@ -684,7 +687,7 @@ export function WagonsTab({
             </Box>
             <Button
               color="orange"
-              disabled={selected.size === 0 || selected.size >= wagons.length}
+              disabled={selected.size === 0}
               onClick={openConfirm}
             >
               Cancel selected ({selected.size})
@@ -692,8 +695,8 @@ export function WagonsTab({
           </Group>
           {selected.size >= wagons.length && selected.size > 0 && (
             <Text fz={12} c="#B3362C" mt={6}>
-              You cannot cancel every wagon here — to cancel the whole booking,
-              use the booking cancellation instead.
+              Every wagon is selected — this cancels the whole booking once the
+              fee is paid; the full freight amount becomes your rebooking credit.
             </Text>
           )}
         </SectionCard>
@@ -759,7 +762,7 @@ export function WagonsTab({
                   Rebooking credit kept
                 </Text>
                 <Text fz={14} fw={800} c="#0A6F4D">
-                  {Number(preview.creditAmount).toLocaleString()}
+                  {Number(preview.creditAmount).toLocaleString()} {currency ?? ""}
                 </Text>
               </Group>
             </Box>
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
index 2f269bdab..a54b22506 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
@@ -43,6 +43,7 @@ import {
   bookingIsSignable,
 } from "./contract/ContractSignButton";
 import { ApproveDeliveryButton } from "./delivery/ApproveDeliveryButton";
+import { RebookWagonsButton } from "./RebookWagonsButton";
 import {
   BookingStatusBadge as StatusBadge,
   BookingTypeBadge,
@@ -52,7 +53,10 @@ import {
 } from "./booking-display";
 
 import { api } from "@/services/api";
-import type { BookingListFilter } from "@/services/bookings.service";
+import type {
+  BookingListFilter,
+  WagonCancellation,
+} from "@/services/bookings.service";
 import type { Freight } from "@edr/types";
 import {
   DataTable,
@@ -176,13 +180,25 @@ const STAT_CARDS: Array<{
 
 function PrimaryAction({
   booking,
+  credit,
   onNavigate,
 }: {
   booking: Freight.IBooking;
+  /** CREDIT_AVAILABLE wagon cancellation opened by this booking, if any. */
+  credit?: WagonCancellation;
   onNavigate: (path: string) => void;
 }) {
   const { status, id } = booking;
   const go = () => onNavigate(`/bookings/${id}`);
+  // Cancelled wagons with a paid credit (partial or whole cancel) → rebook.
+  if (credit) {
+    return (
+      <RebookWagonsButton
+        cancellation={credit}
+        currency={booking.paymentCurrency}
+      />
+    );
+  }
   // A general contract is payable as soon as it's FULLY_EXECUTED (signed); a
   // one-time booking only after it's SELECTED_FOR_BATCH.
   const isGeneralContract = booking.bookingType === "GENERAL_CONTRACT";
@@ -423,6 +439,22 @@ export default function BookingsListPage() {
     api.bookings.list.queryOptions({ input: filter }),
   );
 
+  // Rebookable credits (fee-paid wagon cancellations) keyed by source booking,
+  // so the row action can offer "Rebook wagons" in place of "View".
+  // ponytail: one page of 100 newest rows; paginate if a customer ever holds more.
+  const { data: myCancellations } = useQuery(
+    api.bookings.listMyWagonCancellations.queryOptions({
+      input: { pageSize: 100 },
+    }),
+  );
+  const creditByBooking = useMemo(() => {
+    const m = new Map<string, WagonCancellation>();
+    for (const r of myCancellations?.items ?? []) {
+      if (r.status === "CREDIT_AVAILABLE" && !m.has(r.bookingId)) m.set(r.bookingId, r);
+    }
+    return m;
+  }, [myCancellations]);
+
   // Per-card lifecycle counts (one cheap query each, total-only).
   const allCount = useStatusCount(undefined);
   const activeCount = useStatusCount(
@@ -654,7 +686,11 @@ export default function BookingsListPage() {
                 Track
               </Button>
             )}
-            <PrimaryAction booking={booking} onNavigate={navigate} />
+            <PrimaryAction
+              booking={booking}
+              credit={creditByBooking.get(booking.id)}
+              onNavigate={navigate}
+            />
             <Menu position="bottom-end" withinPortal shadow="md" radius="md">
               <Menu.Target>
                 <ActionIcon
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/RebookWagonsButton.tsx b/apps/edr-freight-web/portal/src/pages/bookings/RebookWagonsButton.tsx
new file mode 100644
index 000000000..372d24156
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/bookings/RebookWagonsButton.tsx
@@ -0,0 +1,108 @@
+import { useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { Alert, Button, Group, Modal, Stack, Text } from "@mantine/core";
+import { RotateCcw } from "lucide-react";
+import toast from "react-hot-toast";
+
+import { api } from "@/services/api";
+import { bookingsService, type WagonCancellation } from "@/services/bookings.service";
+import { OperationDatePicker } from "./clearance";
+import { formatAmount } from "./BookingDetailPage/utils";
+
+const apiErrorMessage = (error: unknown, fallback: string) => {
+  const data = (error as { response?: { data?: { message?: string | string[] } } })
+    ?.response?.data;
+  if (Array.isArray(data?.message)) return data.message.join(", ");
+  if (data?.message) return data.message;
+  return fallback;
+};
+
+/**
+ * List-row action for a CREDIT_AVAILABLE wagon cancellation: pick a shipment
+ * day, rebook the credit as a new PAID booking, jump to it.
+ */
+export function RebookWagonsButton({
+  cancellation,
+  currency,
+  size = "xs",
+}: {
+  cancellation: WagonCancellation;
+  currency?: string;
+  size?: "xs" | "sm";
+}) {
+  const navigate = useNavigate();
+  const qc = useQueryClient();
+  const [open, setOpen] = useState(false);
+  const [date, setDate] = useState("");
+
+  const rebook = useMutation({
+    mutationFn: () =>
+      bookingsService.rebookWagonCancellation(cancellation.id, { scheduledDate: date }),
+    onSuccess: ({ bookingId }) => {
+      qc.invalidateQueries({ queryKey: api.bookings.list.queryKey() });
+      qc.invalidateQueries({ queryKey: api.bookings.listMyWagonCancellations.queryKey() });
+      toast.success("Wagons rebooked — taking you to the new booking.", { duration: 6000 });
+      setOpen(false);
+      navigate(`/bookings/${bookingId}`);
+    },
+    onError: (e) =>
+      toast.error(apiErrorMessage(e, "Could not rebook the wagons. Please try again.")),
+  });
+
+  return (
+    <>
+      <Button
+        size={size}
+        radius="md"
+        color="edr-green"
+        fw={700}
+        fz={13}
+        leftSection={<RotateCcw size={14} />}
+        onClick={() => setOpen(true)}
+      >
+        Rebook wagons
+      </Button>
+      <Modal
+        opened={open}
+        onClose={() => setOpen(false)}
+        title={
+          <Text fw={800} fz={18} c="#10202F">
+            Rebook cancelled wagons
+          </Text>
+        }
+        centered
+        radius={16}
+      >
+        <Stack gap="md">
+          <Alert color="teal" radius="md">
+            {Number(cancellation.wagonsCancelled)} wagon(s) — credit of{" "}
+            <Text span fw={700}>
+              {formatAmount(cancellation.creditAmount)} {currency ?? ""}
+            </Text>
+            . Pick a shipment day; the new booking is created already paid.
+          </Alert>
+          <OperationDatePicker
+            bookingId={cancellation.bookingId}
+            value={date}
+            onChange={setDate}
+          />
+          <Group justify="flex-end">
+            <Button variant="default" radius="md" onClick={() => setOpen(false)}>
+              Close
+            </Button>
+            <Button
+              color="edr-green"
+              radius="md"
+              disabled={!date}
+              loading={rebook.isPending}
+              onClick={() => rebook.mutate()}
+            >
+              Rebook wagons
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
+    </>
+  );
+}

From dc38e843a6dc73bbf2295e4e1e07bd6e8bc68a9d Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Sat, 15 Aug 2026 10:12:37 +0000
Subject: [PATCH 115/174] feat: full wagon cancel, leg board, wagon dates
 feat(freight): editable train leg times, SL invoice payer

---
 .../src/modules/billing/billing.service.ts    |  44 +-
 .../src/modules/bookings/bookings.module.ts   |   1 +
 .../bookings/container-validation.service.ts  |  11 +-
 ...hipping-line-booking-completion.service.ts |  50 +++
 .../train-scheduling.controller.ts            |  33 +-
 .../dto/record-checkpoint.dto.ts              |  39 +-
 .../services/train-scheduling.service.spec.ts |  59 ++-
 .../services/train-scheduling.service.ts      | 232 +++++++++-
 .../src/modules/wagons/wagons.service.ts      |  42 +-
 .../trainScheduling/CheckpointTimeModal.tsx   | 103 +++++
 .../trainScheduling/LegLoadBoardPanel.tsx     | 423 ++++++++++++++++++
 .../trainScheduling/LogPassYardWorkModal.tsx  |  30 +-
 .../trainScheduling/RouteCorridorTrack.tsx    |  35 +-
 .../backoffice/src/constants/URLS.ts          |   2 +
 .../src/pages/fleet/config/resources.ts       |   4 +
 .../src/pages/invoices/InvoiceDetailPage.tsx  |  26 +-
 .../src/pages/invoices/InvoicesPage.tsx       |   4 +-
 .../ruleEngine/RuleEngineResourcePage.tsx     |  16 +-
 .../TrainScheduleTrackPage.tsx                | 143 +++++-
 .../TrainScheduleV2DetailPage.tsx             |  38 +-
 .../TrainScheduleV2ListPage.tsx               |  25 +-
 .../backoffice/src/services/api.ts            |  21 +-
 .../src/services/trainScheduling.service.ts   |  17 +-
 .../backoffice/src/services/wagon.service.ts  |   3 +
 .../backoffice/src/types/trainScheduling.ts   |  12 +
 .../portal/src/components/AppLayout.tsx       |   6 +-
 .../src/pages/bookings/BookingsListPage.tsx   |   4 +-
 .../ShippingLineBookingsPage.tsx              |  11 +
 .../ShippingLineCompletePage.tsx              | 378 +++++++++++-----
 .../shipping-line-bookings.service.ts         |   9 +
 packages/types/src/freight/index.ts           |  15 +-
 31 files changed, 1619 insertions(+), 217 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/components/trainScheduling/CheckpointTimeModal.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/trainScheduling/LegLoadBoardPanel.tsx

diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 78b210a61..720bad774 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -252,7 +252,46 @@ export class BillingService {
     this.applyInvoiceFilters(qb, filter);
 
     const [items, total] = await qb.getManyAndCount();
-    return { items, total };
+    return { items: await this.attachShippingLineCompanies(items), total };
+  }
+
+  /**
+   * Batch-hydrate `shippingLineCompany` for any invoice billed to a shipping
+   * line (`companyId` null). No relation on `Invoice` to eager-load — see the
+   * entity's doc comment — so this is a second query keyed off the ids
+   * already loaded, same shape as `company`.
+   */
+  private async attachShippingLineCompanies<T extends Invoice>(
+    invoices: T[],
+  ): Promise<T[]> {
+    const ids = [
+      ...new Set(
+        invoices
+          .map((i) => i.shippingLineCompanyId)
+          .filter((id): id is string => id != null),
+      ),
+    ];
+    if (!ids.length) return invoices;
+    const lines = await this.dataSource
+      .getRepository(ShippingLineCompany)
+      .find({ where: { id: In(ids) } });
+    const byId = new Map(lines.map((l) => [l.id, l]));
+    return invoices.map((invoice) => {
+      const line = invoice.shippingLineCompanyId
+        ? byId.get(invoice.shippingLineCompanyId)
+        : undefined;
+      return line
+        ? ({
+            ...invoice,
+            shippingLineCompany: {
+              id: line.id,
+              name: line.name,
+              email: line.email,
+              phoneNumber: line.phoneNumber,
+            },
+          } as T)
+        : invoice;
+    });
   }
 
   /**
@@ -432,11 +471,12 @@ export class BillingService {
       relations: { company: true, companyProfile: true },
     });
     if (!invoice) throw new NotFoundException(`Invoice ${id} not found`);
+    const [hydrated] = await this.attachShippingLineCompanies([invoice]);
     const lines = await this.invoiceLines.findAll({
       where: { invoiceId: id },
       order: { createdAt: "ASC" },
     });
-    return { ...invoice, lines } as Invoice & { lines: InvoiceLine[] };
+    return { ...hydrated, lines } as Invoice & { lines: InvoiceLine[] };
   }
 
   // ── Documents (central PDF) ──────────────────────────────────────────────────
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
index 658629592..447292117 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
@@ -121,6 +121,7 @@ import { VehiclesModule } from "../vehicles/vehicles.module";
     BookingsService,
     BookingsRepository,
     BookingPricingService,
+    ContainerValidationService,
     BookingInvoiceService,
     BookingLifecycleNotifierService,
     BookingTransitionService,
diff --git a/apps/edr-freight-api/src/modules/bookings/container-validation.service.ts b/apps/edr-freight-api/src/modules/bookings/container-validation.service.ts
index de4dca661..158ac14de 100644
--- a/apps/edr-freight-api/src/modules/bookings/container-validation.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/container-validation.service.ts
@@ -67,9 +67,16 @@ export class ContainerValidationService {
     const has20ft = containerLines.some((bc) => (bc.containerSize ?? '').includes('20'));
     if (!has20ft) return [];
 
-    const units = await this.load20ftUnits(booking);
-    if (units.length < 2) return [];
+    return this.validate20ftPairingUnits(await this.load20ftUnits(booking));
+  }
 
+  /**
+   * Same rule over units that are not (yet) persisted — a completion payload
+   * being previewed or submitted. Shipping-line completion uses this: its
+   * cargo only hits the DB after the check passes.
+   */
+  async validate20ftPairingUnits(units: Container20ftUnit[]): Promise<PairingViolation[]> {
+    if (units.length < 2) return [];
     const maxDiff = await this.maxPairDiffTons();
     return validate20ftWeightPairing(units, maxDiff);
   }
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.service.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.service.ts
index 0f7be3f18..ce5a7fad8 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.service.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-booking-completion.service.ts
@@ -10,6 +10,8 @@ import { In, Repository } from "typeorm";
 import { BookingPricingService } from "../bookings/booking-pricing.service";
 import { BookingTransitionService } from "../bookings/booking-transition.service";
 import { BookingsService } from "../bookings/bookings.service";
+import type { Container20ftUnit } from "../bookings/container-pairing.util";
+import { ContainerValidationService } from "../bookings/container-validation.service";
 import { BookingContainer } from "../bookings/entities/booking-container.entity";
 import { BookingContainerUnit } from "../bookings/entities/booking-container-unit.entity";
 import { Booking } from "../bookings/entities/booking.entity";
@@ -57,8 +59,35 @@ export class ShippingLineBookingCompletionService {
     private readonly trainSchedulingService: TrainSchedulingService,
     private readonly bookingBatchService: BookingBatchService,
     private readonly creditsService: ShippingLineCreditsService,
+    private readonly containerValidationService: ContainerValidationService,
   ) {}
 
+  /**
+   * 20ft weight-pairing check over the completion payload — the same rule the
+   * customer shipment form enforces (`max20ftPairWeightDiffTons`, default 10t):
+   * two 20ft sharing a wagon must be within the cap. Preview surfaces the
+   * messages; completion hard-blocks on them. Runs off the DTO so nothing is
+   * persisted before the check passes.
+   */
+  private async pairingViolationMessages(
+    dto: CompleteShippingLineBookingDto,
+  ): Promise<string[]> {
+    const units: Container20ftUnit[] = [];
+    for (const line of dto.containers ?? []) {
+      const containerType = await this.resolveContainerType(line);
+      if (containerType.sizeFt !== 20) continue;
+      (line.units ?? []).forEach((u, idx) =>
+        units.push({
+          label: u.containerNumber || `20ft-${idx + 1}`,
+          grossWeightTons: Number(u.vgmTons ?? 0),
+        }),
+      );
+    }
+    const violations =
+      await this.containerValidationService.validate20ftPairingUnits(units);
+    return violations.map((v) => v.message);
+  }
+
   /** Same session→owner resolution every shipping-line entry point uses. */
   private async requireShippingLine(userId: string) {
     const shippingLine =
@@ -193,6 +222,17 @@ export class ShippingLineBookingCompletionService {
       );
     }
 
+    // Unbalanced 20ft pairs can never be planned onto wagons — refuse before
+    // any cargo/credit write below. Same block the contract path applies.
+    if (booking.freightType === "CONTAINER") {
+      const pairing = await this.pairingViolationMessages(dto);
+      if (pairing.length) {
+        throw new BadRequestException(
+          `Cannot complete booking — 20ft containers cannot be paired on wagons: ${pairing.join(" ")}`,
+        );
+      }
+    }
+
     // Completion is booking time. A lane with trains DEDICATED to this line
     // has no window concept at all: the line books whenever it wants until the
     // train's close offset. Only a lane with no dedicated train falls back to
@@ -526,11 +566,21 @@ export class ShippingLineBookingCompletionService {
       computed.appliedModifiers,
     );
 
+    // Pairing is reported, not thrown: the confirm modal shows it next to the
+    // price (as the customer form does) and disables confirm; /complete
+    // hard-blocks the same payload.
+    const pairingErrors =
+      booking.freightType === "CONTAINER"
+        ? await this.pairingViolationMessages(dto)
+        : [];
+
     return {
       totalAmount: computed.totalAmount,
       currency: computed.currency,
       lineItems: computed.lineItems,
       warnings: computed.warnings,
+      overweightLines: computed.overweightLines,
+      pairingErrors,
     };
   }
 
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/controllers/train-scheduling.controller.ts b/apps/edr-freight-api/src/modules/train-scheduling/controllers/train-scheduling.controller.ts
index 93a187a95..54056404a 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/controllers/train-scheduling.controller.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/controllers/train-scheduling.controller.ts
@@ -5,7 +5,7 @@ import { UserTradeAccessService } from "../../user-trade-access/user-trade-acces
 import { resolveAuthUserId } from "../../../common/resolve-auth-user-id";
 
 import {
-  Body, Controller, Delete, Get, Param, ParseUUIDPipe, Patch, Post, Query, Res,
+  Body, Controller, Delete, Get, Param, ParseIntPipe, ParseUUIDPipe, Patch, Post, Query, Res,
 } from "@nestjs/common";
 import { CurrentUser } from "@edr/api-common";
 import {
@@ -37,7 +37,11 @@ import { UpdateImportLoadingStatusDto } from "../dto/update-import-loading-statu
 import { PreviewBulkTrainScheduleDto } from "../dto/preview-bulk-train-schedule.dto";
 import { PreviewContainerTrainScheduleDto } from "../dto/preview-container-train-schedule.dto";
 import { PreviewTrainScheduleDto } from "../dto/preview-train-schedule.dto";
-import { RecordCheckpointDto } from "../dto/record-checkpoint.dto";
+import {
+  DispatchScheduleDto,
+  RecordCheckpointDto,
+  UpdateCheckpointDto,
+} from "../dto/record-checkpoint.dto";
 import {
   ImportDjiboutiActionDto,
   UploadImportDjiboutiDocumentDto,
@@ -516,9 +520,14 @@ export class TrainSchedulingController {
 
   @Post("schedules/:id/dispatch")
   @BookingStaff(FREIGHT_PERMS.trainScheduling.dispatch)
-  @ApiOperation({ summary: "Dispatch a scheduled train" })
-  dispatchSchedule(@Param("id", ParseUUIDPipe) id: string) {
-    return this.trainSchedulingService.dispatchSchedule(id);
+  @ApiOperation({
+    summary: "Dispatch a scheduled train (optional actual departure time, past allowed)",
+  })
+  dispatchSchedule(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: DispatchScheduleDto,
+  ) {
+    return this.trainSchedulingService.dispatchSchedule(id, dto);
   }
 
   @Get("intercity/bookings")
@@ -956,6 +965,20 @@ export class TrainSchedulingController {
     return this.trainSchedulingService.recordCheckpoint(id, dto);
   }
 
+  @Patch("schedules/:id/checkpoints/:sequenceNo")
+  @TrainSchedulingUpdate()
+  @ApiOperation({
+    summary:
+      "Edit a logged leg's time/note (no side effects; allowed while dispatched or after arrival)",
+  })
+  updateCheckpoint(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Param("sequenceNo", ParseIntPipe) sequenceNo: number,
+    @Body() dto: UpdateCheckpointDto,
+  ) {
+    return this.trainSchedulingService.updateCheckpoint(id, sequenceNo, dto);
+  }
+
   @Post("schedules/:id/arrive")
   @TrainSchedulingUpdate()
   @ApiOperation({
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/dto/record-checkpoint.dto.ts b/apps/edr-freight-api/src/modules/train-scheduling/dto/record-checkpoint.dto.ts
index da7ebc0e7..1495185f0 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/dto/record-checkpoint.dto.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/dto/record-checkpoint.dto.ts
@@ -10,8 +10,6 @@ import {
   Min,
 } from 'class-validator';
 
-import { IsNotBackdated } from '../../../common/validators/is-not-backdated.validator';
-
 export class RecordCheckpointDto {
   @ApiProperty({ description: 'Station position along the route (0 = origin).' })
   @IsInt()
@@ -24,17 +22,17 @@ export class RecordCheckpointDto {
   kind?: TrainCheckpointKind;
 
   /**
-   * A checkpoint records where the train is as staff observe it, and the final
-   * one arrives the schedule — so a backdated value rewrites the journey after
-   * the fact. Only "now" is accepted; omit the field and the service stamps it.
+   * When the train was actually at the station — staff often log after the
+   * fact, so a past value is allowed. The service rejects the future and any
+   * value out of order with the neighbouring legs.
    */
   @ApiProperty({
     required: false,
-    description: 'ISO timestamp; defaults to now. Cannot be earlier than now.',
+    description:
+      'ISO timestamp; defaults to now. Past allowed, future rejected, must be in corridor order.',
   })
   @IsOptional()
   @IsISO8601()
-  @IsNotBackdated()
   occurredAt?: string;
 
   @ApiProperty({ required: false })
@@ -43,3 +41,30 @@ export class RecordCheckpointDto {
   @MaxLength(500)
   note?: string;
 }
+
+/** Edit an already-logged leg's time/note — no side effects (no unload, no arrival). */
+export class UpdateCheckpointDto {
+  @ApiProperty({
+    required: false,
+    description: 'ISO timestamp. Past allowed, future rejected, must be in corridor order.',
+  })
+  @IsOptional()
+  @IsISO8601()
+  occurredAt?: string;
+
+  @ApiProperty({ required: false, nullable: true })
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  note?: string | null;
+}
+
+export class DispatchScheduleDto {
+  @ApiProperty({
+    required: false,
+    description: 'Actual departure time; defaults to now. Past allowed, future rejected.',
+  })
+  @IsOptional()
+  @IsISO8601()
+  actualDepartureAt?: string;
+}
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
index 43a169058..ed099ad72 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
@@ -94,6 +94,7 @@ describe('TrainSchedulingService', () => {
   let wagonBookingAllocationsRepository: Record<string, jest.Mock>;
   let wagonAllocationContainerItemsRepository: Record<string, jest.Mock>;
   let wagonAllocationBulkLoadsRepository: Record<string, jest.Mock>;
+  let trainCheckpointEventsRepository: Record<string, jest.Mock>;
 
   beforeEach(() => {
     // findGroupSiblings runs a query builder off dataSource.manager; default it
@@ -127,6 +128,7 @@ describe('TrainSchedulingService', () => {
       findByIdWithFullGraph: jest.fn(),
       findAll: jest.fn(),
       updateStatus: jest.fn(),
+      update: jest.fn(),
       maxReferenceSequence: jest.fn().mockResolvedValue(0),
     };
     trainScheduleBookingsRepository = {
@@ -150,7 +152,7 @@ describe('TrainSchedulingService', () => {
       findAll: jest.fn().mockResolvedValue([]),
     };
 
-    const trainCheckpointEventsRepository = {
+    trainCheckpointEventsRepository = {
       findBySchedule: jest.fn().mockResolvedValue([]),
       findAll: jest.fn().mockResolvedValue([]),
       create: jest.fn(),
@@ -1638,6 +1640,61 @@ describe('TrainSchedulingService', () => {
     });
   });
 
+  describe('updateCheckpoint — leg time correction', () => {
+    const t = (h: number) => new Date(Date.UTC(2026, 0, 1, h));
+    const schedule = {
+      id: 'sch-track',
+      status: 'ARRIVED',
+      routeId: null,
+      originStationId: 'y0',
+      destinationStationId: 'y1',
+      actualDepartureAt: t(8),
+    };
+    const events = () => [
+      { id: 'e0', yardId: 'y0', sequenceNo: 0, kind: 'DEPARTED', occurredAt: t(8) },
+      { id: 'e1', yardId: 'y1', sequenceNo: 1, kind: 'ARRIVED', occurredAt: t(12) },
+    ];
+
+    beforeEach(() => {
+      trainSchedulesRepository.findByIdWithFullGraph.mockResolvedValue(schedule);
+      trainCheckpointEventsRepository.findBySchedule.mockImplementation(async () => events());
+    });
+
+    it('rejects a leg time earlier than the previous leg', async () => {
+      await expect(
+        service.updateCheckpoint('sch-track', 1, { occurredAt: t(7).toISOString() }),
+      ).rejects.toThrow(/cannot be earlier than/);
+      expect(trainCheckpointEventsRepository.update).not.toHaveBeenCalled();
+    });
+
+    it('rejects a leg time later than the next leg', async () => {
+      await expect(
+        service.updateCheckpoint('sch-track', 0, { occurredAt: t(13).toISOString() }),
+      ).rejects.toThrow(/cannot be later than/);
+    });
+
+    it('rejects a future time', async () => {
+      const future = new Date(Date.now() + 3_600_000).toISOString();
+      await expect(
+        service.updateCheckpoint('sch-track', 1, { occurredAt: future }),
+      ).rejects.toThrow(/future/);
+    });
+
+    it('accepts an in-order past time and re-stamps arrival for the final leg', async () => {
+      await service.updateCheckpoint('sch-track', 1, {
+        occurredAt: t(11).toISOString(),
+        note: 'late log',
+      });
+      expect(trainCheckpointEventsRepository.update).toHaveBeenCalledWith('e1', {
+        occurredAt: t(11),
+        note: 'late log',
+      });
+      expect(trainSchedulesRepository.update).toHaveBeenCalledWith('sch-track', {
+        actualArrivalAt: t(11),
+      });
+    });
+  });
+
   describe('effectiveWagonsRequired', () => {
     const effective = (booking: unknown): number =>
       (service as never as { effectiveWagonsRequired(b: unknown): number })
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index 73eb6fc31..2effe6a37 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -174,7 +174,11 @@ import {
 import { TrainCheckpointEvent } from '../entities/train-checkpoint-event.entity';
 import { BookingJourneyService } from '../booking-journey.service';
 import { TrainCheckpointEventsRepository } from '../repositories/train-checkpoint-events.repository';
-import { RecordCheckpointDto } from '../dto/record-checkpoint.dto';
+import {
+  DispatchScheduleDto,
+  RecordCheckpointDto,
+  UpdateCheckpointDto,
+} from '../dto/record-checkpoint.dto';
 import { RouteMilestone } from '../../routes/entities/route-milestone.entity';
 import { deriveTradeDirection } from '../../../common/derive-trade-direction.util';
 import { WarehouseInventoryService } from '../../warehouses/warehouse-inventory.service';
@@ -2645,7 +2649,7 @@ export class TrainSchedulingService {
     return this.getTrainScheduleById(scheduleId);
   }
 
-  async dispatchSchedule(scheduleId: string) {
+  async dispatchSchedule(scheduleId: string, dto: DispatchScheduleDto = {}) {
     const schedule = await this.trainSchedulesRepository.findByIdWithFullGraph(scheduleId);
     if (!schedule) {
       throw new NotFoundException(`Train schedule ${scheduleId} not found`);
@@ -2653,6 +2657,9 @@ export class TrainSchedulingService {
     if (schedule.status !== TrainScheduleStatusEnum.Scheduled) {
       throw new BadRequestException('Only SCHEDULED trains can be dispatched');
     }
+    // Staff may record the departure after the fact — past is fine, future is not.
+    const now = dto.actualDepartureAt ? new Date(dto.actualDepartureAt) : new Date();
+    this.assertNotFuture(now, 'Departure time');
     await this.assertImportDjiboutiMayDepart(schedule);
     // Cargo readiness (in the warehouse, not inspected, not loaded onto a wagon)
     // never blocks departure — the dispatch confirm dialog warns and staff decide.
@@ -2677,7 +2684,6 @@ export class TrainSchedulingService {
       }
     }
 
-    const now = new Date();
     await this.dataSource.transaction(async (manager) => {
       const trainNumber = await this.assignTrainNumber(manager, schedule);
       if (setLocomotiveIds.length) {
@@ -4160,6 +4166,7 @@ export class TrainSchedulingService {
           ? TrainCheckpointKind.Arrived
           : TrainCheckpointKind.Passed);
     const occurredAt = dto.occurredAt ? new Date(dto.occurredAt) : new Date();
+    await this.assertCheckpointTime(schedule, stations, dto.sequenceNo, occurredAt);
 
     // Upsert by (scheduleId, sequenceNo) so re-logging a station updates rather than duplicates.
     const [existing] = await this.trainCheckpointEventsRepository.findAll({
@@ -4183,8 +4190,14 @@ export class TrainSchedulingService {
       });
     }
 
+    // The origin DEPARTED checkpoint IS the departure — keep the schedule's
+    // headline timestamp on the same clock the operator just entered.
+    if (dto.sequenceNo === 0) {
+      await this.trainSchedulesRepository.update(scheduleId, { actualDepartureAt: occurredAt });
+    }
+
     if (dto.sequenceNo === finalSeq) {
-      await this.arriveSchedule(scheduleId);
+      await this.arriveSchedule(scheduleId, occurredAt);
     } else {
       // Mid-corridor auto-unload: bookings destined for this yard alight the
       // moment the train is recorded here — the yard operator no longer has to
@@ -4220,11 +4233,133 @@ export class TrainSchedulingService {
     return this.getScheduleCheckpoints(scheduleId);
   }
 
+  /**
+   * Correct an already-logged leg's time/note. Pure edit: no auto-unload, no
+   * position fix, no arrival — those already happened when the leg was logged.
+   * Allowed on DISPATCHED and ARRIVED trains (a journey is corrected after the
+   * fact as often as during it). The origin/final legs also re-stamp the
+   * schedule's departure/arrival so the headline figures follow the edit.
+   */
+  async updateCheckpoint(scheduleId: string, sequenceNo: number, dto: UpdateCheckpointDto) {
+    const schedule = await this.trainSchedulesRepository.findByIdWithFullGraph(scheduleId);
+    if (!schedule) {
+      throw new NotFoundException(`Train schedule ${scheduleId} not found`);
+    }
+    if (
+      schedule.status !== TrainScheduleStatusEnum.Dispatched &&
+      schedule.status !== TrainScheduleStatusEnum.Arrived
+    ) {
+      throw new BadRequestException('Only DISPATCHED or ARRIVED trains have checkpoints to edit');
+    }
+    const stations = await this.buildScheduleStations(schedule);
+    const station = stations.find((s) => s.sequenceNo === sequenceNo);
+    if (!station) {
+      throw new BadRequestException(`Station ${sequenceNo} is not on this route`);
+    }
+    // Match by yard, like getScheduleCheckpoints — legacy rows may carry an
+    // older station numbering.
+    const events = await this.trainCheckpointEventsRepository.findBySchedule(scheduleId);
+    const existing =
+      events.find((e) => e.yardId === station.yardId) ??
+      events.find((e) => e.sequenceNo === sequenceNo);
+    if (!existing) {
+      throw new BadRequestException(`Station ${station.label} has not been logged yet`);
+    }
+
+    const patch: Partial<TrainCheckpointEvent> = {};
+    if (dto.occurredAt) {
+      const occurredAt = new Date(dto.occurredAt);
+      await this.assertCheckpointTime(schedule, stations, sequenceNo, occurredAt, existing.id);
+      patch.occurredAt = occurredAt;
+    }
+    if (dto.note !== undefined) patch.note = dto.note;
+    if (Object.keys(patch).length) {
+      await this.trainCheckpointEventsRepository.update(existing.id, patch);
+    }
+
+    if (patch.occurredAt) {
+      const finalSeq = stations[stations.length - 1].sequenceNo;
+      if (sequenceNo === 0) {
+        await this.trainSchedulesRepository.update(scheduleId, {
+          actualDepartureAt: patch.occurredAt,
+        });
+      } else if (sequenceNo === finalSeq && schedule.status === TrainScheduleStatusEnum.Arrived) {
+        await this.trainSchedulesRepository.update(scheduleId, {
+          actualArrivalAt: patch.occurredAt,
+        });
+      }
+    }
+
+    return this.getScheduleCheckpoints(scheduleId);
+  }
+
+  private assertNotFuture(at: Date, what: string) {
+    if (Number.isNaN(at.getTime())) {
+      throw new BadRequestException(`${what} is not a valid date`);
+    }
+    // Small skew allowance so an honest "now" from a client clock passes.
+    if (at.getTime() > Date.now() + 60_000) {
+      throw new BadRequestException(`${what} cannot be in the future`);
+    }
+  }
+
+  /**
+   * A leg's time must not be in the future and must sit in corridor order:
+   * no earlier than every logged leg before it (and the dispatch time, for
+   * legs after the origin), no later than every logged leg after it.
+   * `ignoreEventId` excludes the row being edited from its own bounds.
+   */
+  private async assertCheckpointTime(
+    schedule: TrainSchedule,
+    stations: { sequenceNo: number; yardId: string; label: string }[],
+    sequenceNo: number,
+    occurredAt: Date,
+    ignoreEventId?: string,
+  ) {
+    this.assertNotFuture(occurredAt, 'Checkpoint time');
+
+    const seqByYard = new Map(stations.map((s) => [s.yardId, s.sequenceNo]));
+    const labelBySeq = new Map(stations.map((s) => [s.sequenceNo, s.label]));
+    const events = (await this.trainCheckpointEventsRepository.findBySchedule(schedule.id)).filter(
+      (e) => e.id !== ignoreEventId,
+    );
+    const seqOf = (e: TrainCheckpointEvent) => seqByYard.get(e.yardId) ?? e.sequenceNo;
+    const fmt = (d: Date) => d.toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
+
+    let floor: { at: Date; label: string } | null = null;
+    let ceil: { at: Date; label: string } | null = null;
+    for (const e of events) {
+      const s = seqOf(e);
+      if (s < sequenceNo && (!floor || e.occurredAt > floor.at)) {
+        floor = { at: e.occurredAt, label: labelBySeq.get(s) ?? `station ${s}` };
+      }
+      if (s > sequenceNo && (!ceil || e.occurredAt < ceil.at)) {
+        ceil = { at: e.occurredAt, label: labelBySeq.get(s) ?? `station ${s}` };
+      }
+    }
+    // The origin leg rewrites the departure itself; every later leg must
+    // follow it.
+    if (sequenceNo > 0 && schedule.actualDepartureAt && (!floor || schedule.actualDepartureAt > floor.at)) {
+      floor = { at: schedule.actualDepartureAt, label: 'departure' };
+    }
+
+    if (floor && occurredAt < floor.at) {
+      throw new BadRequestException(
+        `Checkpoint time cannot be earlier than ${floor.label} (${fmt(floor.at)})`,
+      );
+    }
+    if (ceil && occurredAt > ceil.at) {
+      throw new BadRequestException(
+        `Checkpoint time cannot be later than ${ceil.label} (${fmt(ceil.at)})`,
+      );
+    }
+  }
+
   /**
    * Mark a dispatched train arrived: close out the schedule, move the locomotive
    * and wagons to the destination yard, and free the assets for re-use.
    */
-  async arriveSchedule(scheduleId: string) {
+  async arriveSchedule(scheduleId: string, arrivedAt?: Date) {
     const schedule = await this.trainSchedulesRepository.findByIdWithFullGraph(scheduleId);
     if (!schedule) {
       throw new NotFoundException(`Train schedule ${scheduleId} not found`);
@@ -4233,7 +4368,9 @@ export class TrainSchedulingService {
       throw new BadRequestException('Only DISPATCHED trains can arrive');
     }
 
-    const now = new Date();
+    // The arrival clock: the operator's entered time when arriving via the final
+    // checkpoint (already order/future-checked there), else now.
+    const now = arrivedAt ?? new Date();
 
     await this.dataSource.transaction(async (manager) => {
       await this.trainSchedulesRepository.updateStatus(
@@ -9025,33 +9162,88 @@ export class TrainSchedulingService {
       throw new BadRequestException('Source wagon has no load to move');
     }
 
-    // Target: a slot of this train set, or an empty consist-only wagon of the
-    // built train (physical wagon with no slot row yet).
+    // Leg spans: a physical wagon carries one slot PER LEG (cross-leg sharing —
+    // Gelan→Adama and Adama→Doraleh loads ride the same wagon in two slots), so
+    // "the slot on that wagon" only means the one whose leg overlaps the moving
+    // load's leg. Null board/alight = the schedule's own endpoints.
+    const stops = await this.stopYardsForSchedule(schedule);
+    const spanOf = (slot: {
+      boardYardId?: string | null;
+      alightYardId?: string | null;
+    }): [number, number] => {
+      const from = slot.boardYardId ? stops.indexOf(slot.boardYardId) : 0;
+      const to = slot.alightYardId ? stops.indexOf(slot.alightYardId) : stops.length - 1;
+      return [from < 0 ? 0 : from, to < 0 ? Math.max(1, stops.length - 1) : to];
+    };
+    const overlaps = (a: [number, number], b: [number, number]) => a[0] < b[1] && b[0] < a[1];
+    const sourceSpan = spanOf(source);
+
+    // Target: a slot of this train set, or a physical wagon of this train —
+    // coupled-but-empty consist wagon (built train), or a wagon already pinned
+    // by another slot of this set (then: the overlapping-leg slot, or a fresh
+    // slot for a free leg).
     const slotById = slots.find((w) => w.id === dto.targetWagonId) ?? null;
-    const wagonForTarget = slotById
-      ? null
-      : schedule.trainSet?.trainId
-        ? await this.dataSource.getRepository(Wagon).findOne({
-            where: { id: dto.targetWagonId, trainId: schedule.trainSet.trainId },
-            relations: { wagonType: true },
-          })
-        : null;
+    let wagonForTarget: Wagon | null = null;
+    if (!slotById) {
+      const wagon = await this.dataSource.getRepository(Wagon).findOne({
+        where: { id: dto.targetWagonId },
+        relations: { wagonType: true },
+      });
+      const onThisTrain =
+        !!wagon &&
+        ((!!schedule.trainSet?.trainId && wagon.trainId === schedule.trainSet.trainId) ||
+          slots.some((w) => w.physicalWagonId === wagon.id));
+      wagonForTarget = onThisTrain ? wagon : null;
+    }
     if (!slotById && !wagonForTarget) {
       throw new NotFoundException('Target wagon is not part of this schedule');
     }
-    // A physical wagon holds at most one slot. When the caller addressed the
-    // wagon directly but a slot is already pinned to it, move into that slot
-    // rather than minting a second one on the same wagon.
     const targetSlot =
       slotById ??
       (wagonForTarget
-        ? (slots.find((w) => w.physicalWagonId === wagonForTarget.id) ?? null)
+        ? (slots.find(
+            (w) =>
+              w.physicalWagonId === wagonForTarget.id && overlaps(spanOf(w), sourceSpan),
+          ) ?? null)
         : null);
     const consistWagon = targetSlot ? null : wagonForTarget;
+
+    // Leg clash guard: after the move, no two slots on one physical wagon may
+    // ride the same edge. Source load → target wagon; on a swap, target load →
+    // source wagon.
+    const targetPhysicalId = targetSlot?.physicalWagonId ?? consistWagon?.id ?? null;
+    const clashOn = (
+      physicalWagonId: string | null,
+      excludeSlotId: string | null,
+      span: [number, number],
+    ) =>
+      !!physicalWagonId &&
+      slots.some(
+        (w) =>
+          w.physicalWagonId === physicalWagonId &&
+          w.id !== excludeSlotId &&
+          w.id !== source.id &&
+          (w.allocations?.length ?? 0) > 0 &&
+          overlaps(spanOf(w), span),
+      );
+    if (clashOn(targetPhysicalId, targetSlot?.id ?? null, sourceSpan)) {
+      throw new BadRequestException(
+        'That wagon already carries another load on the same leg — pick a wagon free on that leg.',
+      );
+    }
     const targetAllocs = targetSlot ? await loadAllocations(targetSlot.id) : [];
     if (targetSlot && targetSlot.id === source.id) {
       return this.getTrainScheduleById(scheduleId);
     }
+    if (
+      targetSlot &&
+      targetAllocs.length &&
+      clashOn(source.physicalWagonId ?? null, source.id, spanOf(targetSlot))
+    ) {
+      throw new BadRequestException(
+        'Swap refused: the source wagon already carries another load on the incoming load’s leg.',
+      );
+    }
 
     const loadTypesOf = (allocs: WagonBookingAllocation[]) => [
       ...new Set(allocs.map((a) => (a.loadType ?? 'CONTAINER').toUpperCase())),
diff --git a/apps/edr-freight-api/src/modules/wagons/wagons.service.ts b/apps/edr-freight-api/src/modules/wagons/wagons.service.ts
index 2d8950fb4..b5a14f6f3 100644
--- a/apps/edr-freight-api/src/modules/wagons/wagons.service.ts
+++ b/apps/edr-freight-api/src/modules/wagons/wagons.service.ts
@@ -121,8 +121,46 @@ export class WagonsService {
    * (yard workspace, coupling pickers) walk the pages client-side — see
    * `wagonService.listAll` in the backoffice.
    */
-  findAll(query: ListWagonsQueryDto = {}): Promise<PaginatedResponse<Wagon>> {
-    return paginateQuery(this.buildListQuery(query), query, { defaultPageSize: 10 });
+  async findAll(query: ListWagonsQueryDto = {}): Promise<PaginatedResponse<Wagon>> {
+    const page = await paginateQuery(this.buildListQuery(query), query, { defaultPageSize: 10 });
+    await this.attachStatusDates(page.items);
+    return page;
+  }
+
+  /**
+   * Latest status-flip dates from the audit log, for the wagons desk columns:
+   * when the wagon last went to MAINTENANCE and when it last became AVAILABLE.
+   * One grouped query per page; null when the log has no such flip.
+   */
+  private async attachStatusDates(wagons: Wagon[]): Promise<void> {
+    if (!wagons.length) return;
+    const rows: Array<{
+      wagonId: string;
+      lastMaintenanceAt: Date | null;
+      lastAvailableAt: Date | null;
+    }> = await this.dataSource
+      .getRepository(WagonStatusLog)
+      .createQueryBuilder('l')
+      .select('l.wagon_id', 'wagonId')
+      .addSelect(
+        `MAX(l.created_at) FILTER (WHERE l.to_status = '${WagonStatus.Maintenance}')`,
+        'lastMaintenanceAt',
+      )
+      .addSelect(
+        `MAX(l.created_at) FILTER (WHERE l.to_status = '${WagonStatus.Available}')`,
+        'lastAvailableAt',
+      )
+      .where('l.wagon_id IN (:...ids)', { ids: wagons.map((w) => w.id) })
+      .groupBy('l.wagon_id')
+      .getRawMany();
+    const byId = new Map(rows.map((r) => [r.wagonId, r]));
+    for (const w of wagons) {
+      const r = byId.get(w.id);
+      Object.assign(w, {
+        lastMaintenanceAt: r?.lastMaintenanceAt ?? null,
+        lastAvailableAt: r?.lastAvailableAt ?? null,
+      });
+    }
   }
 
   async findById(id: string): Promise<Wagon> {
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/CheckpointTimeModal.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/CheckpointTimeModal.tsx
new file mode 100644
index 000000000..6d748b559
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/CheckpointTimeModal.tsx
@@ -0,0 +1,103 @@
+import { Button, Group, Modal, Stack, Text, Textarea } from "@mantine/core";
+import { DateTimePicker } from "@mantine/dates";
+import { useEffect, useState } from "react";
+
+/**
+ * Time + note for one leg of a train's journey — used both to log a pass
+ * (defaults to now) and to correct an already-logged leg (prefilled). Past
+ * times are allowed (staff record after the fact); the future is not, and the
+ * server additionally keeps legs in corridor order.
+ */
+export function CheckpointTimeModal({
+  opened,
+  onClose,
+  title,
+  icon,
+  description,
+  initialOccurredAt,
+  initialNote,
+  submitLabel,
+  submitColor = "edr-green",
+  loading,
+  onSubmit,
+}: {
+  opened: boolean;
+  onClose: () => void;
+  title: string;
+  icon?: React.ReactNode;
+  description?: string;
+  /** ISO; omit to default to now. */
+  initialOccurredAt?: string | null;
+  initialNote?: string | null;
+  submitLabel: string;
+  submitColor?: string;
+  loading: boolean;
+  onSubmit: (values: { occurredAt: string; note: string }) => void;
+}) {
+  const [at, setAt] = useState<Date | null>(null);
+  const [note, setNote] = useState("");
+  useEffect(() => {
+    if (!opened) return;
+    setAt(initialOccurredAt ? new Date(initialOccurredAt) : new Date());
+    setNote(initialNote ?? "");
+  }, [opened, initialOccurredAt, initialNote]);
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      centered
+      radius="lg"
+      title={
+        <Group gap={8}>
+          {icon}
+          <Text fw={700}>{title}</Text>
+        </Group>
+      }
+    >
+      <Stack gap="md">
+        {description ? (
+          <Text size="sm" c="dimmed">
+            {description}
+          </Text>
+        ) : null}
+        <DateTimePicker
+          label="Time"
+          description="Defaults to now — pick an earlier time if you are recording after the fact."
+          value={at}
+          onChange={(v) => setAt(v ? new Date(v) : null)}
+          maxDate={new Date()}
+          valueFormat="DD MMM YYYY HH:mm"
+          clearable={false}
+          radius="md"
+        />
+        <Textarea
+          label="Note"
+          placeholder="Optional"
+          value={note}
+          onChange={(e) => setNote(e.currentTarget.value)}
+          autosize
+          minRows={2}
+          maxRows={4}
+          maxLength={500}
+          radius="md"
+        />
+        <Group justify="flex-end" gap="sm">
+          <Button variant="default" onClick={onClose} disabled={loading}>
+            Cancel
+          </Button>
+          <Button
+            color={submitColor}
+            loading={loading}
+            disabled={!at}
+            onClick={() =>
+              at && onSubmit({ occurredAt: at.toISOString(), note: note.trim() })
+            }
+          >
+            {submitLabel}
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/LegLoadBoardPanel.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/LegLoadBoardPanel.tsx
new file mode 100644
index 000000000..04b5e77de
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/LegLoadBoardPanel.tsx
@@ -0,0 +1,423 @@
+import { Fragment, useEffect, useMemo, useState } from "react";
+import { useMutation } from "@tanstack/react-query";
+import { isAxiosError } from "axios";
+import {
+  Alert,
+  Badge,
+  Button,
+  Group,
+  Paper,
+  Stack,
+  Table,
+  Text,
+  Tooltip,
+} from "@mantine/core";
+import { ArrowLeftRight, Boxes, Info, MoveRight, Wheat, X } from "lucide-react";
+
+import { api } from "@/services/api";
+import { useToast } from "@/hooks/use-toast";
+import type { TrainScheduleDetail } from "@/types/trainScheduling";
+
+type Slot = NonNullable<TrainScheduleDetail["trainSet"]>["wagons"][number];
+type Stop = { yardId: string; label: string };
+type Span = [number, number];
+
+/** One physical wagon of the consist with every slot (leg load) pinned to it. */
+interface WagonRow {
+  key: string;
+  physicalWagonId: string | null;
+  label: string;
+  position: number;
+  typeCode: string | null;
+  capacityTons: number;
+  slots: Array<{ slot: Slot; span: Span; loaded: boolean }>;
+}
+
+const round1 = (n: number) => Math.round(n * 10) / 10;
+const overlaps = (a: Span, b: Span) => a[0] < b[1] && b[0] < a[1];
+
+/**
+ * Leg board: rows = physical wagons in coupling order, columns = corridor legs
+ * (A→B, B→C, …). A wagon reused on disjoint legs shows one load per leg on the
+ * same row, so a "53 full on A→B, 53 full on C→D" train reads at a glance.
+ * Loads move by click: pick a load, then click a wagon that is free on that
+ * load's legs (move) or another load (swap). Same API as the consist strip.
+ */
+export function LegLoadBoardPanel({
+  schedule,
+  onChanged,
+}: {
+  schedule: TrainScheduleDetail;
+  onChanged?: () => void;
+}) {
+  const { toast } = useToast();
+  const stops: Stop[] = schedule.stops ?? [];
+  const legs = useMemo(
+    () => stops.slice(0, -1).map((from, i) => ({ from, to: stops[i + 1], idx: i })),
+    [stops],
+  );
+  const canRearrange = !["DISPATCHED", "ARRIVED", "CANCELLED"].includes(schedule.status);
+
+  const spanOf = (slot: Slot): Span => {
+    const from = slot.boardYardId ? stops.findIndex((s) => s.yardId === slot.boardYardId) : 0;
+    const to = slot.alightYardId
+      ? stops.findIndex((s) => s.yardId === slot.alightYardId)
+      : stops.length - 1;
+    return [from < 0 ? 0 : from, to < 0 ? Math.max(1, stops.length - 1) : to];
+  };
+
+  const rows: WagonRow[] = useMemo(() => {
+    const byKey = new Map<string, WagonRow>();
+    for (const slot of schedule.trainSet?.wagons ?? []) {
+      const key = slot.physicalWagonId ?? `slot:${slot.id}`;
+      let row = byKey.get(key);
+      if (!row) {
+        row = {
+          key,
+          physicalWagonId: slot.physicalWagonId ?? null,
+          label: slot.physicalWagonNumber ?? `#${slot.position ?? slot.sequenceNo}`,
+          position: slot.position ?? slot.sequenceNo,
+          typeCode: slot.wagonType?.code ?? null,
+          capacityTons: slot.capacityTons ?? 0,
+          slots: [],
+        };
+        byKey.set(key, row);
+      }
+      row.position = Math.min(row.position, slot.position ?? slot.sequenceNo);
+      // Coupled-but-empty consist wagons carry no slot row: they are a target only.
+      if (!slot.consistOnly) {
+        row.slots.push({
+          slot,
+          span: spanOf(slot),
+          loaded: (slot.allocations?.length ?? 0) > 0,
+        });
+      }
+    }
+    return [...byKey.values()].sort((a, b) => a.position - b.position);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [schedule.trainSet?.wagons, stops]);
+
+  const [picked, setPicked] = useState<{ slotId: string; rowKey: string; span: Span } | null>(
+    null,
+  );
+  useEffect(() => {
+    if (!picked) return;
+    const onKey = (e: KeyboardEvent) => e.key === "Escape" && setPicked(null);
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [picked]);
+
+  const moveMutation = useMutation(api.trainScheduling.moveWagonLoad.mutationOptions());
+  const doMove = async (targetWagonId: string, swap: boolean) => {
+    if (!picked || moveMutation.isPending) return;
+    try {
+      await moveMutation.mutateAsync({
+        scheduleId: schedule.id,
+        wagonId: picked.slotId,
+        targetWagonId,
+      });
+      toast({ title: swap ? "Loads swapped" : "Load moved" });
+      setPicked(null);
+      onChanged?.();
+    } catch (error) {
+      const message = isAxiosError(error)
+        ? ((error.response?.data as { message?: string | string[] } | undefined)?.message ??
+          null)
+        : null;
+      toast({
+        title: "Could not move the load",
+        description: Array.isArray(message)
+          ? message.join(", ")
+          : (message ?? "The move was rejected — check wagon type, payload and leg."),
+        variant: "destructive",
+      });
+    }
+  };
+
+  if (stops.length < 2) {
+    return (
+      <Alert color="gray" icon={<Info size={16} />} radius="md">
+        This schedule has no corridor stops yet — the leg board needs a route with at least
+        two stops.
+      </Alert>
+    );
+  }
+  if (!rows.length) {
+    return (
+      <Alert color="gray" icon={<Info size={16} />} radius="md">
+        No wagons on this train yet.
+      </Alert>
+    );
+  }
+
+  const sharedRows = rows.filter((r) => r.slots.filter((s) => s.loaded).length > 1).length;
+
+  return (
+    <Stack gap="md">
+      <Group justify="space-between" align="flex-start" wrap="wrap">
+        <Stack gap={2}>
+          <Text fw={700} size="sm">
+            Loads per wagon per leg
+          </Text>
+          <Text size="xs" c="dimmed">
+            One row per physical wagon, one column per leg. A wagon reused on different legs
+            shows one load per leg.{" "}
+            {canRearrange
+              ? "Click a load to pick it up, then click a wagon free on those legs to move it, or another load to swap."
+              : "Read-only — the train has departed."}
+          </Text>
+        </Stack>
+        <Group gap="xs">
+          {sharedRows > 0 ? (
+            <Badge variant="light" color="violet" radius="sm">
+              {sharedRows} wagon{sharedRows === 1 ? "" : "s"} shared across legs
+            </Badge>
+          ) : null}
+          {picked ? (
+            <Button
+              size="xs"
+              variant="default"
+              leftSection={<X size={14} />}
+              onClick={() => setPicked(null)}
+            >
+              Cancel move (Esc)
+            </Button>
+          ) : null}
+        </Group>
+      </Group>
+
+      <Paper withBorder radius="md" style={{ overflowX: "auto" }}>
+        <Table verticalSpacing={6} horizontalSpacing="sm" style={{ minWidth: 640 }}>
+          <Table.Thead>
+            <Table.Tr>
+              <Table.Th style={{ position: "sticky", left: 0, background: "var(--mantine-color-body)", zIndex: 1, width: 180 }}>
+                Wagon
+              </Table.Th>
+              {legs.map((leg) => (
+                <Table.Th key={leg.idx} style={{ minWidth: 200 }}>
+                  <Group gap={4} wrap="nowrap">
+                    <Text size="xs" fw={700} truncate>
+                      {leg.from.label}
+                    </Text>
+                    <MoveRight size={12} />
+                    <Text size="xs" fw={700} truncate>
+                      {leg.to.label}
+                    </Text>
+                  </Group>
+                </Table.Th>
+              ))}
+              <Table.Th style={{ width: 110 }}>Cargo</Table.Th>
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            {rows.map((row) => {
+              const cargoTons = row.slots.reduce(
+                (s, x) =>
+                  s +
+                  ((x.slot.allocations ?? []).reduce(
+                    (a, al) => a + (al.allocatedWeightTons ?? 0),
+                    0,
+                  ) || x.slot.assignedWeightTons || 0),
+                0,
+              );
+              const isPickedRow = picked?.rowKey === row.key;
+              // A row can take the picked load when nothing loaded on it rides
+              // any of the picked load's legs.
+              const rowFreeForPicked =
+                !!picked &&
+                !isPickedRow &&
+                !row.slots.some((s) => s.loaded && overlaps(s.span, picked.span));
+              // Where a "move here" lands: an existing empty slot on those legs,
+              // else the physical wagon itself (the API mints the slot).
+              const emptyTargetSlot = picked
+                ? row.slots.find((s) => !s.loaded && overlaps(s.span, picked.span))
+                : undefined;
+              const moveTargetId = emptyTargetSlot?.slot.id ?? row.physicalWagonId ?? null;
+
+              // Lay slots into leg columns; uncovered legs render as empty cells.
+              const cells: React.ReactNode[] = [];
+              let col = 0;
+              const sorted = [...row.slots].sort((a, b) => a.span[0] - b.span[0]);
+              // Empty cell = uncovered leg (target: the physical wagon) or an
+              // empty slot (target: that slot). Both take the picked load when
+              // the row is free on its legs.
+              const emptyCell = (from: number, to: number, targetId = moveTargetId) => {
+                const droppable = rowFreeForPicked && canRearrange && !!targetId &&
+                  !!picked && overlaps([from, to], picked.span);
+                return (
+                  <Table.Td
+                    key={`e-${from}`}
+                    colSpan={Math.max(1, to - from)}
+                    onClick={droppable ? () => void doMove(targetId!, false) : undefined}
+                    style={{
+                      cursor: droppable ? "pointer" : "default",
+                      background: droppable ? "var(--mantine-color-teal-0)" : undefined,
+                      outline: droppable ? "1px dashed var(--mantine-color-teal-5)" : undefined,
+                      outlineOffset: -3,
+                      borderRadius: 6,
+                    }}
+                  >
+                    {droppable ? (
+                      <Text size="xs" c="teal.7" fw={600} ta="center">
+                        Move here
+                      </Text>
+                    ) : (
+                      <Text size="xs" c="dimmed" ta="center">
+                        —
+                      </Text>
+                    )}
+                  </Table.Td>
+                );
+              };
+              for (const s of sorted) {
+                if (s.span[0] > col) cells.push(emptyCell(col, s.span[0]));
+                if (!s.loaded) {
+                  cells.push(emptyCell(s.span[0], s.span[1], s.slot.id));
+                  col = Math.max(col, s.span[1]);
+                  continue;
+                }
+                const isPicked = picked?.slotId === s.slot.id;
+                const swappable =
+                  !!picked && !isPicked && !isPickedRow && s.loaded && canRearrange;
+                const allocs = s.slot.allocations ?? [];
+                const bulk = allocs.some((a) => (a.loadType ?? "CONTAINER").toUpperCase() === "BULK");
+                const containers = allocs.flatMap((a) => a.containerItems ?? []);
+                cells.push(
+                  <Table.Td
+                    key={s.slot.id}
+                    colSpan={Math.max(1, s.span[1] - s.span[0])}
+                    onClick={
+                      !canRearrange
+                        ? undefined
+                        : s.loaded && !picked
+                          ? () => setPicked({ slotId: s.slot.id, rowKey: row.key, span: s.span })
+                          : swappable
+                            ? () => void doMove(s.slot.id, true)
+                            : isPicked
+                              ? () => setPicked(null)
+                              : undefined
+                    }
+                    style={{
+                      cursor: canRearrange && (s.loaded || swappable) ? "pointer" : "default",
+                      padding: 4,
+                    }}
+                  >
+                    {s.loaded ? (
+                      <Paper
+                        radius="sm"
+                        px={8}
+                        py={6}
+                        style={{
+                          background: bulk
+                            ? "var(--mantine-color-orange-0)"
+                            : "var(--mantine-color-cyan-0)",
+                          borderLeft: `4px solid ${
+                            bulk ? "var(--mantine-color-orange-6)" : "var(--mantine-color-cyan-6)"
+                          }`,
+                          outline: isPicked
+                            ? "2px solid var(--mantine-color-edr-green-6)"
+                            : swappable
+                              ? "1px dashed var(--mantine-color-orange-6)"
+                              : undefined,
+                          outlineOffset: 1,
+                        }}
+                      >
+                        <Group gap={6} wrap="nowrap" justify="space-between">
+                          <Group gap={6} wrap="nowrap">
+                            {bulk ? <Wheat size={13} /> : <Boxes size={13} />}
+                            <Text size="xs" fw={700} truncate>
+                              {[...new Set(allocs.map((a) => a.bookingReference ?? "—"))].join(", ")}
+                            </Text>
+                          </Group>
+                          <Text size="xs" c="dimmed" style={{ whiteSpace: "nowrap" }}>
+                            {round1(
+                              allocs.reduce((a, al) => a + (al.allocatedWeightTons ?? 0), 0),
+                            )}{" "}
+                            t
+                          </Text>
+                        </Group>
+                        <Group gap={4} mt={2} wrap="wrap">
+                          {bulk
+                            ? allocs.map((a) =>
+                                a.bulkLoad ? (
+                                  <Badge key={a.id} size="xs" variant="light" color="orange" radius="sm">
+                                    {a.bulkLoad.cargoDescription ?? "Bulk"} · {round1(a.bulkLoad.weightTons)} t
+                                  </Badge>
+                                ) : null,
+                              )
+                            : containers.map((c) => (
+                                <Badge key={c.id} size="xs" variant="light" color="cyan" radius="sm">
+                                  {c.containerNumber ?? "no number"}
+                                </Badge>
+                              ))}
+                          {swappable ? (
+                            <Badge size="xs" color="orange" radius="sm" leftSection={<ArrowLeftRight size={10} />}>
+                              swap
+                            </Badge>
+                          ) : null}
+                        </Group>
+                      </Paper>
+                    ) : (
+                      <Text size="xs" c="dimmed" ta="center">
+                        empty
+                      </Text>
+                    )}
+                  </Table.Td>,
+                );
+                col = Math.max(col, s.span[1]);
+              }
+              if (col < legs.length) cells.push(emptyCell(col, legs.length));
+
+              return (
+                <Table.Tr
+                  key={row.key}
+                  style={{
+                    background: isPickedRow
+                      ? "var(--mantine-color-green-0)"
+                      : rowFreeForPicked
+                        ? undefined
+                        : picked
+                          ? "var(--mantine-color-gray-0)"
+                          : undefined,
+                    opacity: picked && !isPickedRow && !rowFreeForPicked ? 0.55 : 1,
+                  }}
+                >
+                  <Table.Td style={{ position: "sticky", left: 0, background: "var(--mantine-color-body)", zIndex: 1 }}>
+                    <Group gap={6} wrap="nowrap">
+                      <Badge variant="outline" color="gray" radius="sm" size="sm">
+                        #{row.position}
+                      </Badge>
+                      <Stack gap={0}>
+                        <Text size="sm" fw={700}>
+                          {row.label}
+                        </Text>
+                        <Text size="xs" c="dimmed">
+                          {row.typeCode ?? "—"} · {round1(row.capacityTons)} t
+                        </Text>
+                      </Stack>
+                      {row.slots.filter((s) => s.loaded).length > 1 ? (
+                        <Tooltip label="This wagon carries different loads on different legs">
+                          <Badge size="xs" color="violet" variant="light" radius="sm">
+                            shared
+                          </Badge>
+                        </Tooltip>
+                      ) : null}
+                    </Group>
+                  </Table.Td>
+                  {cells.map((c, i) => (
+                    <Fragment key={i}>{c}</Fragment>
+                  ))}
+                  <Table.Td>
+                    <Text size="xs" fw={600} c={cargoTons > row.capacityTons + 0.001 ? "red.7" : undefined}>
+                      {round1(cargoTons)} / {round1(row.capacityTons)} t
+                    </Text>
+                  </Table.Td>
+                </Table.Tr>
+              );
+            })}
+          </Table.Tbody>
+        </Table>
+      </Paper>
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/LogPassYardWorkModal.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/LogPassYardWorkModal.tsx
index 0e1db09be..06d15da77 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/LogPassYardWorkModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/LogPassYardWorkModal.tsx
@@ -12,6 +12,7 @@ import {
   ThemeIcon,
   Tooltip,
 } from "@mantine/core";
+import { DateTimePicker } from "@mantine/dates";
 import { useMutation, useQuery } from "@tanstack/react-query";
 import {
   CheckCircle2,
@@ -111,7 +112,12 @@ export function LogPassYardWorkModal({
 }) {
   const { toast } = useToast();
   const [justLogged, setJustLogged] = useState(false);
-  useEffect(() => setJustLogged(false), [station?.sequenceNo, opened]);
+  // When the train was here — defaults to now, past allowed (recorded after the fact).
+  const [passAt, setPassAt] = useState<Date | null>(null);
+  useEffect(() => {
+    setJustLogged(false);
+    setPassAt(new Date());
+  }, [station?.sequenceNo, opened]);
   const logged = alreadyLogged || justLogged;
 
   const yardWorkQuery = useQuery(
@@ -133,7 +139,13 @@ export function LogPassYardWorkModal({
   const doLogPass = () => {
     if (!station) return;
     recordCheckpoint.mutate(
-      { id: scheduleId, payload: { sequenceNo: station.sequenceNo } },
+      {
+        id: scheduleId,
+        payload: {
+          sequenceNo: station.sequenceNo,
+          ...(passAt ? { occurredAt: passAt.toISOString() } : {}),
+        },
+      },
       {
         onSuccess: () => {
           setJustLogged(true);
@@ -373,6 +385,20 @@ export function LogPassYardWorkModal({
           </>
         )}
 
+        {!logged ? (
+          <DateTimePicker
+            label={isFinal ? "Arrival time" : "Time at station"}
+            description="Defaults to now — pick an earlier time if you are recording after the fact."
+            value={passAt}
+            onChange={(v) => setPassAt(v ? new Date(v) : null)}
+            maxDate={new Date()}
+            valueFormat="DD MMM YYYY HH:mm"
+            clearable={false}
+            radius="md"
+            maw={320}
+          />
+        ) : null}
+
         <Group justify="space-between" mt="xs">
           <Text size="xs" c="dimmed">
             {logged && pendingBoarders.length > 0
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/RouteCorridorTrack.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/RouteCorridorTrack.tsx
index d6f0b92e5..d3181b424 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/RouteCorridorTrack.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/RouteCorridorTrack.tsx
@@ -1,6 +1,6 @@
 import { Fragment } from "react";
 import { Badge, Box, Button, Group, Stack, Text } from "@mantine/core";
-import { Check, Flag, MapPin, Train } from "lucide-react";
+import { Check, Flag, MapPin, Pencil, Train } from "lucide-react";
 
 import { freightBrand } from "@/theme/freight-brand";
 import type { TrainCheckpoint, TrackStation } from "@/types/trainScheduling";
@@ -14,6 +14,8 @@ export interface RouteCorridorTrackProps {
   canLog: boolean;
   loggingSeq?: number | null;
   onLogCheckpoint?: (sequenceNo: number) => void;
+  /** Present when logged legs may be corrected (dispatched or arrived). */
+  onEditCheckpoint?: (checkpoint: TrainCheckpoint) => void;
 }
 
 const COLUMN_WIDTH = 150;
@@ -31,6 +33,7 @@ export function RouteCorridorTrack({
   canLog,
   loggingSeq,
   onLogCheckpoint,
+  onEditCheckpoint,
 }: RouteCorridorTrackProps) {
   const bySeq = new Map(checkpoints.map((c) => [c.sequenceNo, c]));
   const lastIndex = stations.length - 1;
@@ -160,14 +163,28 @@ export function RouteCorridorTrack({
 
                 {/* checkpoint time or action */}
                 {checkpoint ? (
-                  <Text size="10px" c="dimmed" ta="center">
-                    {new Date(checkpoint.occurredAt).toLocaleString(undefined, {
-                      month: "short",
-                      day: "numeric",
-                      hour: "2-digit",
-                      minute: "2-digit",
-                    })}
-                  </Text>
+                  <Stack gap={2} align="center">
+                    <Text size="10px" c="dimmed" ta="center">
+                      {new Date(checkpoint.occurredAt).toLocaleString(undefined, {
+                        month: "short",
+                        day: "numeric",
+                        hour: "2-digit",
+                        minute: "2-digit",
+                      })}
+                    </Text>
+                    {onEditCheckpoint ? (
+                      <Button
+                        size="compact-xs"
+                        radius="md"
+                        variant="subtle"
+                        color="gray"
+                        leftSection={<Pencil size={11} />}
+                        onClick={() => onEditCheckpoint(checkpoint)}
+                      >
+                        Edit time
+                      </Button>
+                    ) : null}
+                  </Stack>
                 ) : isNext ? (
                   <Button
                     size="compact-xs"
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index df19cfd60..41d42547f 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -483,6 +483,8 @@ export const URL_CONSTANTS = {
       `/train-scheduling/schedules/${id}/intercity/marshalling/document`,
     CHECKPOINTS: (id: string) =>
       `/train-scheduling/schedules/${id}/checkpoints`,
+    CHECKPOINT: (id: string, sequenceNo: number) =>
+      `/train-scheduling/schedules/${id}/checkpoints/${sequenceNo}`,
     ARRIVE: (id: string) => `/train-scheduling/schedules/${id}/arrive`,
     RESCHEDULE_PREVIEW: (id: string) =>
       `/train-scheduling/schedules/${id}/reschedule/preview`,
diff --git a/apps/edr-freight-web/backoffice/src/pages/fleet/config/resources.ts b/apps/edr-freight-web/backoffice/src/pages/fleet/config/resources.ts
index 11ca236be..526181d44 100644
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/config/resources.ts
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/config/resources.ts
@@ -353,6 +353,10 @@ export const FLEET_RESOURCES: FleetResourceConfig[] = [
       { id: "importTrainNumber", header: "Import train no.", accessorKey: "importTrainNumber", format: "code" },
       { id: "currentYard", header: "Current Yard", accessorKey: "currentYard", format: "entityLabel" },
       { id: "status", header: "Status", accessorKey: "status", format: "statusBadge" },
+      // From the status-flip log: last time the wagon went to maintenance, and
+      // last time it became available again (dash = never logged).
+      { id: "lastMaintenanceAt", header: "Last to maintenance", accessorKey: "lastMaintenanceAt", format: "date" },
+      { id: "lastAvailableAt", header: "Available since", accessorKey: "lastAvailableAt", format: "date" },
     ],
     formFields: [
       // Run numbers are optional — a wagon sits in the fleet unassigned to any
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoiceDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoiceDetailPage.tsx
index ef7f9d086..2b5e78646 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoiceDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoiceDetailPage.tsx
@@ -77,9 +77,31 @@ function InfoField({
   );
 }
 
-/** Billed-to company, with its contact/registration details as quick-info rows. */
+/**
+ * Billed-to party: a customer company, or — for shipping-line credit invoices
+ * (`companyId` null) — the shipping line itself. The two payers are mutually
+ * exclusive (DB-enforced), so exactly one branch has data.
+ */
 function RecipientCard({ invoice }: { invoice: Invoice }) {
   const company = invoice.company;
+  const shippingLine = invoice.shippingLineCompany;
+
+  if (!company && shippingLine) {
+    const rows: FieldRowProps[] = [
+      { label: "Phone", value: shippingLine.phoneNumber },
+      { label: "Email", value: shippingLine.email },
+    ];
+    return (
+      <LinkedEntityCard
+        icon={Building2}
+        title="Billed to"
+        name={shippingLine.name}
+        rows={rows}
+        emptyMessage="No additional shipping line details available."
+      />
+    );
+  }
+
   const rows: FieldRowProps[] = [
     { label: "Profile", value: invoice.companyProfile?.reference },
     { label: "TIN", value: company?.tin },
@@ -91,7 +113,7 @@ function RecipientCard({ invoice }: { invoice: Invoice }) {
   return (
     <LinkedEntityCard
       icon={Building2}
-      title="Recipient"
+      title="Billed to"
       name={company?.name ?? "Unnamed company"}
       to={invoice.companyId ? `/dashboard/customers/${invoice.companyId}` : null}
       rows={rows}
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
index ce42e8953..99f3c5d23 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
@@ -112,7 +112,9 @@ export default function InvoicesPanel() {
         header: "Billed to",
         cell: ({ row }) => (
           <Text size="sm" c="edr-text" truncate maw={200}>
-            {row.original.company?.name ?? "—"}
+            {row.original.company?.name ??
+              row.original.shippingLineCompany?.name ??
+              "—"}
           </Text>
         ),
       },
diff --git a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
index a2a33ac4d..688ed3ce2 100644
--- a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
@@ -580,14 +580,10 @@ const RuleEngineResourcePage = () => {
               config={config}
               layout="row"
               readOnly={!canUpdateControls}
-              onEdit={
-                config.slug === "container-types"
-                  ? undefined
-                  : (record) => {
-                      setEditing(record);
-                      setFormOpen(true);
-                    }
-              }
+              onEdit={(record) => {
+                setEditing(record);
+                setFormOpen(true);
+              }}
               onDelete={setDeleteTarget}
               onViewChain={
                 config.slug === "approval-rules"
@@ -958,9 +954,7 @@ const RuleEngineResourcePage = () => {
               totalCount={totalCount}
               onPaginationChange={setPagination}
               readOnly={!canUpdate && !canDelete}
-              onEdit={
-                canUpdate && config.slug !== "container-types" ? openEdit : undefined
-              }
+              onEdit={canUpdate ? openEdit : undefined}
               onDelete={canDelete ? setDeleteTarget : undefined}
               onViewChain={
                 config.slug === "approval-rules"
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleTrackPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleTrackPage.tsx
index 781c241b6..844359bad 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleTrackPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleTrackPage.tsx
@@ -10,6 +10,7 @@ import {
   MapPin,
   Navigation,
   PackageCheck,
+  Pencil,
   Train,
 } from "lucide-react";
 import {
@@ -29,9 +30,10 @@ import {
 } from "@mantine/core";
 
 import { PageContainer } from "@/components/page";
+import { CheckpointTimeModal } from "@/components/trainScheduling/CheckpointTimeModal";
 import { LogPassYardWorkModal } from "@/components/trainScheduling/LogPassYardWorkModal";
 import { RouteCorridorTrack } from "@/components/trainScheduling/RouteCorridorTrack";
-import type { TrackStation } from "@/types/trainScheduling";
+import type { TrackStation, TrainCheckpoint } from "@/types/trainScheduling";
 import {
   RouteCorridor,
   StatusPill,
@@ -156,6 +158,16 @@ export default function TrainScheduleTrackPage() {
   const recordCheckpoint = useMutation(
     api.trainScheduling.recordCheckpoint.mutationOptions(),
   );
+  const updateCheckpoint = useMutation(
+    api.trainScheduling.updateCheckpoint.mutationOptions(),
+  );
+  // Time-entry dialogs: logging a pass at a yard with no work (the yard-work
+  // modal carries its own picker), and correcting an already-logged leg.
+  const [logModal, setLogModal] = useState<{
+    station: TrackStation;
+    isFinal: boolean;
+  } | null>(null);
+  const [editModal, setEditModal] = useState<TrainCheckpoint | null>(null);
   // Yard work drives the log-pass modal: which bookings board/alight per stop.
   const yardWorkQuery = useQuery(
     api.trainScheduling.yardWork.queryOptions({
@@ -241,15 +253,30 @@ export default function TrainScheduleTrackPage() {
 
   const handleLog = (sequenceNo: number) => {
     const station = track.stations.find((s) => s.sequenceNo === sequenceNo);
+    if (!station) return;
     const isFinal = sequenceNo === track.stations[totalStations - 1]?.sequenceNo;
-    if (station && stationHasWork(station)) {
+    if (stationHasWork(station)) {
       setYardModal({ station, isFinal, alreadyLogged: false });
       return;
     }
+    setLogModal({ station, isFinal });
+  };
+
+  const submitLog = (values: { occurredAt: string; note: string }) => {
+    if (!logModal) return;
+    const { station, isFinal } = logModal;
     recordCheckpoint.mutate(
-      { id: scheduleId, payload: { sequenceNo } },
+      {
+        id: scheduleId,
+        payload: {
+          sequenceNo: station.sequenceNo,
+          occurredAt: values.occurredAt,
+          ...(values.note ? { note: values.note } : {}),
+        },
+      },
       {
         onSuccess: () => {
+          setLogModal(null);
           toast({
             title: isFinal
               ? "Train arrived — assets freed, moved to destination yard"
@@ -266,6 +293,32 @@ export default function TrainScheduleTrackPage() {
     );
   };
 
+  const submitEdit = (values: { occurredAt: string; note: string }) => {
+    if (!editModal) return;
+    updateCheckpoint.mutate(
+      {
+        id: scheduleId,
+        sequenceNo: editModal.sequenceNo,
+        payload: { occurredAt: values.occurredAt, note: values.note || null },
+      },
+      {
+        onSuccess: () => {
+          setEditModal(null);
+          toast({ title: "Checkpoint updated" });
+        },
+        onError: (err) =>
+          toast({
+            title: "Could not update checkpoint",
+            description: parseError(err, "Please try again"),
+            variant: "destructive",
+          }),
+      },
+    );
+  };
+  // Legs stay correctable for as long as the journey exists — while rolling
+  // and after arrival.
+  const canEdit = track.status === "DISPATCHED" || track.status === "ARRIVED";
+
   // "Forgot to load" catch: while the train sits at the current station, any
   // boarder there that is still unloaded can be loaded until the next pass.
   const currentStationObj = track.stations.find(
@@ -502,6 +555,7 @@ export default function TrainScheduleTrackPage() {
                 : null
             }
             onLogCheckpoint={handleLog}
+            onEditCheckpoint={canEdit ? setEditModal : undefined}
           />
 
           {/* Cargo the operator forgot: boarders at the CURRENT station stay
@@ -595,24 +649,38 @@ export default function TrainScheduleTrackPage() {
                   )
                 }
                 title={
-                  <Group gap="sm">
-                    <Text fw={700} size="sm">
-                      {cp.label ?? `Station ${cp.sequenceNo}`}
-                    </Text>
-                    <Badge
-                      size="xs"
-                      radius="sm"
-                      variant="light"
-                      color={
-                        cp.kind === "ARRIVED"
-                          ? "teal"
-                          : cp.kind === "DEPARTED"
-                            ? "blue"
-                            : "edr-green"
-                      }
-                    >
-                      {cp.kind}
-                    </Badge>
+                  <Group gap="sm" justify="space-between" wrap="nowrap">
+                    <Group gap="sm">
+                      <Text fw={700} size="sm">
+                        {cp.label ?? `Station ${cp.sequenceNo}`}
+                      </Text>
+                      <Badge
+                        size="xs"
+                        radius="sm"
+                        variant="light"
+                        color={
+                          cp.kind === "ARRIVED"
+                            ? "teal"
+                            : cp.kind === "DEPARTED"
+                              ? "blue"
+                              : "edr-green"
+                        }
+                      >
+                        {cp.kind}
+                      </Badge>
+                    </Group>
+                    {canEdit ? (
+                      <Button
+                        size="compact-xs"
+                        radius="md"
+                        variant="light"
+                        color="gray"
+                        leftSection={<Pencil size={12} />}
+                        onClick={() => setEditModal(cp)}
+                      >
+                        Edit
+                      </Button>
+                    ) : null}
                   </Group>
                 }
               >
@@ -630,6 +698,39 @@ export default function TrainScheduleTrackPage() {
         )}
       </Paper>
 
+      <CheckpointTimeModal
+        opened={logModal !== null}
+        onClose={() => setLogModal(null)}
+        title={
+          logModal?.isFinal
+            ? `Mark arrived at ${logModal.station.label}`
+            : `Log pass at ${logModal?.station.label ?? "station"}`
+        }
+        icon={logModal?.isFinal ? <Flag size={18} /> : <MapPin size={18} />}
+        description={
+          logModal?.isFinal
+            ? "Marks the train arrived: remaining bookings arrive, assets are freed."
+            : undefined
+        }
+        submitLabel={logModal?.isFinal ? "Mark arrived" : "Log pass"}
+        submitColor={logModal?.isFinal ? "teal" : "edr-green"}
+        loading={recordCheckpoint.isPending}
+        onSubmit={submitLog}
+      />
+
+      <CheckpointTimeModal
+        opened={editModal !== null}
+        onClose={() => setEditModal(null)}
+        title={`Edit ${editModal?.label ?? "checkpoint"}`}
+        icon={<Pencil size={18} />}
+        description="Corrects this leg's time and note only — nothing else changes."
+        initialOccurredAt={editModal?.occurredAt}
+        initialNote={editModal?.note}
+        submitLabel="Save"
+        loading={updateCheckpoint.isPending}
+        onSubmit={submitEdit}
+      />
+
       <LogPassYardWorkModal
         opened={yardModal !== null}
         onClose={() => setYardModal(null)}
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
index ef9171d0d..c2a72146d 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
@@ -34,6 +34,7 @@ import {
   Navigation,
   Package,
   PackageCheck,
+  Grid3x3,
   Route as RouteIcon,
   Ruler,
   Send,
@@ -41,6 +42,7 @@ import {
   Weight,
   Workflow as WorkflowIcon,
 } from "lucide-react";
+import { DateTimePicker } from "@mantine/dates";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Link, useParams } from "react-router-dom";
 
@@ -57,6 +59,7 @@ import { ContainerPlacementGrid } from "@/components/trainScheduling/ContainerPl
 import { FleetAvailabilitySummary } from "@/components/trainScheduling/FleetAvailabilitySummary";
 import { IntercityRideAlongPanel } from "@/components/trainScheduling/IntercityRideAlongPanel";
 import { LegCapacityPanel } from "@/components/trainScheduling/LegCapacityPanel";
+import { LegLoadBoardPanel } from "@/components/trainScheduling/LegLoadBoardPanel";
 import { LoadEmptyContainersModal } from "@/components/trainScheduling/LoadEmptyContainersModal";
 import MergeScheduleTrainModal from "@/components/trainScheduling/MergeScheduleTrainModal";
 import ScheduleHistoryPanel from "@/components/trainScheduling/ScheduleHistoryPanel";
@@ -125,6 +128,13 @@ export default function TrainScheduleV2DetailPage() {
   const [gatepassFileUrl, setGatepassFileUrl] = useState("");
   const [gatepassNotes, setGatepassNotes] = useState("");
   const [dispatchConfirmOpen, setDispatchConfirmOpen] = useState(false);
+  // Actual departure — staff often dispatch on paper first and record it later,
+  // so the time is picked (defaults to now when the dialog opens).
+  const [dispatchAt, setDispatchAt] = useState<Date | null>(null);
+  const openDispatchConfirm = () => {
+    setDispatchAt(new Date());
+    setDispatchConfirmOpen(true);
+  };
   const [switchTarget, setSwitchTarget] = useState<EligibleContainerBooking | null>(null);
   const [visualization3DOpen, setVisualization3DOpen] = useState(false);
   const [loadEmptiesOpen, setLoadEmptiesOpen] = useState(false);
@@ -477,7 +487,10 @@ export default function TrainScheduleV2DetailPage() {
   const runDispatch = async () => {
     setDispatchConfirmOpen(false);
     try {
-      await dispatch.mutateAsync(scheduleId);
+      await dispatch.mutateAsync({
+        id: scheduleId,
+        payload: dispatchAt ? { actualDepartureAt: dispatchAt.toISOString() } : {},
+      });
       await openMarshallingDocument({
         title: "Train dispatched",
         successDescription: "Marshalling document generated for the dispatched train.",
@@ -873,7 +886,7 @@ export default function TrainScheduleV2DetailPage() {
               radius="md"
               leftSection={<Send size={18} />}
               loading={dispatch.isPending}
-              onClick={() => setDispatchConfirmOpen(true)}
+              onClick={openDispatchConfirm}
             >
               Dispatch train
             </Button>
@@ -1271,6 +1284,9 @@ export default function TrainScheduleV2DetailPage() {
           <Tabs.Tab value="legs" leftSection={<RouteIcon size={16} />}>
             Leg capacity
           </Tabs.Tab>
+          <Tabs.Tab value="leg-board" leftSection={<Grid3x3 size={16} />}>
+            Leg board
+          </Tabs.Tab>
           <Tabs.Tab value="history" leftSection={<HistoryIcon size={16} />}>
             History
           </Tabs.Tab>
@@ -1359,6 +1375,13 @@ export default function TrainScheduleV2DetailPage() {
           <LegCapacityPanel schedule={schedule} />
         </Tabs.Panel>
 
+        <Tabs.Panel value="leg-board">
+          <LegLoadBoardPanel
+            schedule={schedule}
+            onChanged={() => void detailQuery.refetch()}
+          />
+        </Tabs.Panel>
+
         <Tabs.Panel value="history">
           {scheduleId ? <ScheduleHistoryPanel scheduleId={scheduleId} /> : null}
         </Tabs.Panel>
@@ -1444,6 +1467,17 @@ export default function TrainScheduleV2DetailPage() {
             undone.
           </Text>
 
+          <DateTimePicker
+            label="Actual departure"
+            description="When the train left — defaults to now; a past time is fine."
+            value={dispatchAt}
+            onChange={(v) => setDispatchAt(v ? new Date(v) : null)}
+            maxDate={new Date()}
+            valueFormat="DD MMM YYYY HH:mm"
+            clearable={false}
+            radius="md"
+          />
+
           {hasDispatchWarnings ? (
             <Alert
               color="orange"
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 a659f31fa..7aa6c77b2 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2ListPage.tsx
@@ -18,6 +18,7 @@ import {
   TextInput,
   ThemeIcon,
 } from "@mantine/core";
+import { DateTimePicker } from "@mantine/dates";
 import { useDebouncedValue } from "@mantine/hooks";
 import { isAxiosError } from "axios";
 import {
@@ -134,6 +135,8 @@ export default function TrainScheduleV2ListPage() {
   // confirmation.
   const [dispatchTarget, setDispatchTarget] =
     useState<TrainScheduleListItem | null>(null);
+  // Actual departure — defaults to now when the dialog opens; past is fine.
+  const [dispatchAt, setDispatchAt] = useState<Date | null>(null);
   // Cancelling is likewise irreversible — confirmed before the mutation fires.
   const [cancelTarget, setCancelTarget] =
     useState<TrainScheduleListItem | null>(null);
@@ -508,7 +511,10 @@ export default function TrainScheduleV2ListPage() {
                   {canDispatch && schedule.status === "SCHEDULED" ? (
                     <Menu.Item
                       leftSection={<Play size={15} />}
-                      onClick={() => setDispatchTarget(schedule)}
+                      onClick={() => {
+                        setDispatchAt(new Date());
+                        setDispatchTarget(schedule);
+                      }}
                     >
                       Start (dispatch) train
                     </Menu.Item>
@@ -959,6 +965,16 @@ export default function TrainScheduleV2ListPage() {
             wagons or cargo not yet marked loaded — those warnings are shown
             there, not here.
           </Text>
+          <DateTimePicker
+            label="Actual departure"
+            description="When the train left — defaults to now; a past time is fine."
+            value={dispatchAt}
+            onChange={(v) => setDispatchAt(v ? new Date(v) : null)}
+            maxDate={new Date()}
+            valueFormat="DD MMM YYYY HH:mm"
+            clearable={false}
+            radius="md"
+          />
           <Group justify="flex-end" gap="sm">
             <Button variant="default" onClick={() => setDispatchTarget(null)}>
               Cancel
@@ -970,7 +986,12 @@ export default function TrainScheduleV2ListPage() {
               onClick={async () => {
                 if (!dispatchTarget) return;
                 try {
-                  await dispatchSchedule.mutateAsync(dispatchTarget.id);
+                  await dispatchSchedule.mutateAsync({
+                    id: dispatchTarget.id,
+                    payload: dispatchAt
+                      ? { actualDepartureAt: dispatchAt.toISOString() }
+                      : {},
+                  });
                   toast({ title: "Train dispatched" });
                   setDispatchTarget(null);
                   void schedulesQuery.refetch();
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 2c06700d2..9ee979cfa 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -81,6 +81,8 @@ import type {
   LocomotiveRecord,
   PinWagonsPayload,
   RecordCheckpointPayload,
+  UpdateCheckpointPayload,
+  DispatchSchedulePayload,
   StaffBookingWindow,
   ScheduleMergePreview,
   TrainScheduleDetail,
@@ -797,10 +799,13 @@ export const api = {
       ],
     ),
 
-    dispatchSchedule: endpoint<string, TrainScheduleDetail>(
+    dispatchSchedule: endpoint<
+      { id: string; payload?: DispatchSchedulePayload },
+      TrainScheduleDetail
+    >(
       "train-scheduling",
       "dispatch-schedule",
-      (id) => trainSchedulingService.dispatchSchedule(id),
+      ({ id, payload }) => trainSchedulingService.dispatchSchedule(id, payload),
       undefined,
       () => TRAIN_SCHEDULING_INVALIDATIONS,
     ),
@@ -918,6 +923,18 @@ export const api = {
       () => TRAIN_SCHEDULING_INVALIDATIONS,
     ),
 
+    updateCheckpoint: endpoint<
+      { id: string; sequenceNo: number; payload: UpdateCheckpointPayload },
+      TrainTrackResponse
+    >(
+      "train-scheduling",
+      "update-checkpoint",
+      ({ id, sequenceNo, payload }) =>
+        trainSchedulingService.updateCheckpoint(id, sequenceNo, payload),
+      undefined,
+      () => TRAIN_SCHEDULING_INVALIDATIONS,
+    ),
+
     arriveSchedule: endpoint<string, TrainScheduleDetail>(
       "train-scheduling",
       "arrive-schedule",
diff --git a/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts b/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts
index 58e251196..999f160f7 100644
--- a/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts
@@ -28,6 +28,8 @@ import type {
   LocomotiveRecord,
   PinWagonsPayload,
   RecordCheckpointPayload,
+  UpdateCheckpointPayload,
+  DispatchSchedulePayload,
   StaffBookingWindow,
   ScheduleMergePreview,
   TrainScheduleDetail,
@@ -524,10 +526,11 @@ export const trainSchedulingService = {
 
   dispatchSchedule: async (
     scheduleId: string,
+    payload: DispatchSchedulePayload = {},
   ): Promise<TrainScheduleDetail> => {
     const response = await client.post<TrainScheduleDetail>(
       URL_CONSTANTS.TRAIN_SCHEDULING.DISPATCH(scheduleId),
-      {},
+      payload,
     );
     return unwrap(response.data);
   },
@@ -696,6 +699,18 @@ export const trainSchedulingService = {
     return unwrap(response.data);
   },
 
+  updateCheckpoint: async (
+    scheduleId: string,
+    sequenceNo: number,
+    payload: UpdateCheckpointPayload,
+  ): Promise<TrainTrackResponse> => {
+    const response = await client.patch<TrainTrackResponse>(
+      URL_CONSTANTS.TRAIN_SCHEDULING.CHECKPOINT(scheduleId, sequenceNo),
+      payload,
+    );
+    return unwrap(response.data);
+  },
+
   arriveSchedule: async (scheduleId: string): Promise<TrainScheduleDetail> => {
     const response = await client.post<TrainScheduleDetail>(
       URL_CONSTANTS.TRAIN_SCHEDULING.ARRIVE(scheduleId),
diff --git a/apps/edr-freight-web/backoffice/src/services/wagon.service.ts b/apps/edr-freight-web/backoffice/src/services/wagon.service.ts
index a2fc0c739..f2c4ece8e 100644
--- a/apps/edr-freight-web/backoffice/src/services/wagon.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/wagon.service.ts
@@ -26,6 +26,9 @@ export interface Wagon {
     lengthMeters?: number;
   } | null;
   status: Freight.WagonStatus;
+  /** Latest status-log flip to MAINTENANCE / to AVAILABLE (list endpoint only). */
+  lastMaintenanceAt?: string | null;
+  lastAvailableAt?: string | null;
   currentYardId: string | null;
   currentYard?: { id: string; label?: string; code?: string } | null;
   /** Odd EXPORT run (Ethiopia → Djibouti); null when the wagon is not on a run. */
diff --git a/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts b/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
index 2c49769fc..2330dc4b9 100644
--- a/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
+++ b/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
@@ -910,10 +910,22 @@ export interface TrainTrackResponse {
 export interface RecordCheckpointPayload {
   sequenceNo: number;
   kind?: TrainCheckpointKind;
+  /** When the train was at the station; defaults to now. Past OK, future rejected. */
   occurredAt?: string;
   note?: string;
 }
 
+/** Edit an already-logged leg — pure correction, no side effects. */
+export interface UpdateCheckpointPayload {
+  occurredAt?: string;
+  note?: string | null;
+}
+
+export interface DispatchSchedulePayload {
+  /** Actual departure; defaults to now. Past OK, future rejected. */
+  actualDepartureAt?: string;
+}
+
 export interface TrainScheduleFilters {
   originStationId?: string;
   destinationStationId?: string;
diff --git a/apps/edr-freight-web/portal/src/components/AppLayout.tsx b/apps/edr-freight-web/portal/src/components/AppLayout.tsx
index 6e33d66d7..a2ab76046 100644
--- a/apps/edr-freight-web/portal/src/components/AppLayout.tsx
+++ b/apps/edr-freight-web/portal/src/components/AppLayout.tsx
@@ -423,7 +423,7 @@ export function AppLayout({
             )}
 
             {/* Search pill */}
-            <Group
+            {/* <Group
               gap={8}
               align="center"
               visibleFrom="sm"
@@ -441,7 +441,7 @@ export function AppLayout({
               <Text size="sm" style={{ color: mutedColor, userSelect: "none" }}>
                 Search shipments, bookings…
               </Text>
-            </Group>
+            </Group> */}
 
             {/* Notifications */}
             <NotificationBellContainer />
@@ -549,7 +549,7 @@ export function AppLayout({
                     navigate("/bookings/new", { state: { fresh: true } })
                   }
                 >
-                  New Booking
+                  New Contract
                 </Menu.Item>
                 <Divider />
                 <Menu.Item
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
index a54b22506..d9e074eba 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
@@ -742,7 +742,7 @@ export default function BookingsListPage() {
               Track every cargo booking — from draft to delivery.
             </Text>
           </Box>
-          <Button
+          {/* <Button
             component={Link}
             to="/contracts"
             color="edr-green"
@@ -750,7 +750,7 @@ export default function BookingsListPage() {
             leftSection={<Plus size={16} />}
           >
             New booking
-          </Button>
+          </Button> */}
         </Group>
 
         {/* ── Summary stat cards ──────────────────────────────────────── */}
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
index a56e67afa..1284058bc 100644
--- a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineBookingsPage.tsx
@@ -114,6 +114,17 @@ export default function ShippingLineBookingsPage() {
         );
       },
     },
+    {
+      id: "scheduledDate",
+      header: () => <ColHeader label="Shipment date" />,
+      cell: ({ row }) => (
+        <Text fz={13} c={row.original.scheduledDate ? undefined : "edr-muted"}>
+          {row.original.scheduledDate
+            ? new Date(row.original.scheduledDate).toLocaleDateString()
+            : "—"}
+        </Text>
+      ),
+    },
     {
       id: "status",
       header: () => <ColHeader label="Status" />,
diff --git a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineCompletePage.tsx b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineCompletePage.tsx
index c470de35d..809c8e5c1 100644
--- a/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineCompletePage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/shipping-line/ShippingLineCompletePage.tsx
@@ -17,6 +17,7 @@ import {
   Box,
   Button,
   Center,
+  Divider,
   FileButton,
   Group,
   List,
@@ -26,14 +27,15 @@ import {
   Select,
   Stack,
   Switch,
-  Table,
   Text,
   TextInput,
   Textarea,
+  ThemeIcon,
   Title,
 } from "@mantine/core";
 import {
   AlertCircle,
+  AlertTriangle,
   CalendarDays,
   CheckCircle2,
   ChevronLeft,
@@ -43,6 +45,7 @@ import {
   MapPin,
   Package,
   PackageCheck,
+  Receipt,
   Snowflake,
   Train,
   X,
@@ -55,6 +58,7 @@ import {
   StepLabel,
   fieldStyles,
 } from "../contracts/new-contract-form/shared";
+import { formatRateUnit } from "../contracts/new-contract-form/unit-rates";
 import {
   ShipmentFormInputValues,
   ShipmentFormValues,
@@ -65,6 +69,7 @@ import {
   downloadContainerImportTemplate,
   parseContainerExcel,
 } from "../contracts/new-shipment-form/container-excel";
+import { formatAmount } from "../contracts/new-shipment-form/total";
 import {
   shippingLineBookingsService,
   type CompleteBookingContainerLine,
@@ -213,21 +218,21 @@ function CompleteBookingForm({ booking }: { booking: ShippingLineBooking }) {
     : 0;
   const hasOdd20ft = ft20Total % 2 === 1;
 
-  // Two-step submit: the payload is priced first (authoritative quote, saved
-  // server-side with fresh rate snapshots on every preview), the shipping line
-  // confirms the figure, and only then does the booking submit.
+  // Two-step submit, same shape as the customer shipment form: the confirm
+  // modal opens at once with the payload pending, the server prices it (and
+  // runs the 20ft pairing check) while the modal shows a loader, the shipping
+  // line confirms the figure, and only then does the booking submit.
   const [pendingPayload, setPendingPayload] =
     useState<CompleteShippingLineBookingPayload | null>(null);
-  const [quote, setQuote] = useState<ShippingLinePriceQuote | null>(null);
 
   const previewMutation = useMutation({
     mutationFn: (payload: CompleteShippingLineBookingPayload) =>
       shippingLineBookingsService.pricePreview(booking.id, payload),
-    onSuccess: (result, payload) => {
-      setPendingPayload(payload);
-      setQuote(result);
-    },
+    // A pricing failure (no rate configured) closes the confirm dialog — the
+    // error modal takes over with the server's message.
+    onError: () => setPendingPayload(null),
   });
+  const quote = previewMutation.data ?? null;
 
   const submitMutation = useMutation({
     mutationFn: (payload: CompleteShippingLineBookingPayload) =>
@@ -241,11 +246,17 @@ function CompleteBookingForm({ booking }: { booking: ShippingLineBooking }) {
     // A submit failure (day filled up, window closed meanwhile) must not leave
     // a stale confirm dialog on screen — the error modal takes over.
     onError: () => {
-      setQuote(null);
+      previewMutation.reset();
       setPendingPayload(null);
     },
   });
 
+  const closeConfirm = () => {
+    if (submitMutation.isPending) return;
+    previewMutation.reset();
+    setPendingPayload(null);
+  };
+
   /**
    * Map a container size to the configured container type: reefer type when
    * any container on the line is refrigerated, standard type otherwise —
@@ -313,11 +324,21 @@ function CompleteBookingForm({ booking }: { booking: ShippingLineBooking }) {
       return;
     }
     setPayloadError(null);
-    // Price first — the confirm dialog opens when the quote arrives; the
-    // booking submits only after the shipping line confirms the figure.
+    // Open the confirm dialog now and price into it; the booking submits only
+    // after the shipping line confirms the figure.
+    setPendingPayload(payload);
+    previewMutation.reset();
     previewMutation.mutate(payload);
   });
 
+  const handleConfirm = () => {
+    if (!pendingPayload || !quote) return;
+    // Guard: never let unresolved 20ft pairing errors submit — the server
+    // rejects them anyway; the disabled button just says so first.
+    if (quote.pairingErrors.length > 0) return;
+    submitMutation.mutate(pendingPayload);
+  };
+
   const showValidationSummary =
     form.formState.isSubmitted && !form.formState.isValid;
 
@@ -446,112 +467,14 @@ function CompleteBookingForm({ booking }: { booking: ShippingLineBooking }) {
           </Stack>
         </Modal>
 
-        {/* Price confirmation: the quote just computed (and snapshotted)
-            server-side. Nothing submits until the figure is confirmed. */}
-        <Modal
-          opened={Boolean(quote)}
-          onClose={() => {
-            setQuote(null);
-            setPendingPayload(null);
-          }}
-          centered
-          radius="md"
-          size="lg"
-          title={
-            <Group gap={8}>
-              <PackageCheck size={18} color="var(--mantine-color-teal-6)" />
-              <Text fw={700} fz={16}>
-                Confirm your booking price
-              </Text>
-            </Group>
-          }
-          overlayProps={{ blur: 2, backgroundOpacity: 0.55 }}
-        >
-          {quote && (
-            <Stack gap="md">
-              <Box style={{ overflowX: "auto" }}>
-                <Table verticalSpacing="xs" horizontalSpacing="md">
-                  <Table.Thead>
-                    <Table.Tr>
-                      <Table.Th>Charge</Table.Th>
-                      <Table.Th ta="right">Qty</Table.Th>
-                      <Table.Th ta="right">Amount</Table.Th>
-                    </Table.Tr>
-                  </Table.Thead>
-                  <Table.Tbody>
-                    {quote.lineItems.map((item, i) => (
-                      <Table.Tr key={i}>
-                        <Table.Td>
-                          <Text size="sm">{item.description}</Text>
-                        </Table.Td>
-                        <Table.Td ta="right">
-                          <Text size="sm" c="dimmed">
-                            {item.quantity ?? 1}
-                          </Text>
-                        </Table.Td>
-                        <Table.Td ta="right">
-                          <Text size="sm" fw={600}>
-                            {Number(item.amount).toLocaleString()}{" "}
-                            {item.currency}
-                          </Text>
-                        </Table.Td>
-                      </Table.Tr>
-                    ))}
-                  </Table.Tbody>
-                </Table>
-              </Box>
-              <Group
-                justify="space-between"
-                p="sm"
-                style={{
-                  borderRadius: 10,
-                  background: "var(--mantine-color-teal-0)",
-                }}
-              >
-                <Text fw={700}>Total</Text>
-                <Text fw={800} fz={18}>
-                  {Number(quote.totalAmount).toLocaleString()} {quote.currency}
-                </Text>
-              </Group>
-              <Text size="xs" c="dimmed">
-                The amount is charged to your credit account — no payment is
-                due now. EDR bills your accumulated charges periodically.
-              </Text>
-              {quote.warnings.length > 0 && (
-                <Alert
-                  color="yellow"
-                  radius="md"
-                  icon={<AlertCircle size={16} />}
-                >
-                  {quote.warnings.join(" ")}
-                </Alert>
-              )}
-              <Group justify="flex-end" gap="sm">
-                <Button
-                  variant="default"
-                  radius="md"
-                  onClick={() => {
-                    setQuote(null);
-                    setPendingPayload(null);
-                  }}
-                >
-                  Go back
-                </Button>
-                <Button
-                  color="edr-green"
-                  radius="md"
-                  leftSection={<PackageCheck size={16} />}
-                  loading={submitMutation.isPending}
-                  onClick={() =>
-                    pendingPayload && submitMutation.mutate(pendingPayload)
-                  }
-                >
-                  Confirm & book
-                </Button>
-              </Group>
-            </Stack>
-          )}
-        </Modal>
+        <PriceConfirmModal
+          opened={Boolean(pendingPayload)}
+          quote={quote}
+          quoteLoading={previewMutation.isPending}
+          loading={submitMutation.isPending}
+          onConfirm={handleConfirm}
+          onReject={closeConfirm}
+        />
 
         <Box flex={1} p="24px">
           <Stack gap="lg" className="mx-auto max-w-4xl">
@@ -618,6 +541,225 @@ function CompleteBookingForm({ booking }: { booking: ShippingLineBooking }) {
   );
 }
 
+/**
+ * Price confirmation — the customer shipment form's modal, one-to-one: opens
+ * the moment the form submits, shows a loader while the server prices and
+ * checks 20ft pairing, then the authoritative breakdown. Pairing violations
+ * hard-block confirm (the server rejects them on /complete too); overweight
+ * containers only warn — the surcharge is already inside the total.
+ */
+function PriceConfirmModal({
+  opened,
+  quote,
+  quoteLoading,
+  loading,
+  onConfirm,
+  onReject,
+}: {
+  opened: boolean;
+  quote: ShippingLinePriceQuote | null;
+  quoteLoading: boolean;
+  loading: boolean;
+  onConfirm: () => void;
+  onReject: () => void;
+}) {
+  const pairingErrors = quote?.pairingErrors ?? [];
+  const hasPairingBlock = pairingErrors.length > 0;
+  const overweightLines = quote?.overweightLines ?? [];
+  const overweightSurchargeAmount =
+    quote?.lineItems.find((li) => li.code === "OVERWEIGHT_PER_TON")?.amount ??
+    0;
+
+  // Confirm waits for the authoritative price and a clean pairing check.
+  const confirmDisabled =
+    loading || quoteLoading || hasPairingBlock || !quote;
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onReject}
+      closeOnClickOutside={!loading}
+      closeOnEscape={!loading}
+      withCloseButton={!loading}
+      centered
+      radius="lg"
+      size="lg"
+      title={
+        <Group gap={10}>
+          <ThemeIcon variant="light" color="edr-green" radius="md" size={34}>
+            <Receipt size={18} />
+          </ThemeIcon>
+          <Box>
+            <Text fw={800} fz={16} c="#10202F">
+              Confirm shipment price
+            </Text>
+            <Text fz="xs" c="dimmed">
+              Review the total before booking this shipment.
+            </Text>
+          </Box>
+        </Group>
+      }
+    >
+      <Stack gap="md">
+        {quoteLoading && (
+          <Group gap={8} c="dimmed">
+            <Loader size="xs" color="edr-green" />
+            <Text fz="sm" c="dimmed">
+              Computing the final price breakdown and checking container
+              weights…
+            </Text>
+          </Group>
+        )}
+
+        {hasPairingBlock && (
+          <Alert
+            color="red"
+            variant="light"
+            radius="md"
+            icon={<AlertCircle size={16} />}
+            title="Cannot complete booking — 20ft wagon pairing"
+          >
+            <Stack gap={6}>
+              {pairingErrors.map((msg, i) => (
+                <Text key={i} fz="sm" c="red.8">
+                  {msg}
+                </Text>
+              ))}
+              <Text fz="xs" c="red.7" mt={2}>
+                Adjust the 20ft container weights or quantities so pairs differ
+                by no more than 10 tons.
+              </Text>
+            </Stack>
+          </Alert>
+        )}
+
+        {overweightLines.length > 0 && (
+          <Alert
+            color="yellow"
+            variant="light"
+            radius="md"
+            icon={<AlertTriangle size={16} />}
+            title="Overweight containers"
+          >
+            <Stack gap={6}>
+              {overweightLines.map((line, i) => (
+                <Text key={i} fz="sm" c="#9A5B00">
+                  {line.containerTypeCode}: {line.totalVgmTons}t exceeds limit{" "}
+                  {line.maxAllowedTons}t (+{line.excessTons}t overweight)
+                </Text>
+              ))}
+              <Text fz="xs" c="#9A5B00" mt={2}>
+                {overweightSurchargeAmount > 0
+                  ? `An overweight surcharge of ${formatAmount(overweightSurchargeAmount)} ${
+                      quote?.currency ?? ""
+                    } applies (included in the total below). You can still submit, or go back and adjust weights.`
+                  : "An overweight surcharge applies. You can still submit, or go back and adjust weights."}
+              </Text>
+            </Stack>
+          </Alert>
+        )}
+
+        {quote && quote.warnings.length > 0 && (
+          <Alert
+            color="yellow"
+            variant="light"
+            radius="md"
+            icon={<AlertTriangle size={16} />}
+          >
+            {quote.warnings.join(" ")}
+          </Alert>
+        )}
+
+        {quote && (
+          <Paper
+            withBorder
+            radius={16}
+            p="lg"
+            style={{ borderColor: "#E6ECF2" }}
+          >
+            <Stack gap={10}>
+              {quote.lineItems.map((line, i) => (
+                <Group key={i} justify="space-between" wrap="nowrap" gap="sm">
+                  <Box style={{ minWidth: 0 }}>
+                    <Text fz="sm" c="#10202F" fw={500}>
+                      {line.description}
+                    </Text>
+                    <Text fz="xs" c="dimmed">
+                      {(line.quantity ?? 1).toLocaleString()} ×{" "}
+                      {formatAmount(line.unitAmount ?? line.amount)}{" "}
+                      {quote.currency}
+                      {line.unit
+                        ? ` · ${formatRateUnit(line.unit.toLowerCase())}`
+                        : ""}
+                    </Text>
+                  </Box>
+                  <Text
+                    fz="sm"
+                    fw={600}
+                    c="#10202F"
+                    style={{ whiteSpace: "nowrap" }}
+                  >
+                    {formatAmount(line.amount)} {quote.currency}
+                  </Text>
+                </Group>
+              ))}
+              {quote.lineItems.length === 0 && (
+                <Text fz="sm" c="dimmed">
+                  No priced lines — check the cargo details.
+                </Text>
+              )}
+            </Stack>
+            <Divider my="md" />
+            <Group justify="space-between" align="flex-end">
+              <Text
+                fz="xs"
+                fw={700}
+                tt="uppercase"
+                c="edr-green"
+                style={{ letterSpacing: "0.06em" }}
+              >
+                Total
+              </Text>
+              <Text fw={800} fz={28} c="#10202F">
+                {formatAmount(quote.totalAmount)}{" "}
+                <Text span fz={16} fw={700} c="edr-muted">
+                  {quote.currency}
+                </Text>
+              </Text>
+            </Group>
+            <Text fz="xs" c="dimmed" mt="sm">
+              The amount is charged to your credit account — no payment is due
+              now. EDR bills your accumulated charges periodically.
+            </Text>
+          </Paper>
+        )}
+
+        <Group justify="space-between" mt="xs">
+          <Button
+            variant="default"
+            radius="md"
+            leftSection={<X size={16} />}
+            onClick={onReject}
+            disabled={loading}
+          >
+            Reject &amp; edit
+          </Button>
+          <Button
+            color="edr-green"
+            radius="md"
+            leftSection={<CheckCircle2 size={16} />}
+            onClick={onConfirm}
+            loading={loading}
+            disabled={confirmDisabled}
+          >
+            Confirm &amp; book
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
+
 /** The booking's lane — fixed at initiate time from the chosen route. */
 function RouteCard({ booking }: { booking: ShippingLineBooking }) {
   return (
diff --git a/apps/edr-freight-web/portal/src/services/shipping-line-bookings.service.ts b/apps/edr-freight-web/portal/src/services/shipping-line-bookings.service.ts
index 926298dec..74797e6dc 100644
--- a/apps/edr-freight-web/portal/src/services/shipping-line-bookings.service.ts
+++ b/apps/edr-freight-web/portal/src/services/shipping-line-bookings.service.ts
@@ -67,6 +67,15 @@ export interface ShippingLinePriceQuote {
   currency: string;
   lineItems: Freight.PricingBreakdownLineItem[];
   warnings: string[];
+  /** Containers over their type's weight limit — a surcharge, not a block. */
+  overweightLines: {
+    containerTypeCode: string;
+    totalVgmTons: number;
+    maxAllowedTons: number;
+    excessTons: number;
+  }[];
+  /** 20ft wagon-pairing violations (pair weight diff over the cap) — hard block. */
+  pairingErrors: string[];
 }
 
 /** One wagon the batch engine allocated to the booking. */
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index 2af155533..3ed0ec903 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -959,6 +959,14 @@ export interface IInvoiceCompanyProfile {
   reference: string | null;
 }
 
+/** Shipping line an invoice is billed to, when `companyId` is null (see `IInvoice`). */
+export interface IInvoiceShippingLineCompany {
+  id: string;
+  name: string;
+  email?: string | null;
+  phoneNumber?: string | null;
+}
+
 /** A single billed line on an invoice. */
 export interface IInvoiceLine extends BaseEntity {
   invoiceId: string;
@@ -975,12 +983,15 @@ export interface IInvoiceLine extends BaseEntity {
 
 export interface IInvoice extends BaseEntity {
   invoiceNumber: string;
-  /** Customer (company) the invoice is billed to. */
-  companyId: string;
+  /** Customer (company) the invoice is billed to. Null on a shipping-line invoice — see `shippingLineCompanyId`. */
+  companyId: string | null;
   company?: IInvoiceCompany;
   /** Specific company profile billed. */
   companyProfileId: string;
   companyProfile?: IInvoiceCompanyProfile;
+  /** The shipping line billed, when this invoice bills batched shipping-line credits. Mutually exclusive with `companyId`. */
+  shippingLineCompanyId?: string | null;
+  shippingLineCompany?: IInvoiceShippingLineCompany;
   totalAmount: number;
   /** Cumulative amount settled so far (supports partial payment). */
   paidAmount: number;

From b22f8c838e024da359fcb90e78f4a19bf5eeb4c4 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Sat, 15 Aug 2026 10:34:05 +0000
Subject: [PATCH 116/174] fix issue

---
 apps/edr-freight-web/portal/src/components/AppLayout.tsx        | 2 +-
 .../portal/src/pages/bookings/BookingsListPage.tsx              | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/edr-freight-web/portal/src/components/AppLayout.tsx b/apps/edr-freight-web/portal/src/components/AppLayout.tsx
index a2ab76046..cfe6b93f2 100644
--- a/apps/edr-freight-web/portal/src/components/AppLayout.tsx
+++ b/apps/edr-freight-web/portal/src/components/AppLayout.tsx
@@ -26,7 +26,7 @@ import {
   Menu as MenuIcon,
   Plus,
   RefreshCw,
-  Search,
+  // Search,
   Settings,
   Upload,
   User,
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
index d9e074eba..4d7f3d3a0 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
@@ -26,7 +26,7 @@ import {
   LayoutList,
   MoreVertical,
   Package,
-  Plus,
+  // Plus,
   Search,
   Train,
   Wallet,

From 156fa9d2e408f3cd09f198273e92586f6be1dd3d Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Sat, 15 Aug 2026 11:54:35 +0000
Subject: [PATCH 117/174] fix: improve handling of container sizes in wagon
 cancellation logic

---
 .../booking-wagon-cancellation.service.ts      | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts
index 418fbd5c6..0b4315d62 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts
@@ -54,6 +54,10 @@ import {
  * fee scales with the cancelled wagon count and differs by what was booked.
  */
 export const WAGON_CANCELLATION_FEE_RATE_TYPE = 'CANCELLATION_FEE';
+
+/** `booking_container.container_size` is stored as "20ft"/"40ft" — `Number()` on it is NaN. */
+const sizeFtOf = (size: string | number | null | undefined): number =>
+  parseInt(String(size ?? ''), 10);
 /** invoices.type of the fee invoice — the settlement branch key in BookingInvoiceService. */
 export const WAGON_CANCEL_FEE_INVOICE_TYPE = 'WAGON_CANCEL_FEE';
 
@@ -603,11 +607,11 @@ export class BookingWagonCancellationService {
         const live = liveBySize.get(cut.containerSize) ?? 0;
         if (cut.quantity > live) {
           throw new BadRequestException(
-            `Cannot cancel ${cut.quantity} × ${cut.containerSize}ft — the booking only has ${live}.`,
+            `Cannot cancel ${cut.quantity} × ${sizeFtOf(cut.containerSize)}ft — the booking only has ${live}.`,
           );
         }
         bySize[cut.containerSize] = cut.quantity;
-        wagons += cut.quantity * wagonsPerUnitForSize(Number(cut.containerSize));
+        wagons += cut.quantity * wagonsPerUnitForSize(sizeFtOf(cut.containerSize));
       }
       wagons = round2(wagons);
       if (wagons > totalWagons) {
@@ -849,7 +853,7 @@ export class BookingWagonCancellationService {
     // wagon-space each size's units occupy, so the total always equals
     // cut.wagons (whole wagons on an allocation cut, fractional on a quantity cut).
     const bySize = Object.entries(cut.quantities.bySize ?? {}).filter(([, qty]) => qty > 0);
-    const spaceOf = ([size, qty]: [string, number]) => qty * wagonsPerUnitForSize(Number(size));
+    const spaceOf = ([size, qty]: [string, number]) => qty * wagonsPerUnitForSize(sizeFtOf(size));
     const totalSpace = bySize.reduce((s, e) => s + spaceOf(e), 0);
     if (!bySize.length || totalSpace <= 0) throw missing('containers');
     const containerTypes = await this.dataSource.getRepository(ContainerType).find();
@@ -858,7 +862,7 @@ export class BookingWagonCancellationService {
     let currency = '';
     for (const entry of bySize) {
       const [size] = entry;
-      const sizeFt = Number(size);
+      const sizeFt = sizeFtOf(size);
       const typeIds = new Set(
         containerTypes.filter((ct) => Number(ct.sizeFt) === sizeFt).map((ct) => ct.id),
       );
@@ -892,7 +896,7 @@ export class BookingWagonCancellationService {
       const live = lines.reduce((s, l) => s + Number(l.quantity ?? 0), 0);
       if (live < toDrop) {
         throw new BadRequestException(
-          `Booking changed since the request: only ${live} × ${size}ft left, cannot cancel ${toDrop}.`,
+          `Booking changed since the request: only ${live} × ${sizeFtOf(size)}ft left, cannot cancel ${toDrop}.`,
         );
       }
       for (const line of lines) {
@@ -936,7 +940,7 @@ export class BookingWagonCancellationService {
         });
         await manager.getRepository(BookingContainer).update(line.id, {
           quantity: qty - drop,
-          wagonsRequired: round2((qty - drop) * wagonsPerUnitForSize(Number(size))),
+          wagonsRequired: round2((qty - drop) * wagonsPerUnitForSize(sizeFtOf(size))),
           totalVgmTons: round3(Number(line.totalVgmTons) - droppedVgm),
           hazardousQuantity: keptUnits.filter((u) => u.isHazardous).length,
           reeferQuantity: keptUnits.filter((u) => u.isReefer).length,
@@ -1024,7 +1028,7 @@ export class BookingWagonCancellationService {
       const doomedVgm = round3(doomed.reduce((s, u) => s + Number(u.vgmTons || 0), 0));
       await manager.getRepository(BookingContainer).update(line.id, {
         quantity: kept.length,
-        wagonsRequired: round2(kept.length * wagonsPerUnitForSize(Number(size))),
+        wagonsRequired: round2(kept.length * wagonsPerUnitForSize(sizeFtOf(size))),
         totalVgmTons: round3(Number(line.totalVgmTons) - doomedVgm),
         hazardousQuantity: kept.filter((u) => u.isHazardous).length,
         reeferQuantity: kept.filter((u) => u.isReefer).length,

From 9f531147789ebcd5a5a9076a7b4bbd1f3b4ed832 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Sat, 15 Aug 2026 18:48:33 +0000
Subject: [PATCH 118/174] feat: enhance booking management with shipping line
 support and cargo handling improvements

---
 .../modules/auth/customer-reset.service.ts    | 85 ++++++++++++-------
 .../modules/auth/forgot-password.service.ts   |  4 +-
 .../modules/bookings/bookings.repository.ts   |  7 ++
 .../src/modules/bookings/bookings.service.ts  | 36 ++++++++
 .../bookings/dto/filter-booking.dto.ts        |  8 ++
 .../shipping-line-companies.service.ts        | 28 +++---
 .../bookings/detail/BookingCargoCard.tsx      | 31 ++++++-
 .../features/bookings/mapBookingListRow.ts    | 10 ++-
 .../bookings/BookingRequestDetailPage.tsx     | 34 +++++++-
 .../pages/bookings/BookingRequestsPage.tsx    | 19 ++++-
 .../src/services/bookings.service.ts          |  4 +
 .../backoffice/src/types/booking.ts           |  6 ++
 .../backoffice/src/utils/cargoWeight.ts       | 20 ++++-
 13 files changed, 230 insertions(+), 62 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/auth/customer-reset.service.ts b/apps/edr-freight-api/src/modules/auth/customer-reset.service.ts
index b00fd588e..0a7ed942e 100644
--- a/apps/edr-freight-api/src/modules/auth/customer-reset.service.ts
+++ b/apps/edr-freight-api/src/modules/auth/customer-reset.service.ts
@@ -1,7 +1,6 @@
 import { Injectable, Logger } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { InjectRepository } from "@nestjs/typeorm";
-import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
 import { Repository } from "typeorm";
 
 import { ExternalProfile } from "../companies/entities/external-profile.entity";
@@ -11,9 +10,10 @@ import { ResetChannel } from "./dto/forgot-password.dto";
 import {
   ForgotPasswordService,
   RESET_LINK_TTL_MS,
+  type ResetTicket,
 } from "./forgot-password.service";
 import { maskOtpTarget } from "./mask-target.util";
-import { isDomesticPhone } from "../otp/otp.service";
+import { isDomesticPhone, type OtpTarget } from "../otp/otp.service";
 
 /** The account a staff-triggered reset would land on. */
 export interface CustomerResetTarget {
@@ -116,6 +116,22 @@ export class CustomerResetService {
     channel: ResetChannel,
     options?: { scope?: string; allowWithoutCredential?: boolean },
   ): Promise<SentResetLink | null> {
+    const sent = await this.sendResetLinkToUserOnChannels(userId, [channel], options);
+    return sent[0] ?? null;
+  }
+
+  /**
+   * One ticket, several channels. Minting retires every earlier ticket for the
+   * user (`mintResetTicket`), so sending email and SMS as two separate mints
+   * makes the first link dead on arrival — the same link must go to both.
+   * Returns one entry per channel that was actually sent (unreachable channels
+   * are skipped, not errors).
+   */
+  async sendResetLinkToUserOnChannels(
+    userId: string,
+    channels: ResetChannel[],
+    options?: { scope?: string; allowWithoutCredential?: boolean },
+  ): Promise<SentResetLink[]> {
     const user = options?.allowWithoutCredential
       ? await this.forgotPasswordService.resolveActivatableUserById(userId)
       : await this.forgotPasswordService.resolveActiveUserById(userId);
@@ -128,51 +144,58 @@ export class CustomerResetService {
             : " (or has no active credential — pass allowWithoutCredential for first-time activation)"
         }`,
       );
-      return null;
+      return [];
     }
 
-    return this.deliverResetLink(user, user.id, channel, options?.scope);
+    // Mint once, before any send: a failed send leaves an unused ticket that
+    // simply expires, whereas sending a link before the ticket exists would
+    // hand the customer a URL that is dead on arrival.
+    let ticket: ResetTicket | null = null;
+    const sent: SentResetLink[] = [];
+    for (const channel of channels) {
+      const target = this.forgotPasswordService.targetFor(user, channel);
+      if (!target) continue;
+      // The gateway silently drops foreign numbers — treat like a missing phone
+      // rather than reporting "link sent" for a message that will never arrive.
+      // The backoffice disables the channel up front via `phoneIsDomestic`; this
+      // guards direct API calls.
+      if (channel === "phone" && target.phone && !isDomesticPhone(target.phone)) {
+        this.logger.warn(
+          `Staff reset via SMS refused for user ${userId} — non-domestic phone`,
+        );
+        continue;
+      }
+      ticket ??= await this.forgotPasswordService.mintResetTicket(
+        user.id,
+        RESET_LINK_TTL_MS,
+      );
+      const result = await this.deliverResetLink(
+        target,
+        user.id,
+        channel,
+        ticket,
+        options?.scope,
+      );
+      if (result) sent.push(result);
+    }
+    return sent;
   }
 
   /**
-   * Shared tail: target selection → SMS reachability → mint → send → report.
-   * Callers have already resolved `user` to an active account.
+   * Shared tail: send the already-minted ticket to a resolved target → report.
    */
   private async deliverResetLink(
-    user: User,
+    target: OtpTarget,
     userId: string,
     channel: ResetChannel,
+    ticket: ResetTicket,
     scope?: string,
   ): Promise<SentResetLink | null> {
-    this.logger.log(
-      `Staff-triggered shipping line ${"link"}`,
-    );
-    const target = this.forgotPasswordService.targetFor(user, channel);
-    if (!target) return null;
 
     // A foreign number is unreachable by the domestic-only SMS gateway — treat
     // it like a missing phone rather than reporting "link sent" for a message
-    // that will never arrive. The backoffice disables the channel up front via
-    // `phoneIsDomestic`; this guards direct API calls.
-    if (channel === "phone" && target.phone && !isDomesticPhone(target.phone)) {
-      this.logger.warn(
-        `Staff reset via SMS refused for user ${userId} — non-domestic phone`,
-      );
-      return null;
-    }
-
-    // Mint first, send second: a failed send leaves an unused ticket that simply
-    // expires, whereas sending a link before the ticket exists would hand the
-    // customer a URL that is dead on arrival.
-    const ticket = await this.forgotPasswordService.mintResetTicket(
-      userId,
-      RESET_LINK_TTL_MS,
-    );
     const link = this.buildResetLink(ticket.userId, ticket.verificationCode);
     const expiresAt = new Date(Date.now() + RESET_LINK_TTL_MS);
-this.logger.log(
-      `Staff-triggered shipping line ${link}`,
-    );
 
     const { queued } = target.email
       ? await this.emailClient.sendEmail({
diff --git a/apps/edr-freight-api/src/modules/auth/forgot-password.service.ts b/apps/edr-freight-api/src/modules/auth/forgot-password.service.ts
index a2afdbbbc..673541747 100644
--- a/apps/edr-freight-api/src/modules/auth/forgot-password.service.ts
+++ b/apps/edr-freight-api/src/modules/auth/forgot-password.service.ts
@@ -212,7 +212,9 @@ export class ForgotPasswordService {
    * is the proof).
    */
   async mintResetTicket(userId: string, ttlMs: number): Promise<ResetTicket> {
-    const code = randomBytes(24).toString("base64url");
+    // Hex, not base64url: the token rides in an SMS, and the GSM-7 alphabet has
+    // no "_" — gateways substitute a space and the link arrives broken.
+    const code = randomBytes(24).toString("hex");
     const verificationCode = await hashPassword(code);
 
     await this.dataSource.transaction(async (manager) => {
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
index c029e36d4..379449f4f 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
@@ -80,6 +80,8 @@ export interface BookingListFilterOptions {
   originYardId?: string;
   destinationYardId?: string;
   isGovernment?: 'true' | 'false';
+  /** Shipping-line bookings vs ordinary customer bookings (exactly one owner is set). */
+  customerKind?: 'SHIPPING_LINE' | 'CUSTOMER';
   consolidationPaired?: string;
 }
 
@@ -1043,6 +1045,11 @@ export class BookingsRepository extends BaseRepository<Booking> {
     } else if (options.isGovernment === 'false') {
       qb.andWhere('booking.is_government = FALSE');
     }
+    if (options.customerKind === 'SHIPPING_LINE') {
+      qb.andWhere('booking.shipping_line_company_id IS NOT NULL');
+    } else if (options.customerKind === 'CUSTOMER') {
+      qb.andWhere('booking.shipping_line_company_id IS NULL');
+    }
     if (omit !== 'tradeDirection' && options.tradeDirection) {
       qb.andWhere('booking.trade_direction = :tradeDirection', {
         tradeDirection: options.tradeDirection,
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
index a9e9dfc34..0b5bf5a0a 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.service.ts
@@ -1766,6 +1766,38 @@ export class BookingsService {
         pending.has(b.id);
     }
     this.attachPaymentDrainEnds(bookings);
+    await this.attachShippingLineCompanies(bookings);
+  }
+
+  /**
+   * Batched name lookup for shipping-line-owned bookings (`companyId` null,
+   * `shippingLineCompanyId` set). No relation on the entity — the shipping-line
+   * module sits above bookings — so a raw query keyed off the loaded ids fills
+   * `shippingLineCompany` the way `company` is filled for customers.
+   */
+  private async attachShippingLineCompanies(bookings: Booking[]): Promise<void> {
+    const ids = [
+      ...new Set(
+        bookings
+          .map((b) => b.shippingLineCompanyId)
+          .filter((id): id is string => id != null),
+      ),
+    ];
+    if (!ids.length) return;
+    const rows: Array<{ id: string; name: string; email: string | null; phoneNumber: string | null }> =
+      await this.dataSource.query(
+        `SELECT id, name, email, phone_number AS "phoneNumber"
+           FROM freight.shipping_line_companies
+          WHERE id = ANY($1::uuid[]) AND deleted_at IS NULL`,
+        [ids],
+      );
+    const byId = new Map(rows.map((r) => [r.id, r]));
+    for (const b of bookings) {
+      const line = b.shippingLineCompanyId ? byId.get(b.shippingLineCompanyId) : undefined;
+      if (line) {
+        (b as Booking & { shippingLineCompany?: typeof line }).shippingLineCompany = line;
+      }
+    }
   }
 
   /**
@@ -1822,6 +1854,7 @@ export class BookingsService {
       originYardId: filter.originYardId,
       destinationYardId: filter.destinationYardId,
       isGovernment: filter.isGovernment,
+      customerKind: filter.customerKind,
       consolidationPaired: filter.consolidationPaired,
       // DTO carries 'true'/'false' strings (query params); the repo option is a
       // real boolean — convert, preserving "not filtered" when absent.
@@ -2048,6 +2081,7 @@ export class BookingsService {
       originYardId: filter.originYardId,
       destinationYardId: filter.destinationYardId,
       isGovernment: filter.isGovernment,
+      customerKind: filter.customerKind,
       consolidationPaired: filter.consolidationPaired,
     };
 
@@ -2134,6 +2168,8 @@ export class BookingsService {
       { path: "booking" },
     );
 
+    await this.attachShippingLineCompanies([booking]);
+
     if (booking.files && booking.files.length > 0) {
       booking.files = await Promise.all(
         booking.files.map(async (file: FileRecord) => {
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts
index 43d489bac..b9cf58da0 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts
@@ -111,6 +111,14 @@ export class FilterBookingDto {
   @IsIn(['true', 'false'])
   isGovernment?: 'true' | 'false';
 
+  @ApiPropertyOptional({
+    enum: ['SHIPPING_LINE', 'CUSTOMER'],
+    description: 'Who booked: a shipping line (owned by shipping_line_company_id) or an ordinary customer company',
+  })
+  @IsOptional()
+  @IsIn(['SHIPPING_LINE', 'CUSTOMER'])
+  customerKind?: 'SHIPPING_LINE' | 'CUSTOMER';
+
   @ApiPropertyOptional({
     enum: ['true', 'false'],
     description: 'Filter customs vs self-clearance (non-customs) bookings',
diff --git a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.service.ts b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.service.ts
index 16b2836e1..ad290def8 100644
--- a/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.service.ts
+++ b/apps/edr-freight-api/src/modules/shipping-lines/shipping-line-companies.service.ts
@@ -132,37 +132,33 @@ export class ShippingLineCompaniesService {
    * Email always goes out — it is required at registration and is the only
    * channel guaranteed to reach a foreign-registered line. SMS is sent in
    * addition when the number is domestic, since the gateway silently drops
-   * anything else (see `CustomerResetService`). Two links are two independent
-   * single-use tickets; whichever the line opens first works.
+   * anything else (see `CustomerResetService`). Both carry the SAME single-use
+   * ticket: minting retires earlier tickets, so two mints would kill the email
+   * link the moment the SMS went out.
    *
    * Reports the email send, as that is the one that is always attempted.
    */
   async sendActivationLink(shippingLine: ShippingLineCompany) {
     const scope = `shipping line ${shippingLine.id}`;
+    const channels = [ResetChannel.Email];
+    if (shippingLine.phoneNumber && isDomesticPhone(shippingLine.phoneNumber)) {
+      channels.push(ResetChannel.Phone);
+    }
 
-    const emailed = await this.customerResetService.sendResetLinkToUser(
+    const sent = await this.customerResetService.sendResetLinkToUserOnChannels(
       shippingLine.userId,
-      ResetChannel.Email,
+      channels,
       { scope, allowWithoutCredential: true },
     );
+    const emailed = sent.find((s) => s.channel === ResetChannel.Email) ?? null;
 
     if (!emailed) {
       this.logger.error(
         `Activation email not sent for shipping line ${shippingLine.id} — no reachable address`,
       );
     }
-
-    if (shippingLine.phoneNumber && isDomesticPhone(shippingLine.phoneNumber)) {
-      const texted = await this.customerResetService.sendResetLinkToUser(
-        shippingLine.userId,
-        ResetChannel.Phone,
-        { scope, allowWithoutCredential: true },
-      );
-      if (!texted) {
-        this.logger.warn(
-          `Activation SMS not sent for shipping line ${shippingLine.id}`,
-        );
-      }
+    if (channels.includes(ResetChannel.Phone) && !sent.some((s) => s.channel === ResetChannel.Phone)) {
+      this.logger.warn(`Activation SMS not sent for shipping line ${shippingLine.id}`);
     }
 
     return emailed;
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCargoCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCargoCard.tsx
index 1070aa050..dc7286b5c 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCargoCard.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/BookingCargoCard.tsx
@@ -1,5 +1,5 @@
 import { Package } from "lucide-react";
-import { SimpleGrid, Divider, Box, Table, Text, Badge } from "@mantine/core";
+import { SimpleGrid, Divider, Box, Group, Table, Text, Badge } from "@mantine/core";
 
 import type { BookingDetail } from "@/types/booking";
 import { cargoTonsAndItems } from "@/utils/cargoWeight";
@@ -29,12 +29,37 @@ export function BookingCargoCard({ booking }: BookingCargoCardProps) {
       Number(c.hazardousQuantity ?? 0) > 0 || Number(c.reeferQuantity ?? 0) > 0,
   );
 
+  const isBulk = booking.freightType === "BULK";
+  // Bulk: the commodity itself (Wheat, Steel…) is the headline. Containers:
+  // the freight kind, with the shipper's own description alongside.
+  const cargoHeadline = isBulk
+    ? (booking.cargoType?.label ?? booking.cargoType?.name ?? "Bulk cargo")
+    : "Containers";
+  const cargoDescription = booking.cargoFreeText?.trim() || null;
+
   return (
     <SectionCard icon={Package} title="Cargo specifications" accent="orange">
+      <Group gap="sm" align="center" mb="md" wrap="wrap">
+        <Text fw={800} fz={22} lh={1.1}>
+          {cargoHeadline}
+        </Text>
+        <Badge variant="light" color={isBulk ? "orange" : "blue"} radius="sm">
+          {isBulk ? "Bulk" : "Container"}
+        </Badge>
+        {cargoDescription ? (
+          <Text size="sm" c="dimmed">
+            — {cargoDescription}
+          </Text>
+        ) : null}
+      </Group>
       <SimpleGrid cols={{ base: 1, sm: 3 }} spacing="sm">
         <MetricTile
-          label="Cargo type"
-          value={booking.cargoType?.label ?? booking.freightType}
+          label={isBulk ? "Commodity" : "Cargo type"}
+          value={
+            isBulk
+              ? (booking.cargoType?.label ?? booking.cargoType?.name ?? "—")
+              : (cargoDescription ?? booking.freightType)
+          }
         />
         <MetricTile label="Total VGM" value={`${tons} tons`} />
         {items != null && <MetricTile label="Items" value={`${items}`} />}
diff --git a/apps/edr-freight-web/backoffice/src/features/bookings/mapBookingListRow.ts b/apps/edr-freight-web/backoffice/src/features/bookings/mapBookingListRow.ts
index d7ee13562..66f991989 100644
--- a/apps/edr-freight-web/backoffice/src/features/bookings/mapBookingListRow.ts
+++ b/apps/edr-freight-web/backoffice/src/features/bookings/mapBookingListRow.ts
@@ -20,9 +20,13 @@ export function toBookingListRow(booking: BookingDetail): BookingListRow {
     reference: booking.reference,
     contractReference: booking.contractReference ?? null,
     contractId: booking.contractId ?? null,
-    customerLabel: booking.isGovernment
-      ? (booking.governmentInstitution ?? "Government")
-      : labelFromRef(booking.company, booking.companyId ?? undefined),
+    // Shipping-line bookings have no customer company — the line IS the customer.
+    customerLabel: booking.shippingLineCompany
+      ? booking.shippingLineCompany.name
+      : booking.isGovernment
+        ? (booking.governmentInstitution ?? "Government")
+        : labelFromRef(booking.company, booking.companyId ?? undefined),
+    isShippingLine: Boolean(booking.shippingLineCompany ?? booking.shippingLineCompanyId),
     // customerLabel: labelFromRef(booking.customer, booking.customerId),
     status: booking.status,
     scheduledDate: booking.scheduledDate,
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
index 37609ea40..62c26276a 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
@@ -13,12 +13,14 @@ import {
   MoreHorizontal,
   Package,
   RefreshCw,
+  Ship,
   Truck,
   Wallet,
   Weight,
 } from "lucide-react";
 import {
   ActionIcon,
+  Badge,
   Box,
   Button,
   Center,
@@ -174,7 +176,14 @@ export default function BookingRequestDetailPage() {
   };
 
   const company = booking.company;
+  const shippingLine = booking.shippingLineCompany ?? null;
   const customerName = toBookingListRow(booking).customerLabel;
+  // What is being shipped, in words: bulk → the commodity (Wheat, Steel…);
+  // containers → the shipper's own description when given.
+  const cargoLabel =
+    booking.freightType === "BULK"
+      ? (booking.cargoType?.label ?? booking.cargoType?.name ?? null)
+      : (booking.cargoFreeText?.trim() || null);
 
   const amount = Number(booking.totalAmount);
   const containers = booking.bookingContainers ?? [];
@@ -237,10 +246,27 @@ export default function BookingRequestDetailPage() {
         }
         subtitle={
           <Group gap={6} wrap="wrap">
-            <EntityLink
-              to={company?.id ? `/dashboard/customers/${company.id}` : null}
-              label={customerName ?? "—"}
-            />
+            {shippingLine ? (
+              <Group gap={6} wrap="nowrap">
+                <Ship size={14} />
+                <Text size="sm" fw={600}>
+                  {shippingLine.name}
+                </Text>
+                <Badge size="xs" radius="sm" variant="light" color="teal">
+                  Shipping line
+                </Badge>
+              </Group>
+            ) : (
+              <EntityLink
+                to={company?.id ? `/dashboard/customers/${company.id}` : null}
+                label={customerName ?? "—"}
+              />
+            )}
+            {cargoLabel ? (
+              <Text size="sm" c="dimmed">
+                · {cargoLabel}
+              </Text>
+            ) : null}
             <Text size="sm" c="dimmed">
               · Scheduled {booking.scheduledDate}
             </Text>
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
index b41367619..0c6a3553a 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
@@ -18,6 +18,7 @@ import {
   Package,
   Plus,
   RefreshCw,
+  Ship,
   User,
 } from "lucide-react";
 import { useCallback, useMemo, useRef, useState } from "react";
@@ -62,6 +63,12 @@ const BOOKING_KIND_OPTIONS: { value: BookingKind; label: string }[] = [
   { value: "GENERAL_CONTRACT", label: "General booking" },
 ];
 
+/** Who booked: shipping lines own bookings via `shippingLineCompanyId`, not a customer company. */
+const CUSTOMER_KIND_OPTIONS = [
+  { value: "SHIPPING_LINE", label: "Shipping line" },
+  { value: "CUSTOMER", label: "Customer" },
+];
+
 /** Status options for the filter select — built from the shared status styles. */
 const STATUS_OPTIONS = Object.entries(BOOKING_STATUS_STYLES).map(
   ([value, { label }]) => ({ value, label }),
@@ -132,6 +139,7 @@ export default function BookingRequestsPage() {
   // split), so a deep link can never land behind "More filters" unseen.
   const bookingFilterDefs: FilterDef[] = useMemo(
     () => [
+      { key: "customerKind", label: "Booked by", type: "enum", multiple: false, options: CUSTOMER_KIND_OPTIONS },
       { key: "bookingType", label: "Kind", type: "enum", multiple: false, options: BOOKING_KIND_OPTIONS },
       { key: "statuses", label: "Status", type: "enum", options: STATUS_OPTIONS },
       {
@@ -301,8 +309,17 @@ export default function BookingRequestsPage() {
                 </Badge>
               </div>
               <p className="mt-0.5 flex items-center gap-1 truncate text-xs text-muted-foreground">
-                <User className="size-3 shrink-0 opacity-70" />
+                {b.isShippingLine ? (
+                  <Ship className="size-3 shrink-0 opacity-70" />
+                ) : (
+                  <User className="size-3 shrink-0 opacity-70" />
+                )}
                 {b.customerLabel}
+                {b.isShippingLine ? (
+                  <Badge variant="secondary" className="h-4 shrink-0 px-1 text-[9px] font-medium">
+                    Shipping line
+                  </Badge>
+                ) : null}
               </p>
             </div>
           </div>
diff --git a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
index 6a86dba7d..dead9c520 100644
--- a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
@@ -36,6 +36,8 @@ export interface BookingListFilter {
   scheduledTo?: string;
   originYardId?: string;
   destinationYardId?: string;
+  /** SHIPPING_LINE = booked by a shipping line; CUSTOMER = ordinary customer company. */
+  customerKind?: "SHIPPING_LINE" | "CUSTOMER";
   /** "true" = government bookings only, "false" = private only. */
   isGovernment?: "true" | "false";
   /** Free-text search: booking reference, customer name, contract reference (server-side). */
@@ -151,6 +153,7 @@ export const bookingsService = {
       if (filter.originYardId) params.originYardId = filter.originYardId;
       if (filter.destinationYardId) params.destinationYardId = filter.destinationYardId;
       if (filter.isGovernment) params.isGovernment = filter.isGovernment;
+      if (filter.customerKind) params.customerKind = filter.customerKind;
     }
     const response = await client.get<BookingListSummary>(B.LIST_SUMMARY, {
       params,
@@ -184,6 +187,7 @@ export const bookingsService = {
       if (filter.originYardId) params.originYardId = filter.originYardId;
       if (filter.destinationYardId) params.destinationYardId = filter.destinationYardId;
       if (filter.isGovernment) params.isGovernment = filter.isGovernment;
+      if (filter.customerKind) params.customerKind = filter.customerKind;
       if (filter.customsClearingEnabled)
         params.customsClearingEnabled = filter.customsClearingEnabled;
       if (filter.search) params.search = filter.search;
diff --git a/apps/edr-freight-web/backoffice/src/types/booking.ts b/apps/edr-freight-web/backoffice/src/types/booking.ts
index b4b154800..510139731 100644
--- a/apps/edr-freight-web/backoffice/src/types/booking.ts
+++ b/apps/edr-freight-web/backoffice/src/types/booking.ts
@@ -251,6 +251,10 @@ export interface BookingDetail {
   updatedAt: string;
   // customer?: BookingNamedRef & { companyName?: string };
   company?: BookingNamedRef & Partial<BookingCompany>;
+  /** Set when booked by a shipping line (then `companyId`/`company` are null). */
+  shippingLineCompanyId?: string | null;
+  /** Owner when booked by a shipping line (then `company` is absent). Hydrated server-side. */
+  shippingLineCompany?: { id: string; name: string; email?: string | null; phoneNumber?: string | null };
   originYard?: BookingNamedRef;
   destinationYard?: BookingNamedRef;
   serviceType?: BookingNamedRef & { code?: string; includesCustoms?: boolean; includesFirstMile?: boolean; includesLastMile?: boolean };
@@ -273,6 +277,8 @@ export interface BookingListRow {
   /** Needed to link the reference to the contract's detail page. */
   contractId?: string | null;
   customerLabel: string;
+  /** True when the booking is owned by a shipping line rather than a customer company. */
+  isShippingLine?: boolean;
   status: BookingStatus;
   scheduledDate: string;
   totalAmount: number;
diff --git a/apps/edr-freight-web/backoffice/src/utils/cargoWeight.ts b/apps/edr-freight-web/backoffice/src/utils/cargoWeight.ts
index 7e90313dd..45056ace2 100644
--- a/apps/edr-freight-web/backoffice/src/utils/cargoWeight.ts
+++ b/apps/edr-freight-web/backoffice/src/utils/cargoWeight.ts
@@ -1,18 +1,32 @@
 /**
  * Break-bulk (PER_ITEM) bulk bookings overload `cargoTotalWeightVgm` with the
- * ITEM COUNT; their real tonnage lives in `bulkTotalWeightTons`. Every other
- * booking stores tons in `cargoTotalWeightVgm` directly. Rendering the raw
- * VGM column showed a 20-item / 100T booking as "20 tons".
+ * ITEM COUNT; their real tonnage lives in `bulkTotalWeightTons`. Container
+ * bookings never store a total at all — `cargoTotalWeightVgm` stays 0 and the
+ * weight lives per line (`quantity × vgmPerUnitTons`). Every other booking
+ * stores tons in `cargoTotalWeightVgm` directly. Rendering the raw VGM column
+ * showed a 20-item / 100T booking as "20 tons" and every container booking as
+ * "0 tons".
  */
 export function cargoTonsAndItems(booking: {
   freightType?: string | null;
   cargoTotalWeightVgm?: number | string | null;
   bulkTotalWeightTons?: number | string | null;
+  bookingContainers?: Array<{
+    quantity?: number | string | null;
+    vgmPerUnitTons?: number | string | null;
+  }> | null;
 }): { tons: number; items: number | null } {
   const bulkTons = Number(booking.bulkTotalWeightTons ?? 0);
   const vgm = Number(booking.cargoTotalWeightVgm ?? 0);
   if (booking.freightType === "BULK" && bulkTons > 0) {
     return { tons: bulkTons, items: vgm > 0 ? vgm : null };
   }
+  if (vgm <= 0 && booking.bookingContainers?.length) {
+    const lineTons = booking.bookingContainers.reduce(
+      (sum, c) => sum + Number(c.quantity ?? 0) * Number(c.vgmPerUnitTons ?? 0),
+      0,
+    );
+    return { tons: Math.round(lineTons * 1000) / 1000, items: null };
+  }
   return { tons: vgm, items: null };
 }

From 5ce5cbe29dad4749ee0a05420e875380dab6396c Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Sun, 16 Aug 2026 08:18:40 +0000
Subject: [PATCH 119/174] feat: enhance booking and scheduling features with
 shipping line support and improved search functionality

---
 .../modules/bookings/bookings.repository.ts   |  13 +-
 .../bookings/dto/filter-booking.dto.ts        |   2 +-
 .../scheduling-reschedule.service.spec.ts     |  18 +-
 .../scheduling-reschedule.service.ts          |  21 ++-
 .../services/train-scheduling.service.spec.ts |  26 +++
 .../services/train-scheduling.service.ts      | 168 ++++++++++++------
 .../pages/bookings/BookingRequestsPage.tsx    |   2 +-
 .../contracts/ClearanceDocumentsPage.tsx      |  50 +++++-
 8 files changed, 225 insertions(+), 75 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
index 379449f4f..310364927 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
@@ -16,6 +16,7 @@ import { computeFacets, FacetBucket } from '../../common/utils/facets.util';
 import { wagonsPerUnitForSize } from '../rule-engine/container-type.util';
 import { ContainerType } from '../rule-engine/entities/container-type.entity';
 import { Contract } from '../contracts/entities/contract.entity';
+import { ShippingLineCompany } from '../shipping-lines/entities/shipping-line-company.entity';
 import { ContractRateSnapshot } from '../contracts/entities/contract-rate-snapshot.entity';
 import { ContractRoute } from '../contracts/entities/contract-route.entity';
 import { applyDirectionScope } from '../user-trade-access/trade-scope.util';
@@ -783,16 +784,20 @@ export class BookingsRepository extends BaseRepository<Booking> {
       // by TypeORM and crashes).
       .leftJoin(Contract, 'contract', 'contract.id = booking.contract_id')
       .addSelect('contract.reference', 'contract_reference')
+      // Shipping-line owner name for search only (no relation, see entity) —
+      // the list rows get `shippingLineCompany` hydrated by the service.
+      .leftJoin(ShippingLineCompany, 'slc', 'slc.id = booking.shipping_line_company_id')
       .where('booking.deleted_at IS NULL');
 
     this.applyListFilters(qb, options);
 
-    // Free-text search spans joined columns (company, contract) that only this
-    // list query joins — so it lives here, not in applyListFilters (shared
-    // with getListSummaryMetrics, whose query builder has no joins).
+    // Free-text search spans joined columns (company, shipping line, contract)
+    // that only this list query joins — so it lives here, not in
+    // applyListFilters (shared with getListSummaryMetrics, whose query builder
+    // has no joins).
     if (options.search) {
       qb.andWhere(
-        '(booking.reference ILIKE :search OR company.name ILIKE :search OR contract.reference ILIKE :search)',
+        '(booking.reference ILIKE :search OR company.name ILIKE :search OR slc.name ILIKE :search OR contract.reference ILIKE :search)',
         { search: `%${options.search}%` },
       );
     }
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts
index b9cf58da0..4ffde3d0d 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/filter-booking.dto.ts
@@ -148,7 +148,7 @@ export class FilterBookingDto {
 
   @ApiPropertyOptional({
     description:
-      'Free-text search across booking reference, company name, and contract reference.',
+      'Free-text search across booking reference, customer / shipping-line company name, and contract reference.',
   })
   @IsOptional()
   @Transform(({ value }) =>
diff --git a/apps/edr-freight-api/src/modules/scheduling-reschedule/scheduling-reschedule.service.spec.ts b/apps/edr-freight-api/src/modules/scheduling-reschedule/scheduling-reschedule.service.spec.ts
index 4a5fc86bb..2d1bbf6f4 100644
--- a/apps/edr-freight-api/src/modules/scheduling-reschedule/scheduling-reschedule.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/scheduling-reschedule/scheduling-reschedule.service.spec.ts
@@ -72,6 +72,8 @@ describe('SchedulingRescheduleService', () => {
       previewTrainSchedule: jest.fn(),
       unassignBooking: jest.fn(),
       assignBookingsToSchedule: jest.fn(),
+      windowFieldsForNewDeparture: jest.fn().mockResolvedValue({}),
+      emitWindowState: jest.fn().mockResolvedValue(undefined),
     };
     schedulingRescheduleRepository = {
       createEvent: jest.fn().mockResolvedValue({ id: 'event-1' }),
@@ -213,6 +215,13 @@ describe('SchedulingRescheduleService', () => {
     });
     trainSchedulesRepository.updateStatus.mockResolvedValue(undefined);
     trainSchedulingService.assignBookingsToSchedule.mockResolvedValue({ id: 'sched-1' });
+    // An OPEN window's close must follow the new departure (this is the
+    // portal's "closes in" countdown) — the derived fields ride along with the
+    // date write.
+    const newCloses = new Date('2099-06-22T08:00:00.000Z');
+    trainSchedulingService.windowFieldsForNewDeparture.mockResolvedValue({
+      windowClosesAt: newCloses,
+    });
 
     const result = await service.maintenanceReschedule(
       'sched-1',
@@ -228,9 +237,16 @@ describe('SchedulingRescheduleService', () => {
     expect(trainSchedulesRepository.updateStatus).toHaveBeenCalledWith(
       'sched-1',
       'DRAFT',
-      { scheduledDepartureDate: new Date('2099-06-22T10:00:00.000Z') },
+      {
+        scheduledDepartureDate: new Date('2099-06-22T10:00:00.000Z'),
+        windowClosesAt: newCloses,
+      },
       txManager,
     );
+    expect(trainSchedulingService.windowFieldsForNewDeparture).toHaveBeenCalledWith(
+      schedule,
+      new Date('2099-06-22T10:00:00.000Z'),
+    );
     expect(schedulingRescheduleRepository.createEvent).toHaveBeenCalledWith(
       expect.objectContaining({
         trigger: 'TRAIN_MAINTENANCE',
diff --git a/apps/edr-freight-api/src/modules/scheduling-reschedule/scheduling-reschedule.service.ts b/apps/edr-freight-api/src/modules/scheduling-reschedule/scheduling-reschedule.service.ts
index 7283c874a..7c41ee43a 100644
--- a/apps/edr-freight-api/src/modules/scheduling-reschedule/scheduling-reschedule.service.ts
+++ b/apps/edr-freight-api/src/modules/scheduling-reschedule/scheduling-reschedule.service.ts
@@ -227,17 +227,25 @@ export class SchedulingRescheduleService {
     // through this manager without editing TrainSchedulingService. A failure
     // between those steps and this block can still leave partial state; a human
     // must finish the full cross-service transaction threading.
+    // The booking window must follow the new departure (an OPEN window's
+    // "closes in" countdown is capped at departure − close offset; PRE_WINDOW /
+    // DONE re-derive their open/close). Same math as maintenanceReschedule.
+    const windowFields = newDeparture
+      ? await this.trainSchedulingService.windowFieldsForNewDeparture(
+          schedule,
+          newDeparture,
+        )
+      : {};
+
     await this.dataSource.transaction(async (manager) => {
       if (newDeparture) {
-        // M7: raw write of scheduledDepartureDate. We deliberately do NOT
-        // delegate to TrainSchedulingService.updateScheduleDate, which only
-        // permits a date change while windowPhase === 'PRE_WINDOW' and would
-        // reject reschedules of already-open (SCHEDULED) trains. Consequence:
-        // the booking-window fields are NOT re-derived for the new date here.
+        // Raw write of scheduledDepartureDate: updateScheduleDate only permits a
+        // date change while windowPhase === 'PRE_WINDOW' and would reject
+        // reschedules of already-open (SCHEDULED) trains.
         await this.trainSchedulesRepository.updateStatus(
           scheduleId,
           schedule.status as TrainScheduleStatus,
-          { scheduledDepartureDate: newDeparture },
+          { scheduledDepartureDate: newDeparture, ...windowFields },
           manager,
         );
       }
@@ -263,6 +271,7 @@ export class SchedulingRescheduleService {
     // `newDeparture` is null when the date was unchanged, so retained customers
     // are not falsely told the train was rescheduled.
     await this.notifyRescheduleOutcome(dto, newDeparture);
+    if (newDeparture) void this.trainSchedulingService.emitWindowState(scheduleId);
 
     return { plan, schedule: assignResult };
   }
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
index ed099ad72..15cf4f592 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
@@ -1821,5 +1821,31 @@ describe('TrainSchedulingService', () => {
       expect(written.windowPhase).toBeUndefined();
       expect(written.windowOpensAt).toBeUndefined();
     });
+
+    it('moves an OPEN export close to the new departure but keeps the open', async () => {
+      const opensAt = new Date('2027-06-19T03:00:00.000Z');
+      trainSchedulesRepository.findByIdWithFullGraph.mockResolvedValue(
+        doneExportSchedule({
+          windowPhase: 'OPEN',
+          bookingWindowStatus: 'OPEN',
+          windowOpensAt: opensAt,
+          windowClosesAt: new Date('2027-06-20T03:00:00.000Z'),
+        }),
+      );
+
+      // Departure pushed 3 days later → close = new departure − 120min; the
+      // open customers already booked against stays untouched.
+      await service.maintenanceReschedule('sch-done', {
+        newDepartureDate: '2027-06-23T05:00:00.000Z',
+      } as never);
+
+      const written = scheduleUpdate.mock.calls[0][1];
+      expect(written.scheduledDepartureDate).toEqual(
+        new Date('2027-06-23T05:00:00.000Z'),
+      );
+      expect(written.windowClosesAt).toEqual(new Date('2027-06-23T03:00:00.000Z'));
+      expect(written.windowOpensAt).toBeUndefined();
+      expect(written.windowPhase).toBeUndefined();
+    });
   });
 });
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index 2effe6a37..0fb6e16ab 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -164,6 +164,8 @@ import {
 } from '../booking-batch.constants';
 import { orderConsistWagons } from '../consist-order.util';
 import {
+  bookingCloseCutoff,
+  clampCloseToOfficeHours,
   computeExportWindowTimes,
   computeImportWindowTimes,
   earliestSchedulableDeparture,
@@ -473,7 +475,7 @@ export class TrainSchedulingService {
    * used for lifecycle changes outside the window tick (create, cancel,
    * finalize, restamp). A push failure must never break the mutation.
    */
-  private async emitWindowState(scheduleId: string): Promise<void> {
+  async emitWindowState(scheduleId: string): Promise<void> {
     try {
       const fresh = await this.trainSchedulesRepository.findById(scheduleId);
       // Dedicated shipping-line departures are never announced to the portal —
@@ -1159,66 +1161,73 @@ export class TrainSchedulingService {
   }
 
   /**
-   * Maintenance reschedule: the admin moves a train (with everything aboard) to
-   * a new departure. Unlike {@link updateScheduleDate} this runs at ANY window
-   * phase and inside the booking lead window — a maintenance move is an
-   * operational fact, not a planning choice. What moves and what stays:
+   * Booking-window fields that must follow a train's departure moving to
+   * `departure` (any window phase). Shared by every reschedule path so the
+   * "closes in" countdown always tracks the real departure.
    *
-   *  - MOVES: scheduledDepartureDate; scheduledArrivalDate (same delta); every
-   *    aboard/targeted booking's scheduledDate (the day-pool queries key on it,
-   *    so a booking left on the old day would fall out of its own train's pool).
-   *  - STAYS: train set, wagon assignments, schedule↔booking links, route,
-   *    maxWagons, and the window RULE snapshot. Stamped window times are only
-   *    re-derived for PRE_WINDOW schedules (their window hasn't run yet); a
-   *    schedule mid- or post-window keeps its timeline untouched.
+   * PRE_WINDOW: the stamped open/close were derived from the old departure
+   * and the window hasn't opened yet, so re-derive them from the schedule's
+   * own rule snapshot against the new date (joining the target day's route
+   * group timeline when one exists, exactly like updateScheduleDate).
    *
-   * Customers of every moved booking are notified (maintenanceMoved).
+   * DONE: the window already finished (e.g. the close offset hit and then the
+   * train was moved to a later departure). The window must follow the new
+   * departure, so it REOPENS: re-derive open/close the same way, reset the
+   * phase to PRE_WINDOW and clamp a past open into the present so the tick
+   * opens it immediately. A FULL train stays closed — there is nothing left
+   * to sell — and so does one whose re-derived window would already be over.
+   *
+   * OPEN: customers are already booking against the open they were shown, so
+   * the open stays put — but the close was capped at the OLD departure's
+   * cutoff, so it must follow the new one (import: open + duration under
+   * office hours, capped at the cutoff; export: the cutoff itself). Moving
+   * the train later extends the "closes in" countdown, moving it earlier
+   * shortens it (a close now in the past is picked up by the next tick).
+   *
+   * DOC_REVIEW/PAYMENT keep their running timeline.
    */
-  async maintenanceReschedule(
-    id: string,
-    dto: MaintenanceRescheduleDto,
-  ): Promise<TrainSchedule> {
-    const schedule = await this.trainSchedulesRepository.findByIdWithFullGraph(id);
-    if (!schedule) {
-      throw new NotFoundException(`Train schedule ${id} not found`);
-    }
-    if (!['DRAFT', 'SCHEDULED'].includes(schedule.status)) {
-      throw new BadRequestException(
-        `Cannot reschedule a ${schedule.status.toLowerCase()} train`,
-      );
-    }
-
-    const departure = new Date(dto.newDepartureDate);
-    if (Number.isNaN(departure.getTime())) {
-      throw new BadRequestException('Invalid departure date.');
-    }
-    if (departure.getTime() <= Date.now()) {
-      throw new BadRequestException('New departure must be in the future.');
-    }
-
-    const deltaMs =
-      departure.getTime() - new Date(schedule.scheduledDepartureDate).getTime();
-    const scheduledArrivalDate = schedule.scheduledArrivalDate
-      ? new Date(new Date(schedule.scheduledArrivalDate).getTime() + deltaMs)
-      : undefined;
-
-    // PRE_WINDOW: the stamped open/close were derived from the old departure
-    // and the window hasn't opened yet, so re-derive them from the schedule's
-    // own rule snapshot against the new date (joining the target day's route
-    // group timeline when one exists, exactly like updateScheduleDate).
-    //
-    // DONE: the window already finished (e.g. the close offset hit and then the
-    // train was moved to a later departure). The window must follow the new
-    // departure, so it REOPENS: re-derive open/close the same way, reset the
-    // phase to PRE_WINDOW and clamp a past open into the present so the tick
-    // opens it immediately. A FULL train stays closed — there is nothing left
-    // to sell — and so does one whose re-derived window would already be over.
-    //
-    // Mid-window phases (OPEN/DOC_REVIEW/PAYMENT) keep their running timeline.
+  async windowFieldsForNewDeparture(
+    schedule: TrainSchedule,
+    departure: Date,
+  ): Promise<
+    Partial<
+      Pick<
+        TrainSchedule,
+        | 'windowOpensAt'
+        | 'windowClosesAt'
+        | 'windowPhase'
+        | 'bookingWindowStatus'
+        | 'docReviewCompletedAt'
+        | 'docReviewEndsAt'
+        | 'paymentPhaseEndsAt'
+      >
+    >
+  > {
     const reopenFromDone =
       schedule.windowPhase === 'DONE' && schedule.bookingWindowStatus !== 'FULL';
+    const shiftOpenClose =
+      schedule.windowPhase === 'OPEN' && schedule.windowOpensAt != null;
     const windowFields =
-      schedule.windowPhase === 'PRE_WINDOW' || reopenFromDone
+      shiftOpenClose
+        ? await (async () => {
+            const merged = effectiveWindowConfig(
+              schedule,
+              await this.getWindowConfig(),
+            );
+            const opensAt = schedule.windowOpensAt!;
+            const cutoff = bookingCloseCutoff(departure, schedule.direction, merged);
+            let closesAt = cutoff;
+            if (schedule.direction !== 'EXPORT') {
+              closesAt = clampCloseToOfficeHours(
+                opensAt,
+                new Date(opensAt.getTime() + merged.windowDurationHours * 3_600_000),
+                merged,
+              );
+              if (closesAt.getTime() > cutoff.getTime()) closesAt = cutoff;
+            }
+            return { windowClosesAt: closesAt };
+          })()
+        : schedule.windowPhase === 'PRE_WINDOW' || reopenFromDone
         ? await (async () => {
             const merged = effectiveWindowConfig(
               schedule,
@@ -1266,6 +1275,55 @@ export class TrainSchedulingService {
             };
           })()
         : {};
+    return windowFields;
+  }
+
+  /**
+   * Maintenance reschedule: the admin moves a train (with everything aboard) to
+   * a new departure. Unlike {@link updateScheduleDate} this runs at ANY window
+   * phase and inside the booking lead window — a maintenance move is an
+   * operational fact, not a planning choice. What moves and what stays:
+   *
+   *  - MOVES: scheduledDepartureDate; scheduledArrivalDate (same delta); every
+   *    aboard/targeted booking's scheduledDate (the day-pool queries key on it,
+   *    so a booking left on the old day would fall out of its own train's pool).
+   *  - STAYS: train set, wagon assignments, schedule↔booking links, route,
+   *    maxWagons, and the window RULE snapshot. Stamped window times are
+   *    re-derived for PRE_WINDOW schedules (their window hasn't run yet); an
+   *    OPEN schedule keeps its open but its close follows the new departure;
+   *    DOC_REVIEW/PAYMENT keep their timeline untouched.
+   *
+   * Customers of every moved booking are notified (maintenanceMoved).
+   */
+  async maintenanceReschedule(
+    id: string,
+    dto: MaintenanceRescheduleDto,
+  ): Promise<TrainSchedule> {
+    const schedule = await this.trainSchedulesRepository.findByIdWithFullGraph(id);
+    if (!schedule) {
+      throw new NotFoundException(`Train schedule ${id} not found`);
+    }
+    if (!['DRAFT', 'SCHEDULED'].includes(schedule.status)) {
+      throw new BadRequestException(
+        `Cannot reschedule a ${schedule.status.toLowerCase()} train`,
+      );
+    }
+
+    const departure = new Date(dto.newDepartureDate);
+    if (Number.isNaN(departure.getTime())) {
+      throw new BadRequestException('Invalid departure date.');
+    }
+    if (departure.getTime() <= Date.now()) {
+      throw new BadRequestException('New departure must be in the future.');
+    }
+
+    const deltaMs =
+      departure.getTime() - new Date(schedule.scheduledDepartureDate).getTime();
+    const scheduledArrivalDate = schedule.scheduledArrivalDate
+      ? new Date(new Date(schedule.scheduledArrivalDate).getTime() + deltaMs)
+      : undefined;
+
+    const windowFields = await this.windowFieldsForNewDeparture(schedule, departure);
 
     await this.dataSource.getRepository(TrainSchedule).update(id, {
       scheduledDepartureDate: departure,
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
index 0c6a3553a..8c2a3a912 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
@@ -500,7 +500,7 @@ export default function BookingRequestsPage() {
                 <FilterBar
                   defs={bookingFilterDefs}
                   controls={controls}
-                  searchPlaceholder="Search booking, contract or customer…"
+                  searchPlaceholder="Search booking, contract, customer or shipping line…"
                   viewId="booking-requests"
                 />
               </Box>
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx
index 029c53dd2..db57819d5 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ClearanceDocumentsPage.tsx
@@ -14,7 +14,7 @@ import { DatePickerInput } from "@mantine/dates";
 import { getDateRangePresets } from "@/components/common/dateRangePresets";
 import { useDebouncedValue } from "@mantine/hooks";
 import { keepPreviousData, useQuery } from "@tanstack/react-query";
-import { FileText, Inbox, RefreshCw, Search, User, X } from "lucide-react";
+import { FileText, Inbox, RefreshCw, Search, Ship, User, X } from "lucide-react";
 import { useCallback, useMemo, useState } from "react";
 import { useNavigate } from "react-router-dom";
 
@@ -75,6 +75,12 @@ const OWNERSHIP_OPTIONS = [
   { value: "false", label: "Private" },
 ];
 
+/** Who booked: shipping lines own bookings via `shippingLineCompanyId`, not a customer company. */
+const CUSTOMER_KIND_OPTIONS = [
+  { value: "SHIPPING_LINE", label: "Shipping line" },
+  { value: "CUSTOMER", label: "Customer" },
+];
+
 function startOfDayIso(d: Date): string {
   const x = new Date(d);
   x.setHours(0, 0, 0, 0);
@@ -98,6 +104,7 @@ export default function ClearanceDocumentsPage() {
   const [directionFilter, setDirectionFilter] = useState<string | null>(null);
   const [freightTypeFilter, setFreightTypeFilter] = useState<string | null>(null);
   const [ownershipFilter, setOwnershipFilter] = useState<string | null>(null);
+  const [customerKindFilter, setCustomerKindFilter] = useState<string | null>(null);
   const [createdFrom, setCreatedFrom] = useState<Date | null>(null);
   const [createdTo, setCreatedTo] = useState<Date | null>(null);
   const { pagination, setPagination } = usePagination({ pageSize: PAGE_SIZE });
@@ -118,6 +125,7 @@ export default function ClearanceDocumentsPage() {
       directionFilter,
       freightTypeFilter,
       ownershipFilter,
+      customerKindFilter,
       createdFrom,
       createdTo,
       page,
@@ -138,6 +146,9 @@ export default function ClearanceDocumentsPage() {
         ...(ownershipFilter
           ? { isGovernment: ownershipFilter as "true" | "false" }
           : {}),
+        ...(customerKindFilter
+          ? { customerKind: customerKindFilter as "SHIPPING_LINE" | "CUSTOMER" }
+          : {}),
         ...(createdFrom ? { createdFrom: startOfDayIso(createdFrom) } : {}),
         ...(createdTo ? { createdTo: endOfDayIso(createdTo) } : {}),
       }),
@@ -153,17 +164,29 @@ export default function ClearanceDocumentsPage() {
         header: () => <span className={bookingTable.headerCell}>Customer</span>,
         cell: ({ row }) => {
           const b = row.original;
-          const customer = b.isGovernment
-            ? (b.governmentInstitution ?? "Government")
-            : (b.company?.name ?? "—");
+          const isShippingLine = Boolean(b.shippingLineCompany ?? b.shippingLineCompanyId);
+          const customer = isShippingLine
+            ? (b.shippingLineCompany?.name ?? "Shipping line")
+            : b.isGovernment
+              ? (b.governmentInstitution ?? "Government")
+              : (b.company?.name ?? "—");
           return (
             <div className="flex items-center gap-3 py-1.5">
               <div className={bookingTable.rowIcon}>
-                <User className="size-4" strokeWidth={1.75} />
+                {isShippingLine ? (
+                  <Ship className="size-4" strokeWidth={1.75} />
+                ) : (
+                  <User className="size-4" strokeWidth={1.75} />
+                )}
               </div>
               <div className="min-w-0">
-                <p className="font-medium text-foreground">
+                <p className="flex items-center gap-1.5 font-medium text-foreground">
                   {customer}
+                  {isShippingLine ? (
+                    <Badge variant="secondary" className="h-4 shrink-0 px-1 text-[9px] font-medium">
+                      Shipping line
+                    </Badge>
+                  ) : null}
                 </p>
                 <p className="mt-0.5 flex items-center gap-1 text-xs text-muted-foreground">
                   <FileText className="size-3 shrink-0 opacity-70" />
@@ -267,7 +290,7 @@ export default function ClearanceDocumentsPage() {
             <Box px="md" pt="md" pb="sm" w="100%">
               <Group justify="space-between" gap="md" wrap="wrap">
                 <TextInput
-                  placeholder="Search booking, contract or customer…"
+                  placeholder="Search booking, contract, customer or shipping line…"
                   leftSection={<Search size={18} />}
                   value={query}
                   onChange={(e) => {
@@ -333,6 +356,19 @@ export default function ClearanceDocumentsPage() {
                   style={{ minWidth: 140 }}
                   aria-label="Filter by freight type"
                 />
+                <Select
+                  placeholder="Booked by"
+                  data={CUSTOMER_KIND_OPTIONS}
+                  value={customerKindFilter}
+                  onChange={(v) => {
+                    setCustomerKindFilter(v);
+                    resetPage();
+                  }}
+                  clearable
+                  radius="lg"
+                  style={{ minWidth: 140 }}
+                  aria-label="Filter by booked by"
+                />
                 <Select
                   placeholder="Gov / Private"
                   data={OWNERSHIP_OPTIONS}

From 0e228bfd8d242173f88b3d0751998985668bd4e6 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 17 Aug 2026 06:14:25 +0000
Subject: [PATCH 120/174] changes

---
 .../train-scheduling/services/train-scheduling.service.ts       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index 0fb6e16ab..03535135d 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -1368,7 +1368,7 @@ export class TrainSchedulingService {
    * in the future) using the CURRENT global-rules config. Schedules already OPEN or
    * past their window are left untouched — customers may have booked against the
    * times they were shown, so those stay frozen. Returns the count re-stamped.
-   */
+   */ 
   async restampPendingWindows(): Promise<number> {
     const cfg = await this.getWindowConfig();
     const now = new Date();

From 52fb705a3e847c309166522875a71af4b44a1809 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 17 Aug 2026 06:18:16 +0000
Subject: [PATCH 121/174] changes

---
 .../portal/src/pages/bookings/BookingsListPage.tsx              | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
index 4d7f3d3a0..175aec08f 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
@@ -26,7 +26,7 @@ import {
   LayoutList,
   MoreVertical,
   Package,
-  // Plus,
+  
   Search,
   Train,
   Wallet,

From 562ebf485cb52359cde23fcb583bf1006f8eb5c5 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Sun, 16 Aug 2026 19:15:04 +0000
Subject: [PATCH 122/174] fix(eims): thermal page-length used viewport height,
 not content height
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

scrollHeight is defined as the larger of an element's content height and its
own (viewport) height — for a receipt shorter than the placeholder 1123px
viewport, it silently returned the viewport height back, producing a
correctly-formatted but page-length-tall PDF with a huge trailing blank
strip below the real content. Found by actually rendering one and looking
at it, not caught by unit tests (buildThermalHtml is pure string output,
never exercises page.pdf() sizing).

Fix: use a deliberately tiny (100px) viewport height for the thermal
measurement pass, forcing content to overflow it so scrollHeight always
reflects the receipt's real height. Also round the computed mm value before
templating it into the CSS length string.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../modules/billing/documents/pdf-render.service.ts    | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts b/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts
index 21676c160..3767637a7 100644
--- a/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/pdf-render.service.ts
@@ -84,7 +84,13 @@ export class PdfRenderService {
         const page = await browser.newPage();
         const thermal = opts.thermal ?? false;
         const viewportWidth = thermal ? Math.round((THERMAL_PAGE_WIDTH_MM / 25.4) * 96) : 794;
-        await page.setViewport({ width: viewportWidth, height: 1123, deviceScaleFactor: 1 });
+        // Thermal viewport height is deliberately tiny (not a real page height at all): scrollHeight
+        // is defined as the LARGER of the content's height and the viewport's own height, so a
+        // receipt shorter than the viewport would otherwise report the viewport height back, not
+        // its true content height — a real page-length trailing blank space bug, not theoretical
+        // (confirmed by actually rendering one). A short viewport forces content to overflow it,
+        // so scrollHeight always reflects the content, never the viewport.
+        await page.setViewport({ width: viewportWidth, height: thermal ? 100 : 1123, deviceScaleFactor: 1 });
         await page.setContent(preparedHtml, { waitUntil: "load", timeout: 60_000 });
         await page.emulateMediaType("print");
         await new Promise((resolve) => setTimeout(resolve, 250));
@@ -154,7 +160,7 @@ export class PdfRenderService {
     // browser context regardless, same as the closure form would be.
     const scrollPx = (await page.evaluate("document.documentElement.scrollHeight")) as number;
     const contentMm = (scrollPx / 96) * 25.4 + THERMAL_MARGIN_MM * 2 + THERMAL_FEED_MM;
-    return Math.min(THERMAL_MAX_HEIGHT_MM, contentMm);
+    return Math.min(THERMAL_MAX_HEIGHT_MM, Math.round(contentMm * 100) / 100);
   }
 
   private injectPdfPrintStyles(html: string): string {

From 09bc7c74d73e2262e83157ab7cb493b114f83e28 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 17 Aug 2026 07:18:39 +0000
Subject: [PATCH 123/174] feat(eims): derive buyer City/Country from company
 profile, not global config
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

City: EimsMapperContext.buyerCity was declared but never wired anywhere —
always null, silently, for every buyer. No dedicated city column on Company;
derives from Zone via a new EIMS_BUYER_CITY_CODES map, same lookup mechanism
as Region/Wereda but optional (an unmapped zone resolves to null rather than
throwing) — MoR has already accepted a live filing with City null.

Country: previously a single flat EIMS_BUYER_COUNTRY_CODE applied to every
buyer regardless of Company.country. Now reads company.country, resolved via
a new EIMS_BUYER_COUNTRY_CODES name-to-code map; the flat env var becomes a
domestic-only fallback (applies only when country is empty/Ethiopia), so an
unmapped foreign buyer fails locally instead of silently filing as Ethiopia.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../edr-freight-api/src/config/eims.config.ts | 22 ++++++
 .../billing/eims-invoice.mapper.spec.ts       | 53 ++++++++++++-
 .../modules/billing/eims-invoice.mapper.ts    | 78 ++++++++++++++++---
 .../src/modules/eims/eims-invoice-context.ts  |  2 +
 .../src/modules/eims/eims-test-fixtures.ts    |  2 +
 5 files changed, 147 insertions(+), 10 deletions(-)

diff --git a/apps/edr-freight-api/src/config/eims.config.ts b/apps/edr-freight-api/src/config/eims.config.ts
index cf77072e0..c5565cbc1 100644
--- a/apps/edr-freight-api/src/config/eims.config.ts
+++ b/apps/edr-freight-api/src/config/eims.config.ts
@@ -80,7 +80,19 @@ export interface EimsInvoiceConfig {
   paymentMode: string;
   paymentTerm: string;
   unitDefault: string;
+  /**
+   * Domestic fallback only — used when the buyer's `Company.country` is empty or "Ethiopia" (the
+   * column's own default) and not already listed in `buyerCountryCodes`. A genuinely foreign
+   * buyer must be in `buyerCountryCodes` by name or the mapping fails locally; this value is never
+   * applied to them, so an unconfigured foreign country can't silently be filed as Ethiopia.
+   */
   buyerCountryCode: string | null;
+  /**
+   * Country name → MoR code, from `EIMS_BUYER_COUNTRY_CODES` ("Ethiopia=231,Djibouti=071"). Format
+   * unconfirmed (unlike Region/Wereda, MoR has never named a Country regex), so — unlike them —
+   * this is not validated against a fixed digit pattern, only looked up by name.
+   */
+  buyerCountryCodes: Record<string, string>;
   /**
    * Buyer region name → MoR numeric code, from `EIMS_BUYER_REGION_CODES`
    * ("Addis Ababa=13,Oromia=4"). A buyer whose region is neither a code nor in this map fails
@@ -89,6 +101,14 @@ export interface EimsInvoiceConfig {
   buyerRegionCodes: Record<string, string>;
   /** Same mechanism as `buyerRegionCodes`, for `EIMS_BUYER_WEREDA_CODES` ("Yeka=574"). */
   buyerWeredaCodes: Record<string, string>;
+  /**
+   * Buyer *zone* name → MoR City code, from `EIMS_BUYER_CITY_CODES` ("Kirkos=101"). `Company` has
+   * no dedicated city column — Zone is the closest match in EDR's own data. Optional, unlike
+   * Region/Wereda: MoR has never required City on a live buyer (confirmed — filing already
+   * succeeds with it null), so an unmapped zone falls back to null rather than failing the
+   * mapping.
+   */
+  buyerCityCodes: Record<string, string>;
   /**
    * Per-`chargeType` tax treatment, e.g. `EIMS_TAX_CODE_BY_CHARGE_TYPE=RAIL_FREIGHT=VAT0` +
    * `EIMS_TAX_RATE_BY_CHARGE_TYPE=RAIL_FREIGHT=0`. A charge type not listed here falls back to
@@ -208,8 +228,10 @@ export default registerAs("eims", (): EimsConfig => {
       paymentTerm: process.env.EIMS_PAYMENT_TERM ?? "",
       unitDefault: process.env.EIMS_UNIT_DEFAULT ?? "",
       buyerCountryCode: process.env.EIMS_BUYER_COUNTRY_CODE || null,
+      buyerCountryCodes: parseCodeMap(process.env.EIMS_BUYER_COUNTRY_CODES),
       buyerRegionCodes: parseCodeMap(process.env.EIMS_BUYER_REGION_CODES),
       buyerWeredaCodes: parseCodeMap(process.env.EIMS_BUYER_WEREDA_CODES),
+      buyerCityCodes: parseCodeMap(process.env.EIMS_BUYER_CITY_CODES),
       taxCodeByChargeType: parseCodeMap(process.env.EIMS_TAX_CODE_BY_CHARGE_TYPE),
       taxRateByChargeType: parseCodeMap(process.env.EIMS_TAX_RATE_BY_CHARGE_TYPE),
       exciseByChargeType: parseCodeMap(process.env.EIMS_EXCISE_BY_CHARGE_TYPE),
diff --git a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts
index 7406613fc..6d58a7bec 100644
--- a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts
@@ -60,8 +60,11 @@ const context = (over: Partial<EimsMapperContext> = {}): EimsMapperContext => ({
   unitDefault: "PCS",
   incomeWithholdValue: 0,
   transactionWithholdValue: 0,
+  buyerCountryCode: "231", // test-only, not a confirmed real MoR code
+  buyerCountryCodes: {},
   buyerRegionCodes: { "Addis Ababa": "13" },
   buyerWeredaCodes: {},
+  buyerCityCodes: {},
   ...over,
 });
 
@@ -92,6 +95,9 @@ describe("toEimsInvoice", () => {
 
     expect(doc.BuyerDetails).toEqual({
       City: null,
+      // company.country is "Ethiopia" (the domestic default) — resolves to context's flat
+      // buyerCountryCode fallback, not null, per resolveCountryCode.
+      Country: "231",
       Email: "buyer@abc.et",
       HouseNumber: "NEW",
       IdNumber: null,
@@ -100,7 +106,6 @@ describe("toEimsInvoice", () => {
       LegalName: "ABC Trading PLC",
       Phone: "0912345678",
       Region: "13",
-      Country: null,
       Zone: "SHA",
       Kebele: "03",
       VatNumber: "123475885858",
@@ -335,6 +340,52 @@ describe("toEimsInvoice — MoR field constraints", () => {
     ).toThrow(/buyer Wereda "Yeka".*EIMS_BUYER_WEREDA_CODES/);
   });
 
+  it("derives City from the buyer's zone via the city code map", () => {
+    const doc = toEimsInvoice(
+      invoice({ company: { ...invoice().company!, zone: "Kirkos" } }),
+      seller,
+      context({ buyerCityCodes: { Kirkos: "101" } }),
+    );
+    expect(doc.BuyerDetails.City).toBe("101");
+  });
+
+  it("leaves City null (not a throw) when the buyer's zone has no city mapping — City is optional", () => {
+    const doc = toEimsInvoice(
+      invoice({ company: { ...invoice().company!, zone: "Somewhere Else" } }),
+      seller,
+      context({ buyerCityCodes: {} }),
+    );
+    expect(doc.BuyerDetails.City).toBeNull();
+  });
+
+  it("maps a buyer country name to its code via the country code map", () => {
+    const doc = toEimsInvoice(
+      invoice({ company: { ...invoice().company!, country: "Djibouti" } }),
+      seller,
+      context({ buyerCountryCodes: { Djibouti: "071" } }),
+    );
+    expect(doc.BuyerDetails.Country).toBe("071");
+  });
+
+  it("falls back to the flat domestic country code only for Ethiopia, not any unmapped country", () => {
+    const doc = toEimsInvoice(
+      invoice({ company: { ...invoice().company!, country: "Ethiopia" } }),
+      seller,
+      context({ buyerCountryCode: "231", buyerCountryCodes: {} }),
+    );
+    expect(doc.BuyerDetails.Country).toBe("231");
+  });
+
+  it("refuses a genuinely foreign buyer country with no mapping — never silently files it as Ethiopia", () => {
+    expect(() =>
+      toEimsInvoice(
+        invoice({ company: { ...invoice().company!, country: "Kenya" } }),
+        seller,
+        context({ buyerCountryCode: "231", buyerCountryCodes: {} }),
+      ),
+    ).toThrow(/buyer Country "Kenya".*EIMS_BUYER_COUNTRY_CODES/);
+  });
+
   it("emits NatureOfSupplies lowercase, whatever case it was configured in", () => {
     const doc = toEimsInvoice(invoice(), seller, context({ natureOfSupplies: "Service" }));
     expect(doc.ItemList[0].NatureOfSupplies).toBe("service");
diff --git a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
index 582e3d326..406952867 100644
--- a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
+++ b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
@@ -234,8 +234,13 @@ export interface EimsMapperContext {
    * from a registered invoice").
    */
   relatedDocument?: string | null;
-  /** MoR numeric country code for the buyer; our DB stores the country name. */
+  /**
+   * Domestic fallback only, applied when `company.country` is empty or "Ethiopia" and not already
+   * in `buyerCountryCodes` — see that field. Never applied to a genuinely foreign buyer.
+   */
   buyerCountryCode?: string | null;
+  /** Country name → MoR code. Format unconfirmed, so looked up by name only, not digit-validated. */
+  buyerCountryCodes: Record<string, string>;
   /**
    * Region name → MoR numeric code, for buyers whose stored region is free text.
    *
@@ -252,9 +257,15 @@ export interface EimsMapperContext {
    * fail locally on an unmapped name rather than file a guess.
    */
   buyerWeredaCodes: Record<string, string>;
+  /**
+   * Buyer *zone* name → MoR City code. `Company` has no dedicated city column; Zone is the
+   * closest match in EDR's own data. Unlike Region/Wereda, City is optional — MoR has already
+   * accepted a live filing with it null — so an unmapped zone resolves to null, it does not fail
+   * the mapping.
+   */
+  buyerCityCodes: Record<string, string>;
   buyerIdType?: string | null;
   buyerIdNumber?: string | null;
-  buyerCity?: string | null;
   /** Required when the invoice currency is not ETB. */
   exchangeRate?: number | null;
   invoiceDiscount?: number | null;
@@ -299,17 +310,22 @@ export const formatEimsDate = (issuedAt: Date): string =>
  * exchange rate.
  */
 /**
- * A buyer's location value (Region or Wereda) as a MoR code: passed through when already numeric,
- * otherwise looked up by name (case- and space-insensitive). Throws when neither applies — sending
- * a guessed code onto a tax document is worse than refusing to file.
+ * A buyer's location value (Region, Wereda or City) as a MoR code: passed through when already
+ * numeric, otherwise looked up by name (case- and space-insensitive).
+ *
+ * Region/Wereda are required: an unmapped value throws — sending a guessed code onto a tax
+ * document is worse than refusing to file. City is optional (`required: false`, City's own
+ * caller) — MoR has already accepted a live filing with it null, so an unmapped zone resolves to
+ * null instead of blocking the invoice.
  */
 function resolveLocationCode(
-  field: "Region" | "Wereda",
+  field: "Region" | "Wereda" | "City",
   value: string | null | undefined,
   codes: Record<string, string>,
   envVar: string,
   invoiceNumber: string,
-): string {
+  opts: { required?: boolean } = {},
+): string | null {
   const raw = (value ?? "").trim();
   if (LOCATION_CODE.test(raw)) return raw;
 
@@ -319,12 +335,42 @@ function resolveLocationCode(
   )?.[1];
   if (mapped && LOCATION_CODE.test(mapped)) return mapped;
 
+  if (opts.required === false) return null;
+
   throw new Error(
     `EIMS mapping: invoice ${invoiceNumber} has buyer ${field} ${raw ? `"${raw}"` : "(unset)"}, ` +
       `which is not a MoR ${field} code and has no mapping. Add it to ${envVar}.`,
   );
 }
 
+/**
+ * A buyer's `Country` as a MoR code: looked up by name in `codes` first; when unmapped, applies
+ * `domesticFallback` only if the stored country is empty or "Ethiopia" (the DB column's default).
+ * A genuinely foreign, unmapped country throws rather than silently filing as Ethiopia — same
+ * "fail locally, don't guess" rule as `resolveLocationCode`, but never digit-validated: MoR's
+ * Country code format is unconfirmed, unlike Region/Wereda's proven `^[0-9]{1,3}$`.
+ */
+function resolveCountryCode(
+  country: string | null | undefined,
+  codes: Record<string, string>,
+  domesticFallback: string | null,
+  invoiceNumber: string,
+): string | null {
+  const raw = (country ?? "").trim();
+  const key = raw.toLowerCase().replace(/\s+/g, " ");
+  const mapped = Object.entries(codes).find(
+    ([name]) => name.trim().toLowerCase().replace(/\s+/g, " ") === key,
+  )?.[1];
+  if (mapped) return mapped;
+
+  if ((!raw || key === "ethiopia") && domesticFallback) return domesticFallback;
+
+  throw new Error(
+    `EIMS mapping: invoice ${invoiceNumber} has buyer Country "${raw || "(unset)"}", which has no ` +
+      "MoR country code mapping. Add it to EIMS_BUYER_COUNTRY_CODES.",
+  );
+}
+
 export function toEimsInvoice(
   invoice: EimsMapperInvoice,
   seller: EimsSellerDetails,
@@ -440,7 +486,16 @@ export function toEimsInvoice(
 
   return {
     BuyerDetails: {
-      City: context.buyerCity ?? null,
+      // No dedicated city column on Company — Zone is the closest match; optional (see
+      // resolveLocationCode's City comment).
+      City: resolveLocationCode(
+        "City",
+        company.zone,
+        context.buyerCityCodes,
+        "EIMS_BUYER_CITY_CODES",
+        invoice.invoiceNumber,
+        { required: false },
+      ),
       Email: company.email ?? null,
       HouseNumber: company.houseNo ?? null,
       IdNumber: context.buyerIdNumber ?? null,
@@ -455,7 +510,12 @@ export function toEimsInvoice(
         "EIMS_BUYER_REGION_CODES",
         invoice.invoiceNumber,
       ),
-      Country: context.buyerCountryCode ?? null,
+      Country: resolveCountryCode(
+        company.country,
+        context.buyerCountryCodes,
+        context.buyerCountryCode ?? null,
+        invoice.invoiceNumber,
+      ),
       Zone: company.zone ?? null,
       Kebele: company.kebele ?? null,
       VatNumber: company.vatNumber ?? null,
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts
index b77804eda..4c1c82c10 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-context.ts
@@ -206,8 +206,10 @@ export function buildEimsContext(config: EimsConfig, input: EimsContextInput): E
     incomeWithholdValue: invoice.incomeWithholdValue!,
     transactionWithholdValue: invoice.transactionWithholdValue!,
     buyerCountryCode: invoice.buyerCountryCode,
+    buyerCountryCodes: invoice.buyerCountryCodes,
     buyerRegionCodes: invoice.buyerRegionCodes,
     buyerWeredaCodes: invoice.buyerWeredaCodes,
+    buyerCityCodes: invoice.buyerCityCodes,
     // TEMPORARY — see EimsInvoiceConfig.buyerIdType.
     buyerIdType: invoice.buyerIdType,
     buyerIdNumber: invoice.buyerIdNumber,
diff --git a/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts b/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts
index 93df29da2..650a834b8 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts
@@ -33,8 +33,10 @@ export const eimsInvoiceConfig = (over: Partial<EimsInvoiceConfig> = {}): EimsIn
   paymentTerm: "IMMIDIATE",
   unitDefault: "PCS",
   buyerCountryCode: null,
+  buyerCountryCodes: { Ethiopia: "231" }, // test-only, not a confirmed real MoR code
   buyerRegionCodes: { "Addis Ababa": "13" },
   buyerWeredaCodes: { Yeka: "99" }, // test-only, not a real MoR code
+  buyerCityCodes: { Kirkos: "101" }, // test-only, not a confirmed real MoR code
   taxCodeByChargeType: {},
   taxRateByChargeType: {},
   exciseByChargeType: {},

From 28c9dd93e07286e21c187e5ead39023e72c0b6d8 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 17 Aug 2026 07:40:40 +0000
Subject: [PATCH 124/174] feat(eims): seller identity enriched from e-Trade,
 cached (bootstrap only)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ten EIMS_SELLER_* env vars were the only source of EDR's own seller identity,
duplicating data the platform already has via the same e-Trade lookup used
for every customer company at onboarding. EimsSellerCacheService now enriches
it — but static config remains the source of truth: MoR validates
SellerDetails against its own taxpayer registry (rule 7017, already cleared
against the current static values), so e-Trade fills a field only when the
static value is blank, never overrides one already confirmed. The static
config is therefore the durable fallback, not the cache; an in-memory
snapshot lost on restart is harmless.

ETradeService has no request timeout of its own and no AbortController, so
the cache enforces one locally (stops waiting, doesn't cancel the request)
and de-duplicates concurrent refresh() calls into the same in-flight promise.
getSellerDetails() is fully synchronous — zero I/O — so live registration
never depends on e-Trade being reachable, at boot or per invoice.

VatNumber and Email stay on static config permanently — confirmed by reading
e-Trade's actual response shapes, neither field exists anywhere in what it
returns. Region/Wereda/City reuse the existing EIMS_BUYER_*_CODES maps rather
than adding seller-specific ones — the geography is objective, not
buyer-specific.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../modules/billing/eims-invoice.mapper.ts    |  19 +++
 .../src/modules/companies/companies.module.ts |   3 +
 .../eims-invoice-registration.service.spec.ts |   5 +
 .../eims/eims-invoice-registration.service.ts |  10 +-
 .../eims/eims-seller-cache.service.spec.ts    | 155 ++++++++++++++++++
 .../modules/eims/eims-seller-cache.service.ts | 147 +++++++++++++++++
 .../src/modules/eims/eims.module.ts           |   7 +
 7 files changed, 340 insertions(+), 6 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/eims/eims-seller-cache.service.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/eims/eims-seller-cache.service.ts

diff --git a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
index 406952867..b8755c709 100644
--- a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
+++ b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
@@ -371,6 +371,25 @@ function resolveCountryCode(
   );
 }
 
+/**
+ * Same name-or-code resolution as `resolveLocationCode`, for a caller with no invoice to attach an
+ * error to and that must never throw — currently only `EimsSellerCacheService`, resolving
+ * e-Trade's region/zone/woreda *names* for EDR's own seller identity. Pass-through numeric code,
+ * name lookup, `undefined` on no match — the caller falls back to static config either way.
+ */
+export function resolveOptionalCode(
+  value: string | null | undefined,
+  codes: Record<string, string>,
+): string | undefined {
+  const raw = (value ?? "").trim();
+  if (LOCATION_CODE.test(raw)) return raw;
+  const key = raw.toLowerCase().replace(/\s+/g, " ");
+  const mapped = Object.entries(codes).find(
+    ([name]) => name.trim().toLowerCase().replace(/\s+/g, " ") === key,
+  )?.[1];
+  return mapped && LOCATION_CODE.test(mapped) ? mapped : undefined;
+}
+
 export function toEimsInvoice(
   invoice: EimsMapperInvoice,
   seller: EimsSellerDetails,
diff --git a/apps/edr-freight-api/src/modules/companies/companies.module.ts b/apps/edr-freight-api/src/modules/companies/companies.module.ts
index b990aa8f0..666634cb8 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.module.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.module.ts
@@ -67,6 +67,9 @@ import { VerifaydaModule } from "../verifayda/verifayda.module";
     // Consumed by NotificationInboxModule for portal recipient targeting.
     ExternalProfileRepository,
     CompanyProfileRepository,
+    // Consumed by EimsModule's EimsSellerCacheService — same e-Trade business-registry lookup
+    // already used for every customer company at onboarding, reused for EDR's own TIN.
+    ETradeService,
   ],
 })
 export class CompaniesModule { }
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
index 36c355bed..79d3204dd 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
@@ -11,7 +11,9 @@ import { NotificationsService } from "../notifications/notifications.service";
 import { EimsAuthService } from "./eims-auth.service";
 import { EimsClientService } from "./eims-client.service";
 import { EimsApiException } from "./eims.errors";
+import { buildEimsSeller } from "./eims-invoice-context";
 import { EimsInvoiceRegistrationService } from "./eims-invoice-registration.service";
+import { EimsSellerCacheService } from "./eims-seller-cache.service";
 import { EimsSystemState } from "./entities/eims-system-state.entity";
 import { EimsInvoiceStatus } from "./eims-registration.types";
 
@@ -172,6 +174,9 @@ const build = (
     } as unknown as EimsAuthService,
     { notify } as unknown as NotificationInboxService,
     { directSend } as unknown as NotificationsService,
+    // Same static-config seller the real EimsSellerCacheService falls back to when it has never
+    // successfully fetched e-Trade — matches prior behavior for every test in this file.
+    { getSellerDetails: (c: EimsConfig) => buildEimsSeller(c) } as unknown as EimsSellerCacheService,
   );
 
 /**
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
index ab9f953c5..2ca5f5ffd 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
@@ -27,12 +27,9 @@ import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
 import { EimsAuthService } from "./eims-auth.service";
 import { EimsClientService } from "./eims-client.service";
 import { EimsApiException } from "./eims.errors";
+import { EimsSellerCacheService } from "./eims-seller-cache.service";
 import { EimsSystemState } from "./entities/eims-system-state.entity";
-import {
-  assertEimsInvoiceConfig,
-  buildEimsContext,
-  buildEimsSeller,
-} from "./eims-invoice-context";
+import { assertEimsInvoiceConfig, buildEimsContext } from "./eims-invoice-context";
 import {
   EimsInvoiceError,
   EimsInvoiceStatus,
@@ -83,6 +80,7 @@ export class EimsInvoiceRegistrationService {
     private readonly auth: EimsAuthService,
     private readonly inbox: NotificationInboxService,
     private readonly notifications: NotificationsService,
+    private readonly sellerCache: EimsSellerCacheService,
   ) {}
 
   private get cfg(): EimsConfig {
@@ -128,7 +126,7 @@ export class EimsInvoiceRegistrationService {
     // The request can only be built now: InvoiceCounter and PreviousIrn come from the reservation.
     const request = toEimsInvoice(
       invoice,
-      buildEimsSeller(cfg),
+      this.sellerCache.getSellerDetails(cfg),
       buildEimsContext(cfg, {
         // Allocated from the system state, not our invoiceNumber: MoR validates DocumentNumber
         // against ^(0|[1-9][0-9]{0,8})$, which "INV-20260807-00006" can never satisfy.
diff --git a/apps/edr-freight-api/src/modules/eims/eims-seller-cache.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-seller-cache.service.spec.ts
new file mode 100644
index 000000000..7b4ff1b3f
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/eims-seller-cache.service.spec.ts
@@ -0,0 +1,155 @@
+import { ConfigService } from "@nestjs/config";
+
+import { EimsConfig } from "../../config/eims.config";
+import { ETradeService } from "../companies/services/etrade.service";
+import { eimsConfig, eimsInvoiceConfig } from "./eims-test-fixtures";
+import { EimsSellerCacheService } from "./eims-seller-cache.service";
+
+const registrationData = (over: Record<string, unknown> = {}) => ({
+  companyName: "Ethio-Djibouti Railway PLC (eTrade)",
+  region: "Addis Ababa",
+  zone: "Bole",
+  woreda: "Yeka",
+  mobilePhone: "0911000000",
+  regularPhone: "",
+  ...over,
+});
+
+const build = (cfg: EimsConfig = eimsConfig()) => {
+  const resolveCompanyData = jest.fn();
+  const extractRegistrationData = jest.fn().mockReturnValue(registrationData());
+  const etrade = { resolveCompanyData, extractRegistrationData } as unknown as ETradeService;
+  const config = { get: () => cfg } as unknown as ConfigService;
+  const service = new EimsSellerCacheService(etrade, config);
+  return { service, resolveCompanyData, extractRegistrationData, cfg };
+};
+
+const CODES = {
+  buyerRegionCodes: { "Addis Ababa": "13" },
+  buyerWeredaCodes: { Yeka: "99" },
+  buyerCityCodes: { Bole: "101" },
+};
+
+describe("EimsSellerCacheService.getSellerDetails", () => {
+  it("static config wins over a conflicting e-Trade value", async () => {
+    const cfg = eimsConfig({
+      invoice: eimsInvoiceConfig({ sellerLegalName: "Ethio-Djibouti Railway S.C.", ...CODES }),
+    });
+    const { service, resolveCompanyData } = build(cfg);
+    resolveCompanyData.mockResolvedValue({
+      companyInfo: {},
+      businessInfo: {}, // presence is all that matters — extractRegistrationData is mocked
+    });
+
+    await service.refresh();
+    const seller = service.getSellerDetails(cfg);
+
+    // The static sellerLegalName ("Ethio-Djibouti Railway S.C.") must survive, not e-Trade's
+    // differently-punctuated "Ethio-Djibouti Railway PLC (eTrade)".
+    expect(seller.LegalName).toBe("Ethio-Djibouti Railway S.C.");
+  });
+
+  it("e-Trade fills a field only when the static value is blank", async () => {
+    const cfg = eimsConfig({
+      invoice: eimsInvoiceConfig({
+        sellerLegalName: "",
+        sellerRegion: "",
+        sellerWereda: "",
+        sellerCity: null,
+        ...CODES,
+      }),
+    });
+    const { service, resolveCompanyData } = build(cfg);
+    resolveCompanyData.mockResolvedValue({ companyInfo: {}, businessInfo: {} });
+
+    await service.refresh();
+    const seller = service.getSellerDetails(cfg);
+
+    expect(seller.LegalName).toBe("Ethio-Djibouti Railway PLC (eTrade)");
+    expect(seller.Region).toBe("13");
+    expect(seller.Wereda).toBe("99");
+    expect(seller.City).toBe("101");
+  });
+
+  it("VatNumber and Email are always the static value, never touched by e-Trade", async () => {
+    const cfg = eimsConfig({
+      invoice: eimsInvoiceConfig({ sellerVatNumber: "0000000000", sellerEmail: "finance@example.et", ...CODES }),
+    });
+    const { service, resolveCompanyData } = build(cfg);
+    resolveCompanyData.mockResolvedValue({ companyInfo: {}, businessInfo: {} });
+
+    await service.refresh();
+    const seller = service.getSellerDetails(cfg);
+
+    expect(seller.VatNumber).toBe("0000000000");
+    expect(seller.Email).toBe("finance@example.et");
+  });
+
+  it("falls back to the static config entirely when e-Trade has never been reachable", () => {
+    const cfg = eimsConfig();
+    const { service } = build(cfg);
+
+    // No refresh() ever called/succeeded — cached stays null.
+    const seller = service.getSellerDetails(cfg);
+
+    expect(seller.LegalName).toBe(cfg.invoice.sellerLegalName);
+    expect(seller.Region).toBe(cfg.invoice.sellerRegion);
+  });
+
+  it("does no I/O at all — filing never triggers an e-Trade request", () => {
+    const { service, resolveCompanyData, cfg } = build();
+
+    service.getSellerDetails(cfg);
+    service.getSellerDetails(cfg);
+
+    expect(resolveCompanyData).not.toHaveBeenCalled();
+  });
+});
+
+describe("EimsSellerCacheService.refresh", () => {
+  it("keeps the previous snapshot when a refresh fails", async () => {
+    const cfg = eimsConfig({ invoice: eimsInvoiceConfig({ sellerLegalName: "", ...CODES }) });
+    const { service, resolveCompanyData } = build(cfg);
+    resolveCompanyData.mockResolvedValueOnce({ companyInfo: {}, businessInfo: {} });
+    await service.refresh();
+    expect(service.getSellerDetails(cfg).LegalName).toBe("Ethio-Djibouti Railway PLC (eTrade)");
+
+    resolveCompanyData.mockRejectedValueOnce(new Error("eTrade down"));
+    await service.refresh();
+
+    expect(service.getSellerDetails(cfg).LegalName).toBe("Ethio-Djibouti Railway PLC (eTrade)");
+  });
+
+  it("keeps the previous snapshot on timeout, without waiting for the slow request", async () => {
+    jest.useFakeTimers();
+    try {
+      const cfg = eimsConfig({ invoice: eimsInvoiceConfig({ sellerLegalName: "", ...CODES }) });
+      const { service, resolveCompanyData } = build(cfg);
+      resolveCompanyData.mockResolvedValueOnce({ companyInfo: {}, businessInfo: {} });
+      await service.refresh();
+      expect(service.getSellerDetails(cfg).LegalName).toBe("Ethio-Djibouti Railway PLC (eTrade)");
+
+      resolveCompanyData.mockReturnValueOnce(new Promise(() => {})); // never resolves
+      const refreshing = service.refresh();
+      await jest.advanceTimersByTimeAsync(10_000);
+      await refreshing;
+
+      expect(service.getSellerDetails(cfg).LegalName).toBe("Ethio-Djibouti Railway PLC (eTrade)");
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it("does not start a second e-Trade request while one is already in flight", async () => {
+    const { service, resolveCompanyData } = build();
+    let resolveCall: (value: unknown) => void = () => {};
+    resolveCompanyData.mockReturnValue(new Promise((resolve) => (resolveCall = resolve)));
+
+    const first = service.refresh();
+    const second = service.refresh();
+    resolveCall({ companyInfo: {}, businessInfo: {} });
+    await Promise.all([first, second]);
+
+    expect(resolveCompanyData).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/eims/eims-seller-cache.service.ts b/apps/edr-freight-api/src/modules/eims/eims-seller-cache.service.ts
new file mode 100644
index 000000000..a8d242929
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/eims-seller-cache.service.ts
@@ -0,0 +1,147 @@
+import { Injectable, Logger, OnModuleInit } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+
+import { EimsConfig } from "../../config/eims.config";
+import { ETradeService } from "../companies/services/etrade.service";
+import { EimsSellerDetails, resolveOptionalCode } from "../billing/eims-invoice.mapper";
+import { buildEimsSeller } from "./eims-invoice-context";
+
+const has = (value: string | null | undefined): value is string => Boolean(value && value.trim());
+
+/**
+ * EDR's own EIMS seller identity (LegalName/Phone/Region/Wereda/City), enriched from the same
+ * e-Trade business-registry lookup already used for every customer company at onboarding — instead
+ * of the whole thing being hand-maintained `EIMS_SELLER_*` config.
+ *
+ * **Static config is the source of truth, e-Trade is bootstrap/enrichment only.** MoR validates
+ * `SellerDetails` against its own taxpayer registry (rule 7017, already cleared and live-tested
+ * with the current static values) — e-Trade filling a gap is fine, e-Trade silently overriding a
+ * value already confirmed against MoR is not. `getSellerDetails` therefore only reaches for the
+ * e-Trade-derived value when the static one is blank; a static value, once set, is never replaced.
+ * This also means the durable fallback is the static config, not this cache — the in-memory
+ * snapshot disappearing on a process restart is harmless, not a reliability gap: every field it
+ * could supply already has a working static value today, so filing is unaffected either way.
+ *
+ * `VatNumber` and `Email` are never sourced here — confirmed by reading e-Trade's actual response
+ * shapes (`ETradeCompanyInfo`, `ETradeBusinessInfo`, `CompanyRegistrationData`): neither field
+ * exists anywhere in what e-Trade returns. They stay on static config permanently, same as
+ * `SubCity`/`Locality`/`HouseNumber`, which this pass doesn't touch.
+ *
+ * Cache shape follows `PositionTypePermissionsCache`'s precedent (`src/common/
+ * position-type-permissions.cache.ts`) for "external/slow data, not fetched per request": a plain
+ * field refreshed on a raw `setInterval`, `unref()`'d so it never holds the process open, and a
+ * refresh failure keeps serving the previous snapshot rather than clearing it. Two deliberate
+ * deviations from that precedent, both because `ETradeService` has no request timeout configured
+ * at all (confirmed by reading it) and is a third-party dependency, unlike the DB:
+ *  - the first fetch is fire-and-forget in `onModuleInit`, never awaited by boot;
+ *  - `refresh()` is wrapped in a local timeout, and a second call while one is already in flight
+ *    returns the same in-flight promise instead of starting a duplicate request.
+ *
+ * `getSellerDetails` is fully synchronous — zero I/O at call time — so a live invoice registration
+ * never depends on e-Trade being reachable at that moment, whether or not it ever has been.
+ */
+@Injectable()
+export class EimsSellerCacheService implements OnModuleInit {
+  private readonly logger = new Logger(EimsSellerCacheService.name);
+
+  /** Only the e-Trade-derived fields, used solely to fill a blank static value. */
+  private cached: Partial<EimsSellerDetails> | null = null;
+  /** Concurrency guard — a second `refresh()` call while one is running joins it. */
+  private refreshing: Promise<void> | null = null;
+
+  // ponytail: daily refresh, no invalidation hook — a change at e-Trade takes up to 24h to reach a
+  // filed invoice. Wire a manual refresh() call (e.g. from an admin action) if that lag ever
+  // matters; EDR's own business registration changes rarely enough that this is a generous
+  // ceiling, not a real one.
+  private static readonly REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000;
+  /** Bounded locally since `ETradeService` itself sets none — see the class comment. */
+  private static readonly REFRESH_TIMEOUT_MS = 10_000;
+
+  constructor(
+    private readonly etrade: ETradeService,
+    private readonly config: ConfigService,
+  ) {}
+
+  onModuleInit(): void {
+    void this.refresh();
+    const timer = setInterval(() => void this.refresh(), EimsSellerCacheService.REFRESH_INTERVAL_MS);
+    timer.unref?.();
+  }
+
+  /**
+   * Static config wins whenever it's non-blank — that's the value already confirmed against MoR.
+   * e-Trade fills a field only when the static one is empty. Synchronous, no I/O: safe to call on
+   * every registration.
+   */
+  getSellerDetails(cfg: EimsConfig): EimsSellerDetails {
+    const fallback = buildEimsSeller(cfg);
+    const e = this.cached;
+    return {
+      ...fallback,
+      LegalName: has(fallback.LegalName) ? fallback.LegalName : (e?.LegalName ?? fallback.LegalName),
+      Phone: has(fallback.Phone) ? fallback.Phone : (e?.Phone ?? fallback.Phone),
+      Region: has(fallback.Region) ? fallback.Region : (e?.Region ?? fallback.Region),
+      Wereda: has(fallback.Wereda) ? fallback.Wereda : (e?.Wereda ?? fallback.Wereda),
+      City: has(fallback.City) ? fallback.City : (e?.City ?? fallback.City),
+    };
+  }
+
+  /** Reload the cache. Concurrency-safe (see class comment); public so a caller can force one. */
+  async refresh(): Promise<void> {
+    if (this.refreshing) return this.refreshing;
+    this.refreshing = this.doRefresh().finally(() => {
+      this.refreshing = null;
+    });
+    return this.refreshing;
+  }
+
+  private async doRefresh(): Promise<void> {
+    try {
+      const cfg = this.config.get<EimsConfig>("eims")!;
+      const { companyInfo, businessInfo } = await this.withTimeout(
+        this.etrade.resolveCompanyData(cfg.tin),
+        EimsSellerCacheService.REFRESH_TIMEOUT_MS,
+      );
+      if (!businessInfo) return; // no licence on file yet — keep the previous snapshot
+      const data = this.etrade.extractRegistrationData(businessInfo, companyInfo);
+      const codes = cfg.invoice;
+      this.cached = {
+        LegalName: data.companyName || undefined,
+        Phone: data.mobilePhone || data.regularPhone || undefined,
+        // e-Trade returns region/zone/woreda as names ("Addis Ababa", "Bole") — resolved via the
+        // same buyer code maps, since the geography is objective, not buyer-specific, despite the
+        // env var's "BUYER_" prefix. Never throws: an unmapped name just leaves that field to
+        // getSellerDetails' static-config fallback.
+        Region: resolveOptionalCode(data.region, codes.buyerRegionCodes),
+        Wereda: resolveOptionalCode(data.woreda, codes.buyerWeredaCodes),
+        City: resolveOptionalCode(data.zone, codes.buyerCityCodes),
+      };
+    } catch (err) {
+      this.logger.warn(
+        `EIMS seller e-Trade refresh failed, keeping previous snapshot: ${(err as Error).message}`,
+      );
+    }
+  }
+
+  /**
+   * `ETradeService` sets no request timeout of its own, so one is enforced here. Note this only
+   * stops *waiting* on the request — nothing cancels the underlying HTTP call (no
+   * `AbortController` wired into `ETradeService`), so a timed-out request may still complete in
+   * the background; its result is simply never read.
+   */
+  private withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`e-Trade lookup timed out after ${ms}ms`)), ms);
+      promise.then(
+        (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        (err) => {
+          clearTimeout(timer);
+          reject(err);
+        },
+      );
+    });
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/eims/eims.module.ts b/apps/edr-freight-api/src/modules/eims/eims.module.ts
index 0ee22ec88..5d55a7ee8 100644
--- a/apps/edr-freight-api/src/modules/eims/eims.module.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims.module.ts
@@ -4,6 +4,7 @@ import { TypeOrmModule } from "@nestjs/typeorm";
 
 import { Invoice } from "../billing/entities/invoice.entity";
 import { DocumentsModule } from "../billing/documents/documents.module";
+import { CompaniesModule } from "../companies/companies.module";
 import { NotificationInboxModule } from "../notification-inbox/notification-inbox.module";
 import { NotificationsModule } from "../notifications/notifications.module";
 import { EimsAuthService } from "./eims-auth.service";
@@ -14,6 +15,7 @@ import { EimsCredentialsProvider } from "./eims-credentials.provider";
 import { EimsInvoiceController } from "./eims-invoice.controller";
 import { EimsInvoiceRegistrationService } from "./eims-invoice-registration.service";
 import { EimsReceiptService } from "./eims-receipt.service";
+import { EimsSellerCacheService } from "./eims-seller-cache.service";
 import { EimsSignerService } from "./eims-signer.service";
 import { EimsReceipt } from "./entities/eims-receipt.entity";
 import { EimsSystemState } from "./entities/eims-system-state.entity";
@@ -33,6 +35,10 @@ import { EimsSystemState } from "./entities/eims-system-state.entity";
     // For EimsReceiptService.document() — the shared sealed invoice/receipt PDF layout. No domain
     // deps of its own (StampSettingsService/LogoSettingsService are both @Global), so no cycle.
     DocumentsModule,
+    // For EimsSellerCacheService's ETradeService — CompaniesModule has a forwardRef cycle with
+    // ShippingLineCompaniesModule -> BillingModule, but nothing in that chain imports EimsModule,
+    // so this stays a plain one-directional import, not a new cycle.
+    CompaniesModule,
   ],
   controllers: [EimsInvoiceController],
   providers: [
@@ -44,6 +50,7 @@ import { EimsSystemState } from "./entities/eims-system-state.entity";
     EimsAutoSubmitService,
     EimsCancellationService,
     EimsReceiptService,
+    EimsSellerCacheService,
   ],
   exports: [
     EimsAuthService,

From 339996d27fb1fa116e9fd23d806b2cace672f807 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 17 Aug 2026 07:49:12 +0000
Subject: [PATCH 125/174] docs

---
 CLAUDE.md     | 388 +++++++++++++++++++++++++++++++++++++++++---------
 CLAUDE_NEW.md | 313 ----------------------------------------
 docs/MAP.md   |  96 +++++++++++++
 3 files changed, 420 insertions(+), 377 deletions(-)
 delete mode 100644 CLAUDE_NEW.md
 create mode 100644 docs/MAP.md

diff --git a/CLAUDE.md b/CLAUDE.md
index b90d3b1dd..a20fbaee7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,102 +1,362 @@
 # EDR Platform — Developer Guide
 
+> This file is the contract. If something here contradicts the code, the code is the
+> truth and this file is a bug — fix it in the same PR.
+
+**Looking for where something lives? Read [`docs/MAP.md`](docs/MAP.md) first.** It routes
+you to the right module or page without a repo-wide grep.
+
 ## Overview
 
-Monorepo for the Ethio Djibouti Railway (EDR) digital platform. Contains the Freight Management and Passenger Management applications, plus shared types, NestJS utilities, and React component libraries.
+Monorepo for the Ethio Djibouti Railway (EDR) digital platform. Contains the Freight
+Management and Passenger Management applications, a payment microservice, plus shared
+types, NestJS utilities, and React component libraries.
+
+The freight domain is the largest and most active area. Its core flow is:
+**booking → receive to warehouse → store → load onto train → dispatch → arrive → unload
+→ customer truck (self-haul) or EDR last mile → handover → exit paper → delivered.**
+Fees (storage, demurrage, double handling, truck detention) and allocation rules
+(warehouse/yard/zone) hang off the warehouse stage.
 
 ## Apps
 
-| App                            | Package name                | Purpose                                            | Port |
-| ------------------------------ | --------------------------- | -------------------------------------------------- | ---- |
-| `edr-freight-api`              | `@edr/freight-api`          | NestJS API for freight management                  | 3001 |
-| `edr-freight-web/portal`       | `@edr/freight-portal`       | React frontend for freight customer/portal users   | 5173 |
-| `edr-freight-web/backoffice`   | `@edr/freight-backoffice`   | React frontend for freight backoffice employees    | 5183 |
-| `edr-passenger-api`            | `@edr/passenger-api`        | NestJS API for passenger management                | 3002 |
-| `edr-payment-api`              | `@edr/payment-api`          | NestJS payment microservice (intents, webhooks)    | 3003 |
-| `edr-passenger-web/portal`     | `@edr/passenger-portal`     | React frontend for passenger customer/portal users | 5174 |
-| `edr-passenger-web/backoffice` | `@edr/passenger-backoffice` | React frontend for passenger backoffice employees  | 5184 |
+The two domains are **not built the same way**. Check which stack you are in before
+copying a pattern across:
 
-`edr-freight-web` and `edr-passenger-web` are grouping folders, not workspace packages. Each holds a `portal/` and `backoffice/` sub-app, both of which are independent pnpm workspace packages (declared in `pnpm-workspace.yaml`). The existing `pnpm dev:freight` / `pnpm dev:passenger` turbo filters (`@edr/freight-*` / `@edr/passenger-*`) cover all four web apps + their APIs.
+| App                            | Package name                | Stack                  | Default port |
+| ------------------------------ | --------------------------- | ---------------------- | ------------ |
+| `edr-freight-api`              | `@edr/freight-api`          | NestJS + **TypeORM**   | 3001 |
+| `edr-freight-web/portal`       | `@edr/freight-portal`       | React + **Vite**       | 5273 |
+| `edr-freight-web/backoffice`   | `@edr/freight-backoffice`   | React + **Vite**       | 5283 |
+| `edr-passenger-api`            | `@edr/passenger-api`        | NestJS + **Prisma**    | 4000 |
+| `edr-passenger-web/portal`     | `@edr/passenger-portal`     | **Next.js**            | 5174 |
+| `edr-passenger-web/backoffice` | `@edr/passenger-backoffice` | **Next.js**            | 5184 |
+| `edr-payment-api`              | `@edr/payment-api`          | NestJS + **TypeORM**   | 3003 |
+
+Those are the **fallbacks compiled into the code**, not what you will be running. Every
+port is overridden by `PORT` in the app's `.env` / `.env.development`; the freight vite
+apps read it in `vite.config.ts` (`Number(env.PORT) || 5273`). This machine is shared by
+the whole team and the low ports are contested — see the workspace root `CLAUDE.md` and
+`./wt ports` for who currently holds what.
+
+`edr-freight-web` and `edr-passenger-web` are grouping folders, not workspace packages.
+Each holds a `portal/` and `backoffice/` sub-app, both independent pnpm workspace
+packages (see `pnpm-workspace.yaml`).
+
+`apps/edr-landing/` exists on disk but has **no `package.json`** — it is not a workspace
+package and is not built, linted, or type-checked. Leave it alone unless asked.
+
+`apps/edr-gps-tracker/` is a separate service with its own `.env.example`.
 
 ## Packages
 
-| Package                | Purpose                                                                            |
-| ---------------------- | ---------------------------------------------------------------------------------- |
-| `@edr/types`           | Shared TypeScript interfaces and enums                                             |
-| `@edr/api-common`      | Shared NestJS decorators, filters, interceptors, pipes, BaseEntity, BaseRepository |
-| `@edr/iam-seed`        | IAM baseline seeder for the apps sharing the `iam` schema (freight + passenger)     |
-| `@edr/ui-common`       | Shared React components and theme                                                  |
-| `@edr/eslint-config`   | Shared ESLint configurations (base/nestjs/react)                                   |
-| `@edr/tsconfig`        | Shared TypeScript configurations                                                   |
-| `@edr/prettier-config` | Shared Prettier configuration                                                      |
+| Package                 | Location                      | Purpose                                                       |
+| ----------------------- | ----------------------------- | ------------------------------------------------------------- |
+| `@edr/types`            | `packages/types`              | Shared TypeScript interfaces and enums                        |
+| `@edr/api-common`       | `packages/api-common`         | NestJS decorators, filters, interceptors, pipes, BaseEntity, BaseRepository |
+| `@edr/ui-common`        | `packages/ui-common`          | Shared React components and theme                             |
+| `@edr/iam-seed`         | `packages/iam-seed`           | IAM baseline seeder for apps sharing the `iam` schema         |
+| `@edr/payment-providers`| `packages/payment-providers`  | Payment gateway integrations                                  |
+| `@edr/eslint-config`    | `packages/config/eslint-config`   | Shared ESLint configs (base/nestjs/react)                 |
+| `@edr/tsconfig`         | `packages/config/tsconfig`        | Shared TypeScript configs                                 |
+| `@edr/prettier-config`  | `packages/config/prettier-config` | Shared Prettier config                                    |
+
+The three `config/*` packages are nested one level deeper than the rest — `packages/config`
+itself is not a package.
+
+**`@edr/types` is consumed as its built `dist/`** (`main: ./dist/index.js`). Editing a
+type in `packages/types/src` changes nothing for consumers until you rebuild:
+
+```bash
+pnpm turbo build --filter=@edr/types
+```
+
+If a type-check fails on a field you just added to `@edr/types`, this is why.
 
 ## Commands
 
-| Command              | Description                        |
-| -------------------- | ---------------------------------- |
-| `pnpm install`       | Install all workspace dependencies |
-| `pnpm dev`           | Run every app in dev mode          |
-| `pnpm dev:freight`   | Run only freight API + web         |
-| `pnpm dev:passenger` | Run only passenger API + web       |
-| `pnpm build`         | Build every package and app        |
-| `pnpm test`          | Run all tests                      |
-| `pnpm lint`          | Lint everything                    |
-| `pnpm type-check`    | Type-check every package           |
-| `pnpm format`        | Format all files with Prettier     |
+| Command                       | Description                              |
+| ----------------------------- | ---------------------------------------- |
+| `pnpm install`                | Install all workspace dependencies        |
+| `pnpm dev`                    | Run every app in dev mode                 |
+| `pnpm dev:freight`            | Freight API + portal + backoffice         |
+| `pnpm dev:freight:api`        | Freight API only                          |
+| `pnpm dev:freight:portal`     | Freight portal only                       |
+| `pnpm dev:freight:backoffice` | Freight backoffice only                   |
+| `pnpm dev:passenger`          | Passenger API + web                       |
+| `pnpm dev:payment`            | Payment API                               |
+| `pnpm build`                  | Build every package and app               |
+| `pnpm test`                   | Run all tests (turbo)                     |
+| `pnpm type-check`             | Type-check every package                  |
+| `pnpm format`                 | Format all files with Prettier            |
+| `pnpm lint`                   | **Does not work** — see below             |
 
-## Standards
+**`pnpm lint` fails.** `eslint` is not installed anywhere in the workspace, so
+`turbo run lint` dies with `eslint: not found` even though every package declares a
+`lint` script and `@edr/eslint-config` exists. Until someone adds the dependency,
+tsc's `noUnusedLocals` is the only working unused-code check. Do not claim a change is
+"lint clean".
 
-- **TypeScript strict mode** is enabled in every package and app.
-- **pnpm** is the only supported package manager — never run `npm install` or `yarn`.
-- **Conventional commits** are enforced via commitlint on every commit.
-- **NestJS modules** follow the 4-layer pattern: `module → controller → service → repository` (entities and DTOs live alongside).
+`pnpm format` uses bare `prettier`, which ignores `@edr/prettier-config` — it is wired to
+nothing. On the single-quoted passenger apps it will re-quote the whole file. Pass
+`--config` explicitly there.
+
+Prefer targeted turbo filters over whole-repo runs — they are minutes faster:
+
+```bash
+pnpm turbo type-check --filter=@edr/freight-api --filter=@edr/freight-backoffice
+```
+
+`apps/edr-freight-api` also carries many `seed:*` scripts (demo bookings, wagons, trains,
+gate-pass scenarios). Read the script before running one; several write real rows.
+
+## Environment & database
+
+- Postgres is **external**. There is no postgres service in `docker-compose.yaml`, and
+  no port `5433`/`5434` is published anywhere in the repo.
+- Freight API connection comes from `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`,
+  `DB_NAME` (defaults: `localhost:5433`, `edr_freight`). Development points these at a
+  remote database.
+- The connection sits behind a **connection pooler**. Do **not** pass
+  `extra.options: '-c search_path=…'` — the pooler rejects it with
+  `08P01 unsupported startup parameter in options: search_path`. `search_path` is applied
+  per-connection in a pool `connect` handler instead. See
+  `apps/edr-freight-api/src/config/database.config.ts` before touching connection options.
+- Each app owns its own database. **No cross-database joins**; cross-domain data flows
+  through API calls or message queues.
+- IAM tables live in their own `iam` schema (`iam.users`, `iam.user_credentials`),
+  freight tables in `freight`.
+- `psql` is not installed on the dev machine. To query the database, use the `edr-db`
+  skill (below) or write a short Node script using `pg` and run it from
+  `apps/edr-freight-api`, where `pg` resolves.
+
+## Hard rules
+
+These are non-negotiable. Everything else is a strong default.
+
+- **pnpm only.** Never run `npm install` or `yarn`.
+- **TypeScript strict mode** is on in every package and app. Do not weaken it, and do not
+  reach for `any` to make an error go away.
+- **Never `synchronize: true`.** Not in production, not anywhere. It is currently `false`
+  in every config and it has already corrupted this database twice (see *Migrations*).
+  All schema changes go through migrations.
 - **All entities** use UUID primary keys (`@PrimaryGeneratedColumn('uuid')`).
-- **All entities** have `createdAt`, `updatedAt`, `deletedAt` (soft delete) via `@edr/api-common`'s `BaseEntity`.
-- **All columns** use `snake_case` in the database (`@Column({ name: 'snake_case' })`); TypeScript properties use `camelCase`.
-- **Never use `synchronize: true`** in production database config. All schema changes go through TypeORM migrations.
-- **ESLint + Prettier** run on pre-commit via Husky + lint-staged.
-- **Services** never inject TypeORM `Repository<T>` directly — they inject the custom repository class.
-- **Controllers** never contain business logic.
+- **All entities** extend `BaseEntity` from `@edr/api-common` — `createdAt`, `updatedAt`,
+  `deletedAt` (soft delete).
+- **All columns** are `snake_case` in the database (`@Column({ name: 'snake_case' })`);
+  TypeScript properties are `camelCase`.
+- **Controllers contain no business logic.** They validate, delegate, and shape the response.
+- **Conventional commits.** `fix(warehouses): …`, `feat(bookings): …`.
+- **Do not commit or push unless asked.** Propose the change; let the human decide when it lands.
+- **Do not break working behaviour to add new behaviour.** When a fix is risky, say so and
+  offer the safe version.
 
-## Auth
+## Architecture
 
-Authentication is handled by an external package (`@edr/iamui-common` or equivalent) that will be integrated later. **Do not** implement any auth, login, logout, JWT verification, password hashing, or user management code in this repo.
+### NestJS module shape
 
-When auth integration is needed, use placeholder TODO comments:
+`module → controller → service → repository`, with `entities/` and `dto/` alongside.
+`docs/MAP.md` lists the ~60 freight modules grouped by domain.
 
-- `// @UseGuards(JwtAuthGuard) — TODO: integrate @edr/auth`
-- `// TODO: integrate @edr/auth — replace stub @CurrentUser with real one`
+### Data access — the real model
 
-The `@CurrentUser`, `@Roles`, and `@Public` decorators in `@edr/api-common` are bare metadata setters with no guard wiring — they exist so controllers can be annotated correctly without depending on auth infrastructure yet.
+There are two sanctioned ways to read and write, and you must pick the right one:
 
-## Port Assignments
+1. **Entity CRUD → the custom repository class.** Extends `BaseRepository<Entity>` from
+   `@edr/api-common`. Services inject the repository class, never `Repository<T>` directly.
+2. **Read projections, queue endpoints, cross-table reports → raw SQL** via
+   `this.dataSource.query(...)` or `manager.query(...)` inside a transaction.
 
-- `edr-freight-api`: 3001
-- `edr-freight-web/portal`: 5173
-- `edr-freight-web/backoffice`: 5183
-- `edr-passenger-api`: 3002
-- `edr-payment-api`: 3003
-- `edr-passenger-web/portal`: 5174
-- `edr-passenger-web/backoffice`: 5184
+Raw SQL is normal here, not a smell — the warehouse and scheduling modules are built on it.
+It carries one obligation:
 
-## Database Layout
+> **HARD RULE — validate every raw SQL statement against a real database before you ship it.**
+> A typo'd column name is a runtime 500 that no type-checker will catch. Run it through
+> `EXPLAIN` against the dev database. Column drift is real (see *Migrations*).
 
-- `postgres-freight` (port 5433): database `edr_freight` — freight API only.
-- `postgres-passenger` (port 5434): database `edr_passenger` — passenger API only.
-- `edr_payment` schema — lives in the same Postgres database as the domain system (whatever the passenger `DATABASE_URL` points at) but is owned exclusively by `apps/edr-payment-api`. Dedicated DB user, no cross-schema FKs, domain apps have no grants on it (see `docs/payment-service/`).
-- Each app owns its own DB. No cross-database joins; cross-domain data flows through API calls or message queues.
+Writes inside a transaction use `manager.getRepository(Entity)`, not the injected repository,
+so they join the caller's transaction.
+
+**Never do slow I/O inside a database transaction.** Queue the work and fan it out after
+commit. An SMS awaited inside a transaction once held capacity locks open for the whole
+gateway timeout. Any outbound HTTP call must set an explicit `timeout` — axios defaults to
+no timeout and will wait forever.
+
+### Migrations
+
+Migrations are the most dangerous surface in this repo. Two production-grade incidents have
+already come from it. **Freight and payment use TypeORM migrations; passenger uses Prisma**
+(`apps/edr-passenger-api/prisma/migrations`) — the rules below are about the TypeORM side.
+
+- `migrationsRun: false` — **migrations do NOT run on API boot.** They run as a separate
+  one-shot step, via the Dockerfile's `migration` build target (`docker build --target
+  migration`), with `migrationsTransactionMode: 'each'`.
+  - CI: `.github/workflows/deploy.yml` builds the `migration` image and runs it
+    (`docker run --rm --env-file ...`) *before* building/deploying the app image.
+  - e2e: `docker-compose.e2e.yaml`'s `freight-migration-e2e` service runs once and
+    `freight-api-e2e` depends on it (`condition: service_completed_successfully`).
+  - Local dev (`docker-compose.yaml`) has no equivalent migration service yet — run
+    migrations yourself before `docker compose up freight-api`, e.g.
+    `docker build --target migration -f apps/edr-freight-api/Dockerfile -t freight-migration .`
+    then `docker run --rm --env-file apps/edr-freight-api/.env freight-migration`. Don't
+    use `pnpm run migrate` for this — it runs via `ts-node`, which never writes compiled
+    output to `dist/`, and the freight migrations glob only matches `dist/migrations/*.js`.
+    It silently applies zero freight migrations while exiting 0.
+- Consequences you must design for:
+  - A watch-mode hot reload does **not** re-run migrations. If you add a column that new
+    code reads, apply it to the dev database yourself (idempotently) or fully restart.
+  - `apps/edr-freight-api/src/config/database.config.ts`'s `iamEntities` array is a
+    hand-maintained list of `@tria-plc/iamapi-common` entity classes. The live app never
+    notices when it's stale (`autoLoadEntities: true` papers over gaps via IAM's own
+    `forFeature()` registrations), but the standalone migration `DataSource`
+    (`data-source.ts`, no `autoLoadEntities`) does not have that fallback — a missing
+    entity throws `Entity metadata for X#y was not found` at `initialize()`, before a
+    single migration runs. **Every `@tria-plc/iamapi-common` version bump is a candidate
+    for this to break again** — diff the package's entity classes against `iamEntities`
+    when bumping it.
+- **Give every migration a unique timestamp.** `apps/edr-freight-api/src/migrations` holds
+  39 files, and 8 timestamps are shared by two or more of them. TypeORM orders by timestamp
+  and breaks ties non-deterministically. Check before adding one:
+
+  ```bash
+  ls apps/edr-freight-api/src/migrations | grep -oE '^[0-9]+' | sort | uniq -d
+  ```
+
+  The prefix must be unused *and* higher than the newest recorded row. Note the
+  `freight.migrations` table has far more rows (~309) than this folder has files — most
+  come from `@tria-plc/iamapi-common`'s own migrations, which run from the same data source.
+- **Write idempotent DDL**: `ADD COLUMN IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and
+  backfills guarded by `WHERE col IS NULL`.
+- **Never assume a recorded migration actually applied.** `AddGrnNumberToWarehouseInventory`
+  was recorded in `migrations` while its column was absent — it had been dropped out of band.
+  TypeORM will never re-run a recorded migration, so the fix is a *new repair migration*.
+- **A repair migration's `down()` should be a no-op.** Reverting a repair must not
+  re-introduce the outage it fixed.
+
+### Auth
+
+Auth **is implemented in this repo.** Do not add TODO stubs, and do not write your own.
+
+- `@CurrentUser()` (`@edr/api-common`) is a real `createParamDecorator`, not a metadata stub.
+- Route protection uses `@UseGuards(JwtGuard)` and `@UseGuards(PermissionGuard([...]))`.
+- Freight-domain checks use `hasFreightPermission(user, FREIGHT_PERMS.<area>.<action>)`.
+- Permissions are declared in `apps/edr-freight-api/src/seed/freight-permissions.registry.ts`.
+  Add a permission there before referencing it.
+- Login is freight-api's own `POST /api/auth/login` (SharedAuthModule from
+  `@tria-plc/api-common`). Every login call needs an **`x-client-app` header** —
+  `backoffice` for employees, `portal` for customers. Without it the API 403s with
+  "Missing or unrecognized x-client-app header". Browsers send it; curl must add it.
+- IAM has its own migrations, run ahead of freight migrations from the same data source, and
+  its own CLI scripts (`iam:migration:run`, `iam:seed:run`).
+
+Ownership checks are separate from permission checks. A staff user passes
+`hasFreightPermission`; a customer must additionally pass an ownership assertion such as
+`assertCustomerCanAccessBooking`. Do not drop the ownership check because the permission check passed.
+
+## Frontend conventions
+
+- The **freight** web apps use **Mantine v9** (`^9.3.0`). Its APIs differ from v6/v7 —
+  check the installed version before copying a snippet.
+- `@edr/ui-common` holds shared components and theme; it is imported in ~94 files across the
+  freight web apps. Prefer it over re-implementing a component.
+- **Blob downloads need the async error decoder.** A request with `responseType: 'blob'`
+  delivers the JSON error body as a `Blob`, so the synchronous `extractErrorMessage` finds no
+  `.message` and degrades to `"Request failed with status code 400"`. Use
+  `await extractDownloadErrorMessage(error)` in every PDF/blob catch block. Mutation catches
+  keep the synchronous version — their bodies are already parsed JSON.
+- Server-side guards must be reflected in the UI. If the API will reject the action, the
+  button should be disabled, hidden, or explain the blocker — not fire and surface a 400.
+- Prefer disabling a control with a visible reason over silently hiding it.
+
+## Notifications
+
+In-app notifications resolve recipients from the company's **linked portal users**. If a
+company has none, `notify()` logs `0 recipients — skipped` and stores nothing, with no error.
+SMS and email still send, because they address the company's phone and email directly. Check
+this before debugging a "missing notification".
+
+## PDF generation
+
+Chromium is not installed in every environment. PDF paths must fall back to the hand-rolled
+generators (`styled-pdf.util.ts`, `buildFallbackPdf`, `buildTabularFallbackPdf`) rather than
+assume a headless browser exists.
 
 ## Adding a new module to a NestJS app
 
-1. Create `modules/<feature>/` with `entities/`, `dto/`, and the four `<feature>.{module,controller,service,repository}.ts` files.
+1. Create `modules/<feature>/` with `entities/`, `dto/`, and the four
+   `<feature>.{module,controller,service,repository}.ts` files.
 2. The entity extends `BaseEntity` from `@edr/api-common`.
 3. The repository extends `BaseRepository<Entity>` from `@edr/api-common`.
 4. The service injects the repository class (not `Repository<T>` directly).
-5. The controller uses `@ApiTags()` + `@ApiOperation()` for Swagger.
+5. The controller uses `@ApiTags()` + `@ApiOperation()` for Swagger, and guards the route.
 6. Register the module in the app's `app.module.ts`.
 
 ## Adding a new shared component to `@edr/ui-common`
 
 1. Create `src/components/<Name>/<Name>.tsx` and `src/components/<Name>/index.ts`.
 2. Export from `src/index.ts`.
-3. Component is a functional component with a `ComponentNameProps` interface (named-exported alongside the default).
+3. Component is a functional component with a `ComponentNameProps` interface
+   (named-exported alongside the default).
+
+## Definition of done
+
+A change is done when **all** of these hold. State explicitly which you ran.
+
+1. **It type-checks.** `pnpm turbo type-check --filter=<each touched package>` passes.
+   If you edited `packages/types`, you ran `pnpm turbo build --filter=@edr/types` first.
+2. **Raw SQL is verified.** Every new or edited SQL statement ran under `EXPLAIN` against the
+   dev database without error.
+3. **Migrations are safe.** Unique timestamp, idempotent DDL, and — if the migration adds
+   something the new code reads — applied to the dev database, since watch mode will not run it.
+4. **No new test failures.** `pnpm test` for `@edr/freight-api` has been red on `dev`, so a
+   fully green suite is not the bar — but confirm that for yourself rather than assuming it,
+   then run the specs covering what you touched and confirm you introduced no new failure.
+5. **Formatting is clean** for the files you touched. Git hooks do **not** run automatically
+   (see below), and `pnpm lint` does not work at all, so `noUnusedLocals` from the
+   type-check is your only unused-code signal.
+6. **The behaviour was actually observed**, not merely compiled — you drove the flow, hit the
+   endpoint, or ran the query. If you could not, say so plainly.
+7. **Report honestly.** If a check was skipped, tests failed, or a fix is unverified, say it in
+   the summary. Never describe unverified work as done.
+
+### Hooks do not run
+
+`commitlint.config.js` and a `lint-staged` config both exist, and husky's shims are installed
+at `.husky/_/`. But there are **no user hook scripts** (`.husky/pre-commit`,
+`.husky/commit-msg`), so husky's shim exits 0 and **neither lint-staged nor commitlint ever
+fire.** Nothing validates your commit message or formats your staged files. Run the checks by
+hand; do not assume the hook caught it.
+
+## Known traps
+
+| Trap | What happens | What to do |
+| --- | --- | --- |
+| Schema drift | A recorded migration's column is missing; queries and inserts 500 | Write a new repair migration; never edit the recorded one |
+| Duplicate migration timestamps | Non-deterministic ordering; a migration can be skipped | Pick a fresh, higher timestamp |
+| `@edr/types` not rebuilt | Consumers can't see your new field | `pnpm turbo build --filter=@edr/types` |
+| Slow I/O in a transaction | Locks held for the gateway timeout | Queue it; fan out after commit; always set an HTTP timeout |
+| Blob error bodies | Real 400 message replaced by "Request failed with status code 400" | `await extractDownloadErrorMessage(error)` |
+| Company with no portal user | In-app notification silently vanishes | Check portal users before debugging |
+| Watch-mode reload | New code, old schema → 500 | Apply the migration to the dev DB or restart fully |
+| Login 403 from curl | "Missing or unrecognized x-client-app header" | Send `x-client-app: backoffice` or `portal` |
+| Copying a passenger pattern into freight | Passenger is Prisma + Next.js, freight is TypeORM + Vite | Check which stack you are in first |
+
+## Project skills
+
+Reusable workflows live in `.claude/skills/`. Use them instead of re-deriving the steps:
+
+| Skill | Use for |
+| --- | --- |
+| `edr-db` | Query / `EXPLAIN`-validate / inspect the remote dev DB (`node .claude/skills/edr-db/query.cjs …`). psql is not installed — this is the sanctioned path. Also carries the 400/500 diagnosis loop. |
+| `verify` | The definition-of-done runner: targeted type-check, `@edr/types` rebuild, SQL validation, migration checklist, honest test bar. Run before calling anything finished. |
+| `standup` | "What did I do today / this week" reports for tickets, grounded in `git log` — including the check that commit subjects match their contents. |
+
+## Working style
+
+- **Verify before asserting.** Read the code or query the database. Do not infer behaviour
+  from a filename.
+- **Investigate, then propose.** For anything risky or wide-reaching, present the plan and the
+  trade-off before changing files.
+- **Small, reviewable commits**, one logical change each, conventional message.
+- **Branch from `dev`; PRs target `dev`.**
+- When a finding turns out to be wrong, say so and retract it. A rejected finding is a result.
diff --git a/CLAUDE_NEW.md b/CLAUDE_NEW.md
deleted file mode 100644
index a99f64d0a..000000000
--- a/CLAUDE_NEW.md
+++ /dev/null
@@ -1,313 +0,0 @@
-# EDR Platform — Developer Guide
-
-> This file is the contract. If something here contradicts the code, the code is the
-> truth and this file is a bug — fix it in the same PR.
-
-## Overview
-
-Monorepo for the Ethio Djibouti Railway (EDR) digital platform. Contains the Freight
-Management and Passenger Management applications, a payment microservice, plus shared
-types, NestJS utilities, and React component libraries.
-
-The freight domain is the largest and most active area. Its core flow is:
-**booking → receive to warehouse → store → load onto train → dispatch → arrive → unload
-→ customer truck (self-haul) or EDR last mile → handover → exit paper → delivered.**
-Fees (storage, demurrage, double handling, truck detention) and allocation rules
-(warehouse/yard/zone) hang off the warehouse stage.
-
-## Apps
-
-| App                            | Package name                | Purpose                                            | Default port |
-| ------------------------------ | --------------------------- | -------------------------------------------------- | ------------ |
-| `edr-freight-api`              | `@edr/freight-api`          | NestJS API for freight management                  | 3001 |
-| `edr-freight-web/portal`       | `@edr/freight-portal`       | React frontend for freight customer/portal users   | 5173 |
-| `edr-freight-web/backoffice`   | `@edr/freight-backoffice`   | React frontend for freight backoffice employees    | 5183 |
-| `edr-passenger-api`            | `@edr/passenger-api`        | NestJS API for passenger management                | 3002 |
-| `edr-payment-api`              | `@edr/payment-api`          | NestJS payment microservice (intents, webhooks)    | 3003 |
-| `edr-passenger-web/portal`     | `@edr/passenger-portal`     | React frontend for passenger customer/portal users | 5174 |
-| `edr-passenger-web/backoffice` | `@edr/passenger-backoffice` | React frontend for passenger backoffice employees  | 5184 |
-
-`edr-freight-web` and `edr-passenger-web` are grouping folders, not workspace packages.
-Each holds a `portal/` and `backoffice/` sub-app, both independent pnpm workspace
-packages (see `pnpm-workspace.yaml`).
-
-`apps/edr-landing/` exists on disk but has **no `package.json`** — it is not a workspace
-package and is not built, linted, or type-checked. Leave it alone unless asked.
-
-## Packages
-
-| Package                | Purpose                                                                            |
-| ---------------------- | ---------------------------------------------------------------------------------- |
-| `@edr/types`           | Shared TypeScript interfaces and enums                                             |
-| `@edr/api-common`      | Shared NestJS decorators, filters, interceptors, pipes, BaseEntity, BaseRepository |
-| `@edr/ui-common`       | Shared React components and theme                                                  |
-| `@edr/eslint-config`   | Shared ESLint configurations (base/nestjs/react)                                   |
-| `@edr/tsconfig`        | Shared TypeScript configurations                                                   |
-| `@edr/prettier-config` | Shared Prettier configuration                                                      |
-
-**`@edr/types` is consumed as its built `dist/`** (`main: ./dist/index.js`). Editing a
-type in `packages/types/src` changes nothing for consumers until you rebuild:
-
-```bash
-pnpm turbo build --filter=@edr/types
-```
-
-If a type-check fails on a field you just added to `@edr/types`, this is why.
-
-## Commands
-
-| Command                     | Description                              |
-| --------------------------- | ---------------------------------------- |
-| `pnpm install`              | Install all workspace dependencies        |
-| `pnpm dev`                  | Run every app in dev mode                 |
-| `pnpm dev:freight`          | Freight API + portal + backoffice         |
-| `pnpm dev:freight:api`      | Freight API only                          |
-| `pnpm dev:freight:portal`   | Freight portal only                       |
-| `pnpm dev:freight:backoffice` | Freight backoffice only                 |
-| `pnpm dev:passenger`        | Passenger API + web                       |
-| `pnpm dev:payment`          | Payment API                               |
-| `pnpm build`                | Build every package and app               |
-| `pnpm test`                 | Run all tests (turbo)                     |
-| `pnpm lint`                 | Lint everything                           |
-| `pnpm type-check`           | Type-check every package                  |
-| `pnpm format`               | Format all files with Prettier            |
-
-Prefer targeted turbo filters over whole-repo runs — they are minutes faster:
-
-```bash
-pnpm turbo type-check --filter=@edr/freight-api --filter=@edr/freight-backoffice
-```
-
-`apps/edr-freight-api` also carries many `seed:*` scripts (demo bookings, wagons, trains,
-gate-pass scenarios). Read the script before running one; several write real rows.
-
-## Environment & database
-
-- Postgres is **external**. There is no postgres service in `docker-compose.yaml`, and
-  no port `5433`/`5434` is published anywhere in the repo.
-- Freight API connection comes from `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`,
-  `DB_NAME` (defaults: `localhost:5433`, `edr_freight`). Development points these at a
-  remote database.
-- The connection sits behind a **connection pooler**. Do **not** pass
-  `extra.options: '-c search_path=…'` — the pooler rejects it with
-  `08P01 unsupported startup parameter in options: search_path`. `search_path` is applied
-  per-connection in a pool `connect` handler instead. See
-  `apps/edr-freight-api/src/config/database.config.ts` before touching connection options.
-- Each app owns its own database. **No cross-database joins**; cross-domain data flows
-  through API calls or message queues.
-- `psql` is not installed on the dev machine. To query the database, write a short Node
-  script using the `pg` client and run it from `apps/edr-freight-api` (where `pg` resolves).
-
-## Hard rules
-
-These are non-negotiable. Everything else is a strong default.
-
-- **pnpm only.** Never run `npm install` or `yarn`.
-- **TypeScript strict mode** is on in every package and app. Do not weaken it, and do not
-  reach for `any` to make an error go away.
-- **Never `synchronize: true`.** Not in production, not anywhere. It is currently `false`
-  in every config and it has already corrupted this database twice (see *Migrations*).
-  All schema changes go through TypeORM migrations.
-- **All entities** use UUID primary keys (`@PrimaryGeneratedColumn('uuid')`).
-- **All entities** extend `BaseEntity` from `@edr/api-common` — `createdAt`, `updatedAt`,
-  `deletedAt` (soft delete).
-- **All columns** are `snake_case` in the database (`@Column({ name: 'snake_case' })`);
-  TypeScript properties are `camelCase`.
-- **Controllers contain no business logic.** They validate, delegate, and shape the response.
-- **Conventional commits.** `fix(warehouses): …`, `feat(bookings): …`.
-- **Do not commit or push unless asked.** Propose the change; let the human decide when it lands.
-- **Do not break working behaviour to add new behaviour.** When a fix is risky, say so and
-  offer the safe version.
-
-## Architecture
-
-### NestJS module shape
-
-`module → controller → service → repository`, with `entities/` and `dto/` alongside.
-
-### Data access — the real model
-
-There are two sanctioned ways to read and write, and you must pick the right one:
-
-1. **Entity CRUD → the custom repository class.** Extends `BaseRepository<Entity>` from
-   `@edr/api-common`. Services inject the repository class, never `Repository<T>` directly.
-2. **Read projections, queue endpoints, cross-table reports → raw SQL** via
-   `this.dataSource.query(...)` or `manager.query(...)` inside a transaction.
-
-Raw SQL is normal here, not a smell — the warehouse and scheduling modules are built on it.
-It carries one obligation:
-
-> **HARD RULE — validate every raw SQL statement against a real database before you ship it.**
-> A typo'd column name is a runtime 500 that no type-checker will catch. Run it through
-> `EXPLAIN` against the dev database. Column drift is real (see *Migrations*).
-
-Writes inside a transaction use `manager.getRepository(Entity)`, not the injected repository,
-so they join the caller's transaction.
-
-**Never do slow I/O inside a database transaction.** Queue the work and fan it out after
-commit. An SMS awaited inside a transaction once held capacity locks open for the whole
-gateway timeout. Any outbound HTTP call must set an explicit `timeout` — axios defaults to
-no timeout and will wait forever.
-
-### Migrations
-
-Migrations are the most dangerous surface in this repo. Two production-grade incidents have
-already come from it.
-
-- `migrationsRun: false` — **migrations do NOT run on API boot.** They run as a separate
-  one-shot step, via the Dockerfile's `migration` build target (`docker build --target
-  migration`), with `migrationsTransactionMode: 'each'`.
-  - CI: `.github/workflows/deploy.yml` builds the `migration` image and runs it
-    (`docker run --rm --env-file ...`) *before* building/deploying the app image.
-  - e2e: `docker-compose.e2e.yaml`'s `freight-migration-e2e` service runs once and
-    `freight-api-e2e` depends on it (`condition: service_completed_successfully`).
-  - Local dev (`docker-compose.yaml`) has no equivalent migration service yet — run
-    migrations yourself before `docker compose up freight-api`, e.g.
-    `docker build --target migration -f apps/edr-freight-api/Dockerfile -t freight-migration .`
-    then `docker run --rm --env-file apps/edr-freight-api/.env freight-migration`. Don't
-    use `pnpm run migrate` for this — it runs via `ts-node`, which never writes compiled
-    output to `dist/`, and the freight migrations glob only matches `dist/migrations/*.js`.
-    It silently applies zero freight migrations while exiting 0.
-- Consequences you must design for:
-  - A watch-mode hot reload does **not** re-run migrations. If you add a column that new
-    code reads, apply it to the dev database yourself (idempotently) or fully restart.
-  - `apps/edr-freight-api/src/config/database.config.ts`'s `iamEntities` array is a
-    hand-maintained list of `@tria-plc/iamapi-common` entity classes. The live app never
-    notices when it's stale (`autoLoadEntities: true` papers over gaps via IAM's own
-    `forFeature()` registrations), but the standalone migration `DataSource`
-    (`data-source.ts`, no `autoLoadEntities`) does not have that fallback — a missing
-    entity throws `Entity metadata for X#y was not found` at `initialize()`, before a
-    single migration runs. **Every `@tria-plc/iamapi-common` version bump is a candidate
-    for this to break again** — diff the package's entity classes against `iamEntities`
-    when bumping it.
-- **Give every migration a unique timestamp.** 34 timestamps are currently shared by two or
-  more migrations. TypeORM orders by timestamp and breaks ties non-deterministically. Before
-  adding one, check the filename prefix is unused *and* higher than the newest recorded row.
-- **Write idempotent DDL**: `ADD COLUMN IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and
-  backfills guarded by `WHERE col IS NULL`.
-- **Never assume a recorded migration actually applied.** `AddGrnNumberToWarehouseInventory`
-  was recorded in `migrations` while its column was absent — it had been dropped out of band.
-  TypeORM will never re-run a recorded migration, so the fix is a *new repair migration*.
-- **A repair migration's `down()` should be a no-op.** Reverting a repair must not
-  re-introduce the outage it fixed.
-
-### Auth
-
-Auth **is implemented in this repo.** Do not add TODO stubs, and do not write your own.
-
-- `@CurrentUser()` (`@edr/api-common`) is a real `createParamDecorator`, not a metadata stub.
-- Route protection uses `@UseGuards(JwtGuard)` and `@UseGuards(PermissionGuard([...]))`.
-- Freight-domain checks use `hasFreightPermission(user, FREIGHT_PERMS.<area>.<action>)`.
-- Permissions are declared in `apps/edr-freight-api/src/seed/freight-permissions.registry.ts`.
-  Add a permission there before referencing it.
-- IAM has its own migrations, run ahead of freight migrations from the same data source, and
-  its own CLI scripts (`iam:migration:run`, `iam:seed:run`).
-
-Ownership checks are separate from permission checks. A staff user passes
-`hasFreightPermission`; a customer must additionally pass an ownership assertion such as
-`assertCustomerCanAccessBooking`. Do not drop the ownership check because the permission check passed.
-
-## Frontend conventions
-
-- The web apps use **Mantine v9**. Its APIs differ from v6/v7 — check the installed version
-  before copying a snippet.
-- `@edr/ui-common` holds shared components and theme; it is imported in ~94 files across the
-  freight web apps. Prefer it over re-implementing a component.
-- **Blob downloads need the async error decoder.** A request with `responseType: 'blob'`
-  delivers the JSON error body as a `Blob`, so the synchronous `extractErrorMessage` finds no
-  `.message` and degrades to `"Request failed with status code 400"`. Use
-  `await extractDownloadErrorMessage(error)` in every PDF/blob catch block. Mutation catches
-  keep the synchronous version — their bodies are already parsed JSON.
-- Server-side guards must be reflected in the UI. If the API will reject the action, the
-  button should be disabled, hidden, or explain the blocker — not fire and surface a 400.
-- Prefer disabling a control with a visible reason over silently hiding it.
-
-## Notifications
-
-In-app notifications resolve recipients from the company's **linked portal users**. If a
-company has none, `notify()` logs `0 recipients — skipped` and stores nothing, with no error.
-SMS and email still send, because they address the company's phone and email directly. Check
-this before debugging a "missing notification".
-
-## PDF generation
-
-Chromium is not installed in every environment. PDF paths must fall back to the hand-rolled
-generators (`styled-pdf.util.ts`, `buildFallbackPdf`, `buildTabularFallbackPdf`) rather than
-assume a headless browser exists.
-
-## Adding a new module to a NestJS app
-
-1. Create `modules/<feature>/` with `entities/`, `dto/`, and the four
-   `<feature>.{module,controller,service,repository}.ts` files.
-2. The entity extends `BaseEntity` from `@edr/api-common`.
-3. The repository extends `BaseRepository<Entity>` from `@edr/api-common`.
-4. The service injects the repository class (not `Repository<T>` directly).
-5. The controller uses `@ApiTags()` + `@ApiOperation()` for Swagger, and guards the route.
-6. Register the module in the app's `app.module.ts`.
-
-## Adding a new shared component to `@edr/ui-common`
-
-1. Create `src/components/<Name>/<Name>.tsx` and `src/components/<Name>/index.ts`.
-2. Export from `src/index.ts`.
-3. Component is a functional component with a `ComponentNameProps` interface
-   (named-exported alongside the default).
-
-## Definition of done
-
-A change is done when **all** of these hold. State explicitly which you ran.
-
-1. **It type-checks.** `pnpm turbo type-check --filter=<each touched package>` passes.
-   If you edited `packages/types`, you ran `pnpm turbo build --filter=@edr/types` first.
-2. **Raw SQL is verified.** Every new or edited SQL statement ran under `EXPLAIN` against the
-   dev database without error.
-3. **Migrations are safe.** Unique timestamp, idempotent DDL, and — if the migration adds
-   something the new code reads — applied to the dev database, since watch mode will not run it.
-4. **No new test failures.** `pnpm test` for `@edr/freight-api` is **currently red on `dev`**,
-   so a fully green suite is not the bar. Run the specs covering what you touched and confirm
-   you introduced no new failure.
-5. **Lint and format are clean** for the files you touched. Git hooks do **not** run these
-   automatically (see below), so run them yourself.
-6. **The behaviour was actually observed**, not merely compiled — you drove the flow, hit the
-   endpoint, or ran the query. If you could not, say so plainly.
-7. **Report honestly.** If a check was skipped, tests failed, or a fix is unverified, say it in
-   the summary. Never describe unverified work as done.
-
-### Hooks do not run
-
-`commitlint.config.js` and a `lint-staged` config both exist, and husky's shims are installed
-at `.husky/_/`. But there are **no user hook scripts** (`.husky/pre-commit`,
-`.husky/commit-msg`), so husky's shim exits 0 and **neither lint-staged nor commitlint ever
-fire.** Nothing validates your commit message or formats your staged files. Run the checks by
-hand; do not assume the hook caught it.
-
-## Known traps
-
-| Trap | What happens | What to do |
-| --- | --- | --- |
-| Schema drift | A recorded migration's column is missing; queries and inserts 500 | Write a new repair migration; never edit the recorded one |
-| Duplicate migration timestamps | Non-deterministic ordering; a migration can be skipped | Pick a fresh, higher timestamp |
-| `@edr/types` not rebuilt | Consumers can't see your new field | `pnpm turbo build --filter=@edr/types` |
-| Slow I/O in a transaction | Locks held for the gateway timeout | Queue it; fan out after commit; always set an HTTP timeout |
-| Blob error bodies | Real 400 message replaced by "Request failed with status code 400" | `await extractDownloadErrorMessage(error)` |
-| Company with no portal user | In-app notification silently vanishes | Check portal users before debugging |
-| Watch-mode reload | New code, old schema → 500 | Apply the migration to the dev DB or restart fully |
-
-## Project skills
-
-Reusable workflows live in `.claude/skills/`. Use them instead of re-deriving the steps:
-
-| Skill | Use for |
-| --- | --- |
-| `edr-db` | Query / `EXPLAIN`-validate / inspect the remote dev DB (`node .claude/skills/edr-db/query.cjs …`). psql is not installed — this is the sanctioned path. Also carries the 400/500 diagnosis loop. |
-| `verify` | The definition-of-done runner: targeted type-check, `@edr/types` rebuild, SQL validation, migration checklist, honest test bar. Run before calling anything finished. |
-| `standup` | "What did I do today / this week" reports for tickets, grounded in `git log` — including the check that commit subjects match their contents. |
-
-## Working style
-
-- **Verify before asserting.** Read the code or query the database. Do not infer behaviour
-  from a filename.
-- **Investigate, then propose.** For anything risky or wide-reaching, present the plan and the
-  trade-off before changing files.
-- **Small, reviewable commits**, one logical change each, conventional message.
-- **Branch from `dev`; PRs target `dev`.**
-- When a finding turns out to be wrong, say so and retract it. A rejected finding is a result.
diff --git a/docs/MAP.md b/docs/MAP.md
new file mode 100644
index 000000000..d6aa76322
--- /dev/null
+++ b/docs/MAP.md
@@ -0,0 +1,96 @@
+# Repo map — start here
+
+Routing table for "where does X live". Read this before a repo-wide grep. Paths are from
+the repo root. The rules and traps are in [`../CLAUDE.md`](../CLAUDE.md); this file only
+answers *where*.
+
+## Pick your stack first
+
+| If you are working on…            | Code lives in                     | Stack                |
+| --------------------------------- | --------------------------------- | -------------------- |
+| Freight API / business logic      | `apps/edr-freight-api/src`        | NestJS + TypeORM     |
+| Freight customer UI               | `apps/edr-freight-web/portal`     | React + Vite + Mantine v9 |
+| Freight staff UI                  | `apps/edr-freight-web/backoffice` | React + Vite + Mantine v9 |
+| Passenger API                     | `apps/edr-passenger-api`          | NestJS + **Prisma**  |
+| Passenger UI                      | `apps/edr-passenger-web/*`        | **Next.js**          |
+| Payments (intents, webhooks)      | `apps/edr-payment-api`            | NestJS + TypeORM     |
+| Gateway integrations              | `packages/payment-providers`      | —                    |
+| A shared type or enum             | `packages/types/src`              | rebuild after editing |
+| A shared React component          | `packages/ui-common/src`          | —                    |
+| A Nest decorator/filter/base class| `packages/api-common/src`         | —                    |
+
+## Freight API entry points
+
+| File | What it is |
+| --- | --- |
+| `src/main.ts` | Boot, port (`PORT`, falls back to 3001), global pipes |
+| `src/app.module.ts` | Every module is registered here — the index of the API |
+| `src/config/database.config.ts` | Connection, pooler `search_path` handling, `iamEntities` list |
+| `src/data-source.ts` | Standalone DataSource used by migrations only (no `autoLoadEntities`) |
+| `src/migrations/` | TypeORM migrations (39 files; check for timestamp clashes) |
+| `src/seed/freight-permissions.registry.ts` | Every freight permission; declare before use |
+| `src/scripts/` | One-off and `seed:*` scripts — several write real rows |
+
+## Freight modules by domain
+
+All under `apps/edr-freight-api/src/modules/`.
+
+| Domain | Modules |
+| --- | --- |
+| **Booking & commercial** | `bookings` `contracts` `contract-templates` `consignments` `cargoes` `companies` `user-trade-access` `transit-agents` `shipping-lines` |
+| **Warehouse & yard** | `warehouses` `facilities` `container-management` |
+| **Rail operations** | `trains` `train-schedules` `train-scheduling` `train-sets` `wagons` `wagon-types` `locomotives` `routes` `scheduling` `scheduling-reschedule` `interchange-documents` |
+| **Road / first & last mile** | `first-mile` `last-mile` `last-mile-requests` `drivers` `vehicles` `truck-types` `fleet-history` `fuel` `maintenance` `gps-tracking` `tracking` |
+| **Money** | `billing` `payment` `exchange-settings` |
+| **Identity & access** | `auth` `otp` `verifayda` `audit` |
+| **Documents & files** | `files` `file-upload-settings` `signatures` `stamp-settings` `logo-settings` `minio` |
+| **Comms** | `notifications` `notification-inbox` `support-chat` `support-content` |
+| **Ops & admin** | `backoffice` `overview` `reports` `dropdown-settings` `rule-engine` `compliance` `procurement` `incidents` `import-operations` `eims` `ai` `health` |
+
+Each module follows `module → controller → service → repository`, with `entities/` and
+`dto/` alongside.
+
+## Freight web
+
+Pages live in `src/pages/`, roughly mirroring the API domains.
+
+- **portal** (customer): `bookings` `contracts` `consignments` `billing` `payments`
+  `tracking` `accounts` `customers` `shipping-line` `support` `settings`, plus
+  `MyPortalPage/`, `MySignaturePage.tsx`, `EDRFreightLandingPage.tsx`.
+- **backoffice** (staff): `bookings` `contracts` `contract_templates` `consignments`
+  `customers` `billing` `invoices` `documents` `fleet` `dashboard` `admin` `configuration`
+  `auth` `ai`, plus many single-file pages (`AuditLogsPage.tsx`, `ActivityLogPage.tsx`,
+  `BulkUploadPage.tsx`, `ContentManagementPage.tsx`, …).
+
+Shared components and theme come from `@edr/ui-common` — check there before writing one.
+
+## Tests
+
+| Suite | Location | Run with |
+| --- | --- | --- |
+| Unit / spec | beside the code, `*.spec.ts` | `pnpm --filter @edr/freight-api test` |
+| Freight e2e (Cypress, containerized) | `e2e/freight` | `pnpm e2e:freight:ci` |
+| Passenger e2e | `e2e/` + `e2e/run.sh` | `pnpm test:e2e:passenger` |
+| UI e2e (Playwright) | `e2e-ui/` | `pnpm test:e2e:ui` |
+| Integration | `integration/` | `pnpm it:up`, `pnpm it:test` |
+
+The freight e2e stack has no host Xvfb — use `ci` (containerized), not `run`/`open`.
+Its compose project name is fixed (`edr-freight-e2e`), so only one can run on this
+machine at a time.
+
+## Documents
+
+| Doc | Covers | Trust |
+| --- | --- | --- |
+| `../CLAUDE.md` | The contract: rules, traps, definition of done | Current — fix in the same PR if wrong |
+| `docs/TESTING.md` | Test strategy | — |
+| `docs/e2e-test-matrix.md`, `docs/ui-e2e-test-matrix.md` | Coverage matrices | — |
+| `docs/ISSUES.md`, `docs/SOLUTIONS.md` | Running log of problems and fixes | Historical |
+| `docs/uploads.md` | File upload handling | — |
+| `docs/qa/edr-freight-qa-test-plan.md` | QA test plan | — |
+| `../DEPLOYMENT.md` | Deploy process | — |
+| `../ITMLS_DB_Design.md`, `../orgstructure.md` | Design notes | Historical |
+| `../E2E_TEST_REPORT.md`, `../checkpoint.md` | Point-in-time snapshots | **Stale by design — dated artifacts, not references** |
+
+Root-level `*.sql` and `*.dump` files are ad-hoc data snapshots, not part of the schema.
+Migrations are the only source of truth for schema.

From c3c3d08a41293be0bb1db057b61630dd48ad30ad Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 17 Aug 2026 07:55:52 +0000
Subject: [PATCH 126/174] fix issue

---
 .../booking-clearance.service.spec.ts         |  1 +
 .../contracts/booking-clearance.service.ts    | 39 +++++++-
 .../contracts/ContractClearanceListPage.tsx   | 58 ++++++++++--
 .../contracts/GlDjiboutiClearanceListPage.tsx | 32 ++++---
 .../contracts/contract-clearance-table.css    | 94 +++++++++++++++++++
 .../src/pages/invoices/InvoicesPage.tsx       | 70 +++++++-------
 .../components/WagonCancellationCard.tsx      |  4 +-
 7 files changed, 238 insertions(+), 60 deletions(-)
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/contracts/contract-clearance-table.css

diff --git a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts
index 8c127e840..b29a4cfa5 100644
--- a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts
@@ -110,6 +110,7 @@ function makeService(overrides?: {
         .fn()
         .mockResolvedValue({ id: 'ta-1', name: 'Ahmed Bourhan' }),
     } as never, // transit agents
+    { findAll: jest.fn().mockResolvedValue([]) } as never, // contracts repository
   );
 
   return {
diff --git a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
index e0d30a2be..43176da75 100644
--- a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
@@ -1,4 +1,5 @@
 import { BadRequestException, Injectable } from '@nestjs/common';
+import { In } from 'typeorm';
 import {
   ContractDocPhase,
   isDeliveryOrderFileCode,
@@ -29,6 +30,7 @@ import { ClearanceMilestoneService } from './clearance-milestone.service';
 import { GlOperationsService } from './gl-operations.service';
 import { GlExchangeService } from './gl-exchange.service';
 import { TransitAgentsService } from '../transit-agents/transit-agents.service';
+import { ContractsRepository } from './contracts.repository';
 import { AdviseContractDutyDto } from './dto/phased-clearance.dto';
 import { buildWorkflowFiles, belongsOnDjClearanceQueue, belongsOnEtClearanceQueue, DJ_BOOKING_QUEUE_STATUSES, persistDeclarationUploads, persistDeliveryOrderUploads, persistDraftDeclarationUploads, persistReleaseOrderUploads, persistTransitPermitUploads, PHASED_CUSTOMS_BOOKING_QUEUE_STATUSES } from './phased-clearance.util';
 
@@ -155,6 +157,7 @@ export class BookingClearanceService {
     private readonly notifier: BookingLifecycleNotifierService,
     private readonly glExchangeService: GlExchangeService,
     private readonly transitAgentsService: TransitAgentsService,
+    private readonly contractsRepository: ContractsRepository,
   ) {}
 
   private async assertPhasedCustoms(booking: Booking): Promise<void> {
@@ -988,7 +991,39 @@ export class BookingClearanceService {
       const milestones = await this.workflowService.listMilestonesForBooking(b.id);
       if (belongsOnEtClearanceQueue(milestones)) filtered.push(b);
     }
-    return filtered;
+    return this.attachContractSummary(filtered);
+  }
+
+  /**
+   * Queue rows show the parent contract's reference and lane. Booking has no
+   * contract relation, and a bare initiated instance may not carry yards yet —
+   * so batch-load the contracts (with routes) and fill in what's missing:
+   * `contractReference` always, origin/destination yards only when the booking
+   * lacks them (its own route wins).
+   */
+  private async attachContractSummary(bookings: Booking[]): Promise<Booking[]> {
+    const ids = [...new Set(bookings.map((b) => b.contractId).filter(Boolean))] as string[];
+    if (!ids.length) return bookings;
+    const contracts = await this.contractsRepository.findAll({
+      where: { id: In(ids) },
+      relations: { routes: { originYard: true, destinationYard: true } },
+    });
+    const byId = new Map(contracts.map((c) => [c.id, c]));
+    for (const b of bookings) {
+      const contract = b.contractId ? byId.get(b.contractId) : undefined;
+      if (!contract) continue;
+      const row = b as Booking & { contractReference?: string | null };
+      row.contractReference = contract.reference ?? null;
+      if (b.originYard && b.destinationYard) continue;
+      const routes = contract.routes ?? [];
+      const route =
+        routes.find((r) => r.id === b.contractRouteId) ??
+        (routes.length === 1 ? routes[0] : undefined);
+      if (!route) continue;
+      b.originYard = b.originYard ?? route.originYard;
+      b.destinationYard = b.destinationYard ?? route.destinationYard;
+    }
+    return bookings;
   }
 
   async djQueue(): Promise<Booking[]> {
@@ -1008,6 +1043,6 @@ export class BookingClearanceService {
         filtered.push(b);
       }
     }
-    return filtered;
+    return this.attachContractSummary(filtered);
   }
 }
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 8719f644a..503e6dc60 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractClearanceListPage.tsx
@@ -52,6 +52,47 @@ import {
   summarizeRequestedCargo,
 } from "@/features/clearance/requestedCargo";
 import { contractsService } from "@/services/contracts.service";
+import "./contract-clearance-table.css";
+
+/** Yards carry `label` (API) — older shapes used `name`/`code`. */
+function yardLabel(
+  yard?: { label?: string; code?: string; name?: string } | null,
+): string {
+  if (!yard) return "—";
+  return yard.label ?? yard.name ?? yard.code ?? "—";
+}
+
+/**
+ * "Origin → Destination", wrapping past 120px as "Addis Ababa" /
+ * "→ Djibouti": the arrow is glued to the destination with an nbsp, and
+ * text wraps normally (the table's cells are otherwise nowrap) so a long
+ * lane never spills into the next column.
+ */
+function RouteLabel({
+  origin,
+  destination,
+}: {
+  origin: string;
+  destination: string;
+}) {
+  return (
+    <Text
+      size="sm"
+      maw={120}
+      lh={1.35}
+      style={{ whiteSpace: "normal", overflowWrap: "anywhere" }}
+    >
+      {origin}{" "}
+      <ArrowRight
+        size={13}
+        className="text-muted-foreground"
+        style={{ display: "inline-block", verticalAlign: "-2px" }}
+      />
+      {"\u00A0"}
+      {destination}
+    </Text>
+  );
+}
 
 function CustomsBadge({ customs }: { customs: boolean }) {
   return customs ? (
@@ -118,8 +159,8 @@ export default function ContractClearanceListPage() {
       id: b.id,
       reference: b.reference,
       customerLabel: b.company?.name ?? b.governmentInstitution ?? "—",
-      originLabel: b.originYard?.name ?? "—",
-      destinationLabel: b.destinationYard?.name ?? "—",
+      originLabel: yardLabel(b.originYard),
+      destinationLabel: yardLabel(b.destinationYard),
       tradeDirection: b.tradeDirection ?? "—",
       freightType: b.freightType ?? "—",
       status: b.status,
@@ -430,11 +471,10 @@ function ShipmentBookingsTable({
         id: "route",
         header: () => <span className={bookingTable.headerCell}>Route</span>,
         cell: ({ row }) => (
-          <Group gap={6} wrap="nowrap">
-            <Text size="sm">{row.original.originLabel}</Text>
-            <ArrowRight size={13} className="shrink-0 text-muted-foreground" />
-            <Text size="sm">{row.original.destinationLabel}</Text>
-          </Group>
+          <RouteLabel
+            origin={row.original.originLabel}
+            destination={row.original.destinationLabel}
+          />
         ),
       },
       {
@@ -600,13 +640,13 @@ function ShipmentBookingsTable({
   }
 
   return (
-    <Box style={{ overflowX: "auto" }} px="xs" pb="xs">
+    <Box w="100%" miw={0} style={{ overflowX: "auto" }}>
       <DataTable<ShipmentBookingRow, unknown>
         columns={columns}
         data={rows}
         status={loading ? "loading" : error ? "error" : "success"}
         onRowClick={(row) => onOpen(row.id)}
-        containerClassName="border-0 shadow-none bg-transparent [&_th]:max-w-[100px] [&_td]:max-w-[100px] [&_td]:break-words"
+        containerClassName="edr-clearance-table border-0 shadow-none rounded-none bg-transparent"
       />
     </Box>
   );
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/GlDjiboutiClearanceListPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/GlDjiboutiClearanceListPage.tsx
index 76f2bc5b0..6e34da29a 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/GlDjiboutiClearanceListPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/GlDjiboutiClearanceListPage.tsx
@@ -45,6 +45,7 @@ import { KpiStrip } from "@/components/page/KpiStrip";
 import { bookingTable } from "@/components/bookings/booking-ui.styles";
 import { useBookingDjClearanceQueue } from "@/hooks/bookings/useBookings";
 import type { BookingDetail } from "@/types/booking";
+import "./contract-clearance-table.css";
 
 const prettyStatus = (s?: string | null) =>
   (s ?? "")
@@ -214,15 +215,24 @@ function RouteCell({
 }) {
   return (
     <Stack gap={4} py={2}>
-      <Group gap={6} wrap="nowrap">
-        <Text size="sm" fw={500}>
-          {origin}
-        </Text>
-        <ArrowRight size={14} className="shrink-0 text-muted-foreground" />
-        <Text size="sm" fw={500}>
-          {destination}
-        </Text>
-      </Group>
+      {/* Wraps past 120px as "Addis Ababa" / "→ Djibouti"; text wraps
+          normally (cells are otherwise nowrap) so it never spills over. */}
+      <Text
+        size="sm"
+        fw={500}
+        maw={120}
+        lh={1.35}
+        style={{ whiteSpace: "normal", overflowWrap: "anywhere" }}
+      >
+        {origin}{" "}
+        <ArrowRight
+          size={13}
+          className="text-muted-foreground"
+          style={{ display: "inline-block", verticalAlign: "-2px" }}
+        />
+        {"\u00A0"}
+        {destination}
+      </Text>
       <Group gap={8} align="center">
         <DirectionIcon direction={direction} />
         <Badge size="xs" variant="default" radius="sm">
@@ -676,7 +686,7 @@ export default function GlDjiboutiClearanceListPage() {
                 ) : null}
               </Stack>
             ) : (
-              <Box style={{ overflowX: "auto" }} px="xs" pb="xs">
+              <Box w="100%" miw={0} style={{ overflowX: "auto" }}>
                 <DataTable<ShipmentRow, unknown>
                   columns={shipmentColumns}
                   data={pagedShipmentRows}
@@ -694,7 +704,7 @@ export default function GlDjiboutiClearanceListPage() {
                     manualPagination: true,
                     pageCount,
                   }}
-                  containerClassName="border-0 shadow-none bg-transparent [&_th]:max-w-[100px] [&_td]:max-w-[100px] [&_td]:break-words"
+                  containerClassName="edr-clearance-table border-0 shadow-none rounded-none bg-transparent"
                   footer={DataTableFooter}
                 />
               </Box>
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/contract-clearance-table.css b/apps/edr-freight-web/backoffice/src/pages/contracts/contract-clearance-table.css
new file mode 100644
index 000000000..bdc615fb8
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/contract-clearance-table.css
@@ -0,0 +1,94 @@
+/*
+ * Scoped to .edr-clearance-table — the DataTable container div on the
+ * Document Clearance hubs (GL Ethiopia + GL Djibouti). Mirrors the portal's /bookings table
+ * (bookings-table.css): content-sized columns with a 100px floor, no
+ * truncation, horizontal scroll when the table outgrows the card, sticky
+ * header row and a sticky shadowed action column.
+ */
+.edr-clearance-table {
+  overflow-x: auto;
+  max-width: 100%;
+  min-width: 0;
+}
+
+/*
+ * width: max-content — the table is exactly as wide as its columns' content
+ * needs, never squeezed to fit the viewport; the container scrolls instead.
+ * min-width: 100% keeps it filling the card when content is narrow.
+ */
+.edr-clearance-table table {
+  table-layout: auto;
+  width: max-content;
+  min-width: 100%;
+}
+
+/* 100px floor, no ceiling: cells grow to fit their text, nothing is clipped. */
+.edr-clearance-table th,
+.edr-clearance-table td:not([colspan]) {
+  min-width: 100px;
+  max-width: none;
+  overflow: visible;
+  text-overflow: clip;
+  white-space: nowrap;
+}
+
+/*
+ * Mantine Badge caps itself at max-width: 100%; inside an auto-layout table
+ * cell that resolves against min-content and clips the label. Let badges size
+ * to their text so the column grows to fit them.
+ */
+.edr-clearance-table .mantine-Badge-root {
+  max-width: none;
+}
+
+/*
+ * Mantine Group's preventGrowOverflow caps every child at 100%/N of the cell.
+ * In an auto-width table cell that resolves against min-content and collapses
+ * the badges/text in the Type, Route and Status columns to nothing. Let group
+ * children size to their content; the column grows and the container scrolls.
+ */
+.edr-clearance-table .mantine-Group-root > * {
+  max-width: none;
+  flex-shrink: 0;
+}
+
+/* Sticky header row. */
+.edr-clearance-table thead th {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+}
+
+/*
+ * Sticky action column, shrunk to its content. The width overrides the inline
+ * width DataTable stamps from tanstack's column size — hence !important.
+ * `:not([colspan])` keeps the full-width error/empty rows out.
+ */
+.edr-clearance-table th:last-child,
+.edr-clearance-table td:last-child:not([colspan]) {
+  width: 1% !important;
+  min-width: 0;
+  position: sticky;
+  right: 0;
+  box-shadow: -12px 0 16px -6px rgba(16, 32, 47, 0.3);
+}
+
+/*
+ * Sticky cells sit above the scrolling ones, so they need their own opaque
+ * background or the columns underneath show through.
+ */
+.edr-clearance-table td:last-child:not([colspan]) {
+  background: #f5f8fb;
+  z-index: 2;
+}
+
+/* Row hover uses the tailwind `hover:bg-accent` class on the <tr>. */
+.edr-clearance-table tbody tr:hover td:last-child:not([colspan]) {
+  background: var(--accent, #f4fbf8);
+}
+
+/* Header cell is sticky on both axes — it must outrank the body's sticky column. */
+.edr-clearance-table th:last-child {
+  background: #f4f7fa;
+  z-index: 3;
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
index 99f3c5d23..159157e2f 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/InvoicesPage.tsx
@@ -5,14 +5,20 @@ import {
   Card,
   Group,
   SegmentedControl,
-  SimpleGrid,
   Stack,
   Text,
   TextInput,
 } from "@mantine/core";
 import { useDebouncedValue } from "@mantine/hooks";
 import { useQuery } from "@tanstack/react-query";
-import { RefreshCw, Search, X } from "lucide-react";
+import {
+  Banknote,
+  CircleDollarSign,
+  Landmark,
+  RefreshCw,
+  Search,
+  X,
+} from "lucide-react";
 import { useMemo, useState } from "react";
 import { useNavigate } from "react-router-dom";
 
@@ -22,6 +28,7 @@ import {
   formatMoney,
   humanize,
 } from "@/components/customers";
+import { KpiStrip } from "@/components/page";
 import CreditInvoiceActions from "@/components/shipping-lines/CreditInvoiceActions";
 import { useExchangeSettingsQuery } from "@/hooks/useExchangeSettings";
 import { api } from "@/services/api";
@@ -83,7 +90,7 @@ export default function InvoicesPanel() {
 
   // Summary card: total collected (paidAmount) across every invoice matching
   // the current search/status filters, not just the visible page.
-  const { data: summary } = useQuery(
+  const { data: summary, isLoading: summaryLoading } = useQuery(
     api.invoices.collectedSummary.queryOptions({
       input: {
         filter: { search: debouncedQuery, status: statusFilter || undefined },
@@ -190,39 +197,30 @@ export default function InvoicesPanel() {
 
   return (
     <Stack gap="md">
-      <SimpleGrid cols={{ base: 1, sm: 3 }}>
-        <Card withBorder radius="md" padding="md">
-          <Text size="xs" c="dimmed" fw={600} tt="uppercase">
-            Total collected
-          </Text>
-          <Text size="xl" fw={700} c="edr-text">
-            {etbFromUsd !== null
-              ? formatMoney(etbCollected + etbFromUsd, "ETB")
-              : formatMoney(etbCollected, "ETB")}
-          </Text>
-          <Text size="xs" c="dimmed">
-            {etbFromUsd !== null
-              ? `Includes ${formatMoney(usdCollected, "USD")} converted @ ${rate} ETB/USD`
-              : "USD rate unavailable — ETB collected only"}
-          </Text>
-        </Card>
-        <Card withBorder radius="md" padding="md">
-          <Text size="xs" c="dimmed" fw={600} tt="uppercase">
-            Collected — ETB only
-          </Text>
-          <Text size="xl" fw={700} c="edr-text">
-            {formatMoney(etbCollected, "ETB")}
-          </Text>
-        </Card>
-        <Card withBorder radius="md" padding="md">
-          <Text size="xs" c="dimmed" fw={600} tt="uppercase">
-            Collected — USD only
-          </Text>
-          <Text size="xl" fw={700} c="edr-text">
-            {formatMoney(usdCollected, "USD")}
-          </Text>
-        </Card>
-      </SimpleGrid>
+      <KpiStrip
+        loading={summaryLoading}
+        items={[
+          {
+            label: "Total collected",
+            hint: etbFromUsd !== null ? "ETB + USD" : "ETB only",
+            value: formatMoney(etbCollected + (etbFromUsd ?? 0), "ETB"),
+            icon: CircleDollarSign,
+            color: "edr-green",
+          },
+          {
+            label: "Collected in ETB",
+            value: formatMoney(etbCollected, "ETB"),
+            icon: Banknote,
+            color: "blue",
+          },
+          {
+            label: "Collected in USD",
+            value: formatMoney(usdCollected, "USD"),
+            icon: Landmark,
+            color: "violet",
+          },
+        ]}
+      />
 
       <Card p={0}>
       <Stack gap={0}>
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx
index f75972f28..29ec6705d 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx
@@ -235,7 +235,7 @@ export function WagonCancellationCard({
     <SectionCard>
       <Group justify="space-between" align="center" mb="sm">
         <CardTitle>Wagon Cancellation</CardTitle>
-        {canRequest && !openRow && !creditRow && (
+        {/* {canRequest && !openRow && !creditRow && (
           <Button
             variant="default"
             radius="md"
@@ -244,7 +244,7 @@ export function WagonCancellationCard({
           >
             Cancel wagons
           </Button>
-        )}
+        )} */}
       </Group>
 
       {openRow ? (

From df488ebfaa78587b5c9f067cdaff98a5f1336fc3 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 17 Aug 2026 08:01:29 +0000
Subject: [PATCH 127/174] chnages

---
 .../BookingDetailPage/components/WagonCancellationCard.tsx      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx
index 29ec6705d..d5ab1754a 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingDetailPage/components/WagonCancellationCard.tsx
@@ -11,7 +11,7 @@ import {
   Textarea,
 } from "@mantine/core";
 import { useMutation, useQuery } from "@tanstack/react-query";
-import { CheckCircle2, Clock, CreditCard, TrainTrack } from "lucide-react";
+import { CheckCircle2, Clock, CreditCard } from "lucide-react";
 import { useMemo, useState } from "react";
 import toast from "react-hot-toast";
 import { Link, useNavigate } from "react-router-dom";

From 00bd1250ee056406e626e2bcddd2f5d98b13c4e1 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Fri, 31 Jul 2026 06:36:03 +0000
Subject: [PATCH 128/174] feat: WIP element Chat intergration

---
 .github/workflows/deploy.yml                  |   8 +-
 apps/edr-freight-api/.env.example             |  19 ++
 apps/edr-freight-api/src/app.module.ts        |   6 +
 .../src/common/booking-guards.ts              |   2 +
 .../edr-freight-api/src/config/chat.config.ts |  59 ++++
 .../src/modules/chat/chat-bridge.service.ts   |  73 +++++
 .../modules/chat/chat-provisioning.service.ts | 192 +++++++++++++
 .../src/modules/chat/chat-sso.service.ts      |  59 ++++
 .../src/modules/chat/chat.controller.ts       |  35 +++
 .../src/modules/chat/chat.module.ts           |  16 ++
 .../src/modules/chat/matrix.client.ts         | 263 ++++++++++++++++++
 .../notification-inbox.module.ts              |   3 +
 .../notification-inbox.service.ts             |  12 +-
 .../src/seed/edr-freight.seed.ts              |   1 +
 .../src/seed/freight-permissions.registry.ts  |  11 +
 apps/edr-freight-web/backoffice/src/App.tsx   |   9 +
 .../src/components/layout/route-meta.ts       |   7 +
 .../components/layout/sidebar-sections.tsx    |   7 +
 .../backoffice/src/features/chat/chatApi.ts   |  13 +
 .../src/features/chat/useChatSso.ts           |  19 ++
 .../backoffice/src/lib/permissions.ts         |   4 +
 .../src/pages/chat/ChatLaunchPage.tsx         |  62 +++++
 docker-compose.yaml                           |  28 ++
 infrastructure/matrix/element/Dockerfile      |   9 +
 infrastructure/matrix/element/config.json     |  17 ++
 infrastructure/matrix/element/sso.html        |  36 +++
 infrastructure/matrix/synapse/Dockerfile      |  15 +
 .../matrix/synapse/docker-entrypoint.sh       |  20 ++
 .../matrix/synapse/homeserver.yaml.tmpl       |  95 +++++++
 infrastructure/matrix/synapse/log.config      |  25 ++
 scripts/deploy/sync-env-from-server.sh        |   5 +
 31 files changed, 1128 insertions(+), 2 deletions(-)
 create mode 100644 apps/edr-freight-api/src/config/chat.config.ts
 create mode 100644 apps/edr-freight-api/src/modules/chat/chat-bridge.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/chat/chat-provisioning.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/chat/chat-sso.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/chat/chat.controller.ts
 create mode 100644 apps/edr-freight-api/src/modules/chat/chat.module.ts
 create mode 100644 apps/edr-freight-api/src/modules/chat/matrix.client.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/features/chat/chatApi.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/features/chat/useChatSso.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/chat/ChatLaunchPage.tsx
 create mode 100644 infrastructure/matrix/element/Dockerfile
 create mode 100644 infrastructure/matrix/element/config.json
 create mode 100644 infrastructure/matrix/element/sso.html
 create mode 100644 infrastructure/matrix/synapse/Dockerfile
 create mode 100644 infrastructure/matrix/synapse/docker-entrypoint.sh
 create mode 100644 infrastructure/matrix/synapse/homeserver.yaml.tmpl
 create mode 100644 infrastructure/matrix/synapse/log.config

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index b1c797dc6..b6a7fdb69 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -43,6 +43,8 @@ jobs:
             "passenger-portal"
             "passenger-backoffice"
             "payment-api"
+            "synapse"
+            "element-web"
           )
 
           if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
@@ -84,6 +86,10 @@ jobs:
           echo "$CHANGED" | grep -q "^apps/edr-passenger-web/portal/"     && SERVICES+=("passenger-portal")
           echo "$CHANGED" | grep -q "^apps/edr-passenger-web/backoffice/" && SERVICES+=("passenger-backoffice")
           echo "$CHANGED" | grep -q "^apps/edr-payment-api/"              && SERVICES+=("payment-api")
+          # synapse / element-web have no per-service filter line: their only
+          # source is infrastructure/matrix/, already caught by GLOBAL_PATTERN
+          # above (which redeploys every service), so a dedicated line here
+          # would never fire.
 
           SERVICES=($(printf '%s\n' "${SERVICES[@]}" | sort -u))
 
@@ -119,7 +125,7 @@ jobs:
       - name: Resolve project and build env file
         run: |
           case "${{ matrix.service }}" in
-            freight-api|freight-portal|freight-backoffice|gps-tracker)
+            freight-api|freight-portal|freight-backoffice|gps-tracker|synapse|element-web)
               echo "PROJECT=edr-freight"                      >> "$GITHUB_ENV"
               echo "BUILD_ENV_FILE=freight-web.build.env"    >> "$GITHUB_ENV"
               ;;
diff --git a/apps/edr-freight-api/.env.example b/apps/edr-freight-api/.env.example
index d2359dd97..930c8f1ca 100644
--- a/apps/edr-freight-api/.env.example
+++ b/apps/edr-freight-api/.env.example
@@ -219,3 +219,22 @@ EIMS_AUTO_SUBMIT=false
 EIMS_AUTO_SUBMIT_CRON=0 */5 * * * *
 # MoR rejects documents older than 3 days; the sweep will not attempt those.
 EIMS_AUTO_SUBMIT_MAX_AGE_DAYS=3
+# ── Internal chat (Matrix/Element) ──────────────────────────────────────────
+# Disabled by default; /chat/sso and the nightly room/membership reconcile are
+# no-ops until enabled. See infrastructure/matrix/.
+MATRIX_ENABLED=false
+# Synapse URL reachable from this container (docker-compose service DNS in
+# prod, e.g. http://synapse:8008 — NOT the public https://matrix.edr.et).
+MATRIX_BASE_URL=http://localhost:8008
+# Synapse's own public_baseurl — what Element itself is configured to call.
+# Only used to seed the sso.html handoff page's localStorage.
+MATRIX_PUBLIC_BASE_URL=https://matrix.edr.et
+MATRIX_CHAT_WEB_URL=https://chat.edr.et
+MATRIX_SERVER_NAME=matrix.edr.et
+# Must exactly match infrastructure/matrix/synapse/.env's MATRIX_JWT_SECRET —
+# this is the whole trust boundary for the SSO handoff.
+MATRIX_JWT_SECRET=
+# access_token of a Synapse server-admin account. Bootstrap it once via
+# infrastructure/matrix/synapse's MATRIX_REGISTRATION_SHARED_SECRET (see that
+# file's comments) — this app never touches the shared secret itself.
+MATRIX_ADMIN_TOKEN=
diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index d38c6ea92..405612ddf 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -23,6 +23,7 @@ import telebirrConfig from "./config/telebirr.config";
 import rabbitmqConfig from "./config/rabbitmq.config";
 import faydaConfig from "./config/fayda.config";
 import eimsConfig from "./config/eims.config";
+import chatConfig from "./config/chat.config";
 
 import { BookingsModule } from "./modules/bookings/bookings.module";
 import { ContractsModule } from "./modules/contracts/contracts.module";
@@ -116,7 +117,10 @@ import { InterchangeDocumentsModule } from "./modules/interchange-documents/inte
 import { ImportOperationsModule } from "./modules/import-operations/import-operations.module";
 import { AiModule } from "./modules/ai/ai.module";
 import { AuditModule } from "./modules/audit/audit.module";
+// dev replaced the local LoggerMiddleware with the shared RequestLogMiddleware
+// and deleted ./logger.middleware, so the branch's import is dropped here.
 import { RequestLogMiddleware } from "@edr/api-common";
+import { ChatModule } from "./modules/chat/chat.module";
 import { LoginAudienceMiddleware } from "./modules/auth/login-audience.middleware";
 import { PositionTypePermissionsCache } from "./common/position-type-permissions.cache";
 
@@ -135,6 +139,7 @@ if (!process.env.APPLICATION_NAME) {
         rabbitmqConfig,
         faydaConfig,
         eimsConfig,
+        chatConfig,
       ],
     }),
     ScheduleModule.forRoot(),
@@ -252,6 +257,7 @@ if (!process.env.APPLICATION_NAME) {
     FleetHistoryModule,
     AiModule,
     AuditModule,
+    ChatModule,
   ],
   providers: [
     EdrOrgSeeder,
diff --git a/apps/edr-freight-api/src/common/booking-guards.ts b/apps/edr-freight-api/src/common/booking-guards.ts
index 36ed7ae74..f9eab4d39 100644
--- a/apps/edr-freight-api/src/common/booking-guards.ts
+++ b/apps/edr-freight-api/src/common/booking-guards.ts
@@ -49,6 +49,8 @@ export const MixedAudience = (permission: string | string[]) =>
 
 export const BookingView = () => BookingStaff(FREIGHT_PERMS.bookings.view);
 
+export const ChatSync = () => BookingStaff(FREIGHT_PERMS.chat.sync);
+
 /**
  * The document-review countdown in the backoffice header. Its own permission so
  * it can be granted to exactly the position types that decide operation
diff --git a/apps/edr-freight-api/src/config/chat.config.ts b/apps/edr-freight-api/src/config/chat.config.ts
new file mode 100644
index 000000000..ce20b610b
--- /dev/null
+++ b/apps/edr-freight-api/src/config/chat.config.ts
@@ -0,0 +1,59 @@
+import { registerAs } from '@nestjs/config';
+
+export interface ChatConfig {
+  enabled: boolean;
+  /** Synapse base URL reachable from this container (client + admin APIs). */
+  baseUrl: string;
+  /** Synapse's public_baseurl — what Element itself is configured to call. Only
+   *  used to seed the sso.html handoff; server-to-server calls use {@link baseUrl}. */
+  publicBaseUrl: string;
+  /** Public Element Web origin — the SSO handoff link points here. */
+  webUrl: string;
+  /** Matrix server_name — the `:domain` half of every MXID. */
+  serverName: string;
+  /** HS256 secret. Must exactly match Synapse's jwt_config.secret. */
+  jwtSecret: string;
+  /** Bearer token for a Synapse server admin account (room/user provisioning). */
+  adminToken: string;
+}
+
+const REQUIRED_VARS = [
+  'MATRIX_BASE_URL',
+  'MATRIX_PUBLIC_BASE_URL',
+  'MATRIX_CHAT_WEB_URL',
+  'MATRIX_SERVER_NAME',
+  'MATRIX_JWT_SECRET',
+  'MATRIX_ADMIN_TOKEN',
+] as const;
+
+export default registerAs('chat', (): ChatConfig => {
+  const enabled = (process.env.MATRIX_ENABLED ?? 'false').toLowerCase() === 'true';
+  if (!enabled) {
+    return {
+      enabled: false,
+      baseUrl: '',
+      publicBaseUrl: '',
+      webUrl: '',
+      serverName: '',
+      jwtSecret: '',
+      adminToken: '',
+    };
+  }
+
+  const missing = REQUIRED_VARS.filter((name) => !process.env[name]);
+  if (missing.length > 0) {
+    throw new Error(
+      `Internal chat is enabled (MATRIX_ENABLED=true) but the following env vars are missing: ${missing.join(', ')}`,
+    );
+  }
+
+  return {
+    enabled: true,
+    baseUrl: process.env.MATRIX_BASE_URL!.replace(/\/$/, ''),
+    publicBaseUrl: process.env.MATRIX_PUBLIC_BASE_URL!.replace(/\/$/, ''),
+    webUrl: process.env.MATRIX_CHAT_WEB_URL!.replace(/\/$/, ''),
+    serverName: process.env.MATRIX_SERVER_NAME!,
+    jwtSecret: process.env.MATRIX_JWT_SECRET!,
+    adminToken: process.env.MATRIX_ADMIN_TOKEN!,
+  };
+});
diff --git a/apps/edr-freight-api/src/modules/chat/chat-bridge.service.ts b/apps/edr-freight-api/src/modules/chat/chat-bridge.service.ts
new file mode 100644
index 000000000..75bbe9a29
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/chat/chat-bridge.service.ts
@@ -0,0 +1,73 @@
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import type { ConfigType } from '@nestjs/config';
+import { NotificationType, type NotifyInput } from '@edr/types';
+
+import chatConfig from '../../config/chat.config';
+import { MatrixClient } from './matrix.client';
+
+const FALLBACK_ROOM = { alias: 'freight-alerts', name: 'Freight Alerts' };
+
+/**
+ * Best-effort per-type routing to an existing dept room. Anything not listed
+ * (including GENERIC) falls through to #freight-alerts — safer than a wrong
+ * guess at which department a type belongs to. Extend as real usage shows
+ * which types actually want a dept room instead of the shared feed.
+ *
+ * `name` matters only if this bridge is the very first thing to touch that
+ * alias (normally the nightly/on-demand reconcile creates dept rooms first,
+ * with the position's real name) — ensureRoom never renames an existing
+ * room, so this must match what ChatProvisioningService would have used.
+ */
+const ROOM_FOR_TYPE: Partial<Record<NotificationType, { alias: string; name: string }>> = {
+  [NotificationType.REQUEST_SUBMITTED]: { alias: 'dept-operation', name: 'Operation' },
+  [NotificationType.CLEARANCE_REVIEW]: { alias: 'dept-operation', name: 'Operation' },
+};
+
+/**
+ * Mirrors BACKOFFICE-audience notifications into chat so staff see them
+ * without having the inbox open. Hooked once into
+ * NotificationInboxService.notify() — every one of that service's ~20
+ * callers gets this for free.
+ *
+ * Gated on BACKOFFICE only: notify() also serves PORTAL (customer)
+ * notifications, which must never land in an internal staff room.
+ */
+@Injectable()
+export class ChatBridgeService {
+  private readonly logger = new Logger(ChatBridgeService.name);
+
+  constructor(
+    @Inject(chatConfig.KEY)
+    private readonly config: ConfigType<typeof chatConfig>,
+    private readonly matrix: MatrixClient,
+  ) {}
+
+  async bridge(input: NotifyInput): Promise<void> {
+    if (!this.config.enabled) return;
+
+    try {
+      const room = ROOM_FOR_TYPE[input.type] ?? FALLBACK_ROOM;
+      const roomId = await this.matrix.ensureRoom(room.alias, room.name);
+      const body = input.link ? `${input.title}\n${input.body}\n${input.link}` : `${input.title}\n${input.body}`;
+      const html = `<strong>${escapeHtml(input.title)}</strong><br/>${escapeHtml(input.body)}${
+        input.link ? `<br/><a href="${escapeHtml(input.link)}">${escapeHtml(input.link)}</a>` : ''
+      }`;
+      await this.matrix.sendMessage(roomId, body, html);
+    } catch (err) {
+      // Same contract as NotificationInboxService.notify(): a chat-bridge
+      // failure must never break or roll back the notification that
+      // triggered it.
+      this.logger.error(
+        `Chat bridge failed for ${input.type}: ${(err as Error).message}`,
+      );
+    }
+  }
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
diff --git a/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.ts b/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.ts
new file mode 100644
index 000000000..7b748e576
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.ts
@@ -0,0 +1,192 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Cron, CronExpression } from '@nestjs/schedule';
+import { InjectDataSource } from '@nestjs/typeorm';
+import { DataSource } from 'typeorm';
+
+import { MatrixClient } from './matrix.client';
+
+/** edr-org.seeder.ts's EDR_ORG_KEY / EDR_UNIT_KEY — the org is currently flat
+ *  (one org, one unit), so this is the entire scope of what gets provisioned. */
+const ORG_KEY = 'edr_freight';
+const UNIT_KEY = 'edr_freight_app';
+
+const SPACE_ALIAS = 'edr-freight';
+const GENERAL_ALIAS = 'general';
+
+interface PositionHolder {
+  positionKey: string;
+  positionName: string;
+  userId: string;
+  userName: string;
+}
+
+export interface ReconcileResult {
+  rooms: number;
+  joined: number;
+  kicked: number;
+  deactivated: number;
+}
+
+/**
+ * Keeps Matrix rooms and their membership in sync with IAM's unit/position
+ * tree. There is no local hook on "employee position changed" — IAM writes
+ * happen inside the vendored @tria-plc/iamapi-common package — so this is a
+ * reconcile loop, not an event handler: nightly, plus on-demand via
+ * POST /chat/sync.
+ *
+ * Room identity is a deterministic alias (#dept-<positionKey>), not a stored
+ * mapping table — resolved via the directory API, created on first miss.
+ * Room membership is diffed against Matrix's own joined_members, not a local
+ * snapshot — so a user removed from IAM disappears from chat on the very
+ * next reconcile, with no extra state for this service to own.
+ */
+@Injectable()
+export class ChatProvisioningService {
+  private readonly logger = new Logger(ChatProvisioningService.name);
+
+  constructor(
+    @InjectDataSource() private readonly dataSource: DataSource,
+    private readonly matrix: MatrixClient,
+  ) {}
+
+  @Cron(CronExpression.EVERY_DAY_AT_3AM, { name: 'chat-provisioning-reconcile' })
+  async scheduledReconcile(): Promise<void> {
+    try {
+      const result = await this.reconcile();
+      this.logger.log(
+        `Chat reconcile: ${result.rooms} room(s), ${result.joined} joined, ` +
+          `${result.kicked} kicked, ${result.deactivated} deactivated`,
+      );
+    } catch (err) {
+      // Never throws into the scheduler — chat provisioning must not be able
+      // to take down anything else on the cron registry.
+      this.logger.error(
+        `Chat reconcile failed: ${(err as Error).message}`,
+        (err as Error).stack,
+      );
+    }
+  }
+
+  private async currentHolders(): Promise<PositionHolder[]> {
+    return this.dataSource.query(
+      `SELECT p.key AS "positionKey",
+              COALESCE(p.name->>'en', p.key) AS "positionName",
+              e.user_id AS "userId",
+              COALESCE(iu.name->>'en', iu.username, iu.email) AS "userName"
+         FROM iam.employee_positions ep
+         JOIN iam.employees e ON e.id = ep.employee_id
+         JOIN iam.positions p ON p.id = ep.position_id
+         JOIN iam.units u ON u.id = p.unit_id
+         JOIN iam.organizations o ON o.id = u.organization_id
+         JOIN iam.users iu ON iu.id = e.user_id
+        WHERE ep.is_current = true
+          AND e.is_current = true
+          AND o.key = $1
+          AND u.key = $2`,
+      [ORG_KEY, UNIT_KEY],
+    );
+  }
+
+  /** Force-joins additions, kicks+deactivates users no longer entitled anywhere. */
+  private async syncMembership(
+    roomId: string,
+    desiredUserIds: Set<string>,
+    botMxid: string,
+  ): Promise<{ joined: number; kicked: string[] }> {
+    const current = await this.matrix.joinedMembers(roomId);
+    const currentSet = new Set(current.filter((id) => id !== botMxid));
+
+    let joined = 0;
+    for (const userId of desiredUserIds) {
+      if (!currentSet.has(userId)) {
+        await this.matrix.forceJoin(roomId, userId);
+        joined += 1;
+      }
+    }
+
+    const kicked: string[] = [];
+    for (const userId of currentSet) {
+      if (!desiredUserIds.has(userId)) {
+        await this.matrix.kick(roomId, userId, 'No longer assigned to this room');
+        kicked.push(userId);
+      }
+    }
+
+    return { joined, kicked };
+  }
+
+  async reconcile(): Promise<ReconcileResult> {
+    const holders = await this.currentHolders();
+    const botMxid = await this.matrix.whoami();
+
+    const spaceId = await this.matrix.ensureRoom(SPACE_ALIAS, 'EDR Freight', {
+      isSpace: true,
+    });
+    const generalRoomId = await this.matrix.ensureRoom(GENERAL_ALIAS, 'General', {
+      parentSpaceId: spaceId,
+    });
+
+    const allUserIds = new Set(holders.map((h) => this.matrix.mxid(h.userId)));
+
+    // Accounts are otherwise only created lazily on first JWT login (see
+    // ChatSsoService) — force-joining someone who has never clicked "Chat"
+    // yet 404s ("User not found") without this.
+    const seenUserIds = new Set<string>();
+    for (const h of holders) {
+      const mxid = this.matrix.mxid(h.userId);
+      if (seenUserIds.has(mxid)) continue;
+      seenUserIds.add(mxid);
+      await this.matrix.ensureUser(mxid, h.userName);
+    }
+
+    let rooms = 2; // space + general
+    let joined = 0;
+    let kicked = 0;
+    // A user kicked from anything while holding zero current positions
+    // anywhere in the unit (allUserIds spans every position) is a full
+    // leaver, not just moved between positions — deactivate their account.
+    const kickedUserIds = new Set<string>();
+
+    const generalDiff = await this.syncMembership(generalRoomId, allUserIds, botMxid);
+    joined += generalDiff.joined;
+    kicked += generalDiff.kicked.length;
+    generalDiff.kicked.forEach((uid) => kickedUserIds.add(uid));
+
+    const byPosition = new Map<string, { name: string; userIds: Set<string> }>();
+    for (const h of holders) {
+      const entry = byPosition.get(h.positionKey) ?? {
+        name: h.positionName,
+        userIds: new Set<string>(),
+      };
+      entry.userIds.add(this.matrix.mxid(h.userId));
+      byPosition.set(h.positionKey, entry);
+    }
+
+    for (const [positionKey, { name, userIds }] of byPosition) {
+      const roomId = await this.matrix.ensureRoom(`dept-${positionKey}`, name, {
+        parentSpaceId: spaceId,
+      });
+      rooms += 1;
+
+      const diff = await this.syncMembership(roomId, userIds, botMxid);
+      joined += diff.joined;
+      kicked += diff.kicked.length;
+      diff.kicked.forEach((uid) => kickedUserIds.add(uid));
+    }
+
+    let deactivated = 0;
+    for (const userId of kickedUserIds) {
+      if (allUserIds.has(userId)) continue; // moved position, still current elsewhere
+      try {
+        await this.matrix.deactivateUser(userId);
+        deactivated += 1;
+      } catch (err) {
+        this.logger.warn(
+          `Failed to deactivate departed user ${userId}: ${(err as Error).message}`,
+        );
+      }
+    }
+
+    return { rooms, joined, kicked, deactivated };
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/chat/chat-sso.service.ts b/apps/edr-freight-api/src/modules/chat/chat-sso.service.ts
new file mode 100644
index 000000000..8f9357e10
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/chat/chat-sso.service.ts
@@ -0,0 +1,59 @@
+import { Inject, Injectable } from '@nestjs/common';
+import type { ConfigType } from '@nestjs/config';
+import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
+import { SignJWT } from 'jose';
+
+import chatConfig from '../../config/chat.config';
+import { MatrixClient } from './matrix.client';
+
+/** Matrix login_tokens are single-use and expire in 5 minutes (Synapse default). */
+const JWT_TTL_SECONDS = 60;
+
+function displayName(user: TCurrentUser): string {
+  return (
+    user.name?.en ||
+    Object.values(user.name ?? {}).find((v) => typeof v === 'string' && v) ||
+    user.username ||
+    user.email
+  );
+}
+
+/**
+ * The SSO handoff: turn an already-authenticated freight session into a
+ * one-click Element sign-in link, with no second password anywhere.
+ *
+ *   1. Sign a short-lived JWT asserting this user's id (Synapse's
+ *      org.matrix.login.jwt auto-registers the account on first use).
+ *   2. Trade that JWT for a real Matrix access token.
+ *   3. Trade the access token for a one-shot login_token.
+ *   4. Hand the caller a link to Element's sso.html shim, which seeds
+ *      localStorage and forwards the token into Element's own login flow.
+ */
+@Injectable()
+export class ChatSsoService {
+  constructor(
+    @Inject(chatConfig.KEY)
+    private readonly config: ConfigType<typeof chatConfig>,
+    private readonly matrix: MatrixClient,
+  ) {}
+
+  async getSsoUrl(user: TCurrentUser): Promise<{ url: string }> {
+    const secret = new TextEncoder().encode(this.config.jwtSecret);
+    const jwt = await new SignJWT({ name: displayName(user) })
+      .setProtectedHeader({ alg: 'HS256' })
+      .setSubject(user.id)
+      .setIssuer('edr-freight-api')
+      .setAudience('matrix')
+      .setIssuedAt()
+      .setExpirationTime(`${JWT_TTL_SECONDS}s`)
+      .sign(secret);
+
+    const { access_token } = await this.matrix.loginWithJwt(jwt);
+    const { login_token } = await this.matrix.getLoginToken(access_token);
+
+    const url = new URL(`${this.config.webUrl}/sso.html`);
+    url.searchParams.set('t', login_token);
+    url.searchParams.set('hs', this.config.publicBaseUrl);
+    return { url: url.toString() };
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/chat/chat.controller.ts b/apps/edr-freight-api/src/modules/chat/chat.controller.ts
new file mode 100644
index 000000000..0ecca04c0
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/chat/chat.controller.ts
@@ -0,0 +1,35 @@
+import { Controller, Get, Post, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { CurrentUser } from '@tria-plc/api-common/modules/auth/decorators/current-user.decorator';
+import { JwtGuard } from '@tria-plc/api-common/modules/auth/services/jwt.guard';
+import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
+
+import { ChatSync } from '../../common/booking-guards';
+import { ChatProvisioningService } from './chat-provisioning.service';
+import { ChatSsoService } from './chat-sso.service';
+
+@ApiTags('chat')
+@Controller('chat')
+@ApiBearerAuth()
+export class ChatController {
+  constructor(
+    private readonly sso: ChatSsoService,
+    private readonly provisioning: ChatProvisioningService,
+  ) {}
+
+  @Get('sso')
+  @UseGuards(JwtGuard)
+  @ApiOperation({ summary: 'One-click sign-in link into EDR internal chat' })
+  getSso(@CurrentUser() user: TCurrentUser) {
+    return this.sso.getSsoUrl(user);
+  }
+
+  @Post('sync')
+  @ChatSync()
+  @ApiOperation({
+    summary: 'Re-run the chat room/membership reconcile immediately (normally nightly)',
+  })
+  sync() {
+    return this.provisioning.reconcile();
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/chat/chat.module.ts b/apps/edr-freight-api/src/modules/chat/chat.module.ts
new file mode 100644
index 000000000..8df827339
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/chat/chat.module.ts
@@ -0,0 +1,16 @@
+import { Module } from '@nestjs/common';
+
+import { ChatBridgeService } from './chat-bridge.service';
+import { ChatController } from './chat.controller';
+import { ChatProvisioningService } from './chat-provisioning.service';
+import { ChatSsoService } from './chat-sso.service';
+import { MatrixClient } from './matrix.client';
+
+@Module({
+  controllers: [ChatController],
+  providers: [MatrixClient, ChatSsoService, ChatProvisioningService, ChatBridgeService],
+  // ChatBridgeService: consumed by NotificationInboxModule to mirror
+  // BACKOFFICE notifications into chat — see notification-inbox.module.ts.
+  exports: [ChatBridgeService],
+})
+export class ChatModule {}
diff --git a/apps/edr-freight-api/src/modules/chat/matrix.client.ts b/apps/edr-freight-api/src/modules/chat/matrix.client.ts
new file mode 100644
index 000000000..01dafb6de
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/chat/matrix.client.ts
@@ -0,0 +1,263 @@
+import { Inject, Injectable } from '@nestjs/common';
+import type { ConfigType } from '@nestjs/config';
+
+import chatConfig from '../../config/chat.config';
+
+/**
+ * Thin wrapper over the handful of Matrix Client-Server + Synapse Admin API
+ * calls this app needs. Not a general Matrix SDK — matrix-js-sdk is a
+ * browser/Element concern; the server side only ever provisions rooms/users
+ * and posts bot messages, so a fetch wrapper is the whole job.
+ *
+ * All admin-scoped calls act as the account behind MATRIX_ADMIN_TOKEN. That
+ * same account also posts the notification-bridge messages (see
+ * ChatBridgeService) — one bot/admin account covers both jobs, no separate
+ * bot user needed.
+ */
+@Injectable()
+export class MatrixClient {
+  constructor(
+    @Inject(chatConfig.KEY)
+    private readonly config: ConfigType<typeof chatConfig>,
+  ) {}
+
+  /** `@<localpart>:<server_name>` — the one place this format is assembled. */
+  mxid(localpart: string): string {
+    return `@${localpart}:${this.config.serverName}`;
+  }
+
+  get serverName(): string {
+    return this.config.serverName;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    token: string = this.config.adminToken,
+  ): Promise<T> {
+    const res = await fetch(`${this.config.baseUrl}${path}`, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(
+        `Matrix ${method} ${path} -> ${res.status}: ${text.slice(0, 500)}`,
+      );
+    }
+    if (res.status === 204) return undefined as T;
+    return (await res.json()) as T;
+  }
+
+  /** No auth — only /login accepts a bare JWT with nothing else on the request. */
+  private async publicRequest<T>(
+    method: string,
+    path: string,
+    body: unknown,
+  ): Promise<T> {
+    const res = await fetch(`${this.config.baseUrl}${path}`, {
+      method,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(
+        `Matrix ${method} ${path} -> ${res.status}: ${text.slice(0, 500)}`,
+      );
+    }
+    return (await res.json()) as T;
+  }
+
+  /** 404 → null. Every other non-2xx still throws via {@link request}. */
+  private async requestOrNull<T>(
+    method: string,
+    path: string,
+    token?: string,
+  ): Promise<T | null> {
+    const res = await fetch(`${this.config.baseUrl}${path}`, {
+      method,
+      headers: { Authorization: `Bearer ${token ?? this.config.adminToken}` },
+    });
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(
+        `Matrix ${method} ${path} -> ${res.status}: ${text.slice(0, 500)}`,
+      );
+    }
+    return (await res.json()) as T;
+  }
+
+  /** Sign an already-authenticated freight session into a Matrix session. */
+  loginWithJwt(
+    jwt: string,
+  ): Promise<{ access_token: string; user_id: string; device_id: string }> {
+    return this.publicRequest('POST', '/_matrix/client/v3/login', {
+      type: 'org.matrix.login.jwt',
+      token: jwt,
+      initial_device_display_name: 'EDR Backoffice',
+    });
+  }
+
+  /** The account behind MATRIX_ADMIN_TOKEN — used to exclude the bot itself from membership reconciliation. */
+  async whoami(): Promise<string> {
+    const res = await this.request<{ user_id: string }>(
+      'GET',
+      '/_matrix/client/v3/account/whoami',
+    );
+    return res.user_id;
+  }
+
+  /** Currently-joined user ids for a room (not full member-event state). */
+  async joinedMembers(roomId: string): Promise<string[]> {
+    const res = await this.request<{ joined: Record<string, unknown> }>(
+      'GET',
+      `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/joined_members`,
+    );
+    return Object.keys(res.joined);
+  }
+
+  /** Exchange a fresh access token for a one-shot login_token (5 min TTL). */
+  getLoginToken(accessToken: string): Promise<{ login_token: string }> {
+    return this.request(
+      'POST',
+      '/_matrix/client/v1/login/get_token',
+      {},
+      accessToken,
+    );
+  }
+
+  /** null when the alias doesn't resolve to a room yet. */
+  resolveAlias(alias: string): Promise<{ room_id: string } | null> {
+    return this.requestOrNull(
+      'GET',
+      `/_matrix/client/v3/directory/room/${encodeURIComponent(alias)}`,
+    );
+  }
+
+  createRoom(input: {
+    alias: string;
+    name: string;
+    topic?: string;
+    isSpace?: boolean;
+    parentSpaceId?: string;
+  }): Promise<{ room_id: string }> {
+    return this.request('POST', '/_matrix/client/v3/createRoom', {
+      room_alias_name: input.alias,
+      name: input.name,
+      topic: input.topic,
+      preset: 'private_chat',
+      creation_content: input.isSpace ? { type: 'm.space' } : undefined,
+      initial_state: input.parentSpaceId
+        ? [
+            {
+              type: 'm.space.parent',
+              state_key: input.parentSpaceId,
+              content: { via: [this.config.serverName], canonical: true },
+            },
+          ]
+        : undefined,
+    });
+  }
+
+  addToSpace(spaceId: string, childRoomId: string): Promise<void> {
+    return this.request(
+      'PUT',
+      `/_matrix/client/v3/rooms/${encodeURIComponent(spaceId)}/state/m.space.child/${encodeURIComponent(childRoomId)}`,
+      { via: [this.config.serverName] },
+    );
+  }
+
+  /**
+   * Get-or-create by alias — the room identity scheme this whole module
+   * relies on instead of a local id-mapping table. Idempotent: safe to call
+   * on every reconcile run and every bridged notification alike.
+   */
+  async ensureRoom(
+    alias: string,
+    name: string,
+    opts: { isSpace?: boolean; parentSpaceId?: string } = {},
+  ): Promise<string> {
+    const existing = await this.resolveAlias(`#${alias}:${this.config.serverName}`);
+    if (existing) return existing.room_id;
+
+    const { room_id } = await this.createRoom({
+      alias,
+      name,
+      isSpace: opts.isSpace,
+      parentSpaceId: opts.parentSpaceId,
+    });
+    if (opts.parentSpaceId) {
+      await this.addToSpace(opts.parentSpaceId, room_id);
+    }
+    return room_id;
+  }
+
+  /**
+   * Create the account if absent (no password — this deployment is JWT-SSO
+   * only), or no-op if it already exists. Needed before force-joining a
+   * position holder who has never clicked "Chat": accounts are otherwise
+   * only created lazily on first JWT login, and the admin join API 404s
+   * ("User not found") on an account that doesn't exist yet.
+   */
+  async ensureUser(userId: string, displayName?: string): Promise<void> {
+    const existing = await this.requestOrNull<{ name: string }>(
+      'GET',
+      `/_synapse/admin/v2/users/${encodeURIComponent(userId)}`,
+    );
+    if (existing) return;
+    await this.request(
+      'PUT',
+      `/_synapse/admin/v2/users/${encodeURIComponent(userId)}`,
+      displayName ? { displayname: displayName } : {},
+    );
+  }
+
+  /** Server-admin force-join — no invite to accept, works even mid-outage for the invitee. */
+  forceJoin(roomIdOrAlias: string, userId: string): Promise<void> {
+    return this.request(
+      'POST',
+      `/_synapse/admin/v1/join/${encodeURIComponent(roomIdOrAlias)}`,
+      { user_id: userId },
+    );
+  }
+
+  kick(roomId: string, userId: string, reason: string): Promise<void> {
+    return this.request(
+      'POST',
+      `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/kick`,
+      { user_id: userId, reason },
+    );
+  }
+
+  /** Deactivating (rather than just kicking) a leaver's account revokes all their sessions. */
+  deactivateUser(userId: string): Promise<void> {
+    return this.request(
+      'POST',
+      `/_synapse/admin/v1/deactivate/${encodeURIComponent(userId)}`,
+      { erase: false },
+    );
+  }
+
+  sendMessage(roomId: string, body: string, formattedBody?: string): Promise<void> {
+    const txnId = `edr-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    return this.request(
+      'PUT',
+      `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/send/m.room.message/${txnId}`,
+      formattedBody
+        ? {
+            msgtype: 'm.text',
+            body,
+            format: 'org.matrix.custom.html',
+            formatted_body: formattedBody,
+          }
+        : { msgtype: 'm.text', body },
+    );
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/notification-inbox/notification-inbox.module.ts b/apps/edr-freight-api/src/modules/notification-inbox/notification-inbox.module.ts
index e9f3af958..aa363ad3d 100644
--- a/apps/edr-freight-api/src/modules/notification-inbox/notification-inbox.module.ts
+++ b/apps/edr-freight-api/src/modules/notification-inbox/notification-inbox.module.ts
@@ -4,6 +4,7 @@ import { Session } from "@tria-plc/iamapi-common/entities/iam/user/session.entit
 import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
 
 import { BackofficeModule } from "../backoffice/backoffice.module";
+import { ChatModule } from "../chat/chat.module";
 import { CompaniesModule } from "../companies/companies.module";
 import { NotificationsModule } from "../notifications/notifications.module";
 import { Notification } from "./entities/notification.entity";
@@ -24,6 +25,8 @@ import { WsAuthService } from "./ws-auth.service";
     BackofficeModule,
     // EmailClientService + SmsClientService (HIGH-priority fan-out)
     NotificationsModule,
+    // ChatBridgeService (mirrors BACKOFFICE notifications into chat)
+    ChatModule,
   ],
   controllers: [NotificationInboxController],
   providers: [
diff --git a/apps/edr-freight-api/src/modules/notification-inbox/notification-inbox.service.ts b/apps/edr-freight-api/src/modules/notification-inbox/notification-inbox.service.ts
index 7cfbf81df..119019997 100644
--- a/apps/edr-freight-api/src/modules/notification-inbox/notification-inbox.service.ts
+++ b/apps/edr-freight-api/src/modules/notification-inbox/notification-inbox.service.ts
@@ -1,4 +1,5 @@
 import {
+  NotificationAudience,
   NotificationChannels,
   NotificationChannelsSent,
   NotificationDto,
@@ -11,6 +12,7 @@ import { InjectRepository } from "@nestjs/typeorm";
 import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
 import { Repository } from "typeorm";
 
+import { ChatBridgeService } from "../chat/chat-bridge.service";
 import { EmailClientService } from "../notifications/email-client.service";
 import { SmsClientService } from "../notifications/sms-client.service";
 import { ListNotificationsQueryDto } from "./dto/list-notifications-query.dto";
@@ -37,6 +39,7 @@ export class NotificationInboxService {
     private readonly gateway: NotificationsGateway,
     private readonly emailClient: EmailClientService,
     private readonly smsClient: SmsClientService,
+    private readonly chatBridge: ChatBridgeService,
     @InjectRepository(User)
     private readonly users: Repository<User>,
   ) {}
@@ -44,11 +47,18 @@ export class NotificationInboxService {
   /**
    * Fan a logical notification out to every resolved recipient: persist one row
    * each, push it live over WebSocket, and (for HIGH priority) also queue
-   * email/SMS via the existing clients.
+   * email/SMS via the existing clients. BACKOFFICE-audience notifications are
+   * also mirrored into internal chat (ChatBridgeService) — a shared-room
+   * broadcast, not per-recipient, so it runs once regardless of how many (if
+   * any) in-app rows get created below. Never PORTAL — that's customer-facing
+   * and must never reach a staff room.
    */
   async notify(input: NotifyInput): Promise<void> {
     try {
       const userIds = await this.recipients.resolve(input.recipients);
+      if (input.audience === NotificationAudience.BACKOFFICE) {
+        await this.chatBridge.bridge(input);
+      }
       if (userIds.length === 0) {
         this.logger.debug(
           `notify(${input.type}) resolved 0 recipients — skipped`,
diff --git a/apps/edr-freight-api/src/seed/edr-freight.seed.ts b/apps/edr-freight-api/src/seed/edr-freight.seed.ts
index 1798a8d5f..e4ab41954 100644
--- a/apps/edr-freight-api/src/seed/edr-freight.seed.ts
+++ b/apps/edr-freight-api/src/seed/edr-freight.seed.ts
@@ -242,6 +242,7 @@ export const EDR_FREIGHT_ROLES: FreightSeedRole[] = [
       "edr_freight_app:hierarchy_positions:view",
       "edr_freight_app:hierarchy_employee_assignment:view",
       "edr_freight_app:position_types:view",
+      "edr_freight_app:chat:view",
     ],
   },
   {
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 9e905df6d..4043430e2 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -523,6 +523,12 @@ export const SHIPPING_LINE_PERMISSIONS: FreightPermissionSeed[] = [
   ),
 ];
 
+// Internal chat (Matrix/Element) — sidebar visibility + manual reconcile trigger.
+export const CHAT_PERMISSIONS: FreightPermissionSeed[] = [
+  perm('c9a00001-0001-4000-8000-000000000001', 'edr_freight_app:chat:view', 'Open internal chat'),
+  perm('c9a00001-0001-4000-8000-000000000002', 'edr_freight_app:chat:sync', 'Re-run chat room/membership sync'),
+];
+
 // D. Finance — payments + invoices
 export const FINANCE_PERMISSIONS: FreightPermissionSeed[] = [
   perm(
@@ -1641,6 +1647,7 @@ export const ADVANCED_BACKOFFICE_PERMISSIONS: FreightPermissionSeed[] = [
   ...REPORT_PERMISSIONS,
   ...CUSTOMER_PERMISSIONS,
   ...SHIPPING_LINE_PERMISSIONS,
+  ...CHAT_PERMISSIONS,
   ...FINANCE_PERMISSIONS,
   ...MILE_PERMISSIONS,
   ...FLEET_RAIL_PERMISSIONS,
@@ -1872,6 +1879,10 @@ export const FREIGHT_PERMS = {
     /** Reject any pending invoice request. */
     invoiceReject: "edr_freight_app:shipping_line_credits:invoice_reject",
   },
+  chat: {
+    view: 'edr_freight_app:chat:view',
+    sync: 'edr_freight_app:chat:sync',
+  },
   payments: {
     view: "edr_freight_app:payments:view",
   },
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index 9ac730bda..2ea1c1890 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -115,6 +115,7 @@ import FaydaCallbackPage from "./pages/FaydaCallbackPage";
 import { UserManagementRoutes } from "./user-management/route";
 import SetPassword from "./shared/components/SetPassword";
 import SupportInboxPage from "./pages/support/SupportInboxPage";
+import ChatLaunchPage from "./pages/chat/ChatLaunchPage";
 import {
   APP_TITLE,
   buildSidebarSections,
@@ -298,6 +299,14 @@ const App = () => {
             </RequirePermission>
           }
         />
+        <Route
+          path="chat"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.chat.view}>
+              <ChatLaunchPage />
+            </RequirePermission>
+          }
+        />
         <Route
           path="customers"
           element={
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts b/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts
index 636310e38..691040c0a 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts
+++ b/apps/edr-freight-web/backoffice/src/components/layout/route-meta.ts
@@ -71,6 +71,13 @@ const ROUTE_META: Array<{ prefix: string; meta: PageMeta }> = [
       subtitle: "Manage your account and signature",
     },
   },
+  {
+    prefix: "/dashboard/chat",
+    meta: {
+      title: "Chat",
+      subtitle: "Internal messaging for EDR staff",
+    },
+  },
   {
     // Invoices, Payments, and USD Payments are tabs on one page now
     // (FinanceHubPage); the header title itself is set per-tab there.
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 293e82450..301bf6939 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -32,6 +32,7 @@ import {
   Users,
   Wallet,
   LifeBuoy,
+  MessageSquare,
   TrainFront,
   XCircle,
 } from "lucide-react";
@@ -124,6 +125,12 @@ export const buildSidebarSections = (
           icon: <LifeBuoy />,
           permission: FREIGHT_PERMS.support.agentView,
         },
+        {
+          label: "Chat",
+          href: "/dashboard/chat",
+          icon: <MessageSquare />,
+          permission: FREIGHT_PERMS.chat.view,
+        },
         ...demoItems,
       ],
     },
diff --git a/apps/edr-freight-web/backoffice/src/features/chat/chatApi.ts b/apps/edr-freight-web/backoffice/src/features/chat/chatApi.ts
new file mode 100644
index 000000000..65522aafd
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/features/chat/chatApi.ts
@@ -0,0 +1,13 @@
+import { api } from "@/auth/http";
+
+/**
+ * Internal chat (Matrix/Element) REST calls. Just the one endpoint — Chat
+ * itself is a separate app (chat.edr.et); this backoffice only ever asks for
+ * a fresh sign-in link into it.
+ */
+export const chatApi = {
+  getSsoUrl: async (): Promise<string> => {
+    const { data } = await api.get<{ url: string }>("/chat/sso");
+    return data.url;
+  },
+};
diff --git a/apps/edr-freight-web/backoffice/src/features/chat/useChatSso.ts b/apps/edr-freight-web/backoffice/src/features/chat/useChatSso.ts
new file mode 100644
index 000000000..d25b5f4a1
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/features/chat/useChatSso.ts
@@ -0,0 +1,19 @@
+import { useQuery } from "@tanstack/react-query";
+
+import { chatApi } from "./chatApi";
+
+export const CHAT_SSO_KEY = ["chat", "sso"] as const;
+
+/**
+ * The login_token this resolves to is single-use and expires in 5 minutes
+ * (Synapse default) — the global `staleTime: 0` (queryClient.ts) already
+ * means every fresh mount of the launch page refetches rather than reusing
+ * a possibly-spent link.
+ */
+export function useChatSso() {
+  return useQuery({
+    queryKey: CHAT_SSO_KEY,
+    queryFn: chatApi.getSsoUrl,
+    retry: false,
+  });
+}
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index fe4d4fff9..b2797fa59 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -33,6 +33,10 @@ export const FREIGHT_PERMS = {
   staffUsers: {
     view: "edr_freight_app:staff:users:view",
   },
+  chat: {
+    view: "edr_freight_app:chat:view",
+    sync: "edr_freight_app:chat:sync",
+  },
   bookings: {
     view: "edr_freight_app:bookings:view",
     create: "edr_freight_app:bookings:create",
diff --git a/apps/edr-freight-web/backoffice/src/pages/chat/ChatLaunchPage.tsx b/apps/edr-freight-web/backoffice/src/pages/chat/ChatLaunchPage.tsx
new file mode 100644
index 000000000..6b51b6512
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/chat/ChatLaunchPage.tsx
@@ -0,0 +1,62 @@
+import { Alert, Button, Card, Center, Loader, Stack, Text } from "@mantine/core";
+import { MessageSquare, TriangleAlert } from "lucide-react";
+
+import { PageContainer, PageHeader } from "@/components/page";
+import { useChatSso } from "@/features/chat/useChatSso";
+
+/**
+ * Chat itself lives at chat.edr.et (Element), not in this app — this page's
+ * only job is a fresh one-click sign-in link into it. A real `<a>` (not
+ * `window.open()` in a click handler) so the browser never treats it as a
+ * blocked popup, and no iframe: Element's own CSP refuses to be framed.
+ */
+export default function ChatLaunchPage() {
+  const { data: url, isLoading, isError, refetch } = useChatSso();
+
+  return (
+    <PageContainer>
+      <PageHeader title="Chat" subtitle="Internal messaging for EDR staff" />
+      <Card withBorder radius="md" p="xl">
+        <Center>
+          <Stack align="center" gap="md" py="xl">
+            {isLoading && <Loader />}
+
+            {isError && (
+              <Stack align="center" gap="sm">
+                <Alert
+                  icon={<TriangleAlert size={18} />}
+                  color="red"
+                  title="Couldn't get a sign-in link"
+                  variant="light"
+                >
+                  Something went wrong reaching chat. Try again.
+                </Alert>
+                <Button variant="light" onClick={() => refetch()}>
+                  Retry
+                </Button>
+              </Stack>
+            )}
+
+            {url && (
+              <Stack align="center" gap="sm">
+                <MessageSquare size={40} strokeWidth={1.5} />
+                <Text c="dimmed" ta="center" maw={360}>
+                  Opens EDR Chat in a new tab, already signed in as you.
+                </Text>
+                <Button
+                  component="a"
+                  href={url}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  leftSection={<MessageSquare size={16} />}
+                >
+                  Open EDR Chat
+                </Button>
+              </Stack>
+            )}
+          </Stack>
+        </Center>
+      </Card>
+    </PageContainer>
+  );
+}
diff --git a/docker-compose.yaml b/docker-compose.yaml
index 5d5faa2de..050afc5df 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -116,3 +116,31 @@ services:
     env_file:
       - apps/edr-payment-api/.env
     restart: always
+
+  # Internal employee chat (freight backoffice). No federation, no public
+  # registration — see infrastructure/matrix/synapse/homeserver.yaml.tmpl.
+  synapse:
+    build:
+      context: infrastructure/matrix/synapse
+    ports:
+      - "${SYNAPSE_PORT:-8008}:8008"
+    env_file:
+      - infrastructure/matrix/synapse/.env
+    volumes:
+      - matrix-data:/data
+    # Local dev: Postgres runs in the separate docker-compose.db.dev.yml
+    # project (different docker network) and is only reachable from here via
+    # the host's published port — see MATRIX_DB_HOST in synapse/.env.example.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: always
+
+  element-web:
+    build:
+      context: infrastructure/matrix/element
+    ports:
+      - "${ELEMENT_WEB_PORT:-8080}:80"
+    restart: always
+
+volumes:
+  matrix-data:
diff --git a/infrastructure/matrix/element/Dockerfile b/infrastructure/matrix/element/Dockerfile
new file mode 100644
index 000000000..5ab02cd9b
--- /dev/null
+++ b/infrastructure/matrix/element/Dockerfile
@@ -0,0 +1,9 @@
+# syntax=docker/dockerfile:1
+#
+# EDR internal chat web client. Unmodified upstream Element Web + our public,
+# non-secret config (homeserver URL, branding) and the SSO handoff page.
+# Pin the tag; never float on `latest`.
+FROM ghcr.io/element-hq/element-web:v1.11.108
+
+COPY config.json /app/config.json
+COPY sso.html /app/sso.html
diff --git a/infrastructure/matrix/element/config.json b/infrastructure/matrix/element/config.json
new file mode 100644
index 000000000..6f988d3e9
--- /dev/null
+++ b/infrastructure/matrix/element/config.json
@@ -0,0 +1,17 @@
+{
+  "default_server_config": {
+    "m.homeserver": {
+      "base_url": "https://matrix.edr.et",
+      "server_name": "matrix.edr.et"
+    }
+  },
+  "brand": "EDR Chat",
+  "permalink_prefix": "https://chat.edr.et",
+  "disable_guests": true,
+  "disable_3pid_login": true,
+  "disable_custom_urls": true,
+  "default_theme": "light",
+  "settingDefaults": {
+    "UIFeature.registration": false
+  }
+}
diff --git a/infrastructure/matrix/element/sso.html b/infrastructure/matrix/element/sso.html
new file mode 100644
index 000000000..59a458fa4
--- /dev/null
+++ b/infrastructure/matrix/element/sso.html
@@ -0,0 +1,36 @@
+<!doctype html>
+<!--
+  Element only honours a `?loginToken=` on `/` if `mx_sso_hs_url` is already
+  in localStorage (element-web apps/web/src/Lifecycle.ts attemptTokenLogin,
+  key defined in apps/web/src/BasePlatform.ts). Normally that key is written
+  by Element itself at the start of an SSO redirect; freight-api's SSO
+  handoff skips that redirect (it already knows the homeserver), so this
+  page seeds the key by hand and forwards straight to the login-token URL.
+
+  freight-api's chat-sso.service.ts links here as
+  https://chat.edr.et/sso.html?t=<login_token>&hs=<homeserver base_url>.
+  `hs` is passed rather than hardcoded so this file doesn't need to change if
+  MATRIX_PUBLIC_BASEURL ever does.
+-->
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Signing in to EDR Chat…</title>
+  </head>
+  <body>
+    <script>
+      var params = new URLSearchParams(window.location.search);
+      var token = params.get("t");
+      var homeserver = params.get("hs");
+      if (token && homeserver) {
+        localStorage.setItem("mx_sso_hs_url", homeserver);
+        window.location.replace(
+          "/?loginToken=" + encodeURIComponent(token),
+        );
+      } else {
+        document.body.textContent =
+          "Missing sign-in token. Go back to the EDR backoffice and click Chat again.";
+      }
+    </script>
+  </body>
+</html>
diff --git a/infrastructure/matrix/synapse/Dockerfile b/infrastructure/matrix/synapse/Dockerfile
new file mode 100644
index 000000000..ec424e41f
--- /dev/null
+++ b/infrastructure/matrix/synapse/Dockerfile
@@ -0,0 +1,15 @@
+# syntax=docker/dockerfile:1
+#
+# EDR internal chat homeserver. Unmodified upstream Synapse + our config
+# template — no source build. Pin the tag; never float on `latest`.
+FROM ghcr.io/element-hq/synapse:v1.140.0
+
+RUN apt-get update && apt-get install -y --no-install-recommends gettext-base \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY homeserver.yaml.tmpl /synapse/homeserver.yaml.tmpl
+COPY log.config /synapse/log.config
+COPY docker-entrypoint.sh /synapse/docker-entrypoint.sh
+RUN chmod +x /synapse/docker-entrypoint.sh
+
+ENTRYPOINT ["/synapse/docker-entrypoint.sh"]
diff --git a/infrastructure/matrix/synapse/docker-entrypoint.sh b/infrastructure/matrix/synapse/docker-entrypoint.sh
new file mode 100644
index 000000000..674bf7947
--- /dev/null
+++ b/infrastructure/matrix/synapse/docker-entrypoint.sh
@@ -0,0 +1,20 @@
+#!/bin/sh
+# Renders homeserver.yaml from the template using the runtime env (so
+# MATRIX_JWT_SECRET / DB password / registration_shared_secret come from the
+# service's .env file, never get baked into the image), then hands off to the
+# upstream Synapse image's own entrypoint.
+set -eu
+
+mkdir -p /data
+envsubst \
+  '${MATRIX_SERVER_NAME} ${MATRIX_PUBLIC_BASEURL} ${MATRIX_DB_USER} ${MATRIX_DB_PASSWORD} ${MATRIX_DB_NAME} ${MATRIX_DB_HOST} ${MATRIX_DB_PORT} ${MATRIX_JWT_SECRET} ${MATRIX_REGISTRATION_SHARED_SECRET}' \
+  < /synapse/homeserver.yaml.tmpl > /data/homeserver.yaml
+
+# start.py's `run` mode (the implicit default we hit below) gosu's straight
+# into uid 991 with no chown — it only chowns /data in its `generate` /
+# `migrate_config` modes, which we skip by providing our own pre-rendered
+# config. Without this, 991 can't write its signing key on first boot.
+chown -R 991:991 /data
+
+export SYNAPSE_CONFIG_PATH=/data/homeserver.yaml
+exec /start.py "$@"
diff --git a/infrastructure/matrix/synapse/homeserver.yaml.tmpl b/infrastructure/matrix/synapse/homeserver.yaml.tmpl
new file mode 100644
index 000000000..2f7d59502
--- /dev/null
+++ b/infrastructure/matrix/synapse/homeserver.yaml.tmpl
@@ -0,0 +1,95 @@
+# EDR internal chat — Synapse homeserver config.
+#
+# Rendered to /data/homeserver.yaml at container start by docker-entrypoint.sh
+# (envsubst over this template) so secrets come from the runtime env file,
+# never baked into the image — same convention as freight-api's .env.
+#
+# server_name is PERMANENT: it is baked into every user id and event and
+# cannot change without wiping the server. Do not repoint this at a
+# different value after go-live.
+server_name: "${MATRIX_SERVER_NAME}"
+public_baseurl: "${MATRIX_PUBLIC_BASEURL}"
+pid_file: /data/homeserver.pid
+
+listeners:
+  - port: 8008
+    tls: false
+    type: http
+    x_forwarded: true
+    resources:
+      - names: [client, federation]
+        compress: false
+
+database:
+  name: psycopg2
+  args:
+    user: "${MATRIX_DB_USER}"
+    password: "${MATRIX_DB_PASSWORD}"
+    dbname: "${MATRIX_DB_NAME}"
+    host: "${MATRIX_DB_HOST}"
+    port: ${MATRIX_DB_PORT}
+    cp_min: 5
+    cp_max: 10
+
+media_store_path: /data/media_store
+max_upload_size: 50M
+
+log_config: "/synapse/log.config"
+
+# Internal comms tool: no federation, no open registration, no E2EE-by-default.
+# ponytail: E2EE off — turn on per-room (HR/legal) if compliance asks.
+federation_domain_whitelist: []
+enable_registration: false
+encryption_enabled_by_default_for_room_type: "off"
+
+# Employees authenticate via freight-api's SSO handoff, never a Matrix
+# password prompt. This is the entire auth story for this deployment.
+password_config:
+  enabled: false
+
+jwt_config:
+  enabled: true
+  secret: "${MATRIX_JWT_SECRET}"
+  algorithm: "HS256"
+  issuer: "edr-freight-api"
+  audiences: ["matrix"]
+  # Matches the `name` claim chat-sso.service.ts puts in the JWT — only read
+  # on first login (auto-registration), never updates it on later logins.
+  display_name_claim: "name"
+
+# Consumes the login_token minted by freight-api's SSO endpoint via
+# POST /_matrix/client/v1/login/get_token (issued against an existing,
+# already-JWT-authenticated session — not a bare password grant).
+login_via_existing_session:
+  enabled: true
+  require_ui_auth: false
+  token_timeout: 5m
+
+# Bootstrap-only: used once by ops to register the first admin account
+# (register_new_matrix_user against /_synapse/admin/v1/register), whose
+# access token becomes MATRIX_ADMIN_TOKEN for freight-api's provisioning
+# service. Rotate/remove after bootstrap if desired — nothing else depends
+# on shared-secret registration once the admin account exists.
+registration_shared_secret: "${MATRIX_REGISTRATION_SHARED_SECRET}"
+
+trusted_key_servers: []
+suppress_key_server_warning: true
+
+report_stats: false
+
+# Synapse's default rc_login is sized to defend against internet-facing
+# password brute-forcing. That threat doesn't exist on this deployment —
+# password login is off (see password_config above), and the only path in
+# requires a freight-api-signed JWT — so the default is mostly just
+# punishing legitimate rapid logins from the same office/NAT IP or normal
+# page-refresh retries. Loosened, not disabled, to keep some ceiling.
+rc_login:
+  address:
+    per_second: 100
+    burst_count: 200
+  account:
+    per_second: 100
+    burst_count: 200
+  failed_attempts:
+    per_second: 100
+    burst_count: 200
diff --git a/infrastructure/matrix/synapse/log.config b/infrastructure/matrix/synapse/log.config
new file mode 100644
index 000000000..0894e974f
--- /dev/null
+++ b/infrastructure/matrix/synapse/log.config
@@ -0,0 +1,25 @@
+# Log straight to stdout — the container runtime (docker compose logs / the
+# self-hosted runner's log collection) owns rotation and retention, matching
+# how every other app container in this repo logs.
+version: 1
+
+formatters:
+  precise:
+    format: "%(asctime)s - %(name)s - %(lineno)d - %(levelname)s - %(message)s"
+
+handlers:
+  console:
+    class: logging.StreamHandler
+    formatter: precise
+    stream: ext://sys.stdout
+
+loggers:
+  synapse.storage.SQL:
+    # SQL queries are DEBUG-only noise; leave at INFO unless diagnosing.
+    level: INFO
+
+root:
+  level: INFO
+  handlers: [console]
+
+disable_existing_loggers: false
diff --git a/scripts/deploy/sync-env-from-server.sh b/scripts/deploy/sync-env-from-server.sh
index 69f7eef56..1e9a1ff52 100644
--- a/scripts/deploy/sync-env-from-server.sh
+++ b/scripts/deploy/sync-env-from-server.sh
@@ -31,6 +31,11 @@ declare -A SERVICE_ENV_TARGET=(
   ["passenger-portal"]="apps/edr-passenger-web/portal/.env"
   ["passenger-backoffice"]="apps/edr-passenger-web/backoffice/.env"
   ["payment-api"]="apps/edr-payment-api/.env"
+  ["synapse"]="infrastructure/matrix/synapse/.env"
+  # element-web has no runtime secrets (its config.json is baked into the
+  # image), but the sync step still runs unconditionally per service and
+  # needs a PORT= line to compute ELEMENT_WEB_PORT for docker compose.
+  ["element-web"]="infrastructure/matrix/element/.env"
 )
 
 for service in "$@"; do

From 1ca777614372831303dc0a55696736d2aa02ebc0 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Mon, 17 Aug 2026 09:13:09 +0000
Subject: [PATCH 129/174] Enhance manual payment processing for USD and ETB
 invoices

- Updated API documentation and summaries to reflect support for both USD and ETB invoices.
- Modified data structures to include trade direction for invoices.
- Adjusted UI components to accommodate manual payment confirmations and display relevant information.
- Implemented filtering options for currency in the manual payments worklist.
---
 .../src/modules/billing/billing.controller.ts |   4 +-
 .../src/modules/billing/billing.service.ts    |  84 ++++++--
 .../modules/billing/dto/filter-invoice.dto.ts |   7 +
 .../src/seed/freight-permissions.registry.ts  |   2 +
 apps/edr-freight-web/backoffice/src/App.tsx   |   4 +-
 .../src/pages/invoices/FinanceHubPage.tsx     |   6 +-
 .../src/pages/invoices/UsdPaymentsPage.tsx    | 197 +++++++++++++-----
 .../src/services/invoices.service.ts          |   4 +-
 .../backoffice/src/types/invoice.ts           |  12 +-
 9 files changed, 242 insertions(+), 78 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/billing/billing.controller.ts b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
index b0da6ac24..810c1a55a 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.controller.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
@@ -92,7 +92,7 @@ export class BillingController {
   @Get("offline-usd")
   @ApiOperation({
     summary:
-      "Finance worklist: USD invoices settled offline by bank transfer, with booking pay-window context",
+      "Finance worklist: USD and ETB invoices settled manually (bank transfer / counter), with booking pay-window context",
   })
   findOfflineUsd(@Query() query: FilterInvoiceDto) {
     return this.billingService.findOfflineUsdPaginated(query);
@@ -104,7 +104,7 @@ export class BillingController {
   @ApiConsumes("multipart/form-data")
   @ApiOperation({
     summary:
-      "Finance confirms a USD invoice paid by bank transfer — slip file required, settles the full balance",
+      "Finance confirms an invoice (USD or ETB) paid manually — slip file required, settles the full balance",
   })
   confirmOffline(
     @Param("id", ParseUUIDPipe) id: string,
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 0825ab6dc..44e194a8d 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -16,6 +16,7 @@ import { Booking } from "../bookings/entities/booking.entity";
 // Entity-only import (no module edge): portal reads resolve shipping-line
 // payers straight off the table.
 import { ShippingLineCompany } from "../shipping-lines/entities/shipping-line-company.entity";
+import { ShippingLineCredit } from "../shipping-lines/entities/shipping-line-credit.entity";
 import { EimsConfig } from "../../config/eims.config";
 import { CompaniesService } from "../companies/companies.service";
 import { EimsInvoiceStatus } from "../eims/eims-registration.types";
@@ -48,10 +49,18 @@ export interface PayInvoiceOptions {
 export interface OfflineUsdBookingInfo {
   id: string;
   reference: string;
+  tradeDirection: string | null;
   paymentDeadline: Date | null;
   paymentStatus: string;
 }
 
+/** Row shape of the manual-payments worklist. */
+export type OfflineUsdInvoiceRow = Invoice & {
+  booking: OfflineUsdBookingInfo | null;
+  /** Shipping-line credit invoices span many bookings — one entry per credit. */
+  bookings: { id: string; reference: string; tradeDirection: string | null }[];
+};
+
 /** A single manual/offline settlement to record against an invoice. */
 export interface RecordPaymentInput {
   /** Amount settled by this payment; must be > 0. */
@@ -340,22 +349,23 @@ export class BillingService {
   }
 
   /**
-   * Finance's offline-settlement worklist: USD invoices (paid by bank transfer,
-   * never through the gateway), open ones by default or a single status when
-   * filtered. Booking-sourced rows carry the booking's reference and pay-window
-   * deadline so the UI can show the countdown and link to the booking.
+   * Finance's manual-settlement worklist: USD invoices (paid by bank transfer,
+   * never through the gateway) and ETB invoices Finance settles by hand (bank
+   * transfer / counter) instead of the customer paying online. Open ones by
+   * default or a single status when filtered; both currencies unless
+   * `currency` narrows it. Booking-sourced rows carry the booking's reference,
+   * trade direction and pay-window deadline so the UI can show the countdown
+   * and link to the booking.
    */
   async findOfflineUsdPaginated(
     filter: {
       status?: Freight.InvoiceStatus;
       search?: string;
+      currency?: "USD" | "ETB";
       page?: number;
       pageSize?: number;
     } = {},
-  ): Promise<{
-    items: (Invoice & { booking: OfflineUsdBookingInfo | null })[];
-    total: number;
-  }> {
+  ): Promise<{ items: OfflineUsdInvoiceRow[]; total: number }> {
     const page = filter.page && filter.page > 0 ? filter.page : 1;
     const pageSize =
       filter.pageSize && filter.pageSize > 0 ? filter.pageSize : 20;
@@ -364,11 +374,16 @@ export class BillingService {
       .getRepository(Invoice)
       .createQueryBuilder("invoice")
       .leftJoinAndSelect("invoice.company", "company")
-      .where("UPPER(invoice.currency) = 'USD'")
+      .where("UPPER(invoice.currency) IN ('USD', 'ETB')")
       .orderBy("invoice.issuedAt", "DESC")
       .skip((page - 1) * pageSize)
       .take(pageSize);
 
+    if (filter.currency) {
+      qb.andWhere("UPPER(invoice.currency) = :currency", {
+        currency: filter.currency,
+      });
+    }
     if (filter.status) {
       qb.andWhere("invoice.status = :status", { status: filter.status });
     } else {
@@ -381,7 +396,8 @@ export class BillingService {
       );
     }
 
-    const [items, total] = await qb.getManyAndCount();
+    const [rawItems, total] = await qb.getManyAndCount();
+    const items = await this.attachShippingLineCompanies(rawItems);
 
     const bookingIds = items
       .filter((i) => i.source === "booking")
@@ -389,11 +405,43 @@ export class BillingService {
     const bookings = bookingIds.length
       ? await this.dataSource.getRepository(Booking).find({
           where: { id: In(bookingIds) },
-          select: ["id", "reference", "paymentDeadline", "paymentStatus"],
+          select: [
+            "id",
+            "reference",
+            "tradeDirection",
+            "paymentDeadline",
+            "paymentStatus",
+          ],
         })
       : [];
     const byId = new Map(bookings.map((b) => [b.id, b]));
 
+    // Shipping-line credit invoices bill many bookings at once; each credit
+    // keeps its own booking link, so collect them per invoice.
+    const creditInvoiceIds = items
+      .filter((i) => i.source === Freight.InvoiceSource.ShippingLineCredit)
+      .map((i) => i.id);
+    const credits = creditInvoiceIds.length
+      ? await this.dataSource.getRepository(ShippingLineCredit).find({
+          where: { invoiceId: In(creditInvoiceIds) },
+          relations: { booking: true },
+        })
+      : [];
+    const bookingsByInvoice = new Map<
+      string,
+      OfflineUsdInvoiceRow["bookings"]
+    >();
+    for (const c of credits) {
+      if (!c.invoiceId || !c.booking) continue;
+      const list = bookingsByInvoice.get(c.invoiceId) ?? [];
+      list.push({
+        id: c.booking.id,
+        reference: c.booking.reference,
+        tradeDirection: c.booking.tradeDirection ?? null,
+      });
+      bookingsByInvoice.set(c.invoiceId, list);
+    }
+
     return {
       items: items.map((inv) => {
         const b = byId.get(inv.sourceId);
@@ -403,19 +451,22 @@ export class BillingService {
             ? {
                 id: b.id,
                 reference: b.reference,
+                tradeDirection: b.tradeDirection ?? null,
                 paymentDeadline: b.paymentDeadline ?? null,
                 paymentStatus: b.paymentStatus,
               }
             : null,
-        } as Invoice & { booking: OfflineUsdBookingInfo | null };
+          bookings: bookingsByInvoice.get(inv.id) ?? [],
+        } as OfflineUsdInvoiceRow;
       }),
       total,
     };
   }
 
   /**
-   * Finance confirms a USD invoice as paid by bank transfer: stores the slip
-   * against the invoice and settles the FULL outstanding balance through
+   * Finance confirms an invoice (USD or ETB) as paid manually — bank transfer
+   * or counter payment: stores the slip against the invoice and settles the
+   * FULL outstanding balance through
    * {@link recordPayment}, which flips the invoice to PAID and (for bookings)
    * emits `booking.invoice.paid` — the same event an online payment fires, so
    * the booking advances exactly as if it had been paid through the gateway.
@@ -434,11 +485,6 @@ export class BillingService {
   ): Promise<Invoice> {
     const invoice = await this.invoices.findById(invoiceId);
     if (!invoice) throw new NotFoundException(`Invoice ${invoiceId} not found`);
-    if (invoice.currency?.toUpperCase() !== "USD") {
-      throw new BadRequestException(
-        "Offline confirmation is only for USD invoices — this invoice is paid online.",
-      );
-    }
     if (!file) {
       throw new BadRequestException("The bank payment slip file is required.");
     }
diff --git a/apps/edr-freight-api/src/modules/billing/dto/filter-invoice.dto.ts b/apps/edr-freight-api/src/modules/billing/dto/filter-invoice.dto.ts
index e8942d586..91327946c 100644
--- a/apps/edr-freight-api/src/modules/billing/dto/filter-invoice.dto.ts
+++ b/apps/edr-freight-api/src/modules/billing/dto/filter-invoice.dto.ts
@@ -39,4 +39,11 @@ export class FilterInvoiceDto {
   @IsOptional()
   @IsIn(Object.values(Freight.InvoiceStatus))
   status?: Freight.InvoiceStatus;
+
+  /** Manual-payments worklist only: restrict to one currency. */
+  @ApiPropertyOptional({ enum: ["USD", "ETB"] })
+  @IsOptional()
+  @Transform(({ value }: { value: unknown }) => String(value).toUpperCase())
+  @IsIn(["USD", "ETB"])
+  currency?: "USD" | "ETB";
 }
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 9e905df6d..24be04f66 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -2414,6 +2414,8 @@ export const ROLE_PERMISSION_PRESETS = {
     FREIGHT_PERMS.bookings.view,
     FREIGHT_PERMS.invoices.view,
     FREIGHT_PERMS.invoices.export,
+    // Manual settlement (bank transfer / counter) of USD and ETB invoices.
+    FREIGHT_PERMS.invoices.confirmOffline,
     // Deliberately NOT granted here: invoices:eims_register, eims_resolve, eims_cancel,
     // eims_receipt_register, eims:memo_issue. Automatic filing needs no human permission at all
     // (the cron sweep runs as the system); these are the *manual* exceptional-operations
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index 9ac730bda..c131af4bd 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -315,7 +315,7 @@ const App = () => {
           }
         />
         {/* Merged Invoices / Payments / USD Payments hub — tabs switch via
-            ?tab=invoices|payments|usd-payments (default invoices). Access is
+            ?tab=invoices|payments|manual-payments (default invoices). Access is
             OR'd across both keys so a user with just one still gets in; each
             tab hides itself if the user lacks the permission it used to be
             routed on. */}
@@ -352,7 +352,7 @@ const App = () => {
         />
         <Route
           path="usd-payments"
-          element={<Navigate to="/dashboard/invoices?tab=usd-payments" replace />}
+          element={<Navigate to="/dashboard/invoices?tab=manual-payments" replace />}
         />
         <Route
           path="invoices/:id"
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx
index 261889d0b..d5ac83987 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx
@@ -29,13 +29,13 @@ const TABS = [
     Panel: InvoicesPanel,
   },
   {
-    key: "usd-payments",
-    label: "USD Payments",
+    key: "manual-payments",
+    label: "Manual Payments",
     icon: Landmark,
     // Same gate as Invoices, not a dedicated key — mirrors the old route.
     permission: FREIGHT_PERMS.invoices.view,
     subtitle:
-      "USD invoices are paid by bank transfer. Upload the customer's slip and confirm the payment before the pay window closes.",
+      "Import and export invoices in USD or ETB that Finance settles by hand (bank transfer or counter). Upload the customer's slip and confirm the payment before the pay window closes.",
     Panel: UsdPaymentsPanel,
   },
 ] as const;
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx
index 85e7b21e3..93098ff32 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx
@@ -11,6 +11,7 @@ import {
   Stack,
   Text,
   TextInput,
+  Tooltip,
 } from "@mantine/core";
 import { useDebouncedValue } from "@mantine/hooks";
 import { useMutation, useQuery } from "@tanstack/react-query";
@@ -55,14 +56,19 @@ function formatRemaining(deadlineMs: number, now: number): string | null {
     : `${pad(hours)}:${pad(minutes)}:${pad(seconds)}`;
 }
 
-function PayWindowCell({ deadline }: { deadline: string | null }) {
+/** Ticks once a second while a deadline is set, so window state updates live. */
+function useNow(deadline: string | null): number {
   const [now, setNow] = useState(() => Date.now());
-
   useEffect(() => {
     if (!deadline) return;
     const interval = setInterval(() => setNow(Date.now()), 1000);
     return () => clearInterval(interval);
   }, [deadline]);
+  return now;
+}
+
+function PayWindowCell({ deadline }: { deadline: string | null }) {
+  const now = useNow(deadline);
 
   if (!deadline) {
     return (
@@ -88,13 +94,56 @@ function PayWindowCell({ deadline }: { deadline: string | null }) {
   );
 }
 
-/** True once the pay window has closed — the API refuses confirmation then. */
-function windowClosed(row: OfflineUsdInvoice): boolean {
-  const deadline = row.booking?.paymentDeadline;
-  return Boolean(deadline && new Date(deadline).getTime() <= Date.now());
+/**
+ * "Confirm paid" for one row. Booking invoices are only confirmable while the
+ * booking's pay window is open (the API refuses otherwise): no window yet →
+ * no button; window closed → button disabled with the reason, and it flips
+ * live the second the countdown hits zero. Non-booking invoices (warehouse,
+ * clearance…) have no window and stay confirmable.
+ */
+function ConfirmCell({
+  row,
+  onConfirm,
+}: {
+  row: OfflineUsdInvoice;
+  onConfirm: (row: OfflineUsdInvoice) => void;
+}) {
+  const deadline = row.booking?.paymentDeadline ?? null;
+  const now = useNow(deadline);
+
+  if (row.booking && !deadline) return null;
+  const closed = Boolean(deadline && new Date(deadline).getTime() <= now);
+
+  return (
+    <Tooltip
+      label="Pay window closed — the booking can no longer be confirmed as paid."
+      disabled={!closed}
+      withArrow
+    >
+      <span>
+        <Button
+          size="compact-sm"
+          color="edr-green"
+          leftSection={<CheckCircle2 size={14} />}
+          disabled={closed}
+          onClick={(e) => {
+            e.stopPropagation();
+            onConfirm(row);
+          }}
+        >
+          Confirm paid
+        </Button>
+      </span>
+    </Tooltip>
+  );
 }
 
-/** USD Payments tab body of `FinanceHubPage` — page chrome lives in the parent. */
+/**
+ * Manual Payments tab body of `FinanceHubPage` — page chrome lives in the
+ * parent. Lists open USD and ETB invoices (import and export alike) that
+ * Finance settles by hand; confirming records the payment the same way an
+ * online payment would, so the booking advances identically.
+ */
 export default function UsdPaymentsPanel() {
   const navigate = useNavigate();
   const { pagination, setPagination } = usePagination({ pageSize: 10 });
@@ -103,6 +152,7 @@ export default function UsdPaymentsPanel() {
   const [statusFilter, setStatusFilter] = useState<"" | Freight.InvoiceStatus>(
     "",
   );
+  const [currency, setCurrency] = useState<"" | "USD" | "ETB">("");
   const [confirming, setConfirming] = useState<OfflineUsdInvoice | null>(null);
   const [slip, setSlip] = useState<File | null>(null);
   const [reference, setReference] = useState("");
@@ -119,8 +169,15 @@ export default function UsdPaymentsPanel() {
       pageSize: pagination.pageSize,
       search: debouncedQuery,
       status: statusFilter || undefined,
+      currency: currency || undefined,
     }),
-    [pagination.pageIndex, pagination.pageSize, debouncedQuery, statusFilter],
+    [
+      pagination.pageIndex,
+      pagination.pageSize,
+      debouncedQuery,
+      statusFilter,
+      currency,
+    ],
   );
 
   const { data, isLoading, isError, refetch, isFetching } = useQuery(
@@ -170,7 +227,9 @@ export default function UsdPaymentsPanel() {
         header: "Customer",
         cell: ({ row }) => (
           <Text size="sm" c="edr-text" truncate maw={200}>
-            {row.original.company?.name ?? "—"}
+            {row.original.company?.name ??
+              row.original.shippingLineCompany?.name ??
+              "—"}
           </Text>
         ),
       },
@@ -179,6 +238,28 @@ export default function UsdPaymentsPanel() {
         header: "Booking",
         cell: ({ row }) => {
           const booking = row.original.booking;
+          const bookings = row.original.bookings ?? [];
+          if (!booking && bookings.length) {
+            // Shipping-line credit invoice: one link per billed booking.
+            return (
+              <Group gap={4} wrap="wrap" maw={280}>
+                {bookings.map((b) => (
+                  <Button
+                    key={b.id}
+                    variant="subtle"
+                    size="compact-xs"
+                    rightSection={<ExternalLink size={11} />}
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      navigate(`/dashboard/booking-requests/${b.id}`);
+                    }}
+                  >
+                    {b.reference}
+                  </Button>
+                ))}
+              </Group>
+            );
+          }
           if (!booking) {
             return (
               <Text size="sm" c="dimmed">
@@ -187,20 +268,41 @@ export default function UsdPaymentsPanel() {
             );
           }
           return (
-            <Button
-              variant="subtle"
-              size="compact-sm"
-              rightSection={<ExternalLink size={13} />}
-              onClick={(e) => {
-                e.stopPropagation();
-                navigate(`/dashboard/booking-requests/${booking.id}`);
-              }}
-            >
-              {booking.reference}
-            </Button>
+            <Group gap={6} wrap="nowrap">
+              <Button
+                variant="subtle"
+                size="compact-sm"
+                rightSection={<ExternalLink size={13} />}
+                onClick={(e) => {
+                  e.stopPropagation();
+                  navigate(`/dashboard/booking-requests/${booking.id}`);
+                }}
+              >
+                {booking.reference}
+              </Button>
+              {booking.tradeDirection && (
+                <Badge size="xs" variant="light" radius="sm" color="gray">
+                  {humanize(booking.tradeDirection)}
+                </Badge>
+              )}
+            </Group>
           );
         },
       },
+      {
+        id: "currency",
+        header: "Currency",
+        cell: ({ row }) => (
+          <Badge
+            size="sm"
+            variant="light"
+            radius="sm"
+            color={row.original.currency?.toUpperCase() === "USD" ? "blue" : "teal"}
+          >
+            {row.original.currency}
+          </Badge>
+        ),
+      },
       {
         id: "status",
         header: "Status",
@@ -239,22 +341,8 @@ export default function UsdPaymentsPanel() {
         header: "",
         meta: { headerClassName: "text-right", cellClassName: "text-right" },
         cell: ({ row }) => {
-          const paid = row.original.status === "PAID";
-          if (paid || !canConfirm) return null;
-          return (
-            <Button
-              size="compact-sm"
-              color="edr-green"
-              leftSection={<CheckCircle2 size={14} />}
-              disabled={windowClosed(row.original)}
-              onClick={(e) => {
-                e.stopPropagation();
-                setConfirming(row.original);
-              }}
-            >
-              Confirm paid
-            </Button>
-          );
+          if (row.original.status === "PAID" || !canConfirm) return null;
+          return <ConfirmCell row={row.original} onConfirm={setConfirming} />;
         },
       },
     ],
@@ -288,6 +376,20 @@ export default function UsdPaymentsPanel() {
                 style={{ flex: 1, minWidth: "240px" }}
                 radius="lg"
               />
+              <SegmentedControl
+                size="sm"
+                radius="md"
+                value={currency || "all"}
+                onChange={(v) => {
+                  setCurrency(v === "all" ? "" : (v as "USD" | "ETB"));
+                  setPagination((prev) => ({ ...prev, pageIndex: 0 }));
+                }}
+                data={[
+                  { label: "All", value: "all" },
+                  { label: "ETB", value: "ETB" },
+                  { label: "USD", value: "USD" },
+                ]}
+              />
               <SegmentedControl
                 size="sm"
                 radius="md"
@@ -318,7 +420,7 @@ export default function UsdPaymentsPanel() {
           </Box>
 
           <Box style={{ overflowX: "auto" }} w="100%">
-            <Box miw={1040}>
+            <Box miw={1160}>
               <DataTable
                 columns={columns}
                 data={rows}
@@ -326,13 +428,13 @@ export default function UsdPaymentsPanel() {
                 onRowClick={(row) => navigate(`/dashboard/invoices/${row.id}`)}
                 emptyMessage={
                   debouncedQuery
-                    ? "No USD invoices match your search."
-                    : "No USD invoices awaiting confirmation."
+                    ? "No invoices match your search."
+                    : "No invoices awaiting manual payment confirmation."
                 }
                 error={
                   isError
                     ? {
-                        message: "Failed to load USD invoices.",
+                        message: "Failed to load invoices.",
                         onRetry: () => void refetch(),
                       }
                     : undefined
@@ -361,7 +463,7 @@ export default function UsdPaymentsPanel() {
         opened={confirming !== null}
         onClose={closeConfirm}
         title={
-          <Text fw={700}>Confirm bank transfer payment</Text>
+          <Text fw={700}>Confirm manual payment</Text>
         }
         radius="md"
         size="md"
@@ -371,20 +473,21 @@ export default function UsdPaymentsPanel() {
             <Text size="sm" c="dimmed">
               Confirming settles {confirming.invoiceNumber} in full (
               {formatMoney(confirming.balanceAmount, confirming.currency)}) and
-              marks the booking as paid. Upload the customer&apos;s bank slip
-              first — this cannot be undone.
+              marks the booking as paid — exactly as if the customer had paid
+              online. Upload the customer&apos;s bank slip or receipt first —
+              this cannot be undone.
             </Text>
 
             <PhasedFileDropzone
-              label="Bank payment slip"
-              description="PDF or image of the customer's transfer slip."
+              label="Payment slip / receipt"
+              description="PDF or image of the customer's bank transfer slip or payment receipt."
               value={slip}
               onChange={setSlip}
             />
 
             <TextInput
-              label="Bank reference"
-              description="Optional — the transfer reference from the slip."
+              label="Payment reference"
+              description="Optional — the transfer or receipt reference from the slip."
               placeholder="e.g. FT24091234567"
               value={reference}
               onChange={(e) => setReference(e.target.value)}
diff --git a/apps/edr-freight-web/backoffice/src/services/invoices.service.ts b/apps/edr-freight-web/backoffice/src/services/invoices.service.ts
index cb4417bf0..8c39420ea 100644
--- a/apps/edr-freight-web/backoffice/src/services/invoices.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/invoices.service.ts
@@ -59,7 +59,7 @@ export const invoicesService = {
       .then((r) => r.data);
   },
 
-  /** Finance worklist: USD invoices awaiting bank-transfer confirmation. */
+  /** Finance worklist: USD and ETB invoices awaiting manual payment confirmation. */
   listOfflineUsd(
     filter: InvoiceListFilter,
   ): Promise<PaginatedOfflineUsdInvoices> {
@@ -70,7 +70,7 @@ export const invoicesService = {
       .then((r) => r.data);
   },
 
-  /** Confirm a USD invoice paid by bank transfer — the slip file is required. */
+  /** Confirm an invoice (USD or ETB) paid manually — the slip file is required. */
   confirmOffline(id: string, file: File, reference?: string): Promise<Invoice> {
     const body = new FormData();
     body.append("file", file);
diff --git a/apps/edr-freight-web/backoffice/src/types/invoice.ts b/apps/edr-freight-web/backoffice/src/types/invoice.ts
index 696a403ee..a266a6257 100644
--- a/apps/edr-freight-web/backoffice/src/types/invoice.ts
+++ b/apps/edr-freight-web/backoffice/src/types/invoice.ts
@@ -13,6 +13,8 @@ export interface InvoiceListFilter {
   companyId?: string;
   status?: Freight.InvoiceStatus;
   search?: string;
+  /** Manual-payments worklist only. */
+  currency?: "USD" | "ETB";
 }
 
 /** Standard paginated list envelope (matches the customers/bookings service shape). */
@@ -22,17 +24,21 @@ export interface PaginatedInvoices {
 }
 
 /**
- * A USD invoice on Finance's offline-settlement worklist. Booking-sourced rows
- * carry the shipment's pay-window deadline so the list can show the same
- * countdown the customer sees — Finance must confirm before it closes.
+ * A USD or ETB invoice on Finance's manual-settlement worklist. Booking-sourced
+ * rows carry the shipment's trade direction and pay-window deadline so the list
+ * can show the same countdown the customer sees — Finance must confirm before
+ * it closes.
  */
 export interface OfflineUsdInvoice extends Invoice {
   booking: {
     id: string;
     reference: string;
+    tradeDirection: string | null;
     paymentDeadline: string | null;
     paymentStatus: string;
   } | null;
+  /** Shipping-line credit invoices span many bookings — one entry per credit. */
+  bookings: { id: string; reference: string; tradeDirection: string | null }[];
 }
 
 export interface PaginatedOfflineUsdInvoices {

From 4a4b1981cb39042d7c5797d65f5bbaac294a04a7 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 17 Aug 2026 09:14:38 +0000
Subject: [PATCH 130/174] feat(eims): allow private key/cert as inline base64
 env vars
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

EIMS_PRIVATE_KEY_BASE64 / EIMS_CERTIFICATE_BASE64, alternative to the
existing _PATH vars. Wins over the path when set; falls back to the
file otherwise. Neither var required at boot on its own — the
either/or check moved out of the flat REQUIRED_VARS list.

Lets a dockerized deployment receive the key/cert the same way it
already receives every other EIMS_* secret (plain env var into the
container) instead of needing a host bind mount into the container
filesystem.
---
 .../edr-freight-api/src/config/eims.config.ts | 31 ++++++++++++-----
 .../modules/eims/eims-credentials.provider.ts | 33 ++++++++++++++-----
 .../modules/eims/eims-signer.service.spec.ts  | 26 +++++++++++++--
 .../src/modules/eims/eims-test-fixtures.ts    |  2 ++
 4 files changed, 72 insertions(+), 20 deletions(-)

diff --git a/apps/edr-freight-api/src/config/eims.config.ts b/apps/edr-freight-api/src/config/eims.config.ts
index c5565cbc1..7091c52ef 100644
--- a/apps/edr-freight-api/src/config/eims.config.ts
+++ b/apps/edr-freight-api/src/config/eims.config.ts
@@ -30,6 +30,14 @@ export interface EimsConfig {
   privateKeyPath: string;
   /** Filesystem path to the INSA-issued certificate bundle; sent as base64 of its exact bytes. */
   certificatePath: string;
+  /**
+   * Inline alternative to `privateKeyPath` — the key file's own bytes, base64-encoded, so a
+   * container that can't be given a host bind mount can still receive it as a plain env var.
+   * Takes precedence over the path when set. Either one must be present when EIMS is enabled.
+   */
+  privateKeyBase64: string;
+  /** Inline alternative to `certificatePath`, same precedence rule. */
+  certificateBase64: string;
   httpTimeoutMs: number;
   /** Re-authenticate this many ms before the access token actually expires. */
   tokenSkewMs: number;
@@ -135,14 +143,14 @@ export interface EimsInvoiceConfig {
   buyerIdNumber: string | null;
 }
 
-const REQUIRED_VARS = [
-  "EIMS_CLIENT_ID",
-  "EIMS_CLIENT_SECRET",
-  "EIMS_API_KEY",
-  "EIMS_TIN",
-  "EIMS_PRIVATE_KEY_PATH",
-  "EIMS_CERTIFICATE_PATH",
-] as const;
+const REQUIRED_VARS = ["EIMS_CLIENT_ID", "EIMS_CLIENT_SECRET", "EIMS_API_KEY", "EIMS_TIN"] as const;
+
+// Key/cert each have two ways in (file path or inline base64) — checked separately from
+// REQUIRED_VARS since it's "at least one of", not "this exact var".
+const REQUIRED_EITHER_OR: Array<[string, string]> = [
+  ["EIMS_PRIVATE_KEY_PATH", "EIMS_PRIVATE_KEY_BASE64"],
+  ["EIMS_CERTIFICATE_PATH", "EIMS_CERTIFICATE_BASE64"],
+];
 
 const positiveInt = (raw: string | undefined, fallback: number, name: string): number => {
   if (raw === undefined || raw === "") return fallback;
@@ -189,6 +197,8 @@ export default registerAs("eims", (): EimsConfig => {
     systemType: process.env.EIMS_SYSTEM_TYPE ?? "",
     privateKeyPath: process.env.EIMS_PRIVATE_KEY_PATH ?? "",
     certificatePath: process.env.EIMS_CERTIFICATE_PATH ?? "",
+    privateKeyBase64: process.env.EIMS_PRIVATE_KEY_BASE64 ?? "",
+    certificateBase64: process.env.EIMS_CERTIFICATE_BASE64 ?? "",
     httpTimeoutMs,
     tokenSkewMs,
     autoSubmit: (process.env.EIMS_AUTO_SUBMIT ?? "false").toLowerCase() === "true",
@@ -245,7 +255,10 @@ export default registerAs("eims", (): EimsConfig => {
 
   if (!enabled) return base;
 
-  const missing = REQUIRED_VARS.filter((name) => !process.env[name]);
+  const missing: string[] = REQUIRED_VARS.filter((name) => !process.env[name]);
+  for (const [pathVar, base64Var] of REQUIRED_EITHER_OR) {
+    if (!process.env[pathVar] && !process.env[base64Var]) missing.push(`${pathVar} or ${base64Var}`);
+  }
   if (missing.length > 0) {
     throw new Error(
       `EIMS integration is enabled (EIMS_ENABLED=true) but the following env vars are missing: ${missing.join(", ")}`,
diff --git a/apps/edr-freight-api/src/modules/eims/eims-credentials.provider.ts b/apps/edr-freight-api/src/modules/eims/eims-credentials.provider.ts
index b68a4a32f..18725df37 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-credentials.provider.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-credentials.provider.ts
@@ -24,25 +24,31 @@ export class EimsCredentialsProvider {
     return this.config.get<EimsConfig>("eims")!;
   }
 
-  /** RSA private key, parsed once. Throws a config error if the path is missing or unusable. */
+  /**
+   * RSA private key, parsed once. `privateKeyBase64` wins when set (no file I/O at all — for a
+   * container that can't be given a host bind mount); otherwise falls back to `privateKeyPath`.
+   * Throws a config error if neither is usable.
+   */
   getPrivateKey(): KeyObject {
     if (this.privateKey) return this.privateKey;
 
-    const path = this.cfg.privateKeyPath;
-    if (!path) throw new EimsConfigException("EIMS_PRIVATE_KEY_PATH is not set");
+    const { privateKeyBase64, privateKeyPath: path } = this.cfg;
+    const source = privateKeyBase64 ? "EIMS_PRIVATE_KEY_BASE64" : `EIMS_PRIVATE_KEY_PATH (${path})`;
+    if (!privateKeyBase64 && !path) throw new EimsConfigException("EIMS_PRIVATE_KEY_PATH is not set");
 
     let key: KeyObject;
     try {
-      key = createPrivateKey(readFileSync(path));
+      const bytes = privateKeyBase64 ? Buffer.from(privateKeyBase64, "base64") : readFileSync(path);
+      key = createPrivateKey(bytes);
     } catch (err) {
-      // The path is operational information, not a secret; the key material never appears.
+      // The source is operational information, not a secret; the key material never appears.
       throw new EimsConfigException(
-        `EIMS private key at ${path} could not be read or parsed: ${(err as Error).message}`,
+        `EIMS private key from ${source} could not be read or parsed: ${(err as Error).message}`,
       );
     }
     if (key.asymmetricKeyType !== "rsa") {
       throw new EimsConfigException(
-        `EIMS private key at ${path} is ${key.asymmetricKeyType ?? "of unknown type"}; EIMS requires RSA`,
+        `EIMS private key from ${source} is ${key.asymmetricKeyType ?? "of unknown type"}; EIMS requires RSA`,
       );
     }
 
@@ -51,11 +57,20 @@ export class EimsCredentialsProvider {
     return key;
   }
 
-  /** Base64 of the certificate file's exact bytes. No parsing, no re-encoding. */
+  /**
+   * Base64 of the certificate file's exact bytes. No parsing, no re-encoding. `certificateBase64`
+   * config wins when set (already base64, used as-is); otherwise read from `certificatePath`.
+   */
   getCertificateBase64(): string {
     if (this.certificateBase64) return this.certificateBase64;
 
-    const path = this.cfg.certificatePath;
+    const { certificateBase64: inline, certificatePath: path } = this.cfg;
+    if (inline) {
+      this.certificateBase64 = inline;
+      this.logger.log(`EIMS certificate bundle loaded from EIMS_CERTIFICATE_BASE64`);
+      return this.certificateBase64;
+    }
+
     if (!path) throw new EimsConfigException("EIMS_CERTIFICATE_PATH is not set");
 
     let bytes: Buffer;
diff --git a/apps/edr-freight-api/src/modules/eims/eims-signer.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-signer.service.spec.ts
index 5e408ddf7..d2f190172 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-signer.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-signer.service.spec.ts
@@ -97,8 +97,12 @@ describe("EimsSignerService", () => {
 });
 
 describe("EimsCredentialsProvider", () => {
-  const providerFor = (paths: { privateKeyPath?: string; certificatePath?: string }) =>
-    new EimsCredentialsProvider({ get: () => paths } as unknown as ConfigService);
+  const providerFor = (cfg: {
+    privateKeyPath?: string;
+    certificatePath?: string;
+    privateKeyBase64?: string;
+    certificateBase64?: string;
+  }) => new EimsCredentialsProvider({ get: () => cfg } as unknown as ConfigService);
 
   it("fails clearly when the key path is unset", () => {
     expect(() => providerFor({}).getPrivateKey()).toThrow(/EIMS_PRIVATE_KEY_PATH is not set/);
@@ -115,4 +119,22 @@ describe("EimsCredentialsProvider", () => {
     writeFileSync(emptyPath, "");
     expect(() => providerFor({ certificatePath: emptyPath }).getCertificateBase64()).toThrow(/is empty/);
   });
+
+  it("loads the key from inline base64, no file involved", () => {
+    const keyBase64 = readFileSync(keyPath).toString("base64");
+    const key = providerFor({ privateKeyBase64: keyBase64 }).getPrivateKey();
+    expect(key.asymmetricKeyType).toBe("rsa");
+  });
+
+  it("prefers inline base64 over the path when both are set", () => {
+    const keyBase64 = readFileSync(keyPath).toString("base64");
+    // A path that would fail if it were ever actually read.
+    const key = providerFor({ privateKeyBase64: keyBase64, privateKeyPath: join(dir, "nope.key") }).getPrivateKey();
+    expect(key.asymmetricKeyType).toBe("rsa");
+  });
+
+  it("loads the certificate from inline base64 as-is, no re-encoding", () => {
+    const certBase64 = Buffer.from(CERTIFICATE_FIXTURE, "utf8").toString("base64");
+    expect(providerFor({ certificateBase64: certBase64 }).getCertificateBase64()).toBe(certBase64);
+  });
 });
diff --git a/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts b/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts
index 650a834b8..662436d50 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts
@@ -59,6 +59,8 @@ export const eimsConfig = (over: Partial<EimsConfig> = {}): EimsConfig => ({
   systemType: EIMS_SYSTEM_TYPE,
   privateKeyPath: "/dev/null",
   certificatePath: "/dev/null",
+  privateKeyBase64: "",
+  certificateBase64: "",
   httpTimeoutMs: 30_000,
   tokenSkewMs: 45_000,
   autoSubmit: false,

From 13f7bea590b914acd91b484c8b0b4dc4f52bd5df Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 17 Aug 2026 09:14:38 +0000
Subject: [PATCH 131/174] feat(eims): accept private key/cert as raw PEM env
 vars
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

EIMS_PRIVATE_KEY / EIMS_CERTIFICATE — the PEM text pasted directly,
no encode/decode step at all. Precedence: raw PEM > base64 > path.

Motivated by the base64 path hitting a DECODER::unsupported error in
a live deployment with no way to tell whether the cause was transport
truncation, double-encoding, or an actually-bad file. Two fixes for
that class of problem together:
  - the raw-PEM var removes the encode/decode step entirely, so
    there's nothing left to corrupt in transit
  - a literal \\n (two chars) is unescaped to a real newline, for
    env stores that can't hold a literal line break
  - getPrivateKey() now checks the decoded bytes look like a PEM
    header before handing them to OpenSSL, so a still-bad value fails
    with byte count + safe preview instead of an opaque decoder error
---
 .../src/config/eims.config.spec.ts            | 72 +++++++++++++++++++
 .../edr-freight-api/src/config/eims.config.ts | 37 +++++++---
 .../modules/eims/eims-credentials.provider.ts | 67 ++++++++++++++---
 .../modules/eims/eims-signer.service.spec.ts  | 32 +++++++++
 .../src/modules/eims/eims-test-fixtures.ts    |  2 +
 5 files changed, 191 insertions(+), 19 deletions(-)
 create mode 100644 apps/edr-freight-api/src/config/eims.config.spec.ts

diff --git a/apps/edr-freight-api/src/config/eims.config.spec.ts b/apps/edr-freight-api/src/config/eims.config.spec.ts
new file mode 100644
index 000000000..a6aa3895d
--- /dev/null
+++ b/apps/edr-freight-api/src/config/eims.config.spec.ts
@@ -0,0 +1,72 @@
+import eimsConfigFactory from "./eims.config";
+
+const REQUIRED = {
+  EIMS_ENABLED: "true",
+  EIMS_CLIENT_ID: "cid",
+  EIMS_CLIENT_SECRET: "secret",
+  EIMS_API_KEY: "apikey",
+  EIMS_TIN: "0000000000",
+};
+
+const withEnv = (vars: Record<string, string | undefined>, fn: () => void) => {
+  const prior: Record<string, string | undefined> = {};
+  for (const [key, value] of Object.entries(vars)) {
+    prior[key] = process.env[key];
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+  try {
+    fn();
+  } finally {
+    for (const [key, value] of Object.entries(prior)) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  }
+};
+
+describe("eims.config — private key / certificate resolution", () => {
+  it("unescapes a literal \\n when the PEM was pasted without real newlines", () => {
+    withEnv(
+      { ...REQUIRED, EIMS_PRIVATE_KEY: "line1\\nline2", EIMS_CERTIFICATE_PATH: "/dev/null" },
+      () => {
+        expect(eimsConfigFactory().privateKeyPem).toBe("line1\nline2");
+      },
+    );
+  });
+
+  it("leaves a PEM with real newlines untouched", () => {
+    withEnv(
+      { ...REQUIRED, EIMS_PRIVATE_KEY: "line1\nline2", EIMS_CERTIFICATE_PATH: "/dev/null" },
+      () => {
+        expect(eimsConfigFactory().privateKeyPem).toBe("line1\nline2");
+      },
+    );
+  });
+
+  it("throws naming all three key/cert options when none are set", () => {
+    withEnv(
+      {
+        ...REQUIRED,
+        EIMS_PRIVATE_KEY_PATH: undefined,
+        EIMS_PRIVATE_KEY_BASE64: undefined,
+        EIMS_PRIVATE_KEY: undefined,
+        EIMS_CERTIFICATE_PATH: "/dev/null",
+      },
+      () => {
+        expect(() => eimsConfigFactory()).toThrow(
+          /EIMS_PRIVATE_KEY_PATH or EIMS_PRIVATE_KEY_BASE64 or EIMS_PRIVATE_KEY/,
+        );
+      },
+    );
+  });
+
+  it("is satisfied by any single one of the three key options", () => {
+    withEnv(
+      { ...REQUIRED, EIMS_PRIVATE_KEY: "x", EIMS_CERTIFICATE_PATH: "/dev/null" },
+      () => {
+        expect(() => eimsConfigFactory()).not.toThrow();
+      },
+    );
+  });
+});
diff --git a/apps/edr-freight-api/src/config/eims.config.ts b/apps/edr-freight-api/src/config/eims.config.ts
index 7091c52ef..9d99ae455 100644
--- a/apps/edr-freight-api/src/config/eims.config.ts
+++ b/apps/edr-freight-api/src/config/eims.config.ts
@@ -33,11 +33,20 @@ export interface EimsConfig {
   /**
    * Inline alternative to `privateKeyPath` — the key file's own bytes, base64-encoded, so a
    * container that can't be given a host bind mount can still receive it as a plain env var.
-   * Takes precedence over the path when set. Either one must be present when EIMS is enabled.
+   * Either one must be present when EIMS is enabled. Precedence: `privateKeyPem` > `privateKeyBase64`
+   * > `privateKeyPath`.
    */
   privateKeyBase64: string;
-  /** Inline alternative to `certificatePath`, same precedence rule. */
+  /** Inline alternative to `certificatePath`, same precedence rule as the key. */
   certificateBase64: string;
+  /**
+   * The PEM key pasted directly into the env var, no encoding step at all — the most direct of the
+   * three inline forms, and the hardest for a broken transport step to mangle since there's no
+   * decode stage to get wrong. Wins over `privateKeyBase64`/`privateKeyPath` when set.
+   */
+  privateKeyPem: string;
+  /** Inline alternative to `certificateBase64`, same precedence rule. */
+  certificatePem: string;
   httpTimeoutMs: number;
   /** Re-authenticate this many ms before the access token actually expires. */
   tokenSkewMs: number;
@@ -145,11 +154,11 @@ export interface EimsInvoiceConfig {
 
 const REQUIRED_VARS = ["EIMS_CLIENT_ID", "EIMS_CLIENT_SECRET", "EIMS_API_KEY", "EIMS_TIN"] as const;
 
-// Key/cert each have two ways in (file path or inline base64) — checked separately from
-// REQUIRED_VARS since it's "at least one of", not "this exact var".
-const REQUIRED_EITHER_OR: Array<[string, string]> = [
-  ["EIMS_PRIVATE_KEY_PATH", "EIMS_PRIVATE_KEY_BASE64"],
-  ["EIMS_CERTIFICATE_PATH", "EIMS_CERTIFICATE_BASE64"],
+// Key/cert each have three ways in (file path, inline base64, or raw PEM) — checked separately
+// from REQUIRED_VARS since it's "at least one of", not "this exact var".
+const REQUIRED_ANY_OF: string[][] = [
+  ["EIMS_PRIVATE_KEY_PATH", "EIMS_PRIVATE_KEY_BASE64", "EIMS_PRIVATE_KEY"],
+  ["EIMS_CERTIFICATE_PATH", "EIMS_CERTIFICATE_BASE64", "EIMS_CERTIFICATE"],
 ];
 
 const positiveInt = (raw: string | undefined, fallback: number, name: string): number => {
@@ -171,6 +180,14 @@ const parseCodeMap = (raw: string | undefined): Record<string, string> => {
   return map;
 };
 
+// Some env stores (single-line .env files, certain secret managers) can't hold a literal newline
+// and expect the caller to write "\n" as two characters instead. If the raw value already has a
+// real newline, leave it alone; otherwise unescape "\n" so a PEM pasted that way still parses.
+const normalizePem = (raw: string | undefined): string => {
+  if (!raw) return "";
+  return raw.includes("\n") ? raw : raw.replace(/\\n/g, "\n");
+};
+
 /** Unset stays null so the registration-time check can name it; a set-but-bogus value throws. */
 const optionalNumber = (raw: string | undefined, name: string): number | null => {
   if (raw === undefined || raw === "") return null;
@@ -198,6 +215,8 @@ export default registerAs("eims", (): EimsConfig => {
     privateKeyPath: process.env.EIMS_PRIVATE_KEY_PATH ?? "",
     certificatePath: process.env.EIMS_CERTIFICATE_PATH ?? "",
     privateKeyBase64: process.env.EIMS_PRIVATE_KEY_BASE64 ?? "",
+    privateKeyPem: normalizePem(process.env.EIMS_PRIVATE_KEY),
+    certificatePem: normalizePem(process.env.EIMS_CERTIFICATE),
     certificateBase64: process.env.EIMS_CERTIFICATE_BASE64 ?? "",
     httpTimeoutMs,
     tokenSkewMs,
@@ -256,8 +275,8 @@ export default registerAs("eims", (): EimsConfig => {
   if (!enabled) return base;
 
   const missing: string[] = REQUIRED_VARS.filter((name) => !process.env[name]);
-  for (const [pathVar, base64Var] of REQUIRED_EITHER_OR) {
-    if (!process.env[pathVar] && !process.env[base64Var]) missing.push(`${pathVar} or ${base64Var}`);
+  for (const vars of REQUIRED_ANY_OF) {
+    if (vars.every((name) => !process.env[name])) missing.push(vars.join(" or "));
   }
   if (missing.length > 0) {
     throw new Error(
diff --git a/apps/edr-freight-api/src/modules/eims/eims-credentials.provider.ts b/apps/edr-freight-api/src/modules/eims/eims-credentials.provider.ts
index 18725df37..a5f837c1e 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-credentials.provider.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-credentials.provider.ts
@@ -5,6 +5,17 @@ import { ConfigService } from "@nestjs/config";
 import { EimsConfig } from "../../config/eims.config";
 import { EimsConfigException } from "./eims.errors";
 
+const PEM_HEADER = /-----BEGIN [A-Z ]*(PRIVATE KEY|CERTIFICATE)-----/;
+
+/**
+ * A safe-to-log fingerprint of decoded key/cert bytes: length + a printable-only preview of the
+ * first line. Never the actual key material — PEM headers aren't secret, the base64 body is.
+ */
+const describeBytes = (bytes: Buffer): string => {
+  const preview = bytes.toString("utf8", 0, 40).replace(/[^\x20-\x7e]/g, "?");
+  return `${bytes.length} bytes, starts with "${preview}"`;
+};
+
 /**
  * Loads the INSA-issued EIMS credentials from disk, once, and keeps them in memory.
  *
@@ -25,20 +36,50 @@ export class EimsCredentialsProvider {
   }
 
   /**
-   * RSA private key, parsed once. `privateKeyBase64` wins when set (no file I/O at all — for a
-   * container that can't be given a host bind mount); otherwise falls back to `privateKeyPath`.
-   * Throws a config error if neither is usable.
+   * RSA private key, parsed once. Three ways in, checked in this order: `privateKeyPem` (the PEM
+   * text itself, no encoding step to get wrong), `privateKeyBase64` (for stores that can't hold a
+   * literal newline), `privateKeyPath` (the original file-on-disk form). Throws a config error if
+   * none is usable.
    */
   getPrivateKey(): KeyObject {
     if (this.privateKey) return this.privateKey;
 
-    const { privateKeyBase64, privateKeyPath: path } = this.cfg;
-    const source = privateKeyBase64 ? "EIMS_PRIVATE_KEY_BASE64" : `EIMS_PRIVATE_KEY_PATH (${path})`;
-    if (!privateKeyBase64 && !path) throw new EimsConfigException("EIMS_PRIVATE_KEY_PATH is not set");
+    const { privateKeyPem, privateKeyBase64, privateKeyPath: path } = this.cfg;
+    const source = privateKeyPem
+      ? "EIMS_PRIVATE_KEY"
+      : privateKeyBase64
+        ? "EIMS_PRIVATE_KEY_BASE64"
+        : `EIMS_PRIVATE_KEY_PATH (${path})`;
+    if (!privateKeyPem && !privateKeyBase64 && !path) {
+      throw new EimsConfigException("EIMS_PRIVATE_KEY_PATH is not set");
+    }
+
+    let bytes: Buffer;
+    try {
+      bytes = privateKeyPem
+        ? Buffer.from(privateKeyPem, "utf8")
+        : privateKeyBase64
+          ? Buffer.from(privateKeyBase64, "base64")
+          : readFileSync(path);
+    } catch (err) {
+      throw new EimsConfigException(
+        `EIMS private key from ${source} could not be read or parsed: ${(err as Error).message}`,
+      );
+    }
+
+    // Fail with a diagnosable message before handing possibly-garbled bytes to OpenSSL, whose own
+    // error ("unsupported") gives no hint whether the problem is truncation, double-encoding, or a
+    // genuinely wrong file — all indistinguishable from outside without seeing the decoded bytes.
+    if (!PEM_HEADER.test(bytes.toString("utf8", 0, 100))) {
+      throw new EimsConfigException(
+        `EIMS private key from ${source} does not look like a PEM key after decoding ` +
+          `(${describeBytes(bytes)}) — check it's base64 of the raw key file with no line-wrapping ` +
+          `or truncation, and not base64 applied twice.`,
+      );
+    }
 
     let key: KeyObject;
     try {
-      const bytes = privateKeyBase64 ? Buffer.from(privateKeyBase64, "base64") : readFileSync(path);
       key = createPrivateKey(bytes);
     } catch (err) {
       // The source is operational information, not a secret; the key material never appears.
@@ -58,13 +99,19 @@ export class EimsCredentialsProvider {
   }
 
   /**
-   * Base64 of the certificate file's exact bytes. No parsing, no re-encoding. `certificateBase64`
-   * config wins when set (already base64, used as-is); otherwise read from `certificatePath`.
+   * Base64 of the certificate file's exact bytes. No parsing, no re-encoding of what MoR issued.
+   * `certificatePem`/`certificateBase64` config win when set (used as-is, or re-encoded from the
+   * pasted text respectively); otherwise read from `certificatePath`.
    */
   getCertificateBase64(): string {
     if (this.certificateBase64) return this.certificateBase64;
 
-    const { certificateBase64: inline, certificatePath: path } = this.cfg;
+    const { certificatePem: pem, certificateBase64: inline, certificatePath: path } = this.cfg;
+    if (pem) {
+      this.certificateBase64 = Buffer.from(pem, "utf8").toString("base64");
+      this.logger.log(`EIMS certificate bundle loaded from EIMS_CERTIFICATE`);
+      return this.certificateBase64;
+    }
     if (inline) {
       this.certificateBase64 = inline;
       this.logger.log(`EIMS certificate bundle loaded from EIMS_CERTIFICATE_BASE64`);
diff --git a/apps/edr-freight-api/src/modules/eims/eims-signer.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-signer.service.spec.ts
index d2f190172..f8210cab6 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-signer.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-signer.service.spec.ts
@@ -102,6 +102,8 @@ describe("EimsCredentialsProvider", () => {
     certificatePath?: string;
     privateKeyBase64?: string;
     certificateBase64?: string;
+    privateKeyPem?: string;
+    certificatePem?: string;
   }) => new EimsCredentialsProvider({ get: () => cfg } as unknown as ConfigService);
 
   it("fails clearly when the key path is unset", () => {
@@ -137,4 +139,34 @@ describe("EimsCredentialsProvider", () => {
     const certBase64 = Buffer.from(CERTIFICATE_FIXTURE, "utf8").toString("base64");
     expect(providerFor({ certificateBase64: certBase64 }).getCertificateBase64()).toBe(certBase64);
   });
+
+  it("fails with a decoded-bytes preview when the base64 doesn't decode to a PEM key", () => {
+    // Simulates the real failure this guards against: a truncated/mangled env var still decodes
+    // as *some* bytes, but not a key — OpenSSL's own error here gives no hint why.
+    const notAKey = Buffer.from("not actually a pem file", "utf8").toString("base64");
+    expect(() => providerFor({ privateKeyBase64: notAKey }).getPrivateKey()).toThrow(
+      /does not look like a PEM key.*23 bytes, starts with "not actually a pem file"/s,
+    );
+  });
+
+  it("loads the key from the raw PEM env var directly, no encoding step", () => {
+    const pem = readFileSync(keyPath).toString("utf8");
+    const key = providerFor({ privateKeyPem: pem }).getPrivateKey();
+    expect(key.asymmetricKeyType).toBe("rsa");
+  });
+
+  it("prefers the raw PEM var over base64 and path when all three are set", () => {
+    const pem = readFileSync(keyPath).toString("utf8");
+    const key = providerFor({
+      privateKeyPem: pem,
+      privateKeyBase64: Buffer.from("garbage").toString("base64"),
+      privateKeyPath: join(dir, "nope.key"),
+    }).getPrivateKey();
+    expect(key.asymmetricKeyType).toBe("rsa");
+  });
+
+  it("loads the certificate from the raw PEM env var, re-encoded to base64", () => {
+    const base64 = providerFor({ certificatePem: CERTIFICATE_FIXTURE }).getCertificateBase64();
+    expect(base64).toBe(Buffer.from(CERTIFICATE_FIXTURE, "utf8").toString("base64"));
+  });
 });
diff --git a/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts b/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts
index 662436d50..a55951db4 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-test-fixtures.ts
@@ -61,6 +61,8 @@ export const eimsConfig = (over: Partial<EimsConfig> = {}): EimsConfig => ({
   certificatePath: "/dev/null",
   privateKeyBase64: "",
   certificateBase64: "",
+  privateKeyPem: "",
+  certificatePem: "",
   httpTimeoutMs: 30_000,
   tokenSkewMs: 45_000,
   autoSubmit: false,

From c04859d333f94ecd1c709b4acb07ade326599103 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 17 Aug 2026 11:02:11 +0000
Subject: [PATCH 132/174] fix(warehouses): add container size to standalone
 container-return form
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Backend already accepted containerSize ('20'|'40') on
CreateEmptyContainerReturnDto and enforces one-40ft-or-two-20ft-per-wagon
via assertWagonLoad — the Standalone Return modal just never collected it.
Add a Container Type select and wire it into the submit payload.
---
 .../src/pages/warehouses/ContainerReturnsPage.tsx  | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
index 0510ca997..685e7d2a3 100644
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/ContainerReturnsPage.tsx
@@ -961,6 +961,7 @@ interface StandaloneReturnModalProps {
 
 function StandaloneReturnModal({ opened, onClose, onSubmit, loading }: StandaloneReturnModalProps) {
   const [containerNumber, setContainerNumber] = useState<string>("");
+  const [containerSize, setContainerSize] = useState<EmptyContainerSize | null>(null);
   const [returnedBy, setReturnedBy] = useState<"EDR" | "CUSTOMER" | null>(null);
   const [returnDate, setReturnDate] = useState<string>(new Date().toISOString().split("T")[0]);
   const [warehouse, setWarehouse] = useState<string | null>(null);
@@ -1021,6 +1022,7 @@ function StandaloneReturnModal({ opened, onClose, onSubmit, loading }: Standalon
           containers: [
             {
               containerNumber,
+              containerSize: containerSize ?? undefined,
               returnDate,
               warehouse: selectedWarehouse?.name || warehouse,
               yard: selectedYard?.name,
@@ -1034,6 +1036,7 @@ function StandaloneReturnModal({ opened, onClose, onSubmit, loading }: Standalon
     });
 
     setContainerNumber("");
+    setContainerSize(null);
     setReturnedBy(null);
     setReturnDate(new Date().toISOString().split("T")[0]);
     setWarehouse(null);
@@ -1071,6 +1074,17 @@ function StandaloneReturnModal({ opened, onClose, onSubmit, loading }: Standalon
           required
         />
 
+        <Select
+          label="Container Type"
+          placeholder="Select container size"
+          value={containerSize}
+          onChange={(val) => setContainerSize(val as EmptyContainerSize | null)}
+          data={[
+            { value: "20", label: "20 ft" },
+            { value: "40", label: "40 ft" },
+          ]}
+        />
+
         <Select
           label="Return Warehouse"
           placeholder="Select warehouse for container return"

From 0464a44de470923f2dbd9cb1bfa454c379354416 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 17 Aug 2026 11:21:39 +0000
Subject: [PATCH 133/174] fix(eims): a config error before signing must not
 block the whole system
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

settleFailure() treated any non-EimsApiException error as ambiguous
("might have reached MoR") and permanently blocked all further
filing until manually resolved. EimsConfigException (bad/missing
key, unparseable cert) is thrown by EimsSignerService before
EimsClientService.send()'s try/catch is even entered — by
construction it never reached the wire, so there is nothing
ambiguous about it.

This is exactly what happened live: a private-key parse failure
during the key/cert migration work reserved a counter, failed before
any HTTP call, and got treated as an unresolved in-flight submission
— blocking every other invoice from filing until someone manually
POSTs /eims/resolve.

Fix: EimsConfigException is now deterministic in settleFailure, same
treatment as a clean MoR rejection — both counters roll back, no
system-wide block, invoice marked FAILED (not UNKNOWN). Added a
CONFIG failure kind so the invoice's eimsLastError and the staff
alert both say plainly that the request never reached MoR, instead
of implying a MoR rejection.
---
 .../eims-invoice-registration.service.spec.ts | 25 ++++++++++++++++++-
 .../eims/eims-invoice-registration.service.ts | 23 +++++++++++++----
 .../src/modules/eims/eims.errors.ts           |  3 ++-
 3 files changed, 44 insertions(+), 7 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
index 79d3204dd..5fc74f988 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
@@ -10,7 +10,7 @@ import { NotificationInboxService } from "../notification-inbox/notification-inb
 import { NotificationsService } from "../notifications/notifications.service";
 import { EimsAuthService } from "./eims-auth.service";
 import { EimsClientService } from "./eims-client.service";
-import { EimsApiException } from "./eims.errors";
+import { EimsApiException, EimsConfigException } from "./eims.errors";
 import { buildEimsSeller } from "./eims-invoice-context";
 import { EimsInvoiceRegistrationService } from "./eims-invoice-registration.service";
 import { EimsSellerCacheService } from "./eims-seller-cache.service";
@@ -479,6 +479,29 @@ describe("EimsInvoiceRegistrationService.registerInvoiceWithEims", () => {
     });
   });
 
+  it("a config error (bad key, never reached MoR) rolls back both counters, no system block", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const postSigned = jest
+      .fn()
+      .mockRejectedValue(new EimsConfigException("EIMS private key ... could not be read or parsed"));
+
+    await expect(build(db, postSigned).registerInvoiceWithEims(INVOICE_ID)).rejects.toBeInstanceOf(
+      EimsConfigException,
+    );
+
+    expect(db.invoices.get(INVOICE_ID)).toMatchObject({
+      eimsStatus: EimsInvoiceStatus.Failed,
+      eimsIrn: null,
+      eimsLastError: expect.objectContaining({ kind: "CONFIG" }),
+    });
+    expect(db.state).toMatchObject({
+      inFlightInvoiceId: null,
+      blockedReason: null,
+      previousIrn: null,
+      nextInvoiceCounter: 7,
+    });
+  });
+
   it("treats a success response with no IRN as a failed registration", async () => {
     const db = new FakeDb([invoiceRow()]);
     const postSigned = jest.fn().mockResolvedValue({ statusCode: 200, body: { irn: "" } });
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
index 2ca5f5ffd..d96c64947 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
@@ -26,7 +26,7 @@ import { toEimsInvoiceStatusView } from "./eims-invoice-view.util";
 import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
 import { EimsAuthService } from "./eims-auth.service";
 import { EimsClientService } from "./eims-client.service";
-import { EimsApiException } from "./eims.errors";
+import { EimsApiException, EimsConfigException } from "./eims.errors";
 import { EimsSellerCacheService } from "./eims-seller-cache.service";
 import { EimsSystemState } from "./entities/eims-system-state.entity";
 import { assertEimsInvoiceConfig, buildEimsContext } from "./eims-invoice-context";
@@ -469,6 +469,14 @@ export class EimsInvoiceRegistrationService {
    *    when two rejected self-test attempts deadlocked the sequence until a manual DB reset.
    *
    * An ambiguous result keeps both: MoR may have counted and stored the document.
+   *
+   * `EimsConfigException` is also deterministic, for a different reason: it's thrown by
+   * `EimsSignerService`/`EimsCredentialsProvider` *before* `EimsClientService.send()`'s own
+   * try/catch is even entered (see `send()` — signing happens above its try block), so by
+   * construction no HTTP call was ever made. There is nothing to be ambiguous about — a bad key or
+   * missing config can't have reached MoR. Every error that *did* touch the wire is normalized to
+   * `EimsApiException` before it gets here (`toEimsApiException`), so this check is exhaustive:
+   * config errors are the only other kind `submit()` can throw.
    */
   private async settleFailure(
     invoiceId: string,
@@ -476,10 +484,11 @@ export class EimsInvoiceRegistrationService {
     err: unknown,
   ): Promise<void> {
     const api = err instanceof EimsApiException ? err : null;
-    const deterministic = api ? DETERMINISTIC_KINDS.has(api.kind) : false;
+    const isConfigError = err instanceof EimsConfigException;
+    const deterministic = isConfigError || (api ? DETERMINISTIC_KINDS.has(api.kind) : false);
     const status = deterministic ? EimsInvoiceStatus.Failed : EimsInvoiceStatus.Unknown;
     const lastError: EimsInvoiceError = {
-      kind: api?.kind ?? "UNKNOWN",
+      kind: isConfigError ? "CONFIG" : (api?.kind ?? "UNKNOWN"),
       message: (err as Error)?.message ?? "unknown error",
       httpStatus: api?.httpStatus,
       details: api?.details,
@@ -586,10 +595,14 @@ export class EimsInvoiceRegistrationService {
         type: NotificationType.GENERIC,
         priority: deterministic ? NotificationPriority.NORMAL : NotificationPriority.HIGH,
         title: deterministic
-          ? "EIMS rejected an invoice"
+          ? error.kind === "CONFIG"
+            ? "EIMS filing failed before reaching MoR"
+            : "EIMS rejected an invoice"
           : "EIMS filing unresolved — all further filing is blocked",
         body: deterministic
-          ? `MoR rejected the filing (${error.kind}): ${error.message}. The invoice is marked FAILED; correct it and file again.`
+          ? error.kind === "CONFIG"
+            ? `EIMS is misconfigured: ${error.message}. Nothing was sent to MoR; fix the config and file again.`
+            : `MoR rejected the filing (${error.kind}): ${error.message}. The invoice is marked FAILED; correct it and file again.`
           : `A submission was sent but never acknowledged (${error.kind}). Its IRN is unknown, so no further invoice can be filed until it is resolved with MoR.`,
         link: `/dashboard/invoices/${invoiceId}`,
         data: { invoiceId, eimsStatus: status, kind: error.kind, action: "EIMS_FILING_FAILED" },
diff --git a/apps/edr-freight-api/src/modules/eims/eims.errors.ts b/apps/edr-freight-api/src/modules/eims/eims.errors.ts
index 3be21fdd3..75c513824 100644
--- a/apps/edr-freight-api/src/modules/eims/eims.errors.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims.errors.ts
@@ -10,7 +10,8 @@ export type EimsFailureKind =
   | "FORBIDDEN"
   | "RULE_VALIDATION"
   | "SERVER"
-  | "UNKNOWN";
+  | "UNKNOWN"
+  | "CONFIG";
 
 /** Raised when EIMS is disabled or its credential files are unusable. */
 export class EimsConfigException extends ServiceUnavailableException {

From 0999bc0b8ba177f357c7485508a5389252d3f0cd Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 17 Aug 2026 11:53:12 +0000
Subject: [PATCH 134/174] fix(eims): a mapper failure after reservation also
 orphaned the block
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

toEimsInvoice/buildEimsContext sat outside the try/catch that calls
settleFailure — reservation happens (TX1), then request-building ran
unguarded, then submit() was the only thing actually wrapped. Any
exception during mapping (a validation error like an unmapped buyer
country, or a bug) skipped settleFailure entirely and left the
reservation permanently held: exactly the live incident just seen —
register 500'd, and every subsequent attempt on any invoice 409'd
'already in flight' until manually resolved.

Fix: the try block now starts right after reserve(), covering
request-building and submit() both. settleFailure's determinism
check is generalized to match — any error that is not an
EimsApiException is pre-wire and safe to release, not just
EimsConfigException (still labeled CONFIG; everything else pre-wire
is now labeled the new LOCAL kind). This is exhaustive by
construction: every error that actually touches the wire is already
normalized to EimsApiException inside EimsClientService.send()'s own
catch, so nothing outside that can be ambiguous.
---
 .../eims-invoice-registration.service.spec.ts | 30 +++++++++
 .../eims/eims-invoice-registration.service.ts | 64 ++++++++++---------
 .../src/modules/eims/eims.errors.ts           |  3 +-
 3 files changed, 66 insertions(+), 31 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
index 5fc74f988..f560ff917 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts
@@ -502,6 +502,36 @@ describe("EimsInvoiceRegistrationService.registerInvoiceWithEims", () => {
     });
   });
 
+  it("a mapper failure after reservation (e.g. unmapped buyer country) also releases the reservation", async () => {
+    // Regression: toEimsInvoice/buildEimsContext used to sit outside the try/catch that calls
+    // settleFailure — a throw here left the reservation permanently orphaned (a real live incident:
+    // 500 on register, then every subsequent attempt 409'd "already in flight" until manually
+    // resolved). This never reaches postSigned at all — the mapper throws before submit() is called.
+    const db = new FakeDb([
+      invoiceRow({ company: { ...invoiceRow().company, country: "France" } as never }),
+    ]);
+    const postSigned = jest.fn();
+
+    // The mapper throws a plain Error (it's a pure function, not a NestJS layer) — that's the
+    // point: settleFailure must treat *any* non-EimsApiException as pre-wire, not just its own
+    // known exception types.
+    await expect(build(db, postSigned).registerInvoiceWithEims(INVOICE_ID)).rejects.toThrow(
+      /no MoR country code mapping/,
+    );
+
+    expect(postSigned).not.toHaveBeenCalled();
+    expect(db.invoices.get(INVOICE_ID)).toMatchObject({
+      eimsStatus: EimsInvoiceStatus.Failed,
+      eimsLastError: expect.objectContaining({ kind: "LOCAL" }),
+    });
+    expect(db.state).toMatchObject({
+      inFlightInvoiceId: null,
+      blockedReason: null,
+      previousIrn: null,
+      nextInvoiceCounter: 7,
+    });
+  });
+
   it("treats a success response with no IRN as a failed registration", async () => {
     const db = new FakeDb([invoiceRow()]);
     const postSigned = jest.fn().mockResolvedValue({ statusCode: 200, body: { irn: "" } });
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
index d96c64947..a823e5ddf 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts
@@ -123,27 +123,29 @@ export class EimsInvoiceRegistrationService {
     const reservation = await this.reserve(invoiceId, session.systemNumber);
     if (!reservation) return this.getEimsStatus(invoiceId);
 
-    // The request can only be built now: InvoiceCounter and PreviousIrn come from the reservation.
-    const request = toEimsInvoice(
-      invoice,
-      this.sellerCache.getSellerDetails(cfg),
-      buildEimsContext(cfg, {
-        // Allocated from the system state, not our invoiceNumber: MoR validates DocumentNumber
-        // against ^(0|[1-9][0-9]{0,8})$, which "INV-20260807-00006" can never satisfy.
-        documentNumber: reservation.documentNumber,
-        invoiceCounter: reservation.invoiceCounter,
-        previousIrn: reservation.previousIrn,
-        session,
-        documentType,
-        reason: invoice.eimsReason,
-        relatedDocument,
-      }),
-    );
-
     let irn: string;
     let ackDate: string | undefined;
     let signedQR: string | undefined;
     try {
+      // The request can only be built now: InvoiceCounter and PreviousIrn come from the
+      // reservation. Building it — and everything after — stays inside this try: a reservation is
+      // held from here on, and *any* failure past this point, mapper or wire, must release it
+      // through settleFailure rather than leave it orphaned as a permanent system-wide block.
+      const request = toEimsInvoice(
+        invoice,
+        this.sellerCache.getSellerDetails(cfg),
+        buildEimsContext(cfg, {
+          // Allocated from the system state, not our invoiceNumber: MoR validates DocumentNumber
+          // against ^(0|[1-9][0-9]{0,8})$, which "INV-20260807-00006" can never satisfy.
+          documentNumber: reservation.documentNumber,
+          invoiceCounter: reservation.invoiceCounter,
+          previousIrn: reservation.previousIrn,
+          session,
+          documentType,
+          reason: invoice.eimsReason,
+          relatedDocument,
+        }),
+      );
       // Deliberately outside every transaction — no DB lock is held across the wire.
       const result = await this.submit(request);
       irn = result.irn;
@@ -470,13 +472,14 @@ export class EimsInvoiceRegistrationService {
    *
    * An ambiguous result keeps both: MoR may have counted and stored the document.
    *
-   * `EimsConfigException` is also deterministic, for a different reason: it's thrown by
-   * `EimsSignerService`/`EimsCredentialsProvider` *before* `EimsClientService.send()`'s own
-   * try/catch is even entered (see `send()` — signing happens above its try block), so by
-   * construction no HTTP call was ever made. There is nothing to be ambiguous about — a bad key or
-   * missing config can't have reached MoR. Every error that *did* touch the wire is normalized to
-   * `EimsApiException` before it gets here (`toEimsApiException`), so this check is exhaustive:
-   * config errors are the only other kind `submit()` can throw.
+   * Any error that is *not* an `EimsApiException` is also deterministic, on a different basis:
+   * every error that actually touches the wire is normalized to `EimsApiException` before it gets
+   * here (`EimsClientService.send()`'s catch calls `toEimsApiException` on whatever the HTTP call
+   * threw). The try block this feeds covers request-building (`toEimsInvoice`/`buildEimsContext` —
+   * pure, no I/O) and `submit()`; nothing in that span can produce another exception shape by
+   * touching MoR. So a non-`EimsApiException` here — a mapper validation error (unmapped buyer
+   * country, say), `EimsConfigException` from a bad signing key, or a bug — failed strictly before
+   * any HTTP call went out, and releasing the reservation is always safe, never a guess.
    */
   private async settleFailure(
     invoiceId: string,
@@ -484,11 +487,12 @@ export class EimsInvoiceRegistrationService {
     err: unknown,
   ): Promise<void> {
     const api = err instanceof EimsApiException ? err : null;
-    const isConfigError = err instanceof EimsConfigException;
-    const deterministic = isConfigError || (api ? DETERMINISTIC_KINDS.has(api.kind) : false);
+    // Never touched the wire (see the doc comment above) — always safe to release, whatever it is.
+    const deterministic = api ? DETERMINISTIC_KINDS.has(api.kind) : true;
     const status = deterministic ? EimsInvoiceStatus.Failed : EimsInvoiceStatus.Unknown;
+    const localKind = err instanceof EimsConfigException ? "CONFIG" : "LOCAL";
     const lastError: EimsInvoiceError = {
-      kind: isConfigError ? "CONFIG" : (api?.kind ?? "UNKNOWN"),
+      kind: api?.kind ?? localKind,
       message: (err as Error)?.message ?? "unknown error",
       httpStatus: api?.httpStatus,
       details: api?.details,
@@ -595,13 +599,13 @@ export class EimsInvoiceRegistrationService {
         type: NotificationType.GENERIC,
         priority: deterministic ? NotificationPriority.NORMAL : NotificationPriority.HIGH,
         title: deterministic
-          ? error.kind === "CONFIG"
+          ? error.kind === "CONFIG" || error.kind === "LOCAL"
             ? "EIMS filing failed before reaching MoR"
             : "EIMS rejected an invoice"
           : "EIMS filing unresolved — all further filing is blocked",
         body: deterministic
-          ? error.kind === "CONFIG"
-            ? `EIMS is misconfigured: ${error.message}. Nothing was sent to MoR; fix the config and file again.`
+          ? error.kind === "CONFIG" || error.kind === "LOCAL"
+            ? `${error.kind === "CONFIG" ? "EIMS is misconfigured" : "Filing failed locally"}: ${error.message}. Nothing was sent to MoR; fix it and file again.`
             : `MoR rejected the filing (${error.kind}): ${error.message}. The invoice is marked FAILED; correct it and file again.`
           : `A submission was sent but never acknowledged (${error.kind}). Its IRN is unknown, so no further invoice can be filed until it is resolved with MoR.`,
         link: `/dashboard/invoices/${invoiceId}`,
diff --git a/apps/edr-freight-api/src/modules/eims/eims.errors.ts b/apps/edr-freight-api/src/modules/eims/eims.errors.ts
index 75c513824..853b32c29 100644
--- a/apps/edr-freight-api/src/modules/eims/eims.errors.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims.errors.ts
@@ -11,7 +11,8 @@ export type EimsFailureKind =
   | "RULE_VALIDATION"
   | "SERVER"
   | "UNKNOWN"
-  | "CONFIG";
+  | "CONFIG"
+  | "LOCAL";
 
 /** Raised when EIMS is disabled or its credential files are unusable. */
 export class EimsConfigException extends ServiceUnavailableException {

From 7143ba1040a6a86a66ca76310963d94ac6aaafe0 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 17 Aug 2026 12:38:06 +0000
Subject: [PATCH 135/174] feat(customers): notify marketing on returned
 changes, name actors in history
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three gaps on the backoffice customer detail page:

- Rejecting a change request or sending it back for correction notified
  nobody. Adds CompanyNotifierService.changeRequestReturned, which pings
  the customer desk with the reviewer, the outcome and the note. Marketing
  joins that desk via customers:view + customers:get_notification in the
  role preset — grants still come from the IAM UI, the preset only sets
  the default for new environments.
- submitted_by / reviewed_by / actor_id were stored but never resolved, so
  the History tab could say what changed but never who asked or who sent
  it back. Resolves them through a shared iam-user-name util (deduped from
  the private copy in contract-document-history.service) and renders
  "Requested by" / "Sent back to marketing by" lines. The
  changes_requested badge is relabelled to match the workflow.
- "View" opened an in-page modal one document at a time. Adds
  openFileInNewTab, which opens the tab inside the click gesture and fills
  it once the authenticated fetch resolves, and an "Open all" button that
  loops over the documents table so every file lands in its own tab.
---
 .../src/common/utils/iam-user-name.util.ts    | 49 +++++++++++
 .../modules/companies/companies.service.ts    | 82 ++++++++++++++++++-
 .../companies/company-notifier.service.ts     | 29 +++++++
 .../dto/change-request-response.dto.ts        |  6 ++
 .../dto/company-revision-response.dto.ts      |  3 +
 .../entities/company-change-request.entity.ts |  8 ++
 .../entities/company-revision.entity.ts       |  6 ++
 .../contract-document-history.service.ts      | 38 +--------
 .../src/seed/freight-permissions.registry.ts  |  6 ++
 .../customers/ChangeRequestReview.tsx         | 21 ++---
 .../components/customers/CompanyTimeline.tsx  | 66 +++++++++++++--
 .../pages/customers/CustomerDetailPage.tsx    | 57 +++++++------
 .../backoffice/src/services/files.service.ts  | 47 +++++++++++
 .../backoffice/src/types/customer.ts          |  6 ++
 14 files changed, 335 insertions(+), 89 deletions(-)
 create mode 100644 apps/edr-freight-api/src/common/utils/iam-user-name.util.ts

diff --git a/apps/edr-freight-api/src/common/utils/iam-user-name.util.ts b/apps/edr-freight-api/src/common/utils/iam-user-name.util.ts
new file mode 100644
index 000000000..e4a3465d0
--- /dev/null
+++ b/apps/edr-freight-api/src/common/utils/iam-user-name.util.ts
@@ -0,0 +1,49 @@
+import { DataSource } from "typeorm";
+
+/**
+ * `iam.users.name` is a localized object ({ en, am, … }), not a string — a
+ * plain `String(name)` there yields "[object Object]" in an audit trail.
+ */
+export interface IamUserRow {
+  name?: Record<string, string> | string | null;
+  username?: string | null;
+  email?: string | null;
+}
+
+/** Best display name for a user row: English label → any locale → login → email. */
+export function pickUserName(user: IamUserRow): string | null {
+  const { name } = user;
+  if (typeof name === "string" && name.trim()) return name.trim();
+  if (name && typeof name === "object") {
+    const localized =
+      name.en ??
+      Object.values(name).find((v) => typeof v === "string" && v.trim());
+    if (localized?.trim()) return localized.trim();
+  }
+  return user.username?.trim() || user.email?.trim() || null;
+}
+
+/**
+ * Display names for a set of IAM user ids — one query for the whole set.
+ * `iam.users` is owned by the auth system and has no entity here, so it is read
+ * directly. A miss is not an error: the caller still holds the id and can fall
+ * back to it.
+ */
+export async function resolveIamUserNames(
+  dataSource: DataSource,
+  userIds: (string | null | undefined)[],
+): Promise<Map<string, string>> {
+  const resolved = new Map<string, string>();
+  const ids = [...new Set(userIds.filter((id): id is string => Boolean(id)))];
+  if (ids.length === 0) return resolved;
+
+  const rows = (await dataSource.query(
+    `SELECT id, name, username, email FROM iam.users WHERE id = ANY($1::uuid[])`,
+    [ids],
+  )) as Array<IamUserRow & { id: string }>;
+  for (const row of rows) {
+    const name = pickUserName(row);
+    if (name) resolved.set(row.id, name);
+  }
+  return resolved;
+}
diff --git a/apps/edr-freight-api/src/modules/companies/companies.service.ts b/apps/edr-freight-api/src/modules/companies/companies.service.ts
index 98b30f006..bf8184833 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.service.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.service.ts
@@ -7,6 +7,7 @@ import {
   ForbiddenException,
 } from "@nestjs/common";
 import { DataSource, EntityManager } from "typeorm";
+import { resolveIamUserNames } from "../../common/utils/iam-user-name.util";
 import { CompaniesRepository } from "./companies.repository";
 import { CompanyProfileRepository } from "./company-profile.repository";
 import { CompanyChangeRequestRepository } from "./company-change-request.repository";
@@ -1141,16 +1142,55 @@ export class CompaniesService {
     return new ProfileResponseDto(profile, live, request);
   }
 
-  /** List a company's change requests, newest first (backoffice review). */
+  /**
+   * List a company's change requests, newest first (backoffice review). Actor
+   * ids are resolved to display names here — the history screen has to say who
+   * asked for a change and who sent it back, not print two uuids.
+   */
   async listChangeRequests(companyId: string): Promise<CompanyChangeRequest[]> {
     await this.findCompanyById(companyId);
-    return this.changeRequestRepo.findByCompanyId(companyId);
+    const requests = await this.changeRequestRepo.findByCompanyId(companyId);
+    const names = await this.resolveActorNames(
+      requests.flatMap((r) => [r.submittedBy, r.reviewedBy]),
+    );
+    for (const request of requests) {
+      request.submittedByName = request.submittedBy
+        ? (names.get(request.submittedBy) ?? null)
+        : null;
+      request.reviewedByName = request.reviewedBy
+        ? (names.get(request.reviewedBy) ?? null)
+        : null;
+    }
+    return requests;
   }
 
   /** Onboarding-phase edit history (see {@link recordCompanyRevision}), newest first. */
   async listCompanyRevisions(companyId: string): Promise<CompanyRevision[]> {
     await this.findCompanyById(companyId);
-    return this.revisionRepo.findByCompanyId(companyId);
+    const revisions = await this.revisionRepo.findByCompanyId(companyId);
+    const names = await this.resolveActorNames(revisions.map((r) => r.actorId));
+    for (const revision of revisions) {
+      revision.actorName = revision.actorId
+        ? (names.get(revision.actorId) ?? null)
+        : null;
+    }
+    return revisions;
+  }
+
+  /**
+   * Display names for actor ids, one query for the whole list. A lookup failure
+   * degrades the history to ids rather than failing the request — the entry is
+   * still worth showing without the name.
+   */
+  private async resolveActorNames(
+    actorIds: (string | null | undefined)[],
+  ): Promise<Map<string, string>> {
+    try {
+      return await resolveIamUserNames(this.dataSource, actorIds);
+    } catch (err) {
+      this.logger.warn(`Could not resolve actor names: ${String(err)}`);
+      return new Map();
+    }
   }
 
   /**
@@ -1519,6 +1559,7 @@ export class CompaniesService {
     }
     await this.discardLicenseChanges(request);
     await this.discardDocumentChanges(request);
+    await this.notifyChangeRequestReturned(request, "rejected", note, reviewerId);
     return (
       (await this.changeRequestRepo.update(id, {
         status: ChangeRequestStatus.Rejected,
@@ -1556,6 +1597,12 @@ export class CompaniesService {
         `Change request ${id} is already ${request.status}`,
       );
     }
+    await this.notifyChangeRequestReturned(
+      request,
+      "changes_requested",
+      note,
+      reviewerId,
+    );
     return (
       (await this.changeRequestRepo.update(id, {
         status: ChangeRequestStatus.ChangesRequested,
@@ -1566,6 +1613,35 @@ export class CompaniesService {
     );
   }
 
+  /**
+   * Tell the customer desk a change request came back unapproved. Best-effort:
+   * a missing company or an unresolvable reviewer name must not fail the
+   * reviewer's decision, which is already the point of the try/catch.
+   */
+  private async notifyChangeRequestReturned(
+    request: CompanyChangeRequest,
+    outcome: "rejected" | "changes_requested",
+    note: string,
+    reviewerId?: string,
+  ): Promise<void> {
+    try {
+      const company = await this.companiesRepo.findById(request.companyId);
+      if (!company) return;
+      const names = await this.resolveActorNames([reviewerId]);
+      this.companyNotifier.changeRequestReturned(
+        company,
+        request.id,
+        outcome,
+        note,
+        reviewerId ? (names.get(reviewerId) ?? null) : null,
+      );
+    } catch (err) {
+      this.logger.warn(
+        `Could not notify the customer desk about ${request.id}: ${String(err)}`,
+      );
+    }
+  }
+
   async deleteCompany(id: string): Promise<void> {
     await this.findCompanyById(id);
     await this.companiesRepo.softDelete(id);
diff --git a/apps/edr-freight-api/src/modules/companies/company-notifier.service.ts b/apps/edr-freight-api/src/modules/companies/company-notifier.service.ts
index 6bcd21f08..d3a556f50 100644
--- a/apps/edr-freight-api/src/modules/companies/company-notifier.service.ts
+++ b/apps/edr-freight-api/src/modules/companies/company-notifier.service.ts
@@ -244,6 +244,35 @@ export class CompanyNotifierService {
     );
   }
 
+  /**
+   * A reviewer did NOT approve a customer's profile changes — they rejected it
+   * or sent it back for correction. The customer desk (Marketing included, via
+   * the `customers:get_notification` key) owns the follow-up with the customer,
+   * so the decision has to reach their inbox; without this it was silent, and
+   * only visible to whoever happened to reopen the customer's History tab.
+   */
+  changeRequestReturned(
+    company: Company,
+    changeRequestId: string,
+    outcome: "rejected" | "changes_requested",
+    note: string,
+    reviewerName?: string | null,
+  ): void {
+    const rejected = outcome === "rejected";
+    const by = reviewerName?.trim() ? ` by ${reviewerName.trim()}` : "";
+    this.logger.log(`CHANGE_REQUEST_${outcome.toUpperCase()} — ${company.id}`);
+    this.notifyStaff(
+      company,
+      rejected
+        ? "Customer profile changes rejected"
+        : "Customer profile changes sent back for correction",
+      `${company.name}'s profile changes were ` +
+        `${rejected ? "rejected" : "sent back for correction"}${by}. ` +
+        `Reason: ${note}`,
+      { changeRequestId, outcome, note, reviewerName: reviewerName ?? null },
+    );
+  }
+
   // ── Customer-facing: a specific document needs correcting ──────────────────
 
   /**
diff --git a/apps/edr-freight-api/src/modules/companies/dto/change-request-response.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/change-request-response.dto.ts
index 4a931dae3..2a4f65708 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/change-request-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/change-request-response.dto.ts
@@ -23,8 +23,12 @@ export class ChangeRequestResponseDto {
   documentChanges: DocumentChangeIntent[];
   note: string | null;
   submittedBy: string | null;
+  /** Who filed the request, for the history screen (null when unresolvable). */
+  submittedByName: string | null;
   submittedAt: Date | null;
   reviewedBy: string | null;
+  /** Who approved / rejected / sent it back. */
+  reviewedByName: string | null;
   reviewedAt: Date | null;
   createdAt: Date;
   updatedAt: Date;
@@ -39,8 +43,10 @@ export class ChangeRequestResponseDto {
     this.documentChanges = req.documents?.documentChanges ?? [];
     this.note = req.note ?? null;
     this.submittedBy = req.submittedBy ?? null;
+    this.submittedByName = req.submittedByName ?? null;
     this.submittedAt = req.submittedAt ?? null;
     this.reviewedBy = req.reviewedBy ?? null;
+    this.reviewedByName = req.reviewedByName ?? null;
     this.reviewedAt = req.reviewedAt ?? null;
     this.createdAt = req.createdAt;
     this.updatedAt = req.updatedAt;
diff --git a/apps/edr-freight-api/src/modules/companies/dto/company-revision-response.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/company-revision-response.dto.ts
index c93c7387c..198a44e06 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/company-revision-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/company-revision-response.dto.ts
@@ -8,6 +8,8 @@ export class CompanyRevisionResponseDto {
   id: string;
   companyId: string;
   actorId: string | null;
+  /** Who made the edit, for the history screen (null when unresolvable). */
+  actorName: string | null;
   summary: string;
   changes: CompanyRevisionChange[];
   createdAt: Date;
@@ -16,6 +18,7 @@ export class CompanyRevisionResponseDto {
     this.id = revision.id;
     this.companyId = revision.companyId;
     this.actorId = revision.actorId ?? null;
+    this.actorName = revision.actorName ?? null;
     this.summary = revision.summary;
     this.changes = revision.changes ?? [];
     this.createdAt = revision.createdAt;
diff --git a/apps/edr-freight-api/src/modules/companies/entities/company-change-request.entity.ts b/apps/edr-freight-api/src/modules/companies/entities/company-change-request.entity.ts
index 2ba39ecad..02b49f849 100644
--- a/apps/edr-freight-api/src/modules/companies/entities/company-change-request.entity.ts
+++ b/apps/edr-freight-api/src/modules/companies/entities/company-change-request.entity.ts
@@ -110,4 +110,12 @@ export class CompanyChangeRequest extends BaseEntity {
 
   @Column({ name: "reviewed_at", type: "timestamptz", nullable: true })
   reviewedAt?: Date | null;
+
+  /**
+   * Display names for {@link submittedBy} / {@link reviewedBy}, resolved from
+   * `iam.users` on read. Not columns — the history screen has to name the
+   * person who asked for the change, and an opaque uuid does not.
+   */
+  submittedByName?: string | null;
+  reviewedByName?: string | null;
 }
diff --git a/apps/edr-freight-api/src/modules/companies/entities/company-revision.entity.ts b/apps/edr-freight-api/src/modules/companies/entities/company-revision.entity.ts
index 222a8364f..533f08d7a 100644
--- a/apps/edr-freight-api/src/modules/companies/entities/company-revision.entity.ts
+++ b/apps/edr-freight-api/src/modules/companies/entities/company-revision.entity.ts
@@ -43,4 +43,10 @@ export class CompanyRevision extends BaseEntity {
 
   @Column({ name: "changes", type: "jsonb", default: () => `'[]'::jsonb` })
   changes!: CompanyRevisionChange[];
+
+  /**
+   * Display name for {@link actorId}, resolved from `iam.users` on read. Not a
+   * column — history has to name who made the edit, and a uuid does not.
+   */
+  actorName?: string | null;
 }
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-document-history.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-document-history.service.ts
index e38f737c6..1f1469182 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-document-history.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-document-history.service.ts
@@ -2,6 +2,7 @@ import { Injectable, Logger } from '@nestjs/common';
 import { InjectDataSource, InjectRepository } from '@nestjs/typeorm';
 import { DataSource, Repository } from 'typeorm';
 
+import { resolveIamUserNames } from '../../common/utils/iam-user-name.util';
 import {
   ContractDocumentChange,
   diffSnapshots,
@@ -20,28 +21,6 @@ export interface RecordRevisionInput {
   stepId?: string | null;
 }
 
-/**
- * `iam.users.name` is a localized object ({ en, am, … }), not a string — a
- * plain `String(name)` there yields "[object Object]" in the audit trail.
- */
-interface IamUserRow {
-  name?: Record<string, string> | string | null;
-  username?: string | null;
-  email?: string | null;
-}
-
-/** Best display name for a user row: English label → any locale → login → email. */
-function pickUserName(user: IamUserRow): string | null {
-  const { name } = user;
-  if (typeof name === 'string' && name.trim()) return name.trim();
-  if (name && typeof name === 'object') {
-    const localized =
-      name.en ?? Object.values(name).find((v) => typeof v === 'string' && v.trim());
-    if (localized?.trim()) return localized.trim();
-  }
-  return user.username?.trim() || user.email?.trim() || null;
-}
-
 /** Pre-computed changes (contract fields), rather than a document diff. */
 export interface RecordChangesInput {
   contractId: string;
@@ -120,23 +99,12 @@ export class ContractDocumentHistoryService {
   private async resolveActorNames(
     actorIds: string[],
   ): Promise<Map<string, string>> {
-    const resolved = new Map<string, string>();
-    const ids = [...new Set(actorIds.filter(Boolean))];
-    if (ids.length === 0) return resolved;
-
     try {
-      const rows = (await this.dataSource.query(
-        `SELECT id, name, username, email FROM iam.users WHERE id = ANY($1::uuid[])`,
-        [ids],
-      )) as Array<IamUserRow & { id: string }>;
-      for (const row of rows) {
-        const name = pickUserName(row);
-        if (name) resolved.set(row.id, name);
-      }
+      return await resolveIamUserNames(this.dataSource, actorIds);
     } catch (err) {
       this.logger.warn(`Could not resolve actor names: ${String(err)}`);
+      return new Map();
     }
-    return resolved;
   }
 
   /** Revision history for a contract, newest first. */
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index adbd22584..3fde18648 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -2484,6 +2484,12 @@ export const ROLE_PERMISSION_PRESETS = {
     FREIGHT_PERMS.contracts.suspend,
     FREIGHT_PERMS.contracts.editDocument,
     ...BOOKING_DESK_NOTIFICATION_KEYS,
+    // Marketing follows up with the customer when a reviewer sends profile
+    // changes back, so they sit on the customer desk: read-only on the customer
+    // record (no verify/deactivate — the decision stays with the chief) plus the
+    // desk key the change-request pings are addressed to.
+    FREIGHT_PERMS.customers.view,
+    FREIGHT_PERMS.customers.getNotification,
   ],
   orgManager: [...BOOKING_RULE_ENGINE_PERMISSION_KEYS],
 } as const;
diff --git a/apps/edr-freight-web/backoffice/src/components/customers/ChangeRequestReview.tsx b/apps/edr-freight-web/backoffice/src/components/customers/ChangeRequestReview.tsx
index 65c4f25e3..7f4cf30ce 100644
--- a/apps/edr-freight-web/backoffice/src/components/customers/ChangeRequestReview.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/customers/ChangeRequestReview.tsx
@@ -20,11 +20,10 @@ import {
   FileX2,
 } from "lucide-react";
 import { useState } from "react";
-import { useFileViewer } from "@edr/ui-common";
 
 import { useAuth } from "@/auth/useAuth";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
-import { fetchViewableFile } from "@/services/files.service";
+import { openFileInNewTab } from "@/services/files.service";
 import { api } from "@/services/api";
 import type { Company } from "@/types/customer";
 import { formatDate, humanize } from "./format";
@@ -227,7 +226,6 @@ export function ChangeRequestReview({ company }: { company: Company }) {
     api.customers.requestChangeRequestChanges.mutationOptions(),
   );
 
-  const { view, viewer } = useFileViewer();
   const [actionTarget, setActionTarget] = useState<{
     id: string;
     kind: "reject" | "request-changes";
@@ -350,10 +348,10 @@ export function ChangeRequestReview({ company }: { company: Company }) {
                       type="button"
                       size="sm"
                       onClick={() =>
-                        void fetchViewableFile(
+                        openFileInNewTab(
                           c.fileId,
                           c.fileName ?? humanize(c.code),
-                        ).then(view)
+                        )
                       }
                       style={{
                         textDecoration:
@@ -382,12 +380,7 @@ export function ChangeRequestReview({ company }: { company: Company }) {
                       component="button"
                       type="button"
                       size="sm"
-                      onClick={() =>
-                        void fetchViewableFile(
-                          fileId,
-                          `Document ${i + 1}`,
-                        ).then(view)
-                      }
+                      onClick={() => openFileInNewTab(fileId, `Document ${i + 1}`)}
                     >
                       Document {i + 1}
                     </Anchor>
@@ -421,10 +414,10 @@ export function ChangeRequestReview({ company }: { company: Company }) {
                       type="button"
                       size="sm"
                       onClick={() =>
-                        void fetchViewableFile(
+                        openFileInNewTab(
                           c.fileId,
                           c.fileName ?? "License document",
-                        ).then(view)
+                        )
                       }
                       style={{
                         textDecoration:
@@ -532,8 +525,6 @@ export function ChangeRequestReview({ company }: { company: Company }) {
           </Group>
         </Stack>
       </Modal>
-
-      {viewer}
     </>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/customers/CompanyTimeline.tsx b/apps/edr-freight-web/backoffice/src/components/customers/CompanyTimeline.tsx
index cd421d9bd..8469e4031 100644
--- a/apps/edr-freight-web/backoffice/src/components/customers/CompanyTimeline.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/customers/CompanyTimeline.tsx
@@ -1,9 +1,8 @@
 import { Alert, Anchor, Badge, Card, Group, SimpleGrid, Stack, Text } from "@mantine/core";
 import { useQuery } from "@tanstack/react-query";
 import { FilePlus2, FileX2, History } from "lucide-react";
-import { useFileViewer } from "@edr/ui-common";
 
-import { fetchViewableFile } from "@/services/files.service";
+import { openFileInNewTab } from "@/services/files.service";
 import { api } from "@/services/api";
 import type {
   Company,
@@ -36,6 +35,12 @@ interface TimelineEntry {
   at: string;
   note?: string | null;
   summary?: string;
+  /** Who filed the change (the customer, or staff editing during onboarding). */
+  requestedBy?: string | null;
+  /** When they filed it — the "asked" half of the ask/decide pair below. */
+  requestedAt?: string | null;
+  /** Who decided (approved / rejected / sent it back to marketing). */
+  decidedBy?: string | null;
   fieldDiffs: FieldDiff[];
   docDiffs: DocDiff[];
 }
@@ -43,10 +48,18 @@ interface TimelineEntry {
 const KIND_BADGE: Record<TimelineEntry["kind"], { label: string; color: string }> = {
   approved: { label: "Approved", color: "edr-green" },
   rejected: { label: "Rejected", color: "red" },
-  changes_requested: { label: "Changes requested", color: "yellow" },
+  // Sending a request back is what "reverted to marketing" means here: the
+  // request stays open and marketing owns the follow-up with the customer.
+  changes_requested: { label: "Sent back to marketing", color: "yellow" },
   revision: { label: "Recorded", color: "blue" },
 };
 
+/** "Requested by X" / "Reviewed by X", with the id-less case reading sanely. */
+function actorLine(verb: string, who?: string | null, when?: string | null) {
+  if (!who && !when) return null;
+  return `${verb}${who ? ` by ${who}` : ""}${when ? ` · ${formatDate(when)}` : ""}`;
+}
+
 /**
  * Pair adjacent remove-then-add intents into one before/after doc diff — a
  * "replace" is always staged as `[{op:'remove'}, {op:'add'}]` pushed together
@@ -132,6 +145,9 @@ function fromChangeRequest(
     kind: r.status as TimelineEntry["kind"],
     at: r.reviewedAt ?? r.updatedAt,
     note: r.note,
+    requestedBy: r.submittedByName,
+    requestedAt: r.submittedAt ?? r.createdAt,
+    decidedBy: r.reviewedByName,
     fieldDiffs,
     docDiffs,
   };
@@ -156,6 +172,7 @@ function fromRevision(rev: CompanyRevision): TimelineEntry {
     kind: "revision",
     at: rev.createdAt,
     summary: rev.summary,
+    requestedBy: rev.actorName,
     fieldDiffs,
     docDiffs,
   };
@@ -170,7 +187,6 @@ function fromRevision(rev: CompanyRevision): TimelineEntry {
  * single answer instead of two places to check.
  */
 export function CompanyTimeline({ company }: { company: Company }) {
-  const { view, viewer } = useFileViewer();
   const changeRequestsQuery = useQuery(
     api.customers.changeRequests.queryOptions({ input: { id: company.id } }),
   );
@@ -186,7 +202,7 @@ export function CompanyTimeline({ company }: { company: Company }) {
   ].sort((a, b) => new Date(b.at).getTime() - new Date(a.at).getTime());
 
   const openFile = (file: { id: string; name: string }) =>
-    void fetchViewableFile(file.id, file.name).then(view);
+    openFileInNewTab(file.id, file.name);
 
   if (entries.length === 0) {
     return (
@@ -205,6 +221,20 @@ export function CompanyTimeline({ company }: { company: Company }) {
     <Stack gap="md">
       {entries.map((entry) => {
         const badge = KIND_BADGE[entry.kind];
+        const requestedLine = actorLine(
+          entry.kind === "revision" ? "Edited" : "Requested",
+          entry.requestedBy,
+          entry.requestedAt,
+        );
+        const decidedLine = actorLine(
+          entry.kind === "changes_requested"
+            ? "Sent back to marketing"
+            : entry.kind === "rejected"
+              ? "Rejected"
+              : "Approved",
+          entry.decidedBy,
+          entry.kind === "revision" ? null : entry.at,
+        );
         return (
           <Card key={entry.id} withBorder>
             <Stack gap="sm">
@@ -224,10 +254,33 @@ export function CompanyTimeline({ company }: { company: Company }) {
                 </Text>
               </Group>
 
+              {/* Who asked, and who decided. Without this the feed said what
+                  changed and when, but never named a person — the first thing
+                  anyone auditing a returned request needs. */}
+              {(requestedLine || decidedLine) && (
+                <Stack gap={2}>
+                  {requestedLine && (
+                    <Text size="xs" c="dimmed">
+                      {requestedLine}
+                    </Text>
+                  )}
+                  {decidedLine && (
+                    <Text size="xs" c="dimmed">
+                      {decidedLine}
+                    </Text>
+                  )}
+                </Stack>
+              )}
+
               {entry.note && (
                 <Alert color="yellow" variant="light">
                   <Text size="sm">
-                    <strong>Note:</strong> {entry.note}
+                    <strong>
+                      {entry.kind === "changes_requested"
+                        ? "What was asked for:"
+                        : "Note:"}
+                    </strong>{" "}
+                    {entry.note}
                   </Text>
                 </Alert>
               )}
@@ -293,7 +346,6 @@ export function CompanyTimeline({ company }: { company: Company }) {
           </Card>
         );
       })}
-      {viewer}
     </Stack>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
index b395cc710..40185f990 100644
--- a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
@@ -23,6 +23,7 @@ import {
   Banknote,
   Contact,
   Download,
+  ExternalLink,
   Eye,
   FileSignature,
   FileText,
@@ -69,7 +70,7 @@ import { useAuth } from "@/auth/useAuth";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import {
   downloadBookingFile,
-  fetchViewableFile,
+  openFileInNewTab,
 } from "@/services/files.service";
 import { api } from "@/services/api";
 import type {
@@ -81,12 +82,7 @@ import type {
 } from "@/types/customer";
 import { hasSubmittedOnboarding, isOnboardingDraft } from "@/types/customer";
 import type { Invoice } from "@/types/invoice";
-import {
-  DataTable,
-  useFileViewer,
-  usePagination,
-  type ColumnDef,
-} from "@edr/ui-common";
+import { DataTable, usePagination, type ColumnDef } from "@edr/ui-common";
 import type { Freight } from "@edr/types";
 
 /** Plain-text summary of the company's eTrade-sourced record, downloaded client-side (eTrade returns data, not a document). */
@@ -146,7 +142,6 @@ const POA_DELEGATION_PENDING_CODE = "poa_delegation_letter_pending";
 export default function CustomerDetailPage() {
   const { id } = useParams<{ id: string }>();
   const navigate = useNavigate();
-  const { view, viewer } = useFileViewer();
   const { user } = useAuth();
 
   const { data: company, isLoading } = useQuery(
@@ -271,9 +266,7 @@ export default function CustomerDetailPage() {
                     variant="subtle"
                     color="gray"
                     aria-label={`View ${f.name}`}
-                    onClick={() =>
-                      void fetchViewableFile(f.id, f.name).then(view)
-                    }
+                    onClick={() => openFileInNewTab(f.id, f.name)}
                   >
                     <Eye size={14} />
                   </ActionIcon>
@@ -282,9 +275,7 @@ export default function CustomerDetailPage() {
                     type="button"
                     size="xs"
                     lineClamp={1}
-                    onClick={() =>
-                      void fetchViewableFile(f.id, f.name).then(view)
-                    }
+                    onClick={() => openFileInNewTab(f.id, f.name)}
                     style={{
                       maxWidth: 170,
                       textAlign: "left",
@@ -339,7 +330,7 @@ export default function CustomerDetailPage() {
         ),
       },
     ],
-    [view, canReview],
+    [canReview],
   );
 
   const bookingColumns: ColumnDef<CustomerBooking>[] = useMemo(
@@ -522,9 +513,7 @@ export default function CustomerDetailPage() {
               aria-label="View"
               data-stop-row-click
               onClick={() =>
-                void fetchViewableFile(row.original.id, row.original.name).then(
-                  view,
-                )
+                openFileInNewTab(row.original.id, row.original.name)
               }
             >
               <Eye size={16} />
@@ -564,7 +553,7 @@ export default function CustomerDetailPage() {
         ),
       },
     ],
-    [view, canRequestDocChange],
+    [canRequestDocChange],
   );
 
   const paymentColumns: ColumnDef<CustomerPayment>[] = useMemo(
@@ -1163,9 +1152,7 @@ export default function CustomerDetailPage() {
                                 lineClamp={1}
                                 style={{ flex: 1, textAlign: "left" }}
                                 onClick={() =>
-                                  void fetchViewableFile(doc.id, doc.name).then(
-                                    view,
-                                  )
+                                  openFileInNewTab(doc.id, doc.name)
                                 }
                               >
                                 {doc.name}
@@ -1176,9 +1163,7 @@ export default function CustomerDetailPage() {
                                 color="gray"
                                 aria-label={`Preview ${doc.name}`}
                                 onClick={() =>
-                                  void fetchViewableFile(doc.id, doc.name).then(
-                                    view,
-                                  )
+                                  openFileInNewTab(doc.id, doc.name)
                                 }
                               >
                                 <Eye size={15} />
@@ -1280,6 +1265,23 @@ export default function CustomerDetailPage() {
         {/* DOCUMENTS */}
         <Tabs.Panel value="documents" pt="lg">
           <Stack gap="lg">
+            {/* Reviewing a customer means reading every document, so offer the
+                whole set at once — each opens in its own tab. The loop is
+                synchronous inside the click handler on purpose: that is what
+                keeps the browser treating all of them as user-initiated. */}
+            <Group justify="flex-end">
+              <Button
+                variant="light"
+                leftSection={<ExternalLink size={16} />}
+                disabled={documents.length === 0}
+                onClick={() =>
+                  documents.forEach((d) => openFileInNewTab(d.id, d.name))
+                }
+              >
+                Open all {documents.length > 0 && `(${documents.length})`}
+              </Button>
+            </Group>
+
             <TableCard minWidth={760}>
               <DataTable
                 columns={documentColumns}
@@ -1316,9 +1318,7 @@ export default function CustomerDetailPage() {
                             <Anchor
                               component="button"
                               type="button"
-                              onClick={() =>
-                                void fetchViewableFile(f.id, f.name).then(view)
-                              }
+                              onClick={() => openFileInNewTab(f.id, f.name)}
                               size="xs"
                               style={{
                                 textDecoration:
@@ -1424,7 +1424,6 @@ export default function CustomerDetailPage() {
         onClose={() => setChangeRequestDoc(null)}
       />
 
-      {viewer}
     </PageContainer>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/services/files.service.ts b/apps/edr-freight-web/backoffice/src/services/files.service.ts
index 038b5a86d..c86a3beb4 100644
--- a/apps/edr-freight-web/backoffice/src/services/files.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/files.service.ts
@@ -25,6 +25,53 @@ export async function downloadBookingFile(
   URL.revokeObjectURL(url);
 }
 
+/**
+ * Open a stored file in its own browser tab.
+ *
+ * Two things make this less trivial than an `<a target="_blank">`:
+ * - `GET /files/:id` is authenticated, so the bytes have to come through the
+ *   axios client and be handed over as a blob URL (same reason as
+ *   {@link fetchViewableFile}).
+ * - The tab therefore has to be opened *synchronously*, inside the click
+ *   gesture, and filled once the download resolves — a `window.open()` after an
+ *   `await` is blocked as a popup. That also means a loop over several
+ *   documents opens one tab each, all within the same gesture.
+ *
+ * `noopener` is deliberately not passed: it makes `window.open` return null, and
+ * the handle is what lets us navigate the tab. `opener` is nulled instead.
+ */
+export function openFileInNewTab(id: string, filename: string): void {
+  const tab = window.open("", "_blank");
+  if (tab) {
+    tab.opener = null;
+    tab.document.title = filename;
+    if (tab.document.body) {
+      tab.document.body.textContent = `Opening ${filename}…`;
+    }
+  }
+  void filesService.download(id).then(
+    (blob) => {
+      const url = URL.createObjectURL(blob);
+      if (tab) tab.location.replace(url);
+      // Popup blocked — fall back to a save, so the click still does something.
+      else {
+        const a = document.createElement("a");
+        a.href = url;
+        a.download = filename;
+        a.click();
+      }
+      // Revoking immediately would cancel the tab's own load of the URL.
+      setTimeout(() => URL.revokeObjectURL(url), 60_000);
+    },
+    (error: unknown) => {
+      if (tab?.document.body) {
+        tab.document.body.textContent = `Could not open ${filename}.`;
+      }
+      console.error(`Failed to open file ${id}`, error);
+    },
+  );
+}
+
 /**
  * GET /files/:id is authenticated (global JwtGuard) — raw browser loads
  * (<img>/<iframe>/<a href>) carry no Bearer token and 401. Fetch the bytes
diff --git a/apps/edr-freight-web/backoffice/src/types/customer.ts b/apps/edr-freight-web/backoffice/src/types/customer.ts
index 87a71bf6e..7fa7d792a 100644
--- a/apps/edr-freight-web/backoffice/src/types/customer.ts
+++ b/apps/edr-freight-web/backoffice/src/types/customer.ts
@@ -111,7 +111,11 @@ export interface CompanyChangeRequest {
   /** Staged company-document add/remove intents (e.g. the PoA letter). */
   documentChanges: DocumentChangeIntent[];
   note: string | null;
+  /** Who filed the request — resolved from `iam.users`, null when unknown. */
+  submittedByName: string | null;
   submittedAt: string | null;
+  /** Who approved / rejected / sent it back. */
+  reviewedByName: string | null;
   reviewedAt: string | null;
   createdAt: string;
   updatedAt: string;
@@ -139,6 +143,8 @@ export interface CompanyRevision {
   id: string;
   companyId: string;
   actorId: string | null;
+  /** Who made the edit — resolved from `iam.users`, null when unknown. */
+  actorName: string | null;
   summary: string;
   changes: CompanyRevisionChange[];
   createdAt: string;

From ab734aecc30e210121dd605eb7c60cd50d44d0a9 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Mon, 17 Aug 2026 11:33:26 +0000
Subject: [PATCH 136/174] feat(chat): join users to rooms on sign-in

---
 .../modules/chat/chat-provisioning.service.ts | 59 ++++++++++--
 .../src/modules/chat/chat-sso.service.ts      | 62 +++++++++---
 .../src/modules/chat/matrix.client.spec.ts    | 35 +++++++
 .../src/modules/chat/matrix.client.ts         | 77 +++++++++++++--
 .../src/features/chat/useChatSso.ts           | 19 ----
 .../src/pages/chat/ChatLaunchPage.tsx         | 94 +++++++++++--------
 docker-compose.yaml                           |  4 +
 .../matrix/element/40-element-config.sh       | 18 ++++
 infrastructure/matrix/element/Dockerfile      | 16 +++-
 .../element/{config.json => config.json.tmpl} |  7 +-
 infrastructure/matrix/element/manifest.json   | 12 +++
 infrastructure/matrix/element/sso.html        | 47 ++++++----
 .../matrix/synapse/homeserver.yaml.tmpl       | 18 ++++
 scripts/deploy/sync-env-from-env-manager.sh   |  6 ++
 scripts/deploy/sync-env-from-server.sh        |  6 +-
 15 files changed, 366 insertions(+), 114 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/chat/matrix.client.spec.ts
 delete mode 100644 apps/edr-freight-web/backoffice/src/features/chat/useChatSso.ts
 create mode 100644 infrastructure/matrix/element/40-element-config.sh
 rename infrastructure/matrix/element/{config.json => config.json.tmpl} (61%)
 create mode 100644 infrastructure/matrix/element/manifest.json

diff --git a/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.ts b/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.ts
index 7b748e576..b122d8073 100644
--- a/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.ts
+++ b/apps/edr-freight-api/src/modules/chat/chat-provisioning.service.ts
@@ -67,7 +67,8 @@ export class ChatProvisioningService {
     }
   }
 
-  private async currentHolders(): Promise<PositionHolder[]> {
+  /** Every current holder in the unit, or just one person's rows when `userId` is given. */
+  private async currentHolders(userId?: string): Promise<PositionHolder[]> {
     return this.dataSource.query(
       `SELECT p.key AS "positionKey",
               COALESCE(p.name->>'en', p.key) AS "positionName",
@@ -82,11 +83,53 @@ export class ChatProvisioningService {
         WHERE ep.is_current = true
           AND e.is_current = true
           AND o.key = $1
-          AND u.key = $2`,
-      [ORG_KEY, UNIT_KEY],
+          AND u.key = $2
+          ${userId ? 'AND e.user_id = $3' : ''}`,
+      userId ? [ORG_KEY, UNIT_KEY, userId] : [ORG_KEY, UNIT_KEY],
     );
   }
 
+  /**
+   * Put one person in their rooms right now.
+   *
+   * {@link reconcile} is nightly, so without this a new employee's first
+   * sign-in shows an empty client until 3AM — the SSO handoff creates their
+   * account but joins them to nothing. Called on every /chat/sso, so it is
+   * scoped to the one user (a full reconcile per click would be a room-count
+   * multiple of Matrix calls) and every step is get-or-create.
+   *
+   * Someone holding no current position in the unit joins nothing, by the same
+   * rule the reconcile uses — chat membership follows the org tree.
+   */
+  async joinUserRooms(userId: string, displayName: string): Promise<number> {
+    const positions = await this.currentHolders(userId);
+    if (positions.length === 0) return 0;
+
+    const mxid = this.matrix.mxidFor(userId, displayName);
+    // The JWT login auto-registers too, but that happens after this runs and
+    // the admin join API 404s on an account that does not exist yet.
+    await this.matrix.ensureUser(mxid, displayName);
+
+    const spaceId = await this.matrix.ensureRoom(SPACE_ALIAS, 'EDR Freight', {
+      isSpace: true,
+    });
+    const generalRoomId = await this.matrix.ensureRoom(GENERAL_ALIAS, 'General', {
+      parentSpaceId: spaceId,
+    });
+    await this.matrix.ensureJoined(generalRoomId, mxid);
+
+    for (const position of positions) {
+      const roomId = await this.matrix.ensureRoom(
+        `dept-${position.positionKey}`,
+        position.positionName,
+        { parentSpaceId: spaceId },
+      );
+      await this.matrix.ensureJoined(roomId, mxid);
+    }
+
+    return positions.length + 1;
+  }
+
   /** Force-joins additions, kicks+deactivates users no longer entitled anywhere. */
   private async syncMembership(
     roomId: string,
@@ -99,7 +142,7 @@ export class ChatProvisioningService {
     let joined = 0;
     for (const userId of desiredUserIds) {
       if (!currentSet.has(userId)) {
-        await this.matrix.forceJoin(roomId, userId);
+        await this.matrix.ensureJoined(roomId, userId);
         joined += 1;
       }
     }
@@ -126,14 +169,16 @@ export class ChatProvisioningService {
       parentSpaceId: spaceId,
     });
 
-    const allUserIds = new Set(holders.map((h) => this.matrix.mxid(h.userId)));
+    const allUserIds = new Set(
+      holders.map((h) => this.matrix.mxidFor(h.userId, h.userName)),
+    );
 
     // Accounts are otherwise only created lazily on first JWT login (see
     // ChatSsoService) — force-joining someone who has never clicked "Chat"
     // yet 404s ("User not found") without this.
     const seenUserIds = new Set<string>();
     for (const h of holders) {
-      const mxid = this.matrix.mxid(h.userId);
+      const mxid = this.matrix.mxidFor(h.userId, h.userName);
       if (seenUserIds.has(mxid)) continue;
       seenUserIds.add(mxid);
       await this.matrix.ensureUser(mxid, h.userName);
@@ -158,7 +203,7 @@ export class ChatProvisioningService {
         name: h.positionName,
         userIds: new Set<string>(),
       };
-      entry.userIds.add(this.matrix.mxid(h.userId));
+      entry.userIds.add(this.matrix.mxidFor(h.userId, h.userName));
       byPosition.set(h.positionKey, entry);
     }
 
diff --git a/apps/edr-freight-api/src/modules/chat/chat-sso.service.ts b/apps/edr-freight-api/src/modules/chat/chat-sso.service.ts
index 8f9357e10..22edb8e1c 100644
--- a/apps/edr-freight-api/src/modules/chat/chat-sso.service.ts
+++ b/apps/edr-freight-api/src/modules/chat/chat-sso.service.ts
@@ -1,12 +1,13 @@
-import { Inject, Injectable } from '@nestjs/common';
+import { Inject, Injectable, Logger } from '@nestjs/common';
 import type { ConfigType } from '@nestjs/config';
 import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
 import { SignJWT } from 'jose';
 
 import chatConfig from '../../config/chat.config';
-import { MatrixClient } from './matrix.client';
+import { ChatProvisioningService } from './chat-provisioning.service';
+import { MatrixClient, chatLocalpart } from './matrix.client';
 
-/** Matrix login_tokens are single-use and expire in 5 minutes (Synapse default). */
+/** Long enough for one login call, short enough to be worthless if it leaks. */
 const JWT_TTL_SECONDS = 60;
 
 function displayName(user: TCurrentUser): string {
@@ -24,36 +25,67 @@ function displayName(user: TCurrentUser): string {
  *
  *   1. Sign a short-lived JWT asserting this user's id (Synapse's
  *      org.matrix.login.jwt auto-registers the account on first use).
- *   2. Trade that JWT for a real Matrix access token.
- *   3. Trade the access token for a one-shot login_token.
- *   4. Hand the caller a link to Element's sso.html shim, which seeds
- *      localStorage and forwards the token into Element's own login flow.
+ *   2. Trade that JWT for a real Matrix session.
+ *   3. Hand the caller a link to Element's sso.html shim, which writes that
+ *      session into localStorage and drops the user straight into Element.
+ *
+ * Step 3 used to mint a one-shot login_token and let Element redeem it. That
+ * path is capped at one request per user per minute by a limiter hardcoded in
+ * Synapse, so a second click inside a minute returned M_LIMIT_EXCEEDED — and a
+ * spent token surfaces in Element as "Incorrect username and/or password".
+ * Element accepts a plaintext token out of localStorage (Lifecycle.ts
+ * getStoredToken/tryDecryptToken), so handing over the session we already hold
+ * removes both failure modes and one round-trip.
  */
 @Injectable()
 export class ChatSsoService {
+  private readonly logger = new Logger(ChatSsoService.name);
+
   constructor(
     @Inject(chatConfig.KEY)
     private readonly config: ConfigType<typeof chatConfig>,
     private readonly matrix: MatrixClient,
+    private readonly provisioning: ChatProvisioningService,
   ) {}
 
   async getSsoUrl(user: TCurrentUser): Promise<{ url: string }> {
     const secret = new TextEncoder().encode(this.config.jwtSecret);
-    const jwt = await new SignJWT({ name: displayName(user) })
+    const name = displayName(user);
+
+    // Before the link, not after: the reconcile that fills rooms is nightly, so
+    // a first sign-in would otherwise open an empty client. Best-effort —
+    // failing to join a room is no reason to refuse someone a sign-in link.
+    try {
+      await this.provisioning.joinUserRooms(user.id, name);
+    } catch (err) {
+      this.logger.error(
+        `Room join on sign-in failed for ${user.id}: ${(err as Error).message}`,
+      );
+    }
+    // Synapse takes the localpart straight from `sub` on auto-registration, so
+    // this must be byte-identical to what ChatProvisioningService derives for
+    // the same person — otherwise SSO signs them into one account while the
+    // reconcile force-joins a different one into the rooms.
+    const jwt = await new SignJWT({ name })
       .setProtectedHeader({ alg: 'HS256' })
-      .setSubject(user.id)
+      .setSubject(chatLocalpart(user.id, name))
       .setIssuer('edr-freight-api')
       .setAudience('matrix')
       .setIssuedAt()
       .setExpirationTime(`${JWT_TTL_SECONDS}s`)
       .sign(secret);
 
-    const { access_token } = await this.matrix.loginWithJwt(jwt);
-    const { login_token } = await this.matrix.getLoginToken(access_token);
+    const session = await this.matrix.loginWithJwt(jwt);
 
-    const url = new URL(`${this.config.webUrl}/sso.html`);
-    url.searchParams.set('t', login_token);
-    url.searchParams.set('hs', this.config.publicBaseUrl);
-    return { url: url.toString() };
+    // Session goes in the URL fragment, never the query: a fragment is not sent
+    // to any server, so the token stays out of Element's access log, and
+    // sso.html replaces the entry so it does not linger in history either.
+    const params = new URLSearchParams({
+      hs: this.config.publicBaseUrl,
+      t: session.access_token,
+      u: session.user_id,
+      d: session.device_id,
+    });
+    return { url: `${this.config.webUrl}/sso.html#${params.toString()}` };
   }
 }
diff --git a/apps/edr-freight-api/src/modules/chat/matrix.client.spec.ts b/apps/edr-freight-api/src/modules/chat/matrix.client.spec.ts
new file mode 100644
index 000000000..ea5faa978
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/chat/matrix.client.spec.ts
@@ -0,0 +1,35 @@
+import { chatLocalpart } from './matrix.client';
+
+describe('chatLocalpart', () => {
+  it('reads from the name, not the id', () => {
+    expect(
+      chatLocalpart('03f5eb9e-23a0-4413-8d98-8de4b98b1be2', 'Nati Wondi'),
+    ).toBe('nati-wondi.03f5eb');
+  });
+
+  it('separates two people who share a name', () => {
+    // Both of these are real dev rows — same name, different employees.
+    const a = chatLocalpart('11111111-1111-4111-8111-111111111111', 'MARKOS REGASA');
+    const b = chatLocalpart('22222222-2222-4222-8222-222222222222', 'Markos  REGASA');
+    expect(a).not.toBe(b);
+  });
+
+  it('is stable for the same person', () => {
+    const id = '7d798218-09de-47a1-98eb-f61ec44e9280';
+    expect(chatLocalpart(id, 'Naod')).toBe(chatLocalpart(id, 'Naod'));
+  });
+
+  it('still yields a usable localpart for a name that slugs to nothing', () => {
+    expect(chatLocalpart('7d798218-09de-47a1-98eb-f61ec44e9280', 'ናኦድ')).toBe(
+      'user.7d7982',
+    );
+  });
+
+  it('only emits characters Matrix accepts in a localpart', () => {
+    for (const name of ['Mubarek Jemal Hassen', "N'gozi  O_Brien", 'ናኦድ', 'José']) {
+      expect(chatLocalpart('7d798218-09de-47a1-98eb-f61ec44e9280', name)).toMatch(
+        /^[a-z0-9._=\-/]+$/,
+      );
+    }
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/chat/matrix.client.ts b/apps/edr-freight-api/src/modules/chat/matrix.client.ts
index 01dafb6de..1cd09ac33 100644
--- a/apps/edr-freight-api/src/modules/chat/matrix.client.ts
+++ b/apps/edr-freight-api/src/modules/chat/matrix.client.ts
@@ -14,6 +14,32 @@ import chatConfig from '../../config/chat.config';
  * ChatBridgeService) — one bot/admin account covers both jobs, no separate
  * bot user needed.
  */
+/**
+ * Localpart of a staff member's MXID: their name, plus the first 6 hex of
+ * their freight user id.
+ *
+ * The tail is not decoration. Names collide — 19 of the 114 users in the dev
+ * IAM share a slug with someone else ("MARKOS REGASA" and "Markos  REGASA" are
+ * two different people) — and an MXID is permanent, so a bare slug would hand
+ * two employees the same Matrix account and each other's rooms. The id is
+ * already random, so 6 hex of it separates them without a lookup or a mapping
+ * table, and keeps the derivation pure: ChatSsoService (which mints the JWT
+ * `sub`) and ChatProvisioningService (which force-joins rooms) must agree on
+ * this string exactly or they provision two accounts per person.
+ */
+export function chatLocalpart(userId: string, displayName: string): string {
+  const slug = displayName
+    // NFKD splits an accent off its letter; the non-alnum sweep below then
+    // folds the leftover mark into the same `-` run as the neighbouring space.
+    .normalize('NFKD')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+  // Amharic-only names slug to nothing — the tail still makes it unique.
+  return `${slug || 'user'}.${userId.replace(/-/g, '').slice(0, 6)}`;
+}
+
 @Injectable()
 export class MatrixClient {
   constructor(
@@ -21,11 +47,28 @@ export class MatrixClient {
     private readonly config: ConfigType<typeof chatConfig>,
   ) {}
 
+  /**
+   * Alias localparts go in a URL path segment, so a `/` in one is fatal:
+   * Synapse decodes the path before routing, and `%2F` splits the request into
+   * a route that doesn't exist ("M_UNRECOGNIZED"). resolveAlias reads that 404
+   * as "no such room" and ensureRoom then tries to create the same broken alias
+   * on every run. Position keys are `edr_freight_app/opn` shaped, so this hits
+   * every dept room but the handful whose key happens to be a bare word.
+   */
+  private static aliasSafe(alias: string): string {
+    return alias.replace(/[^A-Za-z0-9._=-]/g, '-');
+  }
+
   /** `@<localpart>:<server_name>` — the one place this format is assembled. */
   mxid(localpart: string): string {
     return `@${localpart}:${this.config.serverName}`;
   }
 
+  /** The MXID of a freight user — see {@link chatLocalpart}. */
+  mxidFor(userId: string, displayName: string): string {
+    return this.mxid(chatLocalpart(userId, displayName));
+  }
+
   get serverName(): string {
     return this.config.serverName;
   }
@@ -123,15 +166,13 @@ export class MatrixClient {
     return Object.keys(res.joined);
   }
 
-  /** Exchange a fresh access token for a one-shot login_token (5 min TTL). */
-  getLoginToken(accessToken: string): Promise<{ login_token: string }> {
-    return this.request(
-      'POST',
-      '/_matrix/client/v1/login/get_token',
-      {},
-      accessToken,
-    );
-  }
+  // No getLoginToken here on purpose. POST /_matrix/client/v1/login/get_token
+  // is rate limited to 1 request per user per MINUTE, hardcoded in Synapse
+  // (rest/client/login_token_request.py: "Ratelimit aggressively … could be
+  // abused by a malicious client to create many sessions") and not settable
+  // from homeserver.yaml. A second click inside a minute got M_LIMIT_EXCEEDED.
+  // ChatSsoService hands Element the session from loginWithJwt directly
+  // instead, which needs no second call.
 
   /** null when the alias doesn't resolve to a room yet. */
   resolveAlias(alias: string): Promise<{ room_id: string } | null> {
@@ -180,10 +221,11 @@ export class MatrixClient {
    * on every reconcile run and every bridged notification alike.
    */
   async ensureRoom(
-    alias: string,
+    rawAlias: string,
     name: string,
     opts: { isSpace?: boolean; parentSpaceId?: string } = {},
   ): Promise<string> {
+    const alias = MatrixClient.aliasSafe(rawAlias);
     const existing = await this.resolveAlias(`#${alias}:${this.config.serverName}`);
     if (existing) return existing.room_id;
 
@@ -228,6 +270,21 @@ export class MatrixClient {
     );
   }
 
+  /**
+   * Force-join, treating "already a member" as success. Synapse answers a
+   * repeat join with 403 `M_FORBIDDEN: "<user> is already in the room."`, which
+   * is a failure only if you assumed you knew the membership first. Callers
+   * that just want someone in a room (sign-in, reconcile racing itself) want
+   * this; the raw 403 tells them nothing they can act on.
+   */
+  async ensureJoined(roomIdOrAlias: string, userId: string): Promise<void> {
+    try {
+      await this.forceJoin(roomIdOrAlias, userId);
+    } catch (err) {
+      if (!/already in the room/i.test((err as Error).message)) throw err;
+    }
+  }
+
   kick(roomId: string, userId: string, reason: string): Promise<void> {
     return this.request(
       'POST',
diff --git a/apps/edr-freight-web/backoffice/src/features/chat/useChatSso.ts b/apps/edr-freight-web/backoffice/src/features/chat/useChatSso.ts
deleted file mode 100644
index d25b5f4a1..000000000
--- a/apps/edr-freight-web/backoffice/src/features/chat/useChatSso.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { useQuery } from "@tanstack/react-query";
-
-import { chatApi } from "./chatApi";
-
-export const CHAT_SSO_KEY = ["chat", "sso"] as const;
-
-/**
- * The login_token this resolves to is single-use and expires in 5 minutes
- * (Synapse default) — the global `staleTime: 0` (queryClient.ts) already
- * means every fresh mount of the launch page refetches rather than reusing
- * a possibly-spent link.
- */
-export function useChatSso() {
-  return useQuery({
-    queryKey: CHAT_SSO_KEY,
-    queryFn: chatApi.getSsoUrl,
-    retry: false,
-  });
-}
diff --git a/apps/edr-freight-web/backoffice/src/pages/chat/ChatLaunchPage.tsx b/apps/edr-freight-web/backoffice/src/pages/chat/ChatLaunchPage.tsx
index 6b51b6512..78f0e7c36 100644
--- a/apps/edr-freight-web/backoffice/src/pages/chat/ChatLaunchPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/chat/ChatLaunchPage.tsx
@@ -1,17 +1,44 @@
-import { Alert, Button, Card, Center, Loader, Stack, Text } from "@mantine/core";
+import { Alert, Button, Card, Center, Stack, Text } from "@mantine/core";
 import { MessageSquare, TriangleAlert } from "lucide-react";
+import { useState } from "react";
 
 import { PageContainer, PageHeader } from "@/components/page";
-import { useChatSso } from "@/features/chat/useChatSso";
+import { chatApi } from "@/features/chat/chatApi";
 
 /**
  * Chat itself lives at chat.edr.et (Element), not in this app — this page's
- * only job is a fresh one-click sign-in link into it. A real `<a>` (not
- * `window.open()` in a click handler) so the browser never treats it as a
- * blocked popup, and no iframe: Element's own CSP refuses to be framed.
+ * only job is a one-click sign-in link into it. No iframe: Element's own CSP
+ * refuses to be framed.
+ *
+ * The link is minted per click, never on mount and never cached: Synapse's
+ * login_token is single-use and expires in 5 minutes, and Element reports a
+ * spent one as "Incorrect username and/or password". A held-onto url is
+ * therefore wrong on the second click, on a remount served from cache, and on
+ * any click more than 5 minutes after the page loaded.
  */
 export default function ChatLaunchPage() {
-  const { data: url, isLoading, isError, refetch } = useChatSso();
+  const [state, setState] = useState<"idle" | "loading" | "error">("idle");
+
+  const open = async () => {
+    // Opened before the await so it still counts as the user's click — a
+    // window.open() after it is treated as a popup and blocked.
+    //
+    // No "noopener" in the features: passing it makes window.open return null,
+    // which would leave this blank tab orphaned and send Element into the
+    // current tab instead. Clearing .opener on the handle does the same job.
+    const tab = window.open("", "_blank");
+    if (tab) tab.opener = null;
+    setState("loading");
+    try {
+      const url = await chatApi.getSsoUrl();
+      if (tab) tab.location.replace(url);
+      else window.location.assign(url); // popup blocked — go in this tab
+      setState("idle");
+    } catch {
+      tab?.close();
+      setState("error");
+    }
+  };
 
   return (
     <PageContainer>
@@ -19,41 +46,30 @@ export default function ChatLaunchPage() {
       <Card withBorder radius="md" p="xl">
         <Center>
           <Stack align="center" gap="md" py="xl">
-            {isLoading && <Loader />}
-
-            {isError && (
-              <Stack align="center" gap="sm">
-                <Alert
-                  icon={<TriangleAlert size={18} />}
-                  color="red"
-                  title="Couldn't get a sign-in link"
-                  variant="light"
-                >
-                  Something went wrong reaching chat. Try again.
-                </Alert>
-                <Button variant="light" onClick={() => refetch()}>
-                  Retry
-                </Button>
-              </Stack>
+            {state === "error" && (
+              <Alert
+                icon={<TriangleAlert size={18} />}
+                color="red"
+                title="Couldn't get a sign-in link"
+                variant="light"
+              >
+                Something went wrong reaching chat. Try again.
+              </Alert>
             )}
 
-            {url && (
-              <Stack align="center" gap="sm">
-                <MessageSquare size={40} strokeWidth={1.5} />
-                <Text c="dimmed" ta="center" maw={360}>
-                  Opens EDR Chat in a new tab, already signed in as you.
-                </Text>
-                <Button
-                  component="a"
-                  href={url}
-                  target="_blank"
-                  rel="noopener noreferrer"
-                  leftSection={<MessageSquare size={16} />}
-                >
-                  Open EDR Chat
-                </Button>
-              </Stack>
-            )}
+            <Stack align="center" gap="sm">
+              <MessageSquare size={40} strokeWidth={1.5} />
+              <Text c="dimmed" ta="center" maw={360}>
+                Opens EDR Chat in a new tab, already signed in as you.
+              </Text>
+              <Button
+                onClick={open}
+                loading={state === "loading"}
+                leftSection={<MessageSquare size={16} />}
+              >
+                Open EDR Chat
+              </Button>
+            </Stack>
           </Stack>
         </Center>
       </Card>
diff --git a/docker-compose.yaml b/docker-compose.yaml
index 050afc5df..a3f57ebb5 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -140,6 +140,10 @@ services:
       context: infrastructure/matrix/element
     ports:
       - "${ELEMENT_WEB_PORT:-8080}:80"
+    # config.json is rendered at container start, not baked — one image serves
+    # dev, staging and prod. See infrastructure/matrix/element/.env.example.
+    env_file:
+      - infrastructure/matrix/element/.env
     restart: always
 
 volumes:
diff --git a/infrastructure/matrix/element/40-element-config.sh b/infrastructure/matrix/element/40-element-config.sh
new file mode 100644
index 000000000..9826a5fc7
--- /dev/null
+++ b/infrastructure/matrix/element/40-element-config.sh
@@ -0,0 +1,18 @@
+#!/bin/sh
+# Renders /app/config.json from config.json.tmpl at container start.
+#
+# The homeserver URL and server_name differ per environment, and config.json is
+# read by the browser rather than the build, so baking it into the image would
+# mean one image per environment. Dropped into /docker-entrypoint.d, which the
+# upstream nginx entrypoint runs (in lexical order) before starting nginx —
+# no ENTRYPOINT override, so the image's own startup work still happens.
+set -eu
+
+: "${MATRIX_PUBLIC_BASEURL:?MATRIX_PUBLIC_BASEURL is required}"
+: "${MATRIX_SERVER_NAME:?MATRIX_SERVER_NAME is required}"
+: "${ELEMENT_PUBLIC_URL:?ELEMENT_PUBLIC_URL is required}"
+
+envsubst '${MATRIX_PUBLIC_BASEURL} ${MATRIX_SERVER_NAME} ${ELEMENT_PUBLIC_URL}' \
+  < /app/config.json.tmpl > /app/config.json
+
+echo "element-config: homeserver ${MATRIX_PUBLIC_BASEURL} (${MATRIX_SERVER_NAME})"
diff --git a/infrastructure/matrix/element/Dockerfile b/infrastructure/matrix/element/Dockerfile
index 5ab02cd9b..330098af6 100644
--- a/infrastructure/matrix/element/Dockerfile
+++ b/infrastructure/matrix/element/Dockerfile
@@ -5,5 +5,19 @@
 # Pin the tag; never float on `latest`.
 FROM ghcr.io/element-hq/element-web:v1.11.108
 
-COPY config.json /app/config.json
+COPY config.json.tmpl /app/config.json.tmpl
 COPY sso.html /app/sso.html
+# Replaces the upstream manifest, which names the app "Element" and advertises
+# the Play/App Store builds under related_applications. Those apps cannot log
+# in here — this deployment has no password login and no SSO provider, only the
+# JWT handoff from freight-api — so pointing staff at them is a dead end.
+COPY manifest.json /app/manifest.json
+COPY 40-element-config.sh /docker-entrypoint.d/40-element-config.sh
+
+# The image runs as uid 101 (nginx) but ships /app root-owned, so the startup
+# hook could not write the rendered config without this.
+USER root
+RUN chmod +x /docker-entrypoint.d/40-element-config.sh \
+    && touch /app/config.json \
+    && chown nginx:nginx /app/config.json
+USER nginx
diff --git a/infrastructure/matrix/element/config.json b/infrastructure/matrix/element/config.json.tmpl
similarity index 61%
rename from infrastructure/matrix/element/config.json
rename to infrastructure/matrix/element/config.json.tmpl
index 6f988d3e9..f08900601 100644
--- a/infrastructure/matrix/element/config.json
+++ b/infrastructure/matrix/element/config.json.tmpl
@@ -1,16 +1,17 @@
 {
   "default_server_config": {
     "m.homeserver": {
-      "base_url": "https://matrix.edr.et",
-      "server_name": "matrix.edr.et"
+      "base_url": "${MATRIX_PUBLIC_BASEURL}",
+      "server_name": "${MATRIX_SERVER_NAME}"
     }
   },
   "brand": "EDR Chat",
-  "permalink_prefix": "https://chat.edr.et",
+  "permalink_prefix": "${ELEMENT_PUBLIC_URL}",
   "disable_guests": true,
   "disable_3pid_login": true,
   "disable_custom_urls": true,
   "default_theme": "light",
+  "mobile_guide_toast": false,
   "settingDefaults": {
     "UIFeature.registration": false
   }
diff --git a/infrastructure/matrix/element/manifest.json b/infrastructure/matrix/element/manifest.json
new file mode 100644
index 000000000..75f5f33e6
--- /dev/null
+++ b/infrastructure/matrix/element/manifest.json
@@ -0,0 +1,12 @@
+{
+  "name": "EDR Chat",
+  "short_name": "EDR Chat",
+  "display": "standalone",
+  "theme_color": "#0dbd8b",
+  "start_url": "index.html",
+  "icons": [
+    { "src": "/vector-icons/150.png", "sizes": "150x150", "type": "image/png" },
+    { "src": "/vector-icons/300.png", "sizes": "300x300", "type": "image/png" },
+    { "src": "/vector-icons/1024.png", "sizes": "1024x1024", "type": "image/png" }
+  ]
+}
diff --git a/infrastructure/matrix/element/sso.html b/infrastructure/matrix/element/sso.html
index 59a458fa4..77f378122 100644
--- a/infrastructure/matrix/element/sso.html
+++ b/infrastructure/matrix/element/sso.html
@@ -1,16 +1,23 @@
 <!doctype html>
 <!--
-  Element only honours a `?loginToken=` on `/` if `mx_sso_hs_url` is already
-  in localStorage (element-web apps/web/src/Lifecycle.ts attemptTokenLogin,
-  key defined in apps/web/src/BasePlatform.ts). Normally that key is written
-  by Element itself at the start of an SSO redirect; freight-api's SSO
-  handoff skips that redirect (it already knows the homeserver), so this
-  page seeds the key by hand and forwards straight to the login-token URL.
+  Session handoff from freight-api into Element.
 
   freight-api's chat-sso.service.ts links here as
-  https://chat.edr.et/sso.html?t=<login_token>&hs=<homeserver base_url>.
-  `hs` is passed rather than hardcoded so this file doesn't need to change if
-  MATRIX_PUBLIC_BASEURL ever does.
+  https://chat.edr.et/sso.html#hs=<homeserver>&t=<access_token>&u=<user_id>&d=<device_id>
+  — a fragment, not a query, so the token is never sent to a server and never
+  lands in an access log. location.replace() below drops this URL from history
+  as well, so the token does not survive the redirect.
+
+  The keys written here are the ones Element reads on startup
+  (element-web src/Lifecycle.ts getStoredSessionVars/getStoredToken): the token
+  is looked up in IndexedDB first and falls back to localStorage, which Element
+  then migrates into IndexedDB itself. A plaintext token is accepted —
+  tryDecryptToken returns a string token as-is, and only decrypts when it finds
+  an encrypted payload.
+
+  This replaced a ?loginToken= handoff: POST /_matrix/client/v1/login/get_token
+  is capped at one call per user per minute by a limiter hardcoded in Synapse,
+  so clicking Chat twice in a minute failed.
 -->
 <html lang="en">
   <head>
@@ -19,17 +26,23 @@
   </head>
   <body>
     <script>
-      var params = new URLSearchParams(window.location.search);
-      var token = params.get("t");
+      var params = new URLSearchParams(window.location.hash.slice(1));
       var homeserver = params.get("hs");
-      if (token && homeserver) {
-        localStorage.setItem("mx_sso_hs_url", homeserver);
-        window.location.replace(
-          "/?loginToken=" + encodeURIComponent(token),
-        );
+      var token = params.get("t");
+      var userId = params.get("u");
+      var deviceId = params.get("d");
+
+      if (homeserver && token && userId && deviceId) {
+        localStorage.setItem("mx_hs_url", homeserver);
+        localStorage.setItem("mx_user_id", userId);
+        localStorage.setItem("mx_device_id", deviceId);
+        localStorage.setItem("mx_access_token", token);
+        localStorage.setItem("mx_has_access_token", "true");
+        localStorage.setItem("mx_is_guest", "false");
+        window.location.replace("/");
       } else {
         document.body.textContent =
-          "Missing sign-in token. Go back to the EDR backoffice and click Chat again.";
+          "Missing sign-in details. Go back to the EDR backoffice and click Chat again.";
       }
     </script>
   </body>
diff --git a/infrastructure/matrix/synapse/homeserver.yaml.tmpl b/infrastructure/matrix/synapse/homeserver.yaml.tmpl
index 2f7d59502..efb7372ac 100644
--- a/infrastructure/matrix/synapse/homeserver.yaml.tmpl
+++ b/infrastructure/matrix/synapse/homeserver.yaml.tmpl
@@ -42,6 +42,24 @@ federation_domain_whitelist: []
 enable_registration: false
 encryption_enabled_by_default_for_room_type: "off"
 
+# Turning rooms' encryption off above is not enough on its own: Element still
+# bootstraps cross-signing on a user's first login, and from then on gates
+# EVERY later login behind "Verify this device" (MatrixChat: crossSigningIsSetUp
+# -> Views.COMPLETE_SECURITY). Nobody on this deployment can clear that gate —
+# each SSO click is a brand-new device, so there is never a second verified
+# device to accept the request, and resetting the identity needs UIA, which
+# password_config.enabled: false makes impossible.
+#
+# This tells Element encryption is off here, so it skips the bootstrap
+# (shouldSkipSetupEncryption) and the gate is never armed. Only helps accounts
+# that have no cross-signing keys yet — anyone already bootstrapped keeps
+# hitting the gate until their keys are cleared.
+extra_well_known_client_content:
+  io.element.e2ee:
+    default: false
+    force_disable: true
+    secure_backup_required: false
+
 # Employees authenticate via freight-api's SSO handoff, never a Matrix
 # password prompt. This is the entire auth story for this deployment.
 password_config:
diff --git a/scripts/deploy/sync-env-from-env-manager.sh b/scripts/deploy/sync-env-from-env-manager.sh
index 6a405ab28..0835f86d9 100644
--- a/scripts/deploy/sync-env-from-env-manager.sh
+++ b/scripts/deploy/sync-env-from-env-manager.sh
@@ -29,6 +29,12 @@ declare -A SERVICE_ENV_TARGET=(
   ["passenger_portal"]="apps/edr-passenger-web/portal/.env"
   ["passenger_backoffice"]="apps/edr-passenger-web/backoffice/.env"
   ["payment_api"]="apps/edr-payment-api/.env"
+  ["synapse"]="infrastructure/matrix/synapse/.env"
+  # element_web holds no secrets, but its config.json is rendered at container
+  # start from MATRIX_PUBLIC_BASEURL / MATRIX_SERVER_NAME / ELEMENT_PUBLIC_URL
+  # (see infrastructure/matrix/element), so it needs an env file like the rest —
+  # plus the PORT line every service env is required to carry.
+  ["element_web"]="infrastructure/matrix/element/.env"
 )
 
 for service in "$@"; do
diff --git a/scripts/deploy/sync-env-from-server.sh b/scripts/deploy/sync-env-from-server.sh
index 1e9a1ff52..4fb7fbe6b 100644
--- a/scripts/deploy/sync-env-from-server.sh
+++ b/scripts/deploy/sync-env-from-server.sh
@@ -32,9 +32,9 @@ declare -A SERVICE_ENV_TARGET=(
   ["passenger-backoffice"]="apps/edr-passenger-web/backoffice/.env"
   ["payment-api"]="apps/edr-payment-api/.env"
   ["synapse"]="infrastructure/matrix/synapse/.env"
-  # element-web has no runtime secrets (its config.json is baked into the
-  # image), but the sync step still runs unconditionally per service and
-  # needs a PORT= line to compute ELEMENT_WEB_PORT for docker compose.
+  # element-web holds no secrets, but its config.json is rendered at container
+  # start from MATRIX_PUBLIC_BASEURL / MATRIX_SERVER_NAME / ELEMENT_PUBLIC_URL,
+  # and the sync step needs a PORT= line to compute ELEMENT_WEB_PORT anyway.
   ["element-web"]="infrastructure/matrix/element/.env"
 )
 

From 7946c1632747d4e72c354fc1d8cedd29af60184c Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 17 Aug 2026 14:05:47 +0000
Subject: [PATCH 137/174] feat(eims): bake in a starter table of Ethiopia
 region/zone/woreda codes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

EIMS_BUYER_REGION_CODES/WEREDA_CODES/CITY_CODES were hand-maintained,
empty-by-default env vars — every buyer from a not-yet-seen area
crashed filing until someone found the MoR code and redeployed.
Happened three times in one afternoon (2026-08-17): Somali region,
Fafan zone, Jigjiga woreda, even the Ethiopia country code were all
unset on the triaplc.com deployment.

Ethiopia's administrative divisions are fixed reference data, not
buyer-specific config. Added ethiopia-geo-codes.ts, a static table
(source: ethiopia_administrative_hierarchy_master.csv, supplied
2026-08-17 — a representative sample, not all ~1000 real woredas)
merged in as the fallback under the existing env vars, which still
win on a name collision — for a quick correction without a redeploy,
or a buyer profile spelled differently than the table (already hit:
DB has zone "Fafen", official spelling "Fafan").

Known limitation, documented in the file: zone/woreda names aren't
always unique nationwide (e.g. "North Shewa" is both an Amhara and
an Oromia zone) and Company stores region/zone/woreda as three
independent strings with no parent linkage, so a flat name map can't
always disambiguate. Only affects the optional City field — never
blocks filing, unlike Region/Wereda.
---
 .../src/config/eims.config.spec.ts            |  44 ++++++
 .../edr-freight-api/src/config/eims.config.ts |  10 +-
 .../src/config/ethiopia-geo-codes.ts          | 139 ++++++++++++++++++
 3 files changed, 190 insertions(+), 3 deletions(-)
 create mode 100644 apps/edr-freight-api/src/config/ethiopia-geo-codes.ts

diff --git a/apps/edr-freight-api/src/config/eims.config.spec.ts b/apps/edr-freight-api/src/config/eims.config.spec.ts
index a6aa3895d..60ee33e1b 100644
--- a/apps/edr-freight-api/src/config/eims.config.spec.ts
+++ b/apps/edr-freight-api/src/config/eims.config.spec.ts
@@ -70,3 +70,47 @@ describe("eims.config — private key / certificate resolution", () => {
     );
   });
 });
+
+describe("eims.config — baked-in Ethiopia region/zone/woreda codes", () => {
+  it("resolves a known region/wereda/zone with no env var set at all", () => {
+    withEnv(
+      { ...REQUIRED, EIMS_PRIVATE_KEY: "x", EIMS_CERTIFICATE_PATH: "/dev/null" },
+      () => {
+        const cfg = eimsConfigFactory();
+        expect(cfg.invoice.buyerRegionCodes.Somali).toBe("05");
+        expect(cfg.invoice.buyerWeredaCodes["Jijiga Town"]).toBe("02");
+        expect(cfg.invoice.buyerCityCodes.Fafan).toBe("01");
+      },
+    );
+  });
+
+  it("an env var entry overrides the baked-in code for the same name", () => {
+    withEnv(
+      {
+        ...REQUIRED,
+        EIMS_PRIVATE_KEY: "x",
+        EIMS_CERTIFICATE_PATH: "/dev/null",
+        EIMS_BUYER_REGION_CODES: "Somali=99",
+      },
+      () => {
+        expect(eimsConfigFactory().invoice.buyerRegionCodes.Somali).toBe("99");
+      },
+    );
+  });
+
+  it("an env var still adds a name the baked-in table doesn't have (a spelling variant)", () => {
+    withEnv(
+      {
+        ...REQUIRED,
+        EIMS_PRIVATE_KEY: "x",
+        EIMS_CERTIFICATE_PATH: "/dev/null",
+        EIMS_BUYER_CITY_CODES: "Fafen=01",
+      },
+      () => {
+        const codes = eimsConfigFactory().invoice.buyerCityCodes;
+        expect(codes.Fafen).toBe("01");
+        expect(codes.Fafan).toBe("01"); // baked-in entry still present alongside it
+      },
+    );
+  });
+});
diff --git a/apps/edr-freight-api/src/config/eims.config.ts b/apps/edr-freight-api/src/config/eims.config.ts
index 9d99ae455..e5530eaf2 100644
--- a/apps/edr-freight-api/src/config/eims.config.ts
+++ b/apps/edr-freight-api/src/config/eims.config.ts
@@ -1,5 +1,7 @@
 import { registerAs } from "@nestjs/config";
 
+import { ETHIOPIA_REGION_CODES, ETHIOPIA_WOREDA_CODES, ETHIOPIA_ZONE_CODES } from "./ethiopia-geo-codes";
+
 /**
  * Ethiopian MoR EIMS e-invoicing gateway.
  *
@@ -258,9 +260,11 @@ export default registerAs("eims", (): EimsConfig => {
       unitDefault: process.env.EIMS_UNIT_DEFAULT ?? "",
       buyerCountryCode: process.env.EIMS_BUYER_COUNTRY_CODE || null,
       buyerCountryCodes: parseCodeMap(process.env.EIMS_BUYER_COUNTRY_CODES),
-      buyerRegionCodes: parseCodeMap(process.env.EIMS_BUYER_REGION_CODES),
-      buyerWeredaCodes: parseCodeMap(process.env.EIMS_BUYER_WEREDA_CODES),
-      buyerCityCodes: parseCodeMap(process.env.EIMS_BUYER_CITY_CODES),
+      // Baked-in Ethiopia reference table first, env var entries win on a name collision — lets a
+      // deployment override or add to it without a redeploy. See ethiopia-geo-codes.ts.
+      buyerRegionCodes: { ...ETHIOPIA_REGION_CODES, ...parseCodeMap(process.env.EIMS_BUYER_REGION_CODES) },
+      buyerWeredaCodes: { ...ETHIOPIA_WOREDA_CODES, ...parseCodeMap(process.env.EIMS_BUYER_WEREDA_CODES) },
+      buyerCityCodes: { ...ETHIOPIA_ZONE_CODES, ...parseCodeMap(process.env.EIMS_BUYER_CITY_CODES) },
       taxCodeByChargeType: parseCodeMap(process.env.EIMS_TAX_CODE_BY_CHARGE_TYPE),
       taxRateByChargeType: parseCodeMap(process.env.EIMS_TAX_RATE_BY_CHARGE_TYPE),
       exciseByChargeType: parseCodeMap(process.env.EIMS_EXCISE_BY_CHARGE_TYPE),
diff --git a/apps/edr-freight-api/src/config/ethiopia-geo-codes.ts b/apps/edr-freight-api/src/config/ethiopia-geo-codes.ts
new file mode 100644
index 000000000..f7257e045
--- /dev/null
+++ b/apps/edr-freight-api/src/config/ethiopia-geo-codes.ts
@@ -0,0 +1,139 @@
+/**
+ * MoR EIMS region/zone/woreda codes, by name — the baked-in fallback under
+ * `EIMS_BUYER_REGION_CODES`/`EIMS_BUYER_WEREDA_CODES`/`EIMS_BUYER_CITY_CODES` (zone is the closest
+ * match to EIMS's "City", per `eims-invoice.mapper.ts`).
+ *
+ * Before this existed, every buyer from a not-yet-seen region/zone/woreda crashed EIMS filing until
+ * someone hunted down the code and added it to an env var by hand — happened three times in one
+ * afternoon (2026-08-17: Somali region, Fafan zone, Jigjiga woreda, even the Ethiopia country code
+ * itself were all unset). Ethiopia's administrative divisions are fixed, known, reference data, not
+ * something that should be maintained reactively per buyer. Source: `ethiopia_administrative_
+ * hierarchy_master.csv`, supplied 2026-08-17 — NOT exhaustive (a representative sample per region,
+ * not all ~1000 real woredas), extend as new gaps surface.
+ *
+ * The env vars stay wired in ahead of this table (see `eims.config.ts`) — for a quick correction
+ * without a redeploy, or a name spelled differently in a buyer's profile than in this table (already
+ * hit live: DB has zone "Fafen", this table's official spelling is "Fafan" — same zone, matching is
+ * case/space-insensitive but not spelling-tolerant, so the env var override is still how that buyer
+ * actually resolves; this table mainly helps the *next* buyer whose profile spelling matches).
+ *
+ * ponytail: region names are unique nationwide (only ~15), safe as a flat map. Zone and woreda names
+ * are not always unique across different regions (e.g. "North Shewa" is both an Amhara zone and an
+ * Oromia zone, different codes) — `Company` stores region/zone/woreda as three independent strings,
+ * no parent linkage, so a flat name lookup can't disambiguate. First occurrence in the source data
+ * wins on a collision. Only affects the optional `City` field (zone) — never blocks filing, unlike
+ * Region/Wereda. A correct fix needs `Company` to store a linked hierarchy, not just three strings;
+ * out of scope here. Upgrade path: key this by `${region}/${zone}` once that linkage exists.
+ */
+const ROWS: Array<[region: string, zone: string, woreda: string, regionCode: string, zoneCode: string, woredaCode: string]> = [
+  ["Tigray", "Western Tigray", "Humera", "01", "01", "01"],
+  ["Tigray", "Western Tigray", "Kafta Humera", "01", "01", "02"],
+  ["Tigray", "Western Tigray", "Tsegede", "01", "01", "03"],
+  ["Tigray", "North Western Tigray", "Shire Endaselassie", "01", "02", "01"],
+  ["Tigray", "North Western Tigray", "Sheraro", "01", "02", "02"],
+  ["Tigray", "Central Tigray", "Axum", "01", "03", "01"],
+  ["Tigray", "Central Tigray", "Adwa", "01", "03", "02"],
+  ["Tigray", "Eastern Tigray", "Adigrat", "01", "04", "01"],
+  ["Tigray", "Southern Tigray", "Maychew", "01", "05", "01"],
+  ["Tigray", "Mekelle Special Zone", "Mekelle City", "01", "06", "01"],
+  ["Afar", "Awusi Rasu (Zone 1)", "Asayita", "02", "01", "01"],
+  ["Afar", "Awusi Rasu (Zone 1)", "Semera-Logiya", "02", "01", "02"],
+  ["Afar", "Kilbet Rasu (Zone 2)", "Abala", "02", "02", "01"],
+  ["Afar", "Gabi Rasu (Zone 3)", "Awash Fentale", "02", "03", "01"],
+  ["Afar", "Fantena Rasu (Zone 4)", "Yalo", "02", "04", "01"],
+  ["Afar", "Hari Rasu (Zone 5)", "Telalak", "02", "05", "01"],
+  ["Amhara", "North Gondar", "Debark", "03", "01", "01"],
+  ["Amhara", "South Gondar", "Debre Tabor", "03", "02", "01"],
+  ["Amhara", "North Wollo", "Woldiya", "03", "03", "01"],
+  ["Amhara", "South Wollo", "Dessie Town", "03", "04", "01"],
+  ["Amhara", "North Shewa", "Debre Berhan", "03", "05", "01"],
+  ["Amhara", "East Gojjam", "Debre Markos", "03", "06", "01"],
+  ["Amhara", "West Gojjam", "Finote Selam", "03", "07", "01"],
+  ["Amhara", "Wag Hemra", "Sekota", "03", "08", "01"],
+  ["Amhara", "Awi", "Injibara", "03", "09", "01"],
+  ["Amhara", "Oromia Special Zone", "Kemise", "03", "10", "01"],
+  ["Amhara", "Bahir Dar Special Zone", "Bahir Dar City", "03", "11", "01"],
+  ["Amhara", "Gondar Special Zone", "Gondar City", "03", "12", "01"],
+  ["Oromia", "North Shewa", "Fiche", "04", "01", "01"],
+  ["Oromia", "South West Shewa", "Waliso", "04", "02", "01"],
+  ["Oromia", "East Shewa", "Adama Town", "04", "03", "01"],
+  ["Oromia", "East Shewa", "Bishoftu Town", "04", "03", "02"],
+  ["Oromia", "West Shewa", "Ambo", "04", "04", "01"],
+  ["Oromia", "Arsi", "Asella", "04", "05", "01"],
+  ["Oromia", "West Arsi", "Shashemene", "04", "06", "01"],
+  ["Oromia", "Bale", "Robe", "04", "07", "01"],
+  ["Oromia", "East Hararghe", "Harar Outskirts", "04", "08", "01"],
+  ["Oromia", "West Hararghe", "Chiro", "04", "09", "01"],
+  ["Oromia", "Jimma", "Jimma Town", "04", "10", "01"],
+  ["Oromia", "Illubabor", "Mettu", "04", "11", "01"],
+  ["Oromia", "Buno Bedele", "Bedele", "04", "12", "01"],
+  ["Oromia", "Welega (West)", "Gimbi", "04", "13", "01"],
+  ["Oromia", "Welega (East)", "Nekemte", "04", "14", "01"],
+  ["Oromia", "Horo Guduru Welega", "Shambu", "04", "15", "01"],
+  ["Oromia", "Kelam Welega", "Dembidolo", "04", "16", "01"],
+  ["Oromia", "Borena", "Yabelo", "04", "17", "01"],
+  ["Oromia", "Guji", "Negele Borana", "04", "18", "01"],
+  ["Oromia", "West Guji", "Bule Hora", "04", "19", "01"],
+  ["Oromia", "East Bale", "Ginir", "04", "20", "01"],
+  ["Oromia", "Sheger City", "Sululta", "04", "21", "01"],
+  ["Somali", "Fafan", "Jijiga Woreda", "05", "01", "01"],
+  ["Somali", "Fafan", "Jijiga Town", "05", "01", "02"],
+  ["Somali", "Fafan", "Awbare", "05", "01", "03"],
+  ["Somali", "Sitti", "Shinile", "05", "02", "01"],
+  ["Somali", "Erer", "Fiq", "05", "03", "01"],
+  ["Somali", "Jarar", "Degehabur", "05", "04", "01"],
+  ["Somali", "Nogob", "Segeg", "05", "05", "01"],
+  ["Somali", "Korahe", "Kebridehar", "05", "06", "01"],
+  ["Somali", "Shabelle", "Gode", "05", "07", "01"],
+  ["Somali", "Afder", "Afder Woreda", "05", "08", "01"],
+  ["Somali", "Liben", "Filtu", "05", "09", "01"],
+  ["Somali", "Dhawa", "Mubarak", "05", "10", "01"],
+  ["Somali", "Dollo", "Warder", "05", "11", "01"],
+  ["Benishangul-Gumuz", "Asosa", "Asosa Woreda", "06", "01", "01"],
+  ["Benishangul-Gumuz", "Kamasashi", "Kamasashi Woreda", "06", "02", "01"],
+  ["Benishangul-Gumuz", "Metekel", "Gilgel Beles", "06", "03", "01"],
+  ["Southern Ethiopia", "Wolayta", "Sodo Zuria", "07", "01", "01"],
+  ["Southern Ethiopia", "Wolayta", "Sodo Town", "07", "01", "02"],
+  ["Southern Ethiopia", "Gamo", "Arba Minch Town", "07", "02", "01"],
+  ["Southern Ethiopia", "Gofa", "Sawla", "07", "03", "01"],
+  ["Southern Ethiopia", "Konso", "Konso Woreda", "07", "04", "01"],
+  ["Southern Ethiopia", "South Omo", "Jinka", "07", "05", "01"],
+  ["Gambela", "Anywaa", "Gambela Zuria", "08", "01", "01"],
+  ["Gambela", "Nuer", "Lare", "08", "02", "01"],
+  ["Gambela", "Majang", "Metu Zuria part", "08", "03", "01"],
+  ["Harari", "Harar Hundanee", "Amir Nur Woreda", "09", "01", "01"],
+  ["Harari", "Harar Hundanee", "Abadir Woreda", "09", "01", "02"],
+  ["Addis Ababa", "Bole Sub-City", "Bole Woreda 01", "10", "01", "01"],
+  ["Addis Ababa", "Kirkos Sub-City", "Kirkos Woreda 01", "10", "02", "01"],
+  ["Addis Ababa", "Nifas Silk Lafto", "NSL Woreda 13", "10", "03", "13"],
+  ["Addis Ababa", "Yeka Sub-City", "Yeka Woreda 01", "10", "04", "01"],
+  ["Addis Ababa", "Arada Sub-City", "Arada Woreda 01", "10", "05", "01"],
+  ["Dire Dawa", "Dire Dawa Urban", "Melka Jebdu", "11", "01", "01"],
+  ["Dire Dawa", "Dire Dawa Rural", "Gurgura", "11", "02", "01"],
+  ["Sidama", "Hawassa City Admin", "Hayek Chereka", "12", "01", "01"],
+  ["Sidama", "Sidama Zuria", "Yirgalem Town", "12", "02", "01"],
+  ["Sidama", "Sidama Zuria", "Aleta Wendo", "12", "02", "02"],
+  ["Southwest Ethiopia", "Keffa", "Bonga Town", "13", "01", "01"],
+  ["Southwest Ethiopia", "Sheka", "Mappi Zuria", "13", "02", "01"],
+  ["Southwest Ethiopia", "Bench Sheko", "Mizan Aman", "13", "03", "01"],
+  ["Central Ethiopia", "Gurage", "Wolkite", "14", "01", "01"],
+  ["Central Ethiopia", "Hadiya", "Hosaina", "14", "02", "01"],
+  ["Central Ethiopia", "Silte", "Worabe", "14", "03", "01"],
+  ["Gedeo State", "Gedeo Zone", "Dilla Zuria", "15", "01", "01"],
+  ["Gedeo State", "Gedeo Zone", "Yirgacheffe", "15", "01", "02"],
+];
+
+/** First occurrence wins on a name collision — see the class comment. */
+const buildMap = (pick: (row: (typeof ROWS)[number]) => [string, string]): Record<string, string> => {
+  const map: Record<string, string> = {};
+  for (const row of ROWS) {
+    const [name, code] = pick(row);
+    if (!(name in map)) map[name] = code;
+  }
+  return map;
+};
+
+export const ETHIOPIA_REGION_CODES: Record<string, string> = buildMap((r) => [r[0], r[3]]);
+/** Zone name → code. Fed into `buyerCityCodes` — EIMS's "City" is really the buyer's zone. */
+export const ETHIOPIA_ZONE_CODES: Record<string, string> = buildMap((r) => [r[1], r[4]]);
+export const ETHIOPIA_WOREDA_CODES: Record<string, string> = buildMap((r) => [r[2], r[5]]);

From 7d8ab932c201d5fbd379f44d8e82eb42fbf89629 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 17 Aug 2026 17:33:58 +0000
Subject: [PATCH 138/174] feat(eims): implement POST /v1/bulkCancel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New endpoint: POST invoices/eims/bulk-cancel, body { items: [{invoiceId,
reasonCode, remark?}] }. Same eimsCancel permission as single cancel — a
batch-scale version of the same irreversible-at-MoR action, not a new
capability.

Same local-eligibility doctrine as single cancel: an already-cancelled or
never-registered invoice is refused right here, no HTTP call, before it
gets a seat in the batch. Only genuinely eligible invoices go into the one
/v1/bulkCancel request; every outcome (local refusal or MoR's own
per-IRN result) is reported back independently — one invoice failing
never blocks the rest.

MoR's bulk response mixes success and error shapes in the same array,
disambiguated by Status (capital, error) vs status (lowercase, success)
— matched back to our invoices by IRN. Notably the bulk success shape
carries no cancellationDate at all, unlike single cancel.

Left out of this pass: bulkRegister. It's async (returns only a
conversationId immediately, results arrive via a webhook callback we
don't have yet) and needs manual counter/previousIrn management per
the collection's own docs — a materially different reservation model
than today's single-invoice TX1/TX2 pattern. Scoping that is a
separate, bigger piece of work.
---
 .../dto/bulk-cancel-eims-registration.dto.ts  |  33 ++++++
 .../eims/eims-cancellation.service.spec.ts    | 104 +++++++++++++++++
 .../modules/eims/eims-cancellation.service.ts | 106 +++++++++++++++++-
 .../modules/eims/eims-invoice.controller.ts   |  12 ++
 .../modules/eims/eims-registration.types.ts   |  40 +++++++
 5 files changed, 294 insertions(+), 1 deletion(-)
 create mode 100644 apps/edr-freight-api/src/modules/eims/dto/bulk-cancel-eims-registration.dto.ts

diff --git a/apps/edr-freight-api/src/modules/eims/dto/bulk-cancel-eims-registration.dto.ts b/apps/edr-freight-api/src/modules/eims/dto/bulk-cancel-eims-registration.dto.ts
new file mode 100644
index 000000000..c4782782c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/eims/dto/bulk-cancel-eims-registration.dto.ts
@@ -0,0 +1,33 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { Type } from "class-transformer";
+import { ArrayMinSize, IsArray, IsOptional, IsString, IsUUID, Length, ValidateNested } from "class-validator";
+
+export class BulkCancelEimsItemDto {
+  @ApiProperty({ description: "Invoice ID to cancel." })
+  @IsUUID()
+  invoiceId!: string;
+
+  @ApiProperty({
+    description: 'Numeric reason code, e.g. "1" (Duplicate), "6" (Calculation Error).',
+    example: "1",
+  })
+  @IsString()
+  @Length(1, 8)
+  reasonCode!: string;
+
+  @ApiPropertyOptional({ description: "Free-text cancellation note.", example: "Duplicate submission" })
+  @IsOptional()
+  @IsString()
+  @Length(0, 500)
+  remark?: string;
+}
+
+/** `POST invoices/eims/bulk-cancel` body — see `EimsCancellationService.cancelBulkWithEims`. */
+export class BulkCancelEimsRegistrationDto {
+  @ApiProperty({ type: [BulkCancelEimsItemDto] })
+  @IsArray()
+  @ArrayMinSize(1)
+  @ValidateNested({ each: true })
+  @Type(() => BulkCancelEimsItemDto)
+  items!: BulkCancelEimsItemDto[];
+}
diff --git a/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.spec.ts b/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.spec.ts
index 6bd9b04b3..b9fdf62df 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.spec.ts
@@ -9,7 +9,9 @@ import { EimsApiException } from "./eims.errors";
 import { EimsInvoiceStatus } from "./eims-registration.types";
 
 const INVOICE_ID = "11111111-1111-4111-8111-111111111111";
+const OTHER_INVOICE_ID = "22222222-2222-4222-8222-222222222222";
 const IRN = "9fe9bbbece6ab76c112b617534e6aac7aa8b819d5be79f4d3d088ed2e887b2e0";
+const OTHER_IRN = "0af579eaef6f1e2d39fa77bd21cf8ecc64e26869275ae1c04eaa9ffea78b6c06";
 
 const invoiceRow = (over: Partial<Invoice> = {}): Invoice =>
   ({
@@ -153,3 +155,105 @@ describe("EimsCancellationService.cancelInvoiceWithEims", () => {
     expect(view.eimsStatus).toBe(EimsInvoiceStatus.Cancelled);
   });
 });
+
+describe("EimsCancellationService.cancelBulkWithEims", () => {
+  it("cancels every eligible invoice in one call, matching results back by IRN", async () => {
+    const db = new FakeDb([invoiceRow(), invoiceRow({ id: OTHER_INVOICE_ID, eimsIrn: OTHER_IRN })]);
+    const postBearer = jest.fn().mockResolvedValue({
+      statusCode: 200,
+      body: [
+        { id: 1, tin: "t", status: "C", mode: "bulk", Irn: OTHER_IRN, ReasonCode: "6", Remark: "x" },
+        { id: 2, tin: "t", status: "C", mode: "bulk", Irn: IRN, ReasonCode: "1", Remark: "" },
+      ],
+    });
+
+    const results = await build(db, postBearer).cancelBulkWithEims([
+      { invoiceId: INVOICE_ID, reasonCode: "1" },
+      { invoiceId: OTHER_INVOICE_ID, reasonCode: "6", remark: "x" },
+    ]);
+
+    expect(postBearer).toHaveBeenCalledWith("/v1/bulkCancel", [
+      { Irn: IRN, ReasonCode: "1", Remark: "" },
+      { Irn: OTHER_IRN, ReasonCode: "6", Remark: "x" },
+    ]);
+    expect(results).toEqual([
+      { invoiceId: INVOICE_ID, success: true, message: expect.stringContaining("cancelled") },
+      { invoiceId: OTHER_INVOICE_ID, success: true, message: expect.stringContaining("cancelled") },
+    ]);
+    expect(db.invoices.get(INVOICE_ID)?.eimsStatus).toBe(EimsInvoiceStatus.Cancelled);
+    expect(db.invoices.get(OTHER_INVOICE_ID)?.eimsStatus).toBe(EimsInvoiceStatus.Cancelled);
+    // Bulk success carries no cancellationDate at all, unlike single cancel.
+    expect(db.invoices.get(INVOICE_ID)?.eimsCancellationDate).toBeNull();
+  });
+
+  it("refuses an already-cancelled or never-registered invoice locally — never sent to MoR", async () => {
+    const db = new FakeDb([
+      invoiceRow({ eimsStatus: EimsInvoiceStatus.Cancelled }),
+      invoiceRow({ id: OTHER_INVOICE_ID, eimsStatus: EimsInvoiceStatus.NotSubmitted, eimsIrn: null }),
+    ]);
+    const postBearer = jest.fn();
+
+    const results = await build(db, postBearer).cancelBulkWithEims([
+      { invoiceId: INVOICE_ID, reasonCode: "1" },
+      { invoiceId: OTHER_INVOICE_ID, reasonCode: "1" },
+    ]);
+
+    expect(postBearer).not.toHaveBeenCalled();
+    expect(results).toEqual([
+      { invoiceId: INVOICE_ID, success: false, message: expect.stringContaining("already cancelled") },
+      { invoiceId: OTHER_INVOICE_ID, success: false, message: expect.stringContaining("never registered") },
+    ]);
+  });
+
+  it("a mix of MoR success and rejection only updates the succeeding invoice", async () => {
+    const db = new FakeDb([invoiceRow(), invoiceRow({ id: OTHER_INVOICE_ID, eimsIrn: OTHER_IRN })]);
+    const postBearer = jest.fn().mockResolvedValue({
+      statusCode: 200,
+      body: [
+        { id: 1, tin: "t", status: "C", mode: "bulk", Irn: IRN, ReasonCode: "1", Remark: "" },
+        { Status: "Processing_Error", msg: "IRN already Canceled.", Irn: OTHER_IRN },
+      ],
+    });
+
+    const results = await build(db, postBearer).cancelBulkWithEims([
+      { invoiceId: INVOICE_ID, reasonCode: "1" },
+      { invoiceId: OTHER_INVOICE_ID, reasonCode: "1" },
+    ]);
+
+    expect(db.invoices.get(INVOICE_ID)?.eimsStatus).toBe(EimsInvoiceStatus.Cancelled);
+    expect(db.invoices.get(OTHER_INVOICE_ID)?.eimsStatus).toBe(EimsInvoiceStatus.Registered);
+    expect(results).toEqual([
+      { invoiceId: INVOICE_ID, success: true, message: expect.stringContaining("cancelled") },
+      { invoiceId: OTHER_INVOICE_ID, success: false, message: "IRN already Canceled." },
+    ]);
+  });
+
+  it("makes no HTTP call at all when every item fails the local eligibility check", async () => {
+    const db = new FakeDb([invoiceRow({ eimsStatus: EimsInvoiceStatus.Cancelled })]);
+    const postBearer = jest.fn();
+
+    await build(db, postBearer).cancelBulkWithEims([{ invoiceId: INVOICE_ID, reasonCode: "1" }]);
+
+    expect(postBearer).not.toHaveBeenCalled();
+  });
+
+  it("notifies the buyer only for invoices that actually got cancelled", async () => {
+    const db = new FakeDb([invoiceRow(), invoiceRow({ id: OTHER_INVOICE_ID, eimsIrn: OTHER_IRN })]);
+    db.companyContact = { phone: "+251911000000", email: null };
+    const directSend = jest.fn().mockResolvedValue(undefined);
+    const postBearer = jest.fn().mockResolvedValue({
+      statusCode: 200,
+      body: [
+        { status: "C", Irn: IRN },
+        { Status: "Processing_Error", msg: "boom", Irn: OTHER_IRN },
+      ],
+    });
+
+    await build(db, postBearer, directSend).cancelBulkWithEims([
+      { invoiceId: INVOICE_ID, reasonCode: "1" },
+      { invoiceId: OTHER_INVOICE_ID, reasonCode: "1" },
+    ]);
+
+    expect(directSend).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.ts b/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.ts
index 9aa525ae3..7f8605c5f 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-cancellation.service.ts
@@ -6,7 +6,15 @@ import { Invoice } from "../billing/entities/invoice.entity";
 import { NotificationsService } from "../notifications/notifications.service";
 import { sendCompanyChannels } from "../notifications/notify-company.util";
 import { EimsClientService } from "./eims-client.service";
-import { EimsCancelRequest, EimsCancelResponse, EimsInvoiceStatus, EimsInvoiceStatusView } from "./eims-registration.types";
+import {
+  EimsBulkCancelItemResult,
+  EimsBulkCancelRequest,
+  EimsBulkCancelResponse,
+  EimsCancelRequest,
+  EimsCancelResponse,
+  EimsInvoiceStatus,
+  EimsInvoiceStatusView,
+} from "./eims-registration.types";
 import { toEimsInvoiceStatusView } from "./eims-invoice-view.util";
 
 /**
@@ -92,6 +100,102 @@ export class EimsCancellationService {
     return this.getEimsCancellationStatus(invoiceId);
   }
 
+  /**
+   * `POST /v1/bulkCancel` — one MoR call for every eligible invoice in `items`, matching the
+   * collection's own shape (an array in, an array of mixed success/error results back).
+   *
+   * Same local-eligibility doctrine as `cancelInvoiceWithEims`, applied per item before anything
+   * goes to MoR: an already-cancelled or never-registered invoice is refused right here (no HTTP
+   * call, no seat in the batch) rather than sent and rejected remotely. Only genuinely eligible
+   * invoices are batched into the one `/v1/bulkCancel` request; everything else is reported back
+   * immediately.
+   *
+   * ponytail: the eligibility pass is per-invoice transactions, not one covering the whole batch —
+   * same reasoning as the single-cancel path (cancel is idempotent at MoR, so a lock held across
+   * every item for the whole call isn't needed for correctness, only for avoiding a wasted call on
+   * an item that's already ineligible).
+   */
+  async cancelBulkWithEims(
+    items: Array<{ invoiceId: string; reasonCode: string; remark?: string }>,
+  ): Promise<EimsBulkCancelItemResult[]> {
+    const results = new Map<string, EimsBulkCancelItemResult>();
+    const eligible: Array<{ invoice: Invoice; reasonCode: string; remark?: string }> = [];
+
+    for (const item of items) {
+      try {
+        const invoice = await this.dataSource.transaction(async (manager) => {
+          const inv = await this.lockInvoice(manager, item.invoiceId);
+          if (inv.eimsStatus === EimsInvoiceStatus.Cancelled) {
+            throw new ConflictException(
+              `Invoice ${inv.invoiceNumber} was already cancelled with EIMS${inv.eimsCancellationDate ? ` (${inv.eimsCancellationDate})` : ""}.`,
+            );
+          }
+          if (!inv.eimsIrn) {
+            throw new BadRequestException(
+              `Invoice ${inv.invoiceNumber} was never registered with EIMS — nothing to cancel.`,
+            );
+          }
+          return inv;
+        });
+        eligible.push({ invoice, reasonCode: item.reasonCode, remark: item.remark });
+      } catch (err) {
+        results.set(item.invoiceId, {
+          invoiceId: item.invoiceId,
+          success: false,
+          message: (err as Error).message,
+        });
+      }
+    }
+
+    if (eligible.length > 0) {
+      const request: EimsBulkCancelRequest = eligible.map((e) => ({
+        Irn: e.invoice.eimsIrn!,
+        ReasonCode: e.reasonCode,
+        Remark: e.remark ?? "",
+      }));
+      // Outside any transaction — no DB lock held across the wire, same as single cancel.
+      const response = await this.client.postBearer<EimsBulkCancelRequest, EimsBulkCancelResponse>(
+        "/v1/bulkCancel",
+        request,
+      );
+      const byIrn = new Map((response?.body ?? []).map((entry) => [entry.Irn, entry]));
+
+      for (const { invoice, reasonCode, remark } of eligible) {
+        const entry = byIrn.get(invoice.eimsIrn!);
+        const failed = !entry || "Status" in entry;
+        if (failed) {
+          const message = entry && "msg" in entry ? entry.msg : "EIMS bulk cancel returned no result for this invoice.";
+          this.logger.warn(`Invoice ${invoice.invoiceNumber} bulk cancel failed: ${message}`);
+          results.set(invoice.id, { invoiceId: invoice.id, success: false, message });
+          continue;
+        }
+
+        await this.dataSource.transaction(async (manager) => {
+          const fresh = await this.lockInvoice(manager, invoice.id);
+          // Re-checked under lock: a concurrent call may have already recorded this cancellation.
+          if (fresh.eimsStatus === EimsInvoiceStatus.Cancelled) return;
+          await manager.update(Invoice, invoice.id, {
+            eimsStatus: EimsInvoiceStatus.Cancelled,
+            eimsCancelledAt: new Date(),
+            // The bulk success shape carries no cancellationDate at all, unlike single cancel.
+            eimsCancellationDate: null,
+            eimsCancellationReasonCode: reasonCode,
+            eimsCancellationRemark: remark ?? null,
+          });
+        });
+        this.logger.log(`Invoice ${invoice.invoiceNumber} cancelled with EIMS via bulk (IRN ${invoice.eimsIrn})`);
+        await this.notifyBuyer(invoice);
+        results.set(invoice.id, {
+          invoiceId: invoice.id,
+          success: true,
+          message: `Invoice ${invoice.invoiceNumber} cancelled with EIMS.`,
+        });
+      }
+    }
+
+    return items.map((item) => results.get(item.invoiceId)!);
+  }
+
   async getEimsCancellationStatus(invoiceId: string): Promise<EimsInvoiceStatusView> {
     const invoice = await this.dataSource.manager.findOne(Invoice, { where: { id: invoiceId } });
     if (!invoice) throw new NotFoundException(`Invoice ${invoiceId} not found`);
diff --git a/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts b/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts
index 7d417551f..11eb214dc 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-invoice.controller.ts
@@ -5,6 +5,7 @@ import type { Response } from "express";
 import { BookingStaff } from "../../common/booking-guards";
 import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
 import { sendPdf } from "../billing/billing.controller";
+import { BulkCancelEimsRegistrationDto } from "./dto/bulk-cancel-eims-registration.dto";
 import { CancelEimsRegistrationDto } from "./dto/cancel-eims-registration.dto";
 import { RegisterSalesReceiptDto } from "./dto/register-sales-receipt.dto";
 import { RegisterWithholdingReceiptDto } from "./dto/register-withholding-receipt.dto";
@@ -89,6 +90,17 @@ export class EimsInvoiceController {
     return this.cancellation.cancelInvoiceWithEims(id, dto.reasonCode, dto.remark);
   }
 
+  @Post("eims/bulk-cancel")
+  @BookingStaff(FREIGHT_PERMS.invoices.eimsCancel)
+  @ApiOperation({
+    summary:
+      "Cancel multiple invoices' registered EIMS documents in one call. Each invoice's outcome is " +
+      "reported independently — one failure never blocks the rest.",
+  })
+  bulkCancel(@Body() dto: BulkCancelEimsRegistrationDto) {
+    return this.cancellation.cancelBulkWithEims(dto.items);
+  }
+
   @Post(":id/eims/receipt/sales")
   @BookingStaff(FREIGHT_PERMS.invoices.eimsReceiptRegister)
   @ApiOperation({ summary: "Register a sales receipt with MoR EIMS against a registered invoice" })
diff --git a/apps/edr-freight-api/src/modules/eims/eims-registration.types.ts b/apps/edr-freight-api/src/modules/eims/eims-registration.types.ts
index 8094d0e74..60941825c 100644
--- a/apps/edr-freight-api/src/modules/eims/eims-registration.types.ts
+++ b/apps/edr-freight-api/src/modules/eims/eims-registration.types.ts
@@ -89,6 +89,46 @@ export interface EimsCancelResponse {
   body?: EimsCancelResponseBody;
 }
 
+/** `POST /v1/bulkCancel` — an array of the same `Irn`/`ReasonCode`/`Remark` shape as single cancel. */
+export type EimsBulkCancelRequest = EimsCancelRequest[];
+
+/**
+ * One element of a `/v1/bulkCancel` response array — MoR mixes success and error shapes in the same
+ * array, one entry per submitted IRN, disambiguated by `Status` (capital, error) vs `status`
+ * (lowercase, success — always `"C"`). Unlike single cancel, a bulk success carries no
+ * `cancellationDate` at all.
+ */
+export interface EimsBulkCancelSuccessItem {
+  id?: number;
+  tin?: string;
+  status: string;
+  mode?: string;
+  Irn: string;
+  ReasonCode?: string;
+  Remark?: string;
+}
+
+export interface EimsBulkCancelErrorItem {
+  Status: string;
+  msg: string;
+  Irn: string;
+}
+
+export type EimsBulkCancelResponseItem = EimsBulkCancelSuccessItem | EimsBulkCancelErrorItem;
+
+export interface EimsBulkCancelResponse {
+  statusCode?: number;
+  message?: string;
+  body?: EimsBulkCancelResponseItem[];
+}
+
+/** One invoice's outcome from `cancelBulkWithEims` — local eligibility failure or MoR's own result. */
+export interface EimsBulkCancelItemResult {
+  invoiceId: string;
+  success: boolean;
+  message: string;
+}
+
 /** Persisted failure detail. Carries the gateway's own error fields only — never our envelope. */
 export interface EimsInvoiceError {
   kind: string;

From e67ccbb9cd1aa81b511c85a6ce8bbb5789bad573 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 17 Aug 2026 18:10:55 +0000
Subject: [PATCH 139/174] fix(eims): stop sending our internal fee-basis tag as
 MoR's ItemList Unit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Confirmed live 2026-08-17 on INV-20260817-00008: MoR rejected the
document with a SCHEMA ERROR on ItemList[0].Unit — 'PER_CONTAINER'
(from the line's own metadata.unit) fails MoR's enum
(LTR/MTR/101/PCS/ROL/MTS/PKG/SET/KLG), its 8-char max, and its
^[A-Za-z]{3,8}$ regex all at once.

line.metadata.unit is our own fee-basis tag (PER_CONTAINER/PER_TON/
PER_ITEM — how a charge is computed) and was never a MoR unit of
measure; the mapper was reusing the same field name for two unrelated
concepts. Every line now sends the single configured
EIMS_UNIT_DEFAULT instead of guessing a per-line value that doesn't
exist in MoR's vocabulary.
---
 .../src/modules/billing/eims-invoice.mapper.spec.ts       | 4 +++-
 .../src/modules/billing/eims-invoice.mapper.ts            | 8 +++++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts
index 6d58a7bec..75d39a500 100644
--- a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts
@@ -151,7 +151,9 @@ describe("toEimsInvoice", () => {
       // EimsLineTax.discount comment in eims-invoice.mapper.ts.
       Discount: 25,
       TotalLineAmount: 1050,
-      Unit: "CTR",
+      // Not "CTR" from the line's metadata.unit — that's our internal fee-basis tag, not a MoR
+      // unit of measure, and is never read for this field (see the mapper's own comment).
+      Unit: "PCS",
     });
     expect(doc.ValueDetails).toEqual({
       Discount: null,
diff --git a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
index b8755c709..c72e61c7a 100644
--- a/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
+++ b/apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts
@@ -463,7 +463,13 @@ export function toEimsInvoice(
     const PreTaxValue = round2(num(line.amount));
     const TaxAmount = round2((PreTaxValue * tax.ratePercent) / 100);
     const ExciseTaxValue = round2(tax.exciseTaxValue);
-    const unit = typeof line.metadata?.unit === "string" ? line.metadata.unit : context.unitDefault;
+    // `line.metadata.unit` is our own fee-basis tag (PER_CONTAINER/PER_TON/PER_ITEM — how a charge
+    // is computed, see the fee-rule docs), never a MoR unit of measure — sending it as-is here
+    // (confirmed live 2026-08-17: "PER_CONTAINER" fails Unit's enum, its 8-char max, and its regex
+    // all at once) is what a prior version of this mapper did by mistake. MoR's own enum
+    // (LTR/MTR/101/PCS/ROL/MTS/PKG/SET/KLG) has no freight-shipment concept at all, so every line
+    // uses the single configured default rather than guessing a per-line value that doesn't exist.
+    const unit = context.unitDefault;
 
     return {
       Discount: round2(tax.discount),

From 2f293e4ae424eac569217515c2eeff0e4069afbf Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 07:28:42 +0000
Subject: [PATCH 140/174] fix: vite env issue

---
 docker-compose.yaml                  | 1 +
 infrastructure/docker/Dockerfile.web | 3 +++
 2 files changed, 4 insertions(+)

diff --git a/docker-compose.yaml b/docker-compose.yaml
index 5d5faa2de..f678f5c02 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -49,6 +49,7 @@ services:
       args:
         TURBO_FILTER: "@edr/freight-portal"
         APP_PATH: apps/edr-freight-web/portal
+        VITE_ENV: ${VITE_ENV:-}
         VITE_API_URL: ${VITE_API_URL:-}
         VITE_BASE_API_URL: ${VITE_BASE_API_URL:-}
         VITE_USER_MANAGEMENT_BASE: ${VITE_USER_MANAGEMENT_BASE:-}
diff --git a/infrastructure/docker/Dockerfile.web b/infrastructure/docker/Dockerfile.web
index 1e26bf643..714e49d33 100644
--- a/infrastructure/docker/Dockerfile.web
+++ b/infrastructure/docker/Dockerfile.web
@@ -30,6 +30,7 @@ ARG NEXT_PUBLIC_API_URL
 ARG VITE_GOOGLE_MAPS_API_KEY
 ARG VITE_POSTHOG_KEY
 ARG VITE_POSTHOG_HOST
+ARG VITE_ENV
 ENV VITE_API_URL=${VITE_API_URL}
 ENV VITE_BASE_API_URL=${VITE_BASE_API_URL}
 ENV VITE_USER_MANAGEMENT_BASE=${VITE_USER_MANAGEMENT_BASE}
@@ -37,6 +38,8 @@ ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
 ENV VITE_GOOGLE_MAPS_API_KEY=${VITE_GOOGLE_MAPS_API_KEY}
 ENV VITE_POSTHOG_KEY=${VITE_POSTHOG_KEY}
 ENV VITE_POSTHOG_HOST=${VITE_POSTHOG_HOST}
+# dev|staging only — gates the Fayda/OTP bypass. Unset in prod.
+ENV VITE_ENV=${VITE_ENV}
 
 RUN if [ -z "$VITE_API_URL" ] || [ -z "$VITE_BASE_API_URL" ] || [ -z "$VITE_USER_MANAGEMENT_BASE" ]; then \
       echo "ERROR: VITE_API_URL, VITE_BASE_API_URL, and VITE_USER_MANAGEMENT_BASE must all be set" && \

From c723b660e254f5a13eca109872a46111b83e2d38 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Tue, 18 Aug 2026 08:27:18 +0000
Subject: [PATCH 141/174] feat(freight): offer built-train wagons per boarding
 yard on multi-yard consists

---
 apps/edr-freight-api/src/app.module.ts        |   2 +
 .../3560000000000-ManualPaymentSettings.ts    |  36 +++
 .../modules/billing/billing.service.spec.ts   |  11 +
 .../src/modules/billing/billing.service.ts    |  30 +-
 .../dto/update-manual-payment-setting.dto.ts  |  18 ++
 .../entities/manual-payment-setting.entity.ts |  26 ++
 .../manual-payment-settings.controller.ts     |  47 +++
 .../manual-payment-settings.service.ts        |  71 +++++
 .../payment-settings.module.ts                |  20 ++
 .../train-scheduling/booking-batch.service.ts |  16 +-
 .../services/train-scheduling.service.ts      | 109 ++++++-
 .../train-scheduling/wagon-plan-flex.util.ts  |  10 +
 .../wagon-stock-ledger.util.spec.ts           |  91 ++++++
 .../wagon-stock-ledger.util.ts                |  45 ++-
 .../src/modules/trains/dto/build-train.dto.ts |   2 +-
 .../modules/trains/train-builder.service.ts   |  58 +++-
 .../src/modules/wagons/wagons.service.ts      |   9 +-
 .../src/seed/freight-permissions.registry.ts  |  21 ++
 apps/edr-freight-web/backoffice/src/App.tsx   |  13 +
 .../components/layout/sidebar-sections.tsx    |   5 +
 .../trainBuilder/AvailableWagonsPanel.tsx     | 162 +++++++----
 .../trainBuilder/ConsistWagonList.tsx         |   7 +-
 .../backoffice/src/constants/URLS.ts          |   4 +
 .../src/hooks/useManualPaymentSettings.ts     |  39 +++
 .../backoffice/src/lib/permissions.ts         |   6 +
 .../src/pages/invoices/FinanceHubPage.tsx     |  40 ++-
 .../src/pages/invoices/UsdPaymentsPage.tsx    |  66 ++---
 .../settings/ManualPaymentSettingsCard.tsx    | 132 +++++++++
 .../trainBuilder/TrainBuilderDetailPage.tsx   |  31 +-
 .../services/manualPaymentSettings.service.ts |  36 +++
 .../src/services/trainBuilder.service.ts      |  11 +
 .../portal/src/hooks/useAuth.ts               |  19 +-
 .../src/pages/contracts/ContractViewPage.tsx  | 272 +++++++++++++-----
 33 files changed, 1234 insertions(+), 231 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3560000000000-ManualPaymentSettings.ts
 create mode 100644 apps/edr-freight-api/src/modules/payment-settings/dto/update-manual-payment-setting.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/payment-settings/entities/manual-payment-setting.entity.ts
 create mode 100644 apps/edr-freight-api/src/modules/payment-settings/manual-payment-settings.controller.ts
 create mode 100644 apps/edr-freight-api/src/modules/payment-settings/manual-payment-settings.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/payment-settings/payment-settings.module.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/hooks/useManualPaymentSettings.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/settings/ManualPaymentSettingsCard.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/services/manualPaymentSettings.service.ts

diff --git a/apps/edr-freight-api/src/app.module.ts b/apps/edr-freight-api/src/app.module.ts
index d38c6ea92..d0ab805a8 100644
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -50,6 +50,7 @@ import { SupportChatModule } from "./modules/support-chat/support-chat.module";
 import { FileUploadSettingsModule } from "./modules/file-upload-settings/file-upload-settings.module";
 import { DropdownSettingsModule } from "./modules/dropdown-settings/dropdown-settings.module";
 import { ExchangeSettingsModule } from "./modules/exchange-settings/exchange-settings.module";
+import { PaymentSettingsModule } from "./modules/payment-settings/payment-settings.module";
 import { StampSettingsModule } from "./modules/stamp-settings/stamp-settings.module";
 import { LogoSettingsModule } from "./modules/logo-settings/logo-settings.module";
 import { ContractTemplatesModule } from "./modules/contract-templates/contract-templates.module";
@@ -213,6 +214,7 @@ if (!process.env.APPLICATION_NAME) {
     FileUploadSettingsModule,
     DropdownSettingsModule,
     ExchangeSettingsModule,
+    PaymentSettingsModule,
     StampSettingsModule,
     LogoSettingsModule,
     ContractTemplatesModule,
diff --git a/apps/edr-freight-api/src/migrations/3560000000000-ManualPaymentSettings.ts b/apps/edr-freight-api/src/migrations/3560000000000-ManualPaymentSettings.ts
new file mode 100644
index 000000000..0c4f5698f
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3560000000000-ManualPaymentSettings.ts
@@ -0,0 +1,36 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Single-row table controlling whether Finance may settle invoices by hand,
+ * per currency (see ManualPaymentSettingsService). Defaults preserve the
+ * pre-toggle behaviour: USD was always bank-transfer-only (ON), ETB manual
+ * settlement is the new capability and must be switched on deliberately (OFF).
+ */
+export class ManualPaymentSettings3560000000000 implements MigrationInterface {
+  name = "ManualPaymentSettings3560000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.manual_payment_settings (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        etb_enabled boolean NOT NULL DEFAULT false,
+        usd_enabled boolean NOT NULL DEFAULT true,
+        updated_by_id uuid,
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz
+      );
+    `);
+    await queryRunner.query(`
+      INSERT INTO freight.manual_payment_settings (etb_enabled, usd_enabled)
+      SELECT false, true
+      WHERE NOT EXISTS (SELECT 1 FROM freight.manual_payment_settings);
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DROP TABLE IF EXISTS freight.manual_payment_settings;`,
+    );
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
index 243b1ee4d..c5cc9a81e 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -81,6 +81,7 @@ describe("BillingService.generateInvoice", () => {
       {} as never, // invoiceDocuments
       {} as never, // files
       { get: () => undefined } as never, // config
+      { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
     );
   });
 
@@ -163,6 +164,7 @@ describe("BillingService.issueMemo", () => {
       {} as never,
       {} as never,
       { get: () => undefined } as never,
+      { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
     );
     return { service, manager, savedLines };
   }
@@ -297,6 +299,7 @@ describe("BillingService.markInvoiceAsPaid", () => {
       {} as never, // invoiceDocuments
       {} as never, // files
       { get: () => undefined } as never, // config
+      { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
     );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
@@ -352,6 +355,7 @@ describe("BillingService.markInvoiceAsPaid", () => {
       {} as never, // invoiceDocuments
       {} as never, // files
       { get: () => undefined } as never, // config
+      { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
     );
 
     await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
@@ -397,6 +401,7 @@ describe("BillingService.settleByPaymentId", () => {
       {} as never, // invoiceDocuments
       {} as never, // files
       { get: () => undefined } as never, // config
+      { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
     );
     return { service, mg, events };
   }
@@ -510,6 +515,7 @@ describe("BillingService.recordPayment", () => {
       {} as never, // invoiceDocuments
       {} as never, // files
       { get: () => undefined } as never, // config
+      { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
     );
     return { service, mg, events };
   }
@@ -627,6 +633,7 @@ describe("BillingService.expirePayable — locked write runs in a transaction",
       {} as never,
       {} as never,
       {} as never, // config
+      { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
     );
     return { service, defaultManager, txManager, transaction };
   };
@@ -700,6 +707,7 @@ describe("BillingService.issuePayable", () => {
       {} as never,
       {} as never,
       {} as never, // config
+      { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
     );
     return { service, manager };
   };
@@ -791,6 +799,7 @@ describe("BillingService — CAC Bank (OTP debit)", () => {
       {} as never,
       {} as never,
       {} as never, // config
+      { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
     );
     return { service, repo };
   };
@@ -874,6 +883,7 @@ describe("BillingService — CBE bill amounts carry cents, never rounded", () =>
       {} as never,
       {} as never,
       {} as never, // config
+      { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
     );
     return { service, repo };
   };
@@ -943,6 +953,7 @@ describe("BillingService.document", () => {
             ? { tin: "0053481357", invoice: { sellerVatNumber: "43256663343256663322" } }
             : undefined,
       } as never, // config
+      { isEnabled: async () => true, enabledCurrencies: async () => ["ETB", "USD"] } as never, // manualPaymentSettings
     );
     return { service, render, renderThermal };
   };
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 44e194a8d..d64361bf8 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -17,6 +17,7 @@ import { Booking } from "../bookings/entities/booking.entity";
 // payers straight off the table.
 import { ShippingLineCompany } from "../shipping-lines/entities/shipping-line-company.entity";
 import { ShippingLineCredit } from "../shipping-lines/entities/shipping-line-credit.entity";
+import { ManualPaymentSettingsService } from "../payment-settings/manual-payment-settings.service";
 import { EimsConfig } from "../../config/eims.config";
 import { CompaniesService } from "../companies/companies.service";
 import { EimsInvoiceStatus } from "../eims/eims-registration.types";
@@ -201,6 +202,7 @@ export class BillingService {
     private readonly invoiceDocuments: InvoiceDocumentService,
     private readonly files: FilesService,
     private readonly config: ConfigService,
+    private readonly manualPaymentSettings: ManualPaymentSettingsService,
   ) { }
 
   // ── Reads ──────────────────────────────────────────────────────────────────
@@ -370,20 +372,24 @@ export class BillingService {
     const pageSize =
       filter.pageSize && filter.pageSize > 0 ? filter.pageSize : 20;
 
+    // Only currencies whose manual-payment channel is switched on are listed:
+    // a row Finance cannot act on is noise, and the confirm endpoint would
+    // refuse it anyway. All off → nothing to work.
+    const enabled = await this.manualPaymentSettings.enabledCurrencies();
+    if (!enabled.length) return { items: [], total: 0 };
+    const currencies = filter.currency
+      ? enabled.filter((c) => c === filter.currency)
+      : enabled;
+    if (!currencies.length) return { items: [], total: 0 };
+
     const qb = this.dataSource
       .getRepository(Invoice)
       .createQueryBuilder("invoice")
       .leftJoinAndSelect("invoice.company", "company")
-      .where("UPPER(invoice.currency) IN ('USD', 'ETB')")
+      .where("UPPER(invoice.currency) IN (:...currencies)", { currencies })
       .orderBy("invoice.issuedAt", "DESC")
       .skip((page - 1) * pageSize)
       .take(pageSize);
-
-    if (filter.currency) {
-      qb.andWhere("UPPER(invoice.currency) = :currency", {
-        currency: filter.currency,
-      });
-    }
     if (filter.status) {
       qb.andWhere("invoice.status = :status", { status: filter.status });
     } else {
@@ -465,7 +471,8 @@ export class BillingService {
 
   /**
    * Finance confirms an invoice (USD or ETB) as paid manually — bank transfer
-   * or counter payment: stores the slip against the invoice and settles the
+   * or counter payment. Refused when that currency's manual-payment channel is
+   * switched off in settings. Stores the slip against the invoice and settles the
    * FULL outstanding balance through
    * {@link recordPayment}, which flips the invoice to PAID and (for bookings)
    * emits `booking.invoice.paid` — the same event an online payment fires, so
@@ -485,6 +492,13 @@ export class BillingService {
   ): Promise<Invoice> {
     const invoice = await this.invoices.findById(invoiceId);
     if (!invoice) throw new NotFoundException(`Invoice ${invoiceId} not found`);
+    // The channel is a setting, not a role: even a permitted user cannot
+    // settle by hand in a currency whose channel is switched off.
+    if (!(await this.manualPaymentSettings.isEnabled(invoice.currency))) {
+      throw new BadRequestException(
+        `Manual payment is disabled for ${invoice.currency ?? "this"} invoices. Enable it in Configuration → Manual payments first.`,
+      );
+    }
     if (!file) {
       throw new BadRequestException("The bank payment slip file is required.");
     }
diff --git a/apps/edr-freight-api/src/modules/payment-settings/dto/update-manual-payment-setting.dto.ts b/apps/edr-freight-api/src/modules/payment-settings/dto/update-manual-payment-setting.dto.ts
new file mode 100644
index 000000000..971de03cb
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/payment-settings/dto/update-manual-payment-setting.dto.ts
@@ -0,0 +1,18 @@
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { IsBoolean, IsOptional } from "class-validator";
+
+/**
+ * Partial update: the UI flips one currency at a time, so an omitted field
+ * leaves that currency's channel exactly as it was.
+ */
+export class UpdateManualPaymentSettingDto {
+  @ApiPropertyOptional({ description: "Allow manual settlement of ETB invoices" })
+  @IsOptional()
+  @IsBoolean()
+  etbEnabled?: boolean;
+
+  @ApiPropertyOptional({ description: "Allow manual settlement of USD invoices" })
+  @IsOptional()
+  @IsBoolean()
+  usdEnabled?: boolean;
+}
diff --git a/apps/edr-freight-api/src/modules/payment-settings/entities/manual-payment-setting.entity.ts b/apps/edr-freight-api/src/modules/payment-settings/entities/manual-payment-setting.entity.ts
new file mode 100644
index 000000000..a18f97279
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/payment-settings/entities/manual-payment-setting.entity.ts
@@ -0,0 +1,26 @@
+import { BaseEntity } from "@edr/api-common";
+import { Column, Entity } from "typeorm";
+
+/**
+ * Single-row table controlling whether Finance may settle invoices by hand
+ * (bank transfer / counter payment) instead of the customer paying online.
+ *
+ * Per currency on purpose: the two channels are operationally different — USD
+ * bookings have always been bank-transfer-only, while ETB normally goes
+ * through the gateway and manual settlement is the exception. Switching one
+ * off must not switch off the other.
+ */
+@Entity({ schema: "freight", name: "manual_payment_settings" })
+export class ManualPaymentSetting extends BaseEntity {
+  /** Manual settlement allowed for ETB invoices. */
+  @Column({ name: "etb_enabled", type: "boolean", default: false })
+  etbEnabled!: boolean;
+
+  /** Manual settlement allowed for USD invoices. */
+  @Column({ name: "usd_enabled", type: "boolean", default: true })
+  usdEnabled!: boolean;
+
+  /** IAM user id of the last operator to change either toggle. */
+  @Column({ name: "updated_by_id", type: "uuid", nullable: true })
+  updatedById?: string | null;
+}
diff --git a/apps/edr-freight-api/src/modules/payment-settings/manual-payment-settings.controller.ts b/apps/edr-freight-api/src/modules/payment-settings/manual-payment-settings.controller.ts
new file mode 100644
index 000000000..786d1f7ca
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/payment-settings/manual-payment-settings.controller.ts
@@ -0,0 +1,47 @@
+import { Body, Controller, Get, Patch } from "@nestjs/common";
+import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
+import { CurrentUser } from "@edr/api-common";
+import type { TCurrentUser } from "@tria-plc/api-common/modules/auth/types/current-user.type";
+
+import { BookingStaff } from "../../common/booking-guards";
+import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
+import { UpdateManualPaymentSettingDto } from "./dto/update-manual-payment-setting.dto";
+import { ManualPaymentSettingsService } from "./manual-payment-settings.service";
+
+@ApiTags("payment-settings")
+@ApiBearerAuth()
+@Controller("payment-settings/manual")
+export class ManualPaymentSettingsController {
+  constructor(private readonly service: ManualPaymentSettingsService) {}
+
+  /**
+   * Read is gated on `manual_payment:view`, which Finance also holds — the
+   * Manual Payments worklist reads this to know which currency tabs to offer.
+   */
+  @Get()
+  @BookingStaff([
+    FREIGHT_PERMS.settings.manualPayment.view,
+    FREIGHT_PERMS.admin,
+  ])
+  @ApiOperation({
+    summary: "Whether manual (offline) invoice settlement is enabled, per currency",
+  })
+  get() {
+    return this.service.get();
+  }
+
+  @Patch()
+  @BookingStaff([
+    FREIGHT_PERMS.settings.manualPayment.manage,
+    FREIGHT_PERMS.admin,
+  ])
+  @ApiOperation({
+    summary: "Enable or disable manual invoice settlement for ETB and/or USD",
+  })
+  update(
+    @Body() dto: UpdateManualPaymentSettingDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.service.update(dto, user?.id ?? null);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/payment-settings/manual-payment-settings.service.ts b/apps/edr-freight-api/src/modules/payment-settings/manual-payment-settings.service.ts
new file mode 100644
index 000000000..efb43fa91
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/payment-settings/manual-payment-settings.service.ts
@@ -0,0 +1,71 @@
+import { Injectable, Logger } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+
+import { ManualPaymentSetting } from "./entities/manual-payment-setting.entity";
+
+/** The two currencies an invoice can be settled by hand in. */
+export type ManualPaymentCurrency = "ETB" | "USD";
+
+/**
+ * Owns the single `manual_payment_settings` row: whether Finance may settle
+ * invoices by hand, per currency.
+ *
+ * Defaults mirror how the platform behaved before the toggles existed — USD
+ * has always been bank-transfer-only so it starts ON; ETB manual settlement is
+ * the new capability and starts OFF, so enabling it is a deliberate act.
+ */
+@Injectable()
+export class ManualPaymentSettingsService {
+  private readonly logger = new Logger(ManualPaymentSettingsService.name);
+
+  constructor(
+    @InjectRepository(ManualPaymentSetting)
+    private readonly repository: Repository<ManualPaymentSetting>,
+  ) {}
+
+  /** The settings row, created at the defaults on first access. */
+  async get(): Promise<ManualPaymentSetting> {
+    const existing = await this.repository.findOne({ where: {} });
+    if (existing) return existing;
+
+    return this.repository.save(
+      this.repository.create({ etbEnabled: false, usdEnabled: true }),
+    );
+  }
+
+  /** Currencies manual settlement is currently allowed for. */
+  async enabledCurrencies(): Promise<ManualPaymentCurrency[]> {
+    const setting = await this.get();
+    const enabled: ManualPaymentCurrency[] = [];
+    if (setting.etbEnabled) enabled.push("ETB");
+    if (setting.usdEnabled) enabled.push("USD");
+    return enabled;
+  }
+
+  /** Whether one currency may be settled by hand right now. */
+  async isEnabled(currency: string | null | undefined): Promise<boolean> {
+    const upper = currency?.toUpperCase();
+    if (upper !== "ETB" && upper !== "USD") return false;
+    const setting = await this.get();
+    return upper === "ETB" ? setting.etbEnabled : setting.usdEnabled;
+  }
+
+  /** Flip either toggle; an omitted field leaves that currency unchanged. */
+  async update(
+    patch: { etbEnabled?: boolean; usdEnabled?: boolean },
+    updatedById?: string | null,
+  ): Promise<ManualPaymentSetting> {
+    const current = await this.get();
+    await this.repository.update(current.id, {
+      ...(patch.etbEnabled === undefined ? {} : { etbEnabled: patch.etbEnabled }),
+      ...(patch.usdEnabled === undefined ? {} : { usdEnabled: patch.usdEnabled }),
+      updatedById: updatedById ?? null,
+    });
+    const updated = await this.get();
+    this.logger.warn(
+      `Manual payment channels set to ETB=${updated.etbEnabled} USD=${updated.usdEnabled} by ${updatedById ?? "unknown user"}`,
+    );
+    return updated;
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/payment-settings/payment-settings.module.ts b/apps/edr-freight-api/src/modules/payment-settings/payment-settings.module.ts
new file mode 100644
index 000000000..bcadfe340
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/payment-settings/payment-settings.module.ts
@@ -0,0 +1,20 @@
+import { Global, Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+
+import { ManualPaymentSetting } from "./entities/manual-payment-setting.entity";
+import { ManualPaymentSettingsController } from "./manual-payment-settings.controller";
+import { ManualPaymentSettingsService } from "./manual-payment-settings.service";
+
+/**
+ * Global so billing can inject {@link ManualPaymentSettingsService} to gate
+ * the manual-settlement worklist and confirmation endpoint without importing
+ * this module (and without a cycle, since this module needs nothing back).
+ */
+@Global()
+@Module({
+  imports: [TypeOrmModule.forFeature([ManualPaymentSetting])],
+  controllers: [ManualPaymentSettingsController],
+  providers: [ManualPaymentSettingsService],
+  exports: [ManualPaymentSettingsService],
+})
+export class PaymentSettingsModule {}
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 4418eed3d..cb1958582 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
@@ -1221,13 +1221,21 @@ export class BookingBatchService implements OnModuleInit {
       const ledger = new WagonStockLedger(
         stock.remainingByTypeId,
         Math.max(1, budget.stops.length - 1),
+        stock.byYardId,
+        budget.stops,
       );
+      // On a multi-yard consist the pool that matters is the one standing at
+      // the booking's own boarding yard — a type carried only in Mojo must not
+      // be advertised to a customer boarding at Dire.
+      const carriedAtBoardYard = (wagonTypeId: string): number => {
+        const boardYardId = stock.byYardId ? budget.stops[leg.fromEdge] : null;
+        if (boardYardId) return stock.byYardId?.get(boardYardId)?.get(wagonTypeId) ?? 0;
+        return stock.remainingByTypeId.get(wagonTypeId) ?? 0;
+      };
       const byWagonType = allowed
         .filter(
           ({ wagonTypeId }) =>
-            stock.mode !== 'TRAIN' ||
-            !wagonTypeId ||
-            (stock.remainingByTypeId.get(wagonTypeId) ?? 0) > 0,
+            stock.mode !== 'TRAIN' || !wagonTypeId || carriedAtBoardYard(wagonTypeId) > 0,
         )
         .map(({ wagonTypeId, dims }) => {
           const type = wagonTypeId ? typeById.get(wagonTypeId) : undefined;
@@ -4783,6 +4791,8 @@ export class BookingBatchService implements OnModuleInit {
     return new WagonStockLedger(
       stock.remainingByTypeId,
       Math.max(1, budget.stops.length - 1),
+      stock.byYardId,
+      budget.stops,
     );
   }
 
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
index 03535135d..9a20c0486 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -1589,6 +1589,7 @@ export class TrainSchedulingService {
           `Train ${builtTrain.code} is not at the origin yard yet; it must arrive before this departure dispatches`,
         );
       }
+      await this.assertRouteCoversWagonYards(builtTrain, route);
       const conflict = await this.findTrainRouteDayConflict(
         builtTrain.id,
         route.id,
@@ -4274,12 +4275,26 @@ export class TrainSchedulingService {
             .getRepository(Locomotive)
             .update({ id: In(locoIds) }, { currentYardId: station.yardId });
         }
+        // Only wagons the train has actually COLLECTED move with it. On a
+        // consist spread across yards (20 in Dire, 33 in Mojo), reaching Mojo
+        // moves the Dire wagons — the ones already aboard — and picks up the
+        // Mojo ones standing here. Wagons waiting at yards further down the
+        // line stay where they are until the train physically gets to them.
+        const passedYardIds = stations
+          .filter((s) => s.sequenceNo <= dto.sequenceNo)
+          .map((s) => s.yardId);
         await manager
           .getRepository(Wagon)
-          .update(
-            { currentTrainScheduleId: scheduleId },
-            { currentYardId: station.yardId },
-          );
+          .createQueryBuilder()
+          .update(Wagon)
+          .set({ currentYardId: station.yardId })
+          .where('current_train_schedule_id = :scheduleId', { scheduleId })
+          // A yard-less wagon has no "waiting further down the line" position
+          // to protect, so it rides along as it always did.
+          .andWhere('(current_yard_id IS NULL OR current_yard_id IN (:...passedYardIds))', {
+            passedYardIds,
+          })
+          .execute();
         if (schedule.trainSet?.trainId) {
           await manager
             .getRepository(Train)
@@ -5286,12 +5301,26 @@ export class TrainSchedulingService {
     const typeCodeById = new Map(wagonTypes.map((type) => [type.id, type.code]));
     const counts = new Map<string, { code: string; available: number }>();
 
+    // A built consist spread across several yards can only offer, at each yard,
+    // the wagons standing there. A single-yard consist keeps the original
+    // behaviour: the whole train counts wherever it currently sits.
+    const consistYards = builtTrainId
+      ? new Set(
+          wagons
+            .filter((w) => w.trainId === builtTrainId && w.currentYardId)
+            .map((w) => w.currentYardId as string),
+        )
+      : new Set<string>();
+    const consistIsSplit = consistYards.size > 1;
+
     for (const wagon of wagons) {
       // Train-bound schedule: the built train's own consist IS the fleet — only
-      // its wagons count (wherever they currently sit; they travel with the
-      // train), and loose yard wagons never do.
+      // its wagons count, and loose yard wagons never do. A single-yard consist
+      // counts wherever it sits (it travels with the train); a split consist is
+      // counted at the yard each wagon actually stands in.
       if (builtTrainId) {
         if (wagon.trainId !== builtTrainId) continue;
+        if (consistIsSplit && wagon.currentYardId !== originYardId) continue;
       } else {
         // Schedule-scoped availability: pins held by OTHER schedules never
         // consume a wagon here — the same physical wagon may serve the July 17
@@ -5651,12 +5680,23 @@ export class TrainSchedulingService {
       // consist views draw the schedule exactly like the train builder; a schedule
       // created with reverseWagonOrder pins back-to-front (physically-last wagon
       // takes slot #1). Unsequenced wagons sort after every sequenced one.
+      const consistYards = new Set(
+        wagons
+          .filter((w) => w.trainId === builtTrainId && w.currentYardId)
+          .map((w) => w.currentYardId as string),
+      );
+      // Split consist: a slot boarding at a given yard must take a wagon that
+      // physically stands there — the train cannot load a Mojo wagon at Dire.
+      // A single-yard consist ignores this (the whole train is at one place).
+      const requiredYardId =
+        consistYards.size > 1 ? (slot.boardYardId ?? originYardId) : null;
       const candidates = wagons
         .filter(
           (w) =>
             w.trainId === builtTrainId &&
             w.wagonTypeId === slot.wagonTypeId &&
-            spanFree(w.id),
+            spanFree(w.id) &&
+            (!requiredYardId || w.currentYardId === requiredYardId),
         )
         .sort((a, b) => {
           if (a.sequenceNumber == null || b.sequenceNumber == null) {
@@ -5825,14 +5865,28 @@ export class TrainSchedulingService {
     });
     const remainingByTypeId = new Map<string, number>();
     const codesByTypeId = new Map<string, string>();
+    const byYardId = new Map<string, Map<string, number>>();
     for (const wagon of wagons) {
       remainingByTypeId.set(
         wagon.wagonTypeId,
         (remainingByTypeId.get(wagon.wagonTypeId) ?? 0) + 1,
       );
       if (wagon.wagonType) codesByTypeId.set(wagon.wagonTypeId, wagon.wagonType.code);
+      if (wagon.currentYardId) {
+        const perType = byYardId.get(wagon.currentYardId) ?? new Map<string, number>();
+        perType.set(wagon.wagonTypeId, (perType.get(wagon.wagonTypeId) ?? 0) + 1);
+        byYardId.set(wagon.currentYardId, perType);
+      }
     }
-    return { mode: 'TRAIN', remainingByTypeId, codesByTypeId };
+    // Single-yard consist (the overwhelming majority): the whole train is
+    // offered at every boarding yard exactly as before — the per-yard split is
+    // only meaningful once the consist is genuinely spread across yards.
+    return {
+      mode: 'TRAIN',
+      remainingByTypeId,
+      codesByTypeId,
+      ...(byYardId.size > 1 ? { byYardId } : {}),
+    };
   }
 
   /**
@@ -6160,6 +6214,45 @@ export class TrainSchedulingService {
     return saved;
   }
 
+  /**
+   * A built train's wagons may stand in several yards. The route must pass
+   * through every one of them as origin or an intermediate stop — never only
+   * as the final destination (the train has to pick the wagons up en route).
+   */
+  private async assertRouteCoversWagonYards(train: Train, route: Route) {
+    const wagons = await this.dataSource.getRepository(Wagon).find({
+      where: { trainId: train.id },
+      select: { id: true, currentYardId: true },
+    });
+    const wagonYards = [...new Set(wagons.map((w) => w.currentYardId).filter((y): y is string => !!y))];
+    if (!wagonYards.length) return;
+
+    const milestones = await this.dataSource
+      .getRepository(RouteMilestone)
+      .find({ where: { routeId: route.id }, order: { sequenceNo: 'ASC' } });
+    const stops = milestones.length >= 2
+      ? milestones.map((m) => m.yardId)
+      : [route.originYardId, route.destinationYardId];
+    // Every stop except the last one is a pickup point.
+    const pickupYards = new Set(stops.slice(0, -1));
+
+    const uncovered = wagonYards.filter((y) => !pickupYards.has(y));
+    if (!uncovered.length) return;
+
+    const labels = await this.yardLabelMap(uncovered);
+    const destination = stops[stops.length - 1];
+    const detail = uncovered
+      .map((y) =>
+        y === destination
+          ? `${labels.get(y) ?? y} (only as the destination)`
+          : `${labels.get(y) ?? y} (not on route)`,
+      )
+      .join(', ');
+    throw new BadRequestException(
+      `Route ${formatRouteLabel(route)} does not pass through every yard where train ${train.code}'s wagons stand: ${detail}`,
+    );
+  }
+
   private async getSchedulableRoute(routeId: string) {
     const route = await this.dataSource.getRepository(Route).findOne({
       where: { id: routeId },
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/wagon-plan-flex.util.ts b/apps/edr-freight-api/src/modules/train-scheduling/wagon-plan-flex.util.ts
index f7db22506..29a67da45 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/wagon-plan-flex.util.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/wagon-plan-flex.util.ts
@@ -43,6 +43,16 @@ export type WagonStock = {
   remainingByTypeId: Map<string, number>;
   /** Wagon-type code per id, for human-readable shortfall messages. */
   codesByTypeId: Map<string, string>;
+  /**
+   * Multi-yard consist only: yardId → (wagonTypeId → count) for the wagons
+   * standing at that yard. A train whose wagons are split across yards can
+   * only offer, at each boarding yard, the wagons physically standing there —
+   * a wagon waiting in Mojo is not bookable from Dire, and one picked up at
+   * Dire is not re-offered at Mojo. Absent (undefined) when every wagon sits
+   * in one yard, which keeps single-yard trains on the original whole-train
+   * math.
+   */
+  byYardId?: Map<string, Map<string, number>>;
 };
 
 export type FlexPlanResult = {
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/wagon-stock-ledger.util.spec.ts b/apps/edr-freight-api/src/modules/train-scheduling/wagon-stock-ledger.util.spec.ts
index 47823cddd..5815ce435 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/wagon-stock-ledger.util.spec.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/wagon-stock-ledger.util.spec.ts
@@ -68,3 +68,94 @@ describe('WagonStockLedger', () => {
     expect(ledger.availableFor(['nw5'], { fromEdge: 2, toEdge: 3 })).toBe(10);
   });
 });
+
+describe('WagonStockLedger — multi-yard consist', () => {
+  // The reported case: a built train of 53 wagons, 20 standing in Dire and 33
+  // in Mojo. Each yard may only sell the wagons physically standing there.
+  const DIRE = 'yard-dire';
+  const MOJO = 'yard-mojo';
+  const ADDIS = 'yard-addis';
+  const STOPS = [DIRE, MOJO, ADDIS];
+  const EDGES = STOPS.length - 1;
+  const splitStock = () =>
+    new Map([
+      [DIRE, new Map([['nw5', 20]])],
+      [MOJO, new Map([['nw5', 33]])],
+    ]);
+  // Legs along Dire → Mojo → Addis.
+  const DIRE_TO_ADDIS = { fromEdge: 0, toEdge: 2 };
+  const MOJO_TO_ADDIS = { fromEdge: 1, toEdge: 2 };
+
+  const splitLedger = () =>
+    new WagonStockLedger(new Map([['nw5', 53]]), EDGES, splitStock(), STOPS);
+
+  it('offers each yard only the wagons standing there', () => {
+    const ledger = splitLedger();
+    expect(ledger.availableFor(['nw5'], DIRE_TO_ADDIS)).toBe(20);
+    expect(ledger.availableFor(['nw5'], MOJO_TO_ADDIS)).toBe(33);
+  });
+
+  it('keeps the yards independent — Dire bookings never eat Mojo stock', () => {
+    const ledger = splitLedger();
+    // A Dire booking rides the whole corridor, occupying the Mojo→Addis edge…
+    expect(ledger.consume(['nw5'], 20, DIRE_TO_ADDIS)).toBe(20);
+    expect(ledger.availableFor(['nw5'], DIRE_TO_ADDIS)).toBe(0);
+    // …but those are Dire's steel, so Mojo still has its own 33 to sell.
+    expect(ledger.availableFor(['nw5'], MOJO_TO_ADDIS)).toBe(33);
+    expect(ledger.consume(['nw5'], 33, MOJO_TO_ADDIS)).toBe(33);
+    expect(ledger.availableFor(['nw5'], MOJO_TO_ADDIS)).toBe(0);
+  });
+
+  it('never lends a free Dire wagon to a Mojo customer', () => {
+    const ledger = splitLedger();
+    // Only 5 of Dire's 20 sell; the other 15 ride past Mojo empty.
+    expect(ledger.consume(['nw5'], 5, DIRE_TO_ADDIS)).toBe(5);
+    // Mojo is still capped at its own 33 — the 15 empty Dire wagons are not
+    // offered here, exactly as the operator requires.
+    expect(ledger.availableFor(['nw5'], MOJO_TO_ADDIS)).toBe(33);
+    expect(ledger.consume(['nw5'], 40, MOJO_TO_ADDIS)).toBe(33);
+  });
+
+  it('offers nothing at the destination — there is nothing to pick up there', () => {
+    const ledger = splitLedger();
+    // A leg boarding at the last stop has no pool of its own.
+    expect(ledger.availableFor(['nw5'], { fromEdge: 2, toEdge: 2 })).toBe(0);
+  });
+
+  it('second example: Addis → Dire → Indode → Mojo → Djibouti', () => {
+    const [ADD, DIRE_2, INDODE, MOJO_2, DJIBOUTI] = [
+      'yard-add',
+      'yard-dire',
+      'yard-indode',
+      'yard-mojo',
+      'yard-djibouti',
+    ];
+    const stops = [ADD, DIRE_2, INDODE, MOJO_2, DJIBOUTI];
+    const ledger = new WagonStockLedger(
+      new Map([['nw5', 53]]),
+      stops.length - 1,
+      new Map([
+        [DIRE_2, new Map([['nw5', 20]])],
+        [MOJO_2, new Map([['nw5', 33]])],
+      ]),
+      stops,
+    );
+    const to = (fromEdge: number) => ({ fromEdge, toEdge: stops.length - 1 });
+    // Addis: the train starts empty — nothing to sell.
+    expect(ledger.availableFor(['nw5'], to(0))).toBe(0);
+    // Dire: the 20 wagons waiting there.
+    expect(ledger.availableFor(['nw5'], to(1))).toBe(20);
+    // Indode: the same 20 wagons, which have moved with the train.
+    expect(ledger.availableFor(['nw5'], to(2))).toBe(0);
+    // Mojo: its own 33 only.
+    expect(ledger.availableFor(['nw5'], to(3))).toBe(33);
+  });
+
+  it('single-yard consist keeps the original whole-train behaviour', () => {
+    // No byYardId (the train is not split) — every leg sees the whole train,
+    // exactly as before this feature.
+    const ledger = new WagonStockLedger(new Map([['nw5', 53]]), EDGES);
+    expect(ledger.availableFor(['nw5'], DIRE_TO_ADDIS)).toBe(53);
+    expect(ledger.availableFor(['nw5'], MOJO_TO_ADDIS)).toBe(53);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/train-scheduling/wagon-stock-ledger.util.ts b/apps/edr-freight-api/src/modules/train-scheduling/wagon-stock-ledger.util.ts
index 0e4f6949d..bf5b935ad 100644
--- a/apps/edr-freight-api/src/modules/train-scheduling/wagon-stock-ledger.util.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/wagon-stock-ledger.util.ts
@@ -20,17 +20,53 @@ import type { CorridorLeg } from './corridor-capacity.util';
  * Gelan→Adama never competes for stock with an export on Adama→Doraleh.
  */
 export class WagonStockLedger {
+  /**
+   * Usage rows keyed by pool. A single-yard train has one pool (''), so this is
+   * exactly the original per-type accounting. A multi-yard consist keys by
+   * boarding yard as well, because the Dire wagons and the Mojo wagons are
+   * disjoint sets of steel: 5 Dire wagons riding the whole corridor occupy the
+   * Mojo→Addis edge, but they must not shrink what Mojo itself can offer.
+   */
   private readonly usedPerEdge = new Map<string, number[]>();
 
   constructor(
     private readonly remainingByTypeId: Map<string, number>,
     private readonly edgeCount: number,
+    /**
+     * Multi-yard consist only (see {@link WagonStock.byYardId}): the wagons
+     * standing at each yard. When present, a leg is served ONLY by the wagons
+     * standing at the yard it boards from — a Dire→Addis booking on a train
+     * whose wagons sit 20 in Dire and 33 in Mojo sees 20, and a Mojo→Addis
+     * booking sees 33, never the Dire wagons that ride past empty.
+     */
+    private readonly byYardId?: Map<string, Map<string, number>>,
+    /** Ordered corridor stops, parallel to the edges — maps an edge to its yard. */
+    private readonly stops: readonly string[] = [],
   ) {}
 
+  /** The yard a leg boards from, or '' when the train is not split across yards. */
+  private poolYardOf(leg: CorridorLeg): string {
+    if (!this.byYardId) return '';
+    return this.stops[leg.fromEdge] ?? '';
+  }
+
+  /** Usage-row key: one row per (pool, wagon type). */
+  private rowKey(wagonTypeId: string, leg: CorridorLeg): string {
+    const pool = this.poolYardOf(leg);
+    return pool ? `${pool}\u0000${wagonTypeId}` : wagonTypeId;
+  }
+
+  /** Wagons of one type offered at the yard a leg boards from. */
+  private totalForType(wagonTypeId: string, leg: CorridorLeg): number {
+    const pool = this.poolYardOf(leg);
+    if (!pool) return this.remainingByTypeId.get(wagonTypeId) ?? 0;
+    return this.byYardId?.get(pool)?.get(wagonTypeId) ?? 0;
+  }
+
   /** Free wagons of ONE type on a leg: total minus its busiest edge within that leg. */
   private availableForType(wagonTypeId: string, leg: CorridorLeg): number {
-    const total = this.remainingByTypeId.get(wagonTypeId) ?? 0;
-    const row = this.usedPerEdge.get(wagonTypeId);
+    const total = this.totalForType(wagonTypeId, leg);
+    const row = this.usedPerEdge.get(this.rowKey(wagonTypeId, leg));
     if (!row) return total;
     let busiest = 0;
     for (let edge = leg.fromEdge; edge < leg.toEdge; edge += 1) {
@@ -69,10 +105,11 @@ export class WagonStockLedger {
       if (!deepest) break;
 
       const take = Math.min(outstanding, deepest.free);
-      let row = this.usedPerEdge.get(deepest.id);
+      const key = this.rowKey(deepest.id, leg);
+      let row = this.usedPerEdge.get(key);
       if (!row) {
         row = new Array<number>(this.edgeCount).fill(0);
-        this.usedPerEdge.set(deepest.id, row);
+        this.usedPerEdge.set(key, row);
       }
       for (let edge = leg.fromEdge; edge < leg.toEdge; edge += 1) {
         row[edge] = (row[edge] ?? 0) + take;
diff --git a/apps/edr-freight-api/src/modules/trains/dto/build-train.dto.ts b/apps/edr-freight-api/src/modules/trains/dto/build-train.dto.ts
index 7b0bdd3bd..08a424cdc 100644
--- a/apps/edr-freight-api/src/modules/trains/dto/build-train.dto.ts
+++ b/apps/edr-freight-api/src/modules/trains/dto/build-train.dto.ts
@@ -44,7 +44,7 @@ export class BuildTrainDto {
   @ApiPropertyOptional({
     type: [String],
     format: 'uuid',
-    description: 'Wagons to attach at build time, in consist order (must sit in the same yard)',
+    description: 'Wagons to attach at build time, in consist order (any yard)',
   })
   @IsOptional()
   @IsArray()
diff --git a/apps/edr-freight-api/src/modules/trains/train-builder.service.ts b/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
index 0f377071c..4b94b2dcb 100644
--- a/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
+++ b/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
@@ -283,6 +283,10 @@ export class TrainBuilderService {
       wagonNumber: wagon.wagonNumber,
       sequenceNumber: wagon.sequenceNumber,
       status: wagon.status,
+      currentYardId: wagon.currentYardId ?? null,
+      currentYard: wagon.currentYard
+        ? { id: wagon.currentYard.id, code: wagon.currentYard.code, label: wagon.currentYard.label }
+        : null,
       wagonType: wagon.wagonType
         ? {
             id: wagon.wagonType.id,
@@ -326,6 +330,27 @@ export class TrainBuilderService {
         : null,
       locomotives,
       wagons,
+      // Where the consist physically stands. A train built from several yards
+      // only picks a yard's wagons up when it reaches that yard, and a customer
+      // boarding there can only book the wagons standing there — the schedule
+      // route must therefore cover every one of these yards before its
+      // destination.
+      wagonYards: [
+        ...wagons
+          .reduce((acc, wagon) => {
+            const id = wagon.currentYardId ?? 'UNASSIGNED';
+            const entry = acc.get(id) ?? {
+              yardId: wagon.currentYardId ?? null,
+              code: wagon.currentYard?.code ?? null,
+              label: wagon.currentYard?.label ?? null,
+              wagonCount: 0,
+            };
+            entry.wagonCount += 1;
+            acc.set(id, entry);
+            return acc;
+          }, new Map<string, { yardId: string | null; code: string | null; label: string | null; wagonCount: number }>())
+          .values(),
+      ].sort((a, b) => b.wagonCount - a.wagonCount),
       totals: {
         wagonCount: wagons.length,
         totalTareTons,
@@ -428,10 +453,13 @@ export class TrainBuilderService {
   }
 
   /**
-   * Relocate the train to another yard. The consist moves as one unit: every
-   * coupled locomotive and wagon follows to the new yard (so their current
-   * yards always match the train's), and each wagon gets a movement-ledger row.
-   * Blocked while the train is out on a dispatched run.
+   * Relocate the train to another yard. The locomotives always follow. Of the
+   * wagons, only those standing WITH the train move: on a consist spread
+   * across yards (20 in Dire, 33 waiting in Mojo), moving the train Dire→Mojo
+   * relocates the 20 it is actually pulling and leaves the Mojo wagons where
+   * they stand — the train collects those by arriving, not by this call.
+   * Each moved wagon gets a movement-ledger row. Blocked while the train is
+   * out on a dispatched run.
    */
   async setYard(id: string, currentYardId: string) {
     await this.dataSource.transaction(async (manager) => {
@@ -439,6 +467,7 @@ export class TrainBuilderService {
       if (train.currentYardId === currentYardId) return;
       const yard = await manager.getRepository(Yard).findOne({ where: { id: currentYardId } });
       if (!yard) throw new NotFoundException(`Yard ${currentYardId} not found`);
+      const previousYardId = train.currentYardId ?? null;
 
       await manager.getRepository(Train).update(train.id, { currentYardId: yard.id });
 
@@ -454,7 +483,17 @@ export class TrainBuilderService {
           );
       }
 
-      const wagons = await manager.getRepository(Wagon).find({ where: { trainId: train.id } });
+      const allWagons = await manager
+        .getRepository(Wagon)
+        .find({ where: { trainId: train.id } });
+      // Wagons travelling with the train = those at the yard it is leaving.
+      // A yard-less wagon has no standing position of its own, so it follows.
+      const wagons = allWagons.filter(
+        (wagon) =>
+          wagon.currentYardId == null ||
+          previousYardId == null ||
+          wagon.currentYardId === previousYardId,
+      );
       const now = new Date();
       for (const wagon of wagons) {
         if (wagon.currentYardId === yard.id) continue;
@@ -475,7 +514,7 @@ export class TrainBuilderService {
     return this.getComposition(id);
   }
 
-  /** Append AVAILABLE wagons from the train's own yard to the consist. */
+  /** Append AVAILABLE, unassigned wagons (any yard) to the consist. */
   async assignWagons(id: string, dto: AssignTrainWagonsDto, userId?: string | null) {
     await this.dataSource.transaction(async (manager) => {
       const train = await this.getEditableTrain(manager, id);
@@ -1037,11 +1076,8 @@ export class TrainBuilderService {
       if (wagon.status !== WagonStatus.Available) {
         throw new ConflictException(`Wagon ${wagon.wagonNumber} is not available (${wagon.status})`);
       }
-      if (wagon.currentYardId !== train.currentYardId) {
-        throw new BadRequestException(
-          `Wagon ${wagon.wagonNumber} is not in the train's yard; only wagons in the same yard can be attached`,
-        );
-      }
+      // Wagons may sit in any yard — the schedule's route must pass through
+      // every wagon yard before its destination (checked at scheduling time).
       toAttach.push(wagon);
     }
     if (!toAttach.length) return [];
diff --git a/apps/edr-freight-api/src/modules/wagons/wagons.service.ts b/apps/edr-freight-api/src/modules/wagons/wagons.service.ts
index b5a14f6f3..f2c76e283 100644
--- a/apps/edr-freight-api/src/modules/wagons/wagons.service.ts
+++ b/apps/edr-freight-api/src/modules/wagons/wagons.service.ts
@@ -342,8 +342,8 @@ export class WagonsService {
 
   async assignToTrain(wagonId: string, dto: AssignWagonToTrainDto): Promise<Wagon> {
     const wagon = await this.findById(wagonId);
-    // Mirror train-builder attachWagons: only a truly free, available wagon in
-    // the train's own yard can be coupled, and never onto a dispatched train.
+    // Mirror train-builder attachWagons: only a truly free, available wagon
+    // (any yard) can be coupled, and never onto a dispatched train.
     if (wagon.trainId != null) {
       throw new ConflictException(`Wagon ${wagon.wagonNumber} is already on another train`);
     }
@@ -358,11 +358,6 @@ export class WagonsService {
         `Train ${train.code} is out on a dispatched run; its composition is frozen until arrival`,
       );
     }
-    if (wagon.currentYardId !== train.currentYardId) {
-      throw new BadRequestException(
-        `Wagon ${wagon.wagonNumber} is not in the train's yard; only wagons in the same yard can be attached`,
-      );
-    }
 
     const maxSeq = await this.wagonRepo
       .createQueryBuilder('w')
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 24be04f66..87ba8cf8a 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -1465,6 +1465,16 @@ export const GRANULAR_SPLIT_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:settings:exchange_rate:manage",
     "Set the USD-ETB fallback rate",
   ),
+  perm(
+    "b4d00001-0001-4000-8000-000000000003",
+    "edr_freight_app:settings:manual_payment:view",
+    "View the manual (offline) payment channel settings",
+  ),
+  perm(
+    "b4d00001-0001-4000-8000-000000000004",
+    "edr_freight_app:settings:manual_payment:manage",
+    "Enable or disable manual invoice settlement per currency",
+  ),
   perm(
     "b4e00001-0001-4000-8000-000000000001",
     "edr_freight_app:settings:contract_templates:view",
@@ -2112,6 +2122,14 @@ export const FREIGHT_PERMS = {
       view: "edr_freight_app:settings:exchange_rate:view",
       manage: "edr_freight_app:settings:exchange_rate:manage",
     },
+    // Whether Finance may settle invoices by hand, per currency. Split
+    // view/manage on purpose: Finance reads it (the worklist offers only the
+    // enabled currencies) but must not switch its own channel on — same
+    // maker-checker split as the other sensitive finance settings.
+    manualPayment: {
+      view: "edr_freight_app:settings:manual_payment:view",
+      manage: "edr_freight_app:settings:manual_payment:manage",
+    },
     contractTemplates: {
       view: "edr_freight_app:settings:contract_templates:view",
       manage: "edr_freight_app:settings:contract_templates:manage",
@@ -2416,6 +2434,9 @@ export const ROLE_PERMISSION_PRESETS = {
     FREIGHT_PERMS.invoices.export,
     // Manual settlement (bank transfer / counter) of USD and ETB invoices.
     FREIGHT_PERMS.invoices.confirmOffline,
+    // Read-only: the worklist offers whichever currencies are switched on.
+    // Flipping the switch is deliberately NOT here — see `manualPayment`.
+    FREIGHT_PERMS.settings.manualPayment.view,
     // Deliberately NOT granted here: invoices:eims_register, eims_resolve, eims_cancel,
     // eims_receipt_register, eims:memo_issue. Automatic filing needs no human permission at all
     // (the cron sweep runs as the system); these are the *manual* exceptional-operations
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index c131af4bd..f07ec32b5 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -86,6 +86,7 @@ import TrainScheduleTrackPage from "./pages/trainScheduling/TrainScheduleTrackPa
 import TrainSchedulingGlobalRulesPage from "./pages/trainScheduling/TrainSchedulingGlobalRulesPage";
 import TradeAccessPage from "./pages/configuration/TradeAccessPage";
 import ExchangeRateSettingsCard from "./pages/settings/ExchangeRateSettingsCard";
+import ManualPaymentSettingsCard from "./pages/settings/ManualPaymentSettingsCard";
 import FirstMilePage from "./pages/operations/FirstMilePage";
 import LastMilePage from "./pages/operations/LastMilePage";
 import TrainDetailPage from "./pages/trains/TrainDetailPage";
@@ -1147,6 +1148,18 @@ const App = () => {
             </RequirePermission>
           }
         />
+        <Route
+          path="configuration/manual-payments"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.settings.manualPayment.view}
+            >
+              <div className="p-4">
+                <ManualPaymentSettingsCard />
+              </div>
+            </RequirePermission>
+          }
+        />
         <Route
           path="configuration/exchange-rate"
           element={
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index 293e82450..ba5637821 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -555,6 +555,11 @@ export const buildSidebarSections = (
               href: "/dashboard/configuration/exchange-rate",
               permission: FREIGHT_PERMS.settings.exchangeRate.view,
             },
+            {
+              label: "Manual payments",
+              href: "/dashboard/configuration/manual-payments",
+              permission: FREIGHT_PERMS.settings.manualPayment.view,
+            },
           ],
         },
         {
diff --git a/apps/edr-freight-web/backoffice/src/components/trainBuilder/AvailableWagonsPanel.tsx b/apps/edr-freight-web/backoffice/src/components/trainBuilder/AvailableWagonsPanel.tsx
index 1bddb77cd..034b4c0bb 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainBuilder/AvailableWagonsPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainBuilder/AvailableWagonsPanel.tsx
@@ -4,34 +4,40 @@ import {
   Button,
   Checkbox,
   Group,
+  Pagination,
   ScrollArea,
   Select,
   Stack,
   Text,
   TextInput,
 } from "@mantine/core";
+import { useDebouncedValue } from "@mantine/hooks";
 import { useQuery } from "@tanstack/react-query";
-import { Plus, Search } from "lucide-react";
-import { useMemo, useState } from "react";
+import { MapPin, Plus, Search } from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+
+const PAGE_SIZE = 20;
 
 import { api } from "@/services/api";
 
 /**
- * AVAILABLE wagons standing in the train's own yard — the only ones that can
- * be coupled. Pick any number and append them to the consist.
+ * AVAILABLE, unassigned wagons from every yard — filtered and paged on the API,
+ * so the picker never page-walks the whole fleet into the browser.
  */
 export default function AvailableWagonsPanel({
-  yardId,
-  yardLabel,
+  homeYardId,
   onAssign,
   assigning,
   exportTrainNumber,
   importTrainNumber,
 }: AvailableWagonsPanelProps) {
   const [search, setSearch] = useState("");
+  const [debouncedSearch] = useDebouncedValue(search, 300);
   const [typeFilter, setTypeFilter] = useState<string>("ALL");
+  const [yardFilter, setYardFilter] = useState<string>("ALL");
   const [runOnly, setRunOnly] = useState(false);
   const [selected, setSelected] = useState<string[]>([]);
+  const [page, setPage] = useState(1);
 
   // The train's own run, e.g. "8001-8002" — only offered when the train has one.
   const runLabel = exportTrainNumber
@@ -39,59 +45,65 @@ export default function AvailableWagonsPanel({
     : null;
 
   const wagonsQuery = useQuery(
-    api.wagons.list.queryOptions({
+    api.wagons.listPaged.queryOptions({
       input: {
         filters: {
           status: Freight.WagonStatus.Available,
-          currentYardId: yardId,
           // Loose wagons only — one already on another train cannot be coupled.
           unassigned: true,
+          search: debouncedSearch.trim() || undefined,
+          currentYardId: yardFilter === "ALL" ? undefined : yardFilter,
+          wagonTypeId: typeFilter === "ALL" ? undefined : typeFilter,
+          // Rostered to this train's run — the API matches either run column.
+          trainNumber: runOnly && exportTrainNumber ? exportTrainNumber : undefined,
+          page,
+          pageSize: PAGE_SIZE,
         },
       },
-      enabled: Boolean(yardId),
     }),
   );
 
-  const wagons = useMemo(() => {
-    const q = search.trim().toLowerCase();
-    return (wagonsQuery.data ?? []).filter((wagon) => {
-      if (typeFilter !== "ALL" && wagon.wagonTypeId !== typeFilter) return false;
-      // Rostered to this train's run — match on the export run, which fixes the
-      // import run anyway.
-      if (runOnly && wagon.exportTrainNumber !== exportTrainNumber) return false;
-      if (q && !wagon.wagonNumber.toLowerCase().includes(q)) return false;
-      return true;
-    });
-  }, [wagonsQuery.data, search, typeFilter, runOnly, exportTrainNumber]);
+  const wagons = wagonsQuery.data?.items ?? [];
+  const total = wagonsQuery.data?.meta.total ?? 0;
+  const totalPages = Math.max(1, wagonsQuery.data?.meta.totalPages ?? 1);
 
-  const runMatchCount = useMemo(
-    () =>
-      exportTrainNumber
-        ? (wagonsQuery.data ?? []).filter(
-            (w) => w.exportTrainNumber === exportTrainNumber,
-          ).length
-        : 0,
-    [wagonsQuery.data, exportTrainNumber],
-  );
+  // Filters change → back to page 1 (and clamp when the list shrinks).
+  useEffect(() => {
+    setPage(1);
+  }, [debouncedSearch, typeFilter, yardFilter, runOnly]);
+  useEffect(() => {
+    if (page > totalPages) setPage(totalPages);
+  }, [page, totalPages]);
 
-  const typeOptions = useMemo(() => {
-    const byId = new Map<string, string>();
-    for (const wagon of wagonsQuery.data ?? []) {
-      if (wagon.wagonType) {
-        // e.g. "Flat wagon (NW5)" — name with its type code.
-        byId.set(
-          wagon.wagonType.id,
-          wagon.wagonType.code
-            ? `${wagon.wagonType.name} (${wagon.wagonType.code})`
-            : wagon.wagonType.name,
-        );
-      }
-    }
+  // Dropdowns come from the reference lists, not the current page — a yard or
+  // type must stay pickable even when this page holds none of it.
+  const yardsQuery = useQuery(api.routes.yards.queryOptions({ staleTime: 5 * 60_000 }));
+  const wagonTypesQuery = useQuery(api.wagonTypes.list.queryOptions({ staleTime: 5 * 60_000 }));
+
+  const yardOptions = useMemo(() => {
+    const yards = [...(yardsQuery.data ?? [])].sort((a, b) =>
+      a.id === homeYardId ? -1 : b.id === homeYardId ? 1 : a.label.localeCompare(b.label),
+    );
     return [
-      { value: "ALL", label: "All types" },
-      ...[...byId.entries()].map(([value, label]) => ({ value, label })),
+      { value: "ALL", label: "All yards" },
+      ...yards.map((yard) => ({
+        value: yard.id,
+        label: `${yard.label}${yard.id === homeYardId ? " · train's yard" : ""}`,
+      })),
     ];
-  }, [wagonsQuery.data]);
+  }, [yardsQuery.data, homeYardId]);
+
+  const typeOptions = useMemo(
+    () => [
+      { value: "ALL", label: "All types" },
+      // e.g. "Flat wagon (NW5)" — name with its type code.
+      ...(wagonTypesQuery.data ?? []).map((type) => ({
+        value: type.id,
+        label: type.code ? `${type.name} (${type.code})` : type.name,
+      })),
+    ],
+    [wagonTypesQuery.data],
+  );
 
   const toggle = (wagonId: string, checked: boolean) => {
     setSelected((prev) =>
@@ -99,8 +111,8 @@ export default function AvailableWagonsPanel({
     );
   };
 
-  const allSelected =
-    wagons.length > 0 && wagons.every((w) => selected.includes(w.id));
+  // Select-all covers this page only — the rest of the matches are not loaded.
+  const allSelected = wagons.length > 0 && wagons.every((w) => selected.includes(w.id));
   const someSelected = wagons.some((w) => selected.includes(w.id));
 
   const toggleAll = (checked: boolean) => {
@@ -138,24 +150,40 @@ export default function AvailableWagonsPanel({
           onChange={(v) => setTypeFilter(v ?? "ALL")}
         />
       </Group>
+      <Select
+        size="sm"
+        leftSection={<MapPin size={14} />}
+        data={yardOptions}
+        value={yardFilter}
+        onChange={(v) => setYardFilter(v ?? "ALL")}
+        searchable
+        aria-label="Filter by yard"
+      />
 
       {runLabel ? (
         <Checkbox
           size="sm"
-          label={`Only wagons on this train's run (${runLabel}) — ${runMatchCount} here`}
+          label={`Only wagons on this train's run (${runLabel})`}
           checked={runOnly}
           onChange={(e) => setRunOnly(e.currentTarget.checked)}
         />
       ) : null}
 
       {wagons.length ? (
-        <Checkbox
-          size="sm"
-          label={`Select all (${wagons.length})`}
-          checked={allSelected}
-          indeterminate={!allSelected && someSelected}
-          onChange={(e) => toggleAll(e.currentTarget.checked)}
-        />
+        <Group justify="space-between" wrap="nowrap">
+          <Checkbox
+            size="sm"
+            label={`Select all on this page (${wagons.length})`}
+            checked={allSelected}
+            indeterminate={!allSelected && someSelected}
+            onChange={(e) => toggleAll(e.currentTarget.checked)}
+          />
+          {selected.length ? (
+            <Text size="xs" c="dimmed">
+              {selected.length} selected
+            </Text>
+          ) : null}
+        </Group>
       ) : null}
 
       <ScrollArea.Autosize mah={380} type="auto">
@@ -166,7 +194,7 @@ export default function AvailableWagonsPanel({
             </Text>
           ) : !wagons.length ? (
             <Text py="md" ta="center" c="dimmed" size="sm">
-              No available wagons in {yardLabel ?? "this yard"}
+              No available wagons match
             </Text>
           ) : (
             wagons.map((wagon) => (
@@ -191,6 +219,15 @@ export default function AvailableWagonsPanel({
                     <Text size="sm" fw={600} ff="monospace" truncate>
                       {wagon.wagonNumber}
                     </Text>
+                    <Badge
+                      size="xs"
+                      radius="sm"
+                      variant="outline"
+                      color={wagon.currentYardId === homeYardId ? "edr-green" : "gray"}
+                      leftSection={<MapPin size={10} />}
+                    >
+                      {wagon.currentYard?.label ?? wagon.currentYard?.code ?? "No yard"}
+                    </Badge>
                     {wagon.exportTrainNumber ? (
                       <Badge
                         size="xs"
@@ -217,6 +254,15 @@ export default function AvailableWagonsPanel({
         </Stack>
       </ScrollArea.Autosize>
 
+      {totalPages > 1 ? (
+        <Group justify="space-between" wrap="nowrap">
+          <Text size="xs" c="dimmed">
+            {(page - 1) * PAGE_SIZE + 1}–{Math.min(page * PAGE_SIZE, total)} of {total}
+          </Text>
+          <Pagination size="sm" value={page} onChange={setPage} total={totalPages} />
+        </Group>
+      ) : null}
+
       <Button
         leftSection={<Plus size={16} />}
         disabled={!selected.length}
@@ -230,8 +276,8 @@ export default function AvailableWagonsPanel({
 }
 
 export interface AvailableWagonsPanelProps {
-  yardId: string;
-  yardLabel?: string | null;
+  /** The train's own yard — sorted first and highlighted; not a restriction. */
+  homeYardId: string | null;
   onAssign: (wagonIds: string[]) => void;
   assigning: boolean;
   /** This train's odd EXPORT run — drives the "only this run" filter. */
diff --git a/apps/edr-freight-web/backoffice/src/components/trainBuilder/ConsistWagonList.tsx b/apps/edr-freight-web/backoffice/src/components/trainBuilder/ConsistWagonList.tsx
index 2aab0ca10..179502b2d 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainBuilder/ConsistWagonList.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainBuilder/ConsistWagonList.tsx
@@ -7,7 +7,7 @@ import {
   type DropResult,
 } from "@hello-pangea/dnd";
 import { ActionIcon, Badge, Box, Group, Stack, Text, Tooltip } from "@mantine/core";
-import { GripVertical, Trash2, Wrench } from "lucide-react";
+import { GripVertical, MapPin, Trash2, Wrench } from "lucide-react";
 import { type ReactNode } from "react";
 import { createPortal } from "react-dom";
 
@@ -191,6 +191,11 @@ function WagonRow({
                 {wagon.wagonType.code}
               </Badge>
             ) : null}
+            {wagon.currentYard ? (
+              <Badge variant="outline" color="gray" size="xs" radius="sm" leftSection={<MapPin size={10} />}>
+                {wagon.currentYard.label ?? wagon.currentYard.code}
+              </Badge>
+            ) : null}
           </Group>
           <Text size="xs" c="dimmed" truncate>
             {wagon.wagonType
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index 4f2001a29..d3165f696 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -57,6 +57,10 @@ export const URL_CONSTANTS = {
     BASE: "/exchange-settings",
   },
 
+  MANUAL_PAYMENT_SETTINGS: {
+    BASE: "/payment-settings/manual",
+  },
+
   AUDIT_LOGS: {
     BASE: "/audit",
   },
diff --git a/apps/edr-freight-web/backoffice/src/hooks/useManualPaymentSettings.ts b/apps/edr-freight-web/backoffice/src/hooks/useManualPaymentSettings.ts
new file mode 100644
index 000000000..b49f33376
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/hooks/useManualPaymentSettings.ts
@@ -0,0 +1,39 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useTranslation } from "react-i18next";
+import { toast } from "sonner";
+
+import {
+  manualPaymentSettingsService,
+  type ManualPaymentSettings,
+} from "@/services/manualPaymentSettings.service";
+import { useErrorHandler } from "@/shared/hooks/useErrorHandler";
+
+export const MANUAL_PAYMENT_SETTINGS_KEY = ["manualPaymentSettings"];
+
+export const useManualPaymentSettingsQuery = () =>
+  useQuery({
+    queryKey: MANUAL_PAYMENT_SETTINGS_KEY,
+    queryFn: () => manualPaymentSettingsService.get(),
+    staleTime: 60_000,
+  });
+
+export const useUpdateManualPaymentSettings = () => {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+  const { handleError } = useErrorHandler(t);
+
+  return useMutation({
+    mutationFn: (
+      patch: Partial<Pick<ManualPaymentSettings, "etbEnabled" | "usdEnabled">>,
+    ) => manualPaymentSettingsService.update(patch),
+    onSuccess: (data) => {
+      queryClient.setQueryData(MANUAL_PAYMENT_SETTINGS_KEY, data);
+      // The Manual Payments worklist only lists enabled currencies.
+      queryClient.invalidateQueries({ queryKey: ["invoices"] });
+      toast.success(
+        t("manualPaymentSettings.updated", "Manual payment settings updated"),
+      );
+    },
+    onError: handleError,
+  });
+};
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index fe4d4fff9..218989517 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -372,6 +372,12 @@ export const FREIGHT_PERMS = {
       view: "edr_freight_app:settings:exchange_rate:view",
       manage: "edr_freight_app:settings:exchange_rate:manage",
     },
+    // Whether Finance may settle invoices by hand, per currency. Finance holds
+    // `view` (the worklist offers only enabled currencies); `manage` is admin.
+    manualPayment: {
+      view: "edr_freight_app:settings:manual_payment:view",
+      manage: "edr_freight_app:settings:manual_payment:manage",
+    },
     contractTemplates: {
       view: "edr_freight_app:settings:contract_templates:view",
       manage: "edr_freight_app:settings:contract_templates:manage",
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx
index d5ac83987..6465be167 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/FinanceHubPage.tsx
@@ -1,8 +1,9 @@
 import { Tabs } from "@mantine/core";
-import { Landmark, Receipt } from "lucide-react";
+import { Banknote, DollarSign, Receipt } from "lucide-react";
 import { useSearchParams } from "react-router-dom";
 
 import { useAuth } from "@/auth/useAuth";
+import { useManualPaymentSettingsQuery } from "@/hooks/useManualPaymentSettings";
 import { PageContainer, PageHeader } from "@/components/page";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 
@@ -16,7 +17,9 @@ import UsdPaymentsPanel from "./UsdPaymentsPage";
  * before, and just doesn't render if the user lacks it.
  *
  * The Payments tab was removed; its summary (total collected, ETB/USD) now
- * lives as a card at the top of the Invoices tab instead.
+ * lives as a card at the top of the Invoices tab instead. Manual payments are
+ * split into one tab per currency — ETB keeps the original `?tab=manual-payments`
+ * key so existing links and the old redirect still land somewhere valid.
  */
 const TABS = [
   {
@@ -30,13 +33,25 @@ const TABS = [
   },
   {
     key: "manual-payments",
-    label: "Manual Payments",
-    icon: Landmark,
+    label: "Manual Payments (ETB)",
+    icon: Banknote,
     // Same gate as Invoices, not a dedicated key — mirrors the old route.
     permission: FREIGHT_PERMS.invoices.view,
+    /** Hidden unless manual settlement is switched on for this currency. */
+    manualCurrency: "ETB",
     subtitle:
-      "Import and export invoices in USD or ETB that Finance settles by hand (bank transfer or counter). Upload the customer's slip and confirm the payment before the pay window closes.",
-    Panel: UsdPaymentsPanel,
+      "Import and export invoices in ETB that Finance settles by hand (bank transfer or counter). Upload the customer's slip and confirm the payment before the pay window closes.",
+    Panel: () => <UsdPaymentsPanel currency="ETB" />,
+  },
+  {
+    key: "manual-payments-usd",
+    label: "Manual Payments (USD)",
+    icon: DollarSign,
+    permission: FREIGHT_PERMS.invoices.view,
+    manualCurrency: "USD",
+    subtitle:
+      "Import and export invoices in USD that Finance settles by hand (bank transfer or counter). Upload the customer's slip and confirm the payment before the pay window closes.",
+    Panel: () => <UsdPaymentsPanel currency="USD" />,
   },
 ] as const;
 
@@ -46,7 +61,18 @@ export default function FinanceHubPage() {
   const { user } = useAuth();
   const [searchParams, setSearchParams] = useSearchParams();
 
-  const visibleTabs = TABS.filter((tab) => hasPermission(user, tab.permission));
+  // A currency whose manual-payment channel is switched off has no tab at all
+  // — the list would be empty and every confirmation refused.
+  const { data: manualSettings } = useManualPaymentSettingsQuery();
+  const manualEnabled = (currency: "ETB" | "USD") =>
+    !manualSettings ||
+    (currency === "ETB" ? manualSettings.etbEnabled : manualSettings.usdEnabled);
+
+  const visibleTabs = TABS.filter(
+    (tab) =>
+      hasPermission(user, tab.permission) &&
+      (!("manualCurrency" in tab) || manualEnabled(tab.manualCurrency)),
+  );
   const requested = searchParams.get("tab");
   const active: TabKey =
     visibleTabs.find((tab) => tab.key === requested)?.key ??
diff --git a/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx
index 93098ff32..5b4da0f43 100644
--- a/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/invoices/UsdPaymentsPage.tsx
@@ -27,6 +27,7 @@ import {
 } from "@/components/customers";
 import { PhasedFileDropzone } from "@/components/contracts/PhasedFileDropzone";
 import { useAuth } from "@/auth/useAuth";
+import { useManualPaymentSettingsQuery } from "@/hooks/useManualPaymentSettings";
 import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
 import { api } from "@/services/api";
 import type { OfflineUsdInvoice } from "@/types/invoice";
@@ -144,7 +145,11 @@ function ConfirmCell({
  * Finance settles by hand; confirming records the payment the same way an
  * online payment would, so the booking advances identically.
  */
-export default function UsdPaymentsPanel() {
+export default function UsdPaymentsPanel({
+  currency,
+}: {
+  currency: "USD" | "ETB";
+}) {
   const navigate = useNavigate();
   const { pagination, setPagination } = usePagination({ pageSize: 10 });
   const [query, setQuery] = useState("");
@@ -152,7 +157,6 @@ export default function UsdPaymentsPanel() {
   const [statusFilter, setStatusFilter] = useState<"" | Freight.InvoiceStatus>(
     "",
   );
-  const [currency, setCurrency] = useState<"" | "USD" | "ETB">("");
   const [confirming, setConfirming] = useState<OfflineUsdInvoice | null>(null);
   const [slip, setSlip] = useState<File | null>(null);
   const [reference, setReference] = useState("");
@@ -163,13 +167,23 @@ export default function UsdPaymentsPanel() {
     FREIGHT_PERMS.invoices.confirmOffline,
   );
 
+  // Manual settlement is switched on per currency in Configuration → Manual
+  // payments. FinanceHubPage hides the tab for a disabled currency; this is
+  // the fallback for a direct `?tab=` link, and the API refuses regardless.
+  const { data: manualSettings } = useManualPaymentSettingsQuery();
+  const currencyEnabled = manualSettings
+    ? currency === "ETB"
+      ? manualSettings.etbEnabled
+      : manualSettings.usdEnabled
+    : true;
+
   const filter = useMemo(
     () => ({
       page: pagination.pageIndex + 1,
       pageSize: pagination.pageSize,
       search: debouncedQuery,
       status: statusFilter || undefined,
-      currency: currency || undefined,
+      currency,
     }),
     [
       pagination.pageIndex,
@@ -180,9 +194,10 @@ export default function UsdPaymentsPanel() {
     ],
   );
 
-  const { data, isLoading, isError, refetch, isFetching } = useQuery(
-    api.invoices.listOfflineUsd.queryOptions({ input: { filter } }),
-  );
+  const { data, isLoading, isError, refetch, isFetching } = useQuery({
+    ...api.invoices.listOfflineUsd.queryOptions({ input: { filter } }),
+    enabled: currencyEnabled,
+  });
 
   const confirm = useMutation(api.invoices.confirmOffline.mutationOptions());
 
@@ -289,20 +304,6 @@ export default function UsdPaymentsPanel() {
           );
         },
       },
-      {
-        id: "currency",
-        header: "Currency",
-        cell: ({ row }) => (
-          <Badge
-            size="sm"
-            variant="light"
-            radius="sm"
-            color={row.original.currency?.toUpperCase() === "USD" ? "blue" : "teal"}
-          >
-            {row.original.currency}
-          </Badge>
-        ),
-      },
       {
         id: "status",
         header: "Status",
@@ -342,11 +343,12 @@ export default function UsdPaymentsPanel() {
         meta: { headerClassName: "text-right", cellClassName: "text-right" },
         cell: ({ row }) => {
           if (row.original.status === "PAID" || !canConfirm) return null;
+          if (!currencyEnabled) return null;
           return <ConfirmCell row={row.original} onConfirm={setConfirming} />;
         },
       },
     ],
-    [canConfirm, navigate],
+    [canConfirm, currencyEnabled, navigate],
   );
 
   return (
@@ -376,20 +378,6 @@ export default function UsdPaymentsPanel() {
                 style={{ flex: 1, minWidth: "240px" }}
                 radius="lg"
               />
-              <SegmentedControl
-                size="sm"
-                radius="md"
-                value={currency || "all"}
-                onChange={(v) => {
-                  setCurrency(v === "all" ? "" : (v as "USD" | "ETB"));
-                  setPagination((prev) => ({ ...prev, pageIndex: 0 }));
-                }}
-                data={[
-                  { label: "All", value: "all" },
-                  { label: "ETB", value: "ETB" },
-                  { label: "USD", value: "USD" },
-                ]}
-              />
               <SegmentedControl
                 size="sm"
                 radius="md"
@@ -427,9 +415,11 @@ export default function UsdPaymentsPanel() {
                 status={isLoading ? "loading" : isError ? "error" : "success"}
                 onRowClick={(row) => navigate(`/dashboard/invoices/${row.id}`)}
                 emptyMessage={
-                  debouncedQuery
-                    ? "No invoices match your search."
-                    : "No invoices awaiting manual payment confirmation."
+                  !currencyEnabled
+                    ? `Manual payment is switched off for ${currency} invoices. Enable it in Configuration → Manual payments.`
+                    : debouncedQuery
+                      ? "No invoices match your search."
+                      : `No ${currency} invoices awaiting manual payment confirmation.`
                 }
                 error={
                   isError
diff --git a/apps/edr-freight-web/backoffice/src/pages/settings/ManualPaymentSettingsCard.tsx b/apps/edr-freight-web/backoffice/src/pages/settings/ManualPaymentSettingsCard.tsx
new file mode 100644
index 000000000..3fe5c1e1e
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/settings/ManualPaymentSettingsCard.tsx
@@ -0,0 +1,132 @@
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/shared/common/ui/card";
+import { Badge } from "@/shared/common/ui/badge";
+import { Switch } from "@/shared/common/ui/switch";
+import { Skeleton } from "@/shared/common/ui/skeleton";
+import { AlertTriangle, Banknote, Landmark } from "lucide-react";
+
+import { useAuth } from "@/auth/useAuth";
+import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
+import {
+  useManualPaymentSettingsQuery,
+  useUpdateManualPaymentSettings,
+} from "@/hooks/useManualPaymentSettings";
+
+type Currency = "ETB" | "USD";
+
+const CURRENCIES: {
+  code: Currency;
+  field: "etbEnabled" | "usdEnabled";
+  icon: typeof Banknote;
+  title: string;
+  description: string;
+}[] = [
+  {
+    code: "ETB",
+    field: "etbEnabled",
+    icon: Banknote,
+    title: "Birr (ETB) invoices",
+    description:
+      "ETB invoices are normally paid online by the customer. Switch this on when Finance also needs to settle them by hand — a bank transfer or a payment at the counter.",
+  },
+  {
+    code: "USD",
+    field: "usdEnabled",
+    icon: Landmark,
+    title: "Dollar (USD) invoices",
+    description:
+      "USD invoices are paid by bank transfer and have no online channel. Switching this off leaves USD customers with no way to be marked as paid.",
+  },
+];
+
+/**
+ * Switches the manual (offline) payment channel on or off per currency.
+ *
+ * Off means gone, not greyed out: the Manual Payments worklist lists only
+ * enabled currencies, and the API refuses a confirmation in a disabled one —
+ * so a stale tab or a direct call cannot slip a payment through.
+ */
+export default function ManualPaymentSettingsCard() {
+  const { user } = useAuth();
+  const canManage =
+    hasPermission(user, FREIGHT_PERMS.settings.manualPayment.manage) ||
+    hasPermission(user, FREIGHT_PERMS.admin);
+
+  const { data, isLoading } = useManualPaymentSettingsQuery();
+  const update = useUpdateManualPaymentSettings();
+
+  const noneEnabled = Boolean(data && !data.etbEnabled && !data.usdEnabled);
+
+  return (
+    <Card className="shadow-lg border-gray-200 dark:border-gray-700">
+      <CardHeader>
+        <CardTitle>Manual payments</CardTitle>
+        <CardDescription>
+          Whether Finance staff may mark invoices as paid by hand, from
+          Invoices → Manual Payments. Each currency is switched separately.
+          Confirming still requires the payment slip and the booking&apos;s pay
+          window to be open.
+        </CardDescription>
+      </CardHeader>
+
+      <CardContent className="space-y-4">
+        {noneEnabled && (
+          <div className="flex items-start gap-2 rounded-md border border-amber-200 bg-amber-50 p-3 text-sm text-amber-900 dark:border-amber-900 dark:bg-amber-950 dark:text-amber-100">
+            <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
+            <p>
+              Both currencies are off — the Manual Payments list is empty and
+              Finance cannot settle any invoice by hand.
+            </p>
+          </div>
+        )}
+
+        {isLoading || !data
+          ? CURRENCIES.map((c) => (
+              <Skeleton key={c.code} className="h-[86px] w-full rounded-md" />
+            ))
+          : CURRENCIES.map(({ code, field, icon: Icon, title, description }) => {
+              const enabled = data[field];
+              return (
+                <div
+                  key={code}
+                  className="flex items-start justify-between gap-4 rounded-md border p-4 dark:border-gray-700"
+                >
+                  <div className="space-y-1">
+                    <div className="flex items-center gap-2">
+                      <Icon className="h-4 w-4 text-muted-foreground" />
+                      <p className="font-medium">{title}</p>
+                      <Badge variant={enabled ? "default" : "secondary"}>
+                        {enabled ? "Enabled" : "Disabled"}
+                      </Badge>
+                    </div>
+                    <p className="text-sm text-muted-foreground">
+                      {description}
+                    </p>
+                  </div>
+                  <Switch
+                    checked={enabled}
+                    disabled={!canManage || update.isPending}
+                    aria-label={`Allow manual payment for ${code} invoices`}
+                    onCheckedChange={(checked) =>
+                      update.mutate({ [field]: checked })
+                    }
+                  />
+                </div>
+              );
+            })}
+
+        {!canManage && (
+          <p className="text-sm text-muted-foreground">
+            You can see these settings but not change them — that needs the
+            manual-payment settings permission.
+          </p>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
index b740a6688..af648d509 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
@@ -278,6 +278,29 @@ export default function TrainBuilderDetailPage() {
         ]}
       />
 
+      {composition.wagonYards.length > 1 ? (
+        <Alert color="blue" icon={<MapPin size={16} />}>
+          <Stack gap={4}>
+            <Text size="sm" fw={600}>
+              This train's wagons stand in {composition.wagonYards.length} yards
+            </Text>
+            <Group gap="xs">
+              {composition.wagonYards.map((group) => (
+                <Badge key={group.yardId ?? "none"} variant="light" color="blue">
+                  {group.label ?? group.code ?? "No yard"} · {group.wagonCount} wagon
+                  {group.wagonCount === 1 ? "" : "s"}
+                </Badge>
+              ))}
+            </Group>
+            <Text size="xs" c="dimmed">
+              The train collects each group when it reaches that yard, so the schedule's route
+              must pass through every one of them before its destination. Customers boarding at
+              a yard can only book the wagons standing there.
+            </Text>
+          </Stack>
+        </Alert>
+      ) : null}
+
       {!composition.editable ? (
         <Alert color="yellow" icon={<AlertTriangle size={16} />}>
           This train is out on a dispatched run — its composition is frozen until arrival.
@@ -379,13 +402,13 @@ export default function TrainBuilderDetailPage() {
           <Grid.Col span={{ base: 12, md: 5 }}>
             <Card h="100%">
               <Stack gap="sm">
-                <Text fw={600}>Available wagons — {yard?.label ?? "yard"}</Text>
+                <Text fw={600}>Available wagons — all yards</Text>
                 <Text size="xs" c="dimmed">
-                  Only AVAILABLE wagons standing in the train's own yard can be coupled.
+                  AVAILABLE, unassigned wagons from every yard can be coupled. The schedule's
+                  route must pass through each wagon's yard before its destination.
                 </Text>
                 <AvailableWagonsPanel
-                  yardId={yard?.id ?? ""}
-                  yardLabel={yard?.label}
+                  homeYardId={yard?.id ?? null}
                   exportTrainNumber={composition.exportTrainNumber}
                   importTrainNumber={composition.importTrainNumber}
                   assigning={assignWagons.isPending}
diff --git a/apps/edr-freight-web/backoffice/src/services/manualPaymentSettings.service.ts b/apps/edr-freight-web/backoffice/src/services/manualPaymentSettings.service.ts
new file mode 100644
index 000000000..6710730cb
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/services/manualPaymentSettings.service.ts
@@ -0,0 +1,36 @@
+import { api as client } from "../auth/http";
+import { unwrap } from "@/utils/endpoint";
+import { URL_CONSTANTS } from "@/constants/URLS";
+import type { ApiResponse } from "@/types/apiResponse";
+
+const BASE = URL_CONSTANTS.MANUAL_PAYMENT_SETTINGS.BASE;
+
+/**
+ * Whether Finance may settle invoices by hand (bank transfer / counter) rather
+ * than the customer paying online — switched per currency, because the two
+ * channels are operationally different.
+ */
+export interface ManualPaymentSettings {
+  etbEnabled: boolean;
+  usdEnabled: boolean;
+  updatedById: string | null;
+  updatedAt?: string;
+}
+
+export const manualPaymentSettingsService = {
+  get: async (): Promise<ManualPaymentSettings> => {
+    const response = await client.get<ApiResponse<ManualPaymentSettings>>(BASE);
+    return unwrap(response.data);
+  },
+
+  /** Partial: an omitted currency keeps its current setting. */
+  update: async (
+    patch: Partial<Pick<ManualPaymentSettings, "etbEnabled" | "usdEnabled">>,
+  ): Promise<ManualPaymentSettings> => {
+    const response = await client.patch<ApiResponse<ManualPaymentSettings>>(
+      BASE,
+      patch,
+    );
+    return unwrap(response.data);
+  },
+};
diff --git a/apps/edr-freight-web/backoffice/src/services/trainBuilder.service.ts b/apps/edr-freight-web/backoffice/src/services/trainBuilder.service.ts
index 2892cb0ec..5b245305e 100644
--- a/apps/edr-freight-web/backoffice/src/services/trainBuilder.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/trainBuilder.service.ts
@@ -67,6 +67,8 @@ export interface TrainCompositionWagon {
   wagonNumber: string;
   sequenceNumber: number | null;
   status: string;
+  currentYardId: string | null;
+  currentYard: YardRefLite | null;
   wagonType: {
     id: string;
     code: string;
@@ -77,6 +79,14 @@ export interface TrainCompositionWagon {
   } | null;
 }
 
+/** Where a built train's wagons physically stand, largest group first. */
+export interface TrainWagonYardGroup {
+  yardId: string | null;
+  code: string | null;
+  label: string | null;
+  wagonCount: number;
+}
+
 export interface TrainCompositionTotals {
   wagonCount: number;
   totalTareTons: number;
@@ -104,6 +114,7 @@ export interface TrainComposition {
   currentYard: YardRefLite | null;
   locomotives: TrainCompositionLocomotive[];
   wagons: TrainCompositionWagon[];
+  wagonYards: TrainWagonYardGroup[];
   totals: TrainCompositionTotals;
   activeSchedules: ActiveScheduleRef[];
   editable: boolean;
diff --git a/apps/edr-freight-web/portal/src/hooks/useAuth.ts b/apps/edr-freight-web/portal/src/hooks/useAuth.ts
index a6e647918..d2fbb1026 100644
--- a/apps/edr-freight-web/portal/src/hooks/useAuth.ts
+++ b/apps/edr-freight-web/portal/src/hooks/useAuth.ts
@@ -46,10 +46,19 @@ const useAuth = () => {
     }),
   );
 
+  // `/companies/getInfo` is customer-only (PortalCustomerGuard). A staff
+  // account signed into the portal 403s on every call, and because a failed
+  // fetch leaves `company` null the onboarding gate redirects, which remounts
+  // the route tree, which refires the query — a request storm. Never ask.
+  const isCustomerAccount =
+    authQuery.data?.userType === "individual" ||
+    authQuery.data?.userType === "external_organization";
+
   const companyQuery = useQuery(
     api.companies.getInfo.queryOptions({
-      enabled: !!authQuery.data?.id,
+      enabled: !!authQuery.data?.id && isCustomerAccount,
       retry: false,
+      refetchOnMount: false,
 
       staleTime(query) {
         // Fast-poll while anything is awaiting a backoffice decision: an
@@ -61,7 +70,7 @@ const useAuth = () => {
             (p) => p.status !== "active",
           )
         )
-          return 60;
+          return 60_000;
 
         return 10 * 60 * 1000;
       },
@@ -308,7 +317,11 @@ const useAuth = () => {
     logout,
     authQuery,
     companyQuery,
-    customerQuery: companyQuery,
+    // A disabled query reports `isPending` forever; the route gates read this
+    // to decide "still loading", so a staff account would sit on a spinner.
+    customerQuery: isCustomerAccount
+      ? companyQuery
+      : { ...companyQuery, isPending: false },
   };
 };
 
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx b/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
index 312ecb62b..e812c12b6 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
@@ -6,15 +6,20 @@ import {
   Box,
   Button,
   Checkbox,
+  CloseButton,
+  Drawer,
+  Flex,
   Group,
   Image,
   Loader,
   Modal,
   Paper,
   PinInput,
+  ScrollArea,
   Stack,
   Text,
   TextInput,
+  ThemeIcon,
 } from "@mantine/core";
 import {
   ArrowLeft,
@@ -24,6 +29,7 @@ import {
   RotateCw,
   ShieldCheck,
 } from "lucide-react";
+import { useMediaQuery } from "@mantine/hooks";
 import toast from "react-hot-toast";
 
 import { ContractSignSuccessModal } from "@/components/contracts/ContractSignSuccessModal";
@@ -44,6 +50,9 @@ export default function ContractViewPage() {
   const navigate = useNavigate();
   const qc = useQueryClient();
   const iframeRef = useRef<HTMLIFrameElement>(null);
+  // Below Mantine's `sm`: the signing surfaces go full-bleed and the consent
+  // bar stacks, so the checkbox and its button stop crowding each other.
+  const isMobile = useMediaQuery("(max-width: 48em)");
 
   const [signOpen, setSignOpen] = useState(false);
   const [otpOpen, setOtpOpen] = useState(false);
@@ -315,7 +324,7 @@ export default function ContractViewPage() {
         </Paper>
       </Box>
 
-      {data.canSignCustomer && hasScrolledToBottom && (
+      {data.canSignCustomer && hasScrolledToBottom && !signOpen && !otpOpen && !successOpen && (
         <Paper
           withBorder
           radius="lg"
@@ -325,87 +334,169 @@ export default function ContractViewPage() {
           maw={920}
           mx="auto"
           style={{
-            // Above SupportWidget's Affix (zIndex 300) — the fixed chat FAB
-            // shares this bottom-right corner and would otherwise render on
-            // top of the required agree-and-sign bar.
-            position: "relative",
-            zIndex: 301,
+            // No z-index escalation here: raising this bar above the chat FAB
+            // is what made it fight every overlay on the page. It keeps clear
+            // of the fixed FAB by leaving room for it instead (paddingRight on
+            // wide screens, where the FAB sits beside the bar's right edge).
             background: "var(--mantine-color-body)",
           }}
+          pr={{ base: "md", sm: 88 }}
         >
-          <Box maw={920} mx="auto">
-            <Group justify="flex-start" align="flex-start" wrap="wrap" gap="sm">
-              <Checkbox
-                checked={agreedToTerms}
-                onChange={(e) => setAgreedToTerms(e.currentTarget.checked)}
-                disabled={!hasScrolledToBottom}
-                label={CONSENT_TEXT}
-                description={
-                  hasScrolledToBottom
-                    ? "You may now sign the contract."
-                    : "Read the full contract above before you can agree and sign."
-                }
-              />
-              <Button
-                color="edr-green"
-                leftSection={<FileSignature size={16} />}
-                disabled={!canProceedToSign}
-                onClick={openSign}
-              >
-                {usingSaved ? "Approve & sign" : "Sign contract"}
-              </Button>
-            </Group>
-          </Box>
+          <Flex
+            direction={{ base: "column", sm: "row" }}
+            align={{ base: "stretch", sm: "center" }}
+            justify="space-between"
+            gap="sm"
+          >
+            <Checkbox
+              checked={agreedToTerms}
+              onChange={(e) => setAgreedToTerms(e.currentTarget.checked)}
+              disabled={!hasScrolledToBottom}
+              label={CONSENT_TEXT}
+              description={
+                hasScrolledToBottom
+                  ? "You may now sign the contract."
+                  : "Read the full contract above before you can agree and sign."
+              }
+            />
+            <Button
+              color="edr-green"
+              leftSection={<FileSignature size={16} />}
+              disabled={!canProceedToSign}
+              onClick={openSign}
+              fullWidth={isMobile}
+              style={{ flexShrink: 0 }}
+            >
+              {usingSaved ? "Approve & sign" : "Sign contract"}
+            </Button>
+          </Flex>
         </Paper>
       )}
 
-      <Modal
+      {/* A right-hand drawer, not a centered dialog: the sign step shares the
+          bottom-right corner with the agree-and-sign bar and the support-chat
+          FAB, and a full-height side panel simply never contends with them. */}
+      <Drawer
         opened={signOpen}
         onClose={() => setSignOpen(false)}
-        title={usingSaved ? "Approve signature" : "Sign contract"}
-        centered
-        radius="lg"
+        position={isMobile ? "bottom" : "right"}
+        size={isMobile ? "100%" : "lg"}
+        padding={0}
+        withCloseButton={false}
+        // Clear of the sign bar (301) and the chat FAB's Affix (300).
+        zIndex={400}
+        overlayProps={{ backgroundOpacity: 0.55, blur: 3 }}
+        // Drawer.Body has no intrinsic height, so the inner flex column (pinned
+        // header / scrolling middle / pinned footer) would collapse without this.
+        styles={{
+          content: { display: "flex", flexDirection: "column" },
+          body: { flex: 1, minHeight: 0, display: "flex", flexDirection: "column" },
+        }}
       >
-        <Stack gap="md">
-          <Text size="sm" c="dimmed">
-            {data.reference} — your signature is stored securely on the
-            contract.
-          </Text>
+        <>
+          {/* Header — pinned, so the contract reference stays visible while the
+              signature and stamp sections scroll. */}
+          <Group
+            justify="space-between"
+            wrap="nowrap"
+            p="lg"
+            style={{
+              borderBottom: "1px solid var(--mantine-color-gray-2)",
+              flexShrink: 0,
+            }}
+          >
+            <Group gap="sm" wrap="nowrap">
+              <ThemeIcon size={38} radius="md" variant="light" color="edr-green">
+                <FileSignature size={19} />
+              </ThemeIcon>
+              <Box>
+                <Text fw={600}>
+                  {usingSaved ? "Approve signature" : "Sign contract"}
+                </Text>
+                <Text size="xs" c="dimmed">
+                  {data.reference}
+                </Text>
+              </Box>
+            </Group>
+            <CloseButton size="lg" onClick={() => setSignOpen(false)} />
+          </Group>
+
+          <ScrollArea style={{ flex: 1, minHeight: 0 }}>
+            <Stack gap="lg" p="lg">
           <TextInput
             label="Full name"
+            description="Printed under your signature on the contract."
+            placeholder="Name as it should appear on the contract"
+            withAsterisk
             value={signerName}
             onChange={(e) => setSignerName(e.currentTarget.value)}
           />
-          {usingSaved ? (
-            <Stack gap="xs">
+
+          <Box>
+            <Group justify="space-between" align="center" mb={6} wrap="nowrap">
+              <Text size="sm" fw={500}>
+                Signature{" "}
+                <Text span c="red">
+                  *
+                </Text>
+              </Text>
+              {usingSaved ? (
+                <Button
+                  variant="subtle"
+                  size="compact-xs"
+                  color="edr-green"
+                  leftSection={<RotateCw size={13} />}
+                  onClick={() => {
+                    setDrawNew(true);
+                    setSignatureData(null);
+                  }}
+                >
+                  Draw a new one
+                </Button>
+              ) : savedSignatureImage ? (
+                <Button
+                  variant="subtle"
+                  size="compact-xs"
+                  color="gray"
+                  onClick={() => {
+                    setDrawNew(false);
+                    setSignatureData(null);
+                  }}
+                >
+                  Use saved signature
+                </Button>
+              ) : null}
+            </Group>
+            {usingSaved ? (
               <Paper
                 withBorder
                 radius="md"
-                p="xs"
-                style={{ borderStyle: "dashed" }}
+                p="sm"
+                style={{
+                  borderStyle: "dashed",
+                  background: "var(--mantine-color-gray-0)",
+                }}
               >
                 <Image
                   src={savedSignatureImage ?? undefined}
                   alt="Saved signature"
                   fit="contain"
-                  h={140}
+                  h={120}
                 />
+                <Group gap={6} mt="xs" justify="center" wrap="nowrap">
+                  <ShieldCheck
+                    size={13}
+                    color="var(--mantine-color-edr-green-6)"
+                  />
+                  <Text size="xs" c="dimmed">
+                    Saved signature — stored securely on your profile
+                  </Text>
+                </Group>
               </Paper>
-              <Button
-                variant="subtle"
-                size="compact-xs"
-                color="edr-green"
-                onClick={() => {
-                  setDrawNew(true);
-                  setSignatureData(null);
-                }}
-              >
-                Draw a new signature instead
-              </Button>
-            </Stack>
-          ) : (
-            <ContractSignaturePad onChange={setSignatureData} />
-          )}
+            ) : (
+              <ContractSignaturePad onChange={setSignatureData} />
+            )}
+          </Box>
 
           <StampUpload
             value={stampData}
@@ -413,26 +504,47 @@ export default function ContractViewPage() {
             description="Attach your official company stamp or seal — it is applied to the contract next to your signature."
           />
 
-          <Group justify="flex-end" gap="sm">
-            <Button variant="default" onClick={() => setSignOpen(false)}>
-              Cancel
-            </Button>
-            <Button
-              color="edr-green"
-              loading={sendOtpMutation.isPending}
-              disabled={
-                sendOtpMutation.isPending ||
-                !signerName.trim() ||
-                (!usingSaved && !signatureData) ||
-                !stampData
-              }
-              onClick={confirmSign}
-            >
-              Continue to verification
-            </Button>
-          </Group>
-        </Stack>
-      </Modal>
+            </Stack>
+          </ScrollArea>
+
+          {/* Footer — pinned, so the primary action never scrolls out of reach. */}
+          <Stack
+            gap="sm"
+            p="lg"
+            style={{
+              borderTop: "1px solid var(--mantine-color-gray-2)",
+              background: "var(--mantine-color-body)",
+              flexShrink: 0,
+            }}
+          >
+            <Group gap={6} wrap="nowrap">
+              <ShieldCheck size={14} color="var(--mantine-color-dimmed)" />
+              <Text size="xs" c="dimmed">
+                We send a 6-digit code to your registered contacts next.
+              </Text>
+            </Group>
+            <Group gap="sm" grow>
+              <Button variant="default" onClick={() => setSignOpen(false)}>
+                Cancel
+              </Button>
+              <Button
+                color="edr-green"
+                leftSection={<ShieldCheck size={16} />}
+                loading={sendOtpMutation.isPending}
+                disabled={
+                  sendOtpMutation.isPending ||
+                  !signerName.trim() ||
+                  (!usingSaved && !signatureData) ||
+                  !stampData
+                }
+                onClick={confirmSign}
+              >
+                Continue to verification
+              </Button>
+            </Group>
+          </Stack>
+        </>
+      </Drawer>
 
       <Modal
         opened={otpOpen}
@@ -440,6 +552,10 @@ export default function ContractViewPage() {
         title="Verify it's you"
         centered
         radius="lg"
+        zIndex={400}
+        // Full-bleed on phones — a centered dialog plus the fixed chat FAB left
+        // the code entry and its buttons fighting for the same few pixels.
+        fullScreen={isMobile}
       >
         <Stack gap="md">
           <Group gap="sm" wrap="nowrap">

From a9763a541a4d9c8fe3594e35c1cbcc1ee1950996 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 08:45:15 +0000
Subject: [PATCH 142/174] feat(companies): support foreign investors onboarding
 on an investment licence
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A foreign company licensed by the Ethiopian Investment Commission is not on
the trade registry, so eTrade holds no record for its TIN and the lookup the
company step is built around returns nothing. Those customers could not get
past onboarding at all.

They now take the same route a co-operative does: an `investorLicence` flag in
`attributes`, and `applyEtradeSourcedFields` skips the eTrade re-check for any
company `usesManualRegistration` covers, so the registration they type is
persisted as sent instead of 400'ing "no registration found for this TIN".
Unlike a co-operative they still hold a business licence per operational role,
so that requirement is untouched, and the foreign document set already asks for
the investment licence itself — no new set.

Only a foreign company may carry the flag, and never alongside the
co-operative one: the two resolve to different document sets.

`POST /companies/onboarding/revert-to-etrade` gives it back. It clears the
typed registration rather than keeping it — the wizard treats a populated
registration block as a passed lookup, so leaving it would walk the customer
straight past the eTrade step the switch exists to reach — and returns the
company to pending, since an approval granted against typed data must not
carry over to a record that now claims to be eTrade's.
---
 .../modules/companies/companies.controller.ts |  15 ++
 .../companies.investor-licence.spec.ts        | 147 ++++++++++++++++++
 .../modules/companies/companies.service.ts    | 126 ++++++++++++++-
 .../onboarding-requirements-response.dto.ts   |   9 ++
 .../companies/dto/profile-response.dto.ts     |  13 +-
 .../companies/dto/response-company.dto.ts     |   9 ++
 .../companies/dto/start-onboarding.dto.ts     |  11 ++
 .../companies/entities/company.entity.ts      |  31 ++++
 8 files changed, 356 insertions(+), 5 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/companies/companies.investor-licence.spec.ts

diff --git a/apps/edr-freight-api/src/modules/companies/companies.controller.ts b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
index 175533c6d..4139424c1 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.controller.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
@@ -288,10 +288,25 @@ export class CompaniesController {
       dto.roles,
       dto.nationality,
       dto.cooperative,
+      dto.investorLicence,
     );
     return new CompanyInfoResponseDto(profile, company);
   }
 
+  @Post("onboarding/revert-to-etrade")
+  @PortalCustomer()
+  @ApiOperation({
+    summary:
+      "Drop the foreign investment-licence route: clear the typed registration and reopen onboarding so the TIN is verified against eTrade",
+  })
+  async revertToRegularCompany(
+    @CurrentUser() user: CurrentIamUser,
+  ): Promise<CompanyInfoResponseDto> {
+    const { profile, company } =
+      await this.companiesService.revertToRegularCompany(user.id);
+    return new CompanyInfoResponseDto(profile, company);
+  }
+
   @Post("company-profile")
   @PortalCustomer()
   @ApiOperation({
diff --git a/apps/edr-freight-api/src/modules/companies/companies.investor-licence.spec.ts b/apps/edr-freight-api/src/modules/companies/companies.investor-licence.spec.ts
new file mode 100644
index 000000000..4a17d9594
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/companies/companies.investor-licence.spec.ts
@@ -0,0 +1,147 @@
+import { BadRequestException } from "@nestjs/common";
+
+import { CompaniesService } from "./companies.service";
+import {
+  CompanyNationality,
+  CompanyStatus,
+  CompanyType,
+} from "./entities/company.entity";
+import { ProfileType } from "./entities/company-profile.entity";
+
+/**
+ * A foreign company on an Investment Commission licence has no eTrade record,
+ * so it types its registration — and the flag saying so is what makes the
+ * backoffice treat those fields as unverified. Two things must hold: only a
+ * foreign company can carry it, and dropping it must not leave the typed
+ * registration behind looking like eTrade's.
+ */
+function makeService(company: Record<string, unknown> | null) {
+  const companiesRepo = {
+    findById: jest.fn(async () => company),
+    update: jest.fn(async () => null),
+    create: jest.fn(async (row: Record<string, unknown>) => ({
+      id: "company-1",
+      ...row,
+    })),
+    existsByTin: jest.fn(async () => false),
+  };
+  const companyProfilesRepo = {
+    findByCompanyId: jest.fn(async () => []),
+    create: jest.fn(async (row: Record<string, unknown>) => ({
+      id: "cp-1",
+      ...row,
+    })),
+    softDelete: jest.fn(async () => undefined),
+  };
+  const profilesRepo = {
+    findByUserId: jest.fn(async () =>
+      company
+        ? { id: "external-1", companyId: "company-1", company: { id: "company-1" } }
+        : null,
+    ),
+    create: jest.fn(async (row: Record<string, unknown>) => ({
+      id: "external-1",
+      ...row,
+    })),
+    update: jest.fn(async () => null),
+  };
+
+  const service = new CompaniesService(
+    companiesRepo as never,
+    companyProfilesRepo as never,
+    {} as never,
+    {} as never,
+    profilesRepo as never,
+    {} as never,
+    {} as never,
+    {} as never,
+    {} as never,
+    {} as never,
+    {} as never,
+    {} as never,
+  );
+
+  jest
+    .spyOn(service, "getCompanyInfoByUserId")
+    .mockImplementation(
+      async () =>
+        ({ profile: { id: "external-1" }, company: { id: "company-1" } }) as never,
+    );
+
+  return { service, companiesRepo, profilesRepo };
+}
+
+const identity = { userId: "user-1", firstName: "Abebe", lastName: "K" };
+
+const start = (
+  service: CompaniesService,
+  nationality: CompanyNationality | undefined,
+  cooperative: boolean,
+  investorLicence: boolean,
+) =>
+  service.startOnboarding(
+    identity as never,
+    CompanyType.Customer,
+    [ProfileType.importer],
+    nationality,
+    cooperative,
+    investorLicence,
+  );
+
+describe("the foreign investment-licence route", () => {
+  it("refuses the flag for an Ethiopian company", async () => {
+    const { service } = makeService(null);
+    await expect(
+      start(service, CompanyNationality.Ethiopian, false, true),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it("refuses the flag alongside the co-operative one", async () => {
+    const { service } = makeService(null);
+    await expect(
+      start(service, CompanyNationality.Foreign, true, true),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it("stores the flag on a new foreign draft", async () => {
+    const { service, companiesRepo } = makeService(null);
+    await start(service, CompanyNationality.Foreign, false, true);
+    expect(companiesRepo.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        nationality: CompanyNationality.Foreign,
+        attributes: { investorLicence: true },
+      }),
+    );
+  });
+
+  it("clears the typed registration and reopens onboarding when switching back to eTrade", async () => {
+    const { service, companiesRepo, profilesRepo } = makeService({
+      id: "company-1",
+      attributes: { investorLicence: true, etradeManagerName: "Typed Name" },
+    });
+
+    await service.revertToRegularCompany("user-1");
+
+    const [, updates] = companiesRepo.update.mock.calls[0] as unknown as [
+      string,
+      Record<string, unknown>,
+    ];
+    expect(updates.attributes).toEqual({});
+    expect(updates.status).toBe(CompanyStatus.Pending);
+    // The wizard treats a populated registration as a passed lookup, so leaving
+    // any of it behind would walk the customer straight past the eTrade step.
+    expect(updates.licenceNumber).toBeNull();
+    expect(updates.region).toBeNull();
+    expect(profilesRepo.update).toHaveBeenCalledWith("external-1", {
+      onboardingCompleted: false,
+      onboardingStep: "company",
+    });
+  });
+
+  it("refuses to switch a company that never took the investment-licence route", async () => {
+    const { service } = makeService({ id: "company-1", attributes: {} });
+    await expect(service.revertToRegularCompany("user-1")).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/companies/companies.service.ts b/apps/edr-freight-api/src/modules/companies/companies.service.ts
index bf8184833..f9090f288 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.service.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.service.ts
@@ -63,7 +63,10 @@ import {
   CompanyStatus,
   CompanyType,
   COOPERATIVE_KEY,
+  INVESTOR_LICENCE_KEY,
+  hasInvestorLicence,
   isCooperative,
+  usesManualRegistration,
 } from "./entities/company.entity";
 import { ExternalProfile } from "./entities/external-profile.entity";
 import {
@@ -378,6 +381,7 @@ export class CompaniesService {
     roles: ProfileType[],
     nationality?: CompanyNationality,
     cooperative?: boolean,
+    investorLicence?: boolean,
   ): Promise<{ profile: ExternalProfile; company: Company }> {
     // Already started — reuse the existing draft, just ensure roles exist and
     // keep the nationality up to date if it was (re)selected.
@@ -388,13 +392,20 @@ export class CompaniesService {
       // flag into `attributes`, or to read a stored one the caller didn't send.
       const needsCompany =
         cooperative !== undefined ||
+        investorLicence !== undefined ||
         roles.includes(ProfileType.freightForwarder);
       const current = needsCompany
         ? await this.companiesRepo.findById(companyId)
         : null;
       const isCoop = cooperative ?? isCooperative(current);
+      const isInvestor = investorLicence ?? hasInvestorLicence(current);
       this.assertRolesAllowedForCooperative(isCoop, roles);
       this.assertNationalityAllowedForCooperative(isCoop, nationality);
+      this.assertInvestorLicenceAllowed(
+        isInvestor,
+        isCoop,
+        nationality ?? current?.nationality ?? undefined,
+      );
       await this.syncCompanyProfiles(companyId, companyType, roles);
       const updates: Partial<Company> = {};
       if (nationality) updates.nationality = nationality;
@@ -402,10 +413,15 @@ export class CompaniesService {
       // stored nationality too, or the company keeps resolving to the foreign
       // document set.
       if (isCoop) updates.nationality = CompanyNationality.Ethiopian;
-      if (cooperative !== undefined) {
+      if (cooperative !== undefined || investorLicence !== undefined) {
         updates.attributes = {
           ...(current?.attributes ?? {}),
-          [COOPERATIVE_KEY]: cooperative,
+          ...(cooperative !== undefined
+            ? { [COOPERATIVE_KEY]: cooperative }
+            : {}),
+          ...(investorLicence !== undefined
+            ? { [INVESTOR_LICENCE_KEY]: investorLicence }
+            : {}),
         };
       }
       if (Object.keys(updates).length > 0) {
@@ -416,6 +432,11 @@ export class CompaniesService {
 
     this.assertRolesAllowedForCooperative(cooperative === true, roles);
     this.assertNationalityAllowedForCooperative(cooperative === true, nationality);
+    this.assertInvestorLicenceAllowed(
+      investorLicence === true,
+      cooperative === true,
+      nationality,
+    );
     const allowedTypes = this.getProfileTypeForCompanyType(companyType);
     const chosenTypes = roles.filter((t) => allowedTypes.includes(t));
 
@@ -428,7 +449,14 @@ export class CompaniesService {
       country: "Ethiopia",
       nationality: nationality ?? CompanyNationality.Ethiopian,
       status: CompanyStatus.Pending,
-      ...(cooperative ? { attributes: { [COOPERATIVE_KEY]: true } } : {}),
+      ...(cooperative || investorLicence
+        ? {
+            attributes: {
+              ...(cooperative ? { [COOPERATIVE_KEY]: true } : {}),
+              ...(investorLicence ? { [INVESTOR_LICENCE_KEY]: true } : {}),
+            },
+          }
+        : {}),
     });
 
     await this.profilesRepo.create({
@@ -485,6 +513,34 @@ export class CompaniesService {
     }
   }
 
+  /**
+   * An investment licence belongs to a foreign company and to nothing else.
+   *
+   * It is the Ethiopian Investment Commission's licence, issued to a foreign
+   * investor — an Ethiopian company registers with the trade registry, which is
+   * exactly the eTrade record this flag says does not exist. A co-operative
+   * cannot hold one either: it is Ethiopian by construction, and the two flags
+   * resolve to different document sets, so a company carrying both would owe an
+   * incoherent list of papers.
+   */
+  private assertInvestorLicenceAllowed(
+    investorLicence: boolean,
+    cooperative: boolean,
+    nationality: CompanyNationality | undefined,
+  ): void {
+    if (!investorLicence) return;
+    if (cooperative) {
+      throw new BadRequestException(
+        "A co-operative union or farm is registered in Ethiopia — it cannot also onboard on a foreign investment licence.",
+      );
+    }
+    if (nationality !== CompanyNationality.Foreign) {
+      throw new BadRequestException(
+        "Only a foreign company can onboard on an investment licence.",
+      );
+    }
+  }
+
   /**
    * Reconcile the company's operational profiles with the roles the user has
    * selected: create the missing ones, drop the ones they deselected.
@@ -2143,6 +2199,7 @@ export class CompaniesService {
     // or farm holds no business licence, so it owes its own list rather than the
     // nationality list plus extras.
     const cooperative = isCooperative(company);
+    const investorLicence = hasInvestorLicence(company);
     const documentSettingCode = this.documentSettingCodeFor(company);
     const [setting, uploadedFiles] = await Promise.all([
       this.fileUploadSettingsService
@@ -2292,6 +2349,7 @@ export class CompaniesService {
       documentSettingCode,
       nationality: company.nationality ?? CompanyNationality.Ethiopian,
       cooperative,
+      investorLicence,
       companyInfo: {
         complete: missingInfo.length === 0,
         missingFields: missingInfo,
@@ -2369,6 +2427,66 @@ export class CompaniesService {
     return this.getCompanyInfoByUserId(userId);
   }
 
+  /**
+   * Drop the investment-licence route and send the company back through the
+   * normal eTrade one.
+   *
+   * Everything the flag let the customer type is cleared, not kept: the
+   * registration block on file was their own statement, and leaving it there
+   * would let the wizard treat the company as already looked-up
+   * (`hasRegistrationDetails` is what stands in for a verified TIN on a
+   * resume) and walk straight past the eTrade step this switch exists to
+   * reach. Onboarding reopens at the company step and the company goes back to
+   * pending — an approval granted against typed data cannot silently carry over
+   * to a record that now claims to be eTrade's.
+   */
+  async revertToRegularCompany(
+    userId: string,
+  ): Promise<{ profile: ExternalProfile; company: Company }> {
+    const profile = await this.profilesRepo.findByUserId(userId);
+    if (!profile)
+      throw new NotFoundException(`Profile for user ${userId} not found`);
+
+    const companyId = profile.company?.id ?? profile.companyId;
+    const company = await this.companiesRepo.findById(companyId);
+    if (!company)
+      throw new NotFoundException(`Company ${companyId} not found`);
+    if (!hasInvestorLicence(company)) {
+      throw new BadRequestException(
+        "This company is already registered through eTrade — there is nothing to switch.",
+      );
+    }
+
+    const attributes = { ...(company.attributes ?? {}) };
+    delete attributes[INVESTOR_LICENCE_KEY];
+    // The manager captured alongside the (typed) registration goes with it —
+    // it never came from a licence, so it must not survive as one.
+    delete attributes.etradeManagerName;
+    delete attributes.etradeManagerPhone;
+
+    await this.companiesRepo.update(companyId, {
+      attributes,
+      status: CompanyStatus.Pending,
+      licenceNumber: null,
+      statusDescription: null,
+      dateRegistered: null,
+      renewedFrom: null,
+      renewalDate: null,
+      renewedTo: null,
+      region: null,
+      zone: null,
+      woreda: null,
+      kebele: null,
+      houseNo: null,
+      etradePhone: null,
+    });
+    await this.profilesRepo.update(profile.id, {
+      onboardingCompleted: false,
+      onboardingStep: "company",
+    });
+    return this.getCompanyInfoByUserId(userId);
+  }
+
   /**
    * Block a self-service action when the company account isn't active, naming
    * the actual status — a suspended customer told "awaiting approval" has no
@@ -3535,7 +3653,7 @@ export class CompaniesService {
     // the registered address themselves, and what they send IS the data. The
     // check is skipped rather than failed: running the lookup would 400 every
     // save with "no registration found for this TIN".
-    if (isCooperative(company)) return;
+    if (usesManualRegistration(company)) return;
 
     const touched = ETRADE_SOURCED_FIELDS.some(
       (key) => key !== "tin" && dto[key] !== undefined,
diff --git a/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts
index 20bd0ab06..49dad4b8d 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/onboarding-requirements-response.dto.ts
@@ -78,6 +78,14 @@ export class OnboardingRequirementsResponseDto {
    */
   cooperative: boolean;
 
+  /**
+   * The company is a foreign investor on an investment licence: no eTrade
+   * record, so the registration was typed. The nationality document set still
+   * applies (it already asks for the investment licence itself), and so does
+   * the per-role business licence.
+   */
+  investorLicence: boolean;
+
   /** Required company-information fields and whether each is filled. */
   companyInfo: {
     complete: boolean;
@@ -116,6 +124,7 @@ export class OnboardingRequirementsResponseDto {
     this.documentSettingCode = init.documentSettingCode;
     this.nationality = init.nationality;
     this.cooperative = init.cooperative;
+    this.investorLicence = init.investorLicence;
     this.companyInfo = init.companyInfo;
     this.documents = init.documents;
     this.licenseProfiles = init.licenseProfiles;
diff --git a/apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts
index 0d7293ab0..14753f8ef 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/profile-response.dto.ts
@@ -2,7 +2,11 @@ import {
   buildCompanyIdentityState,
   CompanyIdentityStateDto,
 } from "./complete-identity-verification.dto";
-import { Company, isCooperative } from "../entities/company.entity";
+import {
+  Company,
+  hasInvestorLicence,
+  isCooperative,
+} from "../entities/company.entity";
 import { ExternalProfile } from "../entities/external-profile.entity";
 import {
   ChangeRequestStatus,
@@ -21,6 +25,12 @@ export class ProfileResponseDto {
    * it from eTrade.
    */
   cooperative: boolean;
+  /**
+   * The company is a foreign investor on an investment licence: eTrade holds
+   * no record, so the company step collects the registration by hand. Drives
+   * the settings card that switches back to the eTrade route.
+   */
+  investorLicence: boolean;
   companyLocation: string;
   companyAddress: string | null;
   tinNumber: string;
@@ -93,6 +103,7 @@ export class ProfileResponseDto {
     this.companyType = company.type;
     this.nationality = company.nationality ?? null;
     this.cooperative = isCooperative(company);
+    this.investorLicence = hasInvestorLicence(company);
     this.companyProfiles =
       company.companyProfiles?.map((p) => new ResponseCompanyProfileDto(p)) ??
       [];
diff --git a/apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts
index e75182889..7c4348e4f 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts
@@ -3,6 +3,7 @@ import {
   CompanyType,
   CompanyStatus,
   CompanyNationality,
+  hasInvestorLicence,
   isCooperative,
 } from '../entities/company.entity';
 import {
@@ -62,6 +63,13 @@ export class ResponseCompanyDto {
    * eTrade manager to check the owner against.
    */
   cooperative: boolean;
+  /**
+   * The company onboarded as a foreign investor on an investment licence:
+   * eTrade holds no record for its TIN, so its registration below was typed by
+   * the customer rather than fetched — nothing here has been checked against a
+   * licence, and the reviewer is the check.
+   */
+  investorLicence: boolean;
   tin: string;
   vatNumber?: string | null;
   fanNumber?: string | null;
@@ -118,6 +126,7 @@ export class ResponseCompanyDto {
     this.status = company.status;
     this.nationality = company.nationality ?? null;
     this.cooperative = isCooperative(company);
+    this.investorLicence = hasInvestorLicence(company);
     this.tin = company.tin;
     this.vatNumber = company.vatNumber;
     this.fanNumber = company.fanNumber;
diff --git a/apps/edr-freight-api/src/modules/companies/dto/start-onboarding.dto.ts b/apps/edr-freight-api/src/modules/companies/dto/start-onboarding.dto.ts
index 91fcb44a1..0eac35a5f 100644
--- a/apps/edr-freight-api/src/modules/companies/dto/start-onboarding.dto.ts
+++ b/apps/edr-freight-api/src/modules/companies/dto/start-onboarding.dto.ts
@@ -31,4 +31,15 @@ export class StartOnboardingDto {
   @IsOptional()
   @IsBoolean()
   cooperative?: boolean;
+
+  /**
+   * The company is a foreign investor: it operates on an investment licence
+   * issued by the Ethiopian Investment Commission, so eTrade holds no record
+   * for its TIN and the registration is typed here instead. Chosen on the same
+   * step for the same reason as the co-operative flag — it decides what the
+   * company step asks for. Only a foreign company can hold one.
+   */
+  @IsOptional()
+  @IsBoolean()
+  investorLicence?: boolean;
 }
diff --git a/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts b/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts
index 54c36bf41..68bf73cdf 100644
--- a/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts
+++ b/apps/edr-freight-api/src/modules/companies/entities/company.entity.ts
@@ -51,6 +51,37 @@ export function isCooperative(
   return company?.attributes?.[COOPERATIVE_KEY] === true;
 }
 
+/**
+ * `attributes` key marking a foreign company onboarding on an investment
+ * licence.
+ *
+ * The Ethiopian Investment Commission registers it, not the trade registry, so
+ * eTrade holds no record for its TIN: the registration is typed and the eTrade
+ * authenticity check is skipped rather than failed — exactly as for a
+ * co-operative. What does NOT change is the licence: the company still holds
+ * one per operational role, so that requirement stands.
+ */
+export const INVESTOR_LICENCE_KEY = "investorLicence";
+
+/** Is this a foreign company registered on an investment licence? */
+export function hasInvestorLicence(
+  company: Pick<Company, "attributes"> | null | undefined,
+): boolean {
+  return company?.attributes?.[INVESTOR_LICENCE_KEY] === true;
+}
+
+/**
+ * eTrade holds nothing for this company, so its registration was typed by hand
+ * rather than fetched — and the backoffice is told so. Two different companies
+ * reach it (a co-operative has no licence at all; a foreign investor's is not
+ * the trade registry's), and every consequence they share hangs off this.
+ */
+export function usesManualRegistration(
+  company: Pick<Company, "attributes"> | null | undefined,
+): boolean {
+  return isCooperative(company) || hasInvestorLicence(company);
+}
+
 @Entity({ schema: "freight", name: "companies" })
 @Index(["tin"])
 @Index(["type"])

From d1584ee708faa32e2fb1b13b5ef9421ca8f44d95 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 08:45:29 +0000
Subject: [PATCH 143/174] feat(portal): offer the investment-licence path in
 the onboarding wizard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A foreign company can now say it operates on an investment licence, on the
same step as its nationality and roles. The box only appears for a foreign
company, and moving the nationality answer back to Ethiopian drops it — the
API refuses both pairings.

The company step's eTrade gate now reads `manualRegistration`
(co-operative OR investment licence): the TIN lookup still runs, but finding
nothing is an expected outcome rather than a blocker, and the registration
section is typed instead. What stays keyed to `cooperative` alone is the
per-role business licence — an investor holds one, a co-operative does not —
so the licence cards and their validation are unchanged for investors.

Also carries the client plumbing for the revert endpoint the settings card
uses next.
---
 .../onboarding/OnboardingWizardDialog.tsx     | 46 ++++++++++++++++++-
 .../portal/src/constants/URLS.ts              |  1 +
 .../src/pages/accounts/CompanyProfileForm.tsx | 29 +++++++++---
 .../steps/CompanyInfoStep.tsx                 | 46 +++++++++++--------
 .../companyProfileForm/steps/OwnerStep.tsx    | 17 ++++---
 .../portal/src/services/api.ts                |  8 ++++
 .../portal/src/services/companies.service.ts  | 15 ++++++
 .../portal/src/types/profile.ts               |  2 +
 8 files changed, 132 insertions(+), 32 deletions(-)

diff --git a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
index d5a87a4ee..0dd3e4462 100644
--- a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
+++ b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
@@ -162,6 +162,13 @@ export default function OnboardingWizardDialog({
   const [cooperative, setCooperative] = useState<boolean>(
     company?.company?.attributes?.cooperative === true,
   );
+  // A foreign company operating on an Ethiopian Investment Commission licence.
+  // eTrade holds nothing for its TIN, so it types the registration exactly as a
+  // co-operative does — but it still holds a licence per role, so nothing about
+  // the licence step changes.
+  const [investorLicence, setInvestorLicence] = useState<boolean>(
+    company?.company?.attributes?.investorLicence === true,
+  );
   // Ticking the box drops the selections the company can no longer hold, rather
   // than letting Continue fail on ones the API refuses: a co-op cannot forward
   // freight, and is registered in Ethiopia so it is never foreign.
@@ -171,8 +178,20 @@ export default function OnboardingWizardDialog({
       setRoles((prev) => prev.filter((r) => r !== "freight_forwarder"));
       // Ethiopian is then the only answer left, so it is made rather than asked.
       setNationality("ethiopian");
+      // Which also rules out the investment licence — that is a foreign
+      // company's, and the API refuses the pair.
+      setInvestorLicence(false);
     }
   }, []);
+  // The investment licence is a foreign company's document. Moving the answer
+  // back to Ethiopian drops it rather than sending a pair the API refuses.
+  const handleNationalityChange = useCallback(
+    (value: CompanyNationality | null) => {
+      setNationality(value);
+      if (value !== "foreign") setInvestorLicence(false);
+    },
+    [],
+  );
   const [documentFiles, setDocumentFiles] = useState<
     Record<string, File | File[] | null>
   >({});
@@ -224,6 +243,7 @@ export default function OnboardingWizardDialog({
       roles: ProfileTypeValue[];
       nationality?: CompanyNationality;
       cooperative?: boolean;
+      investorLicence?: boolean;
     }) => api.companies.startOnboarding.call(vars),
     onSuccess: async () => {
       // Nationality drives the server-resolved identity requirements (Fayda vs
@@ -307,6 +327,7 @@ export default function OnboardingWizardDialog({
     setRoles(existingProfiles.map((p) => p.type));
     setNationality(savedNationality);
     setCooperative(company?.company?.attributes?.cooperative === true);
+    setInvestorLicence(company?.company?.attributes?.investorLicence === true);
     // Resume into the form only when profiles exist; otherwise send the user to
     // role selection so the missing operational profiles get created.
     setPhase(hasOperationalProfiles ? "form" : "nationality-role");
@@ -322,8 +343,9 @@ export default function OnboardingWizardDialog({
       roles: roles as ProfileTypeValue[],
       nationality: nationality ?? undefined,
       cooperative,
+      investorLicence,
     });
-  }, [roles, nationality, cooperative, startMutation]);
+  }, [roles, nationality, cooperative, investorLicence, startMutation]);
 
   // Back from the form's first step returns to nationality/role selection.
   // Safe to re-enter: startOnboarding is idempotent — it reuses the existing
@@ -479,6 +501,10 @@ export default function OnboardingWizardDialog({
     // startOnboarding has persisted it, and the form's whole company step
     // branches on it.
     cooperative: requirementsQuery.data?.cooperative ?? cooperative,
+    // Same rule, same reason: only a persisted flag changes what the company
+    // step asks for.
+    investorLicence:
+      requirementsQuery.data?.investorLicence ?? investorLicence,
     // A freight forwarder cannot answer the power-of-attorney question — the
     // API forces "yes" — so the step offers no way to change it.
     declarationLocked: requirementsQuery.data?.poa?.locked ?? false,
@@ -546,7 +572,7 @@ export default function OnboardingWizardDialog({
               </Text>
               <NationalitySelect
                 value={nationality}
-                onChange={setNationality}
+                onChange={handleNationalityChange}
                 embedded
                 // A co-op is registered in Ethiopia by the co-operative
                 // promotion agency — foreign is not on offer rather than
@@ -563,6 +589,22 @@ export default function OnboardingWizardDialog({
                 label="We're a co-operative union or farm"
                 description="For members with a TIN but no business licence. You'll type your registration details instead of us pulling them from eTrade, and upload your co-operative papers in place of a trade licence."
               />
+              {/* Only a foreign company is offered this: the licence is the
+                  Investment Commission's, and it is the reason eTrade has
+                  nothing to look up. Same consequence as the co-operative box —
+                  typed registration instead of a lookup — but the per-role
+                  business licence still applies, so the documents step is
+                  unchanged. */}
+              {nationality === "foreign" && !cooperative && (
+                <Checkbox
+                  checked={investorLicence}
+                  onChange={(e) =>
+                    setInvestorLicence(e.currentTarget.checked)
+                  }
+                  label="We operate on a foreign investment licence"
+                  description="For investors registered with the Ethiopian Investment Commission rather than the trade registry. eTrade holds no record of your TIN, so you'll type your registration details instead — and our team reviews them by hand."
+                />
+              )}
               <Text fw={600} size="lg" c="edr-text">
                 What does your company do?(multiple)
               </Text>
diff --git a/apps/edr-freight-web/portal/src/constants/URLS.ts b/apps/edr-freight-web/portal/src/constants/URLS.ts
index c9576d192..cefef5ddc 100644
--- a/apps/edr-freight-web/portal/src/constants/URLS.ts
+++ b/apps/edr-freight-web/portal/src/constants/URLS.ts
@@ -103,6 +103,7 @@ export const URL_CONSTANTS = {
     ONBOARDING_STEP: "/api/companies/onboarding-step",
     ONBOARDING_COMPLETE: "/api/companies/onboarding/complete",
     ONBOARDING_REQUIREMENTS: "/api/companies/onboarding/requirements",
+    ONBOARDING_REVERT_TO_ETRADE: "/api/companies/onboarding/revert-to-etrade",
     DASHBOARD: "/api/companies/dashboard",
     FETCH_ETRADE_INFO: "/api/companies/fetch-etrade-info",
     DOCUMENTS: (id: string) => `/api/companies/${id}/documents`,
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 aa445974f..542fd17b5 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
@@ -65,6 +65,7 @@ export default function CompanyProfileForm({
   identity: rawIdentity,
   onIdentityChange,
   cooperative = false,
+  investorLicence = false,
   declarationLocked = false,
 }: {
   documentSettingCode: string;
@@ -118,6 +119,13 @@ export default function CompanyProfileForm({
    * nationality one (resolved by the caller into `documentSettingCode`).
    */
   cooperative?: boolean;
+  /**
+   * The company is a foreign investor on an Investment Commission licence. Like
+   * a co-operative, eTrade holds no record of it, so the registration is typed
+   * and the lookup gate does not apply — but it does hold a business licence
+   * per role, so the licence step is untouched.
+   */
+  investorLicence?: boolean;
   /**
    * The company operates as a freight forwarder, so the power-of-attorney
    * answer is forced to "yes" and cannot be changed here.
@@ -133,6 +141,12 @@ export default function CompanyProfileForm({
     [rawIdentity],
   );
 
+  // eTrade has nothing to say about this company, whichever of the two reasons
+  // applies — so the registration is typed here and the lookup cannot gate the
+  // step. Everything the two cases do NOT share (the per-role business licence)
+  // keeps reading `cooperative` on its own.
+  const manualRegistration = cooperative || investorLicence;
+
   const [step, setStep] = useState<CompanyStep>(initialStep ?? "company");
   const [saving, setSaving] = useState(false);
   /**
@@ -434,7 +448,7 @@ export default function CompanyProfileForm({
     // holds nothing — and wiping them because the customer went back to fix a
     // digit of their TIN would throw away an address they had just typed by
     // hand, over a lookup that never filled anything in the first place.
-    if (cooperative && !etradeFilledRef.current) {
+    if (manualRegistration && !etradeFilledRef.current) {
       setLiveEtradeOwner(null);
       setEtradeCleared(true);
       return;
@@ -730,7 +744,7 @@ export default function CompanyProfileForm({
   // A co-operative never runs the lookup, so there is nothing to be verified
   // against; its TIN is validated by the schema like any other typed field.
   const tinVerified =
-    cooperative || tinStatus === "verified" || hasRegistrationDetails;
+    manualRegistration || tinStatus === "verified" || hasRegistrationDetails;
 
   // Single source of truth for step sequence — navigation, labels and the
   // progress bar all derive from this so adding/removing a step is one edit.
@@ -770,8 +784,8 @@ export default function CompanyProfileForm({
       Boolean(watch(passportField)?.trim()));
 
   const requiredKeys: (keyof FormData)[] = [];
-  if (step === "company" && cooperative) {
-    // A co-operative has no eTrade record, so the fields every other company
+  if (step === "company" && manualRegistration) {
+    // These companies have no eTrade record, so the fields every other company
     // gets read-only from the licence are typed here — and are therefore
     // required here. House number stays optional: plenty of addresses have none.
     requiredKeys.push("companyName", "region", "zone", "woreda", "kebele");
@@ -887,8 +901,9 @@ export default function CompanyProfileForm({
     }
     // The TIN must resolve to a real eTrade record before anything else on
     // this step is even worth validating — gates here rather than through zod.
-    // A co-operative is exempt: it has no licence for eTrade to hold, so
-    // `tinVerified` is true for it and only the duplicate-TIN check applies.
+    // A co-operative and a foreign investor are exempt: eTrade holds no record
+    // for either, so `tinVerified` is true and only the duplicate-TIN check
+    // applies.
     if (step === "company" && tinStatus === "taken") {
       failCheck(
         "This TIN is already registered to another company account.",
@@ -987,6 +1002,7 @@ export default function CompanyProfileForm({
               tinStatus={tinStatus}
               tinVerified={tinVerified}
               hasRegistrationDetails={hasRegistrationDetails}
+              manualRegistration={manualRegistration}
               cooperative={cooperative}
               onETradeDataLoaded={handleETradeDataLoaded}
               onETradeStatusChange={setTinStatus}
@@ -1002,6 +1018,7 @@ export default function CompanyProfileForm({
               source={ownerSource}
               sourced={ownerSourced}
               cooperative={cooperative}
+              manualRegistration={manualRegistration}
             />
           )}
 
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
index b89e0e920..04a91bf07 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
@@ -17,10 +17,13 @@ export interface CompanyInfoStepProps {
   /** Registration fields are already populated (a lookup passed, now or earlier). */
   hasRegistrationDetails: boolean;
   /**
-   * The company is a co-operative union or farm: it has a TIN but no business
-   * licence, so eTrade holds no record to look up and the registration is typed
-   * here instead.
+   * eTrade holds no record for this company's TIN, so the registration is typed
+   * here rather than fetched. True for a co-operative union or farm (no
+   * business licence) and for a foreign investor (licensed by the Investment
+   * Commission, not the trade registry).
    */
+  manualRegistration?: boolean;
+  /** Which of the two it is — wording only; the behaviour is the same. */
   cooperative?: boolean;
   onETradeDataLoaded: (data: CompanyRegistrationData) => void;
   onETradeStatusChange: (status: ETradeStatus) => void;
@@ -32,6 +35,7 @@ export default function CompanyInfoStep({
   tinStatus,
   tinVerified,
   hasRegistrationDetails,
+  manualRegistration = false,
   cooperative = false,
   onETradeDataLoaded,
   onETradeStatusChange,
@@ -71,14 +75,16 @@ export default function CompanyInfoStep({
         index={2}
         title="Company TIN"
         subtitle={
-          cooperative
-            ? "We'll check eTrade for your TIN. Co-operatives often aren't listed — if yours isn't, you'll fill the details in below."
-            : "We'll pull your registration straight from eTrade — nothing to type by hand once it's found."
+          !manualRegistration
+            ? "We'll pull your registration straight from eTrade — nothing to type by hand once it's found."
+            : cooperative
+              ? "We'll check eTrade for your TIN. Co-operatives often aren't listed — if yours isn't, you'll fill the details in below."
+              : "We'll check eTrade for your TIN. An investment licence usually isn't on it — if yours isn't, you'll fill the details in below."
         }
         status={
           tinStatus === "taken"
             ? "blocked"
-            : cooperative
+            : manualRegistration
               ? watch("tinNumber")?.trim() && !errors.tinNumber
                 ? "done"
                 : "todo"
@@ -96,26 +102,26 @@ export default function CompanyInfoStep({
           onReset={onETradeReset}
           alreadyVerified={hasRegistrationDetails}
           selectedLicenceNumber={watch("licenceNumber")}
-          registrationOptional={cooperative}
+          registrationOptional={manualRegistration}
         />
-        {!cooperative && tinVerified && (
+        {!manualRegistration && tinVerified && (
           <ETradeCompanyCard tin={watch("tinNumber")} watch={watch} />
         )}
       </StepSection>
 
-      {/* A co-operative keeps its typed registration section either way. When
-          the lookup found something these arrive prefilled — still editable,
-          because for a co-op they are the customer's own statement rather than
-          the licence's, and the API takes them as given (`applyEtradeSourcedFields`
-          skips co-operatives entirely). */}
-      {cooperative && (
+      {/* A company eTrade cannot answer for keeps its typed registration
+          section either way. When the lookup did find something these arrive
+          prefilled — still editable, because here they are the customer's own
+          statement rather than the licence's, and the API takes them as given
+          (`applyEtradeSourcedFields` skips both cases entirely). */}
+      {manualRegistration && (
         <StepSection
           index={3}
           title="Registration details"
           subtitle={
             hasRegistrationDetails
-              ? "From eTrade. Correct anything that doesn't look right — for a co-operative these are yours to state."
-              : "Everything we'd normally read off an eTrade licence. We need it from you instead."
+              ? "From eTrade. Correct anything that doesn't look right — these are yours to state."
+              : "Everything we'd normally read off an eTrade licence. We need it from you instead. Our team checks it against the papers you upload."
           }
           status={
             watch("companyName")?.trim() && watch("region")?.trim()
@@ -126,7 +132,11 @@ export default function CompanyInfoStep({
           <Stack gap="md">
             <TextInput
               label="Company Name"
-              placeholder="Registered name of the union or farm"
+              placeholder={
+                cooperative
+                  ? "Registered name of the union or farm"
+                  : "Name on your investment licence"
+              }
               error={errors.companyName?.message}
               {...register("companyName")}
             />
diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx
index 4035b8aaf..805ef8784 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/OwnerStep.tsx
@@ -32,6 +32,8 @@ export interface OwnerStepProps {
   sourced: Record<OwnerField, string>;
   /** A co-operative union or farm: no licence, so no eTrade record to match. */
   cooperative?: boolean;
+  /** No eTrade record at all (co-operative or foreign investment licence). */
+  manualRegistration?: boolean;
 }
 
 /**
@@ -56,6 +58,7 @@ export default function OwnerStep({
   source,
   sourced,
   cooperative = false,
+  manualRegistration = false,
 }: OwnerStepProps) {
   const {
     register,
@@ -74,15 +77,17 @@ export default function OwnerStep({
   return (
     <Stack gap="md">
       <Text size="sm" c="edr-muted">
-        {cooperative && !etradeOwner
-          ? "The person who runs the co-operative union or farm. eTrade held no record for your TIN, so we need all of these from you."
+        {manualRegistration && !etradeOwner
+          ? cooperative
+            ? "The person who runs the co-operative union or farm. eTrade held no record for your TIN, so we need all of these from you."
+            : "The person your investment licence names. eTrade held no record for your TIN, so we need all of these from you."
           : "These are the details of the person registered on your eTrade licence. What eTrade and Fayda gave us is shown as they gave it; anything they left blank we need from you."}
       </Text>
 
-      {/* A co-operative is not told its licence listed no manager — it has no
-          licence. Its own "nothing came back" case is covered by the line
-          above. */}
-      {!cooperative && !etradeOwner && !ownerVerified && (
+      {/* A company with no eTrade record is not told its licence listed no
+          manager — eTrade never held one. That "nothing came back" case is
+          covered by the line above. */}
+      {!manualRegistration && !etradeOwner && !ownerVerified && (
         <Alert color="blue" variant="light" icon={<Info size={18} />}>
           Your eTrade licence didn't list a manager, so there's nothing for us
           to prefill. Enter the details of the person registered on it.
diff --git a/apps/edr-freight-web/portal/src/services/api.ts b/apps/edr-freight-web/portal/src/services/api.ts
index 755361520..2f633a06b 100644
--- a/apps/edr-freight-web/portal/src/services/api.ts
+++ b/apps/edr-freight-web/portal/src/services/api.ts
@@ -241,10 +241,18 @@ export const api = {
         nationality?: CompanyNationality;
         /** No business licence: registration typed, no eTrade lookup, no forwarding. */
         cooperative?: boolean;
+        /** Foreign investment licence: registration typed, no eTrade lookup. */
+        investorLicence?: boolean;
       },
       CompanyInfoResponse
     >("companies", "startOnboarding", companiesService.startOnboarding),
 
+    revertToRegularCompany: endpoint<void, CompanyInfoResponse>(
+      "companies",
+      "revertToRegularCompany",
+      companiesService.revertToRegularCompany,
+    ),
+
     setOnboardingStep: endpoint<{ step: string }, void>(
       "companies",
       "setOnboardingStep",
diff --git a/apps/edr-freight-web/portal/src/services/companies.service.ts b/apps/edr-freight-web/portal/src/services/companies.service.ts
index eda9d7e3d..4a6c3139e 100644
--- a/apps/edr-freight-web/portal/src/services/companies.service.ts
+++ b/apps/edr-freight-web/portal/src/services/companies.service.ts
@@ -223,6 +223,8 @@ export interface OnboardingRequirements {
   nationality: string;
   /** No business licence: registration typed by hand, no eTrade lookup. */
   cooperative: boolean;
+  /** Foreign investment licence: registration typed by hand, no eTrade record. */
+  investorLicence: boolean;
   companyInfo: {
     complete: boolean;
     missingFields: { key: string; label: string }[];
@@ -363,6 +365,7 @@ export const companiesService = {
     roles: ProfileTypeValue[];
     nationality?: CompanyNationality;
     cooperative?: boolean;
+    investorLicence?: boolean;
   }): Promise<CompanyInfoResponse> => {
     const response = await client.post<ApiResponse<CompanyInfoResponse>>(
       URL_CONSTANTS.COMPANIES_API.ONBOARDING_START,
@@ -371,6 +374,18 @@ export const companiesService = {
     return unwrap(response.data);
   },
 
+  /**
+   * Give up the foreign investment-licence route and go back through eTrade.
+   * The API clears the typed registration and reopens onboarding at the company
+   * step, so the caller must refresh the company info afterwards.
+   */
+  revertToRegularCompany: async (): Promise<CompanyInfoResponse> => {
+    const response = await client.post<ApiResponse<CompanyInfoResponse>>(
+      URL_CONSTANTS.COMPANIES_API.ONBOARDING_REVERT_TO_ETRADE,
+    );
+    return unwrap(response.data);
+  },
+
   setOnboardingStep: async (payload: { step: string }): Promise<void> => {
     await client.patch(URL_CONSTANTS.COMPANIES_API.ONBOARDING_STEP, payload);
   },
diff --git a/apps/edr-freight-web/portal/src/types/profile.ts b/apps/edr-freight-web/portal/src/types/profile.ts
index 3839e3141..fc297110a 100644
--- a/apps/edr-freight-web/portal/src/types/profile.ts
+++ b/apps/edr-freight-web/portal/src/types/profile.ts
@@ -8,6 +8,8 @@ export interface ProfileResponse {
   nationality: string | null;
   /** No business licence: the registration is typed, not fetched from eTrade. */
   cooperative: boolean;
+  /** Foreign investor on an investment licence: same typed registration, no eTrade record. */
+  investorLicence: boolean;
   companyProfiles: CompanyProfileResponse[];
   companyLocation: string;
   companyAddress: string | null;

From 23d752d1ccb28bde25a6285cf58a2ba4a70f9a62 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 08:45:29 +0000
Subject: [PATCH 144/174] feat(portal): let an investor company switch back to
 eTrade registration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A company that ticked the investment-licence box by mistake, or that has since
been registered with the trade registry, had no way back — the flag is chosen
once, on a step onboarding never returns to.

The Company tab now carries a Registration source card for those companies.
It is a re-application rather than a settings edit, so the confirmation says
so outright: the typed registration is cleared, the company returns to pending
and the wizard reopens on the company step, while documents, owner and contact
details stay. Hidden for everyone else, and disabled while a profile change
request is under review — switching then would strand it.
---
 .../portal/src/pages/SettingsPage.tsx         |   2 +
 .../pages/settings/RegistrationSourceCard.tsx | 149 ++++++++++++++++++
 2 files changed, 151 insertions(+)
 create mode 100644 apps/edr-freight-web/portal/src/pages/settings/RegistrationSourceCard.tsx

diff --git a/apps/edr-freight-web/portal/src/pages/SettingsPage.tsx b/apps/edr-freight-web/portal/src/pages/SettingsPage.tsx
index 13b0d4025..53e0cf0a3 100644
--- a/apps/edr-freight-web/portal/src/pages/SettingsPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/SettingsPage.tsx
@@ -47,6 +47,7 @@ import useAuth from "@/hooks/useAuth";
 import { rolesForCompanyType } from "./settings/companyRoles";
 import TabAccount from "./settings/TabAccount";
 import TabCompanyProfile from "./settings/TabCompanyProfile";
+import RegistrationSourceCard from "./settings/RegistrationSourceCard";
 import TabContactPerson from "./settings/TabContactPerson";
 import TabDocuments from "./settings/TabDocuments";
 import TabOwner from "./settings/TabOwner";
@@ -398,6 +399,7 @@ export default function SettingsPage() {
               />
             </Fieldset>
             <OperationalServicesCard profile={profile} />
+            <RegistrationSourceCard profile={profile} disabled={locked} />
           </Tabs.Panel>
           <Tabs.Panel value="contact">
             <TabContactPerson profile={profile} mode="edit" />
diff --git a/apps/edr-freight-web/portal/src/pages/settings/RegistrationSourceCard.tsx b/apps/edr-freight-web/portal/src/pages/settings/RegistrationSourceCard.tsx
new file mode 100644
index 000000000..09f4e7195
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/settings/RegistrationSourceCard.tsx
@@ -0,0 +1,149 @@
+import { useState } from "react";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import {
+  Alert,
+  Button,
+  Card,
+  Group,
+  List,
+  Modal,
+  Stack,
+  Text,
+  Title,
+} from "@mantine/core";
+import { AlertCircle, FileSearch } from "lucide-react";
+
+import { api } from "@/services/api";
+import type { ProfileResponse } from "@/types/profile";
+import { extractApiError } from "@/utils/result";
+
+/**
+ * Leave the foreign investment-licence route and go back to the ordinary eTrade
+ * one — for a company that has since been registered with the trade registry,
+ * or that ticked the box by mistake.
+ *
+ * It is a re-application, not a settings edit: the API clears the registration
+ * the customer typed (nothing on file was ever checked against a licence) and
+ * puts the company back to pending, so the wizard reopens on the company step
+ * and the TIN goes through eTrade this time. Said plainly here rather than
+ * discovered afterwards.
+ */
+export default function RegistrationSourceCard({
+  profile,
+  disabled = false,
+}: {
+  profile: ProfileResponse;
+  /** A change request is under review — switching now would strand it. */
+  disabled?: boolean;
+}) {
+  const queryClient = useQueryClient();
+  const [confirming, setConfirming] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const revert = useMutation({
+    mutationFn: () => api.companies.revertToRegularCompany.call(),
+    onSuccess: async () => {
+      setConfirming(false);
+      // getInfo is what the onboarding gate reads, so refreshing it is what
+      // reopens the wizard.
+      await Promise.all([
+        queryClient.invalidateQueries({
+          queryKey: api.companies.getInfo.queryKey(),
+        }),
+        queryClient.invalidateQueries({
+          queryKey: api.companies.getProfile.queryKey(),
+        }),
+        queryClient.invalidateQueries({
+          queryKey: api.companies.onboardingRequirements.queryKey(),
+        }),
+      ]);
+    },
+    onError: (err) => setError(extractApiError(err).message),
+  });
+
+  if (!profile.investorLicence) return null;
+
+  return (
+    <>
+      <Card padding="lg" radius="lg" mt="lg">
+        <Group gap="sm" mb="md">
+          <FileSearch size={20} />
+          <Title order={3}>Registration source</Title>
+        </Group>
+        <Stack gap="md">
+          <Text size="sm" c="edr-muted">
+            Your company is registered on a foreign investment licence, so your
+            registration details were entered by hand instead of being read from
+            eTrade. Our team reviews them against the documents you uploaded.
+          </Text>
+          <Text size="sm" c="edr-muted">
+            If your company now holds an eTrade trade licence, you can switch
+            over and have your registration verified automatically.
+          </Text>
+          <Group justify="flex-end">
+            <Button
+              variant="default"
+              disabled={disabled}
+              onClick={() => {
+                setError(null);
+                setConfirming(true);
+              }}
+            >
+              Switch to eTrade registration
+            </Button>
+          </Group>
+          {disabled && (
+            <Text size="xs" c="edr-muted" ta="right">
+              Not available while your profile changes are under review.
+            </Text>
+          )}
+        </Stack>
+      </Card>
+
+      <Modal
+        opened={confirming}
+        onClose={() => setConfirming(false)}
+        title="Switch to eTrade registration?"
+        centered
+        radius="lg"
+      >
+        <Stack gap="md">
+          <Text size="sm">This re-opens your application:</Text>
+          <List size="sm" spacing="xs">
+            <List.Item>
+              The registration details you typed are cleared — eTrade supplies
+              them once your TIN is found.
+            </List.Item>
+            <List.Item>
+              Your company goes back to pending and is reviewed again.
+            </List.Item>
+            <List.Item>
+              Your documents, owner and contact details stay as they are.
+            </List.Item>
+          </List>
+          <Alert color="amber" variant="light" icon={<AlertCircle size={18} />}>
+            If eTrade holds no record for your TIN you won't be able to finish —
+            come back here and re-select the investment licence in the wizard.
+          </Alert>
+          {error && (
+            <Text size="sm" c="red">
+              {error}
+            </Text>
+          )}
+          <Group justify="flex-end">
+            <Button variant="default" onClick={() => setConfirming(false)}>
+              Cancel
+            </Button>
+            <Button
+              color="edr-green"
+              loading={revert.isPending}
+              onClick={() => revert.mutate()}
+            >
+              Switch and re-apply
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
+    </>
+  );
+}

From 0f11d9518f9c299a2e1f1ca82be2910c1c2a34b2 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 08:45:38 +0000
Subject: [PATCH 145/174] feat(backoffice): flag customers whose registration
 was typed, not fetched
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two kinds of customer reach approval with a registration nobody checked: a
co-operative union or farm, which holds no trade licence, and a foreign
investor, whose licence comes from the Investment Commission rather than the
trade registry. Both were reviewed on screens that read exactly like an
eTrade-verified company's, with only a small Registration field naming the
difference.

They now carry an orange "Manual entry" badge in the customers list and beside
the company name, and their overview opens with an alert saying the name,
registration and address below are the customer's own statement — pointing the
reviewer at the paper that stands in for the licence (the co-operative
certificate, or the investment licence) before approving. Approval itself is
not blocked.
---
 .../src/components/customers/badges.tsx       | 30 +++++++++++++++++++
 .../src/components/customers/index.ts         |  1 +
 .../pages/customers/CustomerDetailPage.tsx    | 28 ++++++++++++++++-
 .../src/pages/customers/CustomersPage.tsx     |  5 ++++
 .../backoffice/src/types/customer.ts          |  7 +++++
 5 files changed, 70 insertions(+), 1 deletion(-)

diff --git a/apps/edr-freight-web/backoffice/src/components/customers/badges.tsx b/apps/edr-freight-web/backoffice/src/components/customers/badges.tsx
index 90dea5adb..22d3e66cf 100644
--- a/apps/edr-freight-web/backoffice/src/components/customers/badges.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/customers/badges.tsx
@@ -114,6 +114,36 @@ export function CompanyNationalityBadge({
   );
 }
 
+/**
+ * The company's registration was typed, not fetched from eTrade — nothing in it
+ * has been checked against a licence. Loud on purpose: it is the one thing a
+ * reviewer must not miss about this customer. Two kinds of company land here
+ * for different reasons, and the badge names which.
+ */
+export function ManualRegistrationBadge({
+  cooperative,
+  investorLicence,
+}: {
+  cooperative?: boolean | null;
+  investorLicence?: boolean | null;
+}) {
+  if (!cooperative && !investorLicence) return null;
+  return (
+    <Badge
+      color="orange"
+      variant="light"
+      size="sm"
+      radius="md"
+      fw={600}
+      style={badgeStyle}
+    >
+      {cooperative
+        ? "Manual entry · co-operative"
+        : "Manual entry · investment licence"}
+    </Badge>
+  );
+}
+
 /**
  * Profile chips for a company row: one chip per role (Importer / Exporter / …)
  * carrying its reference code, colored by the profile's status (green active,
diff --git a/apps/edr-freight-web/backoffice/src/components/customers/index.ts b/apps/edr-freight-web/backoffice/src/components/customers/index.ts
index 6f869173c..864a89ae6 100644
--- a/apps/edr-freight-web/backoffice/src/components/customers/index.ts
+++ b/apps/edr-freight-web/backoffice/src/components/customers/index.ts
@@ -4,6 +4,7 @@ export {
   CompanyStatusBadge,
   CompanyTypeBadge,
   InvoiceStatusBadge,
+  ManualRegistrationBadge,
   PaymentStatusBadge,
   ProfileApprovalActions,
   ProfileChips,
diff --git a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
index 40185f990..a81f07c8b 100644
--- a/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/customers/CustomerDetailPage.tsx
@@ -50,6 +50,7 @@ import {
   CompanyTimeline,
   CompanyTypeBadge,
   InvoiceStatusBadge,
+  ManualRegistrationBadge,
   PaymentStatusBadge,
   PersonCard,
   ProfileApprovalActions,
@@ -744,6 +745,10 @@ export default function CustomerDetailPage() {
             ) : (
               <CompanyStatusBadge status={company.status} />
             )}
+            <ManualRegistrationBadge
+              cooperative={company.cooperative}
+              investorLicence={company.investorLicence}
+            />
             <ChangeRequestPendingBadge companyId={company.id} />
           </Group>
         }
@@ -792,6 +797,25 @@ export default function CustomerDetailPage() {
               </Alert>
             )}
 
+            {/* Nothing below came from eTrade for these customers. A
+                co-operative holds no trade licence at all; a foreign investor's
+                comes from the Investment Commission, not the trade registry.
+                Either way every registration field was typed, and the reviewer
+                is the only check there is. */}
+            {(company.cooperative || company.investorLicence) && (
+              <Alert
+                color="orange"
+                variant="light"
+                radius="md"
+                icon={<AlertTriangle size={18} />}
+                title="Registration entered by hand — not verified against eTrade"
+              >
+                {company.cooperative
+                  ? "This company onboarded as a co-operative union or farm, which holds no trade licence, so eTrade had no record to look its TIN up in. The company name, registration and address below are the customer's own statement. Check them against the Co-operative Registration Certificate on the Documents tab before approving."
+                  : "This company onboarded on a foreign investment licence, so we could not look its TIN up on eTrade. The company name, registration and address below are the customer's own statement. Check them against the Investment Licence on the Documents tab before approving."}
+              </Alert>
+            )}
+
             <ChangeRequestReview company={company} />
 
             <KpiStrip
@@ -861,7 +885,9 @@ export default function CustomerDetailPage() {
                           value={
                             company.cooperative
                               ? "Co-operative union / farm (no trade licence)"
-                              : "eTrade trade licence"
+                              : company.investorLicence
+                                ? "Foreign investment licence — typed by the customer, not from eTrade"
+                                : "eTrade trade licence"
                           }
                         />
                         <InfoField label="Address" value={company.address} />
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 91bb72fdc..3825f0165 100644
--- a/apps/edr-freight-web/backoffice/src/pages/customers/CustomersPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/customers/CustomersPage.tsx
@@ -28,6 +28,7 @@ import { useNavigate } from "react-router-dom";
 import {
   CompanyNationalityBadge,
   CompanyStatusBadge,
+  ManualRegistrationBadge,
   ProfileChips,
   formatDate,
 } from "@/components/customers";
@@ -142,6 +143,10 @@ export default function CustomersPage() {
                     {c.name}
                   </Text>
                   <CompanyNationalityBadge nationality={c.nationality} />
+                  <ManualRegistrationBadge
+                    cooperative={c.cooperative}
+                    investorLicence={c.investorLicence}
+                  />
                 </Group>
                 <Text size="xs" c="dimmed">
                   TIN {c.tin}
diff --git a/apps/edr-freight-web/backoffice/src/types/customer.ts b/apps/edr-freight-web/backoffice/src/types/customer.ts
index 7fa7d792a..8c95e7342 100644
--- a/apps/edr-freight-web/backoffice/src/types/customer.ts
+++ b/apps/edr-freight-web/backoffice/src/types/customer.ts
@@ -234,6 +234,13 @@ export interface Company {
    * manager to check the owner against, and it holds no freight-forwarder role.
    */
   cooperative?: boolean;
+  /**
+   * A foreign investor on an Ethiopian Investment Commission licence: eTrade
+   * holds no record for its TIN, so every registration field below was typed by
+   * the customer and verified by nobody. The reviewer is the check — compare
+   * them against the investment licence on the Documents tab.
+   */
+  investorLicence?: boolean;
   address?: string | null;
   phone?: string | null;
   email?: string | null;

From 0b8b9c39ab8064f966b0a428efbcf80d5eb8546f Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 09:00:21 +0000
Subject: [PATCH 146/174] fix(companies): clear the typed registration when the
 manual-entry box is un-ticked

Going back in the wizard and un-ticking co-operative or investment licence used
to write the flag and nothing else. The registration the customer had typed
stayed on the company row, so `hasRegistrationDetails` still read as a passed
eTrade lookup, resume dropped them at their furthest step rather than the
company one, and the application could be finished on unverified data with no
flag left on it for the backoffice to show.

That transition now costs what the settings switch costs: the eTrade-sourced
columns and the manager captured beside them are cleared, and onboarding drops
back to the company step so the TIN actually goes through eTrade. Both the
reset payload and the attribute strip are now shared with
`revertToRegularCompany`, which did this correctly already.
---
 .../companies.investor-licence.spec.ts        | 64 +++++++++++++++
 .../modules/companies/companies.service.ts    | 77 +++++++++++++++----
 2 files changed, 124 insertions(+), 17 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/companies/companies.investor-licence.spec.ts b/apps/edr-freight-api/src/modules/companies/companies.investor-licence.spec.ts
index 4a17d9594..9623945d1 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.investor-licence.spec.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.investor-licence.spec.ts
@@ -138,6 +138,70 @@ describe("the foreign investment-licence route", () => {
     });
   });
 
+  it("clears the typed registration when the box is un-ticked on the way back", async () => {
+    const { service, companiesRepo, profilesRepo } = makeService({
+      id: "company-1",
+      nationality: CompanyNationality.Foreign,
+      attributes: { investorLicence: true, etradeManagerName: "Typed Name" },
+      region: "Addis Ababa",
+      licenceNumber: "TYPED-1",
+    });
+
+    await start(service, CompanyNationality.Foreign, false, false);
+
+    const [, updates] = companiesRepo.update.mock.calls[0] as unknown as [
+      string,
+      Record<string, unknown>,
+    ];
+    // The wizard sends both flags; the typed manager does not survive.
+    expect(updates.attributes).toEqual({
+      cooperative: false,
+      investorLicence: false,
+    });
+    expect(updates.licenceNumber).toBeNull();
+    expect(updates.region).toBeNull();
+    // Resume must land back on the company step, or the customer never reaches
+    // the eTrade lookup they just opted back into.
+    expect(profilesRepo.update).toHaveBeenCalledWith("external-1", {
+      onboardingStep: "company",
+    });
+  });
+
+  it("does the same for a co-operative that stops being one", async () => {
+    const { service, companiesRepo } = makeService({
+      id: "company-1",
+      nationality: CompanyNationality.Ethiopian,
+      attributes: { cooperative: true },
+      region: "Oromia",
+    });
+
+    await start(service, CompanyNationality.Ethiopian, false, false);
+
+    const [, updates] = companiesRepo.update.mock.calls[0] as unknown as [
+      string,
+      Record<string, unknown>,
+    ];
+    expect(updates.region).toBeNull();
+  });
+
+  it("leaves the registration alone while the flag stays on", async () => {
+    const { service, companiesRepo, profilesRepo } = makeService({
+      id: "company-1",
+      nationality: CompanyNationality.Foreign,
+      attributes: { investorLicence: true },
+      region: "Addis Ababa",
+    });
+
+    await start(service, CompanyNationality.Foreign, false, true);
+
+    const [, updates] = companiesRepo.update.mock.calls[0] as unknown as [
+      string,
+      Record<string, unknown>,
+    ];
+    expect(updates).not.toHaveProperty("region");
+    expect(profilesRepo.update).not.toHaveBeenCalled();
+  });
+
   it("refuses to switch a company that never took the investment-licence route", async () => {
     const { service } = makeService({ id: "company-1", attributes: {} });
     await expect(service.revertToRegularCompany("user-1")).rejects.toBeInstanceOf(
diff --git a/apps/edr-freight-api/src/modules/companies/companies.service.ts b/apps/edr-freight-api/src/modules/companies/companies.service.ts
index f9090f288..6dae48f24 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.service.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.service.ts
@@ -424,9 +424,28 @@ export class CompaniesService {
             : {}),
         };
       }
+      // Going back and un-ticking the box is the same act as the settings
+      // switch, so it has to cost the same: the registration the customer typed
+      // goes, and onboarding drops back to the company step. Without this the
+      // draft keeps the typed values, `hasRegistrationDetails` reads as a passed
+      // lookup, resume lands past the company step entirely — and the company
+      // finishes onboarding on unverified data with no flag left to say so.
+      const backToEtrade =
+        usesManualRegistration(current) && !isCoop && !isInvestor;
+      if (backToEtrade) {
+        Object.assign(updates, CompaniesService.CLEARED_REGISTRATION);
+        updates.attributes = this.withoutTypedEtradeManager(
+          updates.attributes ?? current?.attributes,
+        );
+      }
       if (Object.keys(updates).length > 0) {
         await this.companiesRepo.update(companyId, updates);
       }
+      if (backToEtrade) {
+        await this.profilesRepo.update(existing.id, {
+          onboardingStep: "company",
+        });
+      }
       return this.getCompanyInfoByUserId(identity.userId);
     }
 
@@ -513,6 +532,45 @@ export class CompaniesService {
     }
   }
 
+  /**
+   * The registration block as it must look when nobody has verified it.
+   *
+   * Used wherever a company stops being one eTrade cannot answer for: whatever
+   * sits in these columns was the customer's own statement, and the wizard
+   * treats a populated registration as a lookup that already passed
+   * (`hasRegistrationDetails`). Leaving it behind would hand the company an
+   * eTrade-verified record eTrade never supplied — and, once the flag is gone,
+   * a backoffice screen that says so.
+   */
+  private static readonly CLEARED_REGISTRATION: Partial<Company> = {
+    licenceNumber: null,
+    statusDescription: null,
+    dateRegistered: null,
+    renewedFrom: null,
+    renewalDate: null,
+    renewedTo: null,
+    region: null,
+    zone: null,
+    woreda: null,
+    kebele: null,
+    houseNo: null,
+    etradePhone: null,
+  };
+
+  /**
+   * The company's own `attributes`, minus the manager captured alongside a
+   * typed registration. It never came from a licence, so it must not outlive
+   * the registration it belonged to.
+   */
+  private withoutTypedEtradeManager(
+    attributes: Record<string, unknown> | null | undefined,
+  ): Record<string, unknown> {
+    const next = { ...(attributes ?? {}) };
+    delete next.etradeManagerName;
+    delete next.etradeManagerPhone;
+    return next;
+  }
+
   /**
    * An investment licence belongs to a foreign company and to nothing else.
    *
@@ -2457,28 +2515,13 @@ export class CompaniesService {
       );
     }
 
-    const attributes = { ...(company.attributes ?? {}) };
+    const attributes = this.withoutTypedEtradeManager(company.attributes);
     delete attributes[INVESTOR_LICENCE_KEY];
-    // The manager captured alongside the (typed) registration goes with it —
-    // it never came from a licence, so it must not survive as one.
-    delete attributes.etradeManagerName;
-    delete attributes.etradeManagerPhone;
 
     await this.companiesRepo.update(companyId, {
+      ...CompaniesService.CLEARED_REGISTRATION,
       attributes,
       status: CompanyStatus.Pending,
-      licenceNumber: null,
-      statusDescription: null,
-      dateRegistered: null,
-      renewedFrom: null,
-      renewalDate: null,
-      renewedTo: null,
-      region: null,
-      zone: null,
-      woreda: null,
-      kebele: null,
-      houseNo: null,
-      etradePhone: null,
     });
     await this.profilesRepo.update(profile.id, {
       onboardingCompleted: false,

From 333232c4d9da86c3555dfc077313236f5990c7a9 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 11:37:43 +0000
Subject: [PATCH 147/174] fix(portal): persist the region a manual-registration
 company picks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Region select called setValue without shouldDirty. `region` is an
eTrade-bundle key, and stepPayload sends those only when the customer changed
them this session — so for the two routes that type their address by hand (a
co-operative, a foreign investor) the region was dropped on every save while
zone, woreda and kebele went through, because those are registered inputs and
are dirty by construction.

Found by the new onboarding e2e suite: both manual-route companies finished
onboarding with zone/woreda/kebele on file and region empty.
---
 .../steps/CompanyInfoStep.tsx                 |  10 +-
 .../cypress/e2e/flows/onboarding.cy.ts        | 276 ------------------
 2 files changed, 9 insertions(+), 277 deletions(-)
 delete mode 100644 e2e/freight/cypress/e2e/flows/onboarding.cy.ts

diff --git a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
index 04a91bf07..52893ec59 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/steps/CompanyInfoStep.tsx
@@ -159,7 +159,15 @@ export default function CompanyInfoStep({
                 searchable
                 value={region || null}
                 onChange={(v) =>
-                  setValue("region", v ?? "", { shouldValidate: true })
+                  // shouldDirty, or the pick never reaches the API: `region` is
+                  // an eTrade-bundle key, and `stepPayload` sends those only
+                  // when the customer changed them this session. Without it a
+                  // co-operative or foreign investor typed its address and the
+                  // region alone silently vanished on save.
+                  setValue("region", v ?? "", {
+                    shouldValidate: true,
+                    shouldDirty: true,
+                  })
                 }
                 error={errors.region?.message}
               />
diff --git a/e2e/freight/cypress/e2e/flows/onboarding.cy.ts b/e2e/freight/cypress/e2e/flows/onboarding.cy.ts
deleted file mode 100644
index 437c0e92e..000000000
--- a/e2e/freight/cypress/e2e/flows/onboarding.cy.ts
+++ /dev/null
@@ -1,276 +0,0 @@
-/**
- * Full customer onboarding journey, both apps:
- *
- *   1. portal    — /signup form → OTP (read from DB, delivery is off in e2e)
- *                  → account created → onboarding wizard (nationality/role →
- *                  company → personnel → contact → PoA → documents incl. the
- *                  per-role business license) → "Submit for review"
- *   2. backoffice — staff (chief, holds edr_freight_app:admin) approves the
- *                  importer profile on /dashboard/customers/:id
- *   3. portal    — the new customer is active: contract wizard reachable
- *
- * Tests are sequential steps of ONE journey (fresh unique user per run), so
- * retries are disabled — a mid-journey retry would replay a non-idempotent
- * step against already-advanced state.
- *
- * NOTE: switching origin between tests (portal 5373 ↔ backoffice 5383)
- * reloads the spec bundle and resets module state — later tests resolve the
- * journey's user/company from the DB instead of module variables.
- */
-
-import { completeFaydaVerification } from "./import-utils";
-
-const stamp = Date.now();
-const email = `e2e.onboard.${stamp}@example.com`;
-// Ethiopian mobile: 9 + 8 digits, unique per run.
-const phoneNational = `9${String(stamp).slice(-8)}`;
-const signupPassword = "Password@e2e1";
-const tin = String(stamp).slice(-10).padStart(10, "1");
-const vat = String(stamp + 1).slice(-10).padStart(10, "2");
-
-const portal = () => Cypress.env("portalUrl") as string;
-
-/** The journey's company/user = the latest e2e.onboard.* signup in the DB. */
-function latestOnboardJourney() {
-  return cy.task<{ rows: Array<{ name: string; email: string }> }>("db:query", {
-    sql: `SELECT c.name, u.email
-          FROM freight.companies c
-          JOIN freight.external_profiles ep ON ep.company_id = c.id
-          JOIN iam.users u ON u.id = ep.user_id
-          WHERE u.email LIKE 'e2e.onboard.%'
-          ORDER BY c.created_at DESC LIMIT 1`,
-  });
-}
-
-/**
- * Fill a labelled Mantine input (label[for] → input id).
- *
- * The input is resolved fresh for every action rather than captured once.
- * Each wizard step persists and re-seeds asynchronously, and when a field
- * remounts Mantine mints a NEW generated id — so both a subject and an id
- * captured a command earlier can be stale by the time the next command runs.
- * Going label → for → element each time always addresses what's on the page
- * now.
- */
-function fill(label: string | RegExp, value: string) {
-  const input = () =>
-    cy
-      .contains("label", label)
-      .invoke("attr", "for")
-      .then((id) => cy.get(`[id="${id}"]`));
-
-  input().clear({ force: true });
-  input().type(value, { force: true });
-}
-
-/**
- * Fill an input that has no <label> — the wizard's company step renders its
- * fields inside StepSection cards (the heading is the card's title, not a
- * label), so they're reachable only by aria-label. Both TIN and VAT share the
- * "0012345678" placeholder, which is why this matches on aria-label instead.
- */
-function fillAria(ariaSelector: string, value: string) {
-  const selector = `.mantine-Modal-content ${ariaSelector}`;
-  cy.get(selector).clear({ force: true });
-  cy.get(selector).type(value, { force: true });
-}
-
-/** The wizard's phone inputs (react-phone-number-input, type=tel). */
-function fillPhone(index: number, national: string) {
-  const selector = '.mantine-Modal-content input[type="tel"]';
-  cy.get(selector).eq(index).clear({ force: true });
-  cy.get(selector).eq(index).type(national, { force: true });
-}
-
-describe("customer onboarding journey", { retries: 0 }, () => {
-  it("signs up with OTP and completes the onboarding wizard", () => {
-    cy.visit(`${portal()}/signup`);
-
-    fill(/^First name/, "Onboard");
-    fill(/^Last name/, "Tester");
-    fill(/^Email/, email);
-    cy.get('input[type="tel"]').first().type(phoneNational, { force: true });
-    fill(/^Password/, signupPassword);
-    fill(/^Confirm password/, signupPassword);
-    cy.contains("button", "Continue").click();
-
-    // OTP stage — the code is generated + stored even though delivery is off.
-    cy.contains("Verify", { timeout: 15000 }).should("be.visible");
-    cy.getOtp(email).then((otp) => cy.typeOtp(otp));
-    cy.contains("button", "Verify & create account").click();
-
-    // Signed in → /portal → wizard auto-opens on the nationality/role step.
-    cy.location("pathname", { timeout: 20000 }).should("eq", "/portal");
-    cy.contains("Where is your company registered?", { timeout: 15000 }).should(
-      "be.visible",
-    );
-    cy.contains("button", "Ethiopian Company").click();
-    cy.contains("button", "Importer").click();
-    cy.get(".mantine-Modal-content").contains("button", "Continue").click();
-
-    // Ethiopian companies gate the "Owner identity" step on Fayda
-    // verification — a real eSignet redirect + SMS OTP flow that can't run in
-    // e2e. Complete it via the API against fayda-mock-e2e (the profile this
-    // attaches to was just created by the nationality/role step above).
-    // The wizard already fetched `identity` once when this step mounted, and
-    // completing verification out-of-band skips the redirect that would
-    // normally remount everything — so reload to force a fresh fetch. Wizard
-    // progress resumes server-side, so this doesn't lose the nationality/role
-    // step just completed.
-    completeFaydaVerification("owner");
-    cy.reload();
-    cy.contains("Confirm your VAT number", { timeout: 20000 }).should(
-      "be.visible",
-    );
-
-    // The owner's identity is the verification's output, never typed: the
-    // panel must show it verified and render the name/phone/email that came
-    // back from fayda-mock-e2e. Asserting the mock's own values is the only
-    // way to prove the payload travelled Fayda → API → UI rather than the
-    // panel simply flipping a "verified" flag.
-    cy.get(".mantine-Modal-content").within(() => {
-      cy.contains("Fayda verified").should("be.visible");
-      cy.contains("Abebe Bekele").should("be.visible");
-      cy.contains("+251911223344").should("be.visible");
-      cy.contains("abebe.bekele@example.com").should("be.visible");
-    });
-
-    // The verified sub is what locks the owner's fields server-side, so check
-    // it actually landed on the company rather than trusting the panel alone.
-    cy.task<{ rows: Array<{ owner_fayda_sub: string | null }> }>("db:query", {
-      sql: `SELECT c.attributes->>'ownerFaydaSub' AS owner_fayda_sub
-            FROM freight.companies c
-            JOIN freight.external_profiles ep ON ep.company_id = c.id
-            JOIN iam.users u ON u.id = ep.user_id
-            WHERE u.email = $1`,
-      params: [email],
-    }).then(({ rows }) => {
-      expect(rows, "company row").to.have.length(1);
-      expect(rows[0].owner_fayda_sub, "owner Fayda sub").to.eq(
-        "e2e-fayda-sub-0001",
-      );
-    });
-
-    // Company step. TIN auto-triggers the eTrade lookup once it's a full 10
-    // digits (mocked in e2e — see docker-compose.e2e.yaml's etrade-mock-e2e).
-    // A successful lookup locks Company Name/Region/Zone/Woreda/Kebele/House
-    // No as read-only (ETradeCompanyCard) — nothing left to type there, and
-    // Company Email/Phone/Location were dropped from this step entirely (the
-    // Fayda-verified owner supplies contact details now). By label, not
-    // placeholder: the VAT Number field on this same step shares the TIN
-    // field's "0012345678" placeholder, so a placeholder selector matches 2.
-    fillAria('[aria-label^="TIN Number"]', tin);
-    cy.contains("Verified with eTrade", { timeout: 15000 }).should(
-      "be.visible",
-    );
-    // handleETradeDataLoaded sets several fields in sequence (name, region,
-    // zone, woreda, kebele, houseNo) — each a render, still settling right
-    // after the badge appears. Typing into VAT immediately raced one of
-    // those and detached mid-type; let it finish before touching the form.
-    cy.wait(500);
-    fillAria('[aria-label="VAT Number"]', vat);
-    cy.get(".mantine-Modal-content").contains("button", "Continue").click();
-
-    // Personnel (general manager).
-    fill(/^Name/, "General Manager");
-    fill(/^Email/, `gm.${stamp}@example.com`);
-    fillPhone(0, "911234568");
-    cy.get(".mantine-Modal-content").contains("button", "Continue").click();
-
-    // Contact person.
-    fill(/^Name/, "Contact Person");
-    fillPhone(0, "911234569");
-    cy.get(".mantine-Modal-content").contains("button", "Continue").click();
-
-    // PoA — optional for an importer, and left unverified here. The DARS
-    // delegation paper authorises the representative the verification names,
-    // so with no verified PoA there is nothing for it to authorise: the
-    // upload must not be offered, and the step must not block on it. Asserted
-    // as "no file input on this step" rather than by label, so a reworded
-    // document setting doesn't turn a real regression into a passing test.
-    cy.get(".mantine-Modal-content")
-      .contains("Power of Attorney")
-      .should("be.visible");
-    cy.get('.mantine-Modal-content input[type="file"]').should("not.exist");
-    cy.get(".mantine-Modal-content").contains("button", "Continue").click();
-
-    // Documents: no company docs are configured in e2e, but every role needs
-    // a business license.
-    cy.contains("Business license", { timeout: 15000 }).should("be.visible");
-    cy.get('.mantine-Modal-content input[type="file"]')
-      .first()
-      .selectFile("cypress/fixtures/docs/license.pdf", { force: true });
-    cy.get(".mantine-Modal-content")
-      .contains("button", "Submit for review")
-      .click();
-
-    cy.contains("You're all set", { timeout: 30000 }).should("be.visible");
-
-    // DB cross-check: submitted, awaiting approval.
-    cy.task<{ rows: Array<{ status: string; onboarding_completed: boolean }> }>(
-      "db:query",
-      {
-        sql: `SELECT c.status, ep.onboarding_completed
-              FROM freight.companies c
-              JOIN freight.external_profiles ep ON ep.company_id = c.id
-              JOIN iam.users u ON u.id = ep.user_id
-              WHERE u.email = $1`,
-        params: [email],
-      },
-    ).then(({ rows }) => {
-      expect(rows, "company row").to.have.length(1);
-      expect(rows[0].status).to.eq("pending");
-      expect(rows[0].onboarding_completed).to.eq(true);
-    });
-  });
-
-  it("backoffice staff approves the submitted importer profile", () => {
-    cy.loginBackoffice("chief@edr.local");
-    cy.visit("/dashboard/customers");
-
-    latestOnboardJourney().then(({ rows }) => {
-      expect(rows, "onboarded company").to.have.length(1);
-      const company = rows[0].name;
-
-      cy.get('input[placeholder*="Search by company"]').type(company);
-      cy.contains(company, { timeout: 15000 }).click();
-
-      // Role profiles table → approve the pending importer profile. Once
-      // active, the row's action flips to "Suspend".
-      cy.contains("button", "Approve", { timeout: 15000 }).click();
-      cy.contains("button", "Suspend", { timeout: 15000 }).should("be.visible");
-
-      cy.task<{ rows: Array<{ status: string; reference: string | null; company_status: string }> }>(
-        "db:query",
-        {
-          sql: `SELECT p.status, p.reference, c.status AS company_status
-                FROM freight.company_profiles p
-                JOIN freight.companies c ON c.id = p.company_id
-                WHERE c.name = $1 AND p.type = 'importer'`,
-          params: [company],
-        },
-      ).then(({ rows: profiles }) => {
-        expect(profiles, "importer profile").to.have.length(1);
-        expect(profiles[0].status).to.eq("active");
-        expect(profiles[0].reference, "minted reference").to.be.a("string").and
-          .not.be.empty;
-        expect(profiles[0].company_status).to.eq("active");
-      });
-    });
-  });
-
-  it("the approved customer can reach the contract wizard", () => {
-    latestOnboardJourney().then(({ rows }) => {
-      cy.loginPortal(rows[0].email, signupPassword);
-    });
-    cy.visitPortal("/contracts/new");
-
-    // No "Awaiting Approval" gate — the wizard's first step renders.
-    cy.contains("label", "Operation Type", { timeout: 15000 }).should(
-      "be.visible",
-    );
-    cy.contains("Awaiting Approval").should("not.exist");
-  });
-});
-
-export {};

From 431bd3c98b9e69b48078dba138c8fbcd3042884f Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 11:37:43 +0000
Subject: [PATCH 148/174] feat(companies): let a co-operative switch back to
 eTrade as well
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both manual-registration routes exist for one reason — eTrade holds no record
to fetch — so leaving one is the same act whichever it is. A co-operative that
has since taken out a trade licence had no way out at all: the flag is chosen
in the wizard, and an onboarded company can no longer reach it.

revert-to-etrade now accepts either flag and strips both, and a co-operative's
ACTIVE roles go back to Pending with it: those approvals were granted without a
per-role business licence, because a co-op owes none, and the moment it stops
being one that licence is due. Rejected, suspended and blacklisted roles are
left alone — promoting a blocked role to "awaiting approval" would launder a
staff decision away. An investor's roles are untouched; their licences were
always due and already reviewed.

Switching INTO a route stays with the wizard's nationality/role step, which
owns the mutually-exclusive rules; a second entry point would restate all three.
---
 .../modules/companies/companies.controller.ts |  2 +-
 .../companies.investor-licence.spec.ts        | 89 ++++++++++++++++++-
 .../modules/companies/companies.service.ts    | 52 ++++++++++-
 .../pages/settings/RegistrationSourceCard.tsx | 39 ++++++--
 4 files changed, 165 insertions(+), 17 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/companies/companies.controller.ts b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
index 4139424c1..5d29b32f6 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.controller.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.controller.ts
@@ -297,7 +297,7 @@ export class CompaniesController {
   @PortalCustomer()
   @ApiOperation({
     summary:
-      "Drop the foreign investment-licence route: clear the typed registration and reopen onboarding so the TIN is verified against eTrade",
+      "Drop the manual-registration route (co-operative or foreign investment licence): clear the typed registration and reopen onboarding so the TIN is verified against eTrade",
   })
   async revertToRegularCompany(
     @CurrentUser() user: CurrentIamUser,
diff --git a/apps/edr-freight-api/src/modules/companies/companies.investor-licence.spec.ts b/apps/edr-freight-api/src/modules/companies/companies.investor-licence.spec.ts
index 9623945d1..9de99186f 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.investor-licence.spec.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.investor-licence.spec.ts
@@ -6,7 +6,10 @@ import {
   CompanyStatus,
   CompanyType,
 } from "./entities/company.entity";
-import { ProfileType } from "./entities/company-profile.entity";
+import {
+  ProfileStatus,
+  ProfileType,
+} from "./entities/company-profile.entity";
 
 /**
  * A foreign company on an Investment Commission licence has no eTrade record,
@@ -14,6 +17,9 @@ import { ProfileType } from "./entities/company-profile.entity";
  * backoffice treat those fields as unverified. Two things must hold: only a
  * foreign company can carry it, and dropping it must not leave the typed
  * registration behind looking like eTrade's.
+ *
+ * The dropping half is shared with the co-operative route, which has the same
+ * "eTrade holds nothing" shape, so it is exercised here for both.
  */
 function makeService(company: Record<string, unknown> | null) {
   const companiesRepo = {
@@ -26,7 +32,8 @@ function makeService(company: Record<string, unknown> | null) {
     existsByTin: jest.fn(async () => false),
   };
   const companyProfilesRepo = {
-    findByCompanyId: jest.fn(async () => []),
+    findByCompanyId: jest.fn(async (): Promise<Record<string, unknown>[]> => []),
+    updateStatus: jest.fn(async () => null),
     create: jest.fn(async (row: Record<string, unknown>) => ({
       id: "cp-1",
       ...row,
@@ -68,7 +75,7 @@ function makeService(company: Record<string, unknown> | null) {
         ({ profile: { id: "external-1" }, company: { id: "company-1" } }) as never,
     );
 
-  return { service, companiesRepo, profilesRepo };
+  return { service, companiesRepo, companyProfilesRepo, profilesRepo };
 }
 
 const identity = { userId: "user-1", firstName: "Abebe", lastName: "K" };
@@ -202,10 +209,84 @@ describe("the foreign investment-licence route", () => {
     expect(profilesRepo.update).not.toHaveBeenCalled();
   });
 
-  it("refuses to switch a company that never took the investment-licence route", async () => {
+  it("refuses to switch a company that never took a manual-registration route", async () => {
     const { service } = makeService({ id: "company-1", attributes: {} });
     await expect(service.revertToRegularCompany("user-1")).rejects.toBeInstanceOf(
       BadRequestException,
     );
   });
+
+  /**
+   * The switch belongs to both manual-registration routes, not just this one. A
+   * co-operative that has since taken out a trade licence had no way back at
+   * all: the wizard is where the flag is chosen, and an onboarded company can no
+   * longer reach it.
+   */
+  it("switches a co-operative back to eTrade on the same terms", async () => {
+    const { service, companiesRepo, profilesRepo } = makeService({
+      id: "company-1",
+      nationality: CompanyNationality.Ethiopian,
+      attributes: { cooperative: true, etradeManagerName: "Typed Name" },
+      region: "Oromia",
+      licenceNumber: "TYPED-1",
+    });
+
+    await service.revertToRegularCompany("user-1");
+
+    const [, updates] = companiesRepo.update.mock.calls[0] as unknown as [
+      string,
+      Record<string, unknown>,
+    ];
+    expect(updates.attributes).toEqual({});
+    expect(updates.status).toBe(CompanyStatus.Pending);
+    expect(updates.licenceNumber).toBeNull();
+    expect(updates.region).toBeNull();
+    // A co-op owes no per-role business licence; once it stops being one it
+    // does, so the application has to be re-opened and re-reviewed.
+    expect(profilesRepo.update).toHaveBeenCalledWith("external-1", {
+      onboardingCompleted: false,
+      onboardingStep: "company",
+    });
+  });
+
+  /**
+   * Approval of a co-op's role was granted without a business licence, because
+   * a co-op owes none. Leaving makes one due, so the approval no longer stands
+   * for what it said.
+   */
+  it("sends a co-operative's approved roles back for approval", async () => {
+    const { service, companyProfilesRepo } = makeService({
+      id: "company-1",
+      attributes: { cooperative: true },
+    });
+    companyProfilesRepo.findByCompanyId.mockResolvedValue([
+      { id: "role-active", status: ProfileStatus.Active },
+      { id: "role-blocked", status: ProfileStatus.Blacklisted },
+      { id: "role-pending", status: ProfileStatus.Pending },
+    ]);
+
+    await service.revertToRegularCompany("user-1");
+
+    expect(companyProfilesRepo.updateStatus).toHaveBeenCalledWith(
+      "role-active",
+      ProfileStatus.Pending,
+    );
+    // A staff decision is not the customer's to undo by switching registration:
+    // promoting a blocked role to "awaiting approval" would launder the block.
+    expect(companyProfilesRepo.updateStatus).toHaveBeenCalledTimes(1);
+  });
+
+  it("leaves an investor's roles alone — their licences were always due", async () => {
+    const { service, companyProfilesRepo } = makeService({
+      id: "company-1",
+      attributes: { investorLicence: true },
+    });
+    companyProfilesRepo.findByCompanyId.mockResolvedValue([
+      { id: "role-active", status: ProfileStatus.Active },
+    ]);
+
+    await service.revertToRegularCompany("user-1");
+
+    expect(companyProfilesRepo.updateStatus).not.toHaveBeenCalled();
+  });
 });
diff --git a/apps/edr-freight-api/src/modules/companies/companies.service.ts b/apps/edr-freight-api/src/modules/companies/companies.service.ts
index 6dae48f24..1eb611c24 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.service.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.service.ts
@@ -2486,8 +2486,14 @@ export class CompaniesService {
   }
 
   /**
-   * Drop the investment-licence route and send the company back through the
-   * normal eTrade one.
+   * Drop whichever manual-registration route the company is on and send it back
+   * through the normal eTrade one.
+   *
+   * Both routes exist for the same reason — eTrade holds no record to fetch —
+   * so leaving one is the same act whichever it is, and it is the only way back
+   * to eTrade for either. A co-operative union or farm that has since taken out
+   * a trade licence had no exit at all before this; its only route was the
+   * wizard, which an onboarded company can no longer reach.
    *
    * Everything the flag let the customer type is cleared, not kept: the
    * registration block on file was their own statement, and leaving it there
@@ -2497,6 +2503,13 @@ export class CompaniesService {
    * reach. Onboarding reopens at the company step and the company goes back to
    * pending — an approval granted against typed data cannot silently carry over
    * to a record that now claims to be eTrade's.
+   *
+   * Switching the other way — INTO a co-operative or an investment licence — is
+   * deliberately not here. It is the wizard's nationality/role step, which this
+   * reopens, and which is the one place the mutually-exclusive rules live
+   * (`assertInvestorLicenceAllowed`, `assertRolesAllowedForCooperative`,
+   * `assertNationalityAllowedForCooperative`). A second entry point would have
+   * to restate all three.
    */
   async revertToRegularCompany(
     userId: string,
@@ -2509,14 +2522,21 @@ export class CompaniesService {
     const company = await this.companiesRepo.findById(companyId);
     if (!company)
       throw new NotFoundException(`Company ${companyId} not found`);
-    if (!hasInvestorLicence(company)) {
+    if (!usesManualRegistration(company)) {
       throw new BadRequestException(
         "This company is already registered through eTrade — there is nothing to switch.",
       );
     }
 
+    const wasCooperative = isCooperative(company);
+
+    // Both flags go, not just the one that was set: they are mutually exclusive
+    // and a company can only ever hold one, but the destination is "neither",
+    // so stripping only the one we happened to check for would leave the other
+    // behind if the pair ever did coexist.
     const attributes = this.withoutTypedEtradeManager(company.attributes);
     delete attributes[INVESTOR_LICENCE_KEY];
+    delete attributes[COOPERATIVE_KEY];
 
     await this.companiesRepo.update(companyId, {
       ...CompaniesService.CLEARED_REGISTRATION,
@@ -2527,6 +2547,32 @@ export class CompaniesService {
       onboardingCompleted: false,
       onboardingStep: "company",
     });
+
+    // A co-operative owes no per-role business licence — that is the whole
+    // reason its own document set stands in for one. The moment it stops being
+    // one, every role owes a licence that was never uploaded, so an approval
+    // granted without one no longer means what it said: back to Pending, and
+    // the reviewer sees the licence with the rest of the re-application.
+    //
+    // Only Active roles move. Rejected, Suspended and Blacklisted are the
+    // backoffice's own decisions, and quietly promoting a blocked role to
+    // "awaiting approval" would launder the block away. The reference survives
+    // either way — it is minted once (`setCompanyProfileStatus`) and re-approval
+    // reuses it, so bookings that cite it keep citing the same number.
+    //
+    // An investor is untouched: it always held a licence per role, so nothing
+    // becomes due that was not already reviewed.
+    if (wasCooperative) {
+      const roles = await this.companyProfilesRepo.findByCompanyId(companyId);
+      for (const role of roles) {
+        if (role.status !== ProfileStatus.Active) continue;
+        await this.companyProfilesRepo.updateStatus(
+          role.id,
+          ProfileStatus.Pending,
+        );
+      }
+    }
+
     return this.getCompanyInfoByUserId(userId);
   }
 
diff --git a/apps/edr-freight-web/portal/src/pages/settings/RegistrationSourceCard.tsx b/apps/edr-freight-web/portal/src/pages/settings/RegistrationSourceCard.tsx
index 09f4e7195..a814db2b5 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/RegistrationSourceCard.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/RegistrationSourceCard.tsx
@@ -18,15 +18,21 @@ import type { ProfileResponse } from "@/types/profile";
 import { extractApiError } from "@/utils/result";
 
 /**
- * Leave the foreign investment-licence route and go back to the ordinary eTrade
- * one — for a company that has since been registered with the trade registry,
- * or that ticked the box by mistake.
+ * Leave whichever manual-registration route the company is on — a co-operative
+ * union or farm, or a foreign investment licence — and go back to the ordinary
+ * eTrade one. For a company that has since been registered with the trade
+ * registry, or that ticked the box by mistake.
  *
  * It is a re-application, not a settings edit: the API clears the registration
  * the customer typed (nothing on file was ever checked against a licence) and
  * puts the company back to pending, so the wizard reopens on the company step
  * and the TIN goes through eTrade this time. Said plainly here rather than
  * discovered afterwards.
+ *
+ * Only the way OUT is here. Moving between the three registration sources in
+ * the other direction is the wizard's own step, which this reopens — that is
+ * where the rules about which combinations are legal already live, and a second
+ * picker would have to restate every one of them.
  */
 export default function RegistrationSourceCard({
   profile,
@@ -61,7 +67,9 @@ export default function RegistrationSourceCard({
     onError: (err) => setError(extractApiError(err).message),
   });
 
-  if (!profile.investorLicence) return null;
+  // Which of the two routes this is — wording only; leaving costs the same.
+  const cooperative = profile.cooperative;
+  if (!profile.investorLicence && !cooperative) return null;
 
   return (
     <>
@@ -72,9 +80,9 @@ export default function RegistrationSourceCard({
         </Group>
         <Stack gap="md">
           <Text size="sm" c="edr-muted">
-            Your company is registered on a foreign investment licence, so your
-            registration details were entered by hand instead of being read from
-            eTrade. Our team reviews them against the documents you uploaded.
+            {cooperative
+              ? "Your company is registered as a co-operative union or farm, so your registration details were entered by hand instead of being read from eTrade. Our team reviews them against the documents you uploaded."
+              : "Your company is registered on a foreign investment licence, so your registration details were entered by hand instead of being read from eTrade. Our team reviews them against the documents you uploaded."}
           </Text>
           <Text size="sm" c="edr-muted">
             If your company now holds an eTrade trade licence, you can switch
@@ -118,12 +126,25 @@ export default function RegistrationSourceCard({
               Your company goes back to pending and is reviewed again.
             </List.Item>
             <List.Item>
-              Your documents, owner and contact details stay as they are.
+              Your documents, owner and contact details stay as they are — but
+              the papers we ask for change with the registration source, so some
+              may be listed as outstanding again.
             </List.Item>
+            {cooperative && (
+              <List.Item>
+                A business licence becomes due for each of your operational
+                services — a co-operative owes none, an eTrade-registered
+                company does — so any that are already approved go back to
+                awaiting approval until you upload one. Their reference numbers
+                stay the same.
+              </List.Item>
+            )}
           </List>
           <Alert color="amber" variant="light" icon={<AlertCircle size={18} />}>
             If eTrade holds no record for your TIN you won't be able to finish —
-            come back here and re-select the investment licence in the wizard.
+            the wizard reopens on the company step, so go back one step and
+            re-select {cooperative ? "co-operative" : "the investment licence"}{" "}
+            there.
           </Alert>
           {error && (
             <Text size="sm" c="red">

From 0608f8a7eaceb3679e27ca1b558ec37ce97c313a Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 11:37:58 +0000
Subject: [PATCH 149/174] fix(portal): bring the settings tabs in line with the
 wizard's rules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Company, Owner, Contact and Power of Attorney tabs had drifted from the
onboarding wizard while the manual-registration routes were added, and each
divergence locked somebody out of their own account:

- VAT was validated as 10-or-11 digits here and by onboarding's rule there. A
  foreign company's VAT is its own tax authority's and a co-operative's follows
  neither, so the stricter copy failed every save on the tab, not just the VAT
  field. The schema now reuses onboarding's, with a test pinning both rules.
- Fayda's phone claims are normalized on read, as the wizard does — the
  registry holds local numbers that neither the form nor the API's
  @IsValidPhone() accepts.
- The eTrade manager is shown read-only, because that record is exactly what
  the backoffice checks the company against; leaving it editable let a customer
  overwrite the value under review.
- A co-operative's per-role licence cards are hidden on the Documents tab. The
  API lifts the requirement, so the slots could never be filled or cleared.
---
 .../src/pages/settings/TabCompanyProfile.tsx  | 204 ++++++++++++++++--
 .../src/pages/settings/TabContactPerson.tsx   |  62 ++++--
 .../src/pages/settings/TabDocuments.tsx       |   6 +-
 .../portal/src/pages/settings/TabOwner.tsx    | 113 +++++++---
 .../src/pages/settings/TabPowerOfAttorney.tsx | 196 ++++++++++++++---
 .../settings/companyProfileSchema.test.ts     |  70 ++++++
 6 files changed, 560 insertions(+), 91 deletions(-)
 create mode 100644 apps/edr-freight-web/portal/src/pages/settings/companyProfileSchema.test.ts

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 a359a3ff0..f8eb58e8f 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabCompanyProfile.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabCompanyProfile.tsx
@@ -11,6 +11,7 @@ import {
   Button,
   Card,
   Group,
+  Select,
   SimpleGrid,
   Stack,
   Text,
@@ -20,18 +21,22 @@ import {
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { Building2, CheckCircle2, Save, XCircle } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
+import type { FieldErrors, UseFormRegister, UseFormSetValue } from "react-hook-form";
 import { useForm } from "react-hook-form";
 import { z } from "zod";
-import type { CompanyRegistrationData } from "@edr/types";
+import { ETHIOPIAN_REGIONS, type CompanyRegistrationData } from "@edr/types";
 import OnboardingRoleSelect from "./OnboardingRoleSelect";
 import ETradeInfo, {
   type ETradeStatus,
 } from "@/components/onboarding/ETradeInfo";
 import { ReadOnlyField } from "@/pages/accounts/companyProfileForm/ReadOnlyField";
 import StepSection from "@/pages/accounts/companyProfileForm/StepSection";
-import { ETRADE_BUNDLE_FIELDS as SHARED_ETRADE_FIELDS } from "@/pages/accounts/companyProfileForm/schema";
+import {
+  ETRADE_BUNDLE_FIELDS as SHARED_ETRADE_FIELDS,
+  onboardingSchema,
+} from "@/pages/accounts/companyProfileForm/schema";
 
-export const COMPANY_PROFILE_SCHEMA = z.object({
+const BASE_COMPANY_PROFILE_SCHEMA = z.object({
   // eTrade-sourced and read-only, like the registration block below.
   companyName: z.string().optional(),
   companyLocation: z.string().min(1, "Location is required"),
@@ -39,12 +44,13 @@ export const COMPANY_PROFILE_SCHEMA = z.object({
   // no standalone input.
   companyAddress: z.string().optional(),
   tinNumber: z.string().regex(/^\d{10}$/, "TIN must be exactly 10 digits"),
-  // Same rule as onboarding — the two forms write the same column, so they must
-  // not disagree about what is acceptable in it.
-  vatNumber: z
-    .string()
-    .min(1, "VAT number is required")
-    .regex(/^\d{10,11}$/, "VAT number must be 10 or 11 digits"),
+  // Onboarding's own rule, reused rather than restated: the two forms write the
+  // same column, and the copy here had drifted into a 10-or-11-digit check that
+  // onboarding and the API both refuse to make. A foreign company's VAT is
+  // whatever its tax authority issues and a co-operative's follows neither, so
+  // the stricter copy locked those customers out of their own Company tab
+  // entirely — every save on it, not just the VAT.
+  vatNumber: onboardingSchema.shape.vatNumber,
   ownerPassportNumber: z.string().optional(),
   // Registration/address fields are eTrade-sourced and never typed by hand —
   // not even when eTrade leaves one blank, so none of them may be required
@@ -62,7 +68,48 @@ export const COMPANY_PROFILE_SCHEMA = z.object({
   houseNo: z.string().optional(),
 });
 
-export type CompanyProfileFormData = z.infer<typeof COMPANY_PROFILE_SCHEMA>;
+/**
+ * The registration fields a manual-registration company types by hand.
+ *
+ * eTrade holds no record for a co-operative union or farm, nor for a foreign
+ * investor on an Investment Commission licence, so the block every other
+ * company gets read-only off the licence is typed by these two — and is
+ * therefore required of them, exactly as the onboarding wizard requires it.
+ * House number stays optional: plenty of addresses have none.
+ */
+const TYPED_REGISTRATION_LABELS = {
+  companyName: "Company name",
+  region: "Region",
+  zone: "Zone",
+  woreda: "Woreda",
+  kebele: "Kebele",
+} as const;
+
+/**
+ * `manualRegistration` is the only thing that changes here, and it changes the
+ * same way it does in the wizard: **a field is required iff there is an input
+ * on screen for it.** For an eTrade company these are read-only rows, so
+ * requiring one would be a Save button failing on a field with nothing to fix.
+ */
+export const buildCompanyProfileSchema = (manualRegistration: boolean) =>
+  manualRegistration
+    ? BASE_COMPANY_PROFILE_SCHEMA.superRefine((d, ctx) => {
+        for (const key of Object.keys(
+          TYPED_REGISTRATION_LABELS,
+        ) as (keyof typeof TYPED_REGISTRATION_LABELS)[]) {
+          if (d[key]?.trim()) continue;
+          ctx.addIssue({
+            code: "custom",
+            path: [key],
+            message: `${TYPED_REGISTRATION_LABELS[key]} is required`,
+          });
+        }
+      })
+    : BASE_COMPANY_PROFILE_SCHEMA;
+
+export type CompanyProfileFormData = z.infer<
+  typeof BASE_COMPANY_PROFILE_SCHEMA
+>;
 
 /**
  * `etradePhone` is not on this form, so the shared list is filtered down to the
@@ -86,6 +133,17 @@ export default function TabCompanyProfile({
 }: TabCompanyProfileProps) {
   const queryClient = useQueryClient();
   const isCreate = mode === "create";
+  /**
+   * eTrade has nothing to say about this company — a co-operative holds no
+   * business licence, a foreign investor's is the Investment Commission's — so
+   * its registration was typed during onboarding and has to stay editable here.
+   * Rendering the eTrade card instead left that data invisible and frozen: the
+   * one company that owns its registration details was the one that could not
+   * see them.
+   */
+  const manualRegistration = Boolean(
+    profile?.cooperative || profile?.investorLicence,
+  );
   const [selectedRoles, setSelectedRoles] = useState<string[]>([]);
   const [tinStatus, setTinStatus] = useState<ETradeStatus>("idle");
 
@@ -140,7 +198,7 @@ export default function TabCompanyProfile({
     setValue,
     formState: { errors, isDirty, dirtyFields },
   } = useForm<CompanyProfileFormData>({
-    resolver: zodResolver(COMPANY_PROFILE_SCHEMA),
+    resolver: zodResolver(buildCompanyProfileSchema(manualRegistration)),
     values: defaultValues,
   });
 
@@ -315,7 +373,6 @@ export default function TabCompanyProfile({
                 <TextInput
                   label="VAT Number"
                   placeholder="e.g. 0012345678"
-                  maxLength={11}
                   error={errors.vatNumber?.message}
                   {...register("vatNumber")}
                 />
@@ -325,13 +382,21 @@ export default function TabCompanyProfile({
               <StepSection
                 index={2}
                 title="Company TIN"
-                subtitle="Re-verify with eTrade to refresh your registration record — nothing here is typed by hand."
+                subtitle={
+                  manualRegistration
+                    ? "We'll check eTrade for your TIN. If it holds nothing — the usual case here — the details below stay yours to state."
+                    : "Re-verify with eTrade to refresh your registration record — nothing here is typed by hand."
+                }
                 status={
-                  tinVerified
-                    ? "done"
-                    : tinStatus === "taken"
-                      ? "blocked"
-                      : "todo"
+                  tinStatus === "taken"
+                    ? "blocked"
+                    : manualRegistration
+                      ? watch("tinNumber")?.trim() && !errors.tinNumber
+                        ? "done"
+                        : "todo"
+                      : tinVerified
+                        ? "done"
+                        : "todo"
                 }
               >
                 <ETradeInfo
@@ -342,12 +407,33 @@ export default function TabCompanyProfile({
                   onStatusChange={setTinStatus}
                   alreadyVerified={hasRegistrationDetails}
                   selectedLicenceNumber={watch("licenceNumber")}
+                  registrationOptional={manualRegistration}
                 />
-                {tinVerified && (
+                {!manualRegistration && tinVerified && (
                   <EtradeLockedCard tin={watch("tinNumber")} watch={watch} />
                 )}
               </StepSection>
 
+              {manualRegistration && (
+                <StepSection
+                  index={3}
+                  title="Registration details"
+                  subtitle="Everything we'd normally read off an eTrade licence. Our team checks what you state here against the documents you upload."
+                  status={
+                    watch("companyName")?.trim() && watch("region")?.trim()
+                      ? "done"
+                      : "todo"
+                  }
+                >
+                  <TypedRegistrationFields
+                    register={register}
+                    watch={watch}
+                    setValue={setValue}
+                    errors={errors}
+                  />
+                </StepSection>
+              )}
+
               <TextInput
                 label="Location"
                 placeholder="Addis Ababa, Ethiopia"
@@ -409,6 +495,86 @@ export default function TabCompanyProfile({
   );
 }
 
+/**
+ * The registration a manual-registration company states for itself.
+ *
+ * Deliberately editable, unlike `EtradeLockedCard` below: nothing here came
+ * from a licence, so there is no verified record to protect — it is the
+ * customer's own claim, checked by a reviewer against the papers they upload.
+ * Same fields, same rules and same region list as the onboarding wizard's
+ * company step, so a co-operative or investor sees one story in both places.
+ */
+function TypedRegistrationFields({
+  register,
+  watch,
+  setValue,
+  errors,
+}: {
+  register: UseFormRegister<CompanyProfileFormData>;
+  watch: ReturnType<typeof useForm<CompanyProfileFormData>>["watch"];
+  setValue: UseFormSetValue<CompanyProfileFormData>;
+  errors: FieldErrors<CompanyProfileFormData>;
+}) {
+  const region = watch("region") ?? "";
+
+  return (
+    <Stack gap="md">
+      <TextInput
+        label="Company Name"
+        placeholder="Registered name of the company"
+        error={errors.companyName?.message}
+        {...register("companyName")}
+      />
+      <Text size="sm" c="edr-muted">
+        Registered address
+      </Text>
+      <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+        <Select
+          label="Region"
+          placeholder="Select region"
+          // A value eTrade (or an earlier save) supplied may not be spelled the
+          // way our list spells it. Carrying it in as an option keeps it visible
+          // rather than silently blanking a field nobody touched.
+          data={
+            region && !(ETHIOPIAN_REGIONS as readonly string[]).includes(region)
+              ? [...ETHIOPIAN_REGIONS, region]
+              : [...ETHIOPIAN_REGIONS]
+          }
+          searchable
+          value={region || null}
+          onChange={(v) =>
+            setValue("region", v ?? "", {
+              shouldValidate: true,
+              shouldDirty: true,
+            })
+          }
+          error={errors.region?.message}
+        />
+        <TextInput
+          label="Zone"
+          error={errors.zone?.message}
+          {...register("zone")}
+        />
+        <TextInput
+          label="Woreda"
+          error={errors.woreda?.message}
+          {...register("woreda")}
+        />
+        <TextInput
+          label="Kebele"
+          error={errors.kebele?.message}
+          {...register("kebele")}
+        />
+        <TextInput
+          label="House No."
+          error={errors.houseNo?.message}
+          {...register("houseNo")}
+        />
+      </SimpleGrid>
+    </Stack>
+  );
+}
+
 /**
  * The verified eTrade record, rendered strictly read-only — same rule as
  * onboarding's ETradeCompanyCard: nothing here is typeable, not even a field
diff --git a/apps/edr-freight-web/portal/src/pages/settings/TabContactPerson.tsx b/apps/edr-freight-web/portal/src/pages/settings/TabContactPerson.tsx
index d78add01b..3ed377c83 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabContactPerson.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabContactPerson.tsx
@@ -5,20 +5,30 @@ import { zodResolver } from "@hookform/resolvers/zod";
 import { z } from "zod";
 import { CheckCircle2, Save, User, XCircle } from "lucide-react";
 import {
+  Button,
   Card,
   Group,
+  SimpleGrid,
   Stack,
-  Title,
   Text,
   TextInput,
-  Button,
+  Title,
 } from "@mantine/core";
 import { api } from "@/services/api";
 import { ControlledPhoneField, isValidPhone } from "@/components/PhoneField";
 import type { ProfileResponse } from "@/types/profile";
 
+// The same four fields onboarding collects, with the same requiredness. The
+// position and the email were captured by the wizard and then had no input
+// here at all — stored, invisible, and impossible to correct.
 const schema = z.object({
   contactPersonName: z.string().min(1, "Contact person name is required"),
+  contactPersonPosition: z.string().optional(),
+  contactPersonEmail: z
+    .string()
+    .email("Invalid email address")
+    .optional()
+    .or(z.literal("")),
   contactPersonPhone: z
     .string()
     .min(1, "Contact person phone is required")
@@ -39,6 +49,8 @@ export default function TabContactPerson({ profile, mode = "edit", onContinue }:
   const defaultValues = useMemo((): FormData => {
     return {
       contactPersonName: profile.contactPersonName ?? "",
+      contactPersonPosition: profile.contactPersonPosition ?? "",
+      contactPersonEmail: profile.contactPersonEmail ?? "",
       contactPersonPhone: profile.contactPersonPhone ?? "",
     };
   }, [profile]);
@@ -58,6 +70,11 @@ export default function TabContactPerson({ profile, mode = "edit", onContinue }:
     mutationFn: (data: FormData) =>
       api.companies.updateProfile.call({
         contactPersonName: data.contactPersonName,
+        // `|| undefined`, never "": the DTO's `@IsOptional()` only skips null
+        // and undefined, so an empty string is validated and 400s with
+        // "contactPersonEmail must be an email".
+        contactPersonPosition: data.contactPersonPosition || undefined,
+        contactPersonEmail: data.contactPersonEmail || undefined,
         contactPersonPhone: data.contactPersonPhone,
       }),
     onSuccess: () => {
@@ -80,19 +97,36 @@ export default function TabContactPerson({ profile, mode = "edit", onContinue }:
 
       <form onSubmit={handleSubmit(onSubmit)}>
         <Stack gap="md">
-          <TextInput
-            label="Full Name"
-            placeholder="Jane Smith"
-            error={errors.contactPersonName?.message}
-            {...register("contactPersonName")}
-          />
+          <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+            <TextInput
+              label="Full Name"
+              placeholder="Jane Smith"
+              error={errors.contactPersonName?.message}
+              {...register("contactPersonName")}
+            />
+            <TextInput
+              label="Position (Optional)"
+              placeholder="Operations Lead"
+              error={errors.contactPersonPosition?.message}
+              {...register("contactPersonPosition")}
+            />
+          </SimpleGrid>
 
-          <ControlledPhoneField
-            control={control}
-            name="contactPersonPhone"
-            label="Phone Number"
-            required
-          />
+          <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+            <TextInput
+              label="Email (Optional)"
+              type="email"
+              placeholder="contact@company.com"
+              error={errors.contactPersonEmail?.message}
+              {...register("contactPersonEmail")}
+            />
+            <ControlledPhoneField
+              control={control}
+              name="contactPersonPhone"
+              label="Phone Number"
+              required
+            />
+          </SimpleGrid>
         </Stack>
 
         <Group
diff --git a/apps/edr-freight-web/portal/src/pages/settings/TabDocuments.tsx b/apps/edr-freight-web/portal/src/pages/settings/TabDocuments.tsx
index 584fb70d6..617b92826 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabDocuments.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabDocuments.tsx
@@ -171,7 +171,11 @@ export default function TabDocuments({
     return errs;
   };
 
-  const licenseProfiles = profile.companyProfiles;
+  // A co-operative union or farm holds no business licence — that is the whole
+  // reason it uploads its own document set instead — so the API lifts the
+  // per-role requirement and these cards are not shown. Offering an upload slot
+  // nothing can ever fill reads as an outstanding task that cannot be finished.
+  const licenseProfiles = profile.cooperative ? [] : profile.companyProfiles;
 
   // Company documents render through SmartFileInput, which is keyed by field and
   // has no per-file review slot. Surfacing the outstanding corrections as one
diff --git a/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx b/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx
index def3126f1..a1dca3f0d 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabOwner.tsx
@@ -1,3 +1,4 @@
+import { useMemo } from "react";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useForm } from "react-hook-form";
 import { zodResolver } from "@hookform/resolvers/zod";
@@ -19,6 +20,11 @@ import { api } from "@/services/api";
 import { ControlledPhoneField, isValidPhone } from "@/components/PhoneField";
 import FaydaVerifyPanel from "@/components/FaydaVerifyPanel";
 import SourcedField from "@/pages/accounts/companyProfileForm/SourcedField";
+import {
+  firstValidPhone,
+  normalizeIdentityPhones,
+  resolveOwnerSources,
+} from "@/pages/accounts/companyProfileForm/helpers";
 import type { ProfileResponse } from "@/types/profile";
 
 // Optional, not unrequired: whatever a Fayda verification supplied is owned by
@@ -27,6 +33,10 @@ import type { ProfileResponse } from "@/types/profile";
 // are actually on screen; zod only polices format.
 const schema = z.object({
   ownerName: z.string().optional(),
+  // The alternative credential for a foreign company's owner — asked for only
+  // when they are the identity subject and have not verified with Fayda, so
+  // like the three below it is optional here and gated on what is rendered.
+  ownerPassportNumber: z.string().optional(),
   ownerEmail: z
     .string()
     .optional()
@@ -64,20 +74,41 @@ export default function TabOwner({
   onContinue,
 }: TabOwnerProps) {
   const queryClient = useQueryClient();
-  const identity = profile.identity;
+  // Fayda reports a phone as the national registry holds it, routinely a local
+  // number that neither this form nor the API's `@IsValidPhone()` accepts.
+  // Normalize once on read, exactly as the wizard does.
+  const identity = useMemo(
+    () => normalizeIdentityPhones(profile.identity),
+    [profile.identity],
+  );
   const owner = identity?.owner;
   // Only the person the declaration points at carries the verification, so the
   // panel is offered here only when that person is the owner.
   const ownerIsSubject = identity?.subject === "owner";
-  // A Fayda verification owns what its claims filled — the API refuses to
-  // overwrite those, so they show read-only. Anything it left blank stays
-  // editable here, whatever value is currently stored.
   const ownerVerified = owner?.verified ?? false;
-  const ownerLocked = {
-    name: ownerVerified && Boolean(owner?.name?.trim()),
-    email: ownerVerified && Boolean(owner?.email?.trim()),
-    phone: ownerVerified && Boolean(owner?.phone?.trim()),
-  };
+
+  /**
+   * The manager the eTrade licence names, read back from what the lookup
+   * captured. The wizard shows these read-only for the same reason this tab
+   * must: that record is what the backoffice checks the company against, so it
+   * is reported, not retyped. Leaving it editable here let a customer overwrite
+   * the very value the review compares against.
+   */
+  const etradeOwner = useMemo(() => {
+    const name = identity?.etradeManagerName?.trim() ?? "";
+    // Dropped if it cannot normalize — eTrade's is free text ("09        " is a
+    // real answer), and an unusable number must fall through to an input rather
+    // than lock the field behind a value the API would reject.
+    const phone = firstValidPhone(identity?.etradeManagerPhone);
+    return name || phone ? { name, phone } : null;
+  }, [identity?.etradeManagerName, identity?.etradeManagerPhone]);
+
+  // Who owns each field, and with what value — the wizard's own rule, reused so
+  // the two cannot disagree about which details are the customer's to edit.
+  const { source: ownerSource, sourced: ownerSourced } = resolveOwnerSources(
+    identity,
+    etradeOwner,
+  );
 
   const {
     register,
@@ -90,19 +121,23 @@ export default function TabOwner({
       ownerName: profile.ownerName ?? "",
       ownerEmail: profile.ownerEmail ?? "",
       ownerPhone: profile.ownerPhone ?? "",
+      ownerPassportNumber: profile.identity?.owner.passportNumber ?? "",
     },
   });
 
   const mutation = useMutation({
     mutationFn: (data: FormData) =>
       api.companies.updateProfile.call({
-        // `|| undefined`, never "": the DTO's `@IsOptional()` only skips null
-        // and undefined, so an empty string is validated and 400s with
-        // "ownerEmail must be an email". A verified owner legitimately leaves
-        // the fields Fayda did supply blank here.
-        ownerName: data.ownerName || undefined,
-        ownerEmail: data.ownerEmail || undefined,
-        ownerPhone: data.ownerPhone || undefined,
+        // A field a source owns is submitted as that source has it, not as the
+        // form happens to hold it: the read-only row is what the customer was
+        // shown, and only the fields are sent. `|| undefined`, never "": the
+        // DTO's `@IsOptional()` skips null and undefined, so an empty string is
+        // validated and 400s with "ownerEmail must be an email", and a verified
+        // owner legitimately leaves the fields Fayda supplied blank here.
+        ownerName: (ownerSourced.name || data.ownerName) || undefined,
+        ownerEmail: (ownerSourced.email || data.ownerEmail) || undefined,
+        ownerPhone: (ownerSourced.phone || data.ownerPhone) || undefined,
+        ownerPassportNumber: data.ownerPassportNumber || undefined,
       }),
     onSuccess: () => {
       queryClient.invalidateQueries({
@@ -112,15 +147,21 @@ export default function TabOwner({
     },
   });
 
-  // What the verification did NOT supply. Fayda's email and phone claims are
-  // optional, so a verified owner can still be missing details the API demands
-  // — the API leaves exactly those keys typeable, and so does this form.
-  const gaps = {
-    name: !owner?.name?.trim(),
-    email: !owner?.email?.trim(),
-    phone: !owner?.phone?.trim(),
-  };
-  const savable = gaps.name || gaps.email || gaps.phone;
+  // A foreign owner who is the identity subject and has not verified proves
+  // themselves with a passport instead — the same either/or the wizard offers.
+  // Without an input here the only route to it was the onboarding wizard, which
+  // an onboarded company can no longer reach.
+  const passportAskable =
+    (identity?.passportAccepted ?? false) && ownerIsSubject && !ownerVerified;
+
+  // Save is offered when there is at least one input on screen to save. A field
+  // an outside source owns has none, so an owner fully supplied by Fayda and
+  // eTrade has nothing to submit.
+  const savable =
+    !ownerSource.name ||
+    !ownerSource.email ||
+    !ownerSource.phone ||
+    passportAskable;
 
   return (
     <Card padding="lg">
@@ -158,8 +199,8 @@ export default function TabOwner({
 
           <SourcedField
             label="Name"
-            value={owner?.name}
-            source={ownerLocked.name ? "Fayda" : null}
+            value={ownerSourced.name}
+            source={ownerSource.name}
           >
             <TextInput
               label="Name"
@@ -173,8 +214,8 @@ export default function TabOwner({
             <Grid.Col span={{ base: 12, sm: 6 }}>
               <SourcedField
                 label="Email"
-                value={owner?.email}
-                source={ownerLocked.email ? "Fayda" : null}
+                value={ownerSourced.email}
+                source={ownerSource.email}
               >
                 <TextInput
                   label="Email"
@@ -188,8 +229,8 @@ export default function TabOwner({
             <Grid.Col span={{ base: 12, sm: 6 }}>
               <SourcedField
                 label="Phone"
-                value={owner?.phone}
-                source={ownerLocked.phone ? "Fayda" : null}
+                value={ownerSourced.phone}
+                source={ownerSource.phone}
               >
                 <ControlledPhoneField
                   control={control}
@@ -200,6 +241,16 @@ export default function TabOwner({
             </Grid.Col>
           </Grid>
 
+          {passportAskable && (
+            <TextInput
+              label="Owner's Passport Number"
+              description="Fayda is an Ethiopian national ID, so a passport number proves this person instead."
+              placeholder="P1234567"
+              error={errors.ownerPassportNumber?.message}
+              {...register("ownerPassportNumber")}
+            />
+          )}
+
           {savable && (
             <Group justify="flex-end">
               <Button
diff --git a/apps/edr-freight-web/portal/src/pages/settings/TabPowerOfAttorney.tsx b/apps/edr-freight-web/portal/src/pages/settings/TabPowerOfAttorney.tsx
index 63dc3b777..47dd7c3c5 100644
--- a/apps/edr-freight-web/portal/src/pages/settings/TabPowerOfAttorney.tsx
+++ b/apps/edr-freight-web/portal/src/pages/settings/TabPowerOfAttorney.tsx
@@ -42,18 +42,68 @@ import {
   type LicenseFileStatus,
 } from "@/services/companies.service";
 import FaydaVerifyPanel from "@/components/FaydaVerifyPanel";
+import { ControlledPhoneField, isValidPhone } from "@/components/PhoneField";
+import {
+  firstValidEmail,
+  firstValidPhone,
+  normalizeIdentityPhones,
+} from "@/pages/accounts/companyProfileForm/helpers";
 import { verifaydaService } from "@/services/verifayda.service";
 import RoleCard from "@/pages/settings/RoleCard";
 import type { ProfileResponse } from "@/types/profile";
 
-// The representative's name, email, phone and address all come from their
-// Fayda verification — a PoA is always an Ethiopian holding one — so the city
-// is the only detail this form owns.
-const schema = z.object({
-  poaLocation: z.string().optional(),
-});
+/** The representative's details that a Fayda verification may or may not own. */
+const POA_LABELS = {
+  poaName: "Representative's name",
+  poaEmail: "Representative's email",
+  poaPhone: "Representative's phone",
+} as const;
 
-type FormData = z.infer<typeof schema>;
+type PoaField = keyof typeof POA_LABELS;
+
+/**
+ * The representative's details.
+ *
+ * Optional here, not unrequired. Whatever their Fayda verification supplied is
+ * owned by the API and shown read-only, so a blanket `min(1)` would fail a form
+ * that is correct — but Fayda's email and phone claims are optional and
+ * routinely come back empty, and the API's own `REQUIRED_POA_FIELDS` demands
+ * all three once a representative is declared. So requiredness is decided per
+ * render, exactly as the wizard decides it: **a field is required iff there is
+ * an input on screen for it.** This form used to assume the verification always
+ * supplied everything and rendered no inputs at all, which left a company
+ * reported incomplete with nowhere to fix it.
+ */
+const buildSchema = (required: readonly PoaField[]) =>
+  z
+    .object({
+      poaName: z.string().optional(),
+      poaEmail: z
+        .string()
+        .optional()
+        .refine(
+          (v) => !v || z.string().email().safeParse(v).success,
+          "Invalid email address",
+        ),
+      poaPhone: z
+        .string()
+        .optional()
+        .refine((v) => !v || isValidPhone(v), "Enter a valid phone number"),
+      poaPassportNumber: z.string().optional(),
+      poaLocation: z.string().optional(),
+    })
+    .superRefine((d, ctx) => {
+      for (const key of required) {
+        if (d[key]?.trim()) continue;
+        ctx.addIssue({
+          code: "custom",
+          path: [key],
+          message: `${POA_LABELS[key]} is required`,
+        });
+      }
+    });
+
+type FormData = z.infer<ReturnType<typeof buildSchema>>;
 
 const LETTER_ACCEPT = ".pdf,.png,.jpg,.jpeg";
 
@@ -96,18 +146,63 @@ export default function TabPowerOfAttorney({
   const { view, viewer } = useFileViewer();
   const uploadInputRef = useRef<HTMLInputElement>(null);
 
+  // Fayda holds a phone as the national registry does, often a local number the
+  // form's E.164 validation would reject. Normalize on read, as the wizard does.
+  const identity = useMemo(
+    () => normalizeIdentityPhones(profile.identity),
+    [profile.identity],
+  );
+  const poa = identity?.poa;
+  const poaVerified = poa?.verified ?? false;
+
+  /**
+   * Which details the verification owns. Same test as the wizard's: presence is
+   * not enough for an email or a phone, because Fayda's claims are free text and
+   * one the schema would reject is not a claim an input can be hidden behind.
+   */
+  const locked = {
+    name: poaVerified && Boolean(poa?.name?.trim()),
+    email: poaVerified && Boolean(firstValidEmail(poa?.email)),
+    phone: poaVerified && Boolean(firstValidPhone(poa?.phone)),
+  };
+
+  const declaredYes = (identity?.poaDeclared ?? null) === "yes";
+  const passportAccepted = identity?.passportAccepted ?? false;
+  /**
+   * The person exists to describe. Before a verification lands there is nothing
+   * to attach details to — and asking for a name the verification is about to
+   * overwrite is the trap the wizard avoids by the same rule. A foreign company
+   * whose representative may hold no Fayda ID is the exception: the passport is
+   * the proof, so its details are typed from the start.
+   */
+  const established = declaredYes && (poaVerified || passportAccepted);
+
+  const requiredPoaFields: PoaField[] = [];
+  if (established) {
+    if (!locked.name) requiredPoaFields.push("poaName");
+    if (!locked.email) requiredPoaFields.push("poaEmail");
+    if (!locked.phone) requiredPoaFields.push("poaPhone");
+  }
+
   const defaultValues = useMemo(
-    (): FormData => ({ poaLocation: profile.poaLocation ?? "" }),
+    (): FormData => ({
+      poaName: profile.poaName ?? "",
+      poaEmail: profile.poaEmail ?? "",
+      poaPhone: profile.poaPhone ?? "",
+      poaPassportNumber: profile.identity?.poa.passportNumber ?? "",
+      poaLocation: profile.poaLocation ?? "",
+    }),
     [profile],
   );
 
   const {
     register,
+    control,
     handleSubmit,
     reset,
     formState: { errors, isDirty },
   } = useForm<FormData>({
-    resolver: zodResolver(schema),
+    resolver: zodResolver(buildSchema(requiredPoaFields)),
     values: defaultValues,
   });
 
@@ -133,12 +228,6 @@ export default function TabPowerOfAttorney({
   const requirePoa = profile.companyProfiles.some(
     (p) => p.type === "freight_forwarder",
   );
-  // No company types its representative's details — they come from the Fayda
-  // verification whatever the nationality, since a representative acts for the
-  // company inside Ethiopia either way. A PoA therefore exists exactly when one
-  // has been verified.
-  const identity = profile.identity;
-  const poaProvided = identity?.poa.verified ?? false;
   // Whether there is a representative at all is the company's own declaration,
   // held server-side — it decides whose identity the API gates on, so it is
   // never local state here.
@@ -155,9 +244,17 @@ export default function TabPowerOfAttorney({
 
   const mutation = useMutation({
     mutationFn: async (data: FormData) => {
-      // Every identity field except the city is written by the verification, so
-      // only the paper and the location are ever saved here.
-      const fields = { poaLocation: data.poaLocation || undefined };
+      // Whatever the verification did NOT supply is this form's to save, plus
+      // the paper. A field it owns is legitimately blank here (there is no
+      // input), and `|| undefined` keeps that blank out of the payload — the
+      // DTO's `@IsOptional()` skips null and undefined, never "".
+      const fields = {
+        poaName: data.poaName || undefined,
+        poaEmail: data.poaEmail || undefined,
+        poaPhone: data.poaPhone || undefined,
+        poaPassportNumber: data.poaPassportNumber || undefined,
+        poaLocation: data.poaLocation || undefined,
+      };
       // A fresh upload already stages the removal of every paper on file, so
       // the explicit removals only need applying when no replacement was
       // picked. Saving the details after it means the API sees the new paper.
@@ -355,15 +452,62 @@ export default function TabPowerOfAttorney({
 
         <form onSubmit={handleSubmit(onSubmit)}>
           <Stack gap="md">
-            {/* Name, email, phone and address all come from the Fayda
-                verification and are shown on the panel above. Only a company
-                whose representative may hold no Fayda ID still types a
-                location. */}
-            {declared === "yes" && !poaProvided && (
-              <Grid>
-                <Grid.Col span={6}>
+            {/* Whatever the verification supplied is on the panel above; only
+                what it left blank is asked for here. A foreign representative
+                who holds no Fayda ID proves themselves by passport instead —
+                the same either/or the onboarding wizard offers, which an
+                onboarded company can no longer reach. */}
+            {established && passportAccepted && !poaVerified && (
+              <TextInput
+                label="Representative's Passport Number"
+                description="Fayda is an Ethiopian national ID, so a passport number proves this person instead."
+                placeholder="P1234567"
+                error={errors.poaPassportNumber?.message}
+                {...register("poaPassportNumber")}
+              />
+            )}
+
+            {established && !locked.name && (
+              <TextInput
+                label="Representative's Name"
+                placeholder="Abebe Bikila"
+                error={errors.poaName?.message}
+                {...register("poaName")}
+              />
+            )}
+
+            {established && (!locked.email || !locked.phone) && (
+              <SimpleGrid
+                cols={{ base: 1, sm: !locked.email && !locked.phone ? 2 : 1 }}
+                spacing="md"
+              >
+                {!locked.email && (
                   <TextInput
-                    label="PoA Location"
+                    label="Representative's Email"
+                    type="email"
+                    placeholder="representative@company.com"
+                    error={errors.poaEmail?.message}
+                    {...register("poaEmail")}
+                  />
+                )}
+                {!locked.phone && (
+                  <ControlledPhoneField
+                    control={control}
+                    name="poaPhone"
+                    label="Representative's Phone"
+                  />
+                )}
+              </SimpleGrid>
+            )}
+
+            {/* The company's own statement of where the representative is
+                based — never Fayda's `poaAddress`, which the portal does not
+                send — so it stays typeable however well Fayda knows them. */}
+            {established && (
+              <Grid>
+                <Grid.Col span={{ base: 12, sm: 6 }}>
+                  <TextInput
+                    label="Representative's Location"
                     placeholder="City, Country"
                     error={errors.poaLocation?.message}
                     {...register("poaLocation")}
diff --git a/apps/edr-freight-web/portal/src/pages/settings/companyProfileSchema.test.ts b/apps/edr-freight-web/portal/src/pages/settings/companyProfileSchema.test.ts
new file mode 100644
index 000000000..1875aee1b
--- /dev/null
+++ b/apps/edr-freight-web/portal/src/pages/settings/companyProfileSchema.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+
+import { buildCompanyProfileSchema } from "./TabCompanyProfile";
+
+/**
+ * The two rules this schema exists to keep in step with onboarding: what counts
+ * as a VAT number, and who has to type their registration.
+ */
+const base = {
+  companyName: "Acme plc",
+  companyLocation: "Addis Ababa",
+  companyAddress: "",
+  tinNumber: "0012345678",
+  vatNumber: "0012345678",
+  region: "Addis Ababa",
+  zone: "Bole",
+  woreda: "03",
+  kebele: "07",
+  houseNo: "",
+};
+
+describe("buildCompanyProfileSchema", () => {
+  it("accepts a VAT number no Ethiopian format rule would allow", () => {
+    // The whole point of reusing onboarding's rule: a foreign company's VAT is
+    // its own tax authority's, and the stricter copy locked it out of the tab.
+    const parsed = buildCompanyProfileSchema(false).safeParse({
+      ...base,
+      vatNumber: "GB123456789",
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  it("still requires a VAT number", () => {
+    const parsed = buildCompanyProfileSchema(false).safeParse({
+      ...base,
+      vatNumber: "",
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it("does not require the registration block off an eTrade company", () => {
+    // It is read-only for them, so requiring it would fail a save on a field
+    // with no input to fix it.
+    const parsed = buildCompanyProfileSchema(false).safeParse({
+      ...base,
+      companyName: "",
+      region: "",
+      zone: "",
+      woreda: "",
+      kebele: "",
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  it("requires it of a company that types it by hand", () => {
+    const parsed = buildCompanyProfileSchema(true).safeParse({
+      ...base,
+      region: "",
+    });
+    expect(parsed.success).toBe(false);
+    expect(parsed.error?.issues.map((i) => i.path[0])).toContain("region");
+  });
+
+  it("leaves the house number optional either way", () => {
+    expect(
+      buildCompanyProfileSchema(true).safeParse({ ...base, houseNo: "" })
+        .success,
+    ).toBe(true);
+  });
+});

From 2f86557f6117f38c187e0294849069e82306c801 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 11:37:58 +0000
Subject: [PATCH 150/174] test(e2e): teach the eTrade mock to answer "no
 record"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every TIN resolved to the same canned company, so the premise of both manual
routes — eTrade holds nothing — could not be reached at all, and neither could
the dead end an ordinary company hits on a TIN with no trade licence.

The answer now follows the TIN's leading digit, so a spec picks its outcome by
picking its number and no per-spec stubbing is needed: 9… returns a
registration with no businesses (the co-operative / investor case, where the
API's resolveCompanyData finds no licence), 8… 404s the registration lookup
entirely, anything else behaves as before.
---
 e2e/freight/etrade-mock/server.js | 48 +++++++++++++++++++++++++++----
 1 file changed, 43 insertions(+), 5 deletions(-)

diff --git a/e2e/freight/etrade-mock/server.js b/e2e/freight/etrade-mock/server.js
index 95f43ded2..f146637a7 100644
--- a/e2e/freight/etrade-mock/server.js
+++ b/e2e/freight/etrade-mock/server.js
@@ -9,10 +9,30 @@
 // TLS_CERT_PATH/TLS_KEY_PATH before starting this — nothing shaped like a
 // key/cert is committed here.
 //
-// Every TIN resolves to the same canned company — these specs don't care
-// about per-TIN business logic, only that the lookup succeeds so the rest
-// of the company-info form (name, address, manager) auto-fills instead of
-// staying gated behind a "No matching business record" alert.
+// A TIN resolves to the same canned company whatever its digits, EXCEPT for
+// the two failure shapes the onboarding specs need — chosen by the TIN's
+// leading digit so a spec picks its outcome by picking its number, with no
+// per-spec stubbing and no state in this process:
+//
+//   1xxxxxxxxx (default)  registration + one business licence  → "Verified with eTrade"
+//   9xxxxxxxxx            registration, but `Businesses: []`   → the API's resolveCompanyData
+//                                                                returns businessInfo: null,
+//                                                                so /fetch-etrade-info 400s
+//                                                                with "couldn't find a
+//                                                                business license for this
+//                                                                TIN". This is the real
+//                                                                co-operative / foreign-
+//                                                                investor case: the TIN is
+//                                                                registered, the trade
+//                                                                licence is not.
+//   8xxxxxxxxx            404 on the registration lookup       → getCompanyInfoByTin throws,
+//                                                                same 400 to the portal by a
+//                                                                different route (eTrade knows
+//                                                                nothing about this TIN at all).
+//
+// Both failures reach the portal as a 400, which ETradeInfo renders as its
+// `notFound` branch: a red dead end for an ordinary company, and the blue
+// "that's expected" alert for one that types its registration.
 const https = require("node:https");
 const fs = require("node:fs");
 
@@ -25,6 +45,11 @@ const options = {
   ),
 };
 
+/** No trade licence on file for this TIN (a co-operative, a foreign investor). */
+const TIN_WITHOUT_LICENCE = "9";
+/** eTrade holds no registration whatsoever for this TIN. */
+const TIN_UNKNOWN = "8";
+
 function companyInfo(tin) {
   return {
     Tin: tin,
@@ -101,8 +126,21 @@ const server = https.createServer(options, (req, res) => {
     /^\/api\/Registration\/GetRegistrationInfoByTin\/([^/]+)\/en$/,
   );
   if (req.method === "GET" && regMatch) {
+    const tin = regMatch[1];
+
+    if (tin.startsWith(TIN_UNKNOWN)) {
+      res.writeHead(404).end();
+      return;
+    }
+
+    const info = companyInfo(tin);
+    // Registered, but holding no trade licence. The API reads `Businesses`
+    // rather than the HTTP status to decide this, so an empty array is the
+    // honest shape — not an error.
+    if (tin.startsWith(TIN_WITHOUT_LICENCE)) info.Businesses = [];
+
     res.writeHead(200, { "content-type": "application/json" });
-    res.end(JSON.stringify(companyInfo(regMatch[1])));
+    res.end(JSON.stringify(info));
     return;
   }
 

From 03b16b4ee8f8f458d0de1d9a53a9f59d6fbde67e Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 11:38:07 +0000
Subject: [PATCH 151/174] feat: add service type fitler

---
 .../pages/bookings/BookingRequestsPage.tsx    | 12 +++++++-
 .../pages/contracts/ContractRequestsPage.tsx  | 18 ++++++++++-
 .../backoffice/src/services/api.ts            |  7 +++++
 .../src/services/bookings.service.ts          |  4 +++
 .../src/services/contracts.service.ts         |  3 ++
 .../src/pages/bookings/BookingsListPage.tsx   | 29 +++++++++++++++++-
 .../src/pages/contracts/ContractsList.tsx     | 30 ++++++++++++++++++-
 .../portal/src/services/bookings.service.ts   |  2 ++
 .../portal/src/services/contracts.service.ts  |  2 ++
 9 files changed, 103 insertions(+), 4 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
index 8c2a3a912..d6819d940 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
@@ -130,6 +130,15 @@ export default function BookingRequestsPage() {
     [yardRefs],
   );
 
+  // Service-type options — same reference-data payload the booking form uses.
+  const { data: refData } = useQuery(
+    api.bookings.referenceData.queryOptions({ staleTime: 5 * 60_000 }),
+  );
+  const serviceTypeOptions = useMemo(
+    () => (refData?.service ?? []).map((s) => ({ value: s.id, label: s.name })),
+    [refData],
+  );
+
   // Deep links land here pre-filtered (?statuses=A,B&tradeDirection=IMPORT) —
   // the header's document-review alarm opens exactly the undecided requests
   // it is counting down for. No sync effect needed any more: controls.values
@@ -147,6 +156,7 @@ export default function BookingRequestsPage() {
         options: filterOptions(TRADE_DIRECTION_OPTIONS),
       },
       { key: "freightType", label: "Freight", type: "enum", multiple: false, options: FREIGHT_TYPE_OPTIONS },
+      { key: "serviceTypeId", label: "Service", type: "enum", multiple: false, options: serviceTypeOptions },
       { key: "paymentStatus", label: "Payment", type: "enum", multiple: false, options: PAYMENT_STATUS_OPTIONS, secondary: true },
       {
         // Wins over the `paymentStatus` filter above — the queue is by
@@ -172,7 +182,7 @@ export default function BookingRequestsPage() {
         toParams: dateRangeParams("scheduledFrom", "scheduledTo"),
       },
     ],
-    [filterOptions, yardOptions],
+    [filterOptions, yardOptions, serviceTypeOptions],
   );
 
   const controls = useFilters(bookingFilterDefs, { defaultSort: "createdAt:DESC", pageSize: 10 });
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
index cf87a1e1b..aa8b5ed8f 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/ContractRequestsPage.tsx
@@ -115,6 +115,15 @@ export default function ContractRequestsPage() {
     [yardRefs],
   );
 
+  // Service-type options — same reference-data payload the booking form uses.
+  const { data: refData } = useQuery(
+    api.bookings.referenceData.queryOptions({ staleTime: 5 * 60_000 }),
+  );
+  const serviceTypeOptions = useMemo(
+    () => (refData?.service ?? []).map((s) => ({ value: s.id, label: s.name })),
+    [refData],
+  );
+
   // Static shape only (no facet counts) — this is what useFilters needs to
   // parse the URL and build API params. Counts are attached separately below,
   // for rendering only, once the summary query (which itself depends on
@@ -143,6 +152,13 @@ export default function ContractRequestsPage() {
         multiple: false,
         options: FREIGHT_TYPE_OPTIONS,
       },
+      {
+        key: "serviceTypeId",
+        label: "Service",
+        type: "enum",
+        multiple: false,
+        options: serviceTypeOptions,
+      },
       {
         key: "paymentCurrency",
         label: "Currency",
@@ -170,7 +186,7 @@ export default function ContractRequestsPage() {
         toParams: ({ v }) => ({ originYardId: v[0], destinationYardId: v[1] }),
       },
     ],
-    [filterOptions, yardOptions],
+    [filterOptions, yardOptions, serviceTypeOptions],
   );
 
   const controls = useFilters(filterDefs, {
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 8d61698d1..b68589e34 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -2741,6 +2741,13 @@ export const api = {
       ({ id }) => QUERY_KEYS.BOOKINGS.byId(id),
     ),
 
+    referenceData: endpoint<void, Freight.BookingReferenceData>(
+      "bookings",
+      "referenceData",
+      () => bookingsService.getReferenceData() as Promise<Freight.BookingReferenceData>,
+      () => ["bookings", "reference-data"],
+    ),
+
     remove: endpoint<{ id: string }, void>("bookings", "remove", ({ id }) =>
       bookingsService.remove(id),
     ),
diff --git a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
index dead9c520..c6ba796d2 100644
--- a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
@@ -19,6 +19,8 @@ export interface BookingListFilter {
   /** Bookings drawn down under this contract (contract detail's Shipments tab). */
   contractId?: string;
   freightType?: string;
+  /** Service type (rule-engine service_types.id). */
+  serviceTypeId?: string;
   /** ONE_TIME | GENERAL_CONTRACT — the booking-kind tab filter. */
   bookingType?: string;
   /** 'true' → customs bookings, 'false' → self-clearance (non-customs). */
@@ -142,6 +144,7 @@ export const bookingsService = {
       if (filter.pageSize != null) params.pageSize = filter.pageSize;
       if (filter.companyId) params.companyId = filter.companyId;
       if (filter.freightType) params.freightType = filter.freightType;
+      if (filter.serviceTypeId) params.serviceTypeId = filter.serviceTypeId;
       if (filter.bookingType) params.bookingType = filter.bookingType;
       if (filter.tradeDirection) params.tradeDirection = filter.tradeDirection;
       if (filter.paymentCurrency) params.paymentCurrency = filter.paymentCurrency;
@@ -176,6 +179,7 @@ export const bookingsService = {
       if (filter.companyId) params.companyId = filter.companyId;
       if (filter.contractId) params.contractId = filter.contractId;
       if (filter.freightType) params.freightType = filter.freightType;
+      if (filter.serviceTypeId) params.serviceTypeId = filter.serviceTypeId;
       if (filter.bookingType) params.bookingType = filter.bookingType;
       if (filter.tradeDirection) params.tradeDirection = filter.tradeDirection;
       if (filter.paymentCurrency) params.paymentCurrency = filter.paymentCurrency;
diff --git a/apps/edr-freight-web/backoffice/src/services/contracts.service.ts b/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
index 01dbadac7..8c11af23d 100644
--- a/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
@@ -13,6 +13,8 @@ export interface ContractListFilter {
   tab?: string;
   companyId?: string;
   freightType?: string;
+  /** Service type (rule-engine service_types.id). */
+  serviceTypeId?: string;
   tradeDirection?: string;
   contractKind?: string;
   paymentCurrency?: string;
@@ -171,6 +173,7 @@ function buildListParams(filter?: ContractListFilter) {
     if (filter.sortOrder) params.sortOrder = filter.sortOrder;
     if (filter.companyId) params.companyId = filter.companyId;
     if (filter.freightType) params.freightType = filter.freightType;
+    if (filter.serviceTypeId) params.serviceTypeId = filter.serviceTypeId;
     if (filter.tradeDirection) params.tradeDirection = filter.tradeDirection;
     if (filter.contractKind) params.contractKind = filter.contractKind;
     if (filter.paymentCurrency) params.paymentCurrency = filter.paymentCurrency;
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
index 175aec08f..925569be1 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/BookingsListPage.tsx
@@ -374,6 +374,16 @@ export default function BookingsListPage() {
   const [debouncedQuery] = useDebouncedValue(query, 300);
   const [typeFilter, setTypeFilter] = useState<string | null>(null);
   const [freightFilter, setFreightFilter] = useState<string | null>(null);
+  const [serviceFilter, setServiceFilter] = useState<string | null>(null);
+
+  // Service-type options — same reference-data payload the booking form uses.
+  const { data: refData } = useQuery(
+    api.bookings.referenceData.queryOptions({ staleTime: 5 * 60_000 }),
+  );
+  const serviceTypeOptions = useMemo(
+    () => (refData?.service ?? []).map((s) => ({ value: s.id, label: s.name })),
+    [refData],
+  );
   const [sort, setSort] = useState<string>("createdAt:DESC");
   const [createdFrom, setCreatedFrom] = useState<string>("");
   const [createdTo, setCreatedTo] = useState<string>("");
@@ -395,10 +405,11 @@ export default function BookingsListPage() {
   };
 
   const hasExtraFilters =
-    !!typeFilter || !!freightFilter || !!createdFrom || !!createdTo;
+    !!typeFilter || !!freightFilter || !!serviceFilter || !!createdFrom || !!createdTo;
   const clearExtraFilters = () => {
     setTypeFilter(null);
     setFreightFilter(null);
+    setServiceFilter(null);
     setCreatedFrom("");
     setCreatedTo("");
     resetPage();
@@ -410,6 +421,7 @@ export default function BookingsListPage() {
       assignedToSchedule,
       bookingType: typeFilter ?? undefined,
       freightType: freightFilter ?? undefined,
+      serviceTypeId: serviceFilter ?? undefined,
       createdFrom: createdFrom || undefined,
       // include the whole selected end day
       createdTo: createdTo ? `${createdTo}T23:59:59.999Z` : undefined,
@@ -425,6 +437,7 @@ export default function BookingsListPage() {
       assignedToSchedule,
       typeFilter,
       freightFilter,
+      serviceFilter,
       createdFrom,
       createdTo,
       debouncedQuery,
@@ -852,6 +865,20 @@ export default function BookingsListPage() {
                 style={{ width: 150 }}
                 aria-label="Filter by cargo type"
               />
+              <Select
+                placeholder="Any service"
+                data={serviceTypeOptions}
+                value={serviceFilter}
+                onChange={(v) => {
+                  setServiceFilter(v);
+                  resetPage();
+                }}
+                clearable
+                radius="md"
+                comboboxProps={{ withinPortal: true }}
+                style={{ width: 190 }}
+                aria-label="Filter by service type"
+              />
               <Select
                 data={SORT_OPTIONS.map((o) => ({
                   value: o.value,
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/ContractsList.tsx b/apps/edr-freight-web/portal/src/pages/contracts/ContractsList.tsx
index f465ca849..f32890a14 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/ContractsList.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/ContractsList.tsx
@@ -71,6 +71,16 @@ export default function ContractsList() {
   const [disclaimerOpen, setDisclaimerOpen] = useState(false);
   const [freightFilter, setFreightFilter] = useState<string | null>(null);
   const [kindFilter, setKindFilter] = useState<string | null>(null);
+  const [serviceFilter, setServiceFilter] = useState<string | null>(null);
+
+  // Service-type options — same reference-data payload the contract form uses.
+  const { data: refData } = useQuery(
+    api.bookings.referenceData.queryOptions({ staleTime: 5 * 60_000 }),
+  );
+  const serviceTypeOptions = useMemo(
+    () => (refData?.service ?? []).map((s) => ({ value: s.id, label: s.name })),
+    [refData],
+  );
   const [createdFrom, setCreatedFrom] = useState<string>("");
   const [createdTo, setCreatedTo] = useState<string>("");
   const [expanded, setExpanded] = useState<Set<string>>(new Set());
@@ -96,10 +106,11 @@ export default function ContractsList() {
   const resetPage = () =>
     setPagination({ pageIndex: 0, pageSize: pagination.pageSize });
   const hasExtraFilters =
-    !!freightFilter || !!kindFilter || !!createdFrom || !!createdTo;
+    !!freightFilter || !!kindFilter || !!serviceFilter || !!createdFrom || !!createdTo;
   const clearExtraFilters = () => {
     setFreightFilter(null);
     setKindFilter(null);
+    setServiceFilter(null);
     setCreatedFrom("");
     setCreatedTo("");
     resetPage();
@@ -109,6 +120,7 @@ export default function ContractsList() {
     () => ({
       contractKind: kindFilter ?? undefined,
       freightType: freightFilter ?? undefined,
+      serviceTypeId: serviceFilter ?? undefined,
       createdFrom: createdFrom || undefined,
       createdTo: createdTo ? `${createdTo}T23:59:59.999Z` : undefined,
       // Server-side free-text search (contract reference, company name).
@@ -121,6 +133,7 @@ export default function ContractsList() {
     [
       kindFilter,
       freightFilter,
+      serviceFilter,
       createdFrom,
       createdTo,
       debouncedQuery,
@@ -322,6 +335,21 @@ export default function ContractsList() {
               styles={{ input: { height: 42 } }}
               aria-label="Filter by cargo type"
             />
+            <Select
+              placeholder="Any service"
+              data={serviceTypeOptions}
+              value={serviceFilter}
+              onChange={(v) => {
+                setServiceFilter(v);
+                resetPage();
+              }}
+              clearable
+              radius="md"
+              comboboxProps={{ withinPortal: true }}
+              style={{ width: 180 }}
+              styles={{ input: { height: 42 } }}
+              aria-label="Filter by service type"
+            />
             <TextInput
               type="date"
               value={createdFrom}
diff --git a/apps/edr-freight-web/portal/src/services/bookings.service.ts b/apps/edr-freight-web/portal/src/services/bookings.service.ts
index b196ed968..840251729 100644
--- a/apps/edr-freight-web/portal/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/portal/src/services/bookings.service.ts
@@ -182,6 +182,8 @@ export interface BookingListFilter {
   bookingType?: string;
   /** CONTAINER or BULK. */
   freightType?: string;
+  /** Service type (rule-engine service_types.id). */
+  serviceTypeId?: string;
   /** IMPORT / EXPORT / DOMESTIC. */
   tradeDirection?: string;
   /** Narrow to a single operational profile (importer/exporter/freight_forwarder). */
diff --git a/apps/edr-freight-web/portal/src/services/contracts.service.ts b/apps/edr-freight-web/portal/src/services/contracts.service.ts
index 3842296ef..4e9cb79de 100644
--- a/apps/edr-freight-web/portal/src/services/contracts.service.ts
+++ b/apps/edr-freight-web/portal/src/services/contracts.service.ts
@@ -88,6 +88,8 @@ export interface ContractListFilter {
   contractKind?: string;
   /** CONTAINER or BULK. */
   freightType?: string;
+  /** Service type (rule-engine service_types.id). */
+  serviceTypeId?: string;
   /** IMPORT / EXPORT / DOMESTIC. */
   tradeDirection?: string;
   companyProfileId?: string;

From 6469c7fa52842e63fbf7eff48027a9020b0176ce Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 11:38:37 +0000
Subject: [PATCH 152/174] test(e2e): cover every onboarding route across portal
 and backoffice
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five journeys, one file each, every one of them crossing from the portal into
the backoffice and cross-checking the database rather than the screen:

- ethiopian     eTrade verified, Fayda, approved, contract wizard reachable —
                including the dead end a TIN with no trade licence is for an
                ordinary company
- investor      foreign investment licence: nothing on file at eTrade, typed
                registration, passport identity, per-role licence still owed,
                and the backoffice's manual-entry badge and banner
- cooperative   no foreign option, no freight-forwarder role, the co-operative
                document set, no licence cards, its own badge and banner
- switch_back   settings → switch to eTrade → registration cleared, company
                pending, wizard reopened on the company step → re-run through
                eTrade → the flag is gone from the backoffice
- guards        the refused combinations, and the mid-wizard un-tick that has
                to clear the typed registration

Replaces the old onboarding.cy.ts (removed a commit earlier by accident of a
staged deletion): it drove a wizard shape that no longer exists — Fayda before
the company step, a "Personnel" step — so it could only ever have been red.

Notes for whoever edits these next. Attach files to the FIRST empty dropzone,
never by index — SmartFileInput removes the input once a file is on it. Resolve
the company from the database after any cross-origin hop, never from module
state: Cypress re-evaluates the spec bundle and Date.now() with it, which is
what latestJourney's run-stamp cutoff is for. And the deliberate eTrade 400 is
ignored as an uncaught exception — the portal handles that outcome on screen
but leaves the rejected request unhandled at the promise level.
---
 .../cypress/e2e/flows/onboarding-utils.ts     | 385 ++++++++++++++++++
 .../e2e/flows/onboarding_cooperative.cy.ts    | 161 ++++++++
 .../e2e/flows/onboarding_ethiopian.cy.ts      | 180 ++++++++
 .../cypress/e2e/flows/onboarding_guards.cy.ts | 171 ++++++++
 .../e2e/flows/onboarding_investor.cy.ts       | 123 ++++++
 .../e2e/flows/onboarding_switch_back.cy.ts    | 158 +++++++
 6 files changed, 1178 insertions(+)
 create mode 100644 e2e/freight/cypress/e2e/flows/onboarding-utils.ts
 create mode 100644 e2e/freight/cypress/e2e/flows/onboarding_cooperative.cy.ts
 create mode 100644 e2e/freight/cypress/e2e/flows/onboarding_ethiopian.cy.ts
 create mode 100644 e2e/freight/cypress/e2e/flows/onboarding_guards.cy.ts
 create mode 100644 e2e/freight/cypress/e2e/flows/onboarding_investor.cy.ts
 create mode 100644 e2e/freight/cypress/e2e/flows/onboarding_switch_back.cy.ts

diff --git a/e2e/freight/cypress/e2e/flows/onboarding-utils.ts b/e2e/freight/cypress/e2e/flows/onboarding-utils.ts
new file mode 100644
index 000000000..93d193ac7
--- /dev/null
+++ b/e2e/freight/cypress/e2e/flows/onboarding-utils.ts
@@ -0,0 +1,385 @@
+/**
+ * Shared machinery for the onboarding journeys (portal → backoffice).
+ *
+ * The wizard's five form steps are `company → owner → representation →
+ * contact → documents`, preceded by the nationality/role phase. Three routes
+ * run through them:
+ *
+ *   ordinary   eTrade answers for the TIN; the registration is read-only.
+ *   investor   a foreign company on an Investment Commission licence — eTrade
+ *              holds nothing, the registration is typed, the per-role business
+ *              licence is still owed.
+ *   co-op      a union or farm — eTrade holds nothing, the registration is
+ *              typed, and no business licence exists to ask for.
+ *
+ * The eTrade mock picks its answer from the TIN's leading digit (see
+ * etrade-mock/server.js), so a spec chooses "verified" or "nothing on file" by
+ * choosing its number — `etradeTin()` / `noLicenceTin()` / `unknownTin()`.
+ */
+
+/**
+ * Every manual-route journey deliberately looks up a TIN eTrade holds nothing
+ * for, and the API answers 400. The portal handles that outcome on screen (the
+ * "nothing on file" alert is the whole point) but leaves the rejected request
+ * unhandled at the promise level, and Cypress fails a test on any unhandled
+ * rejection from the app. Ignored here rather than per spec: it is the expected
+ * response to a request these journeys make on purpose, in every one of them.
+ *
+ * Narrow on purpose — only the 400. A 500, or anything else the app throws,
+ * still fails the test.
+ */
+Cypress.on("uncaught:exception", (err) => {
+  if (/Request failed with status code 400/.test(err.message)) return false;
+  return true;
+});
+
+const apiUrl = () => Cypress.env("apiUrl") as string;
+
+export const portalUrl = () => Cypress.env("portalUrl") as string;
+
+/* ------------------------------------------------------------------ */
+/* Field helpers                                                       */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Fill a labelled Mantine input (label[for] → input id).
+ *
+ * The input is resolved fresh for every action rather than captured once.
+ * Each wizard step persists and re-seeds asynchronously, and when a field
+ * remounts Mantine mints a NEW generated id — so a subject captured a command
+ * earlier can already be stale. Going label → for → element each time always
+ * addresses what is on the page now.
+ */
+export function fill(label: string | RegExp, value: string) {
+  const input = () =>
+    cy
+      .contains("label", label)
+      .invoke("attr", "for")
+      .then((id) => cy.get(`[id="${id}"]`));
+
+  input().clear({ force: true });
+  input().type(value, { force: true });
+}
+
+/**
+ * Fill an input that has no <label> — the company step renders TIN and VAT
+ * inside StepSection cards (the heading is the card's title, not a label), and
+ * both share the "0012345678" placeholder, so they are addressable only by
+ * aria-label.
+ */
+export function fillAria(ariaSelector: string, value: string) {
+  const selector = `.mantine-Modal-content ${ariaSelector}`;
+  cy.get(selector).clear({ force: true });
+  cy.get(selector).type(value, { force: true });
+}
+
+/** The wizard's phone inputs (react-phone-number-input, type=tel). */
+export function fillPhone(index: number, national: string) {
+  const selector = '.mantine-Modal-content input[type="tel"]';
+  cy.get(selector).eq(index).clear({ force: true });
+  cy.get(selector).eq(index).type(national, { force: true });
+}
+
+/** The wizard's own Continue / Submit button (never the page's). */
+export function wizardClick(label: string | RegExp) {
+  cy.get(".mantine-Modal-content").contains("button", label).click();
+}
+
+/* ------------------------------------------------------------------ */
+/* Identities                                                          */
+/* ------------------------------------------------------------------ */
+
+/** A TIN eTrade answers for: registration + one business licence. */
+export const etradeTin = (stamp: number) => `1${String(stamp).slice(-9)}`;
+/** A TIN eTrade knows, but which holds no trade licence (co-op / investor). */
+export const noLicenceTin = (stamp: number) => `9${String(stamp).slice(-9)}`;
+/** A TIN eTrade has never heard of at all. */
+export const unknownTin = (stamp: number) => `8${String(stamp).slice(-9)}`;
+/** VAT is 10–11 digits and must not collide with the TIN. */
+export const vatNumber = (stamp: number) => `2${String(stamp + 7).slice(-9)}`;
+
+export const SIGNUP_PASSWORD = "Password@e2e1";
+
+export interface Signup {
+  email: string;
+  /** Ethiopian mobile, national format (9 + 8 digits). */
+  phoneNational: string;
+}
+
+/** A unique signup identity for this run, namespaced per journey. */
+export function signupIdentity(prefix: string, stamp: number): Signup {
+  return {
+    email: `e2e.${prefix}.${stamp}@example.com`,
+    phoneNational: `9${String(stamp).slice(-8)}`,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Journey steps                                                       */
+/* ------------------------------------------------------------------ */
+
+/**
+ * /signup → OTP (read from the DB; delivery is off in e2e) → signed in on
+ * /portal with the onboarding wizard already open on the nationality step.
+ */
+export function signupCustomer(who: Signup, firstName = "Onboard") {
+  cy.visit(`${portalUrl()}/signup`);
+
+  fill(/^First name/, firstName);
+  fill(/^Last name/, "Tester");
+  fill(/^Email/, who.email);
+  cy.get('input[type="tel"]').first().type(who.phoneNational, { force: true });
+  fill(/^Password/, SIGNUP_PASSWORD);
+  fill(/^Confirm password/, SIGNUP_PASSWORD);
+  cy.contains("button", "Continue").click();
+
+  cy.contains("Verify", { timeout: 15000 }).should("be.visible");
+  cy.getOtp(who.email).then((otp) => cy.typeOtp(otp));
+  cy.contains("button", "Verify & create account").click();
+
+  cy.location("pathname", { timeout: 20000 }).should("eq", "/portal");
+  cy.contains("Where is your company registered?", { timeout: 15000 }).should(
+    "be.visible",
+  );
+}
+
+/**
+ * Fill the "Registration details" block the manual routes type by hand. Region
+ * is a Mantine Select; the rest are plain inputs.
+ */
+export function typeRegistration(companyName: string) {
+  fill(/^Company Name/, companyName);
+  cy.mantineSelect("Region", "Addis Ababa");
+  fill(/^Zone/, "Zone 1");
+  fill(/^Woreda/, "Woreda 1");
+  fill(/^Kebele/, "Kebele 1");
+}
+
+/**
+ * Attach a PDF to the next empty dropzone on the documents step.
+ *
+ * Not positional: SmartFileInput swaps its dropzone for the file row once
+ * something is attached, so the input disappears from the DOM and every later
+ * index shifts under you. "The first one still asking for a file" is the only
+ * stable address, and it walks the step in render order — company documents
+ * first, then one card per operational profile.
+ */
+export function attachNextFile() {
+  cy.get('.mantine-Modal-content input[type="file"]')
+    .first()
+    .selectFile("cypress/fixtures/docs/license.pdf", { force: true });
+}
+
+/**
+ * Drive the whole investor wizard, signup included, and submit it.
+ *
+ * Shared because two specs need the same customer sitting on the far side of
+ * onboarding: the one that is about the journey, and the one that is about
+ * what happens afterwards. Driving the real UI rather than posting the
+ * equivalent API calls keeps the second spec honest — it starts from a company
+ * the product itself produced.
+ *
+ * `beforeSubmit` runs on the documents step, with everything attached and the
+ * submit button still unpressed: the one place a caller can assert about a
+ * state that does not survive submission.
+ */
+export function completeInvestorOnboarding(
+  who: Signup,
+  stamp: number,
+  opts: { companyName?: string; beforeSubmit?: () => void } = {},
+) {
+  const companyName = opts.companyName ?? `E2E Investor Holdings ${stamp}`;
+
+  signupCustomer(who, "Investor");
+
+  cy.contains("button", "Foreign Company").click();
+  cy.contains("We operate on a foreign investment licence").click();
+  cy.contains("button", "Importer").click();
+  wizardClick("Continue");
+
+  cy.contains("Confirm your VAT number", { timeout: 20000 }).should(
+    "be.visible",
+  );
+  fillAria('[aria-label^="TIN Number"]', noLicenceTin(stamp));
+  cy.contains("Nothing on file at eTrade for this TIN", {
+    timeout: 20000,
+  }).should("be.visible");
+  typeRegistration(companyName);
+  fillAria('[aria-label="VAT Number"]', vatNumber(stamp));
+  wizardClick("Continue");
+
+  // No licence, so no eTrade manager: every owner field is typed, and the
+  // "your licence listed no manager" hint has no business appearing.
+  cy.contains("Company Owner", { timeout: 20000 }).should("be.visible");
+  cy.contains("Your eTrade licence didn't list a manager").should("not.exist");
+  fill(/^Owner's Name/, "Investor Owner");
+  fill(/^Owner's Email/, `owner.${stamp}@example.com`);
+  fillPhone(0, "911234570");
+  wizardClick("Continue");
+
+  cy.contains("Does anyone hold power of attorney for this company?", {
+    timeout: 20000,
+  }).should("be.visible");
+  cy.contains("button", "No, the owner acts for us").click();
+  // Identity is not proven yet, so the step must hold. Asserted as "we did not
+  // advance" rather than on the alert text: answering the declaration refetches
+  // the profile, which re-seeds the form, and the form's watch subscription
+  // clears the alert on any value change — so the message is real but lives for
+  // a few milliseconds.
+  wizardClick("Continue");
+  cy.contains("Who Acts For You").should("be.visible");
+  cy.contains("Contact Person").should("not.exist");
+  // The alternative a foreign company gets and an Ethiopian one does not.
+  cy.contains("Use a passport instead").click();
+  fill(/Passport Number/, `P${String(stamp).slice(-7)}`);
+  wizardClick("Continue");
+
+  cy.contains("Contact Person", { timeout: 20000 }).should("be.visible");
+  fill(/^Name$/, "Investor Contact");
+  fillPhone(0, "911234571");
+  wizardClick("Continue");
+
+  cy.contains("Upload Importer Business license file(s)", {
+    timeout: 20000,
+  }).should("be.visible");
+  attachNextFile();
+  attachNextFile();
+  opts.beforeSubmit?.();
+  wizardClick("Submit for review");
+  cy.contains("You're all set", { timeout: 30000 }).should("be.visible");
+}
+
+/* ------------------------------------------------------------------ */
+/* Database + API                                                      */
+/* ------------------------------------------------------------------ */
+
+export interface CompanyRow {
+  id: string;
+  name: string;
+  status: string;
+  nationality: string | null;
+  attributes: Record<string, unknown> | null;
+  licence_number: string | null;
+  region: string | null;
+  etrade_phone: string | null;
+  onboarding_step: string | null;
+  onboarding_completed: boolean;
+  email: string;
+}
+
+const COMPANY_SQL = `
+  SELECT c.id, c.name, c.status, c.nationality, c.attributes,
+         c.licence_number, c.region, c.etrade_phone,
+         ep.onboarding_step, ep.onboarding_completed, u.email
+    FROM freight.companies c
+    JOIN freight.external_profiles ep ON ep.company_id = c.id
+    JOIN iam.users u ON u.id = ep.user_id`;
+
+/** The company behind one signup email. */
+export function companyByEmail(email: string) {
+  return cy
+    .task<{ rows: CompanyRow[] }>("db:query", {
+      sql: `${COMPANY_SQL} WHERE u.email = $1`,
+      params: [email],
+    })
+    .then(({ rows }) => {
+      expect(rows, `company for ${email}`).to.have.length(1);
+      return cy.wrap(rows[0], { log: false });
+    });
+}
+
+/**
+ * The most recent journey of one kind, resolved from the DB rather than from
+ * module state: Cypress re-evaluates the spec bundle on every cross-origin
+ * visit, so anything held in a module variable is gone by the backoffice test.
+ */
+export function latestJourney(emailPrefix: string) {
+  // Scoped to THIS cypress run. `run:stamp` is minted by the node plugin, which
+  // outlives the bundle re-evaluation a cross-origin visit causes — unlike
+  // anything held in module state. Without the cutoff a journey that failed
+  // mid-way would silently hand the backoffice tests a previous run's company
+  // and pass on it.
+  return cy.task<string>("run:stamp", null, { log: false }).then((runStamp) =>
+    cy
+      .task<{ rows: CompanyRow[] }>("db:query", {
+        sql: `${COMPANY_SQL}
+               WHERE u.email LIKE $1
+                 AND c.created_at >= to_timestamp($2::bigint / 1000.0)
+               ORDER BY c.created_at DESC LIMIT 1`,
+        params: [`e2e.${emailPrefix}.%`, runStamp],
+      })
+      .then(({ rows }) => {
+        expect(rows, `journey for e2e.${emailPrefix}.* in this run`).to.have.length(
+          1,
+        );
+        return cy.wrap(rows[0], { log: false });
+      }),
+  );
+}
+
+/** A portal access token for a customer account. */
+export function portalToken(email: string, password = SIGNUP_PASSWORD) {
+  return cy.apiLogin(email, password, "portal").then((body) => body.token);
+}
+
+/** cy.request against the freight API with a bearer token. */
+export function apiRequest(
+  token: string,
+  method: "GET" | "POST" | "PATCH",
+  path: string,
+  body?: Record<string, unknown>,
+  failOnStatusCode = true,
+) {
+  return cy.request({
+    method,
+    url: `${apiUrl()}${path}`,
+    headers: { Authorization: `Bearer ${token}` },
+    body,
+    failOnStatusCode,
+  });
+}
+
+/* ------------------------------------------------------------------ */
+/* Backoffice                                                          */
+/* ------------------------------------------------------------------ */
+
+/** Open a customer's detail page from the backoffice list, by company name. */
+export function openCustomer(companyName: string) {
+  cy.visit("/dashboard/customers");
+  cy.get('input[placeholder*="Search by company"]').type(companyName);
+  cy.contains(companyName, { timeout: 15000 }).click();
+}
+
+/**
+ * Approve the pending role profile on the open customer page. Once active the
+ * row's action flips to "Suspend", which is what proves the write landed.
+ */
+export function approveFirstProfile() {
+  cy.contains("button", "Approve", { timeout: 15000 }).click();
+  cy.contains("button", "Suspend", { timeout: 15000 }).should("be.visible");
+}
+
+/** Assert the role profile went active and the company with it. */
+export function expectProfileActive(companyName: string, type = "importer") {
+  return cy
+    .task<{
+      rows: Array<{
+        status: string;
+        reference: string | null;
+        company_status: string;
+      }>;
+    }>("db:query", {
+      sql: `SELECT p.status, p.reference, c.status AS company_status
+              FROM freight.company_profiles p
+              JOIN freight.companies c ON c.id = p.company_id
+             WHERE c.name = $1 AND p.type = $2`,
+      params: [companyName, type],
+    })
+    .then(({ rows }) => {
+      expect(rows, `${type} profile`).to.have.length(1);
+      expect(rows[0].status).to.eq("active");
+      expect(rows[0].reference, "minted reference").to.be.a("string").and.not.be
+        .empty;
+      expect(rows[0].company_status).to.eq("active");
+    });
+}
diff --git a/e2e/freight/cypress/e2e/flows/onboarding_cooperative.cy.ts b/e2e/freight/cypress/e2e/flows/onboarding_cooperative.cy.ts
new file mode 100644
index 000000000..d94c12b58
--- /dev/null
+++ b/e2e/freight/cypress/e2e/flows/onboarding_cooperative.cy.ts
@@ -0,0 +1,161 @@
+/**
+ * A co-operative union or farm: a TIN, but no business licence at all.
+ *
+ * It reaches the same typed-registration route as a foreign investor and the
+ * same backoffice flag, and differs from it in three ways the wizard has to
+ * enforce rather than merely explain — it is always Ethiopian, it cannot hold
+ * the freight-forwarder role, and it owes no per-role business licence. Its own
+ * document set stands in for the trade licence.
+ *
+ * One journey across both apps; retries off (see onboarding_ethiopian.cy.ts).
+ */
+
+import { completeFaydaVerification } from "./import-utils";
+import {
+  apiRequest,
+  attachNextFile,
+  companyByEmail,
+  fill,
+  fillAria,
+  fillPhone,
+  latestJourney,
+  noLicenceTin,
+  openCustomer,
+  portalToken,
+  signupCustomer,
+  signupIdentity,
+  typeRegistration,
+  vatNumber,
+  wizardClick,
+} from "./onboarding-utils";
+
+const stamp = Date.now();
+const who = signupIdentity("coop", stamp);
+
+describe("onboarding — co-operative union or farm", { retries: 0 }, () => {
+  it("types its registration, owes no business licence, and submits", () => {
+    signupCustomer(who, "Cooperative");
+
+    // Before the box: both nationalities and all three roles are on offer.
+    cy.contains("button", "Foreign Company").should("be.visible");
+    cy.contains("button", "Freight Forwarder").should("be.visible");
+
+    cy.contains("We're a co-operative union or farm").click();
+
+    // A co-op is registered in Ethiopia by the co-operative promotion agency,
+    // holds no licence, and cannot forward freight — so none of those choices
+    // are offered rather than refused later by the API.
+    cy.contains("button", "Foreign Company").should("not.exist");
+    cy.contains("button", "Freight Forwarder").should("not.exist");
+    cy.contains("We operate on a foreign investment licence").should("not.exist");
+
+    cy.contains("button", "Importer").click();
+    wizardClick("Continue");
+
+    // ── Company step ────────────────────────────────────────────────────
+    cy.contains("Confirm your VAT number", { timeout: 20000 }).should(
+      "be.visible",
+    );
+    fillAria('[aria-label^="TIN Number"]', noLicenceTin(stamp));
+    cy.contains("Nothing on file at eTrade for this TIN", {
+      timeout: 20000,
+    }).should("be.visible");
+
+    typeRegistration(`E2E Farmers Union ${stamp}`);
+    fillAria('[aria-label="VAT Number"]', vatNumber(stamp));
+    wizardClick("Continue");
+
+    // ── Owner step ──────────────────────────────────────────────────────
+    cy.contains("Company Owner", { timeout: 20000 }).should("be.visible");
+    fill(/^Owner's Name/, "Union Chairperson");
+    fill(/^Owner's Email/, `chair.${stamp}@example.com`);
+    fillPhone(0, "911234572");
+    wizardClick("Continue");
+
+    // ── Representation step ─────────────────────────────────────────────
+    cy.contains("Does anyone hold power of attorney for this company?", {
+      timeout: 20000,
+    }).should("be.visible");
+    cy.contains("button", "No, the owner acts for us").click();
+
+    // Ethiopian, so Fayda is the only route — the passport alternative belongs
+    // to foreign companies.
+    cy.contains("Use a passport instead").should("not.exist");
+    completeFaydaVerification("owner");
+    cy.reload();
+    cy.get(".mantine-Modal-content", { timeout: 30000 }).within(() => {
+      cy.contains("Fayda verified").should("be.visible");
+    });
+    wizardClick("Continue");
+
+    // ── Contact step ────────────────────────────────────────────────────
+    cy.contains("Contact Person", { timeout: 20000 }).should("be.visible");
+    fill(/^Name$/, "Union Contact");
+    fillPhone(0, "911234573");
+    wizardClick("Continue");
+
+    // ── Documents step ──────────────────────────────────────────────────
+    // The co-operative set replaces the nationality one, and the per-role
+    // licence cards are not rendered at all — offering a slot nothing can fill
+    // reads as an unfinishable step.
+    cy.contains("Upload Documents", { timeout: 20000 }).should("be.visible");
+    cy.contains("Upload Importer Business license file(s)").should("not.exist");
+    cy.get('.mantine-Modal-content input[type="file"]').should(
+      "have.length",
+      1,
+    );
+
+    portalToken(who.email).then((token) =>
+      apiRequest(token, "GET", "/api/companies/onboarding/requirements").then(
+        (res) => {
+          expect(res.body.data.documentSettingCode).to.eq(
+            "company_onboarding_documents_cooperative",
+          );
+          expect(res.body.data.cooperative).to.eq(true);
+          expect(res.body.data.investorLicence).to.eq(false);
+          // The requirement is lifted, not merely hidden on screen.
+          const outstanding: string[] = res.body.data.outstanding;
+          expect(
+            outstanding.filter((o) => /business license/i.test(o)),
+            "no licence is owed",
+          ).to.have.length(0);
+        },
+      ),
+    );
+
+    attachNextFile();
+    wizardClick("Submit for review");
+    cy.contains("You're all set", { timeout: 30000 }).should("be.visible");
+
+    companyByEmail(who.email).then((company) => {
+      expect(company.status).to.eq("pending");
+      expect(company.onboarding_completed).to.eq(true);
+      expect(company.nationality).to.eq("ethiopian");
+      expect((company.attributes ?? {})["cooperative"]).to.eq(true);
+      expect((company.attributes ?? {})["investorLicence"]).to.be.undefined;
+      expect(company.licence_number, "no eTrade licence").to.be.null;
+    });
+  });
+
+  it("the backoffice flags it as a co-operative", () => {
+    cy.loginBackoffice("chief@edr.local");
+
+    latestJourney("coop").then((company) => {
+      openCustomer(company.name);
+
+      cy.contains("Manual entry · co-operative").should("be.visible");
+      cy.contains("Registration entered by hand — not verified against eTrade")
+        .should("be.visible");
+      cy.contains(
+        "Check them against the Co-operative Registration Certificate",
+      ).should("be.visible");
+      cy.contains("Co-operative union / farm (no trade licence)").should(
+        "be.visible",
+      );
+      // The two manual routes must not be confused with one another.
+      cy.contains("Manual entry · investment licence").should("not.exist");
+    });
+  });
+});
+
+export {};
diff --git a/e2e/freight/cypress/e2e/flows/onboarding_ethiopian.cy.ts b/e2e/freight/cypress/e2e/flows/onboarding_ethiopian.cy.ts
new file mode 100644
index 000000000..e6f08cc95
--- /dev/null
+++ b/e2e/freight/cypress/e2e/flows/onboarding_ethiopian.cy.ts
@@ -0,0 +1,180 @@
+/**
+ * The ordinary onboarding journey, both apps — the baseline every other
+ * onboarding spec is a deviation from:
+ *
+ *   1. portal      signup + OTP → nationality/role → company (eTrade lookup) →
+ *                  owner → representation (Fayda) → contact → documents →
+ *                  "Submit for review"
+ *   2. backoffice  staff approve the importer profile; the customer carries NO
+ *                  manual-entry flag, because eTrade answered for its TIN
+ *   3. portal      the approved customer reaches the contract wizard
+ *
+ * Sequential steps of ONE journey, so retries are off — a mid-journey retry
+ * would replay a non-idempotent step against already-advanced state. Switching
+ * origin between tests (portal ↔ backoffice) re-evaluates the spec bundle and
+ * wipes module state, so the later tests resolve the journey from the DB.
+ */
+
+import { completeFaydaVerification } from "./import-utils";
+import {
+  attachNextFile,
+  companyByEmail,
+  etradeTin,
+  expectProfileActive,
+  fill,
+  fillAria,
+  fillPhone,
+  latestJourney,
+  noLicenceTin,
+  openCustomer,
+  approveFirstProfile,
+  signupCustomer,
+  signupIdentity,
+  vatNumber,
+  wizardClick,
+  SIGNUP_PASSWORD,
+} from "./onboarding-utils";
+
+const stamp = Date.now();
+const who = signupIdentity("ethiopian", stamp);
+
+describe("onboarding — Ethiopian company, eTrade verified", { retries: 0 }, () => {
+  it("completes the wizard and submits for review", () => {
+    signupCustomer(who, "Ethiopian");
+
+    cy.contains("button", "Ethiopian Company").click();
+    // An Ethiopian company is never offered the investment licence — that is a
+    // foreign company's document, and the API refuses the pair.
+    cy.contains("We operate on a foreign investment licence").should("not.exist");
+    cy.contains("button", "Importer").click();
+    wizardClick("Continue");
+
+    // ── Company step ────────────────────────────────────────────────────
+    cy.contains("Confirm your VAT number", { timeout: 20000 }).should(
+      "be.visible",
+    );
+
+    // A TIN eTrade knows but which holds no trade licence is a dead end for an
+    // ordinary company: the alert is red, and Continue must refuse rather than
+    // carry unverified registration data forward.
+    fillAria('[aria-label^="TIN Number"]', noLicenceTin(stamp));
+    cy.contains("No matching business record", { timeout: 20000 }).should(
+      "be.visible",
+    );
+    wizardClick("Continue");
+    cy.contains("We need to confirm your TIN with eTrade before continuing.").should(
+      "be.visible",
+    );
+
+    // The real one. A successful lookup fills and locks company name, region,
+    // zone, woreda, kebele and house number (ETradeCompanyCard).
+    fillAria('[aria-label^="TIN Number"]', etradeTin(stamp));
+    cy.contains("Verified with eTrade", { timeout: 20000 }).should("be.visible");
+    // handleETradeDataLoaded sets a dozen fields in sequence — each a render.
+    // Typing into VAT immediately races one of those and detaches mid-type.
+    cy.wait(500);
+    fillAria('[aria-label="VAT Number"]', vatNumber(stamp));
+    wizardClick("Continue");
+
+    // ── Owner step ──────────────────────────────────────────────────────
+    // Name and phone came from the licence and are read-only; eTrade carries
+    // no email, so that one is asked for.
+    cy.contains("Company Owner", { timeout: 20000 }).should("be.visible");
+    fill(/^Owner's Email/, `owner.${stamp}@example.com`);
+    wizardClick("Continue");
+
+    // ── Representation step ─────────────────────────────────────────────
+    cy.contains("Does anyone hold power of attorney for this company?", {
+      timeout: 20000,
+    }).should("be.visible");
+    cy.contains("button", "No, the owner acts for us").click();
+
+    // An Ethiopian company has no passport alternative — Fayda or nothing.
+    cy.contains("Use a passport instead").should("not.exist");
+    // A real eSignet redirect + SMS OTP can't run in e2e, so complete it
+    // against fayda-mock-e2e via the API. The step already fetched `identity`
+    // when it mounted, and completing out-of-band skips the redirect that
+    // would remount everything — reload to force a fresh fetch. Wizard
+    // progress is server-side, so nothing already answered is lost.
+    completeFaydaVerification("owner");
+    cy.reload();
+
+    cy.get(".mantine-Modal-content", { timeout: 30000 }).within(() => {
+      cy.contains("Fayda verified").should("be.visible");
+      // The mock's own payload — proof it travelled Fayda → API → UI rather
+      // than a flag simply flipping.
+      cy.contains("Abebe Bekele").should("be.visible");
+    });
+
+    // The verified sub is what locks the owner's fields server-side.
+    companyByEmail(who.email).then((company) => {
+      expect(
+        (company.attributes ?? {})["ownerFaydaSub"],
+        "owner Fayda sub",
+      ).to.eq("e2e-fayda-sub-0001");
+    });
+    wizardClick("Continue");
+
+    // ── Contact step ────────────────────────────────────────────────────
+    cy.contains("Contact Person", { timeout: 20000 }).should("be.visible");
+    fill(/^Name$/, "Contact Person");
+    fillPhone(0, "911234569");
+    wizardClick("Continue");
+
+    // ── Documents step ──────────────────────────────────────────────────
+    // One company document is seeded per set on a fresh e2e database
+    // (FileUploadSettingsSeeder gives a new set exactly its first field), and
+    // every operational profile owes a business licence.
+    cy.contains("Upload Importer Business license file(s)", {
+      timeout: 20000,
+    }).should("be.visible");
+    attachNextFile();
+    attachNextFile();
+    wizardClick("Submit for review");
+
+    cy.contains("You're all set", { timeout: 30000 }).should("be.visible");
+
+    companyByEmail(who.email).then((company) => {
+      expect(company.status).to.eq("pending");
+      expect(company.onboarding_completed).to.eq(true);
+      expect(company.nationality).to.eq("ethiopian");
+      // eTrade answered, so neither manual-entry flag is set and the licence
+      // it returned is on file.
+      const attributes = company.attributes ?? {};
+      expect(attributes["investorLicence"]).to.be.undefined;
+      expect(attributes["cooperative"]).to.be.undefined;
+      expect(company.licence_number, "eTrade licence").to.eq("LIC-E2E-0001");
+    });
+  });
+
+  it("backoffice approves it, with no manual-entry flag anywhere", () => {
+    cy.loginBackoffice("chief@edr.local");
+
+    latestJourney("ethiopian").then((company) => {
+      openCustomer(company.name);
+
+      // The badge and banner belong to companies whose registration was typed.
+      // This one's came from eTrade, so neither may appear.
+      cy.contains("Manual entry").should("not.exist");
+      cy.contains("Registration entered by hand").should("not.exist");
+      cy.contains("eTrade trade licence").should("be.visible");
+
+      approveFirstProfile();
+      expectProfileActive(company.name);
+    });
+  });
+
+  it("the approved customer reaches the contract wizard", () => {
+    latestJourney("ethiopian").then((company) => {
+      cy.loginPortal(company.email, SIGNUP_PASSWORD);
+    });
+    cy.visitPortal("/contracts/new");
+
+    cy.contains("label", "Operation Type", { timeout: 20000 }).should(
+      "be.visible",
+    );
+    cy.contains("Awaiting Approval").should("not.exist");
+  });
+});
+
+export {};
diff --git a/e2e/freight/cypress/e2e/flows/onboarding_guards.cy.ts b/e2e/freight/cypress/e2e/flows/onboarding_guards.cy.ts
new file mode 100644
index 000000000..a4f1ab365
--- /dev/null
+++ b/e2e/freight/cypress/e2e/flows/onboarding_guards.cy.ts
@@ -0,0 +1,171 @@
+/**
+ * The states onboarding must refuse, and the one it must undo.
+ *
+ * Two halves. The API guards are cheap `cy.request` checks against the seeded
+ * demo customer — combinations the portal never offers, which is exactly why
+ * they have to be refused server-side rather than merely hidden. The second
+ * half is the expensive one and the reason this spec exists at all: going back
+ * in the wizard and un-ticking the investment licence has to cost what the
+ * settings switch costs, or a company finishes onboarding on registration data
+ * nobody verified, with no flag left to say so.
+ */
+
+import {
+  apiRequest,
+  companyByEmail,
+  fillAria,
+  portalToken,
+  signupCustomer,
+  signupIdentity,
+  typeRegistration,
+  noLicenceTin,
+  vatNumber,
+  wizardClick,
+} from "./onboarding-utils";
+
+const stamp = Date.now();
+const who = signupIdentity("toggle", stamp);
+
+/** The seeded demo customer: an ordinary company that came through eTrade. */
+const DEMO_CUSTOMER = "user@gmail.com";
+const demoPassword = () => Cypress.env("demoPassword") as string;
+
+describe("onboarding — refused combinations", { retries: 0 }, () => {
+  it("refuses an investment licence for an Ethiopian company", () => {
+    portalToken(DEMO_CUSTOMER, demoPassword()).then((token) =>
+      apiRequest(
+        token,
+        "POST",
+        "/api/companies/onboarding/start",
+        {
+          companyType: "customer",
+          roles: ["importer"],
+          nationality: "ethiopian",
+          investorLicence: true,
+        },
+        false,
+      ).then((res) => {
+        expect(res.status).to.eq(400);
+        expect(JSON.stringify(res.body)).to.contain(
+          "Only a foreign company can onboard on an investment licence",
+        );
+      }),
+    );
+  });
+
+  it("refuses a co-operative that also claims an investment licence", () => {
+    // Ethiopian on purpose: a co-op sent as foreign is refused by the older
+    // co-operative guard, which would pass this test without the new one ever
+    // running. Ethiopian gets past that guard and lands on this one.
+    portalToken(DEMO_CUSTOMER, demoPassword()).then((token) =>
+      apiRequest(
+        token,
+        "POST",
+        "/api/companies/onboarding/start",
+        {
+          companyType: "customer",
+          roles: ["importer"],
+          nationality: "ethiopian",
+          cooperative: true,
+          investorLicence: true,
+        },
+        false,
+      ).then((res) => {
+        expect(res.status).to.eq(400);
+        expect(JSON.stringify(res.body)).to.contain(
+          "it cannot also onboard on a foreign investment licence",
+        );
+      }),
+    );
+  });
+
+  it("refuses to switch a company that never took the route", () => {
+    portalToken(DEMO_CUSTOMER, demoPassword()).then((token) =>
+      apiRequest(
+        token,
+        "POST",
+        "/api/companies/onboarding/revert-to-etrade",
+        undefined,
+        false,
+      ).then((res) => {
+        expect(res.status).to.eq(400);
+        expect(JSON.stringify(res.body)).to.contain(
+          "already registered through eTrade",
+        );
+      }),
+    );
+  });
+});
+
+describe("onboarding — un-ticking the box mid-wizard", { retries: 0 }, () => {
+  it("clears the typed registration and reopens on the company step", () => {
+    signupCustomer(who, "Toggle");
+
+    cy.contains("button", "Foreign Company").click();
+    cy.contains("We operate on a foreign investment licence").click();
+    cy.contains("button", "Importer").click();
+    wizardClick("Continue");
+
+    cy.contains("Confirm your VAT number", { timeout: 20000 }).should(
+      "be.visible",
+    );
+
+    // A TIN eTrade knows but which holds no trade licence — the manual route's
+    // own shape. (A TIN eTrade has never heard of surfaces as an outage rather
+    // than as "nothing on file": the API wraps its 404 as "Failed to fetch",
+    // which ETradeInfo reads as unreachable. Different message, different
+    // test.)
+    fillAria('[aria-label^="TIN Number"]', noLicenceTin(stamp));
+    cy.contains("Nothing on file at eTrade for this TIN", {
+      timeout: 20000,
+    }).should("be.visible");
+    typeRegistration(`E2E Toggle Trading ${stamp}`);
+    fillAria('[aria-label="VAT Number"]', vatNumber(stamp));
+    wizardClick("Continue");
+
+    // The typed registration is now on file.
+    cy.contains("Company Owner", { timeout: 20000 }).should("be.visible");
+    companyByEmail(who.email).then((company) => {
+      expect(company.region, "typed address saved").to.eq("Addis Ababa");
+      expect((company.attributes ?? {})["investorLicence"]).to.eq(true);
+    });
+
+    // Back to the company step, then back again to the nationality phase.
+    wizardClick("Back");
+    cy.contains("Confirm your VAT number", { timeout: 20000 }).should(
+      "be.visible",
+    );
+    wizardClick("Back");
+    // `exist`, not `visible`: the heading scrolls under the modal's sticky
+    // header, and where the dialog happens to be scrolled says nothing about
+    // whether we are back on the nationality phase. The checkbox below is the
+    // thing this test actually needs to reach.
+    cy.contains("Where is your company registered?", { timeout: 20000 }).should(
+      "exist",
+    );
+
+    // Change of mind: this company is an ordinary foreign company after all.
+    cy.contains("We operate on a foreign investment licence").click();
+    wizardClick("Continue");
+
+    // Whatever was typed under the flag is gone, and the resume target is the
+    // company step — not the furthest step reached, which would skip the
+    // eTrade lookup the customer has just opted back into.
+    companyByEmail(who.email).then((company) => {
+      expect((company.attributes ?? {})["investorLicence"]).to.eq(false);
+      expect(company.region, "typed address cleared").to.be.null;
+      expect(company.licence_number).to.be.null;
+      expect(company.etrade_phone).to.be.null;
+      expect(company.onboarding_step).to.eq("company");
+    });
+
+    cy.contains("Confirm your VAT number", { timeout: 20000 }).should(
+      "be.visible",
+    );
+    // No typed-registration block any more: eTrade owns these fields again.
+    cy.contains("Nothing on file at eTrade for this TIN").should("not.exist");
+    cy.contains("Registration details").should("not.exist");
+  });
+});
+
+export {};
diff --git a/e2e/freight/cypress/e2e/flows/onboarding_investor.cy.ts b/e2e/freight/cypress/e2e/flows/onboarding_investor.cy.ts
new file mode 100644
index 000000000..50ae4ce36
--- /dev/null
+++ b/e2e/freight/cypress/e2e/flows/onboarding_investor.cy.ts
@@ -0,0 +1,123 @@
+/**
+ * A foreign company onboarding on an Ethiopian Investment Commission licence.
+ *
+ * The Commission licenses it, not the trade registry, so eTrade holds no
+ * record for its TIN: the registration is typed, the company is flagged
+ * `investorLicence`, and the backoffice is told in as many words that nothing
+ * on the screen was verified against a licence. What does NOT change is the
+ * business licence per operational profile — an investor holds one, unlike a
+ * co-operative — so the documents step still asks for it.
+ *
+ * The wizard itself is driven by `completeInvestorOnboarding`, which carries
+ * the step-by-step assertions (the blue "nothing on file" alert, the absent
+ * eTrade manager, the refusal to continue on an unproven identity) because
+ * they hold for every investor run. What lives here is what is specific to
+ * this journey: the document requirements, the persisted flag, and the
+ * backoffice's treatment of it.
+ *
+ * One journey across both apps; retries off (see onboarding_ethiopian.cy.ts).
+ */
+
+import {
+  apiRequest,
+  approveFirstProfile,
+  companyByEmail,
+  completeInvestorOnboarding,
+  expectProfileActive,
+  latestJourney,
+  portalToken,
+  signupIdentity,
+  SIGNUP_PASSWORD,
+} from "./onboarding-utils";
+
+const stamp = Date.now();
+const who = signupIdentity("investor", stamp);
+
+describe("onboarding — foreign investor, no eTrade record", { retries: 0 }, () => {
+  it("types its registration and submits for review", () => {
+    completeInvestorOnboarding(who, stamp, {
+      // On the documents step, everything attached, nothing submitted yet.
+      beforeSubmit: () => {
+        portalToken(who.email).then((token) =>
+          apiRequest(
+            token,
+            "GET",
+            "/api/companies/onboarding/requirements",
+          ).then((res) => {
+            // The foreign set applies unchanged — it already asks for the
+            // investment licence itself, so no third set exists for this case.
+            expect(res.body.data.documentSettingCode).to.eq(
+              "company_onboarding_documents_foreign",
+            );
+            expect(res.body.data.investorLicence, "investorLicence flag").to.eq(
+              true,
+            );
+            expect(res.body.data.cooperative).to.eq(false);
+            // The one thing this route does NOT share with a co-operative.
+            expect(
+              res.body.data.licenseProfiles,
+              "per-role licence still tracked",
+            ).to.have.length(1);
+          }),
+        );
+      },
+    });
+
+    companyByEmail(who.email).then((company) => {
+      expect(company.status).to.eq("pending");
+      expect(company.onboarding_completed).to.eq(true);
+      expect(company.nationality).to.eq("foreign");
+      expect((company.attributes ?? {})["investorLicence"]).to.eq(true);
+      expect(company.name).to.contain("E2E Investor Holdings");
+      // Typed, not fetched: the address is what the customer entered, and no
+      // licence number exists at all.
+      expect(company.region).to.eq("Addis Ababa");
+      expect(company.licence_number, "no eTrade licence").to.be.null;
+    });
+  });
+
+  it("the backoffice flags the typed registration, then approves", () => {
+    cy.loginBackoffice("chief@edr.local");
+
+    latestJourney("investor").then((company) => {
+      cy.visit("/dashboard/customers");
+      cy.get('input[placeholder*="Search by company"]').type(company.name);
+      cy.contains(company.name, { timeout: 20000 }).should("be.visible");
+
+      // The list is where a reviewer first meets this customer, so the flag
+      // has to be there and not only on the detail page.
+      cy.contains("Manual entry · investment licence").should("be.visible");
+      cy.contains(company.name).click();
+
+      cy.contains("Manual entry · investment licence").should("be.visible");
+      cy.contains(
+        "Registration entered by hand — not verified against eTrade",
+      ).should("be.visible");
+      cy.contains("Check them against the Investment Licence").should(
+        "be.visible",
+      );
+      cy.contains(
+        "Foreign investment licence — typed by the customer, not from eTrade",
+      ).should("be.visible");
+      cy.contains("Manual entry · co-operative").should("not.exist");
+
+      // Flagging is advisory: approval itself is not blocked.
+      approveFirstProfile();
+      expectProfileActive(company.name);
+    });
+  });
+
+  it("the approved investor reaches the contract wizard", () => {
+    latestJourney("investor").then((company) => {
+      cy.loginPortal(company.email, SIGNUP_PASSWORD);
+    });
+    cy.visitPortal("/contracts/new");
+
+    cy.contains("label", "Operation Type", { timeout: 20000 }).should(
+      "be.visible",
+    );
+    cy.contains("Awaiting Approval").should("not.exist");
+  });
+});
+
+export {};
diff --git a/e2e/freight/cypress/e2e/flows/onboarding_switch_back.cy.ts b/e2e/freight/cypress/e2e/flows/onboarding_switch_back.cy.ts
new file mode 100644
index 000000000..4f16898d0
--- /dev/null
+++ b/e2e/freight/cypress/e2e/flows/onboarding_switch_back.cy.ts
@@ -0,0 +1,158 @@
+/**
+ * Giving the investment-licence route back.
+ *
+ * A company that ticked the box by mistake, or that has since been registered
+ * with the trade registry, switches from Settings → Company. It is a
+ * re-application rather than a settings edit, and this spec is about proving
+ * that literally: the typed registration is cleared (nothing on file was ever
+ * checked against a licence), the company returns to pending, onboarding
+ * reopens on the company step — and only after a real eTrade lookup does the
+ * backoffice stop flagging it.
+ *
+ * Each test is one leg of a single journey, in order, retries off. The
+ * portal ↔ backoffice hops re-evaluate the spec bundle, so every leg resolves
+ * the company from the database rather than from module state.
+ */
+
+import {
+  approveFirstProfile,
+  companyByEmail,
+  completeInvestorOnboarding,
+  etradeTin,
+  expectProfileActive,
+  fillAria,
+  latestJourney,
+  openCustomer,
+  signupIdentity,
+  wizardClick,
+  SIGNUP_PASSWORD,
+} from "./onboarding-utils";
+
+const stamp = Date.now();
+const who = signupIdentity("switchback", stamp);
+
+describe("onboarding — switching back to eTrade registration", { retries: 0 }, () => {
+  it("onboards on an investment licence", () => {
+    completeInvestorOnboarding(who, stamp, {
+      companyName: `E2E Switchback Trading ${stamp}`,
+    });
+
+    companyByEmail(who.email).then((company) => {
+      expect((company.attributes ?? {})["investorLicence"]).to.eq(true);
+      expect(company.region, "typed address").to.eq("Addis Ababa");
+    });
+  });
+
+  it("is approved by the backoffice", () => {
+    cy.loginBackoffice("chief@edr.local");
+    latestJourney("switchback").then((company) => {
+      openCustomer(company.name);
+      cy.contains("Manual entry · investment licence").should("be.visible");
+      approveFirstProfile();
+      expectProfileActive(company.name);
+    });
+  });
+
+  it("switches back from settings, which clears the typed registration", () => {
+    latestJourney("switchback").then((company) => {
+      cy.loginPortal(company.email, SIGNUP_PASSWORD);
+    });
+    cy.visitPortal("/settings");
+
+    cy.contains("Registration source", { timeout: 20000 }).should("be.visible");
+    cy.contains("button", "Switch to eTrade registration").click();
+
+    // The confirmation has to state the cost outright — this is the screen
+    // that decides whether the customer knows they are re-applying.
+    cy.contains("Switch to eTrade registration?").should("be.visible");
+    cy.contains("The registration details you typed are cleared").should(
+      "be.visible",
+    );
+    cy.contains("Your company goes back to pending").should("be.visible");
+    cy.contains("button", "Switch and re-apply").click();
+
+    cy.contains("Registration source", { timeout: 20000 }).should("not.exist");
+
+    latestJourney("switchback").then((company) => {
+      expect((company.attributes ?? {})["investorLicence"]).to.be.undefined;
+      expect(company.status).to.eq("pending");
+      expect(company.onboarding_completed).to.eq(false);
+      // The wizard treats a populated registration as a lookup that already
+      // passed, so leaving any of it behind would walk the customer straight
+      // past the eTrade step this switch exists to reach.
+      expect(company.region, "typed address cleared").to.be.null;
+      expect(company.licence_number).to.be.null;
+      expect(company.etrade_phone).to.be.null;
+      expect(company.onboarding_step, "resume target").to.eq("company");
+    });
+  });
+
+  it("re-runs onboarding through eTrade and resubmits", () => {
+    latestJourney("switchback").then((company) => {
+      cy.loginPortal(company.email, SIGNUP_PASSWORD);
+    });
+    cy.visitPortal("/portal");
+
+    // Reopened on the company step — not on the furthest step reached before.
+    cy.contains("Confirm your VAT number", { timeout: 30000 }).should(
+      "be.visible",
+    );
+    // The typed registration section is gone: this is an ordinary company now.
+    cy.contains("Nothing on file at eTrade for this TIN").should("not.exist");
+
+    fillAria('[aria-label^="TIN Number"]', etradeTin(stamp));
+    cy.contains("Verified with eTrade", { timeout: 20000 }).should("be.visible");
+    cy.wait(500);
+    wizardClick("Continue");
+
+    // Owner, representation and contact are already satisfied server-side —
+    // the switch keeps everything except the registration — so each step only
+    // needs advancing.
+    cy.contains("Company Owner", { timeout: 20000 }).should("be.visible");
+    wizardClick("Continue");
+    cy.contains("The owner acts for the company", { timeout: 20000 }).should(
+      "be.visible",
+    );
+    wizardClick("Continue");
+    cy.contains("Contact Person", { timeout: 20000 }).should("be.visible");
+    wizardClick("Continue");
+
+    // Documents and the licence were uploaded before the switch and survive
+    // it, so the step is already satisfied.
+    cy.contains("Upload Importer Business license file(s)", {
+      timeout: 20000,
+    }).should("be.visible");
+    wizardClick("Submit for review");
+    cy.contains("You're all set", { timeout: 30000 }).should("be.visible");
+
+    latestJourney("switchback").then((company) => {
+      expect(company.onboarding_completed).to.eq(true);
+      expect((company.attributes ?? {})["investorLicence"]).to.be.undefined;
+      // eTrade answered this time, and its licence is on file.
+      expect(company.licence_number).to.eq("LIC-E2E-0001");
+    });
+  });
+
+  it("the backoffice no longer flags it", () => {
+    cy.loginBackoffice("chief@edr.local");
+    latestJourney("switchback").then((company) => {
+      openCustomer(company.name);
+
+      cy.contains("eTrade trade licence").should("be.visible");
+      cy.contains("Manual entry").should("not.exist");
+      cy.contains("Registration entered by hand").should("not.exist");
+    });
+  });
+
+  it("offers nothing to switch to a customer who came through eTrade", () => {
+    // The seeded demo customer onboarded the ordinary way, so the card must
+    // not be on its settings page at all.
+    cy.loginPortal();
+    cy.visitPortal("/settings");
+
+    cy.contains("Operational Services", { timeout: 20000 }).should("be.visible");
+    cy.contains("Registration source").should("not.exist");
+  });
+});
+
+export {};

From f62054d4a467cb5ba93c9a81d8108592cc7c850d Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 11:47:18 +0000
Subject: [PATCH 153/174] fix(portal): accept a business licence the server
 already holds
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A resumed onboarding asked for the per-role business licence again and refused
to submit until it was uploaded a second time, however many were already on
file. `getInfo` never populates `companyProfiles[].licenseFiles`, and the
wizard validates against exactly that — so every profile looked empty, while
`markOnboardingComplete` would have accepted the application as it stood.

Validation now reads `licenseProfiles[].uploaded` from the onboarding
requirements: the server's own verdict, already fetched by the step, and the
same source the API enforces on submit.

Reachable today by anyone who resumes onboarding after a licence upload, and by
every company that switches back to eTrade registration — which is where the
e2e suite hit it.
---
 .../onboarding/OnboardingWizardDialog.tsx         |  9 +++++++++
 .../src/pages/accounts/CompanyProfileForm.tsx     | 15 ++++++++++++++-
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
index 0dd3e4462..b06b1487c 100644
--- a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
+++ b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
@@ -492,6 +492,15 @@ export default function OnboardingWizardDialog({
     licenseFiles,
     onLicenseChange: setLicenseFiles,
     uploadedDocumentKeys,
+    // What the server says is already on file, per operational profile. The
+    // wizard's own `roleProfiles` cannot say: getInfo leaves `licenseFiles`
+    // empty, so a resumed wizard asked for a licence it had already been given
+    // and refused to submit until it was uploaded a second time.
+    uploadedLicenceProfileIds: (
+      requirementsQuery.data?.licenseProfiles ?? []
+    )
+      .filter((p) => p.uploaded)
+      .map((p) => p.profileId),
     onUploadDocuments: handleUploadDocuments,
     // The company's single identity verification, and whose it is. Fayda is
     // mandatory for an Ethiopian company; a foreign one may instead type a
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 542fd17b5..fd0e060e1 100644
--- a/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
@@ -61,6 +61,7 @@ export default function CompanyProfileForm({
   onLicenseChange,
   submitError,
   uploadedDocumentKeys,
+  uploadedLicenceProfileIds,
   onUploadDocuments,
   identity: rawIdentity,
   onIdentityChange,
@@ -96,6 +97,16 @@ export default function CompanyProfileForm({
   submitError?: string | null;
   /** fileKeys whose company document is already uploaded server-side (resume). */
   uploadedDocumentKeys?: string[];
+  /**
+   * Profile ids whose business licence the server already holds.
+   *
+   * `roleProfiles.existingFiles` cannot answer this on a resumed wizard:
+   * `getInfo` does not populate `licenseFiles`, so every profile looks empty
+   * however many licences are on file. Taken from the onboarding requirements,
+   * which is the server's own verdict and what `markOnboardingComplete`
+   * enforces.
+   */
+  uploadedLicenceProfileIds?: string[];
   /**
    * Auto-upload the currently-selected company documents (the Documents step's
    * "Continue" action). Resolves to an error message string on failure so the
@@ -688,7 +699,9 @@ export default function CompanyProfileForm({
     if (cooperative) return errs;
     for (const p of roleProfiles ?? []) {
       const hasNew = (licenseFiles?.[p.id]?.length ?? 0) > 0;
-      const hasExisting = p.existingFiles.length > 0;
+      const hasExisting =
+        p.existingFiles.length > 0 ||
+        (uploadedLicenceProfileIds ?? []).includes(p.id);
       if (!hasNew && !hasExisting) {
         errs[p.id] = "Business license is required";
       }

From f3e64681c2b304aeb0aa6d18ab4a6558a23bad7c Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 11:47:18 +0000
Subject: [PATCH 154/174] test(e2e): wait for rehydration before retyping the
 TIN after a switch

The switch clears the registration but not the tax number, so the company step
reopens with the old TIN and RHF re-seeds the field when the profile refetch
lands. A TIN typed before that arrived was silently replaced by the stored one
and the lookup ran against the wrong number.

The spec now waits for the rehydrated VAT value, then asserts the field holds
what it typed before waiting on eTrade.
---
 .../cypress/e2e/flows/onboarding_switch_back.cy.ts    | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/e2e/freight/cypress/e2e/flows/onboarding_switch_back.cy.ts b/e2e/freight/cypress/e2e/flows/onboarding_switch_back.cy.ts
index 4f16898d0..e6c903e89 100644
--- a/e2e/freight/cypress/e2e/flows/onboarding_switch_back.cy.ts
+++ b/e2e/freight/cypress/e2e/flows/onboarding_switch_back.cy.ts
@@ -100,7 +100,18 @@ describe("onboarding — switching back to eTrade registration", { retries: 0 },
     // The typed registration section is gone: this is an ordinary company now.
     cy.contains("Nothing on file at eTrade for this TIN").should("not.exist");
 
+    // Wait for the profile to rehydrate before typing. The company still holds
+    // the TIN it typed under the flag (the switch clears the registration, not
+    // the tax number), and RHF re-seeds the field when the refetch lands — so a
+    // TIN typed into an empty-looking field is silently replaced by the stored
+    // one, and the lookup then runs against the wrong number.
+    cy.get('.mantine-Modal-content [aria-label="VAT Number"]')
+      .should("not.have.value", "");
     fillAria('[aria-label^="TIN Number"]', etradeTin(stamp));
+    cy.get('.mantine-Modal-content [aria-label^="TIN Number"]').should(
+      "have.value",
+      etradeTin(stamp),
+    );
     cy.contains("Verified with eTrade", { timeout: 20000 }).should("be.visible");
     cy.wait(500);
     wizardClick("Continue");

From f7be33eaaf4436ef5c47a6582b2096f01b677237 Mon Sep 17 00:00:00 2001
From: Hagernesh <hagernesh@example.com>
Date: Mon, 17 Aug 2026 18:43:26 +0000
Subject: [PATCH 155/174] feat(eims): alias bare Addis Ababa sub-city names to
 the CSV's woreda codes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Confirmed live 2026-08-17: buyer profiles store just the sub-city name
("Bole", "Arada") as their woreda, never the source CSV's specific
example-woreda name ("Bole Woreda 01") — hit for three different
buyers in a row (Bole, Arada, Lemi Kura) before any got past this
check. Since the CSV lists exactly one representative woreda per
Addis sub-city, alias the bare name to that same code instead of
waiting on a fuller table — use what's already been supplied first.

Lemi Kura itself isn't in the source CSV at all (one of Addis
Ababa's newer sub-cities) — still needs its real code from MoR.
---
 .../src/config/eims.config.spec.ts            | 15 +++++++++++++
 .../src/config/ethiopia-geo-codes.ts          | 21 +++++++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/apps/edr-freight-api/src/config/eims.config.spec.ts b/apps/edr-freight-api/src/config/eims.config.spec.ts
index 60ee33e1b..127b3ea62 100644
--- a/apps/edr-freight-api/src/config/eims.config.spec.ts
+++ b/apps/edr-freight-api/src/config/eims.config.spec.ts
@@ -113,4 +113,19 @@ describe("eims.config — baked-in Ethiopia region/zone/woreda codes", () => {
       },
     );
   });
+
+  it("resolves the bare Addis Ababa sub-city name a buyer profile actually stores, not the CSV's example-woreda name", () => {
+    withEnv(
+      { ...REQUIRED, EIMS_PRIVATE_KEY: "x", EIMS_CERTIFICATE_PATH: "/dev/null" },
+      () => {
+        const codes = eimsConfigFactory().invoice.buyerWeredaCodes;
+        expect(codes.Bole).toBe("01");
+        expect(codes.Arada).toBe("01");
+        expect(codes.Kirkos).toBe("01");
+        expect(codes.Yeka).toBe("01");
+        expect(codes["Nifas Silk Lafto"]).toBe("13");
+        expect(codes["Nefas Silk-Lafto"]).toBe("13");
+      },
+    );
+  });
 });
diff --git a/apps/edr-freight-api/src/config/ethiopia-geo-codes.ts b/apps/edr-freight-api/src/config/ethiopia-geo-codes.ts
index f7257e045..ca48a7c5f 100644
--- a/apps/edr-freight-api/src/config/ethiopia-geo-codes.ts
+++ b/apps/edr-freight-api/src/config/ethiopia-geo-codes.ts
@@ -137,3 +137,24 @@ export const ETHIOPIA_REGION_CODES: Record<string, string> = buildMap((r) => [r[
 /** Zone name → code. Fed into `buyerCityCodes` — EIMS's "City" is really the buyer's zone. */
 export const ETHIOPIA_ZONE_CODES: Record<string, string> = buildMap((r) => [r[1], r[4]]);
 export const ETHIOPIA_WOREDA_CODES: Record<string, string> = buildMap((r) => [r[2], r[5]]);
+
+/**
+ * Buyer records commonly store just the bare Addis Ababa sub-city name ("Bole", "Arada") as their
+ * woreda, not the source CSV's specific example-woreda name ("Bole Woreda 01") — confirmed live
+ * 2026-08-17 across three different buyers before any of them actually got past this check. Since
+ * the CSV lists exactly one representative woreda per Addis sub-city, alias the bare name to that
+ * same code rather than wait on a fuller table.
+ */
+const ADDIS_SUBCITY_ALIASES: Array<[bareName: string, csvZoneName: string]> = [
+  ["Bole", "Bole Sub-City"],
+  ["Kirkos", "Kirkos Sub-City"],
+  ["Nifas Silk Lafto", "Nifas Silk Lafto"],
+  // Matches EIMS_BUYER_WEREDA_CODES' own existing spelling in .env — same zone, different hyphenation.
+  ["Nefas Silk-Lafto", "Nifas Silk Lafto"],
+  ["Yeka", "Yeka Sub-City"],
+  ["Arada", "Arada Sub-City"],
+];
+for (const [bareName, csvZoneName] of ADDIS_SUBCITY_ALIASES) {
+  const row = ROWS.find((r) => r[1] === csvZoneName);
+  if (row && !(bareName in ETHIOPIA_WOREDA_CODES)) ETHIOPIA_WOREDA_CODES[bareName] = row[5];
+}

From cbcc9a02e69d6e5084e528dc5b3421d01c422a8c Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 12:44:02 +0000
Subject: [PATCH 156/174] fix: approval window

---
 .../companies.license-supersede.spec.ts       | 187 ++++++++++++++++++
 .../companies.profile-approval.spec.ts        | 115 +++++++++++
 .../modules/companies/companies.service.ts    |  59 +++++-
 .../src/components/customers/badges.tsx       |  43 ++--
 4 files changed, 390 insertions(+), 14 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/companies/companies.license-supersede.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/companies/companies.profile-approval.spec.ts

diff --git a/apps/edr-freight-api/src/modules/companies/companies.license-supersede.spec.ts b/apps/edr-freight-api/src/modules/companies/companies.license-supersede.spec.ts
new file mode 100644
index 000000000..5a73b6040
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/companies/companies.license-supersede.spec.ts
@@ -0,0 +1,187 @@
+import { CompaniesService } from "./companies.service";
+import { CompanyStatus } from "./entities/company.entity";
+import {
+  ProfileStatus,
+  ProfileType,
+} from "./entities/company-profile.entity";
+
+/**
+ * Uploading a business licence only ever adds a row — nothing overwrites. So a
+ * customer answering a rejection or a document correction used to end up with
+ * the refused licence still listed beside the new one, in the portal and in the
+ * backoffice, with nothing saying which is current. An upload that answers a
+ * reviewer now retires what it answers; an upload with nothing outstanding is a
+ * genuine addition and still just adds.
+ */
+interface StoredFile {
+  id: string;
+  name: string;
+  code: string;
+  createdAt: Date;
+  reviewStatus?: string | null;
+  removed?: boolean;
+}
+
+const T0 = new Date("2026-01-01T00:00:00Z");
+const REJECTED_AT = new Date("2026-02-01T00:00:00Z");
+const T2 = new Date("2026-03-01T00:00:00Z");
+
+function makeService(
+  status: ProfileStatus,
+  files: StoredFile[],
+  reviewedAt: Date | null = null,
+) {
+  const stored = [...files];
+  const profile = {
+    id: "profile-1",
+    companyId: "company-1",
+    type: ProfileType.importer,
+    status,
+    reviewedAt,
+  };
+  const company = {
+    id: "company-1",
+    status:
+      status === ProfileStatus.Active
+        ? CompanyStatus.Active
+        : CompanyStatus.Pending,
+    companyProfiles: [profile],
+  };
+
+  const live = () => stored.filter((f) => !f.removed);
+  const filesService = {
+    upload: jest.fn(async (input: { code: string; file: { originalname: string } }) => {
+      const record = {
+        id: `file-${stored.length + 1}`,
+        name: input.file.originalname,
+        code: input.code,
+        createdAt: T2,
+        size: 1,
+        mimeType: "application/pdf",
+      };
+      stored.push(record);
+      return record;
+    }),
+    findByResource: jest.fn(async () => live()),
+    findWithOpenChangeRequest: jest.fn(async () =>
+      live().filter((f) => f.reviewStatus === "change_requested"),
+    ),
+    findById: jest.fn(async (id: string) => ({
+      ...stored.find((f) => f.id === id),
+      resource: "company_profiles",
+      resourceId: "profile-1",
+    })),
+    remove: jest.fn(async (id: string) => {
+      const found = stored.find((f) => f.id === id);
+      if (found) found.removed = true;
+    }),
+    clearReview: jest.fn(async (id: string) => {
+      const found = stored.find((f) => f.id === id);
+      if (found) found.reviewStatus = null;
+    }),
+  };
+
+  const changeRequestRepo = {
+    findPendingByCompanyId: jest.fn(async () => null),
+    create: jest.fn(async (row: Record<string, unknown>) => ({ id: "cr-1", ...row })),
+    update: jest.fn(async () => ({ id: "cr-1" })),
+    findByCompanyId: jest.fn(async () => []),
+  };
+
+  const service = new CompaniesService(
+    { findById: jest.fn(async () => company) } as never,
+    { findByCompanyId: jest.fn(async () => [profile]) } as never,
+    changeRequestRepo as never,
+    {} as never,
+    { findByCompanyId: jest.fn(async () => []) } as never,
+    {} as never,
+    filesService as never,
+    {} as never,
+    {} as never,
+    { changeRequestSubmitted: jest.fn() } as never,
+    {} as never,
+    {} as never,
+  );
+
+  jest
+    .spyOn(service, "getCompanyInfoByUserId")
+    .mockImplementation(
+      async () => ({ profile: { id: "external-1" }, company }) as never,
+    );
+
+  return { service, stored, live, filesService, changeRequestRepo };
+}
+
+const upload = (service: CompaniesService) =>
+  service.addProfileLicenseFiles("user-1", "profile-1", [
+    { originalname: "new-licence.pdf" } as never,
+  ]);
+
+describe("a business licence uploaded to answer a reviewer", () => {
+  it("retires the file the reviewer flagged for correction", async () => {
+    const { service, live } = makeService(ProfileStatus.Pending, [
+      { id: "file-old", name: "old.pdf", code: "business_license", createdAt: T0, reviewStatus: "change_requested" },
+    ]);
+
+    await upload(service);
+
+    expect(live().map((f) => f.name)).toEqual(["new-licence.pdf"]);
+  });
+
+  it("retires what was on file when the role was rejected, but not the customer's own fix so far", async () => {
+    // Two uploads answering one rejection (a second page, or a re-pick) must not
+    // cannibalise each other — only what the reviewer actually refused goes.
+    const { service, live } = makeService(
+      ProfileStatus.Rejected,
+      [
+        { id: "file-refused", name: "refused.pdf", code: "business_license", createdAt: T0 },
+        { id: "file-fix-1", name: "fix-page-1.pdf", code: "business_license", createdAt: T2 },
+      ],
+      REJECTED_AT,
+    );
+
+    await upload(service);
+
+    expect(live().map((f) => f.name)).toEqual([
+      "fix-page-1.pdf",
+      "new-licence.pdf",
+    ]);
+  });
+
+  it("leaves an ordinary addition alone when nothing was asked for", async () => {
+    const { service, live } = makeService(ProfileStatus.Pending, [
+      { id: "file-old", name: "existing.pdf", code: "business_license", createdAt: T0 },
+    ]);
+
+    await upload(service);
+
+    expect(live().map((f) => f.name)).toEqual([
+      "existing.pdf",
+      "new-licence.pdf",
+    ]);
+  });
+
+  it("stages the swap for review on an approved role instead of deleting", async () => {
+    // A live role's licence is not the customer's to remove unilaterally: the
+    // old file stays until a reviewer approves the swap.
+    const { service, live, changeRequestRepo } = makeService(
+      ProfileStatus.Active,
+      [
+        { id: "file-old", name: "old.pdf", code: "business_license", createdAt: T0, reviewStatus: "change_requested" },
+      ],
+    );
+
+    await upload(service);
+
+    expect(live().map((f) => f.name)).toEqual(["old.pdf", "new-licence.pdf"]);
+    const intents = changeRequestRepo.create.mock.calls.flatMap(
+      ([row]) => (row as any).documents.licenseChanges,
+    );
+    expect(intents).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ op: "add", fileId: "file-2" }),
+        expect.objectContaining({ op: "remove", fileId: "file-old" }),
+      ]),
+    );
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/companies/companies.profile-approval.spec.ts b/apps/edr-freight-api/src/modules/companies/companies.profile-approval.spec.ts
new file mode 100644
index 000000000..79fbdd479
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/companies/companies.profile-approval.spec.ts
@@ -0,0 +1,115 @@
+import { BadRequestException } from "@nestjs/common";
+
+import { CompaniesService } from "./companies.service";
+import { Company, CompanyStatus } from "./entities/company.entity";
+import {
+  CompanyProfile,
+  ProfileStatus,
+  ProfileType,
+} from "./entities/company-profile.entity";
+
+/**
+ * A rejection hands the role back to the customer: they fix what was flagged
+ * and resubmit (`reapplyCompanyProfile` → Pending). The reviewer used to be
+ * able to skip that entirely and approve straight out of Rejected — granting
+ * the role over the documents that were just refused, while the customer's
+ * "please fix this" note was still on their screen.
+ */
+function makeService(status: ProfileStatus) {
+  const profile: Partial<CompanyProfile> = {
+    id: "profile-1",
+    companyId: "company-1",
+    type: ProfileType.importer,
+    status,
+    reference: null,
+    reviewNote: status === ProfileStatus.Rejected ? "Licence expired" : null,
+  };
+  const company = {
+    id: "company-1",
+    status: CompanyStatus.Pending,
+    attributes: {},
+  };
+
+  const written: Partial<CompanyProfile>[] = [];
+  const profileRepo = {
+    update: jest.fn(async (_id: string, patch: Partial<CompanyProfile>) => {
+      written.push(patch);
+      Object.assign(profile, patch);
+      return null;
+    }),
+    findOne: jest.fn(async () => profile),
+  };
+  const companyRepo = { findOne: jest.fn(async () => company), update: jest.fn() };
+
+  const companyProfilesRepo = {
+    findById: jest.fn(async () => profile),
+    generateReference: jest.fn(async () => "IM-A00001"),
+  };
+  const profilesRepo = {
+    // Onboarding submitted — the other gate in this method is not what these
+    // tests are about.
+    findByCompanyId: jest.fn(async () => [{ onboardingCompleted: true }]),
+  };
+  const filesService = { findWithOpenChangeRequest: jest.fn(async () => []) };
+  const dataSource = {
+    transaction: jest.fn(async (cb: (m: unknown) => Promise<unknown>) =>
+      cb({
+        findOne: jest.fn(async () => company),
+        getRepository: (entity: unknown) =>
+          entity === Company ? companyRepo : profileRepo,
+      }),
+    ),
+  };
+  const companyNotifier = { profileStatusChanged: jest.fn(), companyApproved: jest.fn() };
+
+  const service = new CompaniesService(
+    {} as never,
+    companyProfilesRepo as never,
+    {} as never,
+    {} as never,
+    profilesRepo as never,
+    {} as never,
+    filesService as never,
+    {} as never,
+    {} as never,
+    companyNotifier as never,
+    dataSource as never,
+    {} as never,
+  );
+
+  return { service, profile, written, companyProfilesRepo };
+}
+
+describe("approving an operational role", () => {
+  it("refuses to approve a role the customer has not resubmitted", async () => {
+    const { service, companyProfilesRepo } = makeService(ProfileStatus.Rejected);
+
+    await expect(
+      service.setCompanyProfileStatus("profile-1", ProfileStatus.Active),
+    ).rejects.toBeInstanceOf(BadRequestException);
+    // Refused before any reference could be minted against the rejected role.
+    expect(companyProfilesRepo.generateReference).not.toHaveBeenCalled();
+  });
+
+  it("lets a reviewer undo their own rejection, and drops the note with it", async () => {
+    const { service, written } = makeService(ProfileStatus.Rejected);
+
+    await service.setCompanyProfileStatus("profile-1", ProfileStatus.Pending);
+
+    expect(written[0]).toMatchObject({
+      status: ProfileStatus.Pending,
+      reviewNote: null,
+    });
+  });
+
+  it("still approves a role that is awaiting its first decision", async () => {
+    const { service, written } = makeService(ProfileStatus.Pending);
+
+    await service.setCompanyProfileStatus("profile-1", ProfileStatus.Active);
+
+    expect(written[0]).toMatchObject({
+      status: ProfileStatus.Active,
+      reference: "IM-A00001",
+    });
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/companies/companies.service.ts b/apps/edr-freight-api/src/modules/companies/companies.service.ts
index 1eb611c24..d7151f200 100644
--- a/apps/edr-freight-api/src/modules/companies/companies.service.ts
+++ b/apps/edr-freight-api/src/modules/companies/companies.service.ts
@@ -1830,6 +1830,24 @@ export class CompaniesService {
       );
     }
 
+    // A rejected role is waiting on the customer, not on the reviewer: nothing
+    // has been resubmitted, and the note telling them what to fix is still on
+    // their screen. Approving straight out of Rejected grants the very role that
+    // was refused, over the documents that were refused with it. The way back is
+    // the customer's own resubmission (`reapplyCompanyProfile` → Pending); a
+    // rejection made in error is undone by moving the role back to pending
+    // review first — the same shape as "withdraw the change request first" on
+    // the document gate below.
+    if (
+      status === ProfileStatus.Active &&
+      existing.status === ProfileStatus.Rejected
+    ) {
+      throw new BadRequestException(
+        "This role was rejected — the customer has to fix what was flagged and resubmit it before it can be approved. " +
+          "If the rejection was a mistake, move the role back to pending review first.",
+      );
+    }
+
     // A self-registered company is only reviewable once its owner submits the
     // onboarding wizard (markOnboardingComplete) — until then its profiles are
     // half-filled drafts and approving one would mint a reference against an
@@ -1958,7 +1976,14 @@ export class CompaniesService {
       status === ProfileStatus.Suspended
     ) {
       patch.reviewNote = note ?? null;
-    } else if (status === ProfileStatus.Active) {
+    } else if (
+      status === ProfileStatus.Active ||
+      status === ProfileStatus.Pending
+    ) {
+      // Pending only reaches here when a reviewer withdraws their own rejection
+      // (the customer's resubmission clears the note in `reapplyCompanyProfile`),
+      // so the reason they gave goes with it — leaving it would keep telling the
+      // customer to fix something nobody is waiting on any more.
       patch.reviewNote = null;
     }
     if (status !== ProfileStatus.Pending) {
@@ -2675,6 +2700,9 @@ export class CompaniesService {
    * with the role itself. Only for an already-approved role are they staged under
    * the pending code and recorded as `add` intents on a pending change request —
    * a licence swap on a live role is a change; a licence on a new role is not.
+   *
+   * An upload that answers a reviewer also retires the licence it answers (see
+   * below), so a correction never leaves both copies on file.
    */
   async addProfileLicenseFiles(
     userId: string,
@@ -2686,6 +2714,28 @@ export class CompaniesService {
     const gated = profile.status === ProfileStatus.Active;
     const code = gated ? LICENSE_PENDING_CODE : LICENSE_CODE;
 
+    // An upload that answers the reviewer replaces what they refused; it does
+    // not sit next to it. Uploading only ever adds a row, so without this the
+    // refused licence stays listed in the portal and the backoffice beside the
+    // new one and nothing says which is current. Two things count as refused:
+    // the file the reviewer flagged for correction, and — when the whole role
+    // came back rejected — every licence that was already on file when they
+    // rejected it. Anything the customer uploaded *since* that decision is part
+    // of the same fix (a second page, a re-pick), so it survives, and an upload
+    // with nothing outstanding is a genuine addition and is left alone.
+    const rejectedAt =
+      profile.status === ProfileStatus.Rejected
+        ? (profile.reviewedAt ?? null)
+        : null;
+    const superseded = rejectedAt
+      ? (
+          await this.filesService.findByResource(profileId, LICENSE_RESOURCE)
+        ).filter((f) => f.createdAt < rejectedAt)
+      : await this.filesService.findWithOpenChangeRequest(
+          [profileId],
+          LICENSE_RESOURCE,
+        );
+
     const uploaded = await Promise.all(
       files.map((file) =>
         this.filesService.upload({
@@ -2710,6 +2760,13 @@ export class CompaniesService {
       );
     }
 
+    // Retire what the upload supersedes, through the normal removal path so an
+    // approved role stages a `remove` intent (reviewed as a swap) while an
+    // unapproved one just drops the file.
+    for (const stale of superseded) {
+      await this.removeProfileLicenseFile(userId, profileId, stale.id);
+    }
+
     // A fresh licence upload answers any correction the reviewer asked for on the
     // previous one, so the old row must stop blocking approval.
     await this.resolveDocumentChangeRequests(
diff --git a/apps/edr-freight-web/backoffice/src/components/customers/badges.tsx b/apps/edr-freight-web/backoffice/src/components/customers/badges.tsx
index 22d3e66cf..3127a39f8 100644
--- a/apps/edr-freight-web/backoffice/src/components/customers/badges.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/customers/badges.tsx
@@ -338,9 +338,11 @@ export function InvoiceStatusBadge({
 
 /**
  * Inline approval action buttons for a profile row.
- * Transitions: pending → approve / reject-with-note | rejected → approve (override) |
+ * Transitions: pending → approve / reject-with-note | rejected → undo-rejection (→ pending) |
  * active → suspend | suspended → reactivate/blacklist | blacklisted → reinstate.
- * Rejecting captures a note the customer sees so they can fix and reapply.
+ * Rejecting captures a note the customer sees so they can fix and reapply — a
+ * rejected role is theirs to resubmit, so it cannot be approved from here until
+ * they do (the API refuses it); undoing the rejection is the only way back.
  *
  * `locked` (customer hasn't submitted onboarding) withholds the review decision
  * only — there's no application to judge yet, and the API rejects the call
@@ -526,18 +528,33 @@ export function ProfileApprovalActions({
   }
 
   if (status === "rejected") {
-    if (!canSet("active")) return null;
+    // No Approve here: the role is waiting on the customer to fix what was
+    // flagged and resubmit it, and the API refuses rejected → active outright.
+    // All that's left is undoing a rejection that shouldn't have happened,
+    // which puts the role back in the queue rather than into service.
+    if (!canSet("pending")) return null;
     return (
-      <Button
-        size="xs"
-        variant="light"
-        color="edr-green"
-        radius="md"
-        loading={isPending}
-        onClick={() => act("active")}
-      >
-        Approve
-      </Button>
+      <Group gap={8} wrap="nowrap">
+        <Text size="xs" c="dimmed" fs="italic">
+          Awaiting customer resubmission
+        </Text>
+        <Tooltip
+          multiline
+          w={260}
+          label="Puts the role back in the pending queue and clears the rejection note. Use only if the rejection itself was a mistake — it does not approve the role."
+        >
+          <Button
+            size="xs"
+            variant="subtle"
+            color="gray"
+            radius="md"
+            loading={isPending}
+            onClick={() => act("pending")}
+          >
+            Undo rejection
+          </Button>
+        </Tooltip>
+      </Group>
     );
   }
 

From 22a3fb98eec99fed9bc52595b3d5fe32e06643ca Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Tue, 18 Aug 2026 12:50:35 +0000
Subject: [PATCH 157/174] feat: Implement consolidated booking functionality

- Added support for viewing and managing consolidated bookings in BookingRequestDetailPage.
- Enhanced BookingRequestsPage to display paired bookings in a single row.
- Introduced pairedDecision method in bookings service to handle decisions for both halves of a consolidated pair.
- Updated contracts service to include methods for manual consolidation of odd-20ft bookings.
- Created new components for selecting and editing consolidation partners.
- Added tests for paired decision logic and manual consolidation scenarios.
- Updated UI to reflect changes in booking handling and provide user feedback for odd container counts.
---
 ...booking-transition.paired-decision.spec.ts | 132 ++++
 .../bookings/booking-transition.service.ts    |  69 +++
 .../modules/bookings/bookings.controller.ts   |  26 +
 .../modules/bookings/bookings.repository.ts   |  85 +++
 .../bookings/dto/request-changes.dto.ts       |  33 +
 ...tract-booking.manual-consolidation.spec.ts | 213 +++++++
 .../contracts/contract-booking.service.ts     | 156 +++++
 .../modules/contracts/contracts.controller.ts |  40 +-
 .../dto/create-booking-under-contract.dto.ts  |  44 +-
 .../bookings/BookingActionsMenu.tsx           |  32 +-
 .../bookings/BookingConfirmDialog.tsx         |  24 +
 .../bookings/useBookingActionDialog.ts        |  37 ++
 .../contracts/GlCreateBookingForm.tsx         | 566 +++++++++++++++++-
 .../ConsolidationPartnerPanel.tsx             | 255 ++++++++
 .../ConsolidationPartnerPicker.tsx            | 137 +++++
 .../backoffice/src/constants/URLS.ts          |   8 +
 .../bookings/booking-actions.config.ts        |   3 +
 .../src/hooks/bookings/useBookings.ts         |  32 +
 .../bookings/BookingRequestDetailPage.tsx     |  83 ++-
 .../pages/bookings/BookingRequestsPage.tsx    |  43 +-
 .../src/services/bookings.service.ts          |  20 +
 .../src/services/contracts.service.ts         |  66 ++
 .../backoffice/src/types/booking.ts           |   6 +
 .../new-booking-form/step8-review.tsx         |  26 +-
 .../contracts/NewShipmentRequestPage.tsx      |  19 +-
 25 files changed, 2121 insertions(+), 34 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/bookings/booking-transition.paired-decision.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/contracts/contract-booking.manual-consolidation.spec.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPanel.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPicker.tsx

diff --git a/apps/edr-freight-api/src/modules/bookings/booking-transition.paired-decision.spec.ts b/apps/edr-freight-api/src/modules/bookings/booking-transition.paired-decision.spec.ts
new file mode 100644
index 000000000..91b1bfd91
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/booking-transition.paired-decision.spec.ts
@@ -0,0 +1,132 @@
+import { BookingTransitionService } from './booking-transition.service';
+import { Booking } from './entities/booking.entity';
+
+/**
+ * Staff decisions on a consolidated pair. Two bookings sharing a wagon must move
+ * together: accepting one alone would put half a wagon into the approval chain,
+ * and cancelling one alone would strand the other on a wagon it can no longer
+ * fill. All-or-nothing — if either half throws, neither booking moved.
+ */
+describe('BookingTransitionService — paired staff decisions', () => {
+  function makeService(booking: Partial<Booking>) {
+    const bookingsService = {
+      findById: jest.fn().mockResolvedValue(booking as Booking),
+    };
+    // Runs the callback so a throw propagates, which is what the all-or-nothing
+    // guarantee reduces to from this service's point of view.
+    const dataSource = {
+      transaction: jest.fn(async (cb: () => Promise<unknown>) => cb()),
+    };
+
+    const service = new BookingTransitionService(
+      {} as never, // bookingsRepository
+      {} as never, // ruleEngineService
+      {} as never, // pricingService
+      {} as never, // contractService
+      {} as never, // filesService
+      {} as never, // fileUploadSettingsService
+      {} as never, // bookingBatchService
+      bookingsService as never,
+      {} as never, // bookingClearanceService
+      {} as never, // workflowService
+      {} as never, // invoiceService
+      {} as never, // containerValidationService
+      {} as never, // notifier
+      {} as never, // events
+      undefined, // milestoneService
+      dataSource as never,
+    );
+    return { service, dataSource };
+  }
+
+  const paired = {
+    id: 'b-1',
+    reference: 'BK-1',
+    consolidationPartnerId: 'b-2',
+  } as Booking;
+
+  it('accepts both halves with the same validity window', async () => {
+    const { service } = makeService(paired);
+    const accept = jest
+      .spyOn(service, 'acceptIntake')
+      .mockImplementation(async (id) => ({ id }) as Booking);
+
+    const result = await service.applyPairedDecision('b-1', 'accept', 'staff-1', {
+      validityDays: 30,
+    });
+
+    expect(accept).toHaveBeenCalledTimes(2);
+    expect(accept).toHaveBeenNthCalledWith(1, 'b-1', 'staff-1', 30);
+    expect(accept).toHaveBeenNthCalledWith(2, 'b-2', 'staff-1', 30);
+    expect(result.booking.id).toBe('b-1');
+    expect(result.partner.id).toBe('b-2');
+  });
+
+  it('cancels both halves with the same reason', async () => {
+    const { service } = makeService(paired);
+    const cancel = jest
+      .spyOn(service, 'cancel')
+      .mockImplementation(async (id) => ({ id }) as Booking);
+
+    await service.applyPairedDecision('b-1', 'cancel', 'staff-1', {
+      reason: 'customer withdrew',
+    });
+
+    expect(cancel).toHaveBeenNthCalledWith(1, 'b-1', 'customer withdrew');
+    expect(cancel).toHaveBeenNthCalledWith(2, 'b-2', 'customer withdrew');
+  });
+
+  it('propagates a failure on the second half so neither is committed', async () => {
+    const { service, dataSource } = makeService(paired);
+    jest
+      .spyOn(service, 'cancel')
+      .mockImplementationOnce(async (id) => ({ id }) as Booking)
+      .mockImplementationOnce(async () => {
+        throw new Error('partner is already in transit');
+      });
+
+    await expect(
+      service.applyPairedDecision('b-1', 'cancel', 'staff-1', { reason: 'x' }),
+    ).rejects.toThrow('partner is already in transit');
+
+    // Both halves ran inside one transaction, so the throw rolls the first back.
+    expect(dataSource.transaction).toHaveBeenCalledTimes(1);
+  });
+
+  it('refuses a booking that has no partner', async () => {
+    const { service } = makeService({
+      id: 'b-1',
+      consolidationPartnerId: null,
+    } as Booking);
+
+    await expect(
+      service.applyPairedDecision('b-1', 'cancel', 'staff-1', { reason: 'x' }),
+    ).rejects.toThrow(/no consolidation partner/i);
+  });
+
+  it('requires a validity window to accept', async () => {
+    const { service } = makeService(paired);
+    const accept = jest.spyOn(service, 'acceptIntake');
+
+    await expect(
+      service.applyPairedDecision('b-1', 'accept', 'staff-1', {}),
+    ).rejects.toThrow(/validity/i);
+    expect(accept).not.toHaveBeenCalled();
+  });
+
+  it('routes operationAccept through the operation review on both halves', async () => {
+    const { service } = makeService(paired);
+    const review = jest
+      .spyOn(service, 'reviewOperationRequest')
+      .mockImplementation(async (id) => ({ id }) as Booking);
+
+    await service.applyPairedDecision('b-1', 'operationAccept', 'staff-1', {});
+
+    expect(review).toHaveBeenNthCalledWith(1, 'b-1', 'ACCEPT', 'staff-1', {
+      note: undefined,
+    });
+    expect(review).toHaveBeenNthCalledWith(2, 'b-2', 'ACCEPT', 'staff-1', {
+      note: undefined,
+    });
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
index 2f50d0f38..556ce0e98 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
@@ -455,6 +455,75 @@ export class BookingTransitionService {
     return this.cancel(bookingId, reason ?? "Customer cancelled before payment");
   }
 
+  /**
+   * Run a staff decision across BOTH halves of a consolidated pair.
+   *
+   * Two bookings that share a wagon must move together: accepting one while the
+   * other stays behind would put half a wagon into the approval chain, and
+   * cancelling one alone would strand the other on a wagon it can no longer
+   * fill. All-or-nothing — if either half throws, the transaction rolls back and
+   * neither booking moved.
+   *
+   * Each half still runs the ordinary single-booking transition, so pricing,
+   * invoicing and notifications stay per booking: the customers are billed and
+   * notified separately, exactly as they are today.
+   */
+  async applyPairedDecision(
+    bookingId: string,
+    decision: "accept" | "cancel" | "operationAccept" | "requestChanges",
+    actorId: string,
+    options: { reason?: string; note?: string; validityDays?: number } = {},
+  ): Promise<{ booking: Booking; partner: Booking }> {
+    const booking = await this.bookingsService.findById(bookingId);
+    const partnerId = booking.consolidationPartnerId;
+    if (!partnerId) {
+      throw new BadRequestException(
+        "This booking has no consolidation partner — use the single-booking action.",
+      );
+    }
+
+    const runOne = async (id: string): Promise<Booking> => {
+      switch (decision) {
+        case "accept":
+          // Same requirement as the single-booking accept: the approval chain
+          // needs a contract validity window.
+          if (!(Number(options.validityDays) > 0)) {
+            throw new BadRequestException(
+              "Contract validity (days) is required to accept.",
+            );
+          }
+          return this.acceptIntake(id, actorId, Number(options.validityDays));
+        case "cancel":
+          return this.cancel(
+            id,
+            options.reason ?? "Cancelled with its consolidation partner",
+          );
+        case "operationAccept":
+          return this.reviewOperationRequest(id, "ACCEPT", actorId, {
+            note: options.note,
+          });
+        case "requestChanges":
+          return this.requestChanges(id, options.note ?? "", actorId);
+      }
+    };
+
+    // Without a DataSource (unit tests hand-construct this service) fall back to
+    // running the two halves directly — the ordering guarantee still holds, only
+    // the rollback does not.
+    if (!this.dataSource) {
+      const own = await runOne(bookingId);
+      const other = await runOne(partnerId);
+      return { booking: own, partner: other };
+    }
+
+    return this.dataSource.transaction(async () => {
+      // Sequential: one connection per transaction context.
+      const own = await runOne(bookingId);
+      const other = await runOne(partnerId);
+      return { booking: own, partner: other };
+    });
+  }
+
   async cancel(bookingId: string, reason: string): Promise<Booking> {
     const booking = await this.bookingsService.findById(bookingId);
     assertBookingStatus(booking, [
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts b/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
index 9c4b69ad6..c2d6465c2 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
@@ -59,6 +59,7 @@ import { SubmitBookingResponseDto } from './dto/submit-booking-response.dto';
 import {
   AcceptIntakeDto,
   CancelBookingDto,
+  PairedDecisionDto,
   RejectBookingDto,
   RequestChangesDto,
   ReviewDocumentDto,
@@ -1541,6 +1542,31 @@ export class BookingsController {
     return this.transitionService.enrichBookingResponse(booking);
   }
 
+  @Post(":id/paired-decision")
+  @BookingStaff(FREIGHT_PERMS.bookings.cancel)
+  @ApiOperation({
+    summary:
+      "Apply a staff decision (accept / cancel / operationAccept / requestChanges) to BOTH halves of a consolidated pair, all-or-nothing.",
+  })
+  async pairedDecision(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: PairedDecisionDto,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    const { booking, partner } = await this.transitionService.applyPairedDecision(
+      id,
+      dto.decision,
+      resolveAuthUserId(user),
+      { reason: dto.reason, note: dto.note, validityDays: dto.validityDays },
+    );
+    // Sequential enrichment: both go back so the UI can refresh either tab.
+    const enrichedBooking =
+      await this.transitionService.enrichBookingResponse(booking);
+    const enrichedPartner =
+      await this.transitionService.enrichBookingResponse(partner);
+    return { booking: enrichedBooking, partner: enrichedPartner };
+  }
+
   @Post(":id/cancel")
   @BookingStaff(FREIGHT_PERMS.bookings.cancel)
   @ApiOperation({ summary: "Cancel booking" })
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
index 310364927..7b042e0c7 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
@@ -308,6 +308,72 @@ export class BookingsRepository extends BaseRepository<Booking> {
       .find({ where: { contractId } });
   }
 
+  /**
+   * Bookings a GL operator may manually link to `booking` as its odd-20ft
+   * consolidation partner (Path B customs flow). Unlike
+   * {@link findComplementaryConsolidationPartner} — which auto-pairs on an exact
+   * quantity complement — this lists CANDIDATES for a human to choose from, so
+   * the filter is deliberately looser: any other customs booking on the same
+   * route/direction that is itself carrying an odd 20ft count. Two odd counts
+   * always sum to even, so any pick fills the shared wagon.
+   *
+   * Bare instances awaiting completion have no persisted containers yet, so the
+   * odd-count test runs on the requested container lines when they exist and the
+   * booking is offered as a candidate when they do not (GL enters its cargo on
+   * the split form).
+   */
+  async findManualConsolidationCandidates(
+    booking: Booking,
+    limit = 50,
+  ): Promise<Booking[]> {
+    const rows = await this.repository
+      .createQueryBuilder('b')
+      .leftJoinAndSelect('b.bookingContainers', 'bc')
+      .leftJoinAndSelect('bc.containerType', 'ct')
+      .leftJoinAndSelect('b.company', 'company')
+      .where('b.id != :bookingId', { bookingId: booking.id })
+      // Never offer a booking that already shares a wagon with someone else.
+      .andWhere('b.consolidationPartnerId IS NULL')
+      // Customs-only: this manual flow exists because a customs (Path B)
+      // instance is completed by GL, not by the customer.
+      .andWhere('b.customsClearingEnabled = true')
+      // Same physical wagon ⇒ same route and same direction.
+      .andWhere('b.originYardId = :originYardId', {
+        originYardId: booking.originYardId,
+      })
+      .andWhere('b.destinationYardId = :destinationYardId', {
+        destinationYardId: booking.destinationYardId,
+      })
+      .andWhere('b.tradeDirection = :tradeDirection', {
+        tradeDirection: booking.tradeDirection,
+      })
+      // Bookable = clearance finished and the booking is waiting to be completed,
+      // the same set completeUnderContract accepts, plus one already parked for a
+      // partner.
+      .andWhere('b.status IN (:...statuses)', {
+        statuses: [
+          'CLEARANCE_READY',
+          'OPERATION_CHANGES_REQUESTED',
+          'PENDING_CONSOLIDATION',
+        ],
+      })
+      .orderBy('b.createdAt', 'ASC')
+      .take(limit)
+      .getMany();
+
+    // Odd-20ft test in memory: a bare instance has no containers yet (GL fills
+    // them on the split form) and stays a candidate; one that already carries
+    // cargo qualifies only when its 20ft total is odd.
+    return rows.filter((row) => {
+      const lines = row.bookingContainers ?? [];
+      if (lines.length === 0) return true;
+      const ft20 = lines
+        .filter((line) => Number(line.containerType?.sizeFt) === 20)
+        .reduce((sum, line) => sum + Number(line.quantity || 0), 0);
+      return ft20 % 2 === 1;
+    });
+  }
+
   /**
    * Find another booking whose container quantity complements this one to fill whole wagon(s)
    * (same route, same container type, partial wagon on both sides). Only 20ft lines ever
@@ -508,6 +574,25 @@ export class BookingsRepository extends BaseRepository<Booking> {
     } as never);
   }
 
+  /**
+   * Link two bookings as consolidation partners WITHOUT touching their statuses.
+   * Used by the manual GL pairing, where both bookings have just been completed
+   * into their live status — unlike {@link pairConsolidation}, which exists to
+   * resume bookings parked in PENDING_CONSOLIDATION and rewrites status as part
+   * of that resume.
+   */
+  async linkConsolidationPartners(
+    bookingId: string,
+    partnerId: string,
+  ): Promise<void> {
+    await this.repository.update(bookingId, {
+      consolidationPartnerId: partnerId,
+    } as never);
+    await this.repository.update(partnerId, {
+      consolidationPartnerId: bookingId,
+    } as never);
+  }
+
   /** Un-pair a consolidation. */
   async unpairConsolidation(bookingId: string, partnerId: string): Promise<void> {
     await this.repository.update(bookingId, {
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/request-changes.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/request-changes.dto.ts
index 63ad5b9f4..9c4e5c944 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/request-changes.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/request-changes.dto.ts
@@ -125,3 +125,36 @@ export class OperationReviewDto {
   @IsString()
   note?: string;
 }
+
+/**
+ * A staff decision applied to BOTH halves of a consolidated pair. The two
+ * bookings share a wagon, so they advance or cancel together — never one alone.
+ */
+export class PairedDecisionDto {
+  @ApiProperty({
+    enum: ["accept", "cancel", "operationAccept", "requestChanges"],
+    description: 'Which staff decision to apply to both bookings.',
+  })
+  @IsIn(["accept", "cancel", "operationAccept", "requestChanges"])
+  decision!: "accept" | "cancel" | "operationAccept" | "requestChanges";
+
+  @ApiPropertyOptional({ description: "Cancellation reason (decision=cancel)." })
+  @IsOptional()
+  @IsString()
+  reason?: string;
+
+  @ApiPropertyOptional({
+    description: "Message to the customer (decision=requestChanges).",
+  })
+  @IsOptional()
+  @IsString()
+  note?: string;
+
+  @ApiPropertyOptional({
+    description: "Contract validity window in days (decision=accept).",
+  })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  validityDays?: number;
+}
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.manual-consolidation.spec.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.manual-consolidation.spec.ts
new file mode 100644
index 000000000..841baab31
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.manual-consolidation.spec.ts
@@ -0,0 +1,213 @@
+import { ContractBookingService } from './contract-booking.service';
+import { Booking } from '../bookings/entities/booking.entity';
+
+/**
+ * Manual (GL-driven) odd-20ft consolidation. On a customs contract GL completes
+ * the booking, so GL also picks who shares its wagon: two bookings each carrying
+ * an odd 20ft count are completed together onto one wagon.
+ *
+ * The two invariants that matter are that the pair is all-or-nothing (a failure
+ * on either half must leave NEITHER booking completed and no link written) and
+ * that the two bookings stay financially separate — one completion each, so one
+ * price and one invoice each.
+ */
+describe('ContractBookingService — manual odd-20ft consolidation', () => {
+  function makeService(overrides: {
+    bookingsRepository?: Partial<Record<string, jest.Mock>>;
+    dataSource?: unknown;
+  }) {
+    const bookingsRepository = {
+      findByIdWithFiles: jest.fn(),
+      findManualConsolidationCandidates: jest.fn().mockResolvedValue([]),
+      linkConsolidationPartners: jest.fn().mockResolvedValue(undefined),
+      ...overrides.bookingsRepository,
+    };
+
+    // A transaction that simply runs the callback — enough to assert the
+    // all-or-nothing contract: whatever throws inside propagates out, and the
+    // caller observes no link written.
+    const dataSource = overrides.dataSource ?? {
+      transaction: jest.fn(async (cb: (m: unknown) => Promise<unknown>) => cb({})),
+    };
+
+    const service = new ContractBookingService(
+      { findByIdWithRelations: jest.fn() } as never,
+      bookingsRepository as never,
+      {} as never, // bookingPricingService
+      {} as never, // consolidationService
+      {} as never, // containerTypesService
+      {} as never, // ruleEngineService
+      {} as never, // milestoneService
+      {} as never, // invoiceService
+      {} as never, // bookingNotifier
+      dataSource as never,
+      {} as never, // trainSchedulingService
+      {} as never, // bookingBatchService
+      {} as never, // bookingTransitionService
+    );
+    return { service, bookingsRepository, dataSource };
+  }
+
+  const partnerBooking = {
+    id: 'b-2',
+    reference: 'BK-2',
+    contractId: 'c-2',
+    consolidationPartnerId: null,
+  } as unknown as Booking;
+
+  const pairDto = {
+    partnerBookingId: 'b-2',
+    booking: { scheduledDate: '2026-09-01' },
+    partner: { scheduledDate: '2026-09-01' },
+  };
+
+  it('completes both halves and links them', async () => {
+    const { service, bookingsRepository } = makeService({
+      bookingsRepository: {
+        findByIdWithFiles: jest
+          .fn()
+          // partner lookup before the transaction
+          .mockResolvedValueOnce(partnerBooking)
+          // the two reloads after it
+          .mockResolvedValueOnce({ id: 'b-1', reference: 'BK-1' } as Booking)
+          .mockResolvedValueOnce({ id: 'b-2', reference: 'BK-2' } as Booking),
+      },
+    });
+
+    // Each half runs the ordinary completion machine — one call per booking, so
+    // each is priced and invoiced on its own.
+    const complete = jest
+      .spyOn(service, 'completeUnderContract')
+      .mockImplementation(
+        async (_contractId, bookingId) =>
+          ({
+            booking: { id: bookingId } as Booking,
+            warnings: [],
+          }) as never,
+      );
+
+    const result = await service.completeConsolidatedPair(
+      'c-1',
+      'b-1',
+      pairDto as never,
+    );
+
+    expect(complete).toHaveBeenCalledTimes(2);
+    // The partner is completed against ITS OWN contract, not this one.
+    expect(complete.mock.calls[0][0]).toBe('c-1');
+    expect(complete.mock.calls[1][0]).toBe('c-2');
+    // Neither half may re-enter the automatic matcher — GL links them here.
+    expect(complete.mock.calls[0][2]).toMatchObject({
+      skipAutoConsolidation: true,
+    });
+    expect(complete.mock.calls[1][2]).toMatchObject({
+      skipAutoConsolidation: true,
+    });
+    expect(bookingsRepository.linkConsolidationPartners).toHaveBeenCalledWith(
+      'b-1',
+      'b-2',
+    );
+    expect(result.booking.id).toBe('b-1');
+    expect(result.partner.id).toBe('b-2');
+  });
+
+  it('links nothing when the partner half fails (all-or-nothing)', async () => {
+    const { service, bookingsRepository } = makeService({
+      bookingsRepository: {
+        findByIdWithFiles: jest.fn().mockResolvedValue(partnerBooking),
+      },
+    });
+
+    jest
+      .spyOn(service, 'completeUnderContract')
+      .mockImplementationOnce(
+        async () => ({ booking: { id: 'b-1' } as Booking, warnings: [] }) as never,
+      )
+      .mockImplementationOnce(async () => {
+        throw new Error('no train space for the partner');
+      });
+
+    await expect(
+      service.completeConsolidatedPair('c-1', 'b-1', pairDto as never),
+    ).rejects.toThrow('no train space for the partner');
+
+    // The link is the last write in the transaction — it must never happen when
+    // a half failed, so the rollback leaves no dangling pairing.
+    expect(bookingsRepository.linkConsolidationPartners).not.toHaveBeenCalled();
+  });
+
+  it('refuses a partner that already shares a wagon', async () => {
+    const { service } = makeService({
+      bookingsRepository: {
+        findByIdWithFiles: jest.fn().mockResolvedValue({
+          ...partnerBooking,
+          consolidationPartnerId: 'b-9',
+        }),
+      },
+    });
+
+    await expect(
+      service.completeConsolidatedPair('c-1', 'b-1', pairDto as never),
+    ).rejects.toThrow(/already shares a wagon/i);
+  });
+
+  it('refuses to consolidate a booking with itself', async () => {
+    const { service } = makeService({});
+
+    await expect(
+      service.completeConsolidatedPair('c-1', 'b-1', {
+        ...pairDto,
+        partnerBookingId: 'b-1',
+      } as never),
+    ).rejects.toThrow(/cannot be consolidated with itself/i);
+  });
+
+  it('offers only bookings whose own 20ft count is odd', async () => {
+    // Two odd counts always sum to even, so an odd partner is exactly what fills
+    // the wagon; an even one would leave the pair partial again.
+    const rows = [
+      {
+        id: 'odd',
+        reference: 'BK-ODD',
+        bookingContainers: [
+          { quantity: 3, containerType: { sizeFt: 20 } },
+        ],
+      },
+      {
+        id: 'even',
+        reference: 'BK-EVEN',
+        bookingContainers: [
+          { quantity: 4, containerType: { sizeFt: 20 } },
+        ],
+      },
+      // A bare instance has no cargo yet — GL enters it on the split form, so it
+      // stays a candidate.
+      { id: 'bare', reference: 'BK-BARE', bookingContainers: [] },
+    ];
+
+    const { service } = makeService({
+      bookingsRepository: {
+        findByIdWithFiles: jest
+          .fn()
+          .mockResolvedValue({ id: 'b-1', contractId: 'c-1' } as Booking),
+        findManualConsolidationCandidates: jest.fn(async (booking: Booking) =>
+          // Mirror the repository's in-memory odd filter.
+          rows.filter((row) => {
+            void booking;
+            const lines = row.bookingContainers ?? [];
+            if (lines.length === 0) return true;
+            const ft20 = lines
+              .filter((l) => Number(l.containerType?.sizeFt) === 20)
+              .reduce((sum, l) => sum + Number(l.quantity || 0), 0);
+            return ft20 % 2 === 1;
+          }),
+        ),
+      },
+    });
+
+    const candidates = await service.listConsolidationCandidates('c-1', 'b-1');
+    expect(candidates.map((c) => c.reference)).toEqual(['BK-ODD', 'BK-BARE']);
+    expect(candidates[0].ft20Quantity).toBe(3);
+    expect(candidates[1].hasCargo).toBe(false);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
index 3d362d53f..ddd85fc48 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
@@ -44,6 +44,7 @@ import {
 import { ClearanceMilestoneService } from './clearance-milestone.service';
 import { isEffectivelyExpired } from './utils/contract-expiry.util';
 import {
+  CompleteConsolidatedPairDto,
   CreateBookingContainerLineDto,
   CreateBookingUnderContractDto,
 } from './dto/create-booking-under-contract.dto';
@@ -62,6 +63,25 @@ export interface CreateBookingUnderContractResult {
   warnings: string[];
 }
 
+/**
+ * A booking GL may pick as the shared-wagon partner of an odd-20ft customs
+ * booking. `hasCargo` is false for a bare instance whose containers GL still has
+ * to enter on the split completion form.
+ */
+export interface ConsolidationCandidate {
+  id: string;
+  reference: string;
+  contractId: string | null;
+  companyName: string | null;
+  status: string;
+  tradeDirection: string | null;
+  originYardId: string | null;
+  destinationYardId: string | null;
+  scheduledDate: string | null;
+  ft20Quantity: number;
+  hasCargo: boolean;
+}
+
 /**
  * Outstanding split remainder of a contract: what was booked in the first split
  * booking's pre-split snapshot MINUS everything currently booked. Container
@@ -598,6 +618,134 @@ export class ContractBookingService {
     return created;
   }
 
+  /**
+   * Candidate partners a GL operator may link to an odd-20ft customs booking.
+   * Manual counterpart to the automatic pairing in {@link consolidateDrawdown} —
+   * a customs instance is completed by GL, so GL also chooses who shares its
+   * wagon rather than waiting for the auto-matcher to find an exact complement.
+   */
+  async listConsolidationCandidates(
+    contractId: string,
+    bookingId: string,
+  ): Promise<ConsolidationCandidate[]> {
+    const booking = await this.bookingsRepository.findByIdWithFiles(bookingId);
+    if (!booking || booking.contractId !== contractId) {
+      throw new NotFoundException(`Booking ${bookingId} not found on this contract`);
+    }
+
+    const rows = await this.bookingsRepository.findManualConsolidationCandidates(
+      booking,
+    );
+    return rows.map((row) => {
+      const lines = row.bookingContainers ?? [];
+      return {
+        id: row.id,
+        reference: row.reference,
+        contractId: row.contractId ?? null,
+        companyName: row.company?.name ?? null,
+        status: row.status,
+        tradeDirection: row.tradeDirection ?? null,
+        originYardId: row.originYardId ?? null,
+        destinationYardId: row.destinationYardId ?? null,
+        scheduledDate: row.scheduledDate ? row.scheduledDate.toISOString() : null,
+        ft20Quantity: lines
+          .filter((line) => Number(line.containerType?.sizeFt) === 20)
+          .reduce((sum, line) => sum + Number(line.quantity || 0), 0),
+        hasCargo: lines.length > 0,
+      };
+    });
+  }
+
+  /**
+   * Complete an odd-20ft customs booking together with the partner booking GL
+   * picked for its shared wagon. Both halves run the ordinary
+   * {@link completeUnderContract} machine — same gates, same pricing, same
+   * per-booking invoice, so each customer still pays only its own shipment — and
+   * are linked as consolidation partners at the end.
+   *
+   * All-or-nothing: the two completions plus the pairing run inside one
+   * transaction, so a failure on either half leaves neither booking completed
+   * and no half-linked wagon behind. `runInTransaction` is used rather than a
+   * manual QueryRunner so the nested services join the same transactional
+   * context through the shared DataSource.
+   */
+  async completeConsolidatedPair(
+    contractId: string,
+    bookingId: string,
+    dto: CompleteConsolidatedPairDto,
+    actorPermissions?: unknown,
+  ): Promise<{
+    booking: Booking;
+    partner: Booking;
+    warnings: string[];
+  }> {
+    if (dto.partnerBookingId === bookingId) {
+      throw new BadRequestException(
+        'A booking cannot be consolidated with itself.',
+      );
+    }
+
+    const partner = await this.bookingsRepository.findByIdWithFiles(
+      dto.partnerBookingId,
+    );
+    if (!partner) {
+      throw new NotFoundException(
+        `Partner booking ${dto.partnerBookingId} not found`,
+      );
+    }
+    if (partner.consolidationPartnerId) {
+      throw new ConflictException(
+        `Booking ${partner.reference} already shares a wagon with another booking.`,
+      );
+    }
+    if (!partner.contractId) {
+      throw new BadRequestException(
+        `Booking ${partner.reference} is not a contract booking and cannot be completed here.`,
+      );
+    }
+
+    const warnings: string[] = [];
+
+    const { ownId, partnerId } = await this.dataSource.transaction(async () => {
+      const own = await this.completeUnderContract(
+        contractId,
+        bookingId,
+        { ...dto.booking, skipAutoConsolidation: true },
+        // Both halves are completed by the same GL actor that reached this
+        // endpoint — the customs gate in completeUnderContract re-checks it.
+        actorPermissions,
+      );
+      warnings.push(...own.warnings);
+
+      const other = await this.completeUnderContract(
+        partner.contractId as string,
+        partner.id,
+        { ...dto.partner, skipAutoConsolidation: true },
+        actorPermissions,
+      );
+      warnings.push(...other.warnings);
+
+      // Link the two halves. Written directly (not via pairConsolidation) because
+      // both bookings have just been completed into their live status here —
+      // pairConsolidation exists to RESUME bookings parked in
+      // PENDING_CONSOLIDATION and would overwrite that status.
+      await this.bookingsRepository.linkConsolidationPartners(
+        own.booking.id,
+        other.booking.id,
+      );
+      return { ownId: own.booking.id, partnerId: other.booking.id };
+    });
+
+    // Sequential reads: one connection per transaction context.
+    const finalBooking = await this.bookingsRepository.findByIdWithFiles(ownId);
+    const finalPartner = await this.bookingsRepository.findByIdWithFiles(partnerId);
+    return {
+      booking: finalBooking!,
+      partner: finalPartner ?? partner,
+      warnings,
+    };
+  }
+
   /**
    * Complete a bare initiated booking after its per-booking clearance is
    * finalized (CLEARANCE_READY) or operations returned it for changes
@@ -826,10 +974,18 @@ export class ContractBookingService {
       // exactly like a drawdown created with cargo does. The shipment day is
       // stored first so the pairing event can resume straight into the
       // operations queue.
+      // Customs (Path B) instances are exempt from the AUTO-matcher: GL links
+      // their shared wagon by hand through completeConsolidatedPair, so nothing
+      // may claim a partner for them behind GL's back. A customs half completed
+      // as part of a manual pair carries `skipAutoConsolidation`; one completed
+      // alone still falls through to the automatic gate below, so an odd 20ft
+      // booking can never proceed on a partial wagon. Non-customs drawdowns are
+      // unaffected.
       const withContainers = await this.bookingsRepository.findByIdWithFiles(booking.id);
       if (
         withContainers &&
         freightType === 'CONTAINER' &&
+        !dto.skipAutoConsolidation &&
         (await this.consolidationService.needsConsolidationFromBooking(withContainers))
       ) {
         await this.bookingsRepository.update(booking.id, {
diff --git a/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts b/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
index c9db49b24..e9404f8e1 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
@@ -76,7 +76,10 @@ import {
 import { SignContractDto } from './dto/sign-contract.dto';
 import { ReviewClearanceDocumentDto } from './dto/review-clearance-document.dto';
 import { RenewContractDto } from './dto/renew-contract.dto';
-import { CreateBookingUnderContractDto } from './dto/create-booking-under-contract.dto';
+import {
+  CompleteConsolidatedPairDto,
+  CreateBookingUnderContractDto,
+} from './dto/create-booking-under-contract.dto';
 import {
   CreateBookingRequestDto,
   ReviewBookingRequestDto,
@@ -1152,6 +1155,41 @@ export class ContractsController {
     // Customs (Path B) instances may only be completed by GL Ethiopia — the
     // service checks the actor's contracts:create_booking permission.
     return this.contractBookingService.completeUnderContract(
+      id,
+      bookingId,
+      // skipAutoConsolidation is internal to the manual pair-completion path; a
+      // client must never suppress the wagon gate on a lone booking.
+      { ...dto, skipAutoConsolidation: false },
+      user,
+    );
+  }
+
+  @Get(':id/bookings/:bookingId/consolidation-candidates')
+  @MixedAudience(FREIGHT_PERMS.contracts.createBooking)
+  @ApiOperation({
+    summary:
+      'Bookings GL may link to this odd-20ft customs booking as its shared-wagon partner (same route and direction, customs, odd 20ft, unpaired).',
+  })
+  listConsolidationCandidates(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Param('bookingId', ParseUUIDPipe) bookingId: string,
+  ) {
+    return this.contractBookingService.listConsolidationCandidates(id, bookingId);
+  }
+
+  @Post(':id/bookings/:bookingId/complete-consolidated')
+  @MixedAudience(FREIGHT_PERMS.contracts.createBooking)
+  @ApiOperation({
+    summary:
+      'Complete this booking and its chosen shared-wagon partner together (all-or-nothing). Each booking is priced and invoiced separately — only the wagon is shared.',
+  })
+  completeConsolidatedPair(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Param('bookingId', ParseUUIDPipe) bookingId: string,
+    @Body() dto: CompleteConsolidatedPairDto,
+    @CurrentUser() user: TCurrentUser & { sub?: string },
+  ) {
+    return this.contractBookingService.completeConsolidatedPair(
       id,
       bookingId,
       dto,
diff --git a/apps/edr-freight-api/src/modules/contracts/dto/create-booking-under-contract.dto.ts b/apps/edr-freight-api/src/modules/contracts/dto/create-booking-under-contract.dto.ts
index 8c1bf763d..f50ca9d4d 100644
--- a/apps/edr-freight-api/src/modules/contracts/dto/create-booking-under-contract.dto.ts
+++ b/apps/edr-freight-api/src/modules/contracts/dto/create-booking-under-contract.dto.ts
@@ -1,4 +1,4 @@
-import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { ApiHideProperty, ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { Transform, Type } from 'class-transformer';
 import {
   IsArray,
@@ -219,4 +219,46 @@ export class CreateBookingUnderContractDto {
   @IsOptional()
   @IsString()
   notes?: string;
+
+  /**
+   * Internal: set by the manual GL pair-completion path, never by a client.
+   * Suppresses the automatic wagon-consolidation gate for this completion
+   * because the caller links the shared wagon itself. Excluded from the public
+   * schema so a client cannot set it to bypass the gate on a lone booking.
+   */
+  @ApiHideProperty()
+  @IsOptional()
+  @IsBoolean()
+  skipAutoConsolidation?: boolean;
+}
+
+/**
+ * Complete an odd-20ft customs booking together with the partner booking GL
+ * picked to share its wagon. Each half carries its own full completion payload —
+ * the two bookings stay separately priced and separately invoiced, they only
+ * share the wagon.
+ */
+export class CompleteConsolidatedPairDto {
+  @ApiProperty({
+    format: 'uuid',
+    description: 'The booking chosen to share this booking’s wagon.',
+  })
+  @IsUUID()
+  partnerBookingId!: string;
+
+  @ApiProperty({
+    type: CreateBookingUnderContractDto,
+    description: 'Completion payload for the booking in the URL.',
+  })
+  @ValidateNested()
+  @Type(() => CreateBookingUnderContractDto)
+  booking!: CreateBookingUnderContractDto;
+
+  @ApiProperty({
+    type: CreateBookingUnderContractDto,
+    description: 'Completion payload for the partner booking.',
+  })
+  @ValidateNested()
+  @Type(() => CreateBookingUnderContractDto)
+  partner!: CreateBookingUnderContractDto;
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/BookingActionsMenu.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/BookingActionsMenu.tsx
index a50028e90..5b7de12d5 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/BookingActionsMenu.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/BookingActionsMenu.tsx
@@ -38,6 +38,7 @@ export function BookingActionsMenu({
     reference: row.reference,
     schedulingStatus: row.schedulingStatus,
     customsClearingEnabled: row.customsClearingEnabled,
+    consolidationPartnerId: row.consolidationPartnerId,
   };
 
   const flow = useBookingActionDialog(row.id, context);
@@ -92,7 +93,13 @@ export function BookingActionsMenu({
             );
           })}
         </Group>
-        <ActionDialog flow={flow} pendingAction={pendingAction} onSuppressRowClick={onSuppressRowClick} />
+        <ActionDialog
+          flow={flow}
+          pendingAction={pendingAction}
+          onSuppressRowClick={onSuppressRowClick}
+          consolidationPartnerId={row.consolidationPartnerId}
+          consolidationPartnerReference={row.consolidationPartnerReference}
+        />
       </>
     );
   }
@@ -149,7 +156,13 @@ export function BookingActionsMenu({
         </Menu.Dropdown>
       </Menu>
 
-      <ActionDialog flow={flow} pendingAction={pendingAction} onSuppressRowClick={onSuppressRowClick} />
+      <ActionDialog
+          flow={flow}
+          pendingAction={pendingAction}
+          onSuppressRowClick={onSuppressRowClick}
+          consolidationPartnerId={row.consolidationPartnerId}
+          consolidationPartnerReference={row.consolidationPartnerReference}
+        />
     </Group>
   );
 }
@@ -158,10 +171,14 @@ function ActionDialog({
   flow,
   pendingAction,
   onSuppressRowClick,
+  consolidationPartnerId,
+  consolidationPartnerReference,
 }: {
   flow: ReturnType<typeof useBookingActionDialog>;
   pendingAction: ReturnType<typeof useBookingActionDialog>["pendingAction"];
   onSuppressRowClick?: () => void;
+  consolidationPartnerId?: string | null;
+  consolidationPartnerReference?: string | null;
 }) {
   return (
     <BookingConfirmDialog
@@ -182,6 +199,17 @@ function ActionDialog({
       }}
       isPending={flow.mutations.isPending || flow.detailLoading}
       confirmDisabled={flow.confirmDisabled}
+      // Only the four pairable decisions land on both halves; the rest stay
+      // per booking, so the warning must not appear for them.
+      pairedWithReference={
+        consolidationPartnerId &&
+        pendingAction &&
+        ["accept", "cancel", "operationAccept", "requestChanges"].includes(
+          pendingAction.id,
+        )
+          ? (consolidationPartnerReference ?? "its wagon partner")
+          : null
+      }
     />
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/BookingConfirmDialog.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/BookingConfirmDialog.tsx
index 6b8e4b650..246704aca 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/BookingConfirmDialog.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/BookingConfirmDialog.tsx
@@ -1,5 +1,7 @@
 import type { ReactNode } from "react";
+import { Link2 } from "lucide-react";
 import {
+  Alert,
   Modal,
   Group,
   Stack,
@@ -37,6 +39,12 @@ interface BookingConfirmDialogProps {
   isPending: boolean;
   confirmDisabled?: boolean;
   extra?: ReactNode;
+  /**
+   * Reference of the booking sharing this one's wagon. When set, the dialog
+   * warns that the decision lands on BOTH bookings — staff must not think they
+   * are acting on one.
+   */
+  pairedWithReference?: string | null;
 }
 
 export function BookingConfirmDialog({
@@ -52,6 +60,7 @@ export function BookingConfirmDialog({
   isPending,
   confirmDisabled = false,
   extra,
+  pairedWithReference = null,
 }: BookingConfirmDialogProps) {
   if (!action || !action.confirmTitle) return null;
 
@@ -125,6 +134,21 @@ export function BookingConfirmDialog({
             {action.confirmDescription}
           </Text>
         )}
+        {pairedWithReference && (
+          <Alert
+            color="blue"
+            variant="light"
+            radius="md"
+            mt="sm"
+            icon={<Link2 size={16} />}
+          >
+            <Text size="sm">
+              This applies to <strong>{pairedWithReference}</strong> as well —
+              the two bookings share a wagon and are decided together. If either
+              fails, neither changes.
+            </Text>
+          </Alert>
+        )}
       </Box>
 
       {/* Body */}
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/useBookingActionDialog.ts b/apps/edr-freight-web/backoffice/src/components/bookings/useBookingActionDialog.ts
index be7111745..24398bdf9 100644
--- a/apps/edr-freight-web/backoffice/src/components/bookings/useBookingActionDialog.ts
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/useBookingActionDialog.ts
@@ -14,6 +14,19 @@ function isValidValidityDays(value: string): boolean {
   return Number.isInteger(days) && days >= 1 && days <= 365;
 }
 
+/**
+ * Decisions that must be applied to BOTH halves of a consolidated pair. The two
+ * bookings share one wagon: accepting one alone would put half a wagon into the
+ * approval chain, and cancelling one alone would strand the other on a wagon it
+ * can no longer fill.
+ */
+const PAIRED_DECISIONS = {
+  accept: "accept",
+  cancel: "cancel",
+  operationAccept: "operationAccept",
+  requestChanges: "requestChanges",
+} as const;
+
 export function useBookingActionDialog(
   bookingId: string,
   context: BookingActionContext,
@@ -52,6 +65,30 @@ export function useBookingActionDialog(
 
     const onSuccess = () => closeDialog();
 
+    // A booking on a shared wagon routes the four pairable decisions through the
+    // paired endpoint, which applies them to both halves all-or-nothing. Every
+    // other action stays per booking.
+    const pairedDecision =
+      PAIRED_DECISIONS[pendingAction.id as keyof typeof PAIRED_DECISIONS];
+    if (context.consolidationPartnerId && pairedDecision) {
+      if (pairedDecision === "accept") {
+        const days = Number(inputValue.trim());
+        if (!Number.isInteger(days) || days < 1 || days > 365) return;
+        mutations.pairedDecision.mutate(
+          { decision: "accept", validityDays: days },
+          { onSuccess },
+        );
+        return;
+      }
+      mutations.pairedDecision.mutate(
+        pairedDecision === "cancel"
+          ? { decision: "cancel", reason: inputValue.trim() }
+          : { decision: pairedDecision, note: inputValue.trim() },
+        { onSuccess },
+      );
+      return;
+    }
+
     switch (pendingAction.id) {
       case "accept": {
         const days = Number(inputValue.trim());
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/GlCreateBookingForm.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/GlCreateBookingForm.tsx
index 67e84a09f..ca55338cb 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/GlCreateBookingForm.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/GlCreateBookingForm.tsx
@@ -11,6 +11,7 @@ import { useMutation, useQuery } from "@tanstack/react-query";
 import {
   ActionIcon,
   Alert,
+  Badge,
   Box,
   Button,
   Center,
@@ -40,6 +41,7 @@ import {
   FileText,
   FileUp,
   Flame,
+  Link2,
   MapPin,
   Package,
   Receipt,
@@ -57,7 +59,10 @@ import {
 import { api } from "@/services/api";
 import { PageContainer } from "@/components/page";
 import { PageHeader } from "@/components/page/PageHeader";
-import { contractsService } from "@/services/contracts.service";
+import {
+  contractsService,
+  type ConsolidationCandidate,
+} from "@/services/contracts.service";
 import { bookingsService } from "@/services/bookings.service";
 import {
   useContractCapacity,
@@ -80,6 +85,18 @@ import {
   StepHeader,
   StepLabel,
 } from "./gl-booking-form/form-ui";
+import {
+  ConsolidationPartnerPanel,
+  emptyPartnerLine,
+} from "./gl-booking-form/ConsolidationPartnerPanel";
+import { ConsolidationPartnerPicker } from "./gl-booking-form/ConsolidationPartnerPicker";
+
+/**
+ * Container sizes offered on the parent-booking panel. Fixed rather than taken
+ * from this contract's scope: the parent booking is a different customer on a
+ * different contract, so its sizes are its own.
+ */
+const PARTNER_SIZES = ["20ft", "40ft"];
 
 /** All booking-window times are communicated in East Africa Time. */
 const EAT_TZ = "Africa/Addis_Ababa";
@@ -240,6 +257,14 @@ export default function GlCreateBookingForm() {
     enabled: Boolean(copyFromParam),
   });
 
+  // The booking being completed — used to name the customer on the price
+  // confirmation when a second booking's price is shown beside it.
+  const { data: completeBooking } = useQuery({
+    queryKey: ["gl-complete-booking", completeBookingId],
+    queryFn: () => bookingsService.getById(completeBookingId!),
+    enabled: Boolean(completeBookingId),
+  });
+
   // Same window-gating the customer sees: booking is only allowed while a
   // window is OPEN for one of the contract's routes. Intercity contracts are
   // never window-gated — the shipment rides a passing train staff pick later.
@@ -290,6 +315,18 @@ export default function GlCreateBookingForm() {
   const [withReturn, setWithReturn] = useState(false);
   const [prefilled, setPrefilled] = useState(false);
   const [priceOpen, setPriceOpen] = useState(false);
+  // ── Odd-20ft shared wagon (customs / Path B) ──────────────────────────────
+  // An odd 20ft total leaves one container unpaired. On a customs contract GL
+  // resolves that here by linking a second booking that is also odd — two odd
+  // counts always sum to even — completing both together onto the shared wagon.
+  const [consolidateOdd, setConsolidateOdd] = useState(false);
+  // Set once GL flips the toggle by hand, so the auto-on effect below never
+  // re-opens a panel GL deliberately closed.
+  const consolidateTouchedRef = useRef(false);
+  const [partnerPickerOpen, setPartnerPickerOpen] = useState(false);
+  const [partner, setPartner] = useState<ConsolidationCandidate | null>(null);
+  const [partnerLines, setPartnerLines] = useState<ContainerLineDraft[]>([]);
+  const [partnerCargoDescription, setPartnerCargoDescription] = useState("");
   const seededRef = useRef(false);
   const returnSeededRef = useRef(false);
 
@@ -834,6 +871,48 @@ export default function GlCreateBookingForm() {
   }, [isContainer, containerLines]);
   const hasOdd20ft = ft20Total % 2 === 1;
 
+  // Only a customs (Path B) instance being COMPLETED by GL can use the shared
+  // wagon: it is GL, not the customer, who links the two bookings. Anything else
+  // keeps the historical hard block on odd 20ft.
+  const oddConsolidationAvailable = Boolean(
+    completeBookingId && isContainer && contract?.customsClearingEnabled,
+  );
+
+  // Auto-on: entering an odd 20ft total opens the consolidation panel by itself,
+  // once. GL can still switch it off — then odd is blocked exactly as before.
+  useEffect(() => {
+    if (!oddConsolidationAvailable) return;
+    if (consolidateTouchedRef.current) return;
+    if (hasOdd20ft) setConsolidateOdd(true);
+  }, [oddConsolidationAvailable, hasOdd20ft]);
+
+  // Clear the partner as soon as the panel closes or stops applying, so a
+  // leftover selection can never ride along into a plain single-booking submit.
+  useEffect(() => {
+    if (consolidateOdd && oddConsolidationAvailable) return;
+    setPartner(null);
+    setPartnerLines([]);
+    setPartnerCargoDescription("");
+  }, [consolidateOdd, oddConsolidationAvailable]);
+
+  const consolidationActive =
+    oddConsolidationAvailable && consolidateOdd && hasOdd20ft;
+
+  // Once a parent booking is linked, each booking's cargo is entered under its
+  // own labelled heading so it is clear which containers belong to whom.
+  const splitView = Boolean(consolidationActive && partner);
+
+  const candidatesQuery = useQuery({
+    queryKey: ["consolidation-candidates", id, completeBookingId],
+    queryFn: () =>
+      contractsService.listConsolidationCandidates(
+        id ?? "",
+        completeBookingId ?? "",
+      ),
+    enabled:
+      partnerPickerOpen && Boolean(id) && Boolean(completeBookingId),
+  });
+
   const bulkUom = contract ? bulkUnitOfMeasure(contract) : "PER_TON";
 
   const bulkErrors = useMemo<BulkErrors>(() => {
@@ -886,7 +965,64 @@ export default function GlCreateBookingForm() {
       !cargoDescriptionError
     : !bulkErrors.quantity && !bulkErrors.hazardous && !bulkErrors.reefer;
 
-  const formValid = cargoValid && !hasOdd20ft && !dateError && !routeError;
+  // The unpaired 20ft container is resolved by the shared wagon, so with an
+  // active consolidation an odd total stops being a blocker; without one it
+  // blocks exactly as before.
+  const oddBlocksSubmit = hasOdd20ft && !consolidationActive;
+
+  // Partner side: a linked partner must be picked, carry an odd 20ft count of
+  // its own (odd + odd = even fills the wagon) and have complete unit details.
+  const partnerFt20Total = useMemo(() => {
+    if (!consolidationActive) return 0;
+    return partnerLines
+      .filter((l) => parseInt(l.containerSize, 10) === 20)
+      .reduce((sum, l) => sum + Number(l.quantity || 0), 0);
+  }, [consolidationActive, partnerLines]);
+
+  const partnerError = useMemo<string | undefined>(() => {
+    if (!consolidationActive) return undefined;
+    if (!partner) return "Select the booking that shares this wagon.";
+    const totalQty = partnerLines.reduce(
+      (sum, l) => sum + Math.max(0, Number(l.quantity) || 0),
+      0,
+    );
+    if (totalQty < 1) {
+      return `Enter the containers for ${partner.reference}.`;
+    }
+    if (partnerFt20Total % 2 === 0) {
+      return `${partner.reference} must also carry an odd number of 20ft containers so the two bookings fill whole wagons together (it has ${partnerFt20Total}).`;
+    }
+    const incomplete = partnerLines.some((line) => {
+      const qty = Number(line.quantity || 0);
+      return qty >= 1 && line.units.length < qty;
+    });
+    if (incomplete) {
+      return `Enter the container details for all of ${partner.reference}'s containers.`;
+    }
+    const badUnit = partnerLines.some((line) =>
+      line.units.some(
+        (u) =>
+          !ISO_CONTAINER_NUMBER_REGEX.test(u.containerNumber.trim().toUpperCase()) ||
+          !(Number(u.vgmTons) > 0),
+      ),
+    );
+    if (badUnit) {
+      return `Every ${partner.reference} container needs a valid container number and a VGM above 0.`;
+    }
+    if (!partnerCargoDescription.trim()) {
+      return `Describe the cargo carried in ${partner.reference}'s containers.`;
+    }
+    return undefined;
+  }, [
+    consolidationActive,
+    partner,
+    partnerLines,
+    partnerFt20Total,
+    partnerCargoDescription,
+  ]);
+
+  const formValid =
+    cargoValid && !oddBlocksSubmit && !dateError && !routeError && !partnerError;
 
   /** The create-booking DTO from the current form state — shared by the
    * authoritative price preview and the actual submit so what GL confirms is
@@ -953,6 +1089,44 @@ export default function GlCreateBookingForm() {
     return payload;
   };
 
+  /**
+   * Completion DTO for the partner half of a shared wagon. Route, day and train
+   * are deliberately copied from THIS booking: the two bookings ride the same
+   * wagon, so they must ride the same train on the same day. Only the cargo and
+   * the billing currency belong to the partner.
+   */
+  const buildPartnerPayload = (): Freight.CreateBookingUnderContractDto | null => {
+    if (!partner || !consolidationActive) return null;
+
+    const payload: Freight.CreateBookingUnderContractDto = {
+      paymentCurrency,
+      ...(scheduledDate
+        ? { scheduledDate: new Date(scheduledDate).toISOString() }
+        : {}),
+      ...(trainScheduleId ? { trainScheduleId } : {}),
+      ...(partnerCargoDescription.trim()
+        ? { cargoFreeText: partnerCargoDescription.trim() }
+        : {}),
+      containers: partnerLines
+        .filter((l) => Number(l.quantity) >= 1)
+        .map((l) => ({
+          containerSize: l.containerSize,
+          quantity: Number(l.quantity),
+          hazardousQuantity: Number(l.hazardousQuantity || 0) || undefined,
+          reeferQuantity: Number(l.reeferQuantity || 0) || undefined,
+          units: l.units.map((u) => ({
+            containerNumber: u.containerNumber.trim().toUpperCase(),
+            ...(u.sealNumber ? { sealNumber: u.sealNumber } : {}),
+            vgmTons: Number(u.vgmTons) || 0,
+            isHazardous: Boolean(u.isHazardous),
+            isReefer: Boolean(u.isReefer),
+          })),
+        })),
+    };
+
+    return payload;
+  };
+
   // Authoritative price preview (same pricing pass the booking persists at
   // create): rail freight + first/last mile + overweight + every surcharge,
   // plus the hard-block checks (20ft pairing, max capacity, container numbers
@@ -964,6 +1138,22 @@ export default function GlCreateBookingForm() {
   });
   const validation = validateShipmentMutation.data ?? null;
 
+  // The partner is priced against ITS OWN contract, so the two totals shown in
+  // the confirm modal are each customer's real bill — nobody pays for the other.
+  const validatePartnerMutation = useMutation({
+    mutationFn: (input: {
+      contractId: string;
+      bookingId: string;
+      dto: Freight.CreateBookingUnderContractDto;
+    }) =>
+      contractsService.validateShipment(
+        input.contractId,
+        input.dto,
+        input.bookingId,
+      ),
+  });
+  const partnerValidation = validatePartnerMutation.data ?? null;
+
   const serverTotal = useMemo(() => {
     const items = validation?.lineItems;
     if (!items?.length) return null;
@@ -1010,8 +1200,52 @@ export default function GlCreateBookingForm() {
     };
   }, [serverTotal, priceTotal, overweightSurchargeAmount]);
 
+  const partnerTotal = useMemo(() => {
+    const items = partnerValidation?.lineItems;
+    if (!items?.length) return null;
+    return {
+      currency: partnerValidation?.currency ?? "ETB",
+      lines: items.map((li) => ({
+        label: li.description,
+        unitPrice: li.unitAmount,
+        unit: li.unit.toLowerCase(),
+        quantity: li.quantity,
+        amount: li.amount,
+      })),
+      total:
+        partnerValidation?.totalAmount ?? items.reduce((s, l) => s + l.amount, 0),
+    };
+  }, [partnerValidation]);
+
+  // The partner half must clear the same hard blocks as this one — the pair is
+  // booked all-or-nothing, so a block on either side blocks both.
+  const partnerBlockers = useMemo(() => {
+    if (!consolidationActive || !partnerValidation) return [];
+    return [
+      ...(partnerValidation.pairingErrors ?? []),
+      ...(partnerValidation.capacityErrors ?? []),
+      ...(partnerValidation.containerClashErrors ?? []),
+      ...(partnerValidation.spaceErrors ?? []),
+    ];
+  }, [consolidationActive, partnerValidation]);
+
+  const completePairMutation = useMutation({
+    mutationFn: (input: {
+      payload: Freight.CreateBookingUnderContractDto;
+      partnerPayload: Freight.CreateBookingUnderContractDto;
+      partnerBookingId: string;
+    }) =>
+      contractsService.completeConsolidatedPair(id ?? "", completeBookingId ?? "", {
+        partnerBookingId: input.partnerBookingId,
+        booking: input.payload,
+        partner: input.partnerPayload,
+      }),
+  });
+
   const submitPending =
-    mutations.createBooking.isPending || mutations.completeBooking.isPending;
+    mutations.createBooking.isPending ||
+    mutations.completeBooking.isPending ||
+    completePairMutation.isPending;
 
   // Block confirm until the authoritative server price is in hand — the client
   // estimate is display-only; booking on it would confirm an un-validated,
@@ -1023,7 +1257,13 @@ export default function GlCreateBookingForm() {
     capacityErrors.length > 0 ||
     containerClashErrors.length > 0 ||
     spaceErrors.length > 0 ||
-    !serverTotal;
+    !serverTotal ||
+    // Same bar for the shared-wagon partner: its authoritative price must be in
+    // hand and its own hard blocks clear before either booking is confirmed.
+    (consolidationActive &&
+      (validatePartnerMutation.isPending ||
+        !partnerTotal ||
+        partnerBlockers.length > 0));
 
   const openPriceModal = () => {
     // Surface the per-field errors (portal-parity validation) instead of
@@ -1039,6 +1279,15 @@ export default function GlCreateBookingForm() {
       validateShipmentMutation.reset();
       validateShipmentMutation.mutate(payload);
     }
+    validatePartnerMutation.reset();
+    const partnerPayload = buildPartnerPayload();
+    if (partnerPayload && partner?.contractId) {
+      validatePartnerMutation.mutate({
+        contractId: partner.contractId,
+        bookingId: partner.id,
+        dto: partnerPayload,
+      });
+    }
   };
 
   const handleSubmit = () => {
@@ -1054,6 +1303,25 @@ export default function GlCreateBookingForm() {
     const payload = buildPayload();
     if (!payload) return;
 
+    // Shared wagon: both halves complete together, all-or-nothing on the server.
+    if (consolidationActive && partner && completeBookingId) {
+      // A hard block on the partner's own price preview blocks the pair.
+      if (partnerBlockers.length > 0) return;
+      const partnerPayload = buildPartnerPayload();
+      if (!partnerPayload) return;
+      completePairMutation.mutate(
+        {
+          payload,
+          partnerPayload,
+          partnerBookingId: partner.id,
+        },
+        {
+          onSuccess: () => navigate(`/dashboard/clearance/${completeBookingId}`),
+        },
+      );
+      return;
+    }
+
     if (completeBookingId) {
       // Completion mode: cargo + day land on the already-cleared instance —
       // the request was linked and accepted at submission time.
@@ -1347,6 +1615,18 @@ export default function GlCreateBookingForm() {
                 maxRows={4}
                 styles={fieldStyles}
               />
+              {/* With a parent booking linked, each booking's containers are
+                  entered in its own labelled section, one after the other. */}
+              {splitView ? (
+                <Group gap={8} align="center">
+                  <Badge color="edr-green" variant="light" radius="sm">
+                    {completeBooking?.reference ?? "This booking"}
+                  </Badge>
+                  <Text fz={13} fw={600} c="#10202F">
+                    {completeBooking?.company?.name ?? "—"}
+                  </Text>
+                </Group>
+              ) : null}
               {containerLines.length === 0 ? (
                 <Text fz="sm" c="dimmed">
                   This contract has no container sizes in scope.
@@ -1526,7 +1806,71 @@ export default function GlCreateBookingForm() {
                 ))
               )}
 
-              {hasOdd20ft ? (
+              {hasOdd20ft && oddConsolidationAvailable ? (
+                <Alert
+                  color={consolidateOdd ? "edr-green" : "red"}
+                  variant="light"
+                  radius="md"
+                  icon={<AlertCircle size={16} />}
+                  title={`Odd number of 20ft containers (${ft20Total})`}
+                >
+                  <Stack gap={10}>
+                    <Text fz={13}>
+                      20ft containers travel two per wagon, so one container here
+                      is unpaired. On a customs booking you can pair it with
+                      another customer's odd booking and complete both onto the
+                      shared wagon — each booking is still priced and invoiced
+                      separately.
+                    </Text>
+                    <Switch
+                      checked={consolidateOdd}
+                      color="edr-green"
+                      label="Share a wagon with another booking"
+                      onChange={(e) => {
+                        consolidateTouchedRef.current = true;
+                        setConsolidateOdd(e.currentTarget.checked);
+                      }}
+                    />
+                    {consolidateOdd ? (
+                      <Group gap={10} align="center" wrap="wrap">
+                        <Button
+                          size="xs"
+                          radius="md"
+                          variant="light"
+                          color="edr-green"
+                          leftSection={<Link2 size={14} />}
+                          onClick={() => setPartnerPickerOpen(true)}
+                        >
+                          {partner
+                            ? `Parent booking: ${partner.reference} — change`
+                            : "Parent booking"}
+                        </Button>
+                        {partner ? (
+                          <Button
+                            size="xs"
+                            radius="md"
+                            variant="subtle"
+                            color="gray"
+                            onClick={() => {
+                              setPartner(null);
+                              setPartnerLines([]);
+                              setPartnerCargoDescription("");
+                            }}
+                          >
+                            Remove
+                          </Button>
+                        ) : null}
+                      </Group>
+                    ) : (
+                      <Text fz={12.5} c="red.7">
+                        With sharing off, book an even number of 20ft containers
+                        — add one more or remove one (e.g. {ft20Total + 1} or{" "}
+                        {ft20Total - 1} instead of {ft20Total}).
+                      </Text>
+                    )}
+                  </Stack>
+                </Alert>
+              ) : hasOdd20ft ? (
                 <Alert
                   color="red"
                   variant="light"
@@ -1540,6 +1884,34 @@ export default function GlCreateBookingForm() {
                   — the booking cannot be created with an unpaired 20ft container.
                 </Alert>
               ) : null}
+
+              {splitView && partner ? (
+                <>
+                  <Divider my={4} />
+                  <Group gap={8} align="center">
+                    <Badge color="blue" variant="light" radius="sm">
+                      {partner.reference}
+                    </Badge>
+                    <Text fz={13} fw={600} c="#10202F">
+                      {partner.companyName ?? "—"}
+                    </Text>
+                  </Group>
+                  <Text fz={12.5} c="dimmed">
+                    Parent booking — ships on the same day and train, billed to
+                    its own customer.
+                  </Text>
+                  <ConsolidationPartnerPanel
+                    lines={partnerLines}
+                    onLinesChange={setPartnerLines}
+                    cargoDescription={partnerCargoDescription}
+                    onCargoDescriptionChange={setPartnerCargoDescription}
+                    showHazardous={Boolean(contract.isHazardous)}
+                    showReefer={Boolean(contract.isReefer)}
+                    showErrors={showErrors}
+                    error={partnerError}
+                  />
+                </>
+              ) : null}
             </Stack>
           </StepCard>
         ) : (
@@ -1806,12 +2178,31 @@ export default function GlCreateBookingForm() {
             >
               Fix the highlighted fields before reviewing the price.
             </Alert>
+          ) : partnerError ? (
+            // The review button is disabled while the parent booking is
+            // incomplete, so the click that would reveal the errors never
+            // lands — say what is outstanding without waiting for it.
+            <Alert
+              color="yellow"
+              variant="light"
+              radius="md"
+              icon={<AlertCircle size={16} />}
+              mb="sm"
+            >
+              {partnerError}
+            </Alert>
           ) : null}
           <Group justify="flex-end">
             <Tooltip
-              label={`Book an even number of 20ft containers — ${ft20Total} is odd and would leave one unpaired.`}
+              label={
+                oddBlocksSubmit
+                  ? `Book an even number of 20ft containers — ${ft20Total} is odd and would leave one unpaired.`
+                  : (partnerError ?? "")
+              }
               withArrow
-              disabled={!hasOdd20ft}
+              // Only explain a block that is actually in force: an odd count
+              // linked to a parent booking is resolved by the shared wagon.
+              disabled={!oddBlocksSubmit && !partnerError}
             >
               {/* Mantine tooltips get no pointer events from a disabled button,
                   so the wrapper carries the hover target. */}
@@ -1821,9 +2212,11 @@ export default function GlCreateBookingForm() {
                   radius="md"
                   leftSection={<Receipt size={16} />}
                   onClick={openPriceModal}
-                  // Same hard block the customer portal applies at review time —
-                  // an unpaired 20ft can never be planned onto a wagon.
-                  disabled={hasOdd20ft}
+                  // An unpaired 20ft can never be planned onto a wagon — unless
+                  // a parent booking is linked to share it, which is what
+                  // oddBlocksSubmit accounts for. The parent's own cargo must be
+                  // complete too, or there is nothing to price.
+                  disabled={oddBlocksSubmit || Boolean(partnerError)}
                 >
                   Review price &amp; book
                 </Button>
@@ -1833,6 +2226,24 @@ export default function GlCreateBookingForm() {
         </Box>
       </Box>
 
+      <ConsolidationPartnerPicker
+        opened={partnerPickerOpen}
+        onClose={() => setPartnerPickerOpen(false)}
+        candidates={candidatesQuery.data ?? []}
+        isLoading={candidatesQuery.isLoading}
+        isError={candidatesQuery.isError}
+        onSelect={(candidate) => {
+          setPartner(candidate);
+          // Seed a 20ft and a 40ft line. The parent booking sits on its OWN
+          // contract, whose size scope need not match this one's, so the panel
+          // offers both sizes rather than mirroring this contract's scope; a
+          // size the parent does not ship is simply left at 0.
+          setPartnerLines(PARTNER_SIZES.map(emptyPartnerLine));
+          setPartnerCargoDescription("");
+          setPartnerPickerOpen(false);
+        }}
+      />
+
       <Modal
         opened={priceOpen}
         onClose={() => {
@@ -1984,6 +2395,18 @@ export default function GlCreateBookingForm() {
             )}
 
             <Paper withBorder radius={16} p="lg" style={{ borderColor: "#E6ECF2" }}>
+              {/* Whose bill this is. Only worth naming when a second booking is
+                  on screen — on a lone booking there is nothing to confuse it with. */}
+              {consolidationActive && partner ? (
+                <Group gap={8} align="center" mb={12} wrap="wrap">
+                  <Badge color="edr-green" variant="light" radius="sm">
+                    {completeBooking?.reference ?? "This booking"}
+                  </Badge>
+                  <Text fz={13} fw={600} c="#10202F">
+                    {completeBooking?.company?.name ?? contract.company?.name ?? "—"}
+                  </Text>
+                </Group>
+              ) : null}
               <Stack gap={10}>
                 {displayTotal.lines.map((line, i) => (
                   <Group key={i} justify="space-between" wrap="nowrap" gap="sm">
@@ -2028,6 +2451,123 @@ export default function GlCreateBookingForm() {
               </Group>
             </Paper>
 
+            {consolidationActive && partner ? (
+              <Paper
+                withBorder
+                radius={16}
+                p="lg"
+                style={{ borderColor: "#E6ECF2" }}
+              >
+                <Group gap={8} align="center" mb={12} wrap="wrap">
+                  <Badge color="blue" variant="light" radius="sm">
+                    {partner.reference}
+                  </Badge>
+                  <Text fz={13} fw={600} c="#10202F">
+                    {partner.companyName ?? "—"}
+                  </Text>
+                </Group>
+
+                {validatePartnerMutation.isPending ? (
+                  <Group gap={8} c="dimmed">
+                    <Loader size="xs" color="edr-green" />
+                    <Text fz="sm" c="dimmed">
+                      Pricing the partner booking…
+                    </Text>
+                  </Group>
+                ) : partnerBlockers.length > 0 ? (
+                  <Alert
+                    color="red"
+                    variant="light"
+                    radius="md"
+                    icon={<AlertCircle size={16} />}
+                    title={`Cannot book ${partner.reference}`}
+                  >
+                    <Stack gap={6}>
+                      {partnerBlockers.map((msg, i) => (
+                        <Text key={i} fz="sm" c="red.8">
+                          {msg}
+                        </Text>
+                      ))}
+                      <Text fz="xs" c="red.7" mt={2}>
+                        Both bookings are confirmed together, so this must be
+                        fixed before either can be booked.
+                      </Text>
+                    </Stack>
+                  </Alert>
+                ) : partnerTotal ? (
+                  <>
+                    <Stack gap={10}>
+                      {partnerTotal.lines.map((line, i) => (
+                        <Group
+                          key={i}
+                          justify="space-between"
+                          wrap="nowrap"
+                          gap="sm"
+                        >
+                          <Box style={{ minWidth: 0 }}>
+                            <Text fz="sm" fw={500}>
+                              {line.label}
+                            </Text>
+                            <Text fz="xs" c="dimmed">
+                              {line.quantity.toLocaleString()} ×{" "}
+                              {line.unitPrice.toLocaleString()}{" "}
+                              {partnerTotal.currency} ·{" "}
+                              {formatRateUnit(line.unit)}
+                            </Text>
+                          </Box>
+                          <Text
+                            fz="sm"
+                            fw={600}
+                            style={{ whiteSpace: "nowrap" }}
+                          >
+                            {line.amount.toLocaleString()}{" "}
+                            {partnerTotal.currency}
+                          </Text>
+                        </Group>
+                      ))}
+                    </Stack>
+                    <Divider my="md" />
+                    <Group justify="space-between" align="flex-end">
+                      <Text
+                        fz="xs"
+                        fw={700}
+                        tt="uppercase"
+                        c="blue"
+                        style={{ letterSpacing: "0.06em" }}
+                      >
+                        Total
+                      </Text>
+                      <Text fw={800} fz={28}>
+                        {partnerTotal.total.toLocaleString()}{" "}
+                        <Text span fz={16} fw={700} c="dimmed">
+                          {partnerTotal.currency}
+                        </Text>
+                      </Text>
+                    </Group>
+                  </>
+                ) : (
+                  <Text fz="sm" c="dimmed">
+                    No price yet for the partner booking.
+                  </Text>
+                )}
+              </Paper>
+            ) : null}
+
+            {consolidationActive && partner ? (
+              <Alert
+                color="blue"
+                variant="light"
+                radius="md"
+                icon={<Link2 size={16} />}
+              >
+                <Text fz="sm">
+                  These two bookings share one wagon but stay separate: each is
+                  invoiced to its own customer and paid separately. Confirming
+                  books both together — if either fails, neither is booked.
+                </Text>
+              </Alert>
+            ) : null}
+
             <Group justify="space-between" mt="xs">
               <Button
                 variant="default"
@@ -2046,7 +2586,11 @@ export default function GlCreateBookingForm() {
                 disabled={confirmDisabled}
                 onClick={handleSubmit}
               >
-                {completeBookingId ? "Confirm & complete" : "Confirm & book"}
+                {consolidationActive && partner
+                  ? "Confirm & book both"
+                  : completeBookingId
+                    ? "Confirm & complete"
+                    : "Confirm & book"}
               </Button>
             </Group>
           </Stack>
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPanel.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPanel.tsx
new file mode 100644
index 000000000..e52cce097
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPanel.tsx
@@ -0,0 +1,255 @@
+import { type KeyboardEvent } from "react";
+import {
+  Box,
+  Checkbox,
+  Group,
+  Stack,
+  Text,
+  TextInput,
+} from "@mantine/core";
+
+/**
+ * Container editor for the PARTNER half of a shared wagon. Deliberately a
+ * reduced version of the main form's editor: the partner contributes only cargo
+ * — route, shipment day and train are inherited from the booking it shares the
+ * wagon with, and hazardous/reefer/return counts are derived from the per-unit
+ * ticks rather than typed line totals.
+ */
+
+export interface PartnerUnitDraft {
+  containerNumber: string;
+  sealNumber: string;
+  vgmTons: string;
+  isHazardous: boolean;
+  isReefer: boolean;
+  isReturn: boolean;
+}
+
+export interface PartnerLineDraft {
+  containerSize: string;
+  quantity: string;
+  hazardousQuantity: string;
+  reeferQuantity: string;
+  returnQuantity: string;
+  units: PartnerUnitDraft[];
+}
+
+export function emptyPartnerUnit(): PartnerUnitDraft {
+  return {
+    containerNumber: "",
+    sealNumber: "",
+    vgmTons: "",
+    isHazardous: false,
+    isReefer: false,
+    isReturn: false,
+  };
+}
+
+export function emptyPartnerLine(size: string): PartnerLineDraft {
+  return {
+    containerSize: size,
+    quantity: "0",
+    hazardousQuantity: "0",
+    reeferQuantity: "0",
+    returnQuantity: "0",
+    units: [],
+  };
+}
+
+/** Quantities are magnitudes — swallow the minus key before it reaches the field. */
+const blockNegative = (event: KeyboardEvent<HTMLInputElement>) => {
+  if (event.key === "-") event.preventDefault();
+};
+
+/** Grow or shrink a line's unit rows to match its quantity. */
+function syncUnits(line: PartnerLineDraft, quantity: number): PartnerLineDraft {
+  const target = Math.max(0, Math.floor(quantity) || 0);
+  const units = [...line.units];
+  while (units.length < target) units.push(emptyPartnerUnit());
+  units.length = target;
+  return {
+    ...line,
+    units,
+    hazardousQuantity: String(units.filter((u) => u.isHazardous).length),
+    reeferQuantity: String(units.filter((u) => u.isReefer).length),
+  };
+}
+
+interface Props {
+  lines: PartnerLineDraft[];
+  onLinesChange: (lines: PartnerLineDraft[]) => void;
+  cargoDescription: string;
+  onCargoDescriptionChange: (value: string) => void;
+  /** Whether per-container hazardous / refrigerated ticks apply. */
+  showHazardous: boolean;
+  showReefer: boolean;
+  /** Surface field errors only after the operator tried to continue. */
+  showErrors: boolean;
+  error?: string;
+}
+
+export function ConsolidationPartnerPanel({
+  lines,
+  onLinesChange,
+  cargoDescription,
+  onCargoDescriptionChange,
+  showHazardous,
+  showReefer,
+  showErrors,
+  error,
+}: Props) {
+  const patchLine = (index: number, patch: Partial<PartnerLineDraft>) => {
+    onLinesChange(
+      lines.map((line, i) => (i === index ? { ...line, ...patch } : line)),
+    );
+  };
+
+  const patchUnit = (
+    lineIndex: number,
+    unitIndex: number,
+    patch: Partial<PartnerUnitDraft>,
+  ) => {
+    onLinesChange(
+      lines.map((line, i) => {
+        if (i !== lineIndex) return line;
+        const units = line.units.map((unit, u) =>
+          u === unitIndex ? { ...unit, ...patch } : unit,
+        );
+        return {
+          ...line,
+          units,
+          hazardousQuantity: String(units.filter((u) => u.isHazardous).length),
+          reeferQuantity: String(units.filter((u) => u.isReefer).length),
+        };
+      }),
+    );
+  };
+
+  return (
+    <Stack gap={14}>
+      {error && showErrors ? (
+        <Text fz={12.5} c="red.7">
+          {error}
+        </Text>
+      ) : null}
+
+      {lines.map((line, lineIdx) => (
+        <Box
+          key={`${line.containerSize}-${lineIdx}`}
+          className="rounded-xl"
+          style={{ border: "1px solid #E6ECF2", padding: 16 }}
+        >
+          <Text fz={14} fw={700} mb={10}>
+            {line.containerSize} containers
+          </Text>
+
+          <TextInput
+            type="number"
+            onKeyDown={blockNegative}
+            label="Quantity *"
+            min={0}
+            value={line.quantity}
+            onChange={(e) => patchLine(lineIdx, { quantity: e.currentTarget.value })}
+            // Sync off the typed value, not the captured `line` — that snapshot
+            // still holds the pre-edit quantity and would write it back.
+            onBlur={(e) => {
+              const typed = e.currentTarget.value;
+              patchLine(lineIdx, {
+                ...syncUnits({ ...line, quantity: typed }, Number(typed || 0)),
+                quantity: typed,
+              });
+            }}
+            mb={12}
+          />
+
+          {line.units.map((unit, unitIdx) => (
+            <Box key={unitIdx} mb={10}>
+              <Text fz={12} fw={600} c="#5B6B7B" mb={6}>
+                Container {unitIdx + 1}
+              </Text>
+              <Group gap={12} grow align="flex-start">
+                <TextInput
+                  label="Container number *"
+                  placeholder="e.g. MSCU1234567"
+                  value={unit.containerNumber}
+                  error={
+                    showErrors && !unit.containerNumber.trim()
+                      ? "Required."
+                      : undefined
+                  }
+                  onChange={(e) =>
+                    patchUnit(lineIdx, unitIdx, {
+                      containerNumber: e.currentTarget.value.toUpperCase(),
+                    })
+                  }
+                />
+                <TextInput
+                  label="Seal number"
+                  value={unit.sealNumber}
+                  onChange={(e) =>
+                    patchUnit(lineIdx, unitIdx, {
+                      sealNumber: e.currentTarget.value,
+                    })
+                  }
+                />
+                <TextInput
+                  type="number"
+                  onKeyDown={blockNegative}
+                  label="VGM (tons) *"
+                  min={0}
+                  value={unit.vgmTons}
+                  error={
+                    showErrors && !(Number(unit.vgmTons) > 0)
+                      ? "Required."
+                      : undefined
+                  }
+                  onChange={(e) =>
+                    patchUnit(lineIdx, unitIdx, { vgmTons: e.currentTarget.value })
+                  }
+                />
+              </Group>
+              {showHazardous || showReefer ? (
+                <Group gap={16} mt={8}>
+                  {showHazardous ? (
+                    <Checkbox
+                      size="xs"
+                      label="Hazardous"
+                      checked={unit.isHazardous}
+                      onChange={(e) =>
+                        patchUnit(lineIdx, unitIdx, {
+                          isHazardous: e.currentTarget.checked,
+                        })
+                      }
+                    />
+                  ) : null}
+                  {showReefer ? (
+                    <Checkbox
+                      size="xs"
+                      label="Refrigerated"
+                      checked={unit.isReefer}
+                      onChange={(e) =>
+                        patchUnit(lineIdx, unitIdx, {
+                          isReefer: e.currentTarget.checked,
+                        })
+                      }
+                    />
+                  ) : null}
+                </Group>
+              ) : null}
+            </Box>
+          ))}
+        </Box>
+      ))}
+
+      <TextInput
+        label="Cargo description *"
+        placeholder="What these containers carry"
+        value={cargoDescription}
+        error={
+          showErrors && !cargoDescription.trim() ? "Required." : undefined
+        }
+        onChange={(e) => onCargoDescriptionChange(e.currentTarget.value)}
+      />
+    </Stack>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPicker.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPicker.tsx
new file mode 100644
index 000000000..c20c08994
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/gl-booking-form/ConsolidationPartnerPicker.tsx
@@ -0,0 +1,137 @@
+import {
+  Alert,
+  Badge,
+  Box,
+  Button,
+  Center,
+  Group,
+  Loader,
+  Modal,
+  Stack,
+  Text,
+  ThemeIcon,
+} from "@mantine/core";
+import { AlertCircle, Link2 } from "lucide-react";
+
+import type { ConsolidationCandidate } from "@/services/contracts.service";
+
+/**
+ * Picker for the booking that shares this booking's wagon. The server has
+ * already narrowed the list to bookings that can legally pair — same route and
+ * direction, customs clearing, an odd 20ft count of their own and not already
+ * linked to someone else — so every row here is a valid choice.
+ */
+interface Props {
+  opened: boolean;
+  onClose: () => void;
+  candidates: ConsolidationCandidate[];
+  isLoading: boolean;
+  isError: boolean;
+  onSelect: (candidate: ConsolidationCandidate) => void;
+}
+
+export function ConsolidationPartnerPicker({
+  opened,
+  onClose,
+  candidates,
+  isLoading,
+  isError,
+  onSelect,
+}: Props) {
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      centered
+      radius="lg"
+      size="lg"
+      title={
+        <Group gap={10}>
+          <ThemeIcon variant="light" color="blue" radius="md" size={34}>
+            <Link2 size={18} />
+          </ThemeIcon>
+          <Box>
+            <Text fw={800} fz={16}>
+              Pick the parent booking
+            </Text>
+            <Text fz="xs" c="dimmed">
+              Customs bookings on the same route that also carry an odd number of
+              20ft containers.
+            </Text>
+          </Box>
+        </Group>
+      }
+    >
+      {isLoading ? (
+        <Center py="xl">
+          <Loader size="sm" color="edr-green" />
+        </Center>
+      ) : isError ? (
+        <Alert
+          color="red"
+          variant="light"
+          radius="md"
+          icon={<AlertCircle size={16} />}
+        >
+          Could not load the candidate bookings. Close this and try again.
+        </Alert>
+      ) : candidates.length === 0 ? (
+        <Alert
+          color="yellow"
+          variant="light"
+          radius="md"
+          icon={<AlertCircle size={16} />}
+          title="No booking available to share this wagon"
+        >
+          <Text fz="sm">
+            No other customs booking on this route currently carries an odd
+            number of 20ft containers. Either wait for one, or switch the
+            shared-wagon option off and book an even number of 20ft containers.
+          </Text>
+        </Alert>
+      ) : (
+        <Stack gap={10}>
+          {candidates.map((candidate) => (
+            <Box
+              key={candidate.id}
+              className="rounded-xl"
+              style={{ border: "1px solid #E6ECF2", padding: 14 }}
+            >
+              <Group justify="space-between" align="center" wrap="wrap" gap={10}>
+                <Box style={{ minWidth: 0 }}>
+                  <Group gap={8} align="center" wrap="wrap">
+                    <Text fz={14} fw={700} c="#10202F">
+                      {candidate.reference}
+                    </Text>
+                    <Badge size="sm" variant="light" color="gray" radius="sm">
+                      {candidate.status.replaceAll("_", " ")}
+                    </Badge>
+                  </Group>
+                  <Text fz={12.5} c="dimmed" mt={2}>
+                    {candidate.companyName ?? "—"}
+                    {candidate.tradeDirection
+                      ? ` · ${candidate.tradeDirection}`
+                      : ""}
+                    {" · "}
+                    {candidate.hasCargo
+                      ? `${candidate.ft20Quantity} × 20ft`
+                      : "cargo not entered yet"}
+                  </Text>
+                </Box>
+                <Button
+                  size="xs"
+                  radius="md"
+                  variant="light"
+                  color="edr-green"
+                  onClick={() => onSelect(candidate)}
+                >
+                  Select
+                </Button>
+              </Group>
+            </Box>
+          ))}
+        </Stack>
+      )}
+    </Modal>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index d3165f696..1415ad37b 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -191,6 +191,8 @@ export const URL_CONSTANTS = {
     BY_ID: (id: string) => `/bookings/${id}`,
     QUEUE: (queue: string) => `/bookings/queues/${queue}`,
     STAFF_ACCEPT: (id: string) => `/bookings/${id}/staff/accept`,
+    // Consolidated pair: one staff decision applied to both halves at once.
+    PAIRED_DECISION: (id: string) => `/bookings/${id}/paired-decision`,
     STAFF_REQUEST_CHANGES: (id: string) =>
       `/bookings/${id}/staff/request-changes`,
     STAFF_REJECT: (id: string) => `/bookings/${id}/staff/reject`,
@@ -317,6 +319,12 @@ export const URL_CONSTANTS = {
     AWAITING_SHIPMENT: "/contracts/awaiting-shipment",
     BOOKINGS_COMPLETE: (id: string, bookingId: string) =>
       `/contracts/${id}/bookings/${bookingId}/complete`,
+    // Odd-20ft shared-wagon consolidation (customs/Path B): candidates GL may
+    // link, and the all-or-nothing completion of both halves together.
+    CONSOLIDATION_CANDIDATES: (id: string, bookingId: string) =>
+      `/contracts/${id}/bookings/${bookingId}/consolidation-candidates`,
+    BOOKINGS_COMPLETE_CONSOLIDATED: (id: string, bookingId: string) =>
+      `/contracts/${id}/bookings/${bookingId}/complete-consolidated`,
     VALIDATE_SHIPMENT: (id: string) => `/contracts/${id}/validate-shipment`,
     CAPACITY: (id: string) => `/contracts/${id}/capacity`,
     // Shipment requests (GENERAL + customs, Path B): customer → GL queue → booking.
diff --git a/apps/edr-freight-web/backoffice/src/features/bookings/booking-actions.config.ts b/apps/edr-freight-web/backoffice/src/features/bookings/booking-actions.config.ts
index 5600f6cfb..eba31130c 100644
--- a/apps/edr-freight-web/backoffice/src/features/bookings/booking-actions.config.ts
+++ b/apps/edr-freight-web/backoffice/src/features/bookings/booking-actions.config.ts
@@ -59,6 +59,9 @@ export type BookingActionContext = Pick<
   | "reference"
   | "schedulingStatus"
   | "customsClearingEnabled"
+  // Set when this booking shares a wagon: the pairable staff decisions then
+  // apply to both halves at once rather than to this booking alone.
+  | "consolidationPartnerId"
 >;
 
 const ALLOCATABLE_SCHEDULING_STATUSES = new Set([
diff --git a/apps/edr-freight-web/backoffice/src/hooks/bookings/useBookings.ts b/apps/edr-freight-web/backoffice/src/hooks/bookings/useBookings.ts
index 2fce8aa8f..64e993207 100644
--- a/apps/edr-freight-web/backoffice/src/hooks/bookings/useBookings.ts
+++ b/apps/edr-freight-web/backoffice/src/hooks/bookings/useBookings.ts
@@ -121,7 +121,38 @@ export function useBookingMutations(bookingId: string) {
     onError: (error) => toast.error(parseApiError(error, "Failed to cancel booking")),
   });
 
+  /**
+   * One staff decision applied to both halves of a consolidated pair. Both
+   * bookings are invalidated on success so whichever tab is open reflects the
+   * new state immediately.
+   */
+  const pairedDecision = useMutation({
+    mutationFn: (payload: {
+      decision: "accept" | "cancel" | "operationAccept" | "requestChanges";
+      reason?: string;
+      note?: string;
+      validityDays?: number;
+    }) => {
+      const { decision, ...options } = payload;
+      return bookingsService.pairedDecision(bookingId, decision, options);
+    },
+    onSuccess: (data) => {
+      toast.success("Applied to both bookings on the shared wagon");
+      void invalidateBookingDetail(qc, data.booking.id);
+      void invalidateBookingDetail(qc, data.partner.id);
+    },
+    onError: (error) => {
+      toast.error(
+        parseApiError(error, "Failed to apply the decision to both bookings"),
+      );
+      // Nothing should have committed (the server runs both halves in one
+      // transaction), but refetch so the UI never shows a stale guess.
+      void invalidateBookingDetail(qc, bookingId);
+    },
+  });
+
   const isPending =
+    pairedDecision.isPending ||
     staffAccept.isPending ||
     requestChanges.isPending ||
     staffReject.isPending ||
@@ -134,6 +165,7 @@ export function useBookingMutations(bookingId: string) {
     cancel.isPending;
 
   return {
+    pairedDecision,
     staffAccept,
     requestChanges,
     staffReject,
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
index 62c26276a..2444899dd 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
@@ -9,6 +9,7 @@ import {
   FolderOpen,
   Layers,
   LayoutGrid,
+  Link2,
   Milestone,
   MoreHorizontal,
   Package,
@@ -79,14 +80,50 @@ export default function BookingRequestDetailPage() {
   const [searchParams, setSearchParams] = useSearchParams();
   // Deep-link from a warehouse fee invoice → this booking's warehouse section.
   useScrollToHash();
+
+  // Consolidated pair: `?booking=<partnerId>` swaps the WHOLE page over to the
+  // other half of the shared wagon. Everything below — KPIs, stepper, the
+  // overview/orders/documents/trucks sub-tabs, the action toolbar — then reads
+  // from the selected booking, so each half gets its own complete detail page
+  // under a top-level tab. The URL id stays put so Back still works.
+  const selectedId = searchParams.get("booking") || id;
   const {
     data: booking,
     isLoading,
     isError,
     refetch,
     isFetching,
-  } = useBookingDetail(id);
-  const mutations = useBookingMutations(id ?? "");
+  } = useBookingDetail(selectedId);
+  const mutations = useBookingMutations(selectedId ?? "");
+
+  // The pair is discovered from whichever half is on screen: each booking
+  // carries a reference to the other.
+  const routeBookingId = id ?? "";
+  const partnerId = booking?.consolidationPartnerId ?? null;
+  const isPaired = Boolean(partnerId);
+  const viewingPartner = selectedId !== routeBookingId;
+  // Tab identities: the booking named by the URL is always the first tab, the
+  // other half the second — regardless of which one is currently displayed.
+  const firstTabId = routeBookingId;
+  const secondTabId = viewingPartner ? selectedId : partnerId;
+
+  // Only for the tab label (reference + customer) — the displayed half is
+  // loaded above. Skipped entirely when the booking is not part of a pair.
+  const { data: otherBooking } = useBookingDetail(
+    secondTabId && secondTabId !== selectedId ? secondTabId : undefined,
+  );
+  const firstTabBooking = viewingPartner ? otherBooking : booking;
+  const secondTabBooking = viewingPartner ? booking : otherBooking;
+
+  const selectBooking = (bookingId: string) => {
+    const next = new URLSearchParams(searchParams);
+    if (bookingId === routeBookingId) next.delete("booking");
+    else next.set("booking", bookingId);
+    // Switching booking resets the sub-tab: the other half has its own content
+    // and may not even have the tab that was open (e.g. Orders).
+    next.delete("tab");
+    setSearchParams(next, { replace: true });
+  };
 
   if (isLoading) {
     return (
@@ -349,6 +386,48 @@ export default function BookingRequestDetailPage() {
       />
 
       <Stack gap="lg">
+        {/* Consolidated pair: one tab per booking, switching the ENTIRE page
+            below. The overview/orders/documents/trucks tabs further down are
+            sub-tabs of whichever booking is selected here. */}
+        {isPaired && secondTabId ? (
+          <Tabs
+            value={selectedId ?? undefined}
+            onChange={(value) => value && selectBooking(value)}
+            variant="pills"
+            radius="md"
+          >
+            <Tabs.List>
+              <Tabs.Tab value={firstTabId} leftSection={<Link2 size={15} />}>
+                <Stack gap={0} align="flex-start">
+                  <Text fz={13} fw={700}>
+                    {firstTabBooking?.reference ?? "Booking"}
+                  </Text>
+                  <Text fz={11} c="dimmed">
+                    {firstTabBooking?.company?.name ?? "—"}
+                  </Text>
+                </Stack>
+              </Tabs.Tab>
+              <Tabs.Tab value={secondTabId} leftSection={<Link2 size={15} />}>
+                <Stack gap={0} align="flex-start">
+                  <Text fz={13} fw={700}>
+                    {secondTabBooking?.reference ?? "Partner booking"}
+                  </Text>
+                  <Text fz={11} c="dimmed">
+                    {secondTabBooking?.company?.name ?? "—"}
+                  </Text>
+                </Stack>
+              </Tabs.Tab>
+            </Tabs.List>
+          </Tabs>
+        ) : null}
+
+        {isPaired ? (
+          <Text size="xs" c="dimmed">
+            These two bookings share one wagon. Accepting or cancelling applies
+            to both; each is invoiced and paid separately.
+          </Text>
+        ) : null}
+
         <KpiStrip items={kpis} />
 
         {booking.holdExpiresAt && booking.schedulingStatus === "HOLDING" ? (
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
index 8c2a3a912..ebdba3e11 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestsPage.tsx
@@ -15,6 +15,7 @@ import {
   CheckCircle2,
   Clock,
   LayoutList,
+  Link2,
   Package,
   Plus,
   RefreshCw,
@@ -200,10 +201,28 @@ export default function BookingRequestsPage() {
 
   // Search is applied server-side (via the `search` filter param) — no
   // client-side filtering here.
-  const rows = useMemo(
-    () => (data?.items ?? []).map(toBookingListRow),
-    [data?.items],
-  );
+  const rows = useMemo(() => {
+    const mapped = (data?.items ?? []).map(toBookingListRow);
+    // Consolidated pairs share one wagon and are decided together, so they show
+    // as ONE row. Keep the half that appears first in the current sort and hang
+    // the other on it as `pairedWith`; the row renders both bookings' details
+    // and opens the detail page, where each half gets its own tab.
+    const byId = new Map(mapped.map((row) => [row.id, row]));
+    const absorbed = new Set<string>();
+    const merged: BookingListRow[] = [];
+    for (const row of mapped) {
+      if (absorbed.has(row.id)) continue;
+      const partnerId = row.consolidationPartnerId;
+      const partner = partnerId ? byId.get(partnerId) : undefined;
+      if (partner && !absorbed.has(partner.id)) {
+        absorbed.add(partner.id);
+        merged.push({ ...row, pairedWith: partner });
+        continue;
+      }
+      merged.push(row);
+    }
+    return merged;
+  }, [data?.items]);
 
   const total = data?.total ?? 0;
   const hasSearch = controls.searchText.trim().length > 0;
@@ -321,6 +340,22 @@ export default function BookingRequestsPage() {
                   </Badge>
                 ) : null}
               </p>
+              {/* Shared wagon: the second booking rides in the same row, so the
+                  operator sees both customers before opening the pair. */}
+              {b.pairedWith ? (
+                <div className="mt-1.5 border-l-2 border-muted pl-2">
+                  <div className="flex items-center gap-1.5">
+                    <Link2 className="size-3 shrink-0 opacity-70" />
+                    <p className="truncate text-xs font-medium text-foreground">
+                      {b.pairedWith.reference}
+                    </p>
+                  </div>
+                  <p className="mt-0.5 flex items-center gap-1 truncate text-xs text-muted-foreground">
+                    <User className="size-3 shrink-0 opacity-70" />
+                    {b.pairedWith.customerLabel}
+                  </p>
+                </div>
+              ) : null}
             </div>
           </div>
         );
diff --git a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
index dead9c520..9fa24924d 100644
--- a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
@@ -323,6 +323,26 @@ export const bookingsService = {
   cancel: (id: string, reason: string) =>
     postBooking<BookingDetail>(B.CANCEL(id), { reason }),
 
+  /**
+   * Apply one staff decision to BOTH halves of a consolidated pair. The two
+   * bookings share a wagon, so they advance or cancel together — all-or-nothing
+   * on the server. Each half keeps its own invoice and payment.
+   */
+  pairedDecision: async (
+    id: string,
+    decision: "accept" | "cancel" | "operationAccept" | "requestChanges",
+    options: { reason?: string; note?: string; validityDays?: number } = {},
+  ): Promise<{ booking: BookingDetail; partner: BookingDetail }> => {
+    const response = await client.post(B.PAIRED_DECISION(id), {
+      decision,
+      ...options,
+    });
+    return unwrap(response.data) as {
+      booking: BookingDetail;
+      partner: BookingDetail;
+    };
+  },
+
   create: async (payload: Record<string, unknown>): Promise<BookingDetail> => {
     const response = await client.post<{ booking: BookingDetail } | BookingDetail>(
       B.BASE,
diff --git a/apps/edr-freight-web/backoffice/src/services/contracts.service.ts b/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
index 01dbadac7..f06f2fb61 100644
--- a/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/contracts.service.ts
@@ -71,6 +71,32 @@ export interface ShipmentValidation {
   totalAmount?: number;
 }
 
+/**
+ * A booking GL may pick as the shared-wagon partner of an odd-20ft customs
+ * booking. `hasCargo` is false for a bare instance whose containers GL still
+ * enters on the split completion form.
+ */
+export interface ConsolidationCandidate {
+  id: string;
+  reference: string;
+  contractId: string | null;
+  companyName: string | null;
+  status: string;
+  tradeDirection: string | null;
+  originYardId: string | null;
+  destinationYardId: string | null;
+  scheduledDate: string | null;
+  ft20Quantity: number;
+  hasCargo: boolean;
+}
+
+/** Both halves of a shared-wagon completion, each with its own full payload. */
+export interface CompleteConsolidatedPairPayload {
+  partnerBookingId: string;
+  booking: Freight.CreateBookingUnderContractDto;
+  partner: Freight.CreateBookingUnderContractDto;
+}
+
 export interface ContractListSummaryMetrics {
   inQueue: number;
   needsAction: number;
@@ -674,6 +700,46 @@ export const contractsService = {
     };
   },
 
+  /**
+   * Bookings GL may link to an odd-20ft customs booking as its shared-wagon
+   * partner (same route and direction, customs, odd 20ft, not already paired).
+   */
+  listConsolidationCandidates: async (
+    id: string,
+    bookingId: string,
+  ): Promise<ConsolidationCandidate[]> => {
+    const response = await client.get(
+      C.CONSOLIDATION_CANDIDATES(id, bookingId),
+    );
+    return (unwrap(response.data) ?? []) as ConsolidationCandidate[];
+  },
+
+  /**
+   * Complete an odd-20ft booking together with the partner booking sharing its
+   * wagon. All-or-nothing on the server: either both bookings complete and are
+   * linked, or neither does. Each booking keeps its own price and its own
+   * invoice — only the wagon is shared.
+   */
+  completeConsolidatedPair: async (
+    id: string,
+    bookingId: string,
+    payload: CompleteConsolidatedPairPayload,
+  ): Promise<{
+    booking: { id: string; reference: string };
+    partner: { id: string; reference: string };
+    warnings?: string[];
+  }> => {
+    const response = await client.post(
+      C.BOOKINGS_COMPLETE_CONSOLIDATED(id, bookingId),
+      payload,
+    );
+    return unwrap(response.data) as {
+      booking: { id: string; reference: string };
+      partner: { id: string; reference: string };
+      warnings?: string[];
+    };
+  },
+
   /**
    * Pre-create validation + authoritative price preview: the same
    * BookingPricingService pass that prices the booking on create (rail +
diff --git a/apps/edr-freight-web/backoffice/src/types/booking.ts b/apps/edr-freight-web/backoffice/src/types/booking.ts
index 510139731..d3d6c0293 100644
--- a/apps/edr-freight-web/backoffice/src/types/booking.ts
+++ b/apps/edr-freight-web/backoffice/src/types/booking.ts
@@ -296,6 +296,12 @@ export interface BookingListRow {
   governmentInstitution?: string | null;
   consolidationPartnerId?: string | null;
   consolidationPartnerReference?: string | null;
+  /**
+   * The other half of a consolidated pair, folded into this row for display.
+   * Set client-side when both halves are present in the same page of results —
+   * the list shows one row per shared wagon, not one per booking.
+   */
+  pairedWith?: BookingListRow | null;
   customsClearingEnabled?: boolean;
   /**
    * Derived booking kind for the list "Type" column. Mirrors the server's
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step8-review.tsx b/apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step8-review.tsx
index 001e55966..cfddea8b3 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step8-review.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step8-review.tsx
@@ -163,11 +163,17 @@ export function Step8Review({
           .join(", ")
       : "";
 
-  // 20ft containers must pair up (two per wagon) — an odd total blocks submit.
+  // 20ft containers must pair up (two per wagon). Without customs an odd total
+  // still blocks submit — nothing downstream can place the unpaired container.
+  // With customs it is allowed: Global Logistics completes the booking and links
+  // it to another customer's odd booking so the two share the wagon, so an odd
+  // count here is only a notice.
   const { hasOddUnit: hasOdd20ft, ft20Wagons: twentyFtCount } =
     values.cargoType === "container"
       ? calcWagons(values.containers ?? [])
       : { hasOddUnit: false, ft20Wagons: 0 };
+  const oddPairsViaCustoms = hasOdd20ft && Boolean(values.customsClearingEnabled);
+  const oddBlocksSubmit = hasOdd20ft && !oddPairsViaCustoms;
 
   const isGeneralContract = values.bookingType === "general_contract";
   // Both one-time and general contracts take the bulk amount from the cargo step
@@ -543,7 +549,7 @@ export function Step8Review({
             </Paper>
 
             <Paper radius={20} p="lg" withBorder bg="white">
-              {hasOdd20ft ? (
+              {oddBlocksSubmit ? (
                 <Box mb="md">
                   <AlertBox tone="error">
                     <p className="font-semibold">
@@ -558,6 +564,20 @@ export function Step8Review({
                     </p>
                   </AlertBox>
                 </Box>
+              ) : oddPairsViaCustoms ? (
+                <Box mb="md">
+                  <AlertBox tone="info">
+                    <p className="font-semibold">
+                      Odd number of 20ft containers ({twentyFtCount})
+                    </p>
+                    <p className="mt-1 text-xs">
+                      20ft containers travel two per wagon, so one of yours will
+                      share a wagon with another shipment. Global Logistics
+                      arranges the pairing when completing your booking — you are
+                      billed only for your own containers.
+                    </p>
+                  </AlertBox>
+                </Box>
               ) : noWagonForSelectedDay ? (
                 <Box mb="md">
                   <AlertBox tone="error">
@@ -587,7 +607,7 @@ export function Step8Review({
                   leftSection={<Send size={16} />}
                   onClick={onSubmit}
                   loading={submitPending}
-                  disabled={submitPending || hasOdd20ft || noWagonForSelectedDay}
+                  disabled={submitPending || oddBlocksSubmit || noWagonForSelectedDay}
                 >
                   Submit
                 </Button>
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentRequestPage.tsx b/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentRequestPage.tsx
index 9c6974641..69f15e756 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentRequestPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentRequestPage.tsx
@@ -106,14 +106,14 @@ export default function NewShipmentRequestPage() {
     contract.cargoScope?.[0];
   const isPerItem = bulkScope?.cargoType?.unitOfMeasure === "PER_ITEM";
 
-  // 20ft containers ride two per wagon, so an odd total can never be planned —
-  // and GL's create-booking form blocks it too, so an odd request would only
-  // dead-end there. Same even-number rule the booking forms apply.
+  // 20ft containers ride two per wagon. An odd total leaves one unpaired, which
+  // is allowed here: on a customs contract GL completes the booking and links it
+  // to another customer's odd booking so the two share the wagon. The request is
+  // therefore informational only, not a block.
   const ft20Requested = isContainer ? Number(qtyBySize["20ft"]) || 0 : 0;
   const hasOdd20ft = ft20Requested % 2 === 1;
 
   const handleSubmit = () => {
-    if (hasOdd20ft) return;
     const dto: Freight.CreateBookingRequestDto = {
       contractRouteId: route?.id,
       scheduledDate: hasCustoms ? undefined : scheduledDate || undefined,
@@ -220,17 +220,17 @@ export default function NewShipmentRequestPage() {
 
             {hasOdd20ft ? (
               <Alert
-                color="red"
+                color="blue"
                 variant="light"
                 radius="md"
                 icon={<AlertCircle size={16} />}
                 title={`Odd number of 20ft containers (${ft20Requested})`}
               >
                 <Text fz={13}>
-                  20ft containers travel two per wagon, so they must be requested
-                  in even numbers. Please add one more 20ft container or remove
-                  one (e.g. request {ft20Requested + 1} or {ft20Requested - 1}{" "}
-                  instead of {ft20Requested}).
+                  20ft containers travel two per wagon, so one of yours will
+                  share a wagon with another shipment. Global Logistics arranges
+                  the pairing when completing your booking — you are billed only
+                  for your own containers.
                 </Text>
               </Alert>
             ) : null}
@@ -281,7 +281,6 @@ export default function NewShipmentRequestPage() {
               leftSection={<Send size={16} />}
               loading={submit.isPending}
               onClick={handleSubmit}
-              disabled={hasOdd20ft}
             >
               Submit shipment request
             </Button>

From 6823a32fee315e6d0079cd45adc3a46267b4477a Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 12:55:11 +0000
Subject: [PATCH 158/174] feat: yard scoping to position

---
 .../migrations/3560000000000-YardPositions.ts |  47 ++
 .../3570000000000-YardViewAllPermission.ts    |  54 ++
 .../src/modules/audit/audit-endpoints.ts      |   5 +
 .../controllers/yard-positions.controller.ts  |  85 +++
 .../rule-engine/dto/yard-positions.dto.ts     |  30 ++
 .../entities/yard-position.entity.ts          |  28 +
 .../modules/rule-engine/rule-engine.module.ts |  12 +
 .../services/yard-positions.service.ts        | 194 +++++++
 .../services/yard-scope.service.spec.ts       | 139 +++++
 .../services/yard-scope.service.ts            | 186 +++++++
 .../warehouse-inventory.controller.ts         |  14 +-
 .../warehouses/warehouse-inventory.service.ts |  46 +-
 .../src/seed/freight-permissions.registry.ts  |  25 +
 .../ruleEngine/RuleEngineResourcePage.tsx     |  31 ++
 .../src/pages/ruleEngine/YardDesksModal.tsx   | 134 +++++
 .../src/services/yardPositions.service.ts     |  64 +++
 .../src/user-management/AppMenuTabs.tsx       | 508 +++++++++---------
 .../location-management/LocationForm.tsx      | 365 +++++++++++++
 .../location-management/LocationTypeForm.tsx  | 173 ++++++
 .../location-management/LocationTypesTab.tsx  | 204 +++++++
 .../location-management/LocationsTab.tsx      | 233 ++++++++
 .../dto/locations/location.type.ts            |  54 ++
 .../user-management/hooks/useLocationTypes.ts |  93 ++++
 .../src/user-management/hooks/useLocations.ts |  95 ++++
 .../pages/location-management/index.tsx       |  35 ++
 .../backoffice/src/user-management/route.tsx  |   5 +
 .../services/api/locationService.ts           |  55 ++
 27 files changed, 2657 insertions(+), 257 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3560000000000-YardPositions.ts
 create mode 100644 apps/edr-freight-api/src/migrations/3570000000000-YardViewAllPermission.ts
 create mode 100644 apps/edr-freight-api/src/modules/rule-engine/controllers/yard-positions.controller.ts
 create mode 100644 apps/edr-freight-api/src/modules/rule-engine/dto/yard-positions.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/rule-engine/entities/yard-position.entity.ts
 create mode 100644 apps/edr-freight-api/src/modules/rule-engine/services/yard-positions.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/rule-engine/services/yard-scope.service.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/rule-engine/services/yard-scope.service.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/ruleEngine/YardDesksModal.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/services/yardPositions.service.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationForm.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationTypeForm.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationTypesTab.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationsTab.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/user-management/dto/locations/location.type.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/user-management/hooks/useLocationTypes.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/user-management/hooks/useLocations.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/user-management/pages/location-management/index.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/user-management/services/api/locationService.ts

diff --git a/apps/edr-freight-api/src/migrations/3560000000000-YardPositions.ts b/apps/edr-freight-api/src/migrations/3560000000000-YardPositions.ts
new file mode 100644
index 000000000..102a5b85d
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3560000000000-YardPositions.ts
@@ -0,0 +1,47 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Which desks work at which yard — the input to yard access scoping.
+ *
+ * Many-to-many: a position (what the user-management tree calls a department)
+ * can cover several yards, and a yard is staffed by several positions. The
+ * scope resolver reads it to answer "which yards may this caller touch?".
+ *
+ * `yard_id` carries a real FK; `position_id` deliberately does NOT. Positions
+ * live in `iam`, which is owned by the vendored @tria-plc/iamapi-common package
+ * and shared with the passenger app: a hard FK would let freight block an IAM
+ * delete, and would have to be dropped the day IAM moves to its own database.
+ * Reads join `iam.positions … WHERE deleted_at IS NULL` instead, so a
+ * soft-deleted position silently drops out of scope rather than granting it.
+ *
+ * The unique index is PARTIAL — soft-deleted rows must not block re-adding the
+ * same pair later.
+ */
+export class YardPositions3560000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.yard_positions (
+        id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        yard_id     uuid NOT NULL REFERENCES freight.yards(id) ON DELETE CASCADE,
+        position_id uuid NOT NULL,
+        created_at  timestamptz NOT NULL DEFAULT now(),
+        updated_at  timestamptz NOT NULL DEFAULT now(),
+        deleted_at  timestamptz
+      )
+    `);
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS ux_yard_positions_pair
+        ON freight.yard_positions (yard_id, position_id)
+        WHERE deleted_at IS NULL
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS ix_yard_positions_position
+        ON freight.yard_positions (position_id)
+        WHERE deleted_at IS NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.yard_positions`);
+  }
+}
diff --git a/apps/edr-freight-api/src/migrations/3570000000000-YardViewAllPermission.ts b/apps/edr-freight-api/src/migrations/3570000000000-YardViewAllPermission.ts
new file mode 100644
index 000000000..0a53bd530
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3570000000000-YardViewAllPermission.ts
@@ -0,0 +1,54 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Seed `edr_freight_app:yards:view_all` — the cross-yard bypass for yard access
+ * scoping.
+ *
+ * The permission catalog is otherwise written by `EdrOrgSeeder`, which skips
+ * itself unless `SEED_EDR_ORG` is set. That flag is off in normal environments,
+ * so a key added to the registry never reaches `iam.permissions` and cannot be
+ * granted to anyone — the bypass would exist in code and be unusable in the
+ * database. A migration is the one path that runs everywhere.
+ *
+ * Idempotent on `key`, which is the identity every consumer resolves by (the
+ * registry's uuid is only used where a seed row needs one). Skips silently when
+ * the freight application row is absent, since there is nothing to attach to.
+ */
+export class YardViewAllPermission3570000000000 implements MigrationInterface {
+  private static readonly KEY = 'edr_freight_app:yards:view_all';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `INSERT INTO iam.permissions (id, key, name, application_id)
+       SELECT gen_random_uuid(),
+              $1::varchar,
+              '{"am": "Access every yard (bypass yard scoping)", "en": "Access every yard (bypass yard scoping)"}'::jsonb,
+              a.id
+         FROM iam.application a
+        WHERE a.key = 'edr_freight_app'
+          AND NOT EXISTS (SELECT 1 FROM iam.permissions p WHERE p.key = $1::varchar)`,
+      [YardViewAllPermission3570000000000.KEY],
+    );
+  }
+
+  /**
+   * Removes only the permission row itself. Any grant of it goes first, or the
+   * delete trips the position/role permission foreign keys — and a half-removed
+   * permission is worse than one left in place.
+   */
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DELETE FROM iam.position_permissions
+        WHERE permission_id IN (SELECT id FROM iam.permissions WHERE key = $1)`,
+      [YardViewAllPermission3570000000000.KEY],
+    );
+    await queryRunner.query(
+      `DELETE FROM iam.role_permissions
+        WHERE permission_id IN (SELECT id FROM iam.permissions WHERE key = $1)`,
+      [YardViewAllPermission3570000000000.KEY],
+    );
+    await queryRunner.query(`DELETE FROM iam.permissions WHERE key = $1`, [
+      YardViewAllPermission3570000000000.KEY,
+    ]);
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts b/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
index d46f63a7d..17b2d1580 100644
--- a/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
+++ b/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
@@ -633,6 +633,11 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "DELETE /api/weight-limit-rules/:id": ["Soft-delete a weight limit rule", "DELETE", "Weight Limit Rule"],
 
   // Yard
+  // Yard Position (desk↔yard mapping — an input to yard access scoping, so
+  // every change to it is evidence of who widened or narrowed someone's reach)
+  "PUT /api/yard-positions/yard/:yardId": ["Replace a yard's whole position set", "PUT", "Yard Position"],
+  "PUT /api/yard-positions/position/:positionId": ["Replace a position's whole yard set", "PUT", "Yard Position"],
+
   "POST /api/yards": ["Create a yard", "POST", "Yard"],
   "PATCH /api/yards/:id": ["Update a yard", "PATCH", "Yard"],
   "DELETE /api/yards/:id": ["Soft-delete a yard", "DELETE", "Yard"],
diff --git a/apps/edr-freight-api/src/modules/rule-engine/controllers/yard-positions.controller.ts b/apps/edr-freight-api/src/modules/rule-engine/controllers/yard-positions.controller.ts
new file mode 100644
index 000000000..44ae27607
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/rule-engine/controllers/yard-positions.controller.ts
@@ -0,0 +1,85 @@
+import { Body, Controller, Get, Param, ParseUUIDPipe, Put, Query } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+
+import { CurrentUser } from '@edr/api-common';
+import { StaffReference } from '../../../common/booking-guards';
+import { RuleEngineUpdate, RuleEngineView } from '../../../common/rule-engine-guards';
+import {
+  ListYardPositionsQueryDto,
+  SetPositionYardsDto,
+  SetYardPositionsDto,
+} from '../dto/yard-positions.dto';
+import { YardPositionsService } from '../services/yard-positions.service';
+import { YardScopeService } from '../services/yard-scope.service';
+
+/**
+ * Desk↔yard mapping — which positions ("departments" in the user-management
+ * tree) staff which yard. It is yard configuration, so it is gated by the same
+ * rule-engine yard keys as the rest of the yards screen.
+ *
+ * Writes REPLACE the whole set for the side being edited. The admin UI submits
+ * the full multi-select value; a caller sending a delta will drop everything it
+ * omits. Both write paths flush the scope resolver's cache so a mapping change
+ * takes effect on the next request instead of up to a minute later.
+ */
+@ApiTags('yard-positions')
+@Controller('yard-positions')
+@ApiBearerAuth()
+export class YardPositionsController {
+  constructor(
+    private readonly service: YardPositionsService,
+    private readonly scope: YardScopeService,
+  ) {}
+
+  @Get()
+  @RuleEngineView('yards')
+  @ApiOperation({ summary: 'List desk↔yard mappings, optionally by yard or position' })
+  list(@Query() query: ListYardPositionsQueryDto) {
+    return this.service.list(query);
+  }
+
+  @Get('positions')
+  @RuleEngineView('yards')
+  @ApiOperation({ summary: 'Positions selectable as yard desks' })
+  listPositions() {
+    return this.service.listSelectablePositions();
+  }
+
+  @Get('my-yards')
+  // Any signed-in staff member, NOT gated on the yards keys: this returns the
+  // caller's own access and nothing else, and the frontend needs it to
+  // preselect yard filters. Gating it on `rule_engine:yards:view` 403'd every
+  // desk that does not administer yards — i.e. exactly the users it is for.
+  @StaffReference()
+  @ApiOperation({
+    summary: "The caller's own yard scope (null yardIds = unrestricted)",
+  })
+  async myYards(@CurrentUser() user: unknown) {
+    const yardIds = await this.scope.getScopedYardIds(user as never);
+    return { yardIds, unrestricted: yardIds === null, enforced: this.scope.enforced };
+  }
+
+  @Put('yard/:yardId')
+  @RuleEngineUpdate('yards')
+  @ApiOperation({ summary: "Replace a yard's whole position set" })
+  async setPositionsForYard(
+    @Param('yardId', ParseUUIDPipe) yardId: string,
+    @Body() dto: SetYardPositionsDto,
+  ) {
+    const rows = await this.service.setPositionsForYard(yardId, dto.positionIds);
+    this.scope.invalidate();
+    return rows;
+  }
+
+  @Put('position/:positionId')
+  @RuleEngineUpdate('yards')
+  @ApiOperation({ summary: "Replace a position's whole yard set" })
+  async setYardsForPosition(
+    @Param('positionId', ParseUUIDPipe) positionId: string,
+    @Body() dto: SetPositionYardsDto,
+  ) {
+    const rows = await this.service.setYardsForPosition(positionId, dto.yardIds);
+    this.scope.invalidate();
+    return rows;
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/rule-engine/dto/yard-positions.dto.ts b/apps/edr-freight-api/src/modules/rule-engine/dto/yard-positions.dto.ts
new file mode 100644
index 000000000..b18648d78
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/rule-engine/dto/yard-positions.dto.ts
@@ -0,0 +1,30 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsArray, IsOptional, IsUUID } from 'class-validator';
+
+export class ListYardPositionsQueryDto {
+  @ApiPropertyOptional({ format: 'uuid' })
+  @IsOptional()
+  @IsUUID()
+  yardId?: string;
+
+  @ApiPropertyOptional({ format: 'uuid' })
+  @IsOptional()
+  @IsUUID()
+  positionId?: string;
+}
+
+/** Replaces the yard's whole position set — see the controller's PUT docs. */
+export class SetYardPositionsDto {
+  @ApiProperty({ type: [String], format: 'uuid' })
+  @IsArray()
+  @IsUUID('4', { each: true })
+  positionIds!: string[];
+}
+
+/** Replaces the position's whole yard set. */
+export class SetPositionYardsDto {
+  @ApiProperty({ type: [String], format: 'uuid' })
+  @IsArray()
+  @IsUUID('4', { each: true })
+  yardIds!: string[];
+}
diff --git a/apps/edr-freight-api/src/modules/rule-engine/entities/yard-position.entity.ts b/apps/edr-freight-api/src/modules/rule-engine/entities/yard-position.entity.ts
new file mode 100644
index 000000000..de12b5674
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/rule-engine/entities/yard-position.entity.ts
@@ -0,0 +1,28 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+
+import { Yard } from './yard.entity';
+
+/**
+ * One desk staffed at one yard.
+ *
+ * The pairing that yard access scoping resolves against: a caller's active
+ * position decides which yards they may touch. Position rows live in `iam`
+ * (`iam.positions` — what the user-management tree labels "departments"), so
+ * `positionId` is an unconstrained uuid by design; see the migration for why.
+ */
+@Entity({ schema: 'freight', name: 'yard_positions' })
+@Index(['yardId'])
+@Index(['positionId'])
+export class YardPosition extends BaseEntity {
+  @Column({ name: 'yard_id', type: 'uuid' })
+  yardId!: string;
+
+  @ManyToOne(() => Yard, { nullable: false, onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'yard_id' })
+  yard?: Yard;
+
+  /** `iam.positions.id`. No FK — IAM is package-owned and soft-deletes. */
+  @Column({ name: 'position_id', type: 'uuid' })
+  positionId!: string;
+}
diff --git a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts
index 549a35fa2..97e89cc3b 100644
--- a/apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts
+++ b/apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts
@@ -13,6 +13,7 @@ import { ShippingLinesController } from './controllers/shipping-lines.controller
 import { WeightLimitRulesController } from './controllers/weight-limit-rules.controller';
 import { YardDistancesController } from './controllers/yard-distances.controller';
 import { YardsController } from './controllers/yards.controller';
+import { YardPositionsController } from './controllers/yard-positions.controller';
 
 import { ApprovalRule } from './entities/approval-rule.entity';
 import { CargoType } from './entities/cargo-type.entity';
@@ -28,6 +29,7 @@ import { Yard } from './entities/yard.entity';
 import { YardDistance } from './entities/yard-distance.entity';
 import { YardFacility } from './entities/yard-facility.entity';
 import { YardLocation } from './entities/yard-location.entity';
+import { YardPosition } from './entities/yard-position.entity';
 
 import { APPROVAL_RULES_REPOSITORY } from './interfaces/approval-rules.repository.interface';
 import { CARGO_TYPES_REPOSITORY } from './interfaces/cargo-types.repository.interface';
@@ -65,6 +67,8 @@ import { WeightLimitRulesService } from './services/weight-limit-rules.service';
 import { YardsService } from './services/yards.service';
 import { YardDistancesService } from './services/yard-distances.service';
 import { YardFacilitiesService } from './services/yard-facilities.service';
+import { YardPositionsService } from './services/yard-positions.service';
+import { YardScopeService } from './services/yard-scope.service';
 
 import { RuleEngineService } from './rule-engine.service';
 
@@ -91,6 +95,7 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
       YardDistance,
       YardFacility,
       YardLocation,
+      YardPosition,
       ShippingLine,
       Rate,
       ApprovalRule,
@@ -116,6 +121,7 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
     ServiceTypesController,
     WeightLimitRulesController,
     YardsController,
+    YardPositionsController,
     YardDistancesController,
     ShippingLinesController,
     RatesController,
@@ -152,6 +158,8 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
     YardsService,
     YardDistancesService,
     YardFacilitiesService,
+    YardPositionsService,
+    YardScopeService,
     ShippingLinesService,
     RatesService,
     ApprovalRulesService,
@@ -168,6 +176,10 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
     YardsService,
     YardDistancesService,
     YardFacilitiesService,
+    YardPositionsService,
+    // Exported so any module can narrow its yard queries through the one
+    // resolver — the module is @Global, so no import is needed to inject it.
+    YardScopeService,
     ShippingLinesService,
     RatesService,
     ApprovalRulesService,
diff --git a/apps/edr-freight-api/src/modules/rule-engine/services/yard-positions.service.ts b/apps/edr-freight-api/src/modules/rule-engine/services/yard-positions.service.ts
new file mode 100644
index 000000000..93f9752f6
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/rule-engine/services/yard-positions.service.ts
@@ -0,0 +1,194 @@
+import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
+import { DataSource, In, IsNull } from 'typeorm';
+
+import { YardPosition } from '../entities/yard-position.entity';
+import { Yard } from '../entities/yard.entity';
+
+/** A mapped desk, joined to its IAM position for display. */
+export interface YardPositionRow {
+  id: string;
+  yardId: string;
+  yardCode: string;
+  yardLabel: string;
+  positionId: string;
+  /** Localised name from `iam.positions.name` — null if the position is gone. */
+  positionName: { am?: string; en?: string } | null;
+  positionTypeKey: string | null;
+}
+
+/**
+ * The desk↔yard mapping behind yard access scoping.
+ *
+ * Reads always join `iam.positions` and drop soft-deleted rows: the mapping has
+ * no FK to IAM (see the migration), so a position deleted in the admin UI leaves
+ * an orphan row here. Dropping it on read means the orphan can never widen
+ * someone's scope — it just disappears.
+ */
+@Injectable()
+export class YardPositionsService {
+  constructor(private readonly dataSource: DataSource) {}
+
+  /** Mapping rows, optionally narrowed to one yard or one position. */
+  async list(filter: {
+    yardId?: string;
+    positionId?: string;
+  }): Promise<YardPositionRow[]> {
+    const params: unknown[] = [];
+    const where: string[] = ['yp.deleted_at IS NULL', 'y.deleted_at IS NULL'];
+
+    if (filter.yardId) {
+      params.push(filter.yardId);
+      where.push(`yp.yard_id = $${params.length}`);
+    }
+    if (filter.positionId) {
+      params.push(filter.positionId);
+      where.push(`yp.position_id = $${params.length}`);
+    }
+
+    return this.dataSource.query(
+      `SELECT yp.id            AS "id",
+              yp.yard_id       AS "yardId",
+              y.code           AS "yardCode",
+              y.label          AS "yardLabel",
+              yp.position_id   AS "positionId",
+              p.name           AS "positionName",
+              pt.key           AS "positionTypeKey"
+         FROM freight.yard_positions yp
+         JOIN freight.yards y        ON y.id = yp.yard_id
+         -- INNER join: a mapping whose position was deleted grants nothing and
+         -- is not shown. The row stays for audit until someone re-saves the set.
+         JOIN iam.positions p        ON p.id = yp.position_id AND p.deleted_at IS NULL
+         LEFT JOIN iam.position_types pt ON pt.id = p.position_type_id
+        WHERE ${where.join(' AND ')}
+        ORDER BY y.display_order ASC, y.label ASC, p.name->>'en' ASC`,
+      params,
+    );
+  }
+
+  /**
+   * Replace the yard's entire position set.
+   *
+   * Replace, not append — the admin UI submits the full multi-select value, so a
+   * partial payload would silently keep desks the user just unticked. Callers
+   * sending a delta will remove everything they omit.
+   */
+  async setPositionsForYard(
+    yardId: string,
+    positionIds: string[],
+  ): Promise<YardPositionRow[]> {
+    await this.assertYardExists(yardId);
+    await this.assertPositionsExist(positionIds);
+
+    await this.dataSource.transaction(async (manager) => {
+      const repo = manager.getRepository(YardPosition);
+      await repo.delete({ yardId });
+      if (positionIds.length) {
+        await repo.insert(
+          [...new Set(positionIds)].map((positionId) => ({ yardId, positionId })),
+        );
+      }
+    });
+
+    return this.list({ yardId });
+  }
+
+  /** Replace the position's entire yard set. Same replace semantics. */
+  async setYardsForPosition(
+    positionId: string,
+    yardIds: string[],
+  ): Promise<YardPositionRow[]> {
+    await this.assertPositionsExist([positionId]);
+    await this.assertYardsExist(yardIds);
+
+    await this.dataSource.transaction(async (manager) => {
+      const repo = manager.getRepository(YardPosition);
+      await repo.delete({ positionId });
+      if (yardIds.length) {
+        await repo.insert(
+          [...new Set(yardIds)].map((yardId) => ({ yardId, positionId })),
+        );
+      }
+    });
+
+    return this.list({ positionId });
+  }
+
+  /**
+   * Positions offered by the mapping picker.
+   *
+   * Reads `iam.positions` directly rather than going through IAM's
+   * `/positions/list/{unitId}`: that endpoint needs the caller to resolve a unit
+   * first, and the picker wants every desk that could staff a yard regardless of
+   * which unit it hangs under.
+   */
+  async listSelectablePositions(): Promise<
+    Array<{
+      id: string;
+      name: { am?: string; en?: string } | null;
+      positionTypeKey: string | null;
+      unitKey: string | null;
+    }>
+  > {
+    return this.dataSource.query(
+      `SELECT p.id       AS "id",
+              p.name     AS "name",
+              pt.key     AS "positionTypeKey",
+              u.key      AS "unitKey"
+         FROM iam.positions p
+         LEFT JOIN iam.position_types pt ON pt.id = p.position_type_id
+         LEFT JOIN iam.units u           ON u.id = p.unit_id
+        WHERE p.deleted_at IS NULL
+        ORDER BY p.name->>'en' ASC`,
+    );
+  }
+
+  /** Yard ids mapped to any of these positions — the scope resolver's read. */
+  async yardIdsForPositions(positionIds: string[]): Promise<string[]> {
+    if (!positionIds.length) return [];
+    const rows: { yardId: string }[] = await this.dataSource.query(
+      `SELECT DISTINCT yp.yard_id AS "yardId"
+         FROM freight.yard_positions yp
+         JOIN freight.yards y ON y.id = yp.yard_id AND y.deleted_at IS NULL
+        WHERE yp.deleted_at IS NULL
+          AND yp.position_id = ANY($1)`,
+      [positionIds],
+    );
+    return rows.map((r) => r.yardId);
+  }
+
+  private async assertYardExists(yardId: string): Promise<void> {
+    const yard = await this.dataSource
+      .getRepository(Yard)
+      .findOne({ where: { id: yardId, deletedAt: IsNull() } });
+    if (!yard) throw new NotFoundException(`Yard ${yardId} not found`);
+  }
+
+  private async assertYardsExist(yardIds: string[]): Promise<void> {
+    if (!yardIds.length) return;
+    const found = await this.dataSource
+      .getRepository(Yard)
+      .count({ where: { id: In(yardIds), deletedAt: IsNull() } });
+    if (found !== new Set(yardIds).size) {
+      throw new BadRequestException('One or more yards do not exist');
+    }
+  }
+
+  /**
+   * Validated in the service because the database cannot: there is no FK to
+   * `iam.positions`, so an unchecked payload would happily store a typo'd uuid
+   * that silently grants nothing and reads as a configuration bug later.
+   */
+  private async assertPositionsExist(positionIds: string[]): Promise<void> {
+    if (!positionIds.length) return;
+    const unique = [...new Set(positionIds)];
+    const rows: { count: string }[] = await this.dataSource.query(
+      `SELECT COUNT(*)::text AS count
+         FROM iam.positions
+        WHERE id = ANY($1) AND deleted_at IS NULL`,
+      [unique],
+    );
+    if (Number(rows[0]?.count ?? 0) !== unique.length) {
+      throw new BadRequestException('One or more positions do not exist');
+    }
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/rule-engine/services/yard-scope.service.spec.ts b/apps/edr-freight-api/src/modules/rule-engine/services/yard-scope.service.spec.ts
new file mode 100644
index 000000000..c9af80ad3
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/rule-engine/services/yard-scope.service.spec.ts
@@ -0,0 +1,139 @@
+import { ForbiddenException } from '@nestjs/common';
+
+import { YardScopeService } from './yard-scope.service';
+
+/**
+ * The resolver answers "which yards", never "may they act at all" — that stays
+ * with the permission guard. So a mapped desk is narrowed to its yards, and an
+ * unmapped one keeps the reach its permissions already gave it.
+ */
+describe('YardScopeService', () => {
+  const yardIdsForPositions = jest.fn();
+  const service = () =>
+    new YardScopeService({ yardIdsForPositions } as never);
+
+  const staff = (positionId: string, permissions: string[] = []) => ({
+    roles: [{ key: 'staff' }],
+    permissions: permissions.map((key) => ({ key })),
+    employee: { position: { id: positionId, permissions: [] } },
+  });
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    delete process.env.YARD_SCOPE_ENFORCE;
+  });
+
+  it('resolves a mapped position to its yards', async () => {
+    yardIdsForPositions.mockResolvedValue(['yard-kality', 'yard-mojo']);
+
+    const scope = await service().getScopedYardIds(staff('pos-officer'));
+
+    expect(scope).toEqual(['yard-kality', 'yard-mojo']);
+    expect(yardIdsForPositions).toHaveBeenCalledWith(['pos-officer']);
+  });
+
+  it('leaves an unmapped position unrestricted — permissions still gate the action', async () => {
+    yardIdsForPositions.mockResolvedValue([]);
+
+    expect(await service().getScopedYardIds(staff('pos-unmapped'))).toBeNull();
+  });
+
+  it('leaves a caller with no resolvable position unrestricted', async () => {
+    const noPosition = { roles: [{ key: 'staff' }], employee: { position: {} } };
+
+    expect(await service().getScopedYardIds(noPosition)).toBeNull();
+    expect(yardIdsForPositions).not.toHaveBeenCalled();
+  });
+
+  it('narrows nothing for an anonymous caller but grants nothing either', async () => {
+    expect(await service().getScopedYardIds(null)).toEqual([]);
+  });
+
+  it('returns unrestricted only for super admins and view_all holders', async () => {
+    const superAdmin = { roles: [{ key: 'super_admin' }] };
+    const hqDesk = staff('pos-occ', ['edr_freight_app:yards:view_all']);
+
+    expect(await service().getScopedYardIds(superAdmin)).toBeNull();
+    expect(await service().getScopedYardIds(hqDesk)).toBeNull();
+    expect(yardIdsForPositions).not.toHaveBeenCalled();
+  });
+
+  it('includes delegated positions — standing in must not lose the yard', async () => {
+    yardIdsForPositions.mockResolvedValue(['yard-kality']);
+
+    await service().getScopedYardIds({
+      roles: [{ key: 'staff' }],
+      employee: {
+        position: { id: 'pos-own' },
+        delegatedPositions: [{ id: 'pos-gelan-director' }],
+      },
+    });
+
+    expect(yardIdsForPositions).toHaveBeenCalledWith([
+      'pos-own',
+      'pos-gelan-director',
+    ]);
+  });
+
+  describe('listFilterYardIds', () => {
+    it('narrows nothing while shadow-logging', async () => {
+      yardIdsForPositions.mockResolvedValue(['yard-kality']);
+
+      expect(
+        await service().listFilterYardIds(staff('pos-officer'), undefined, 'list'),
+      ).toBeNull();
+    });
+
+    it('narrows to the mapped yards once enforcing', async () => {
+      process.env.YARD_SCOPE_ENFORCE = 'true';
+      yardIdsForPositions.mockResolvedValue(['yard-kality', 'yard-mojo']);
+
+      expect(
+        await service().listFilterYardIds(staff('pos-officer'), undefined, 'list'),
+      ).toEqual(['yard-kality', 'yard-mojo']);
+    });
+
+    it('keeps an in-scope yard filter as the caller asked', async () => {
+      process.env.YARD_SCOPE_ENFORCE = 'true';
+      yardIdsForPositions.mockResolvedValue(['yard-kality', 'yard-mojo']);
+
+      expect(
+        await service().listFilterYardIds(staff('pos-officer'), 'yard-mojo', 'list'),
+      ).toEqual(['yard-mojo']);
+    });
+
+    it('returns an empty set — not everything — for an out-of-scope yard filter', async () => {
+      process.env.YARD_SCOPE_ENFORCE = 'true';
+      yardIdsForPositions.mockResolvedValue(['yard-kality']);
+
+      expect(
+        await service().listFilterYardIds(staff('pos-officer'), 'yard-djibouti', 'list'),
+      ).toEqual([]);
+    });
+
+    it('never narrows an unmapped desk', async () => {
+      process.env.YARD_SCOPE_ENFORCE = 'true';
+      yardIdsForPositions.mockResolvedValue([]);
+
+      expect(
+        await service().listFilterYardIds(staff('pos-unmapped'), undefined, 'list'),
+      ).toBeNull();
+    });
+  });
+
+  it('only logs an out-of-scope yard until YARD_SCOPE_ENFORCE is set', async () => {
+    yardIdsForPositions.mockResolvedValue(['yard-kality']);
+    const shadow = service();
+
+    await expect(
+      shadow.assertYardInScope(staff('pos-officer'), 'yard-mojo', 'test'),
+    ).resolves.toBeUndefined();
+
+    process.env.YARD_SCOPE_ENFORCE = 'true';
+    const enforcing = service();
+
+    await expect(
+      enforcing.assertYardInScope(staff('pos-officer'), 'yard-mojo', 'test'),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/rule-engine/services/yard-scope.service.ts b/apps/edr-freight-api/src/modules/rule-engine/services/yard-scope.service.ts
new file mode 100644
index 000000000..0a7fbe2e0
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/rule-engine/services/yard-scope.service.ts
@@ -0,0 +1,186 @@
+import { ForbiddenException, Injectable, Logger } from "@nestjs/common";
+
+import { hasFreightPermission, isSuperAdmin } from "../../../common/freight-permission.util";
+import { FREIGHT_PERMS } from "../../../seed/freight-permissions.registry";
+import { YardPositionsService } from "./yard-positions.service";
+
+/**
+ * Caller shape the resolver reads — the `/auth/me` user in either of its two
+ * shapes. Structurally compatible with what `freight-permission.util` accepts,
+ * so the same object serves both the permission checks and the position walk.
+ */
+type PositionLike = {
+  id?: string;
+  permissions?: { key?: string }[];
+  positionType?: { key?: string } | null;
+};
+
+type ScopeUser = {
+  roles?: { key?: string }[];
+  permissions?: { key?: string }[];
+  employee?:
+    | {
+        position?: PositionLike;
+        delegatedPositions?: PositionLike[];
+      }
+    | { positions?: PositionLike[] }[]
+    | null;
+};
+
+/**
+ * Which yards a caller may touch.
+ *
+ * Scope follows the caller's ACTIVE position, not a union of every position they
+ * have ever held: the frontends already send `x-current-position-id` and the
+ * token snapshots that one position, so switching desks switches yards — which
+ * is what staff covering two yards actually do. Delegated positions are added on
+ * top, otherwise standing in for the Gelan director silently loses Gelan.
+ *
+ * `null` means unrestricted, and an UNMAPPED caller gets it. Scoping narrows a
+ * desk that has been given yards; it does not hand out access. Whether the
+ * caller may perform the action at all is the permission guard's job — this
+ * resolver only answers "which yards", so a desk with the permission and no
+ * mapping keeps the reach it had before the mapping existed.
+ *
+ * The trade-off is deliberate and worth knowing: an accidentally-cleared
+ * mapping widens access rather than blocking work, so the mapping is not a
+ * containment barrier on its own — the permission keys still are. Super admins
+ * and holders of `yards:view_all` are unrestricted regardless of mapping.
+ *
+ * ENFORCEMENT IS OFF until `YARD_SCOPE_ENFORCE=true`. Until then
+ * {@link assertYardInScope} logs what it would have blocked and returns. Flip it
+ * only once the mapping table is populated and the log is quiet — on an empty
+ * table, enforcing locks out every staff member at once.
+ */
+@Injectable()
+export class YardScopeService {
+  private readonly logger = new Logger(YardScopeService.name);
+
+  // ponytail: 60s cache keyed by the position-id set, no invalidation hook. A
+  // mapping change takes up to a minute to reach the resolver. Call
+  // `invalidate()` from the mutation if that lag ever matters.
+  private static readonly CACHE_TTL_MS = 60_000;
+  private readonly cache = new Map<string, { yardIds: string[]; at: number }>();
+
+  constructor(private readonly yardPositions: YardPositionsService) {}
+
+  /** True when the deny path is live; false while shadow-logging. */
+  get enforced(): boolean {
+    return process.env.YARD_SCOPE_ENFORCE === "false";
+  }
+
+  /** Yard ids the caller is scoped to, or `null` for unrestricted. */
+  async getScopedYardIds(user: ScopeUser | null | undefined): Promise<string[] | null> {
+    // No user at all is an unauthenticated call the guards should already have
+    // rejected — narrow to nothing rather than trusting it.
+    if (!user) return [];
+    if (isSuperAdmin(user)) return null;
+    if (hasFreightPermission(user, FREIGHT_PERMS.yards.viewAll)) return null;
+
+    const positionIds = this.effectivePositionIds(user);
+    // No resolvable position — nothing to narrow by, so nothing is narrowed.
+    if (!positionIds.length) return null;
+
+    const key = positionIds.join(",");
+    const hit = this.cache.get(key);
+    if (hit && Date.now() - hit.at < YardScopeService.CACHE_TTL_MS) {
+      return hit.yardIds.length ? hit.yardIds : null;
+    }
+
+    const yardIds = await this.yardPositions.yardIdsForPositions(positionIds);
+    this.cache.set(key, { yardIds, at: Date.now() });
+    // Unmapped desk → unrestricted. Mapping narrows; absence of one does not.
+    return yardIds.length ? yardIds : null;
+  }
+
+  async isYardInScope(
+    user: ScopeUser | null | undefined,
+    yardId: string | null | undefined,
+  ): Promise<boolean> {
+    if (!yardId) return true;
+    const scope = await this.getScopedYardIds(user);
+    return scope === null || scope.includes(yardId);
+  }
+
+  /**
+   * Gate an action on a yard. While `YARD_SCOPE_ENFORCE` is unset this only
+   * logs — wire it into write paths first and read filters second, so the
+   * shadow log shows what enforcement would break before it breaks it.
+   */
+  async assertYardInScope(
+    user: ScopeUser | null | undefined,
+    yardId: string | null | undefined,
+    context: string,
+  ): Promise<void> {
+    if (await this.isYardInScope(user, yardId)) return;
+
+    const positions = this.effectivePositionIds(user).join(",") || "none";
+    if (!this.enforced) {
+      this.logger.warn(
+        `[yard-scope shadow] would block ${context}: yard=${yardId} positions=${positions}`,
+      );
+      return;
+    }
+    throw new ForbiddenException("This yard is outside your assigned yards");
+  }
+
+  /**
+   * Yard ids a list query should be narrowed to, or `null` for no narrowing.
+   *
+   * Returns an EMPTY array only when the caller explicitly asked for a yard
+   * outside their scope and enforcement is on — the caller should answer with an
+   * empty result rather than silently widening back to everything.
+   *
+   * While `YARD_SCOPE_ENFORCE` is unset this always returns `null` and logs what
+   * it would have narrowed, so the mapping can be populated against real traffic
+   * before it starts hiding rows.
+   */
+  async listFilterYardIds(
+    user: ScopeUser | null | undefined,
+    requestedYardId: string | null | undefined,
+    context: string,
+  ): Promise<string[] | null> {
+    const scope = await this.getScopedYardIds(user);
+    if (scope === null) return null;
+
+    const outOfScope = !!requestedYardId && !scope.includes(requestedYardId);
+
+    if (!this.enforced) {
+      this.logger.warn(
+        `[yard-scope shadow] would narrow ${context} to [${scope.join(", ")}]` +
+          (outOfScope ? ` and reject yard=${requestedYardId}` : ""),
+      );
+      return null;
+    }
+
+    if (outOfScope) return [];
+    return requestedYardId ? [requestedYardId] : scope;
+  }
+
+  /** Drops the memoised scopes — call after editing the mapping. */
+  invalidate(): void {
+    this.cache.clear();
+  }
+
+  /** Active position plus any delegated ones, across both `employee` shapes. */
+  private effectivePositionIds(user: ScopeUser | null | undefined): string[] {
+    const ids = new Set<string>();
+    const employee = user?.employee;
+    if (!employee) return [];
+
+    if (Array.isArray(employee)) {
+      for (const emp of employee) {
+        for (const position of emp.positions ?? []) {
+          if (position?.id) ids.add(position.id);
+        }
+      }
+      return [...ids];
+    }
+
+    if (employee.position?.id) ids.add(employee.position.id);
+    for (const delegated of employee.delegatedPositions ?? []) {
+      if (delegated?.id) ids.add(delegated.id);
+    }
+    return [...ids];
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts
index 459b5009e..19d3b4b7a 100644
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.controller.ts
@@ -38,15 +38,21 @@ export class WarehouseInventoryController {
   @Get()
   @BookingStaff(FREIGHT_PERMS.warehouseInventory.view)
   @ApiOperation({ summary: 'List warehouse inventory' })
-  findAll(@Query() filter: FilterWarehouseInventoryDto) {
-    return this.inventoryService.findAll(filter);
+  findAll(
+    @Query() filter: FilterWarehouseInventoryDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.inventoryService.findAll(filter, user);
   }
 
   @Get('ready-for-loading')
   @BookingStaff(FREIGHT_PERMS.warehouseInventory.view)
   @ApiOperation({ summary: 'List inventory ready for loading' })
-  findReadyForLoading(@Query() filter: FilterWarehouseInventoryDto) {
-    return this.inventoryService.findReadyForLoading(filter);
+  findReadyForLoading(
+    @Query() filter: FilterWarehouseInventoryDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.inventoryService.findReadyForLoading(filter, user);
   }
 
   @Get('inquiry')
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 7412f0269..126998bae 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
@@ -39,6 +39,7 @@ import {
 import { SignaturesService } from '../signatures/signatures.service';
 import { StampSettingsService } from '../stamp-settings/stamp-settings.service';
 import { LogoSettingsService } from '../logo-settings/logo-settings.service';
+import { YardScopeService } from '../rule-engine/services/yard-scope.service';
 import { logoImageCss, logoMarkup } from '../billing/documents/logo-markup.util';
 import { sealClass, sealImageCss, sealMarkup } from '../billing/documents/seal-markup.util';
 import { BulkInspectDto } from './dto/bulk-inspect.dto';
@@ -423,6 +424,7 @@ export class WarehouseInventoryService {
     private readonly events: EventEmitter2,
     private readonly stampSettings: StampSettingsService,
     private readonly logoSettings: LogoSettingsService,
+    private readonly yardScope: YardScopeService,
   ) {}
 
   /**
@@ -978,7 +980,16 @@ export class WarehouseInventoryService {
 
   // ── Listing ────────────────────────────────────────────────────────────
 
-  async findAll(filter: FilterWarehouseInventoryDto): Promise<WarehouseInventory[]> {
+  /**
+   * `user` drives yard access scoping: a desk mapped to yards sees only those
+   * yards' inventory. Optional so internal callers that are not serving a
+   * request (schedulers, other services) are unaffected — they pass nothing and
+   * get the unscoped list, which is what they had before.
+   */
+  async findAll(
+    filter: FilterWarehouseInventoryDto,
+    user?: unknown,
+  ): Promise<WarehouseInventory[]> {
     const createdAt =
       filter.dateFrom && filter.dateTo
         ? Between(new Date(filter.dateFrom), new Date(filter.dateTo))
@@ -1020,6 +1031,32 @@ export class WarehouseInventoryService {
       });
     }
 
+    // Yard scoping — applied to `base` before the search branch splits it, so
+    // both OR arms carry the constraint. A null result means "do not narrow".
+    //
+    // Scoped on `warehouse.stationId`, NOT on `inventory.yardId`: those are two
+    // different id spaces that share a name. `warehouse_inventory.yard_id` is a
+    // FK to `warehouse_yards` — a yard INSIDE a warehouse — while the desk↔yard
+    // mapping is against `freight.yards`, the network yard, which inventory
+    // reaches through `warehouses.station_id`. Filtering `yardId` against
+    // mapped network yards matches nothing and hides every row (observed: all
+    // 34 rows disappeared before this was corrected).
+    //
+    // `filter.yardId` is likewise a warehouse-yard id, so it is NOT passed as
+    // the requested yard here; `filter.facilityId` is the station-yard filter.
+    const scopedYardIds = await this.yardScope.listFilterYardIds(
+      user as never,
+      filter.facilityId,
+      'warehouse-inventory list',
+    );
+    if (scopedYardIds) {
+      if (!scopedYardIds.length) return [];
+      base.warehouse = {
+        ...((base.warehouse as FindOptionsWhere<Warehouse>) ?? {}),
+        stationId: scopedYardIds.length === 1 ? scopedYardIds[0] : In(scopedYardIds),
+      };
+    }
+
     const search = filter.search?.trim();
     const where: FindManyOptions<WarehouseInventory>['where'] = search
       ? [
@@ -1037,8 +1074,11 @@ export class WarehouseInventoryService {
     return items;
   }
 
-  findReadyForLoading(filter: FilterWarehouseInventoryDto): Promise<WarehouseInventory[]> {
-    return this.findAll({ ...filter, status: 'READY_FOR_LOADING' });
+  findReadyForLoading(
+    filter: FilterWarehouseInventoryDto,
+    user?: unknown,
+  ): Promise<WarehouseInventory[]> {
+    return this.findAll({ ...filter, status: 'READY_FOR_LOADING' }, user);
   }
 
   /**
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 01c1d67d0..e39b08b59 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -459,6 +459,26 @@ export const GAP_CONTROLLER_PERMISSIONS: FreightPermissionSeed[] = [
   ),
 ];
 
+/**
+ * Yard access scoping. `yard_positions` maps desks to yards and the resolver
+ * (`YardScopeService`) narrows a caller to the yards their active position is
+ * mapped to. This key is the deliberate way out of that narrowing, for the HQ
+ * desks that are cross-yard by nature (OCC, CEO, rolling stock). Without it,
+ * "unmapped" would have to mean "sees everything", which is a bypass by
+ * accident rather than by grant.
+ *
+ * Editing the mapping itself needs no key of its own: it is yard configuration,
+ * so it rides on `rule_engine:yards:view` / `:update` like every other field on
+ * a yard.
+ */
+export const YARD_SCOPE_PERMISSIONS: FreightPermissionSeed[] = [
+  perm(
+    "f4a00001-0001-4000-8000-000000000001",
+    "edr_freight_app:yards:view_all",
+    "Access every yard (bypass yard scoping)",
+  ),
+];
+
 /**
  * Advanced backoffice resources — full CRUD + workflow-action keys.
  * See docs/rbac/freight-backoffice-permissions.md. Additive only: the existing
@@ -1667,6 +1687,7 @@ export const BOOKING_RULE_ENGINE_PERMISSIONS = [
   ...CONTRACT_PERMISSIONS,
   ...RULE_ENGINE_PERMISSIONS,
   ...GAP_CONTROLLER_PERMISSIONS,
+  ...YARD_SCOPE_PERMISSIONS,
   ...ADVANCED_BACKOFFICE_PERMISSIONS,
 ];
 
@@ -1844,6 +1865,10 @@ export const FREIGHT_PERMS = {
   allocation: {
     manage: "edr_freight_app:allocation:manage",
   },
+  yards: {
+    /** Bypasses yard scoping entirely — see YARD_SCOPE_PERMISSIONS. */
+    viewAll: "edr_freight_app:yards:view_all",
+  },
   customers: {
     view: "edr_freight_app:customers:view",
     create: "edr_freight_app:customers:create",
diff --git a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
index 688ed3ce2..a83a90fb4 100644
--- a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx
@@ -26,6 +26,7 @@ import { PageContainer, PageHeader } from "@/components/page";
 import ManageRuleEngineOrderDialog from "@/components/ruleEngine/ManageRuleEngineOrderDialog";
 import PriorityRuleApprovalsSection from "@/pages/ruleEngine/PriorityRuleApprovalsSection";
 import RateApprovalsSection from "@/pages/ruleEngine/RateApprovalsSection";
+import { YardDesksModal } from "@/pages/ruleEngine/YardDesksModal";
 import { nextPriorityRangeStart } from "@/pages/ruleEngine/priorityRuleRange";
 import RuleEngineCardGrid from "@/components/ruleEngine/RuleEngineCardGrid";
 import RuleEngineFormDialog from "@/components/ruleEngine/RuleEngineFormDialog";
@@ -167,6 +168,10 @@ const RuleEngineResourcePage = () => {
     null,
   );
   const [chainOpen, setChainOpen] = useState(false);
+  // Yards only: which desks work at this yard (input to yard access scoping).
+  const [desksYard, setDesksYard] = useState<Record<string, unknown> | null>(
+    null,
+  );
   const [orderDialogOpen, setOrderDialogOpen] = useState(false);
   const { viewMode, setViewMode } = useRuleEngineViewMode(
     config?.slug ?? DEFAULT_CONFIGURATION_SLUG,
@@ -566,6 +571,17 @@ const RuleEngineResourcePage = () => {
       cell: ({ row }) => (
         <div onClick={(e) => e.stopPropagation()} data-stop-row-click>
           <Group gap="xs" wrap="nowrap" justify="flex-end">
+            {config.slug === "yards" ? (
+              <Tooltip label="Desks that work at this yard">
+                <Button
+                  size="compact-xs"
+                  variant="light"
+                  onClick={() => setDesksYard(row.original)}
+                >
+                  Desks
+                </Button>
+              </Tooltip>
+            ) : null}
             {config.orderConfig && canUpdateControls ? (
               <RuleEngineOrderControls
                 record={row.original}
@@ -968,6 +984,21 @@ const RuleEngineResourcePage = () => {
         </Stack>
       </Card>
 
+      <YardDesksModal
+        opened={!!desksYard}
+        onClose={() => setDesksYard(null)}
+        readOnly={!canUpdateControls}
+        yard={
+          desksYard
+            ? {
+                id: String(desksYard.id),
+                code: String(desksYard.code ?? ""),
+                label: String(desksYard.label ?? ""),
+              }
+            : null
+        }
+      />
+
       <RuleEngineFormDialog
         open={formOpen}
         onOpenChange={setFormOpen}
diff --git a/apps/edr-freight-web/backoffice/src/pages/ruleEngine/YardDesksModal.tsx b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/YardDesksModal.tsx
new file mode 100644
index 000000000..5a9b6ccf6
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/ruleEngine/YardDesksModal.tsx
@@ -0,0 +1,134 @@
+import { useEffect, useState } from "react";
+import {
+  Alert,
+  Button,
+  Group,
+  Loader,
+  Modal,
+  MultiSelect,
+  Stack,
+  Text,
+} from "@mantine/core";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import toast from "react-hot-toast";
+
+import { extractErrorMessage } from "@/utils/errorExtractor";
+import { yardPositionsService } from "@/services/yardPositions.service";
+
+interface YardDesksModalProps {
+  opened: boolean;
+  onClose: () => void;
+  yard: { id: string; code: string; label: string } | null;
+  /** Read-only when the caller lacks the yards update permission. */
+  readOnly?: boolean;
+}
+
+const positionLabel = (
+  name: { am?: string; en?: string } | null,
+  fallback: string,
+) => name?.en?.trim() || name?.am?.trim() || fallback;
+
+/**
+ * Which desks staff a yard — the input to yard access scoping.
+ *
+ * Saving REPLACES the yard's whole set (the API's PUT is a replace), which is
+ * why the control is a multi-select holding the complete list rather than
+ * add/remove buttons.
+ */
+export function YardDesksModal({
+  opened,
+  onClose,
+  yard,
+  readOnly = false,
+}: YardDesksModalProps) {
+  const queryClient = useQueryClient();
+  const [selected, setSelected] = useState<string[]>([]);
+
+  const positions = useQuery({
+    queryKey: ["yard-positions", "positions"],
+    queryFn: yardPositionsService.listPositions,
+    enabled: opened,
+    staleTime: 5 * 60 * 1000,
+  });
+
+  const mapping = useQuery({
+    queryKey: ["yard-positions", "yard", yard?.id],
+    queryFn: () => yardPositionsService.listByYard(yard!.id),
+    enabled: opened && !!yard?.id,
+  });
+
+  // Reset to what the server holds whenever the modal opens on a new yard, so a
+  // cancelled edit never leaks into the next one.
+  useEffect(() => {
+    if (mapping.data) setSelected(mapping.data.map((row) => row.positionId));
+  }, [mapping.data]);
+
+  const save = useMutation({
+    mutationFn: () => yardPositionsService.setForYard(yard!.id, selected),
+    onSuccess: () => {
+      toast.success("Yard desks updated");
+      queryClient.invalidateQueries({ queryKey: ["yard-positions"] });
+      onClose();
+    },
+    onError: (error) =>
+      toast.error(extractErrorMessage(error, "Failed to update yard desks")),
+  });
+
+  const options = (positions.data ?? []).map((position) => ({
+    value: position.id,
+    label: positionLabel(position.name, position.id.slice(0, 8)),
+  }));
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      title={yard ? `Desks at ${yard.label} (${yard.code})` : "Desks"}
+      size="lg"
+    >
+      <Stack gap="md">
+        <Alert color="blue" variant="light">
+          <Text size="sm">
+            Positions mapped here are the desks that work at this yard. Yard
+            access scoping reads this mapping — a staff member acting on this
+            desk is scoped to this yard.
+          </Text>
+        </Alert>
+
+        {positions.isLoading || mapping.isLoading ? (
+          <Group justify="center" py="lg">
+            <Loader size="sm" />
+          </Group>
+        ) : (
+          <MultiSelect
+            data={options}
+            value={selected}
+            onChange={setSelected}
+            disabled={readOnly}
+            label="Positions"
+            placeholder={selected.length ? undefined : "Select positions"}
+            description="Saving replaces the whole set — anything removed here loses this yard."
+            searchable
+            clearable
+            hidePickedOptions
+            maxDropdownHeight={280}
+          />
+        )}
+
+        <Group justify="flex-end">
+          <Button variant="default" onClick={onClose}>
+            Cancel
+          </Button>
+          <Button
+            onClick={() => save.mutate()}
+            loading={save.isPending}
+            disabled={readOnly || mapping.isLoading}
+            title={readOnly ? "You cannot edit yards" : undefined}
+          >
+            Save
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/services/yardPositions.service.ts b/apps/edr-freight-web/backoffice/src/services/yardPositions.service.ts
new file mode 100644
index 000000000..db8984827
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/services/yardPositions.service.ts
@@ -0,0 +1,64 @@
+import { api as apiClient } from "../auth/http";
+
+// NOTE: `auth/http`'s response interceptor already unwraps the API's
+// `{ success, data }` envelope, so `response.data` IS the payload here — a
+// second `.data` hop reads undefined and silently yields an empty list.
+
+/** A desk mapped to a yard, joined to its IAM position for display. */
+export interface YardPositionRow {
+  id: string;
+  yardId: string;
+  yardCode: string;
+  yardLabel: string;
+  positionId: string;
+  positionName: { am?: string; en?: string } | null;
+  positionTypeKey: string | null;
+}
+
+export interface SelectablePosition {
+  id: string;
+  name: { am?: string; en?: string } | null;
+  positionTypeKey: string | null;
+  unitKey: string | null;
+}
+
+export interface MyYardScope {
+  /** null = unrestricted (super admin or `yards:view_all`). */
+  yardIds: string[] | null;
+  unrestricted: boolean;
+  /** False while the backend is still shadow-logging instead of denying. */
+  enforced: boolean;
+}
+
+export const yardPositionsService = {
+  listByYard: async (yardId: string): Promise<YardPositionRow[]> => {
+    const { data } = await apiClient.get(`/yard-positions`, {
+      params: { yardId },
+    });
+    return data ?? [];
+  },
+
+  listPositions: async (): Promise<SelectablePosition[]> => {
+    const { data } = await apiClient.get(`/yard-positions/positions`);
+    return data ?? [];
+  },
+
+  myScope: async (): Promise<MyYardScope> => {
+    const { data } = await apiClient.get(`/yard-positions/my-yards`);
+    return data;
+  },
+
+  /**
+   * Replaces the yard's whole desk set — send every position that should remain
+   * mapped, not just the additions.
+   */
+  setForYard: async (
+    yardId: string,
+    positionIds: string[],
+  ): Promise<YardPositionRow[]> => {
+    const { data } = await apiClient.put(`/yard-positions/yard/${yardId}`, {
+      positionIds,
+    });
+    return data ?? [];
+  },
+};
diff --git a/apps/edr-freight-web/backoffice/src/user-management/AppMenuTabs.tsx b/apps/edr-freight-web/backoffice/src/user-management/AppMenuTabs.tsx
index 127806334..4e8f30561 100644
--- a/apps/edr-freight-web/backoffice/src/user-management/AppMenuTabs.tsx
+++ b/apps/edr-freight-web/backoffice/src/user-management/AppMenuTabs.tsx
@@ -1,250 +1,258 @@
-import { Link, useLocation } from "react-router-dom";
-import {
-  Archive,
-  BarChart,
-  Building2,
-  ChartAreaIcon,
-  ClipboardList,
-  FileText,
-  Globe,
-  Settings,
-  Users2,
-  UsersRound,
-} from "lucide-react";
-import { useTranslation } from "react-i18next";
-
-import { useAuth } from "@/shared/context/AuthContext";
-import {
-  SidebarGroup,
-  SidebarGroupContent,
-  SidebarGroupLabel,
-  SidebarMenu,
-  SidebarMenuButton,
-  SidebarMenuItem,
-  useSidebar,
-} from "@/shared/common/ui/sidebar";
-
-export interface MenuItem {
-  label: string;
-  href: string;
-  icon: React.ReactNode;
-  roles?: string[];
-  /** Sidebar section this item is bucketed under. */
-  group: string;
-}
-
-// Section render order; groups with no role-visible items are skipped.
-const GROUP_ORDER = [
-  "Overview",
-  "Organizations",
-  "Content",
-  "Records",
-  "Configuration",
-  "Archive",
-  "System",
-];
-
-export const AppMenuTabs = () => {
-  const { user } = useAuth();
-  const { pathname } = useLocation();
-  const { setOpenMobile } = useSidebar();
-  const { t } = useTranslation();
-
-  const userRoles = user?.roles.map((role) => role.key) || [];
-
-  const menuItems: MenuItem[] = [
-    {
-      label: "dashboard",
-      href: "/user-management/dashboard",
-      icon: <BarChart className="h-4 w-4" />,
-      roles: ["super_admin"],
-      group: "Overview",
-    },
-    {
-      label: "organizations",
-      href: "/user-management/organizations",
-      icon: <Building2 className="h-4 w-4" />,
-      roles: ["super_admin"],
-      group: "Organizations",
-    },
-    {
-      label: "organizationAdmins",
-      href: "/user-management/organization_admins",
-      icon: <Users2 className="h-4 w-4" />,
-      roles: ["super_admin"],
-      group: "Organizations",
-    },
-    {
-      label: "externalUsers",
-      href: "/user-management/external_users",
-      icon: <Users2 className="h-4 w-4" />,
-      roles: ["super_admin"],
-      group: "Organizations",
-    },
-    {
-      label: "dashboard",
-      href: "/user-management/user_management-dashboard",
-      icon: <BarChart className="h-4 w-4" />,
-      roles: ["admin", "organization_admin", "unit_admin"],
-      group: "Overview",
-    },
-    {
-      label: "userManagement",
-      href: "/user-management/user_management",
-      icon: <UsersRound className="h-4 w-4" />,
-      roles: ["admin", "organization_admin", "unit_admin"],
-      group: "Overview",
-    },
-    {
-      label: "contentManagement",
-      href: "/user-management/content-management",
-      icon: <FileText className="h-4 w-4" />,
-      roles: ["admin", "organization_admin", "unit_admin"],
-      group: "Content",
-    },
-    {
-      label: "webManagement",
-      href: "/user-management/web-management",
-      icon: <Globe className="h-4 w-4" />,
-      roles: ["admin", "organization_admin", "unit_admin"],
-      group: "Content",
-    },
-    {
-      label: "Bulk",
-      href: "/user-management/bulk-upload",
-      icon: <FileText className="h-4 w-4" />,
-      roles: ["admin", "organization_admin", "unit_admin"],
-      group: "Content",
-    },
-    {
-      label: "Position",
-      href: "/user-management/position-management",
-      icon: <FileText className="h-4 w-4" />,
-      roles: ["admin", "organization_admin", "unit_admin", "super_admin"],
-      group: "Configuration",
-    },
-    {
-      label: "settings",
-      href: "/user-management/organization-settings",
-      icon: <Settings className="h-4 w-4" />,
-      roles: ["admin", "organization_admin", "unit_admin"],
-      group: "Configuration",
-    },
-    {
-      label: "Add Site",
-      href: "/user-management/add-site",
-      icon: <Globe className="h-4 w-4" />,
-      roles: ["super_admin"],
-      group: "Configuration",
-    },
-    {
-      label: "migratedRecords",
-      href: "/user-management/migrated-records-management",
-      icon: <FileText className="h-4 w-4" />,
-      roles: ["super_admin"],
-      group: "Records",
-    },
-    {
-      label: "Sector Reports",
-      href: "/user-management/sector-reports",
-      icon: <ChartAreaIcon className="h-4 w-4" />,
-      roles: ["unit_admin", "admin", "organization_admin"],
-      group: "Records",
-    },
-    {
-      label: "Archive Users",
-      href: "/user-management/archive-users",
-      icon: <Archive className="h-4 w-4" />,
-      roles: ["super_admin"],
-      group: "Archive",
-    },
-    {
-      label: "Archived Organizations",
-      href: "/user-management/archived-organizations",
-      icon: <Archive className="h-4 w-4" />,
-      roles: ["super_admin"],
-      group: "Archive",
-    },
-    {
-      label: "Archive Users",
-      href: "/user-management/archives",
-      icon: <Archive className="h-4 w-4" />,
-      roles: ["admin", "organization_admin", "unit_admin"],
-      group: "Archive",
-    },
-    {
-      label: "Archived Units & Positions",
-      href: "/user-management/archived",
-      icon: <Archive className="h-4 w-4" />,
-      roles: ["admin", "organization_admin", "unit_admin"],
-      group: "Archive",
-    },
-    {
-      label: "activityLog",
-      href: "/user-management/activity_log",
-      icon: <ClipboardList className="h-4 w-4" />,
-      roles: ["super_admin"],
-      group: "System",
-    },
-    {
-      label: "setting",
-      href: "/user-management/settings",
-      icon: <Settings className="h-4 w-4" />,
-      roles: ["super_admin"],
-      group: "System",
-    },
-    {
-      label: "Letter Template",
-      href: "/user-management/templates",
-      icon: <FileText className="h-4 w-4" />,
-      roles: ["super_admin"],
-      group: "System",
-    },
-  ];
-
-  const filteredMenu = menuItems.filter((item) =>
-    item.roles?.some((r) => userRoles.includes(r)),
-  );
-
-  const isActive = (href: string) =>
-    pathname === href || pathname.startsWith(`${href}/`);
-
-  return (
-    <>
-      {GROUP_ORDER.map((group) => {
-        const items = filteredMenu.filter((item) => item.group === group);
-        if (items.length === 0) return null;
-
-        return (
-          <SidebarGroup key={group} className="pb-0">
-            <SidebarGroupLabel>{group}</SidebarGroupLabel>
-            <SidebarGroupContent>
-              <SidebarMenu>
-                {items.map((item) => {
-                  const label = t(`organization.${item.label}`, item.label);
-                  return (
-                    <SidebarMenuItem key={item.href}>
-                      <SidebarMenuButton
-                        asChild
-                        isActive={isActive(item.href)}
-                        tooltip={label}
-                      >
-                        <Link
-                          to={item.href}
-                          onClick={() => setOpenMobile(false)}
-                        >
-                          {item.icon}
-                          <span>{label}</span>
-                        </Link>
-                      </SidebarMenuButton>
-                    </SidebarMenuItem>
-                  );
-                })}
-              </SidebarMenu>
-            </SidebarGroupContent>
-          </SidebarGroup>
-        );
-      })}
-    </>
-  );
-};
+import { Link, useLocation } from "react-router-dom";
+import {
+  Archive,
+  BarChart,
+  Building2,
+  ChartAreaIcon,
+  ClipboardList,
+  FileText,
+  Globe,
+  MapPin,
+  Settings,
+  Users2,
+  UsersRound,
+} from "lucide-react";
+import { useTranslation } from "react-i18next";
+
+import { useAuth } from "@/shared/context/AuthContext";
+import {
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  useSidebar,
+} from "@/shared/common/ui/sidebar";
+
+export interface MenuItem {
+  label: string;
+  href: string;
+  icon: React.ReactNode;
+  roles?: string[];
+  /** Sidebar section this item is bucketed under. */
+  group: string;
+}
+
+// Section render order; groups with no role-visible items are skipped.
+const GROUP_ORDER = [
+  "Overview",
+  "Organizations",
+  "Content",
+  "Records",
+  "Configuration",
+  "Archive",
+  "System",
+];
+
+export const AppMenuTabs = () => {
+  const { user } = useAuth();
+  const { pathname } = useLocation();
+  const { setOpenMobile } = useSidebar();
+  const { t } = useTranslation();
+
+  const userRoles = user?.roles.map((role) => role.key) || [];
+
+  const menuItems: MenuItem[] = [
+    {
+      label: "dashboard",
+      href: "/user-management/dashboard",
+      icon: <BarChart className="h-4 w-4" />,
+      roles: ["super_admin"],
+      group: "Overview",
+    },
+    {
+      label: "organizations",
+      href: "/user-management/organizations",
+      icon: <Building2 className="h-4 w-4" />,
+      roles: ["super_admin"],
+      group: "Organizations",
+    },
+    {
+      label: "organizationAdmins",
+      href: "/user-management/organization_admins",
+      icon: <Users2 className="h-4 w-4" />,
+      roles: ["super_admin"],
+      group: "Organizations",
+    },
+    {
+      label: "externalUsers",
+      href: "/user-management/external_users",
+      icon: <Users2 className="h-4 w-4" />,
+      roles: ["super_admin"],
+      group: "Organizations",
+    },
+    {
+      label: "dashboard",
+      href: "/user-management/user_management-dashboard",
+      icon: <BarChart className="h-4 w-4" />,
+      roles: ["admin", "organization_admin", "unit_admin"],
+      group: "Overview",
+    },
+    {
+      label: "userManagement",
+      href: "/user-management/user_management",
+      icon: <UsersRound className="h-4 w-4" />,
+      roles: ["admin", "organization_admin", "unit_admin"],
+      group: "Overview",
+    },
+    {
+      label: "contentManagement",
+      href: "/user-management/content-management",
+      icon: <FileText className="h-4 w-4" />,
+      roles: ["admin", "organization_admin", "unit_admin"],
+      group: "Content",
+    },
+    {
+      label: "webManagement",
+      href: "/user-management/web-management",
+      icon: <Globe className="h-4 w-4" />,
+      roles: ["admin", "organization_admin", "unit_admin"],
+      group: "Content",
+    },
+    {
+      label: "Bulk",
+      href: "/user-management/bulk-upload",
+      icon: <FileText className="h-4 w-4" />,
+      roles: ["admin", "organization_admin", "unit_admin"],
+      group: "Content",
+    },
+    {
+      label: "Position",
+      href: "/user-management/position-management",
+      icon: <FileText className="h-4 w-4" />,
+      roles: ["admin", "organization_admin", "unit_admin", "super_admin"],
+      group: "Configuration",
+    },
+    {
+      label: "Locations",
+      href: "/user-management/locations",
+      icon: <MapPin className="h-4 w-4" />,
+      roles: ["admin", "organization_admin", "unit_admin", "super_admin"],
+      group: "Configuration",
+    },
+    {
+      label: "settings",
+      href: "/user-management/organization-settings",
+      icon: <Settings className="h-4 w-4" />,
+      roles: ["admin", "organization_admin", "unit_admin"],
+      group: "Configuration",
+    },
+    {
+      label: "Add Site",
+      href: "/user-management/add-site",
+      icon: <Globe className="h-4 w-4" />,
+      roles: ["super_admin"],
+      group: "Configuration",
+    },
+    {
+      label: "migratedRecords",
+      href: "/user-management/migrated-records-management",
+      icon: <FileText className="h-4 w-4" />,
+      roles: ["super_admin"],
+      group: "Records",
+    },
+    {
+      label: "Sector Reports",
+      href: "/user-management/sector-reports",
+      icon: <ChartAreaIcon className="h-4 w-4" />,
+      roles: ["unit_admin", "admin", "organization_admin"],
+      group: "Records",
+    },
+    {
+      label: "Archive Users",
+      href: "/user-management/archive-users",
+      icon: <Archive className="h-4 w-4" />,
+      roles: ["super_admin"],
+      group: "Archive",
+    },
+    {
+      label: "Archived Organizations",
+      href: "/user-management/archived-organizations",
+      icon: <Archive className="h-4 w-4" />,
+      roles: ["super_admin"],
+      group: "Archive",
+    },
+    {
+      label: "Archive Users",
+      href: "/user-management/archives",
+      icon: <Archive className="h-4 w-4" />,
+      roles: ["admin", "organization_admin", "unit_admin"],
+      group: "Archive",
+    },
+    {
+      label: "Archived Units & Positions",
+      href: "/user-management/archived",
+      icon: <Archive className="h-4 w-4" />,
+      roles: ["admin", "organization_admin", "unit_admin"],
+      group: "Archive",
+    },
+    {
+      label: "activityLog",
+      href: "/user-management/activity_log",
+      icon: <ClipboardList className="h-4 w-4" />,
+      roles: ["super_admin"],
+      group: "System",
+    },
+    {
+      label: "setting",
+      href: "/user-management/settings",
+      icon: <Settings className="h-4 w-4" />,
+      roles: ["super_admin"],
+      group: "System",
+    },
+    {
+      label: "Letter Template",
+      href: "/user-management/templates",
+      icon: <FileText className="h-4 w-4" />,
+      roles: ["super_admin"],
+      group: "System",
+    },
+  ];
+
+  const filteredMenu = menuItems.filter((item) =>
+    item.roles?.some((r) => userRoles.includes(r)),
+  );
+
+  const isActive = (href: string) =>
+    pathname === href || pathname.startsWith(`${href}/`);
+
+  return (
+    <>
+      {GROUP_ORDER.map((group) => {
+        const items = filteredMenu.filter((item) => item.group === group);
+        if (items.length === 0) return null;
+
+        return (
+          <SidebarGroup key={group} className="pb-0">
+            <SidebarGroupLabel>{group}</SidebarGroupLabel>
+            <SidebarGroupContent>
+              <SidebarMenu>
+                {items.map((item) => {
+                  const label = t(`organization.${item.label}`, item.label);
+                  return (
+                    <SidebarMenuItem key={item.href}>
+                      <SidebarMenuButton
+                        asChild
+                        isActive={isActive(item.href)}
+                        tooltip={label}
+                      >
+                        <Link
+                          to={item.href}
+                          onClick={() => setOpenMobile(false)}
+                        >
+                          {item.icon}
+                          <span>{label}</span>
+                        </Link>
+                      </SidebarMenuButton>
+                    </SidebarMenuItem>
+                  );
+                })}
+              </SidebarMenu>
+            </SidebarGroupContent>
+          </SidebarGroup>
+        );
+      })}
+    </>
+  );
+};
diff --git a/apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationForm.tsx b/apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationForm.tsx
new file mode 100644
index 000000000..aeb03cd71
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationForm.tsx
@@ -0,0 +1,365 @@
+import { useForm } from "react-hook-form";
+import { z } from "zod";
+import { zodResolver } from "@hookform/resolvers/zod";
+import {
+  APIProvider,
+  Map as GoogleMap,
+  Marker,
+  type MapMouseEvent,
+} from "@vis.gl/react-google-maps";
+
+import { Button } from "@/shared/common/ui/button";
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@/shared/common/ui/form";
+import { Input } from "@/shared/common/ui/input";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/shared/common/ui/select";
+import { Textarea } from "@/shared/common/ui/textarea";
+import { useLocalizedName } from "@/shared/common/localizedName";
+import type {
+  Location,
+  LocationPayload,
+  LocationType,
+} from "@/user-management/dto/locations/location.type";
+import { useLocations } from "@/user-management/hooks/useLocations";
+
+const GOOGLE_MAPS_API_KEY = import.meta.env.VITE_GOOGLE_MAPS_API_KEY?.trim();
+/** Addis Ababa — where every EDR location is within a map pan. */
+const DEFAULT_CENTER = { lat: 9.032, lng: 38.7469 };
+
+const NO_PARENT = "__none__";
+
+const numeric = (label: string) =>
+  z
+    .string()
+    .trim()
+    .optional()
+    .refine((v) => !v || !Number.isNaN(Number(v)), `${label} must be a number`);
+
+const locationSchema = z.object({
+  nameAm: z.string().trim().min(1, "Amharic name is required"),
+  nameEn: z.string().trim().optional(),
+  code: z.string().trim().min(1, "Code is required"),
+  locationTypeId: z.string().uuid("Location type is required"),
+  parentId: z.string().optional(),
+  latitude: numeric("Latitude"),
+  longitude: numeric("Longitude"),
+  area: numeric("Area"),
+  boundaryJson: z
+    .string()
+    .trim()
+    .optional()
+    .refine((v) => {
+      if (!v) return true;
+      try {
+        const parsed = JSON.parse(v);
+        return typeof parsed === "object" && parsed !== null;
+      } catch {
+        return false;
+      }
+    }, "Boundary must be a JSON object"),
+});
+
+export type LocationFormValues = z.infer<typeof locationSchema>;
+
+interface LocationFormProps {
+  mode: "create" | "edit";
+  location?: Location;
+  locationTypes: LocationType[];
+  /** Every location, for the parent picker — the API has no filter endpoint. */
+  allLocations: Location[];
+  onSuccess?: () => void;
+}
+
+export function LocationForm({
+  mode,
+  location,
+  locationTypes,
+  allLocations,
+  onSuccess,
+}: LocationFormProps) {
+  const localizedName = useLocalizedName();
+  const { createLocation, updateLocation, isCreatingLocation, isUpdatingLocation } =
+    useLocations();
+
+  const form = useForm<LocationFormValues>({
+    resolver: zodResolver(locationSchema),
+    defaultValues: {
+      nameAm: location?.names?.am ?? "",
+      nameEn: location?.names?.en ?? "",
+      code: location?.code ?? "",
+      locationTypeId: location?.locationTypeId ?? "",
+      parentId: location?.parentId ?? NO_PARENT,
+      latitude: location?.latitude ?? "",
+      longitude: location?.longitude ?? "",
+      area: location?.area ?? "",
+      boundaryJson: location?.boundaryJson
+        ? JSON.stringify(location.boundaryJson, null, 2)
+        : "",
+    },
+  });
+
+  const [lat, lng] = [form.watch("latitude"), form.watch("longitude")];
+  const pin =
+    lat && lng && !Number.isNaN(Number(lat)) && !Number.isNaN(Number(lng))
+      ? { lat: Number(lat), lng: Number(lng) }
+      : null;
+
+  const dropPin = (event: MapMouseEvent) => {
+    const point = event.detail.latLng;
+    if (!point) return;
+    form.setValue("latitude", point.lat.toFixed(6), { shouldDirty: true });
+    form.setValue("longitude", point.lng.toFixed(6), { shouldDirty: true });
+  };
+
+  // ponytail: self only, not descendants — the API accepts any parentId, so a
+  // deep cycle (A → B → A) is still possible. Walk the chain here if it bites.
+  const parentOptions = allLocations.filter((item) => item.id !== location?.id);
+
+  const submit = (values: LocationFormValues) => {
+    const payload: LocationPayload = {
+      names: {
+        am: values.nameAm,
+        ...(values.nameEn ? { en: values.nameEn } : {}),
+      },
+      code: values.code,
+      locationTypeId: values.locationTypeId,
+      parentId:
+        values.parentId && values.parentId !== NO_PARENT
+          ? values.parentId
+          : undefined,
+      latitude: values.latitude || undefined,
+      longitude: values.longitude || undefined,
+      area: values.area || undefined,
+      boundaryJson: values.boundaryJson
+        ? (JSON.parse(values.boundaryJson) as Record<string, unknown>)
+        : undefined,
+    };
+
+    if (mode === "create") {
+      createLocation(payload, {
+        onSuccess: () => {
+          form.reset();
+          onSuccess?.();
+        },
+      });
+      return;
+    }
+    if (location) {
+      updateLocation(
+        { id: location.id, payload },
+        { onSuccess: () => onSuccess?.() },
+      );
+    }
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(submit)} className="space-y-4">
+        <div className="grid grid-cols-2 gap-4">
+          <FormField
+            control={form.control}
+            name="nameAm"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Amharic Name *</FormLabel>
+                <FormControl>
+                  <Input placeholder="አዲስ አበባ" {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name="nameEn"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>English Name</FormLabel>
+                <FormControl>
+                  <Input placeholder="Addis Ababa" {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name="code"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Code *</FormLabel>
+                <FormControl>
+                  <Input placeholder="LOC-001" {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name="locationTypeId"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Location Type *</FormLabel>
+                <Select onValueChange={field.onChange} value={field.value}>
+                  <FormControl>
+                    <SelectTrigger>
+                      <SelectValue placeholder="Select a type" />
+                    </SelectTrigger>
+                  </FormControl>
+                  <SelectContent>
+                    {locationTypes.map((type) => (
+                      <SelectItem key={type.id} value={type.id}>
+                        {localizedName(type.names)} · L{type.level}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name="parentId"
+            render={({ field }) => (
+              <FormItem className="col-span-2">
+                <FormLabel>Parent Location</FormLabel>
+                <Select onValueChange={field.onChange} value={field.value}>
+                  <FormControl>
+                    <SelectTrigger>
+                      <SelectValue placeholder="No parent (top level)" />
+                    </SelectTrigger>
+                  </FormControl>
+                  <SelectContent>
+                    <SelectItem value={NO_PARENT}>
+                      No parent (top level)
+                    </SelectItem>
+                    {parentOptions.map((item) => (
+                      <SelectItem key={item.id} value={item.id}>
+                        {localizedName(item.names)} ({item.code})
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+        </div>
+
+        <div className="space-y-2">
+          <FormLabel>Coordinates</FormLabel>
+          {GOOGLE_MAPS_API_KEY ? (
+            <div className="h-64 w-full overflow-hidden rounded-md border">
+              <APIProvider apiKey={GOOGLE_MAPS_API_KEY}>
+                <GoogleMap
+                  defaultCenter={pin ?? DEFAULT_CENTER}
+                  defaultZoom={pin ? 12 : 6}
+                  gestureHandling="greedy"
+                  disableDefaultUI={false}
+                  onClick={dropPin}
+                  style={{ width: "100%", height: "100%" }}
+                >
+                  {pin ? <Marker position={pin} /> : null}
+                </GoogleMap>
+              </APIProvider>
+            </div>
+          ) : (
+            // Name the missing variable rather than rendering a dead grey box.
+            <p className="rounded-md border border-amber-200 bg-amber-50 p-3 text-sm text-amber-800">
+              Map picker unavailable — <code>VITE_GOOGLE_MAPS_API_KEY</code> is
+              not set. Type the coordinates below instead.
+            </p>
+          )}
+          {GOOGLE_MAPS_API_KEY ? (
+            <p className="text-xs text-muted-foreground">
+              Click the map to drop a pin, or type the values.
+            </p>
+          ) : null}
+        </div>
+
+        <div className="grid grid-cols-3 gap-4">
+          <FormField
+            control={form.control}
+            name="latitude"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Latitude</FormLabel>
+                <FormControl>
+                  <Input placeholder="9.032000" {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name="longitude"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Longitude</FormLabel>
+                <FormControl>
+                  <Input placeholder="38.746900" {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name="area"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Area</FormLabel>
+                <FormControl>
+                  <Input placeholder="1000.25" {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+        </div>
+
+        <FormField
+          control={form.control}
+          name="boundaryJson"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Boundary (GeoJSON)</FormLabel>
+              <FormControl>
+                <Textarea
+                  rows={4}
+                  placeholder='{"type":"Polygon","coordinates":[]}'
+                  className="font-mono text-xs"
+                  {...field}
+                />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        <Button
+          type="submit"
+          className="w-full"
+          disabled={isCreatingLocation || isUpdatingLocation}
+        >
+          {mode === "create" ? "Create Location" : "Save Changes"}
+        </Button>
+      </form>
+    </Form>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationTypeForm.tsx b/apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationTypeForm.tsx
new file mode 100644
index 000000000..242a53c7a
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationTypeForm.tsx
@@ -0,0 +1,173 @@
+import { useForm } from "react-hook-form";
+import { z } from "zod";
+import { zodResolver } from "@hookform/resolvers/zod";
+
+import { Button } from "@/shared/common/ui/button";
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@/shared/common/ui/form";
+import { Input } from "@/shared/common/ui/input";
+import { Textarea } from "@/shared/common/ui/textarea";
+import type {
+  LocationType,
+  LocationTypePayload,
+} from "@/user-management/dto/locations/location.type";
+import { useLocationTypes } from "@/user-management/hooks/useLocationTypes";
+
+const locationTypeSchema = z.object({
+  nameAm: z.string().trim().min(1, "Amharic name is required"),
+  nameEn: z.string().trim().optional(),
+  code: z.string().trim().min(1, "Code is required"),
+  description: z.string().trim().optional(),
+  // Level is the hierarchy depth (1 = country, 2 = region, …). Server takes a
+  // number, so an empty string would post NaN.
+  level: z.coerce.number().int().min(1, "Level must be 1 or greater"),
+});
+
+export type LocationTypeFormValues = z.input<typeof locationTypeSchema>;
+
+interface LocationTypeFormProps {
+  mode: "create" | "edit";
+  locationType?: LocationType;
+  onSuccess?: () => void;
+}
+
+export function LocationTypeForm({
+  mode,
+  locationType,
+  onSuccess,
+}: LocationTypeFormProps) {
+  const {
+    createLocationType,
+    updateLocationType,
+    isCreatingLocationType,
+    isUpdatingLocationType,
+  } = useLocationTypes();
+
+  const form = useForm<LocationTypeFormValues, unknown, z.output<typeof locationTypeSchema>>({
+    resolver: zodResolver(locationTypeSchema),
+    defaultValues: {
+      nameAm: locationType?.names?.am ?? "",
+      nameEn: locationType?.names?.en ?? "",
+      code: locationType?.code ?? "",
+      description: locationType?.description ?? "",
+      level: locationType?.level ?? 1,
+    },
+  });
+
+  const submit = (values: z.output<typeof locationTypeSchema>) => {
+    const payload: LocationTypePayload = {
+      names: {
+        am: values.nameAm,
+        ...(values.nameEn ? { en: values.nameEn } : {}),
+      },
+      code: values.code,
+      description: values.description || undefined,
+      level: values.level,
+    };
+
+    if (mode === "create") {
+      createLocationType(payload, {
+        onSuccess: () => {
+          form.reset();
+          onSuccess?.();
+        },
+      });
+      return;
+    }
+    if (locationType) {
+      updateLocationType(
+        { id: locationType.id, payload },
+        { onSuccess: () => onSuccess?.() },
+      );
+    }
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(submit)} className="space-y-4">
+        <div className="grid grid-cols-2 gap-4">
+          <FormField
+            control={form.control}
+            name="nameAm"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Amharic Name *</FormLabel>
+                <FormControl>
+                  <Input placeholder="ከተማ" {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name="nameEn"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>English Name</FormLabel>
+                <FormControl>
+                  <Input placeholder="City" {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name="code"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Code *</FormLabel>
+                <FormControl>
+                  <Input placeholder="CITY" {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            control={form.control}
+            name="level"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Level *</FormLabel>
+                <FormControl>
+                  <Input type="number" min={1} {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+        </div>
+
+        <FormField
+          control={form.control}
+          name="description"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Description</FormLabel>
+              <FormControl>
+                <Textarea rows={3} placeholder="City level location" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        <Button
+          type="submit"
+          className="w-full"
+          disabled={isCreatingLocationType || isUpdatingLocationType}
+        >
+          {mode === "create" ? "Create Location Type" : "Save Changes"}
+        </Button>
+      </form>
+    </Form>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationTypesTab.tsx b/apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationTypesTab.tsx
new file mode 100644
index 000000000..0a6cdd11d
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationTypesTab.tsx
@@ -0,0 +1,204 @@
+import { useState } from "react";
+import { ColumnDef } from "@tanstack/react-table";
+import { Pencil, Trash2 } from "lucide-react";
+
+import { useAuth } from "@/auth/useAuth";
+import { isSuperAdmin } from "@/lib/permissions";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/shared/common/ui/alert-dialog";
+import { Button } from "@/shared/common/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@/shared/common/ui/dialog";
+import { AdvancedTable } from "@/shared/common/ui/table/AdvancedTable";
+import { useLocalizedName } from "@/shared/common/localizedName";
+import { usePermissions } from "@/shared/context/PermissionContext";
+import type { LocationType } from "@/user-management/dto/locations/location.type";
+import { useLocationTypes } from "@/user-management/hooks/useLocationTypes";
+import { LocationTypeForm } from "./LocationTypeForm";
+
+const PAGE_SIZE = 10;
+
+export function LocationTypesTab() {
+  const [pageIndex, setPageIndex] = useState(0);
+  const [editing, setEditing] = useState<LocationType | null>(null);
+  const [creating, setCreating] = useState(false);
+  const [deleting, setDeleting] = useState<LocationType | null>(null);
+
+  const localizedName = useLocalizedName();
+  const { permissions } = usePermissions();
+  const { user } = useAuth();
+  const superAdmin = isSuperAdmin(user);
+  const can = (key: string) => superAdmin || permissions.includes(key);
+
+  const {
+    locationTypes,
+    isLoadingLocationTypes,
+    refetchLocationTypes,
+    deleteLocationType,
+    isDeletingLocationType,
+  } = useLocationTypes({
+    skip: pageIndex * PAGE_SIZE,
+    take: PAGE_SIZE,
+    orderBy: "level:ASC",
+  });
+
+  const columns: ColumnDef<LocationType>[] = [
+    {
+      accessorKey: "names",
+      header: () => "Name",
+      cell: ({ row }) => <span>{localizedName(row.original.names)}</span>,
+    },
+    {
+      accessorKey: "code",
+      header: () => "Code",
+      cell: ({ row }) => <span>{row.original.code}</span>,
+    },
+    {
+      accessorKey: "level",
+      header: () => "Level",
+      cell: ({ row }) => <span>{row.original.level}</span>,
+    },
+    {
+      accessorKey: "description",
+      header: () => "Description",
+      cell: ({ row }) => <span>{row.original.description || "--"}</span>,
+    },
+    {
+      id: "actions",
+      header: () => "Actions",
+      cell: ({ row }) => (
+        <div className="flex gap-2">
+          <Button
+            variant="ghost"
+            size="icon"
+            disabled={!can("can:update:location_type")}
+            title={
+              can("can:update:location_type")
+                ? "Edit"
+                : "You cannot edit location types"
+            }
+            onClick={() => setEditing(row.original)}
+          >
+            <Pencil className="h-4 w-4" />
+          </Button>
+          <Button
+            variant="ghost"
+            size="icon"
+            disabled={!can("can:delete:location_type")}
+            title={
+              can("can:delete:location_type")
+                ? "Delete"
+                : "You cannot delete location types"
+            }
+            onClick={() => setDeleting(row.original)}
+          >
+            <Trash2 className="h-4 w-4 text-red-600" />
+          </Button>
+        </div>
+      ),
+    },
+  ];
+
+  return (
+    <div className="space-y-4">
+      <div className="flex justify-end">
+        <Button
+          disabled={!can("can:create:location_type")}
+          title={
+            can("can:create:location_type")
+              ? undefined
+              : "You cannot create location types"
+          }
+          onClick={() => setCreating(true)}
+        >
+          New Location Type
+        </Button>
+      </div>
+
+      <AdvancedTable
+        columns={columns}
+        data={locationTypes?.items ?? []}
+        tableName="Location Types"
+        isLoading={isLoadingLocationTypes}
+        itemCount={locationTypes?.count ?? 0}
+        pageIndex={pageIndex}
+        pageSize={PAGE_SIZE}
+        onPageChange={setPageIndex}
+        nextFunction={() => setPageIndex((page) => page + 1)}
+        prevFunction={() => setPageIndex((page) => Math.max(page - 1, 0))}
+        refresh={refetchLocationTypes}
+      />
+
+      <Dialog
+        open={creating || !!editing}
+        onOpenChange={(open) => {
+          if (!open) {
+            setCreating(false);
+            setEditing(null);
+          }
+        }}
+      >
+        <DialogContent className="max-w-xl">
+          <DialogHeader>
+            <DialogTitle>
+              {editing ? "Edit Location Type" : "New Location Type"}
+            </DialogTitle>
+          </DialogHeader>
+          <LocationTypeForm
+            key={editing?.id ?? "create"}
+            mode={editing ? "edit" : "create"}
+            locationType={editing ?? undefined}
+            onSuccess={() => {
+              setCreating(false);
+              setEditing(null);
+            }}
+          />
+        </DialogContent>
+      </Dialog>
+
+      <AlertDialog
+        open={!!deleting}
+        onOpenChange={(open) => !open && setDeleting(null)}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>
+              Delete {deleting ? localizedName(deleting.names) : ""}?
+            </AlertDialogTitle>
+            <AlertDialogDescription>
+              This is a permanent delete. Locations already using this type will
+              block it at the foreign key.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              disabled={isDeletingLocationType}
+              onClick={() => {
+                if (deleting) {
+                  deleteLocationType(deleting.id, {
+                    onSuccess: () => setDeleting(null),
+                  });
+                }
+              }}
+            >
+              Delete
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </div>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationsTab.tsx b/apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationsTab.tsx
new file mode 100644
index 000000000..d3c63035d
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/user-management/components/location-management/LocationsTab.tsx
@@ -0,0 +1,233 @@
+import { useMemo, useState } from "react";
+import { ColumnDef } from "@tanstack/react-table";
+import { Pencil, Trash2 } from "lucide-react";
+
+import { useAuth } from "@/auth/useAuth";
+import { isSuperAdmin } from "@/lib/permissions";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/shared/common/ui/alert-dialog";
+import { Button } from "@/shared/common/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@/shared/common/ui/dialog";
+import { AdvancedTable } from "@/shared/common/ui/table/AdvancedTable";
+import { useLocalizedName } from "@/shared/common/localizedName";
+import { usePermissions } from "@/shared/context/PermissionContext";
+import type { Location } from "@/user-management/dto/locations/location.type";
+import { useLocations } from "@/user-management/hooks/useLocations";
+import { useLocationTypes } from "@/user-management/hooks/useLocationTypes";
+import { LocationForm } from "./LocationForm";
+
+const PAGE_SIZE = 10;
+/** The API has no filter endpoint, so the parent picker and the type/parent
+ * name columns are resolved from one big list. */
+const LOOKUP_TAKE = 1000;
+
+export function LocationsTab() {
+  const [pageIndex, setPageIndex] = useState(0);
+  const [editing, setEditing] = useState<Location | null>(null);
+  const [creating, setCreating] = useState(false);
+  const [deleting, setDeleting] = useState<Location | null>(null);
+
+  const localizedName = useLocalizedName();
+  const { permissions } = usePermissions();
+  const { user } = useAuth();
+  const superAdmin = isSuperAdmin(user);
+  const can = (key: string) => superAdmin || permissions.includes(key);
+
+  const { locations, isLoadingLocations, refetchLocations, deleteLocation, isDeletingLocation } =
+    useLocations({ skip: pageIndex * PAGE_SIZE, take: PAGE_SIZE });
+  const { locations: allLocations } = useLocations({ take: LOOKUP_TAKE });
+  const { locationTypes } = useLocationTypes({ take: LOOKUP_TAKE });
+
+  const typeName = useMemo(() => {
+    const byId = new Map(
+      (locationTypes?.items ?? []).map((type) => [type.id, type]),
+    );
+    return (id: string) => {
+      const type = byId.get(id);
+      return type ? `${localizedName(type.names)} (L${type.level})` : "--";
+    };
+  }, [locationTypes, localizedName]);
+
+  const parentName = useMemo(() => {
+    const byId = new Map(
+      (allLocations?.items ?? []).map((item) => [item.id, item]),
+    );
+    return (id?: string | null) => {
+      if (!id) return "--";
+      const parent = byId.get(id);
+      return parent ? localizedName(parent.names) : id.slice(0, 8);
+    };
+  }, [allLocations, localizedName]);
+
+  const columns: ColumnDef<Location>[] = [
+    {
+      accessorKey: "names",
+      header: () => "Name",
+      cell: ({ row }) => <span>{localizedName(row.original.names)}</span>,
+    },
+    {
+      accessorKey: "code",
+      header: () => "Code",
+      cell: ({ row }) => <span>{row.original.code}</span>,
+    },
+    {
+      accessorKey: "locationTypeId",
+      header: () => "Type",
+      cell: ({ row }) => <span>{typeName(row.original.locationTypeId)}</span>,
+    },
+    {
+      accessorKey: "parentId",
+      header: () => "Parent",
+      cell: ({ row }) => <span>{parentName(row.original.parentId)}</span>,
+    },
+    {
+      id: "coordinates",
+      header: () => "Coordinates",
+      cell: ({ row }) => {
+        const { latitude, longitude } = row.original;
+        return (
+          <span>{latitude && longitude ? `${latitude}, ${longitude}` : "--"}</span>
+        );
+      },
+    },
+    {
+      id: "actions",
+      header: () => "Actions",
+      cell: ({ row }) => (
+        <div className="flex gap-2">
+          <Button
+            variant="ghost"
+            size="icon"
+            disabled={!can("can:update:location")}
+            title={
+              can("can:update:location") ? "Edit" : "You cannot edit locations"
+            }
+            onClick={() => setEditing(row.original)}
+          >
+            <Pencil className="h-4 w-4" />
+          </Button>
+          <Button
+            variant="ghost"
+            size="icon"
+            disabled={!can("can:delete:location")}
+            title={
+              can("can:delete:location")
+                ? "Delete"
+                : "You cannot delete locations"
+            }
+            onClick={() => setDeleting(row.original)}
+          >
+            <Trash2 className="h-4 w-4 text-red-600" />
+          </Button>
+        </div>
+      ),
+    },
+  ];
+
+  return (
+    <div className="space-y-4">
+      <div className="flex justify-end">
+        <Button
+          disabled={!can("can:create:location")}
+          title={
+            can("can:create:location")
+              ? undefined
+              : "You cannot create locations"
+          }
+          onClick={() => setCreating(true)}
+        >
+          New Location
+        </Button>
+      </div>
+
+      <AdvancedTable
+        columns={columns}
+        data={locations?.items ?? []}
+        tableName="Locations"
+        isLoading={isLoadingLocations}
+        itemCount={locations?.count ?? 0}
+        pageIndex={pageIndex}
+        pageSize={PAGE_SIZE}
+        onPageChange={setPageIndex}
+        nextFunction={() => setPageIndex((page) => page + 1)}
+        prevFunction={() => setPageIndex((page) => Math.max(page - 1, 0))}
+        refresh={refetchLocations}
+      />
+
+      <Dialog
+        open={creating || !!editing}
+        onOpenChange={(open) => {
+          if (!open) {
+            setCreating(false);
+            setEditing(null);
+          }
+        }}
+      >
+        <DialogContent className="max-w-2xl max-h-[90vh] overflow-y-auto">
+          <DialogHeader>
+            <DialogTitle>
+              {editing ? "Edit Location" : "New Location"}
+            </DialogTitle>
+          </DialogHeader>
+          <LocationForm
+            key={editing?.id ?? "create"}
+            mode={editing ? "edit" : "create"}
+            location={editing ?? undefined}
+            locationTypes={locationTypes?.items ?? []}
+            allLocations={allLocations?.items ?? []}
+            onSuccess={() => {
+              setCreating(false);
+              setEditing(null);
+            }}
+          />
+        </DialogContent>
+      </Dialog>
+
+      <AlertDialog
+        open={!!deleting}
+        onOpenChange={(open) => !open && setDeleting(null)}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>
+              Delete {deleting ? localizedName(deleting.names) : ""}?
+            </AlertDialogTitle>
+            <AlertDialogDescription>
+              This is a permanent delete, not an archive. A location that still
+              has child locations or unit clusters attached will be refused by
+              the database.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              disabled={isDeletingLocation}
+              onClick={() => {
+                if (deleting) {
+                  deleteLocation(deleting.id, {
+                    onSuccess: () => setDeleting(null),
+                  });
+                }
+              }}
+            >
+              Delete
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </div>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/user-management/dto/locations/location.type.ts b/apps/edr-freight-web/backoffice/src/user-management/dto/locations/location.type.ts
new file mode 100644
index 000000000..92acbac3a
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/user-management/dto/locations/location.type.ts
@@ -0,0 +1,54 @@
+/**
+ * IAM organisation-structure locations. The API is `@tria-plc/iamapi-common`'s
+ * generic CRUD controller: list returns `{ count, items }` flattened into the
+ * response envelope (`/api/locations` is in `flatResponseModules`), and it
+ * joins nothing — `locationType` and `parent` are NOT expanded, so the UI
+ * resolves both from the type/location lists it already loaded.
+ */
+export interface LocaleName {
+  am: string;
+  en?: string;
+}
+
+export interface LocationType {
+  id: string;
+  code: string;
+  names: LocaleName;
+  description?: string | null;
+  level: number;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface Location {
+  id: string;
+  parentId?: string | null;
+  locationTypeId: string;
+  names: LocaleName;
+  code: string;
+  /** Decimal strings server-side, not numbers. */
+  latitude?: string | null;
+  longitude?: string | null;
+  area?: string | null;
+  boundaryJson?: Record<string, unknown> | null;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface ListResponse<T> {
+  count: number;
+  items: T[];
+}
+
+export interface ListQuery {
+  skip?: number;
+  take?: number;
+  /** `field:ASC` / `field:DESC`, comma separated. No search or filter exists. */
+  orderBy?: string;
+}
+
+export type LocationPayload = Omit<Location, "id" | "createdAt" | "updatedAt">;
+export type LocationTypePayload = Omit<
+  LocationType,
+  "id" | "createdAt" | "updatedAt"
+>;
diff --git a/apps/edr-freight-web/backoffice/src/user-management/hooks/useLocationTypes.ts b/apps/edr-freight-web/backoffice/src/user-management/hooks/useLocationTypes.ts
new file mode 100644
index 000000000..e33f62e40
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/user-management/hooks/useLocationTypes.ts
@@ -0,0 +1,93 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useTranslation } from "react-i18next";
+import { toast } from "sonner";
+
+import { useErrorHandler } from "@/shared/hooks/useErrorHandler";
+import type {
+  ListQuery,
+  ListResponse,
+  LocationType,
+  LocationTypePayload,
+} from "@/user-management/dto/locations/location.type";
+import { locationTypeService } from "../services/api/locationService";
+
+export const useLocationTypes = (params: ListQuery = {}) => {
+  const { t } = useTranslation();
+  const { handleError } = useErrorHandler(t);
+  const queryClient = useQueryClient();
+
+  const invalidate = () =>
+    queryClient.invalidateQueries({ queryKey: ["location-types"] });
+
+  const {
+    data: locationTypes,
+    isLoading: isLoadingLocationTypes,
+    isError: isErrorLocationTypes,
+    refetch: refetchLocationTypes,
+  } = useQuery<ListResponse<LocationType>>({
+    queryKey: ["location-types", params],
+    queryFn: async () => {
+      const { data } = await locationTypeService.list(params);
+      return { count: data?.count ?? 0, items: data?.items ?? [] };
+    },
+    staleTime: 5 * 60 * 1000,
+  });
+
+  const { mutate: createLocationType, isPending: isCreatingLocationType } =
+    useMutation({
+      mutationFn: async (payload: LocationTypePayload) => {
+        const { data } = await locationTypeService.create(payload);
+        return data;
+      },
+      onSuccess: () => {
+        toast.success(t("locationType.created", "Location type created"));
+        invalidate();
+      },
+      onError: handleError,
+    });
+
+  const { mutate: updateLocationType, isPending: isUpdatingLocationType } =
+    useMutation({
+      mutationFn: async ({
+        id,
+        payload,
+      }: {
+        id: string;
+        payload: LocationTypePayload;
+      }) => {
+        const { data } = await locationTypeService.update(id, payload);
+        return data;
+      },
+      onSuccess: () => {
+        toast.success(t("locationType.updated", "Location type updated"));
+        invalidate();
+      },
+      onError: handleError,
+    });
+
+  const { mutate: deleteLocationType, isPending: isDeletingLocationType } =
+    useMutation({
+      mutationFn: async (id: string) => {
+        const { data } = await locationTypeService.remove(id);
+        return data;
+      },
+      onSuccess: () => {
+        toast.success(t("locationType.deleted", "Location type deleted"));
+        invalidate();
+      },
+      onError: handleError,
+    });
+
+  return {
+    locationTypes,
+    isLoadingLocationTypes,
+    isErrorLocationTypes,
+    refetchLocationTypes,
+    createLocationType,
+    isCreatingLocationType,
+    updateLocationType,
+    isUpdatingLocationType,
+    deleteLocationType,
+    isDeletingLocationType,
+  };
+};
diff --git a/apps/edr-freight-web/backoffice/src/user-management/hooks/useLocations.ts b/apps/edr-freight-web/backoffice/src/user-management/hooks/useLocations.ts
new file mode 100644
index 000000000..43e68b567
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/user-management/hooks/useLocations.ts
@@ -0,0 +1,95 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useTranslation } from "react-i18next";
+import { toast } from "sonner";
+
+import { useErrorHandler } from "@/shared/hooks/useErrorHandler";
+import type {
+  ListQuery,
+  ListResponse,
+  Location,
+  LocationPayload,
+} from "@/user-management/dto/locations/location.type";
+import { locationService } from "../services/api/locationService";
+
+/**
+ * `params` is the whole server-side query surface: skip/take/orderBy. There is
+ * no search or filter endpoint, so a caller that needs every location (parent
+ * picker, name lookups) asks for a large `take`.
+ */
+export const useLocations = (params: ListQuery = {}) => {
+  const { t } = useTranslation();
+  const { handleError } = useErrorHandler(t);
+  const queryClient = useQueryClient();
+
+  const invalidate = () =>
+    queryClient.invalidateQueries({ queryKey: ["locations"] });
+
+  const {
+    data: locations,
+    isLoading: isLoadingLocations,
+    isError: isErrorLocations,
+    refetch: refetchLocations,
+  } = useQuery<ListResponse<Location>>({
+    queryKey: ["locations", params],
+    queryFn: async () => {
+      const { data } = await locationService.list(params);
+      return { count: data?.count ?? 0, items: data?.items ?? [] };
+    },
+    staleTime: 5 * 60 * 1000,
+  });
+
+  const { mutate: createLocation, isPending: isCreatingLocation } = useMutation({
+    mutationFn: async (payload: LocationPayload) => {
+      const { data } = await locationService.create(payload);
+      return data;
+    },
+    onSuccess: () => {
+      toast.success(t("location.created", "Location created"));
+      invalidate();
+    },
+    onError: handleError,
+  });
+
+  const { mutate: updateLocation, isPending: isUpdatingLocation } = useMutation({
+    mutationFn: async ({
+      id,
+      payload,
+    }: {
+      id: string;
+      payload: LocationPayload;
+    }) => {
+      const { data } = await locationService.update(id, payload);
+      return data;
+    },
+    onSuccess: () => {
+      toast.success(t("location.updated", "Location updated"));
+      invalidate();
+    },
+    onError: handleError,
+  });
+
+  const { mutate: deleteLocation, isPending: isDeletingLocation } = useMutation({
+    mutationFn: async (id: string) => {
+      const { data } = await locationService.remove(id);
+      return data;
+    },
+    onSuccess: () => {
+      toast.success(t("location.deleted", "Location deleted"));
+      invalidate();
+    },
+    onError: handleError,
+  });
+
+  return {
+    locations,
+    isLoadingLocations,
+    isErrorLocations,
+    refetchLocations,
+    createLocation,
+    isCreatingLocation,
+    updateLocation,
+    isUpdatingLocation,
+    deleteLocation,
+    isDeletingLocation,
+  };
+};
diff --git a/apps/edr-freight-web/backoffice/src/user-management/pages/location-management/index.tsx b/apps/edr-freight-web/backoffice/src/user-management/pages/location-management/index.tsx
new file mode 100644
index 000000000..b8ac18350
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/user-management/pages/location-management/index.tsx
@@ -0,0 +1,35 @@
+import {
+  Tabs,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+} from "@/shared/common/ui/tabs";
+import { LocationsTab } from "@/user-management/components/location-management/LocationsTab";
+import { LocationTypesTab } from "@/user-management/components/location-management/LocationTypesTab";
+
+export default function LocationManagementPage() {
+  return (
+    <div className="w-full space-y-6 p-6">
+      <div>
+        <h1 className="text-2xl font-semibold">Location Management</h1>
+        <p className="text-sm text-muted-foreground">
+          Locations and their hierarchy levels, shared across the IAM
+          organisation structure.
+        </p>
+      </div>
+
+      <Tabs defaultValue="locations">
+        <TabsList>
+          <TabsTrigger value="locations">Locations</TabsTrigger>
+          <TabsTrigger value="types">Location Types</TabsTrigger>
+        </TabsList>
+        <TabsContent value="locations" className="pt-4">
+          <LocationsTab />
+        </TabsContent>
+        <TabsContent value="types" className="pt-4">
+          <LocationTypesTab />
+        </TabsContent>
+      </Tabs>
+    </div>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/user-management/route.tsx b/apps/edr-freight-web/backoffice/src/user-management/route.tsx
index a336b3f9f..93e414c50 100644
--- a/apps/edr-freight-web/backoffice/src/user-management/route.tsx
+++ b/apps/edr-freight-web/backoffice/src/user-management/route.tsx
@@ -10,6 +10,7 @@ import TemplatePage from "@/super-admin/components/templates/components/template
 import CreatePositionPage from "./pages/position-management/create";
 import EditPositionPage from "./pages/position-management/edit";
 import PositionManagementPage from "./pages/position-management";
+import LocationManagementPage from "./pages/location-management";
 import MigratedDataManagementPage from "./pages/position-management/MigratedDataManagementPage";
 import UserPositionApprovalPage from "./pages/UserPositionApprovalPage";
 import ViewMigratedDataPage from "./components/MigratedRecords/ViewMigratedDataPage";
@@ -140,6 +141,10 @@ export function UserManagementRoutes(): ReactElement {
                           path="user-management/position-management"
                           element={<PositionManagementPage />}
                         />
+                        <Route
+                          path="user-management/locations"
+                          element={<LocationManagementPage />}
+                        />
                         {/*
                           The per-officer teeter (ማህተም) + signature upload. This
                           is NOT the company stamp: it is the individual approval
diff --git a/apps/edr-freight-web/backoffice/src/user-management/services/api/locationService.ts b/apps/edr-freight-web/backoffice/src/user-management/services/api/locationService.ts
new file mode 100644
index 000000000..56d2596ba
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/user-management/services/api/locationService.ts
@@ -0,0 +1,55 @@
+import { withHeaders } from "@/record-management/services/api/withHeaders";
+import axiosInstance from "@/shared/services/axiosInstance";
+import type {
+  ListQuery,
+  ListResponse,
+  Location,
+  LocationPayload,
+  LocationType,
+  LocationTypePayload,
+} from "@/user-management/dto/locations/location.type";
+import { AxiosResponse } from "axios";
+
+export const locationService = {
+  list: (
+    params: ListQuery = {},
+  ): Promise<AxiosResponse<ListResponse<Location>>> =>
+    axiosInstance.get(`/locations`, { params, headers: withHeaders() }),
+
+  create: (payload: LocationPayload): Promise<AxiosResponse<Location>> =>
+    axiosInstance.post(`/locations`, payload, { headers: withHeaders() }),
+
+  update: (
+    id: string,
+    payload: LocationPayload,
+  ): Promise<AxiosResponse<Location>> =>
+    axiosInstance.put(`/locations/${id}`, payload, { headers: withHeaders() }),
+
+  // Hard delete server-side — a location with children or unit clusters fails
+  // on the foreign key rather than returning a tidy 409.
+  remove: (id: string): Promise<AxiosResponse<void>> =>
+    axiosInstance.delete(`/locations/${id}`, { headers: withHeaders() }),
+};
+
+export const locationTypeService = {
+  list: (
+    params: ListQuery = {},
+  ): Promise<AxiosResponse<ListResponse<LocationType>>> =>
+    axiosInstance.get(`/location-types`, { params, headers: withHeaders() }),
+
+  create: (
+    payload: LocationTypePayload,
+  ): Promise<AxiosResponse<LocationType>> =>
+    axiosInstance.post(`/location-types`, payload, { headers: withHeaders() }),
+
+  update: (
+    id: string,
+    payload: LocationTypePayload,
+  ): Promise<AxiosResponse<LocationType>> =>
+    axiosInstance.put(`/location-types/${id}`, payload, {
+      headers: withHeaders(),
+    }),
+
+  remove: (id: string): Promise<AxiosResponse<void>> =>
+    axiosInstance.delete(`/location-types/${id}`, { headers: withHeaders() }),
+};

From dd6df306f28f6b5f549681786ab082e79d03fca0 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Tue, 18 Aug 2026 13:11:09 +0000
Subject: [PATCH 159/174] lifecycle

---
 ...booking-lifecycle-notifier.service.spec.ts | 40 ++++++++++++++++---
 .../booking-lifecycle-notifier.service.ts     | 21 ++++++----
 .../bookings/DocumentClearanceDetailPage.tsx  | 31 ++++++++++++++
 3 files changed, 79 insertions(+), 13 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.spec.ts b/apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.spec.ts
index 9a5960295..c9bdc4845 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.spec.ts
@@ -36,9 +36,13 @@ describe('BookingLifecycleNotifierService — operation changes requested', () =
     );
   });
 
-  it('sends a GL-created booking back to the GL who created it, not the customer', async () => {
+  it('sends a GL-created customs booking back to the GL who created it, not the customer', async () => {
     service.operationChangesRequested(
-      booking({ createdByRole: 'GL_ET', createdByUserId: 'gl-user-1' }),
+      booking({
+        customsClearingEnabled: true,
+        createdByRole: 'GL_ET',
+        createdByUserId: 'gl-user-1',
+      }),
       'Cargo weight does not match the declaration',
     );
     await flush();
@@ -54,7 +58,7 @@ describe('BookingLifecycleNotifierService — operation changes requested', () =
     expect(notifications.directSend).not.toHaveBeenCalled();
   });
 
-  it('still tells the customer when the booking is their own', async () => {
+  it('still tells the customer when the booking is a non-customs self-service booking', async () => {
     service.operationChangesRequested(booking(), 'Please attach the packing list');
     await flush();
 
@@ -65,14 +69,38 @@ describe('BookingLifecycleNotifierService — operation changes requested', () =
     expect(notifications.directSend).toHaveBeenCalled();
   });
 
-  it('falls back to the customer when the GL creator is unknown (legacy rows)', async () => {
+  it('routes a customer-opened customs booking to the clearance desk, not the customer', async () => {
+    // Path B lets the customer open the ONE_TIME shipment instance themselves
+    // (contract-booking.service assertGate's customerMayInitiate) — createdByRole
+    // stays 'CUSTOMER', but GL still owns completing/resubmitting it.
     service.operationChangesRequested(
-      booking({ createdByRole: 'GL_ET', createdByUserId: null }),
+      booking({ customsClearingEnabled: true, createdByRole: 'CUSTOMER' }),
       'Fix the declaration',
     );
     await flush();
 
-    expect(inbox.notify.mock.calls[0][0].recipients).toEqual({ companyId: 'co-1' });
+    const sent = inbox.notify.mock.calls[0][0];
+    expect(sent.recipients).toEqual({
+      permissionKeys: [FREIGHT_PERMS.bookings.clearanceGetNotification],
+    });
+    expect(sent.audience).toBe('BACKOFFICE');
+    expect(notifications.directSend).not.toHaveBeenCalled();
+  });
+
+  it('falls back to the clearance desk when the GL creator is unknown (legacy rows)', async () => {
+    service.operationChangesRequested(
+      booking({
+        customsClearingEnabled: true,
+        createdByRole: 'GL_ET',
+        createdByUserId: null,
+      }),
+      'Fix the declaration',
+    );
+    await flush();
+
+    expect(inbox.notify.mock.calls[0][0].recipients).toEqual({
+      permissionKeys: [FREIGHT_PERMS.bookings.clearanceGetNotification],
+    });
   });
 });
 
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 01f0fd053..030f1115f 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
@@ -247,20 +247,27 @@ export class BookingLifecycleNotifierService {
   /**
    * Operations returned the operation request for changes.
    *
-   * A customs (Path B) booking was created BY GL Ethiopia on the customer's
-   * behalf — the customer cannot edit or resubmit it, so telling them to "update
-   * from the portal" is a dead end. Those go to the GL who created it, linking
-   * the contract clearance page they work from. Everything else (customer-made
-   * bookings) keeps the portal message.
+   * A customs (Path B) booking is completed by GL Ethiopia on the customer's
+   * behalf regardless of who opened the shipment instance — the customer-opened
+   * ONE_TIME case (see contract-booking.service assertGate) still stamps
+   * createdByRole 'CUSTOMER', so gate on customsClearingEnabled, not on who
+   * created it. The customer cannot edit or resubmit a customs booking, so
+   * telling them to "update from the portal" is a dead end. Those go to the GL
+   * who created it when known, else the clearance desk, linking the contract
+   * clearance page they work from. Everything else (customer-made bookings)
+   * keeps the portal message.
    */
   operationChangesRequested(b: Booking, note: string): void {
-    if (b.createdByRole === 'GL_ET' && b.createdByUserId) {
+    if (b.customsClearingEnabled) {
       const msg =
         `Operations returned booking ${b.reference} for changes: ${note}. ` +
         `Address it on the contract clearance page and resubmit to Operations.`;
       this.logger.log(`OPERATION CHANGES REQUESTED (to GL) — ${this.ref(b)}`);
       void this.inbox.notify({
-        recipients: { userIds: [b.createdByUserId] },
+        recipients:
+          b.createdByRole === 'GL_ET' && b.createdByUserId
+            ? { userIds: [b.createdByUserId] }
+            : CLEARANCE_DESK,
         audience: NotificationAudience.BACKOFFICE,
         type: NotificationType.BOOKING_STATUS,
         title: `Booking ${b.reference} needs changes`,
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
index 48ce552a8..39a0e9d77 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/DocumentClearanceDetailPage.tsx
@@ -27,6 +27,7 @@ import {
 import type { Freight } from "@edr/types";
 
 import { ClearanceOpsTabs } from "@/components/contracts/ClearanceOpsTabs";
+import { BookingChangesRequestedAlert } from "@/components/contracts/BookingChangesRequestedAlert";
 import { PageContainer, PageHeader, KpiStrip } from "@/components/page";
 import type { KpiItem } from "@/components/page";
 import {
@@ -134,6 +135,20 @@ export default function DocumentClearanceDetailPage() {
     hasPermission(user, FREIGHT_PERMS.contracts.createBooking) &&
     !isDjiboutiGl(user);
 
+  // Operations sent this GL-created booking back for changes. Customs bookings
+  // are never self-booked (see BookingChangesRequestedAlert) — the note and the
+  // resubmit belong here, on the page GL works from, not the customer's portal.
+  const bookingNeedsChanges = booking?.status === "OPERATION_CHANGES_REQUESTED";
+  const isGlBookingOwner =
+    hasPermission(user, FREIGHT_PERMS.contracts.createBooking) &&
+    !isDjiboutiGl(user);
+  const changeRequestNote =
+    [...(booking?.reviewNotes ?? [])]
+      .filter((n) => n.type === "CHANGES_REQUESTED")
+      .sort(
+        (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
+      )[0]?.note ?? null;
+
   const docsPhaseComplete =
     clearance?.milestones?.some(
       (m) => m.milestoneCode === "DOCUMENTS_APPROVED" && m.status === "COMPLETED",
@@ -279,6 +294,22 @@ export default function DocumentClearanceDetailPage() {
           }
         />
 
+        {bookingNeedsChanges ? (
+          <BookingChangesRequestedAlert
+            bookingId={id!}
+            reference={booking?.reference}
+            note={changeRequestNote}
+            scheduledDate={booking?.scheduledDate}
+            canResubmit={isGlBookingOwner}
+            editHref={
+              booking?.contractId
+                ? `/dashboard/contracts/${booking.contractId}/bookings/${id}/complete?copyFrom=${id}`
+                : undefined
+            }
+            onResubmitted={() => void refetch()}
+          />
+        ) : null}
+
         <KpiStrip items={kpis} />
 
         {requestedLines ? (

From 40904049cf781016e1b6d9a671ae8aff7e0c72fd Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Tue, 18 Aug 2026 13:17:55 +0000
Subject: [PATCH 160/174] feat: implement consolidation approval process for
 shared-wagon bookings

- Add migration for consolidation approvals table and status enum
- Create ConsolidationApprovalService to handle approval logic
- Implement repository for managing consolidation approvals
- Add entity for consolidation approval with necessary fields
- Develop frontend components for displaying and managing consolidation approvals
- Create tests for consolidation approval service to ensure correct behavior
---
 .../3570000000000-ConsolidationApprovals.ts   |  89 ++++++
 .../booking-lifecycle-notifier.service.ts     |  30 ++
 .../modules/bookings/bookings.controller.ts   |  65 ++++
 .../src/modules/bookings/bookings.module.ts   |   8 +
 .../consolidation-approval.service.spec.ts    | 202 +++++++++++++
 .../consolidation-approval.service.ts         | 255 ++++++++++++++++
 .../consolidation-approvals.repository.ts     | 120 ++++++++
 .../bookings/dto/request-changes.dto.ts       |  23 ++
 .../bookings/entities/booking.entity.ts       |   4 +
 .../entities/consolidation-approval.entity.ts |  98 ++++++
 .../contract-booking.completion.spec.ts       |   2 +
 .../contract-booking.consolidation.spec.ts    |   1 +
 .../contract-booking.initiate-gate.spec.ts    |   1 +
 ...tract-booking.manual-consolidation.spec.ts |   3 +
 .../contract-booking.resubmit-cargo.spec.ts   |   1 +
 .../contracts/contract-booking.service.ts     |  15 +
 .../contracts/contract-clearance.service.ts   |  53 ++--
 .../modules/contracts/contracts.controller.ts |   3 +
 .../modules/contracts/contracts.repository.ts |  25 ++
 .../src/seed/freight-permissions.registry.ts  |  25 ++
 apps/edr-freight-web/backoffice/src/App.tsx   |  13 +
 .../detail/ConsolidationApprovalCard.tsx      |  82 +++++
 .../trainBuilder/AvailableWagonsPanel.tsx     | 199 +++++++-----
 .../trainBuilder/ConsistWagonList.tsx         |  36 ++-
 .../TrainCompositionDiagram.tsx               |  14 +-
 .../backoffice/src/constants/URLS.ts          |   9 +
 .../bookings/booking-status.config.ts         |   8 +
 .../backoffice/src/lib/permissions.ts         |   1 +
 .../backoffice/src/lib/queryClient.test.ts    |  58 ++++
 .../backoffice/src/lib/queryClient.ts         |  28 +-
 .../bookings/BookingRequestDetailPage.tsx     |  19 ++
 .../bookings/ConsolidationApprovalsPage.tsx   | 284 ++++++++++++++++++
 .../trainBuilder/TrainBuilderDetailPage.tsx   | 146 ++++++---
 .../backoffice/src/services/api.ts            |  43 ++-
 .../src/services/bookings.service.ts          |  63 ++++
 .../backoffice/src/utils/endpoint.ts          |  56 +++-
 36 files changed, 1898 insertions(+), 184 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3570000000000-ConsolidationApprovals.ts
 create mode 100644 apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/bookings/consolidation-approvals.repository.ts
 create mode 100644 apps/edr-freight-api/src/modules/bookings/entities/consolidation-approval.entity.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/bookings/detail/ConsolidationApprovalCard.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/lib/queryClient.test.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/bookings/ConsolidationApprovalsPage.tsx

diff --git a/apps/edr-freight-api/src/migrations/3570000000000-ConsolidationApprovals.ts b/apps/edr-freight-api/src/migrations/3570000000000-ConsolidationApprovals.ts
new file mode 100644
index 000000000..879c9b472
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3570000000000-ConsolidationApprovals.ts
@@ -0,0 +1,89 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Approval gate for consolidated (shared-wagon) bookings.
+ *
+ * A booking that fills its own wagons goes straight from GL completion to the
+ * operations queue. A CONSOLIDATED booking does not: it shares one physical
+ * wagon with another customer's booking, which means two customers' cargo, two
+ * invoices and two liabilities riding the same wagon. That pairing is a
+ * commercial decision, so it is reviewed by a person before Operations sees it.
+ *
+ * The pair is approved as a UNIT — one row covers both halves (booking_id +
+ * partner_booking_id) so an approver can never approve one side of a shared
+ * wagon and leave the other pending. Rows are never deleted; decided rows are
+ * the audit trail of who approved which pairing and when.
+ *
+ * One PENDING row per booking at a time (partial unique index on each side of
+ * the pair): a second request while one is undecided is a coordination failure,
+ * not a workflow.
+ */
+export class ConsolidationApprovals3570000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      DO $$ BEGIN
+        CREATE TYPE freight.consolidation_approvals_status_enum
+          AS ENUM ('PENDING', 'APPROVED', 'REJECTED');
+      EXCEPTION WHEN duplicate_object THEN NULL; END $$
+    `);
+
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.consolidation_approvals (
+        id uuid PRIMARY KEY DEFAULT uuid_generate_v4(),
+        booking_id uuid NOT NULL REFERENCES freight.bookings (id),
+        partner_booking_id uuid NOT NULL REFERENCES freight.bookings (id),
+        status freight.consolidation_approvals_status_enum NOT NULL DEFAULT 'PENDING',
+        -- Who put the pairing up for review (the GL user who completed it) and
+        -- who decided it. Both are recorded: the point of the gate is that they
+        -- are different people.
+        requested_by uuid,
+        requested_at timestamptz NOT NULL DEFAULT now(),
+        decided_by uuid,
+        decided_at timestamptz,
+        decision_note varchar(500),
+        -- Snapshot of what was approved, so the audit trail still reads
+        -- correctly after the bookings themselves move on.
+        scheduled_date timestamptz,
+        booking_reference varchar(50),
+        partner_booking_reference varchar(50),
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz
+      )
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_consolidation_approvals_booking_status
+        ON freight.consolidation_approvals (booking_id, status)
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_consolidation_approvals_status
+        ON freight.consolidation_approvals (status)
+    `);
+
+    // The workflow invariant, enforced where it cannot race: at most one
+    // undecided request per booking — on EITHER side of the pair, so the same
+    // wagon can never collect two pending requests from its two halves.
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS uq_consolidation_approvals_one_pending
+        ON freight.consolidation_approvals (booking_id)
+        WHERE status = 'PENDING' AND deleted_at IS NULL
+    `);
+
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS uq_consolidation_approvals_one_pending_partner
+        ON freight.consolidation_approvals (partner_booking_id)
+        WHERE status = 'PENDING' AND deleted_at IS NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DROP TABLE IF EXISTS freight.consolidation_approvals`,
+    );
+    await queryRunner.query(
+      `DROP TYPE IF EXISTS freight.consolidation_approvals_status_enum`,
+    );
+  }
+}
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 01f0fd053..7755a870b 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
@@ -463,6 +463,36 @@ export class BookingLifecycleNotifierService {
     );
   }
 
+  /**
+   * A shared-wagon pairing is waiting for a human decision. Two customers' cargo
+   * on one wagon is a commercial call, so this never auto-advances.
+   */
+  consolidationApprovalRequestedToStaff(b: Booking, partnerReference: string): void {
+    this.inAppStaff(
+      b,
+      'Shared wagon needs approval',
+      `Booking ${this.ref(b)} shares a wagon with ${partnerReference} — approve the consolidation before it reaches Operations.`,
+    );
+  }
+
+  /** The pairing was approved; both halves move on to Operations together. */
+  consolidationApprovedToStaff(b: Booking, partnerReference: string): void {
+    this.inAppStaff(
+      b,
+      'Shared wagon approved',
+      `The shared wagon for ${this.ref(b)} and ${partnerReference} was approved — both bookings are now with Operations.`,
+    );
+  }
+
+  /** The pairing was rejected; both halves go back to GL for changes. */
+  consolidationRejectedToStaff(b: Booking, partnerReference: string, reason: string): void {
+    this.inAppStaff(
+      b,
+      'Shared wagon rejected',
+      `The shared wagon for ${this.ref(b)} and ${partnerReference} was rejected: ${reason}`,
+    );
+  }
+
   /** Customer uploaded clearance documents — review is next. */
   clearanceDocsUploadedToStaff(b: Booking): void {
     this.inAppStaff(
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts b/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
index c2d6465c2..67a0f930d 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
@@ -50,6 +50,7 @@ import { BookingReferenceDataService } from './booking-reference-data.service';
 import { scopedDirections } from '../user-trade-access/trade-scope.util';
 import { UserTradeAccessService } from '../user-trade-access/user-trade-access.service';
 import { BookingsService } from './bookings.service';
+import { ConsolidationApprovalService } from './consolidation-approval.service';
 import { BookingReferenceDataDto } from './dto/booking-reference-data.dto';
 import { CreateBookingDto } from './dto/create-booking.dto';
 import { BookingListSummaryDto } from './dto/booking-list-summary.dto';
@@ -58,8 +59,10 @@ import { GeneratePriceResponseDto } from './dto/generate-price-response.dto';
 import { SubmitBookingResponseDto } from './dto/submit-booking-response.dto';
 import {
   AcceptIntakeDto,
+  ApproveConsolidationDto,
   CancelBookingDto,
   PairedDecisionDto,
+  RejectConsolidationDto,
   RejectBookingDto,
   RequestChangesDto,
   ReviewDocumentDto,
@@ -166,6 +169,7 @@ export class BookingsController {
     private readonly lastMileService: LastMileService,
     private readonly userTradeAccessService: UserTradeAccessService,
     private readonly wagonCancellationService: BookingWagonCancellationService,
+    private readonly consolidationApprovalService: ConsolidationApprovalService,
   ) {}
 
   @Post()
@@ -1542,6 +1546,67 @@ export class BookingsController {
     return this.transitionService.enrichBookingResponse(booking);
   }
 
+  // ── Shared-wagon (consolidation) approval gate ────────────────────────────
+  // A consolidated pair is held here, not in the operations queue: two
+  // customers' cargo on one wagon is a commercial call, so a person signs off
+  // on the pairing before Operations sees either half.
+
+  @Get("consolidation-approvals/queue")
+  @BookingStaff(FREIGHT_PERMS.bookings.approveConsolidation)
+  @ApiOperation({
+    summary:
+      "Shared-wagon pairings awaiting approval, oldest first. Each row covers BOTH bookings on the wagon.",
+  })
+  consolidationApprovalQueue() {
+    return this.consolidationApprovalService.queue();
+  }
+
+  @Get(":id/consolidation-approvals")
+  @BookingStaff(FREIGHT_PERMS.bookings.view)
+  @ApiOperation({
+    summary:
+      "Approval history for this booking's shared wagon — who decided what, when, and why.",
+  })
+  consolidationApprovalHistory(@Param("id", ParseUUIDPipe) id: string) {
+    return this.consolidationApprovalService.historyForBooking(id);
+  }
+
+  @Post("consolidation-approvals/:approvalId/approve")
+  @BookingStaff(FREIGHT_PERMS.bookings.approveConsolidation)
+  @ApiOperation({
+    summary:
+      "Approve a shared wagon: both bookings leave the gate and continue to Operations together.",
+  })
+  approveConsolidation(
+    @Param("approvalId", ParseUUIDPipe) approvalId: string,
+    @Body() dto: ApproveConsolidationDto,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    return this.consolidationApprovalService.approve(
+      approvalId,
+      resolveAuthUserId(user) ?? "",
+      dto.note,
+    );
+  }
+
+  @Post("consolidation-approvals/:approvalId/reject")
+  @BookingStaff(FREIGHT_PERMS.bookings.approveConsolidation)
+  @ApiOperation({
+    summary:
+      "Reject a shared wagon: both bookings go back to GL for changes with the reason.",
+  })
+  rejectConsolidation(
+    @Param("approvalId", ParseUUIDPipe) approvalId: string,
+    @Body() dto: RejectConsolidationDto,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    return this.consolidationApprovalService.reject(
+      approvalId,
+      resolveAuthUserId(user) ?? "",
+      dto.reason,
+    );
+  }
+
   @Post(":id/paired-decision")
   @BookingStaff(FREIGHT_PERMS.bookings.cancel)
   @ApiOperation({
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
index 447292117..b3ea4a546 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
@@ -30,6 +30,9 @@ import { BookingsController } from './bookings.controller';
 // import { PayController } from './pay.controller';
 import { BookingsRepository } from './bookings.repository';
 import { ConsolidationService } from './consolidation.service';
+import { ConsolidationApprovalService } from './consolidation-approval.service';
+import { ConsolidationApprovalsRepository } from './consolidation-approvals.repository';
+import { ConsolidationApproval } from './entities/consolidation-approval.entity';
 import { ContainerValidationService } from './container-validation.service';
 import { BookingsService } from './bookings.service';
 import { BookingCargoModifier } from './entities/booking-cargo-modifier.entity';
@@ -72,6 +75,7 @@ import { VehiclesModule } from "../vehicles/vehicles.module";
       BookingWagonCancellation,
       CustomerTruckAssignment,
       CustomerTruckContainer,
+      ConsolidationApproval,
     ]),
     BillingModule,
     DocumentsModule,
@@ -98,6 +102,8 @@ import { VehiclesModule } from "../vehicles/vehicles.module";
     BookingsService,
     BookingsRepository,
     ConsolidationService,
+    ConsolidationApprovalService,
+    ConsolidationApprovalsRepository,
     ContainerValidationService,
     BookingReferenceDataService,
     BookingPricingService,
@@ -126,6 +132,8 @@ import { VehiclesModule } from "../vehicles/vehicles.module";
     BookingLifecycleNotifierService,
     BookingTransitionService,
     ConsolidationService,
+    ConsolidationApprovalService,
+    ConsolidationApprovalsRepository,
     CustomerTruckService,
     ContainerReceiptService,
     BookingWagonCancellationService,
diff --git a/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.spec.ts b/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.spec.ts
new file mode 100644
index 000000000..d418fbd3c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.spec.ts
@@ -0,0 +1,202 @@
+import {
+  ConsolidationApprovalService,
+  CONSOLIDATION_APPROVAL_PENDING,
+} from './consolidation-approval.service';
+import { ConsolidationApprovalStatus } from './entities/consolidation-approval.entity';
+import { Booking } from './entities/booking.entity';
+
+/**
+ * The shared-wagon approval gate. Two customers' cargo on one wagon is a
+ * commercial call, so the pair is held for a human decision instead of going
+ * straight to Operations.
+ *
+ * The invariants that matter: both halves are held and released TOGETHER (a
+ * decision on one side of a shared wagon is meaningless without the other), the
+ * requester cannot approve their own pairing, and a decided pairing cannot be
+ * decided twice.
+ */
+describe('ConsolidationApprovalService', () => {
+  const PENDING = {
+    id: 'ap-1',
+    bookingId: 'b-1',
+    partnerBookingId: 'b-2',
+    status: ConsolidationApprovalStatus.Pending,
+    requestedBy: 'gl-user',
+  };
+
+  function makeService(overrides: {
+    approvals?: Partial<Record<string, jest.Mock>>;
+    bookingsRepository?: Partial<Record<string, jest.Mock>>;
+  } = {}) {
+    const approvals = {
+      findPendingForBooking: jest.fn().mockResolvedValue(null),
+      findById: jest.fn().mockResolvedValue(PENDING),
+      create: jest.fn().mockResolvedValue({ id: 'ap-1' }),
+      decide: jest.fn().mockResolvedValue(true),
+      findQueue: jest.fn().mockResolvedValue([]),
+      findAllForBooking: jest.fn().mockResolvedValue([]),
+      ...overrides.approvals,
+    };
+    const bookingsRepository = {
+      update: jest.fn().mockResolvedValue(undefined),
+      createReviewNote: jest.fn().mockResolvedValue(undefined),
+      ...overrides.bookingsRepository,
+    };
+    const bookingsService = {
+      findById: jest.fn(async (id: string) =>
+        ({ id, reference: `BK-${id}` }) as Booking,
+      ),
+    };
+    const notifier = {
+      consolidationApprovalRequestedToStaff: jest.fn(),
+      consolidationApprovedToStaff: jest.fn(),
+      consolidationRejectedToStaff: jest.fn(),
+      operationRequestedToStaff: jest.fn(),
+    };
+    const dataSource = {
+      transaction: jest.fn(async (cb: () => Promise<unknown>) => cb()),
+    };
+
+    const service = new ConsolidationApprovalService(
+      approvals as never,
+      bookingsRepository as never,
+      bookingsService as never,
+      notifier as never,
+      dataSource as never,
+    );
+    return { service, approvals, bookingsRepository, notifier };
+  }
+
+  it('holds BOTH halves at the gate when a pairing is created', async () => {
+    const { service, approvals, bookingsRepository, notifier } = makeService();
+
+    await service.requestApproval('b-1', 'b-2', 'gl-user');
+
+    expect(approvals.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        bookingId: 'b-1',
+        partnerBookingId: 'b-2',
+        requestedBy: 'gl-user',
+      }),
+    );
+    // Neither half may sit in the operations queue while the wagon is unreviewed.
+    expect(bookingsRepository.update).toHaveBeenCalledWith('b-1', {
+      status: CONSOLIDATION_APPROVAL_PENDING,
+    });
+    expect(bookingsRepository.update).toHaveBeenCalledWith('b-2', {
+      status: CONSOLIDATION_APPROVAL_PENDING,
+    });
+    expect(
+      notifier.consolidationApprovalRequestedToStaff,
+    ).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not open a second review for a pairing already pending', async () => {
+    const { service, approvals } = makeService({
+      approvals: {
+        findPendingForBooking: jest.fn().mockResolvedValue(PENDING),
+      },
+    });
+
+    const result = await service.requestApproval('b-1', 'b-2', 'gl-user');
+
+    expect(result).toBe(PENDING);
+    expect(approvals.create).not.toHaveBeenCalled();
+  });
+
+  it('releases BOTH halves to Operations on approval, logging who decided', async () => {
+    const { service, approvals, bookingsRepository, notifier } = makeService();
+
+    await service.approve('ap-1', 'approver-1', 'looks fine');
+
+    expect(approvals.decide).toHaveBeenCalledWith(
+      'ap-1',
+      ConsolidationApprovalStatus.Approved,
+      'approver-1',
+      'looks fine',
+    );
+    expect(bookingsRepository.update).toHaveBeenCalledWith('b-1', {
+      status: 'OPERATION_REQUEST_PENDING',
+    });
+    expect(bookingsRepository.update).toHaveBeenCalledWith('b-2', {
+      status: 'OPERATION_REQUEST_PENDING',
+    });
+    // Operations only learns about the pair now — the gate is what kept it out.
+    expect(notifier.operationRequestedToStaff).toHaveBeenCalledTimes(2);
+  });
+
+  it('sends BOTH halves back to GL on rejection, with the reason on each', async () => {
+    const { service, approvals, bookingsRepository } = makeService();
+
+    await service.reject('ap-1', 'approver-1', 'partner cargo is wrong');
+
+    expect(approvals.decide).toHaveBeenCalledWith(
+      'ap-1',
+      ConsolidationApprovalStatus.Rejected,
+      'approver-1',
+      'partner cargo is wrong',
+    );
+    expect(bookingsRepository.createReviewNote).toHaveBeenCalledWith(
+      'b-1',
+      'partner cargo is wrong',
+      'CHANGES_REQUESTED',
+    );
+    expect(bookingsRepository.createReviewNote).toHaveBeenCalledWith(
+      'b-2',
+      'partner cargo is wrong',
+      'CHANGES_REQUESTED',
+    );
+    expect(bookingsRepository.update).toHaveBeenCalledWith('b-1', {
+      status: 'OPERATION_CHANGES_REQUESTED',
+    });
+    expect(bookingsRepository.update).toHaveBeenCalledWith('b-2', {
+      status: 'OPERATION_CHANGES_REQUESTED',
+    });
+  });
+
+  it('refuses to let the requester approve their own pairing', async () => {
+    const { service, bookingsRepository } = makeService();
+
+    await expect(
+      service.approve('ap-1', 'gl-user'),
+    ).rejects.toThrow(/must be approved by someone else/i);
+    expect(bookingsRepository.update).not.toHaveBeenCalled();
+  });
+
+  it('requires a reason to reject', async () => {
+    const { service, approvals } = makeService();
+
+    await expect(service.reject('ap-1', 'approver-1', '   ')).rejects.toThrow(
+      /reason is required/i,
+    );
+    expect(approvals.decide).not.toHaveBeenCalled();
+  });
+
+  it('refuses a pairing that was already decided', async () => {
+    const { service, bookingsRepository } = makeService({
+      approvals: {
+        findById: jest.fn().mockResolvedValue({
+          ...PENDING,
+          status: ConsolidationApprovalStatus.Approved,
+        }),
+      },
+    });
+
+    await expect(service.approve('ap-1', 'approver-1')).rejects.toThrow(
+      /already approved/i,
+    );
+    expect(bookingsRepository.update).not.toHaveBeenCalled();
+  });
+
+  it('loses cleanly when another approver decides the same pairing first', async () => {
+    // decide() writes only against a still-PENDING row, so the loser of the race
+    // affects nothing and must not move the bookings.
+    const { service } = makeService({
+      approvals: { decide: jest.fn().mockResolvedValue(false) },
+    });
+
+    await expect(service.approve('ap-1', 'approver-1')).rejects.toThrow(
+      /already decided by someone else/i,
+    );
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.ts b/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.ts
new file mode 100644
index 000000000..ed8bdfe7a
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.ts
@@ -0,0 +1,255 @@
+import {
+  BadRequestException,
+  ConflictException,
+  Inject,
+  Injectable,
+  Logger,
+  NotFoundException,
+  forwardRef,
+} from "@nestjs/common";
+import { DataSource } from "typeorm";
+
+import { Booking } from "./entities/booking.entity";
+import {
+  ConsolidationApproval,
+  ConsolidationApprovalStatus,
+} from "./entities/consolidation-approval.entity";
+import { ConsolidationApprovalsRepository } from "./consolidation-approvals.repository";
+import { BookingsRepository } from "./bookings.repository";
+import { BookingsService } from "./bookings.service";
+import { BookingLifecycleNotifierService } from "./booking-lifecycle-notifier.service";
+
+/** Where a rejected pair goes back to, so GL can fix and resubmit. */
+const REJECTED_STATUS = "OPERATION_CHANGES_REQUESTED";
+
+/** The gate's own holding status — neither half reaches Operations from here. */
+export const CONSOLIDATION_APPROVAL_PENDING = "CONSOLIDATION_APPROVAL_PENDING";
+
+/**
+ * The shared-wagon approval gate.
+ *
+ * A booking that fills its own wagons goes straight from GL completion to the
+ * operations queue. A consolidated one does not: two customers' cargo rides one
+ * physical wagon under two separate invoices, so a person reviews the pairing
+ * before Operations sees either half.
+ *
+ * Both halves are held and released TOGETHER — the wagon is shared, so a
+ * decision on one is meaningless without the other. Every request is kept,
+ * decided or not: the table is the audit trail of who approved which pairing,
+ * when, and why.
+ */
+@Injectable()
+export class ConsolidationApprovalService {
+  private readonly logger = new Logger(ConsolidationApprovalService.name);
+
+  constructor(
+    private readonly approvals: ConsolidationApprovalsRepository,
+    private readonly bookingsRepository: BookingsRepository,
+    @Inject(forwardRef(() => BookingsService))
+    private readonly bookingsService: BookingsService,
+    private readonly notifier: BookingLifecycleNotifierService,
+    private readonly dataSource: DataSource,
+  ) {}
+
+  /**
+   * Park a newly consolidated pair for review instead of letting it continue to
+   * Operations. Called from the completion path once the two halves are linked.
+   *
+   * Idempotent: a pair that already has an undecided request is left alone, so a
+   * retried completion cannot open a second review of the same wagon.
+   */
+  async requestApproval(
+    bookingId: string,
+    partnerBookingId: string,
+    requestedBy: string | null,
+  ): Promise<ConsolidationApproval> {
+    const existing = await this.approvals.findPendingForBooking(bookingId);
+    if (existing) return existing;
+
+    // Sequential reads: one connection per transaction context.
+    const booking = await this.bookingsService.findById(bookingId);
+    const partner = await this.bookingsService.findById(partnerBookingId);
+    if (!booking || !partner) {
+      throw new NotFoundException("Both bookings of the pair must exist.");
+    }
+
+    const approval = await this.approvals.create({
+      bookingId,
+      partnerBookingId,
+      requestedBy,
+      scheduledDate: booking.scheduledDate ?? null,
+      bookingReference: booking.reference ?? null,
+      partnerBookingReference: partner.reference ?? null,
+    });
+
+    // Hold BOTH halves: the wagon is shared, so neither may advance alone.
+    await this.bookingsRepository.update(bookingId, {
+      status: CONSOLIDATION_APPROVAL_PENDING,
+    } as never);
+    await this.bookingsRepository.update(partnerBookingId, {
+      status: CONSOLIDATION_APPROVAL_PENDING,
+    } as never);
+
+    this.notifier.consolidationApprovalRequestedToStaff(
+      booking,
+      partner.reference ?? partnerBookingId,
+    );
+    this.logger.log(
+      `Consolidation ${booking.reference} + ${partner.reference} awaiting approval (${approval.id}).`,
+    );
+    return approval;
+  }
+
+  /**
+   * Approve the pairing: both halves leave the gate and continue to Operations,
+   * which is exactly where a non-consolidated booking would already be.
+   *
+   * All-or-nothing — the two status writes and the decision record share one
+   * transaction, so the audit trail can never claim an approval that did not
+   * take effect.
+   */
+  async approve(
+    approvalId: string,
+    decidedBy: string,
+    note?: string,
+  ): Promise<{ booking: Booking; partner: Booking }> {
+    const approval = await this.loadPending(approvalId);
+    this.assertDifferentPerson(approval, decidedBy);
+
+    await this.dataSource.transaction(async () => {
+      const claimed = await this.approvals.decide(
+        approval.id,
+        ConsolidationApprovalStatus.Approved,
+        decidedBy,
+        note,
+      );
+      // Lost the race to another approver deciding the same pairing.
+      if (!claimed) {
+        throw new ConflictException(
+          "This consolidation was already decided by someone else.",
+        );
+      }
+      await this.bookingsRepository.update(approval.bookingId, {
+        status: "OPERATION_REQUEST_PENDING",
+      } as never);
+      await this.bookingsRepository.update(approval.partnerBookingId, {
+        status: "OPERATION_REQUEST_PENDING",
+      } as never);
+    });
+
+    const booking = await this.bookingsService.findById(approval.bookingId);
+    const partner = await this.bookingsService.findById(
+      approval.partnerBookingId,
+    );
+    this.notifier.consolidationApprovedToStaff(
+      booking,
+      partner.reference ?? approval.partnerBookingId,
+    );
+    // Operations only now learns about the pair — the gate is what kept it out.
+    this.notifier.operationRequestedToStaff(booking);
+    this.notifier.operationRequestedToStaff(partner);
+    return { booking, partner };
+  }
+
+  /**
+   * Reject the pairing: both halves go back to GL as OPERATION_CHANGES_REQUESTED
+   * with the reason, so the cargo or the partner can be changed and resubmitted.
+   */
+  async reject(
+    approvalId: string,
+    decidedBy: string,
+    reason: string,
+  ): Promise<{ booking: Booking; partner: Booking }> {
+    if (!reason?.trim()) {
+      throw new BadRequestException(
+        "A reason is required to reject a consolidation.",
+      );
+    }
+    const approval = await this.loadPending(approvalId);
+    this.assertDifferentPerson(approval, decidedBy);
+
+    await this.dataSource.transaction(async () => {
+      const claimed = await this.approvals.decide(
+        approval.id,
+        ConsolidationApprovalStatus.Rejected,
+        decidedBy,
+        reason.trim(),
+      );
+      if (!claimed) {
+        throw new ConflictException(
+          "This consolidation was already decided by someone else.",
+        );
+      }
+      await this.bookingsRepository.createReviewNote(
+        approval.bookingId,
+        reason.trim(),
+        "CHANGES_REQUESTED",
+      );
+      await this.bookingsRepository.createReviewNote(
+        approval.partnerBookingId,
+        reason.trim(),
+        "CHANGES_REQUESTED",
+      );
+      await this.bookingsRepository.update(approval.bookingId, {
+        status: REJECTED_STATUS,
+      } as never);
+      await this.bookingsRepository.update(approval.partnerBookingId, {
+        status: REJECTED_STATUS,
+      } as never);
+    });
+
+    const booking = await this.bookingsService.findById(approval.bookingId);
+    const partner = await this.bookingsService.findById(
+      approval.partnerBookingId,
+    );
+    this.notifier.consolidationRejectedToStaff(
+      booking,
+      partner.reference ?? approval.partnerBookingId,
+      reason.trim(),
+    );
+    return { booking, partner };
+  }
+
+  /** Pending pairings awaiting a decision, oldest first. */
+  queue(): Promise<ConsolidationApproval[]> {
+    return this.approvals.findQueue();
+  }
+
+  /** Full decision history for one booking — who decided what, and when. */
+  historyForBooking(bookingId: string): Promise<ConsolidationApproval[]> {
+    return this.approvals.findAllForBooking(bookingId);
+  }
+
+  /** The undecided request covering this booking, if any. */
+  pendingForBooking(bookingId: string): Promise<ConsolidationApproval | null> {
+    return this.approvals.findPendingForBooking(bookingId);
+  }
+
+  private async loadPending(approvalId: string): Promise<ConsolidationApproval> {
+    const approval = await this.approvals.findById(approvalId);
+    if (!approval) {
+      throw new NotFoundException(`Approval ${approvalId} not found`);
+    }
+    if (approval.status !== ConsolidationApprovalStatus.Pending) {
+      throw new ConflictException(
+        `This consolidation was already ${approval.status.toLowerCase()}.`,
+      );
+    }
+    return approval;
+  }
+
+  /**
+   * Maker–checker: the point of the gate is a second pair of eyes, so the GL
+   * user who created the pairing cannot also approve it.
+   */
+  private assertDifferentPerson(
+    approval: ConsolidationApproval,
+    decidedBy: string,
+  ): void {
+    if (approval.requestedBy && approval.requestedBy === decidedBy) {
+      throw new BadRequestException(
+        "You created this consolidation — it must be approved by someone else.",
+      );
+    }
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/consolidation-approvals.repository.ts b/apps/edr-freight-api/src/modules/bookings/consolidation-approvals.repository.ts
new file mode 100644
index 000000000..b398e7e8c
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/consolidation-approvals.repository.ts
@@ -0,0 +1,120 @@
+import { Injectable } from "@nestjs/common";
+import { DataSource, In, Repository } from "typeorm";
+
+import {
+  ConsolidationApproval,
+  ConsolidationApprovalStatus,
+} from "./entities/consolidation-approval.entity";
+
+/**
+ * Persistence for the shared-wagon approval gate. Rows are never deleted —
+ * decided rows are the audit trail of who approved which pairing and when.
+ */
+@Injectable()
+export class ConsolidationApprovalsRepository {
+  private readonly repository: Repository<ConsolidationApproval>;
+
+  constructor(private readonly dataSource: DataSource) {
+    this.repository = this.dataSource.getRepository(ConsolidationApproval);
+  }
+
+  /**
+   * The undecided request covering `bookingId`, from EITHER side of the pair —
+   * one row governs both halves, and the caller may hold either one.
+   */
+  findPendingForBooking(
+    bookingId: string,
+  ): Promise<ConsolidationApproval | null> {
+    return this.repository.findOne({
+      where: [
+        { bookingId, status: ConsolidationApprovalStatus.Pending },
+        {
+          partnerBookingId: bookingId,
+          status: ConsolidationApprovalStatus.Pending,
+        },
+      ],
+    });
+  }
+
+  /** Every request touching this booking, newest first (the audit trail). */
+  findAllForBooking(bookingId: string): Promise<ConsolidationApproval[]> {
+    return this.repository.find({
+      where: [{ bookingId }, { partnerBookingId: bookingId }],
+      order: { createdAt: "DESC" },
+    });
+  }
+
+  findById(id: string): Promise<ConsolidationApproval | null> {
+    return this.repository.findOne({ where: { id } });
+  }
+
+  /** Pending requests for the review queue, oldest first (FIFO). */
+  findQueue(): Promise<ConsolidationApproval[]> {
+    return this.repository.find({
+      where: { status: ConsolidationApprovalStatus.Pending },
+      relations: {
+        booking: { company: true },
+        partnerBooking: { company: true },
+      },
+      order: { requestedAt: "ASC" },
+    });
+  }
+
+  create(input: {
+    bookingId: string;
+    partnerBookingId: string;
+    requestedBy?: string | null;
+    scheduledDate?: Date | null;
+    bookingReference?: string | null;
+    partnerBookingReference?: string | null;
+  }): Promise<ConsolidationApproval> {
+    return this.repository.save(
+      this.repository.create({
+        ...input,
+        status: ConsolidationApprovalStatus.Pending,
+        requestedAt: new Date(),
+      }),
+    );
+  }
+
+  /**
+   * Record the decision. Written only against a row still PENDING, so two
+   * approvers racing on the same pairing cannot both succeed — the second
+   * update matches nothing and the caller sees `false`.
+   */
+  async decide(
+    id: string,
+    status:
+      | ConsolidationApprovalStatus.Approved
+      | ConsolidationApprovalStatus.Rejected,
+    decidedBy: string | null,
+    decisionNote?: string | null,
+  ): Promise<boolean> {
+    const result = await this.repository.update(
+      { id, status: ConsolidationApprovalStatus.Pending },
+      {
+        status,
+        decidedBy,
+        decidedAt: new Date(),
+        decisionNote: decisionNote ?? null,
+      },
+    );
+    return (result.affected ?? 0) > 0;
+  }
+
+  /** Undecided requests covering any of these bookings (list badging). */
+  findPendingForBookings(
+    bookingIds: string[],
+  ): Promise<ConsolidationApproval[]> {
+    if (bookingIds.length === 0) return Promise.resolve([]);
+    return this.repository.find({
+      where: [
+        { bookingId: In(bookingIds), status: ConsolidationApprovalStatus.Pending },
+        {
+          partnerBookingId: In(bookingIds),
+          status: ConsolidationApprovalStatus.Pending,
+        },
+      ],
+    });
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/request-changes.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/request-changes.dto.ts
index 9c4e5c944..9631def73 100644
--- a/apps/edr-freight-api/src/modules/bookings/dto/request-changes.dto.ts
+++ b/apps/edr-freight-api/src/modules/bookings/dto/request-changes.dto.ts
@@ -158,3 +158,26 @@ export class PairedDecisionDto {
   @Min(1)
   validityDays?: number;
 }
+
+/** Approve a shared-wagon pairing. The note is optional context for the audit. */
+export class ApproveConsolidationDto {
+  @ApiPropertyOptional({
+    description: "Optional note recorded with the approval.",
+    maxLength: 500,
+  })
+  @IsOptional()
+  @IsString()
+  note?: string;
+}
+
+/** Reject a shared-wagon pairing. A reason is mandatory — GL has to act on it. */
+export class RejectConsolidationDto {
+  @ApiProperty({
+    description:
+      "Why the pairing is rejected. Sent back to GL on both bookings.",
+    maxLength: 500,
+  })
+  @IsString()
+  @MinLength(1)
+  reason!: string;
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts b/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
index cdcfbc3eb..c85e15cfb 100644
--- a/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
+++ b/apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts
@@ -58,6 +58,10 @@ export const BOOKING_STATUSES = [
   // the booking enters the batch holding pool.
   'OPERATION_REQUEST_PENDING',
   'OPERATION_CHANGES_REQUESTED',
+  // Shared-wagon review gate: a consolidated pair waits for a human decision
+  // before either half reaches Operations. Two customers' cargo on one wagon is
+  // a commercial call, so it is never auto-advanced.
+  'CONSOLIDATION_APPROVAL_PENDING',
   'OPERATION_PRICE_PENDING_CONFIRM',
 ] as const;
 
diff --git a/apps/edr-freight-api/src/modules/bookings/entities/consolidation-approval.entity.ts b/apps/edr-freight-api/src/modules/bookings/entities/consolidation-approval.entity.ts
new file mode 100644
index 000000000..91c3dcdee
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/entities/consolidation-approval.entity.ts
@@ -0,0 +1,98 @@
+import { BaseEntity } from "@edr/api-common";
+import { Column, Entity, Index, JoinColumn, ManyToOne } from "typeorm";
+
+import { Booking } from "./booking.entity";
+
+export enum ConsolidationApprovalStatus {
+  Pending = "PENDING",
+  Approved = "APPROVED",
+  Rejected = "REJECTED",
+}
+
+/**
+ * Approval gate for a consolidated (shared-wagon) booking pair.
+ *
+ * A booking that fills its own wagons goes straight from GL completion to the
+ * operations queue. A consolidated one does not: two customers' cargo rides one
+ * physical wagon, under two separate invoices and two separate liabilities. That
+ * pairing is a commercial decision, so a person reviews it before Operations
+ * sees either half.
+ *
+ * The pair is approved as a UNIT — one row covers both halves — so nobody can
+ * approve one side of a shared wagon and leave the other pending. Rows are never
+ * deleted: decided rows are the audit trail of who approved which pairing, when,
+ * and why.
+ */
+@Entity({ schema: "freight", name: "consolidation_approvals" })
+@Index(["bookingId", "status"])
+@Index(["status"])
+export class ConsolidationApproval extends BaseEntity {
+  @Column({ name: "booking_id", type: "uuid" })
+  bookingId!: string;
+
+  @ManyToOne(() => Booking)
+  @JoinColumn({ name: "booking_id" })
+  booking?: Booking;
+
+  /** The other half of the shared wagon. */
+  @Column({ name: "partner_booking_id", type: "uuid" })
+  partnerBookingId!: string;
+
+  @ManyToOne(() => Booking)
+  @JoinColumn({ name: "partner_booking_id" })
+  partnerBooking?: Booking;
+
+  @Column({
+    name: "status",
+    type: "enum",
+    enum: ConsolidationApprovalStatus,
+    default: ConsolidationApprovalStatus.Pending,
+  })
+  status!: ConsolidationApprovalStatus;
+
+  /** IAM user id of the GL staff whose completion created the pairing. */
+  @Column({ name: "requested_by", type: "uuid", nullable: true })
+  requestedBy?: string | null;
+
+  @Column({ name: "requested_at", type: "timestamptz", default: () => "now()" })
+  requestedAt!: Date;
+
+  /** IAM user id of the approver; null while pending. */
+  @Column({ name: "decided_by", type: "uuid", nullable: true })
+  decidedBy?: string | null;
+
+  @Column({ name: "decided_at", type: "timestamptz", nullable: true })
+  decidedAt?: Date | null;
+
+  /** Why it was approved or rejected. Required on reject, optional on approve. */
+  @Column({
+    name: "decision_note",
+    type: "varchar",
+    length: 500,
+    nullable: true,
+  })
+  decisionNote?: string | null;
+
+  // ── Snapshot ──────────────────────────────────────────────────────────────
+  // Copied at request time so the audit trail still reads correctly after the
+  // bookings themselves move on (rebooked to another day, cancelled, renamed).
+
+  @Column({ name: "scheduled_date", type: "timestamptz", nullable: true })
+  scheduledDate?: Date | null;
+
+  @Column({
+    name: "booking_reference",
+    type: "varchar",
+    length: 50,
+    nullable: true,
+  })
+  bookingReference?: string | null;
+
+  @Column({
+    name: "partner_booking_reference",
+    type: "varchar",
+    length: 50,
+    nullable: true,
+  })
+  partnerBookingReference?: string | null;
+}
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.completion.spec.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.completion.spec.ts
index c222ffc16..bdb8d74cd 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-booking.completion.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.completion.spec.ts
@@ -30,6 +30,7 @@ describe('ContractBookingService — quantity-cap completion', () => {
       {} as never, // trainSchedulingService
       {} as never, // bookingBatchService
       {} as never, // bookingTransitionService
+      {} as never, // consolidationApprovalService
     );
     return { service, contractsRepository };
   }
@@ -156,6 +157,7 @@ describe('ContractBookingService — quantity-cap completion', () => {
         {} as never,
         {} as never,
         {} as never,
+        {} as never, // consolidationApprovalService
       );
       return { service, contractsRepository };
     }
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.consolidation.spec.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.consolidation.spec.ts
index 84465145d..fb68b3f5c 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-booking.consolidation.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.consolidation.spec.ts
@@ -64,6 +64,7 @@ describe('ContractBookingService — drawdown consolidation gate', () => {
       {} as never, // trainSchedulingService
       {} as never, // bookingBatchService
       {} as never, // bookingTransitionService
+      {} as never, // consolidationApprovalService
     );
     return {
       service,
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.initiate-gate.spec.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.initiate-gate.spec.ts
index 6b5f54c91..6155eb583 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-booking.initiate-gate.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.initiate-gate.spec.ts
@@ -26,6 +26,7 @@ describe('ContractBookingService — customs booking gate', () => {
       {} as never, // trainSchedulingService
       {} as never, // bookingBatchService
       {} as never, // bookingTransitionService
+      {} as never, // consolidationApprovalService
     );
   }
 
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.manual-consolidation.spec.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.manual-consolidation.spec.ts
index 841baab31..49e77627f 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-booking.manual-consolidation.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.manual-consolidation.spec.ts
@@ -44,6 +44,9 @@ describe('ContractBookingService — manual odd-20ft consolidation', () => {
       {} as never, // trainSchedulingService
       {} as never, // bookingBatchService
       {} as never, // bookingTransitionService
+      // The pairing is parked for approval rather than going straight to
+      // Operations; the gate itself is covered by its own spec.
+      { requestApproval: jest.fn().mockResolvedValue({ id: 'ap-1' }) } as never,
     );
     return { service, bookingsRepository, dataSource };
   }
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.resubmit-cargo.spec.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.resubmit-cargo.spec.ts
index d5d15d73d..0a892b108 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-booking.resubmit-cargo.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.resubmit-cargo.spec.ts
@@ -59,6 +59,7 @@ describe('ContractBookingService — changes-requested resubmit restating cargo'
       trainSchedulingService as never,
       {} as never, // bookingBatchService
       {} as never, // bookingTransitionService
+      {} as never, // consolidationApprovalService
     );
     return { service, bookingsRepository, invoiceService };
   }
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
index ddd85fc48..9e31aff34 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
@@ -20,6 +20,7 @@ import { BookingPricingService } from '../bookings/booking-pricing.service';
 import { BookingTransitionService } from '../bookings/booking-transition.service';
 import { BookingLifecycleNotifierService } from '../bookings/booking-lifecycle-notifier.service';
 import { ConsolidationService } from '../bookings/consolidation.service';
+import { ConsolidationApprovalService } from '../bookings/consolidation-approval.service';
 import { PriceLineItemDto } from '../bookings/dto/generate-price-response.dto';
 import { BookingInvoiceService } from '../bookings/booking-invoice.service';
 import { validate20ftWeightPairing } from '../bookings/container-pairing.util';
@@ -130,6 +131,8 @@ export class ContractBookingService {
     private readonly bookingBatchService: BookingBatchService,
     @Inject(forwardRef(() => BookingTransitionService))
     private readonly bookingTransitionService: BookingTransitionService,
+    @Inject(forwardRef(() => ConsolidationApprovalService))
+    private readonly consolidationApprovalService: ConsolidationApprovalService,
   ) {}
 
   async createUnderContract(
@@ -674,6 +677,8 @@ export class ContractBookingService {
     bookingId: string,
     dto: CompleteConsolidatedPairDto,
     actorPermissions?: unknown,
+    /** IAM id of the GL user creating the pairing — recorded on the approval. */
+    actorUserId?: string | null,
   ): Promise<{
     booking: Booking;
     partner: Booking;
@@ -736,6 +741,16 @@ export class ContractBookingService {
       return { ownId: own.booking.id, partnerId: other.booking.id };
     });
 
+    // Both halves have just been completed into the operations queue by the
+    // ordinary completion machine. A shared wagon does not go there unreviewed:
+    // pull the pair back into the approval gate, which releases them to
+    // Operations only once a person signs off on the pairing.
+    await this.consolidationApprovalService.requestApproval(
+      ownId,
+      partnerId,
+      actorUserId ?? null,
+    );
+
     // Sequential reads: one connection per transaction context.
     const finalBooking = await this.bookingsRepository.findByIdWithFiles(ownId);
     const finalPartner = await this.bookingsRepository.findByIdWithFiles(partnerId);
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 76106a9ff..826c7fdff 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
@@ -358,32 +358,39 @@ export class ContractClearanceService {
     // Once GL creates the shipment booking, surface its reference + status so the
     // customer sees the concrete booking instead of a stale "will be created
     // shortly" message. Reuse the export booking load; fetch for import too.
+    let linkedBookingId: string | null = null;
     let linkedBookingReference: string | null = null;
     let linkedBookingStatus: string | null = null;
     let linkedBookingReviewNote: string | null = null;
     let linkedBookingScheduledDate: string | null = null;
-    if (cycle?.bookingId) {
-      const booking = await this.bookingsService.findById(cycle.bookingId);
-      if (booking) {
-        linkedBookingReference = booking.reference ?? null;
-        linkedBookingStatus = booking.status ?? null;
-        linkedBookingScheduledDate = booking.scheduledDate
-          ? new Date(booking.scheduledDate).toISOString()
-          : null;
-        // Newest changes-requested note (reviewNotes ride along on findById).
-        linkedBookingReviewNote =
-          [...(booking.reviewNotes ?? [])]
-            .filter((n) => n.type === 'CHANGES_REQUESTED')
-            .sort(
-              (a, b) =>
-                new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
-            )[0]?.note ?? null;
-        if (contract.tradeDirection === 'EXPORT') {
-          nextAction = this.workflowService.computeNextActionForBooking(
-            booking,
-            bookingMilestones,
-          );
-        }
+    // The cycle is the historical link, but it is not written on every path (an
+    // FCFS export booking and a GL drawdown both reach the operations queue
+    // without a cycle row), so fall back to the contract's own live booking —
+    // otherwise the clearance page sees no linked booking at all and cannot show
+    // its status or the actions that depend on it.
+    const booking = cycle?.bookingId
+      ? await this.bookingsService.findById(cycle.bookingId)
+      : await this.contractsRepository.findLatestBookingForContract(contractId);
+    if (booking) {
+      linkedBookingId = booking.id ?? null;
+      linkedBookingReference = booking.reference ?? null;
+      linkedBookingStatus = booking.status ?? null;
+      linkedBookingScheduledDate = booking.scheduledDate
+        ? new Date(booking.scheduledDate).toISOString()
+        : null;
+      // Newest changes-requested note (reviewNotes ride along on findById).
+      linkedBookingReviewNote =
+        [...(booking.reviewNotes ?? [])]
+          .filter((n) => n.type === 'CHANGES_REQUESTED')
+          .sort(
+            (a, b) =>
+              new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
+          )[0]?.note ?? null;
+      if (contract.tradeDirection === 'EXPORT') {
+        nextAction = this.workflowService.computeNextActionForBooking(
+          booking,
+          bookingMilestones,
+        );
       }
     }
 
@@ -420,7 +427,7 @@ export class ContractClearanceService {
       bookingReady: boundary,
       preClearanceFinalized: Boolean(cycle?.preClearanceFinalizedAt),
       exportClearanceFinalized: Boolean(cycle?.completedAt),
-      linkedBookingId: cycle?.bookingId ?? null,
+      linkedBookingId,
       linkedBookingReference,
       linkedBookingStatus,
       linkedBookingReviewNote,
diff --git a/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts b/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
index e9404f8e1..9f602ec21 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
@@ -1194,6 +1194,9 @@ export class ContractsController {
       bookingId,
       dto,
       user,
+      // Recorded as the requester on the approval: the person who created the
+      // pairing may not be the one who approves it.
+      user?.id ?? user?.sub ?? null,
     );
   }
 
diff --git a/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts b/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
index d89d43250..309079010 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
@@ -656,6 +656,31 @@ export class ContractsRepository extends BaseRepository<Contract> {
       .getCount();
   }
 
+  /**
+   * The live shipment booking on a contract, newest first.
+   *
+   * The clearance view historically reached the booking through
+   * `currentCycle().bookingId`, but a cycle row is not created on every path —
+   * an FCFS export booking and a GL drawdown both reach
+   * OPERATION_REQUEST_PENDING without one — so that lookup returns null and the
+   * clearance page loses the booking's status entirely. This resolves it from
+   * the bookings themselves, which is the authoritative link (bookings carry
+   * contract_id), and is used as the fallback when the cycle has no booking.
+   */
+  async findLatestBookingForContract(
+    contractId: string,
+  ): Promise<Booking | null> {
+    return this.dataSource
+      .getRepository(Booking)
+      .createQueryBuilder('b')
+      .where('b.contract_id = :contractId', { contractId })
+      .andWhere('b.status NOT IN (:...terminal)', {
+        terminal: TERMINAL_BOOKING_STATUSES,
+      })
+      .orderBy('b.created_at', 'DESC')
+      .getOne();
+  }
+
   async createReviewNote(
     contractId: string,
     body: string,
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 87ba8cf8a..e9c0d453a 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -226,6 +226,14 @@ export const BOOKING_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:bookings:wagon_cancellation_rebook",
     "Rebook cancelled wagons for a customer",
   ),
+  // Shared-wagon gate: two customers' cargo on one wagon is a commercial call,
+  // so it is signed off separately from the ordinary booking approvals — and
+  // never by the GL user who created the pairing.
+  perm(
+    "a1000001-0001-4000-8000-000000000029",
+    "edr_freight_app:bookings:approve_consolidation",
+    "Approve shared-wagon consolidation",
+  ),
 ];
 
 /**
@@ -1754,6 +1762,7 @@ export const FREIGHT_PERMS = {
     wagonCancellationVoid: "edr_freight_app:bookings:wagon_cancellation_void",
     wagonCancellationRebook:
       "edr_freight_app:bookings:wagon_cancellation_rebook",
+    approveConsolidation: "edr_freight_app:bookings:approve_consolidation",
     // Notification selectors, not route guards — see NOTIFICATION_PERMISSIONS.
     getNotification: "edr_freight_app:bookings:get_notification",
     clearanceGetNotification:
@@ -2354,6 +2363,10 @@ export const ROLE_PERMISSION_PRESETS = {
     FREIGHT_PERMS.bookings.reject,
     FREIGHT_PERMS.bookings.approveLineStaff,
     FREIGHT_PERMS.bookings.rejectApproval,
+    // Shared-wagon gate: two customers' cargo on one wagon is a commercial
+    // call. Granted to the approver roles and NOT to GL — GL creates the
+    // pairing, so GL approving it would defeat the second pair of eyes.
+    FREIGHT_PERMS.bookings.approveConsolidation,
     FREIGHT_PERMS.bookings.cancel,
     FREIGHT_PERMS.bookings.wagonCancellationView,
     FREIGHT_PERMS.bookings.wagonCancellationVoid,
@@ -2410,6 +2423,10 @@ export const ROLE_PERMISSION_PRESETS = {
     FREIGHT_PERMS.bookings.view,
     FREIGHT_PERMS.bookings.approveDirector,
     FREIGHT_PERMS.bookings.rejectApproval,
+    // Shared-wagon gate: two customers' cargo on one wagon is a commercial
+    // call. Granted to the approver roles and NOT to GL — GL creates the
+    // pairing, so GL approving it would defeat the second pair of eyes.
+    FREIGHT_PERMS.bookings.approveConsolidation,
     FREIGHT_PERMS.bookings.generateContract,
     FREIGHT_PERMS.contracts.view,
     FREIGHT_PERMS.contracts.approveDirector,
@@ -2422,6 +2439,10 @@ export const ROLE_PERMISSION_PRESETS = {
     FREIGHT_PERMS.bookings.view,
     FREIGHT_PERMS.bookings.approveCeo,
     FREIGHT_PERMS.bookings.rejectApproval,
+    // Shared-wagon gate: two customers' cargo on one wagon is a commercial
+    // call. Granted to the approver roles and NOT to GL — GL creates the
+    // pairing, so GL approving it would defeat the second pair of eyes.
+    FREIGHT_PERMS.bookings.approveConsolidation,
     FREIGHT_PERMS.contracts.view,
     FREIGHT_PERMS.contracts.approveCeo,
     ...allRuleEngineViewKeys(),
@@ -2500,6 +2521,10 @@ export const ROLE_PERMISSION_PRESETS = {
     FREIGHT_PERMS.bookings.reject,
     FREIGHT_PERMS.bookings.approveLineStaff,
     FREIGHT_PERMS.bookings.rejectApproval,
+    // Shared-wagon gate: two customers' cargo on one wagon is a commercial
+    // call. Granted to the approver roles and NOT to GL — GL creates the
+    // pairing, so GL approving it would defeat the second pair of eyes.
+    FREIGHT_PERMS.bookings.approveConsolidation,
     FREIGHT_PERMS.bookings.cancel,
     FREIGHT_PERMS.bookings.wagonCancellationView,
     FREIGHT_PERMS.bookings.wagonCancellationVoid,
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index f07ec32b5..d303e3b77 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -19,6 +19,7 @@ import ForgotPasswordPage from "./pages/auth/ForgotPasswordPage";
 import BookingContractPage from "./pages/bookings/BookingContractPage";
 import BookingRequestDetailPage from "./pages/bookings/BookingRequestDetailPage";
 import BookingRequestsPage from "./pages/bookings/BookingRequestsPage";
+import ConsolidationApprovalsPage from "./pages/bookings/ConsolidationApprovalsPage";
 import NewBookingPage from "./pages/bookings/NewBookingPage";
 import WagonCancellationsPage from "./pages/bookings/WagonCancellationsPage";
 import ContractRequestsPage from "./pages/contracts/ContractRequestsPage";
@@ -381,6 +382,18 @@ const App = () => {
             </RequirePermission>
           }
         />
+        {/* Shared-wagon gate: consolidated pairs wait for a human decision
+            before either half reaches Operations. */}
+        <Route
+          path="consolidation-approvals"
+          element={
+            <RequirePermission
+              permission={FREIGHT_PERMS.bookings.approveConsolidation}
+            >
+              <ConsolidationApprovalsPage />
+            </RequirePermission>
+          }
+        />
         <Route
           path="booking-requests/:id"
           element={
diff --git a/apps/edr-freight-web/backoffice/src/components/bookings/detail/ConsolidationApprovalCard.tsx b/apps/edr-freight-web/backoffice/src/components/bookings/detail/ConsolidationApprovalCard.tsx
new file mode 100644
index 000000000..a5c74f52e
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/bookings/detail/ConsolidationApprovalCard.tsx
@@ -0,0 +1,82 @@
+import { useQuery } from "@tanstack/react-query";
+import { Badge, Box, Group, Stack, Text } from "@mantine/core";
+import { Link2 } from "lucide-react";
+
+import { bookingsService } from "@/services/bookings.service";
+import { formatDateTime } from "@/lib/format";
+import { SectionCard } from "./SectionCard";
+
+const STATUS_COLOR: Record<string, string> = {
+  PENDING: "yellow",
+  APPROVED: "teal",
+  REJECTED: "red",
+};
+
+/**
+ * Audit trail for this booking's shared wagon: every approval request against
+ * it, who decided, when, and why. Rendered only for a booking that is actually
+ * consolidated — there is nothing to show otherwise.
+ */
+export function ConsolidationApprovalCard({ bookingId }: { bookingId: string }) {
+  const { data } = useQuery({
+    queryKey: ["consolidation-approvals", "history", bookingId],
+    queryFn: () => bookingsService.consolidationApprovalHistory(bookingId),
+    enabled: Boolean(bookingId),
+  });
+
+  if (!data?.length) return null;
+
+  return (
+    <SectionCard icon={Link2} title="Shared wagon approval">
+      <Stack gap="md">
+        {data.map((row) => (
+          <Box
+            key={row.id}
+            style={{
+              borderLeft: "3px solid var(--mantine-color-gray-3)",
+              paddingLeft: 12,
+            }}
+          >
+            <Group gap={8} align="center" wrap="wrap" mb={4}>
+              <Badge
+                color={STATUS_COLOR[row.status] ?? "gray"}
+                variant="light"
+                radius="sm"
+                size="sm"
+              >
+                {row.status}
+              </Badge>
+              <Text fz={13} fw={600}>
+                {row.bookingReference ?? "—"} + {row.partnerBookingReference ?? "—"}
+              </Text>
+            </Group>
+
+            <Text fz={12} c="dimmed">
+              Requested {formatDateTime(row.requestedAt)}
+              {row.requestedBy ? ` by ${row.requestedBy}` : ""}
+            </Text>
+
+            {row.decidedAt ? (
+              <Text fz={12} c="dimmed">
+                {row.status === "APPROVED" ? "Approved" : "Rejected"}{" "}
+                {formatDateTime(row.decidedAt)}
+                {row.decidedBy ? ` by ${row.decidedBy}` : ""}
+              </Text>
+            ) : (
+              <Text fz={12} c="yellow.8">
+                Waiting for a decision — neither booking reaches Operations until
+                this is approved.
+              </Text>
+            )}
+
+            {row.decisionNote ? (
+              <Text fz={12.5} mt={4} style={{ whiteSpace: "pre-wrap" }}>
+                “{row.decisionNote}”
+              </Text>
+            ) : null}
+          </Box>
+        ))}
+      </Stack>
+    </SectionCard>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/trainBuilder/AvailableWagonsPanel.tsx b/apps/edr-freight-web/backoffice/src/components/trainBuilder/AvailableWagonsPanel.tsx
index 034b4c0bb..7077f3fdf 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainBuilder/AvailableWagonsPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainBuilder/AvailableWagonsPanel.tsx
@@ -14,7 +14,7 @@ import {
 import { useDebouncedValue } from "@mantine/hooks";
 import { useQuery } from "@tanstack/react-query";
 import { MapPin, Plus, Search } from "lucide-react";
-import { useEffect, useMemo, useState } from "react";
+import { memo, useCallback, useEffect, useMemo, useState } from "react";
 
 const PAGE_SIZE = 20;
 
@@ -24,7 +24,7 @@ import { api } from "@/services/api";
  * AVAILABLE, unassigned wagons from every yard — filtered and paged on the API,
  * so the picker never page-walks the whole fleet into the browser.
  */
-export default function AvailableWagonsPanel({
+function AvailableWagonsPanel({
   homeYardId,
   onAssign,
   assigning,
@@ -36,7 +36,7 @@ export default function AvailableWagonsPanel({
   const [typeFilter, setTypeFilter] = useState<string>("ALL");
   const [yardFilter, setYardFilter] = useState<string>("ALL");
   const [runOnly, setRunOnly] = useState(false);
-  const [selected, setSelected] = useState<string[]>([]);
+  const [selected, setSelected] = useState<ReadonlySet<string>>(() => new Set());
   const [page, setPage] = useState(1);
 
   // The train's own run, e.g. "8001-8002" — only offered when the train has one.
@@ -60,6 +60,9 @@ export default function AvailableWagonsPanel({
           pageSize: PAGE_SIZE,
         },
       },
+      // Keep the previous page on screen while the next one loads — otherwise
+      // paging and typing flash the list to "Loading wagons…" on every stroke.
+      placeholderData: (prev) => prev,
     }),
   );
 
@@ -105,32 +108,32 @@ export default function AvailableWagonsPanel({
     [wagonTypesQuery.data],
   );
 
-  const toggle = (wagonId: string, checked: boolean) => {
-    setSelected((prev) =>
-      checked ? [...prev, wagonId] : prev.filter((id) => id !== wagonId),
-    );
-  };
+  const toggle = useCallback((wagonId: string, checked: boolean) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (checked) next.add(wagonId);
+      else next.delete(wagonId);
+      return next;
+    });
+  }, []);
 
   // Select-all covers this page only — the rest of the matches are not loaded.
-  const allSelected = wagons.length > 0 && wagons.every((w) => selected.includes(w.id));
-  const someSelected = wagons.some((w) => selected.includes(w.id));
+  const allSelected = wagons.length > 0 && wagons.every((w) => selected.has(w.id));
+  const someSelected = wagons.some((w) => selected.has(w.id));
 
   const toggleAll = (checked: boolean) => {
     setSelected((prev) => {
-      if (checked) {
-        const ids = new Set(prev);
-        wagons.forEach((w) => ids.add(w.id));
-        return [...ids];
-      }
-      const visible = new Set(wagons.map((w) => w.id));
-      return prev.filter((id) => !visible.has(id));
+      const next = new Set(prev);
+      if (checked) wagons.forEach((w) => next.add(w.id));
+      else wagons.forEach((w) => next.delete(w.id));
+      return next;
     });
   };
 
   const handleAssign = () => {
-    if (!selected.length) return;
-    onAssign(selected);
-    setSelected([]);
+    if (!selected.size) return;
+    onAssign([...selected]);
+    setSelected(new Set());
   };
 
   return (
@@ -178,16 +181,24 @@ export default function AvailableWagonsPanel({
             indeterminate={!allSelected && someSelected}
             onChange={(e) => toggleAll(e.currentTarget.checked)}
           />
-          {selected.length ? (
+          {selected.size ? (
             <Text size="xs" c="dimmed">
-              {selected.length} selected
+              {selected.size} selected
             </Text>
           ) : null}
         </Group>
       ) : null}
 
       <ScrollArea.Autosize mah={380} type="auto">
-        <Stack gap={6}>
+        {/* Previous results stay put while the next page loads (placeholderData),
+            so dim them rather than blanking the list. */}
+        <Stack
+          gap={6}
+          style={{
+            opacity: wagonsQuery.isFetching && !wagonsQuery.isLoading ? 0.55 : 1,
+            transition: "opacity 120ms ease",
+          }}
+        >
           {wagonsQuery.isLoading ? (
             <Text py="md" ta="center" c="dimmed" size="sm">
               Loading wagons…
@@ -198,57 +209,14 @@ export default function AvailableWagonsPanel({
             </Text>
           ) : (
             wagons.map((wagon) => (
-              <Group
+              <WagonOption
                 key={wagon.id}
-                gap="sm"
-                wrap="nowrap"
-                p="xs"
-                style={{
-                  border: "1px solid var(--mantine-color-gray-2)",
-                  borderRadius: "var(--mantine-radius-md)",
-                }}
-              >
-                <Checkbox
-                  size="sm"
-                  checked={selected.includes(wagon.id)}
-                  onChange={(e) => toggle(wagon.id, e.currentTarget.checked)}
-                  aria-label={`Select wagon ${wagon.wagonNumber}`}
-                />
-                <Stack gap={0} style={{ flex: 1, minWidth: 0 }}>
-                  <Group gap={6} wrap="nowrap">
-                    <Text size="sm" fw={600} ff="monospace" truncate>
-                      {wagon.wagonNumber}
-                    </Text>
-                    <Badge
-                      size="xs"
-                      radius="sm"
-                      variant="outline"
-                      color={wagon.currentYardId === homeYardId ? "edr-green" : "gray"}
-                      leftSection={<MapPin size={10} />}
-                    >
-                      {wagon.currentYard?.label ?? wagon.currentYard?.code ?? "No yard"}
-                    </Badge>
-                    {wagon.exportTrainNumber ? (
-                      <Badge
-                        size="xs"
-                        radius="sm"
-                        variant="light"
-                        color={
-                          wagon.exportTrainNumber === exportTrainNumber ? "edr-green" : "gray"
-                        }
-                      >
-                        {wagon.exportTrainNumber}
-                        {wagon.importTrainNumber ? `-${wagon.importTrainNumber}` : ""}
-                      </Badge>
-                    ) : null}
-                  </Group>
-                  <Text size="xs" c="dimmed" truncate>
-                    {wagon.wagonType
-                      ? `${wagon.wagonType.name} · ${wagon.wagonType.capacityTons ?? "—"}T cap`
-                      : "Unknown type"}
-                  </Text>
-                </Stack>
-              </Group>
+                wagon={wagon}
+                selected={selected.has(wagon.id)}
+                homeYardId={homeYardId}
+                exportTrainNumber={exportTrainNumber}
+                onToggle={toggle}
+              />
             ))
           )}
         </Stack>
@@ -265,16 +233,19 @@ export default function AvailableWagonsPanel({
 
       <Button
         leftSection={<Plus size={16} />}
-        disabled={!selected.length}
+        disabled={!selected.size}
         loading={assigning}
         onClick={handleAssign}
       >
-        Add {selected.length ? `${selected.length} wagon${selected.length > 1 ? "s" : ""}` : "wagons"} to consist
+        Add {selected.size ? `${selected.size} wagon${selected.size > 1 ? "s" : ""}` : "wagons"} to consist
       </Button>
     </Stack>
   );
 }
 
+/** Memoized: the workspace re-renders on every pending mutation. */
+export default memo(AvailableWagonsPanel);
+
 export interface AvailableWagonsPanelProps {
   /** The train's own yard — sorted first and highlighted; not a restriction. */
   homeYardId: string | null;
@@ -285,3 +256,81 @@ export interface AvailableWagonsPanelProps {
   /** This train's even IMPORT run — label only; the export run does the matching. */
   importTrainNumber?: string | null;
 }
+
+/**
+ * One selectable wagon row. Memoized: the picker re-renders on every keystroke
+ * and every selection change, but a row only actually changes when its own
+ * checkbox flips — so a full page of rows stays untouched.
+ */
+const WagonOption = memo(function WagonOption({
+  wagon,
+  selected,
+  homeYardId,
+  exportTrainNumber,
+  onToggle,
+}: {
+  wagon: {
+    id: string;
+    wagonNumber: string;
+    currentYardId?: string | null;
+    currentYard?: { label?: string | null; code?: string | null } | null;
+    exportTrainNumber?: string | null;
+    importTrainNumber?: string | null;
+    wagonType?: { name?: string | null; capacityTons?: number | null } | null;
+  };
+  selected: boolean;
+  homeYardId: string | null;
+  exportTrainNumber?: string | null;
+  onToggle: (wagonId: string, checked: boolean) => void;
+}) {
+  return (
+    <Group
+      gap="sm"
+      wrap="nowrap"
+      p="xs"
+      style={{
+        border: "1px solid var(--mantine-color-gray-2)",
+        borderRadius: "var(--mantine-radius-md)",
+      }}
+    >
+      <Checkbox
+        size="sm"
+        checked={selected}
+        onChange={(e) => onToggle(wagon.id, e.currentTarget.checked)}
+        aria-label={`Select wagon ${wagon.wagonNumber}`}
+      />
+      <Stack gap={0} style={{ flex: 1, minWidth: 0 }}>
+        <Group gap={6} wrap="nowrap">
+          <Text size="sm" fw={600} ff="monospace" truncate>
+            {wagon.wagonNumber}
+          </Text>
+          <Badge
+            size="xs"
+            radius="sm"
+            variant="outline"
+            color={wagon.currentYardId === homeYardId ? "edr-green" : "gray"}
+            leftSection={<MapPin size={10} />}
+          >
+            {wagon.currentYard?.label ?? wagon.currentYard?.code ?? "No yard"}
+          </Badge>
+          {wagon.exportTrainNumber ? (
+            <Badge
+              size="xs"
+              radius="sm"
+              variant="light"
+              color={wagon.exportTrainNumber === exportTrainNumber ? "edr-green" : "gray"}
+            >
+              {wagon.exportTrainNumber}
+              {wagon.importTrainNumber ? `-${wagon.importTrainNumber}` : ""}
+            </Badge>
+          ) : null}
+        </Group>
+        <Text size="xs" c="dimmed" truncate>
+          {wagon.wagonType
+            ? `${wagon.wagonType.name} · ${wagon.wagonType.capacityTons ?? "—"}T cap`
+            : "Unknown type"}
+        </Text>
+      </Stack>
+    </Group>
+  );
+});
diff --git a/apps/edr-freight-web/backoffice/src/components/trainBuilder/ConsistWagonList.tsx b/apps/edr-freight-web/backoffice/src/components/trainBuilder/ConsistWagonList.tsx
index 179502b2d..101176042 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainBuilder/ConsistWagonList.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainBuilder/ConsistWagonList.tsx
@@ -8,7 +8,7 @@ import {
 } from "@hello-pangea/dnd";
 import { ActionIcon, Badge, Box, Group, Stack, Text, Tooltip } from "@mantine/core";
 import { GripVertical, MapPin, Trash2, Wrench } from "lucide-react";
-import { type ReactNode } from "react";
+import { memo, useCallback, useMemo, type ReactNode } from "react";
 import { createPortal } from "react-dom";
 
 import type { TrainCompositionWagon } from "@/services/trainBuilder.service";
@@ -32,7 +32,7 @@ const PortalAwareRow = ({
  * The train's ordered wagon consist. Drag to reorder (persisted on drop),
  * trash to detach a wagon back to the yard.
  */
-export default function ConsistWagonList({
+function ConsistWagonList({
   wagons,
   editable,
   onReorder,
@@ -40,7 +40,7 @@ export default function ConsistWagonList({
   onMaintenance,
   busy = false,
 }: ConsistWagonListProps) {
-  const onDragEnd = (result: DropResult) => {
+  const onDragEnd = useCallback((result: DropResult) => {
     if (!result.destination) return;
     const from = result.source.index;
     const to = result.destination.index;
@@ -49,7 +49,18 @@ export default function ConsistWagonList({
     const [moved] = next.splice(from, 1);
     next.splice(to, 0, moved!);
     onReorder(next.map((w) => w.id));
-  };
+  }, [wagons, onReorder]);
+
+  // Legend of the types actually coupled, in consist order — the colour code is
+  // only readable if the row tints are keyed somewhere.
+  const legend = useMemo(
+    () => [
+      ...new Map(
+        wagons.filter((w) => w.wagonType).map((w) => [w.wagonType!.code, w.wagonType!]),
+      ).values(),
+    ],
+    [wagons],
+  );
 
   if (!wagons.length) {
     return (
@@ -59,16 +70,6 @@ export default function ConsistWagonList({
     );
   }
 
-  // Legend of the types actually coupled, in consist order — the colour code is
-  // only readable if the row tints are keyed somewhere.
-  const legend = [
-    ...new Map(
-      wagons
-        .filter((w) => w.wagonType)
-        .map((w) => [w.wagonType!.code, w.wagonType!]),
-    ).values(),
-  ];
-
   return (
     <DragDropContext onDragEnd={onDragEnd}>
       <Droppable droppableId="train-consist-wagons" isDropDisabled={!editable || busy}>
@@ -118,6 +119,9 @@ export default function ConsistWagonList({
   );
 }
 
+/** Memoized: a 40-wagon consist re-renders every row otherwise. */
+export default memo(ConsistWagonList);
+
 export interface ConsistWagonListProps {
   wagons: TrainCompositionWagon[];
   editable: boolean;
@@ -128,7 +132,7 @@ export interface ConsistWagonListProps {
   busy?: boolean;
 }
 
-function WagonRow({
+const WagonRow = memo(function WagonRow({
   wagon,
   index,
   dragProvided,
@@ -232,4 +236,4 @@ function WagonRow({
       </Group>
     </PortalAwareRow>
   );
-}
+});
diff --git a/apps/edr-freight-web/backoffice/src/components/trainScheduling/TrainCompositionDiagram.tsx b/apps/edr-freight-web/backoffice/src/components/trainScheduling/TrainCompositionDiagram.tsx
index 6a89af519..79bc9ece2 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/TrainCompositionDiagram.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/TrainCompositionDiagram.tsx
@@ -1,4 +1,4 @@
-import { useMemo } from "react";
+import { memo, useMemo } from "react";
 import { Box, Group, Paper, Progress, Stack, Text, Tooltip } from "@mantine/core";
 import { useElementSize } from "@mantine/hooks";
 import { Box as BoxIcon, Container as ContainerIcon, Fuel, Gauge, TrainFront } from "lucide-react";
@@ -132,7 +132,7 @@ function Coupler() {
   );
 }
 
-function LocomotiveCar({
+const LocomotiveCar = memo(function LocomotiveCar({
   code,
   name,
   maxPullWeightTons,
@@ -260,7 +260,7 @@ function LocomotiveCar({
       </Box>
     </Tooltip>
   );
-}
+});
 
 const CONTAINER_GRADIENTS = [
   "linear-gradient(180deg, var(--mantine-color-cyan-5), var(--mantine-color-cyan-7))",
@@ -271,7 +271,7 @@ const CONTAINER_BORDERS = [
   "var(--mantine-color-blue-8)",
 ];
 
-function WagonCar({ wagon }: { wagon: NormalizedWagon }) {
+const WagonCar = memo(function WagonCar({ wagon }: { wagon: NormalizedWagon }) {
   // GROSS on both sides: cargo + tare vs rated payload + tare.
   const grossTons = round1(wagon.assignedWeightTons + wagon.tareWeightTons);
   const maxGrossTons = round1(wagon.capacityTons + wagon.tareWeightTons);
@@ -468,7 +468,7 @@ function WagonCar({ wagon }: { wagon: NormalizedWagon }) {
       </Box>
     </Tooltip>
   );
-}
+});
 
 /** Railway track: two rails over evenly-spaced sleepers. */
 function TrackBed() {
@@ -520,7 +520,7 @@ function TrackBed() {
   );
 }
 
-export function TrainCompositionDiagram({
+export const TrainCompositionDiagram = memo(function TrainCompositionDiagram({
   locomotive,
   locomotives,
   wagons,
@@ -818,7 +818,7 @@ export function TrainCompositionDiagram({
       </Stack>
     </Paper>
   );
-}
+});
 
 function LegendDot({ color, label }: { color: string; label: string }) {
   return (
diff --git a/apps/edr-freight-web/backoffice/src/constants/URLS.ts b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
index 1415ad37b..745ab7fd8 100644
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -193,6 +193,15 @@ export const URL_CONSTANTS = {
     STAFF_ACCEPT: (id: string) => `/bookings/${id}/staff/accept`,
     // Consolidated pair: one staff decision applied to both halves at once.
     PAIRED_DECISION: (id: string) => `/bookings/${id}/paired-decision`,
+    // Shared-wagon approval gate: a consolidated pair waits for a human
+    // decision before either half reaches Operations.
+    CONSOLIDATION_APPROVAL_QUEUE: "/bookings/consolidation-approvals/queue",
+    CONSOLIDATION_APPROVAL_HISTORY: (id: string) =>
+      `/bookings/${id}/consolidation-approvals`,
+    CONSOLIDATION_APPROVE: (approvalId: string) =>
+      `/bookings/consolidation-approvals/${approvalId}/approve`,
+    CONSOLIDATION_REJECT: (approvalId: string) =>
+      `/bookings/consolidation-approvals/${approvalId}/reject`,
     STAFF_REQUEST_CHANGES: (id: string) =>
       `/bookings/${id}/staff/request-changes`,
     STAFF_REJECT: (id: string) => `/bookings/${id}/staff/reject`,
diff --git a/apps/edr-freight-web/backoffice/src/features/bookings/booking-status.config.ts b/apps/edr-freight-web/backoffice/src/features/bookings/booking-status.config.ts
index 07dbae7ce..cd3cef570 100644
--- a/apps/edr-freight-web/backoffice/src/features/bookings/booking-status.config.ts
+++ b/apps/edr-freight-web/backoffice/src/features/bookings/booking-status.config.ts
@@ -102,6 +102,11 @@ export const BOOKING_STATUS_STYLES: Record<string, StatusStyle> = {
     label: "Operation Changes",
     color: "bg-orange-50 text-orange-700 border-orange-200",
   },
+  // Shared-wagon gate: held for a human decision before reaching Operations.
+  CONSOLIDATION_APPROVAL_PENDING: {
+    label: "Wagon Approval",
+    color: "bg-amber-50 text-amber-700 border-amber-200",
+  },
   OPERATION_PRICE_PENDING_CONFIRM: {
     label: "Price Confirm",
     color: "bg-amber-50 text-amber-700 border-amber-200",
@@ -309,6 +314,9 @@ export const BOOKING_LIST_TABS = [
       "OPERATION_REQUEST_PENDING",
       "OPERATION_CHANGES_REQUESTED",
       "OPERATION_PRICE_PENDING_CONFIRM",
+      // Held at the shared-wagon gate — still an ops-review-stage booking, it
+      // just needs the pairing signed off before Operations can act on it.
+      "CONSOLIDATION_APPROVAL_PENDING",
     ],
   },
   {
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index 218989517..6dce79940 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -57,6 +57,7 @@ export const FREIGHT_PERMS = {
     wagonCancellationVoid: "edr_freight_app:bookings:wagon_cancellation_void",
     wagonCancellationRebook:
       "edr_freight_app:bookings:wagon_cancellation_rebook",
+    approveConsolidation: "edr_freight_app:bookings:approve_consolidation",
   },
   contracts: {
     view: "edr_freight_app:contracts:view",
diff --git a/apps/edr-freight-web/backoffice/src/lib/queryClient.test.ts b/apps/edr-freight-web/backoffice/src/lib/queryClient.test.ts
new file mode 100644
index 000000000..81a91d8ee
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/lib/queryClient.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import { queryClient } from "./queryClient";
+
+/**
+ * The MutationCache seeds `meta.updates` entries into the cache and then skips
+ * exactly those keys when running `meta.invalidates`. Getting that skip wrong
+ * silently reintroduces the refetch it exists to avoid, so it is worth pinning.
+ */
+const runOnSuccess = (meta: Record<string, unknown>, data: unknown, variables: unknown) => {
+  const handler = (queryClient.getMutationCache() as unknown as {
+    config: {
+      onSuccess?: (
+        data: unknown,
+        variables: unknown,
+        context: unknown,
+        mutation: { meta?: Record<string, unknown> },
+      ) => void;
+    };
+  }).config.onSuccess;
+  handler?.(data, variables, undefined, { meta });
+};
+
+describe("MutationCache updates/invalidates", () => {
+  it("writes the mutation response into the seeded key and leaves it fresh", () => {
+    const seededKey = ["train-builder", "composition", "t1"] as const;
+    const siblingKey = ["train-builder", "list", {}] as const;
+
+    queryClient.setQueryData(seededKey, { code: "STALE" });
+    queryClient.setQueryData(siblingKey, { items: [] });
+
+    const response = { code: "FRESH" };
+    runOnSuccess(
+      {
+        updates: (_v: unknown, d: unknown) => [[seededKey, d]],
+        invalidates: () => [["train-builder"]],
+      },
+      response,
+      { id: "t1" },
+    );
+
+    // Seeded key holds the response, and was NOT invalidated back to stale.
+    expect(queryClient.getQueryData(seededKey)).toStrictEqual(response);
+    expect(queryClient.getQueryState(seededKey)?.isInvalidated).toBe(false);
+
+    // Its siblings under the same root still get invalidated.
+    expect(queryClient.getQueryState(siblingKey)?.isInvalidated).toBe(true);
+  });
+
+  it("invalidates everything when a mutation declares no updates", () => {
+    const key = ["train-builder", "composition", "t2"] as const;
+    queryClient.setQueryData(key, { code: "X" });
+
+    runOnSuccess({ invalidates: () => [["train-builder"]] }, undefined, undefined);
+
+    expect(queryClient.getQueryState(key)?.isInvalidated).toBe(true);
+  });
+});
diff --git a/apps/edr-freight-web/backoffice/src/lib/queryClient.ts b/apps/edr-freight-web/backoffice/src/lib/queryClient.ts
index ee072b330..e372e3255 100644
--- a/apps/edr-freight-web/backoffice/src/lib/queryClient.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/queryClient.ts
@@ -1,6 +1,6 @@
 import { MutationCache, QueryClient } from "@tanstack/react-query";
 
-import type { InvalidatesMeta } from "@/utils/endpoint";
+import type { InvalidatesMeta, UpdatesMeta } from "@/utils/endpoint";
 
 /**
  * Single app-wide React Query client (do not nest additional providers).
@@ -14,13 +14,37 @@ import type { InvalidatesMeta } from "@/utils/endpoint";
 export const queryClient = new QueryClient({
   mutationCache: new MutationCache({
     onSuccess: (data, variables, _context, mutation) => {
+      // Seed first: endpoints that return the entity they just changed write it
+      // straight into its cache key, so the screen updates from the response
+      // instead of round-tripping for data it already holds.
+      const updates = mutation.meta?.updates as UpdatesMeta | undefined;
+      const seeded: readonly unknown[][] = [];
+      if (typeof updates === "function") {
+        for (const [queryKey, value] of updates(variables, data)) {
+          queryClient.setQueryData(queryKey, value);
+          seeded.push(queryKey as unknown[]);
+        }
+      }
+
       const invalidates = mutation.meta?.invalidates as
         | InvalidatesMeta
         | undefined;
       if (typeof invalidates !== "function") return;
 
       for (const queryKey of invalidates(variables, data)) {
-        void queryClient.invalidateQueries({ queryKey });
+        void queryClient.invalidateQueries({
+          queryKey,
+          // A seeded key already holds the authoritative value from this very
+          // response — invalidating it would refetch it right back.
+          predicate: seeded.length
+            ? (query) =>
+                !seeded.some(
+                  (key) =>
+                    key.length === query.queryKey.length &&
+                    key.every((part, i) => Object.is(part, query.queryKey[i])),
+                )
+            : undefined,
+        });
       }
     },
     // Mutation failures are surfaced globally by the axios interceptor in
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
index 2444899dd..f0783ab82 100644
--- a/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/BookingRequestDetailPage.tsx
@@ -21,6 +21,7 @@ import {
 } from "lucide-react";
 import {
   ActionIcon,
+  Alert,
   Badge,
   Box,
   Button,
@@ -48,6 +49,7 @@ import { BookingPriorityBadge } from "@/components/bookings/BookingPriorityBadge
 import { NextStepBanner } from "@/components/bookings/NextStepBanner";
 import { SchedulingStatusBadge } from "@/components/trainScheduling/ScheduleStatusBadge";
 import { ConsolidationWaitingBanner } from "@/components/bookings/detail/ConsolidationWaitingBanner";
+import { ConsolidationApprovalCard } from "@/components/bookings/detail/ConsolidationApprovalCard";
 import {
   detailStyles,
   BookingRouteServiceCard,
@@ -460,6 +462,21 @@ export default function BookingRequestDetailPage() {
           <ConsolidationWaitingBanner bookingId={booking.id} />
         )}
 
+        {booking.status === "CONSOLIDATION_APPROVAL_PENDING" && (
+          <Alert
+            color="yellow"
+            radius="md"
+            icon={<Link2 size={18} />}
+            title="Waiting for shared-wagon approval"
+          >
+            <Text size="sm">
+              This booking shares a wagon with another customer&apos;s booking.
+              Both are held here until the pairing is approved — neither reaches
+              Operations before then.
+            </Text>
+          </Alert>
+        )}
+
         <Grid gap="lg">
           {/* LEFT — primary content, split into tabs to keep each view focused.
               The Documents tab is always present, so the tab bar always renders. */}
@@ -534,6 +551,8 @@ export default function BookingRequestDetailPage() {
                     that train and its clock must be readable before the approve
                     button. */}
                 <BookingSchedulingWindowCard booking={booking} />
+                {/* Renders itself only when this booking has a shared wagon. */}
+                <ConsolidationApprovalCard bookingId={booking.id} />
                 <BookingActionsToolbar
                   booking={booking}
                   mutations={mutations}
diff --git a/apps/edr-freight-web/backoffice/src/pages/bookings/ConsolidationApprovalsPage.tsx b/apps/edr-freight-web/backoffice/src/pages/bookings/ConsolidationApprovalsPage.tsx
new file mode 100644
index 000000000..1aebe90c3
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/bookings/ConsolidationApprovalsPage.tsx
@@ -0,0 +1,284 @@
+import { useState } from "react";
+import { Link } from "react-router-dom";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  Alert,
+  Badge,
+  Box,
+  Button,
+  Center,
+  Group,
+  Loader,
+  Modal,
+  Paper,
+  Stack,
+  Text,
+  Textarea,
+  ThemeIcon,
+} from "@mantine/core";
+import { AlertCircle, Check, Clock, Link2, X } from "lucide-react";
+import toast from "react-hot-toast";
+
+import { PageContainer, PageHeader } from "@/components/page";
+import {
+  bookingsService,
+  type ConsolidationApprovalRow,
+} from "@/services/bookings.service";
+import { formatDateTime } from "@/lib/format";
+import { extractErrorMessage } from "@/utils/errorExtractor";
+
+const QUEUE_KEY = ["consolidation-approvals", "queue"];
+
+/**
+ * Review queue for shared-wagon pairings.
+ *
+ * A booking that fills its own wagons goes straight to Operations. A
+ * consolidated one waits here: two customers' cargo rides one physical wagon
+ * under two separate invoices, so a person signs off on the pairing first.
+ * Approving releases BOTH bookings to Operations; rejecting sends BOTH back to
+ * GL with the reason.
+ */
+export default function ConsolidationApprovalsPage() {
+  const qc = useQueryClient();
+  const [decision, setDecision] = useState<{
+    row: ConsolidationApprovalRow;
+    kind: "approve" | "reject";
+  } | null>(null);
+  const [note, setNote] = useState("");
+
+  const {
+    data: rows,
+    isLoading,
+    isError,
+  } = useQuery({
+    queryKey: QUEUE_KEY,
+    queryFn: () => bookingsService.consolidationApprovalQueue(),
+  });
+
+  const close = () => {
+    setDecision(null);
+    setNote("");
+  };
+
+  const decide = useMutation({
+    mutationFn: () => {
+      if (!decision) throw new Error("No pairing selected");
+      return decision.kind === "approve"
+        ? bookingsService.approveConsolidation(decision.row.id, note.trim() || undefined)
+        : bookingsService.rejectConsolidation(decision.row.id, note.trim());
+    },
+    onSuccess: () => {
+      toast.success(
+        decision?.kind === "approve"
+          ? "Shared wagon approved — both bookings sent to Operations"
+          : "Shared wagon rejected — both bookings returned to GL",
+      );
+      void qc.invalidateQueries({ queryKey: QUEUE_KEY });
+      close();
+    },
+    onError: (error) =>
+      toast.error(extractErrorMessage(error, "Could not record the decision")),
+  });
+
+  // A rejection has to tell GL what to fix, so the reason is mandatory there.
+  const confirmDisabled =
+    decide.isPending || (decision?.kind === "reject" && !note.trim());
+
+  return (
+    <PageContainer>
+      <PageHeader
+        title="Shared wagon approvals"
+        subtitle="Two customers' cargo on one wagon — review the pairing before it reaches Operations."
+      />
+
+      {isLoading ? (
+        <Center py={80}>
+          <Loader color="edr-green" />
+        </Center>
+      ) : isError ? (
+        <Alert color="red" radius="md" icon={<AlertCircle size={16} />}>
+          Could not load the approval queue.
+        </Alert>
+      ) : !rows?.length ? (
+        <Alert color="gray" radius="md" icon={<Check size={16} />}>
+          Nothing waiting for approval.
+        </Alert>
+      ) : (
+        <Stack gap="md">
+          {rows.map((row) => (
+            <Paper
+              key={row.id}
+              withBorder
+              radius="lg"
+              p="lg"
+              style={{ borderColor: "#E6ECF2" }}
+            >
+              <Group justify="space-between" align="flex-start" wrap="wrap" gap="md">
+                <Box style={{ minWidth: 0, flex: 1 }}>
+                  <Group gap={8} align="center" mb={10}>
+                    <ThemeIcon variant="light" color="blue" radius="md" size={30}>
+                      <Link2 size={16} />
+                    </ThemeIcon>
+                    <Text fw={800} fz={15}>
+                      Shared wagon
+                    </Text>
+                    <Badge color="yellow" variant="light" radius="sm">
+                      Awaiting approval
+                    </Badge>
+                  </Group>
+
+                  <Group gap="xl" wrap="wrap">
+                    <BookingSide
+                      id={row.bookingId}
+                      reference={row.booking?.reference ?? row.bookingReference}
+                      company={row.booking?.company?.name}
+                    />
+                    <BookingSide
+                      id={row.partnerBookingId}
+                      reference={
+                        row.partnerBooking?.reference ??
+                        row.partnerBookingReference
+                      }
+                      company={row.partnerBooking?.company?.name}
+                    />
+                  </Group>
+
+                  <Group gap={6} mt={12} c="dimmed">
+                    <Clock size={13} />
+                    <Text fz={12}>
+                      Requested {formatDateTime(row.requestedAt)}
+                      {row.scheduledDate
+                        ? ` · ships ${formatDateTime(row.scheduledDate)}`
+                        : ""}
+                    </Text>
+                  </Group>
+                </Box>
+
+                <Group gap="sm">
+                  <Button
+                    color="edr-green"
+                    radius="md"
+                    leftSection={<Check size={15} />}
+                    onClick={() => {
+                      setDecision({ row, kind: "approve" });
+                      setNote("");
+                    }}
+                  >
+                    Approve
+                  </Button>
+                  <Button
+                    color="red"
+                    variant="light"
+                    radius="md"
+                    leftSection={<X size={15} />}
+                    onClick={() => {
+                      setDecision({ row, kind: "reject" });
+                      setNote("");
+                    }}
+                  >
+                    Reject
+                  </Button>
+                </Group>
+              </Group>
+            </Paper>
+          ))}
+        </Stack>
+      )}
+
+      <Modal
+        opened={Boolean(decision)}
+        onClose={() => {
+          if (!decide.isPending) close();
+        }}
+        centered
+        radius="lg"
+        title={
+          <Text fw={800} fz={16}>
+            {decision?.kind === "approve"
+              ? "Approve this shared wagon?"
+              : "Reject this shared wagon?"}
+          </Text>
+        }
+      >
+        <Stack gap="md">
+          <Text fz="sm" c="dimmed">
+            {decision?.kind === "approve"
+              ? "Both bookings leave the gate together and continue to Operations. Each is still invoiced and paid separately."
+              : "Both bookings go back to GL as “changes requested” with your reason. Neither reaches Operations."}
+          </Text>
+
+          <Textarea
+            label={
+              decision?.kind === "approve"
+                ? "Note (optional)"
+                : "Reason (required)"
+            }
+            description={
+              decision?.kind === "approve"
+                ? "Recorded with the approval for the audit trail."
+                : "GL sees this on both bookings — say what has to change."
+            }
+            placeholder={
+              decision?.kind === "approve"
+                ? "Anything worth recording…"
+                : "e.g. the partner's cargo weights are unbalanced for one wagon"
+            }
+            value={note}
+            onChange={(e) => setNote(e.currentTarget.value)}
+            autosize
+            minRows={3}
+          />
+
+          <Group justify="flex-end" gap="sm">
+            <Button
+              variant="default"
+              radius="md"
+              onClick={close}
+              disabled={decide.isPending}
+            >
+              Cancel
+            </Button>
+            <Button
+              color={decision?.kind === "approve" ? "edr-green" : "red"}
+              radius="md"
+              loading={decide.isPending}
+              disabled={confirmDisabled}
+              onClick={() => decide.mutate()}
+            >
+              {decision?.kind === "approve" ? "Approve both" : "Reject both"}
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
+    </PageContainer>
+  );
+}
+
+/** One half of the wagon: its reference (linked) and whose cargo it is. */
+function BookingSide({
+  id,
+  reference,
+  company,
+}: {
+  id: string;
+  reference?: string | null;
+  company?: string | null;
+}) {
+  return (
+    <Box style={{ minWidth: 0 }}>
+      <Text
+        component={Link}
+        to={`/dashboard/booking-requests/${id}`}
+        fz={14}
+        fw={700}
+        c="blue.7"
+        style={{ textDecoration: "none" }}
+      >
+        {reference ?? "—"}
+      </Text>
+      <Text fz={12.5} c="dimmed">
+        {company ?? "—"}
+      </Text>
+    </Box>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
index af648d509..69a4edb4b 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
@@ -29,7 +29,7 @@ import {
   Weight,
   Wrench,
 } from "lucide-react";
-import { useState } from "react";
+import { useCallback, useMemo, useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
 
 import AvailableWagonsPanel from "@/components/trainBuilder/AvailableWagonsPanel";
@@ -98,7 +98,14 @@ export default function TrainBuilderDetailPage() {
   const canDisband = hasPermission(user, FREIGHT_PERMS.trains.disband);
 
   const compositionQuery = useQuery(
-    api.trainBuilder.composition.queryOptions({ input: { id }, enabled: Boolean(id) }),
+    api.trainBuilder.composition.queryOptions({
+      input: { id },
+      enabled: Boolean(id),
+      // Mutations seed this key from their own response (see `seedComposition`
+      // in services/api.ts), so the cached consist is authoritative — the
+      // global staleTime of 0 would otherwise refetch it on every remount.
+      staleTime: 30_000,
+    }),
   );
   const assignWagons = useMutation(api.trainBuilder.assignWagons.mutationOptions());
   const removeWagon = useMutation(api.trainBuilder.removeWagon.mutationOptions());
@@ -111,6 +118,34 @@ export default function TrainBuilderDetailPage() {
   const activate = useMutation(api.trainBuilder.activate.mutationOptions());
 
   const composition = compositionQuery.data;
+
+  // The diagram memoizes off its `locomotives`/`wagons` props; building those
+  // arrays inline in JSX would hand it a new identity on every render and
+  // re-normalize + repaint every car for each keystroke or pending mutation.
+  const diagramLocomotives = useMemo(
+    () =>
+      (composition?.locomotives ?? []).map((loco) => ({
+        code: loco.code,
+        name: loco.name,
+        maxPullWeightTons: loco.maxPullWeightTons,
+      })),
+    [composition?.locomotives],
+  );
+  const diagramWagons = useMemo(
+    () =>
+      (composition?.wagons ?? []).map((wagon, index) => ({
+        sequenceNo: wagon.sequenceNumber ?? index + 1,
+        capacityTons: wagon.wagonType?.capacityTons ?? 0,
+        // No bookings at build time — wagons ride empty until allocation.
+        assignedWeightTons: 0,
+        tareWeightTons: wagon.wagonType?.tareWeightTons ?? 0,
+        wagonTypeCode: wagon.wagonType?.code ?? null,
+        physicalWagonNumber: wagon.wagonNumber,
+        allocations: [],
+      })),
+    [composition?.wagons],
+  );
+
   // Staff identify a train by its operational run numbers, not the internal
   // code — mirrors formatTrainRunLabel on the API, which writes the history note.
   const trainRunLabel =
@@ -130,17 +165,62 @@ export default function TrainBuilderDetailPage() {
     maintenanceWagon.isPending ||
     reorderWagons.isPending;
 
-  const withToast = async (action: () => Promise<unknown>, failTitle: string) => {
-    try {
-      await action();
-    } catch (err) {
-      toast({
-        title: failTitle,
-        description: parseError(err, "Something went wrong"),
-        variant: "destructive",
-      });
-    }
-  };
+  const withToast = useCallback(
+    async (action: () => Promise<unknown>, failTitle: string) => {
+      try {
+        await action();
+      } catch (err) {
+        toast({
+          title: failTitle,
+          description: parseError(err, "Something went wrong"),
+          variant: "destructive",
+        });
+      }
+    },
+    [toast],
+  );
+
+  // Stable handlers: the consist list and wagon picker are memoized, so a new
+  // closure each render would defeat the memo and re-render every wagon row
+  // (and re-mount the drag context) on unrelated state changes.
+  // `trainId` is only absent before the composition loads, and these handlers
+  // are wired to controls that render after that — the guard keeps the promise
+  // rather than leaning on a non-null assertion.
+  const trainId = composition?.id;
+  const handleAssign = useCallback(
+    (wagonIds: string[]) => {
+      if (!trainId) return;
+      void withToast(
+        () => assignWagons.mutateAsync({ id: trainId, wagonIds }),
+        "Could not add wagons",
+      );
+    },
+    [withToast, assignWagons.mutateAsync, trainId],
+  );
+  const handleReorder = useCallback(
+    (wagonIds: string[]) => {
+      if (!trainId) return;
+      void withToast(
+        () => reorderWagons.mutateAsync({ id: trainId, wagonIds }),
+        "Could not reorder wagons",
+      );
+    },
+    [withToast, reorderWagons.mutateAsync, trainId],
+  );
+  const handleRemove = useCallback(
+    (wagonId: string) => {
+      if (!trainId) return;
+      void withToast(
+        () => removeWagon.mutateAsync({ id: trainId, wagonId }),
+        "Could not detach wagon",
+      );
+    },
+    [withToast, removeWagon.mutateAsync, trainId],
+  );
+  const handleMaintenance = useCallback(
+    (wagon: TrainCompositionWagon) => setMaintenanceTarget(wagon),
+    [],
+  );
 
   if (compositionQuery.isLoading) {
     return (
@@ -364,21 +444,8 @@ export default function TrainBuilderDetailPage() {
 
       <Stack gap="sm">
         <TrainCompositionDiagram
-          locomotives={composition.locomotives.map((loco) => ({
-            code: loco.code,
-            name: loco.name,
-            maxPullWeightTons: loco.maxPullWeightTons,
-          }))}
-          wagons={composition.wagons.map((wagon, index) => ({
-            sequenceNo: wagon.sequenceNumber ?? index + 1,
-            capacityTons: wagon.wagonType?.capacityTons ?? 0,
-            // No bookings at build time — wagons ride empty until allocation.
-            assignedWeightTons: 0,
-            tareWeightTons: wagon.wagonType?.tareWeightTons ?? 0,
-            wagonTypeCode: wagon.wagonType?.code ?? null,
-            physicalWagonNumber: wagon.wagonNumber,
-            allocations: [],
-          }))}
+          locomotives={diagramLocomotives}
+          wagons={diagramWagons}
           trainNumber={composition.code}
           totalLengthMeters={totals.totalLengthMeters}
         />
@@ -412,12 +479,7 @@ export default function TrainBuilderDetailPage() {
                   exportTrainNumber={composition.exportTrainNumber}
                   importTrainNumber={composition.importTrainNumber}
                   assigning={assignWagons.isPending}
-                  onAssign={(wagonIds) =>
-                    void withToast(
-                      () => assignWagons.mutateAsync({ id: composition.id, wagonIds }),
-                      "Could not add wagons",
-                    )
-                  }
+                  onAssign={handleAssign}
                 />
               </Stack>
             </Card>
@@ -434,19 +496,9 @@ export default function TrainBuilderDetailPage() {
                 wagons={composition.wagons}
                 editable={composition.editable && canAssign}
                 busy={busy}
-                onReorder={(wagonIds) =>
-                  void withToast(
-                    () => reorderWagons.mutateAsync({ id: composition.id, wagonIds }),
-                    "Could not reorder wagons",
-                  )
-                }
-                onRemove={(wagonId) =>
-                  void withToast(
-                    () => removeWagon.mutateAsync({ id: composition.id, wagonId }),
-                    "Could not detach wagon",
-                  )
-                }
-                onMaintenance={(wagon) => setMaintenanceTarget(wagon)}
+                onReorder={handleReorder}
+                onRemove={handleRemove}
+                onMaintenance={handleMaintenance}
               />
             </Stack>
           </Card>
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 8d61698d1..d02c53f28 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -284,6 +284,32 @@ const TRAIN_BUILDER_INVALIDATIONS: ReadonlyArray<readonly unknown[]> = [
   QUERY_KEYS.FLEET.ROOT,
 ];
 
+/**
+ * Coupling/uncoupling wagons moves wagons between the available pool and one
+ * train — it does not touch locomotives, so those roots stay valid. Trimming
+ * the set keeps a drag-reorder from refetching the whole fleet.
+ */
+const TRAIN_BUILDER_WAGON_INVALIDATIONS: ReadonlyArray<readonly unknown[]> = [
+  QUERY_KEYS.TRAIN_BUILDER.ROOT,
+  QUERY_KEYS.TRAIN_SCHEDULING.ROOT,
+  ["wagons"],
+];
+
+/**
+ * Every train-builder mutation responds with the train's full, fresh
+ * composition — write it straight into the detail cache so the workspace
+ * repaints from the response instead of refetching what it was just handed.
+ */
+const seedComposition = (
+  input: { id: string } | string,
+  data: TrainComposition,
+): ReadonlyArray<readonly [readonly unknown[], unknown]> => [
+  [
+    QUERY_KEYS.TRAIN_BUILDER.composition(typeof input === "string" ? input : input.id),
+    data,
+  ],
+];
+
 export const api = {
   trainScheduling: {
     // ── Queries ────────────────────────────────────────────────────────────
@@ -2070,6 +2096,7 @@ export const api = {
         trainBuilderService.setLocomotives(id, locomotiveIds).then((r) => r.data),
       undefined,
       () => TRAIN_BUILDER_INVALIDATIONS,
+      seedComposition,
     ),
 
     setYard: endpoint<{ id: string; currentYardId: string }, TrainComposition>(
@@ -2079,6 +2106,7 @@ export const api = {
         trainBuilderService.setYard(id, currentYardId).then((r) => r.data),
       undefined,
       () => TRAIN_BUILDER_INVALIDATIONS,
+      seedComposition,
     ),
 
     updateDetails: endpoint<
@@ -2091,6 +2119,7 @@ export const api = {
         trainBuilderService.updateDetails(id, payload).then((r) => r.data),
       undefined,
       () => TRAIN_BUILDER_INVALIDATIONS,
+      seedComposition,
     ),
 
     assignWagons: endpoint<{ id: string; wagonIds: string[] }, TrainComposition>(
@@ -2099,7 +2128,8 @@ export const api = {
       ({ id, wagonIds }) =>
         trainBuilderService.assignWagons(id, wagonIds).then((r) => r.data),
       undefined,
-      () => TRAIN_BUILDER_INVALIDATIONS,
+      () => TRAIN_BUILDER_WAGON_INVALIDATIONS,
+      seedComposition,
     ),
 
     removeWagon: endpoint<{ id: string; wagonId: string }, TrainComposition>(
@@ -2108,7 +2138,8 @@ export const api = {
       ({ id, wagonId }) =>
         trainBuilderService.removeWagon(id, wagonId).then((r) => r.data),
       undefined,
-      () => TRAIN_BUILDER_INVALIDATIONS,
+      () => TRAIN_BUILDER_WAGON_INVALIDATIONS,
+      seedComposition,
     ),
 
     sendWagonToMaintenance: endpoint<
@@ -2120,7 +2151,8 @@ export const api = {
       ({ id, wagonId, note }) =>
         trainBuilderService.sendWagonToMaintenance(id, wagonId, note).then((r) => r.data),
       undefined,
-      () => TRAIN_BUILDER_INVALIDATIONS,
+      () => TRAIN_BUILDER_WAGON_INVALIDATIONS,
+      seedComposition,
     ),
 
     reorderWagons: endpoint<{ id: string; wagonIds: string[] }, TrainComposition>(
@@ -2129,7 +2161,8 @@ export const api = {
       ({ id, wagonIds }) =>
         trainBuilderService.reorderWagons(id, wagonIds).then((r) => r.data),
       undefined,
-      () => TRAIN_BUILDER_INVALIDATIONS,
+      () => TRAIN_BUILDER_WAGON_INVALIDATIONS,
+      seedComposition,
     ),
 
     deactivate: endpoint<string, TrainComposition>(
@@ -2138,6 +2171,7 @@ export const api = {
       (id) => trainBuilderService.deactivate(id).then((r) => r.data),
       undefined,
       () => TRAIN_BUILDER_INVALIDATIONS,
+      seedComposition,
     ),
 
     activate: endpoint<string, TrainComposition>(
@@ -2146,6 +2180,7 @@ export const api = {
       (id) => trainBuilderService.activate(id).then((r) => r.data),
       undefined,
       () => TRAIN_BUILDER_INVALIDATIONS,
+      seedComposition,
     ),
 
     disband: endpoint<string, void>(
diff --git a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
index 9fa24924d..aaab2c3d4 100644
--- a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
@@ -6,6 +6,35 @@ import type { Freight } from "@edr/types";
 
 const B = URL_CONSTANTS.BOOKINGS;
 
+/**
+ * One shared-wagon approval. Covers BOTH bookings on the wagon — the pair is
+ * decided as a unit, never one side at a time.
+ */
+export interface ConsolidationApprovalRow {
+  id: string;
+  bookingId: string;
+  partnerBookingId: string;
+  status: "PENDING" | "APPROVED" | "REJECTED";
+  requestedBy?: string | null;
+  requestedAt: string;
+  decidedBy?: string | null;
+  decidedAt?: string | null;
+  decisionNote?: string | null;
+  scheduledDate?: string | null;
+  bookingReference?: string | null;
+  partnerBookingReference?: string | null;
+  booking?: {
+    id: string;
+    reference?: string;
+    company?: { name?: string } | null;
+  } | null;
+  partnerBooking?: {
+    id: string;
+    reference?: string;
+    company?: { name?: string } | null;
+  } | null;
+}
+
 export interface BookingListFilter {
   status?: string;
   /** Comma-separated statuses for grouped tabs */
@@ -323,6 +352,40 @@ export const bookingsService = {
   cancel: (id: string, reason: string) =>
     postBooking<BookingDetail>(B.CANCEL(id), { reason }),
 
+  // ── Shared-wagon approval gate ──────────────────────────────────────────
+
+  /** Pairings awaiting a decision, oldest first. */
+  consolidationApprovalQueue: async (): Promise<ConsolidationApprovalRow[]> => {
+    const response = await client.get(B.CONSOLIDATION_APPROVAL_QUEUE);
+    return (unwrap(response.data) ?? []) as ConsolidationApprovalRow[];
+  },
+
+  /** Decision history for one booking's shared wagon — who, when, and why. */
+  consolidationApprovalHistory: async (
+    bookingId: string,
+  ): Promise<ConsolidationApprovalRow[]> => {
+    const response = await client.get(
+      B.CONSOLIDATION_APPROVAL_HISTORY(bookingId),
+    );
+    return (unwrap(response.data) ?? []) as ConsolidationApprovalRow[];
+  },
+
+  /** Approve: both bookings leave the gate and continue to Operations. */
+  approveConsolidation: async (approvalId: string, note?: string) => {
+    const response = await client.post(B.CONSOLIDATION_APPROVE(approvalId), {
+      note,
+    });
+    return unwrap(response.data);
+  },
+
+  /** Reject: both bookings go back to GL for changes with the reason. */
+  rejectConsolidation: async (approvalId: string, reason: string) => {
+    const response = await client.post(B.CONSOLIDATION_REJECT(approvalId), {
+      reason,
+    });
+    return unwrap(response.data);
+  },
+
   /**
    * Apply one staff decision to BOTH halves of a consolidated pair. The two
    * bookings share a wagon, so they advance or cancel together — all-or-nothing
diff --git a/apps/edr-freight-web/backoffice/src/utils/endpoint.ts b/apps/edr-freight-web/backoffice/src/utils/endpoint.ts
index 02bc70e85..bc0b01cd7 100644
--- a/apps/edr-freight-web/backoffice/src/utils/endpoint.ts
+++ b/apps/edr-freight-web/backoffice/src/utils/endpoint.ts
@@ -33,6 +33,27 @@ export type InvalidatesMeta = (
   data: unknown,
 ) => ReadonlyArray<readonly unknown[]>;
 
+/**
+ * Cache entries a mutation can write DIRECTLY from its own response, skipping
+ * a refetch. Many endpoints already return the fresh entity they just changed
+ * (e.g. every train-builder mutation returns the whole `TrainComposition`), so
+ * re-fetching that same key is a wasted round-trip and a visible flicker.
+ *
+ * Returned pairs are written with `setQueryData` by the app-wide MutationCache
+ * BEFORE the `invalidates` keys are invalidated, and any key seeded here is
+ * skipped by that invalidation pass — the value just written IS the fresh one.
+ */
+export type UpdatesFn<TInput, TResponse> = (
+  input: TInput,
+  data: TResponse,
+) => ReadonlyArray<readonly [readonly unknown[], unknown]>;
+
+/** Shape stored in `mutation.meta.updates` and consumed by the MutationCache. */
+export type UpdatesMeta = (
+  variables: unknown,
+  data: unknown,
+) => ReadonlyArray<readonly [readonly unknown[], unknown]>;
+
 // ---------------------------------------------------------------------------
 // Endpoint interfaces
 // ---------------------------------------------------------------------------
@@ -67,6 +88,7 @@ export function endpoint<TInput, TResponse>(
   execute: (input: TInput) => Promise<TResponse>,
   queryKeyBuilder?: (input: TInput) => readonly unknown[],
   invalidates?: InvalidatesFn<TInput, TResponse>,
+  updates?: UpdatesFn<TInput, TResponse>,
 ) {
   const buildKey = (input?: TInput): readonly unknown[] => {
     if (queryKeyBuilder && input !== undefined) {
@@ -101,16 +123,30 @@ export function endpoint<TInput, TResponse>(
   const mutationOptions = (
     config?: Omit<UseMutationOptions<TResponse, Error, TInput>, "mutationFn">,
   ): UseMutationOptions<TResponse, Error, TInput> => {
-    const meta = invalidates
-      ? {
-          ...config?.meta,
-          invalidates: ((variables, data) =>
-            invalidates(
-              variables as TInput,
-              data as TResponse,
-            )) satisfies InvalidatesMeta,
-        }
-      : config?.meta;
+    const meta =
+      invalidates || updates
+        ? {
+            ...config?.meta,
+            ...(invalidates
+              ? {
+                  invalidates: ((variables, data) =>
+                    invalidates(
+                      variables as TInput,
+                      data as TResponse,
+                    )) satisfies InvalidatesMeta,
+                }
+              : {}),
+            ...(updates
+              ? {
+                  updates: ((variables, data) =>
+                    updates(
+                      variables as TInput,
+                      data as TResponse,
+                    )) satisfies UpdatesMeta,
+                }
+              : {}),
+          }
+        : config?.meta;
 
     return {
       ...config,

From db64a1878b43c87df2a88899c5366dc0c306d147 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Tue, 18 Aug 2026 13:59:15 +0000
Subject: [PATCH 161/174] feat: implement consolidation approval process for
 shared-wagon bookings

- Add migration for consolidation approvals table and status enum
- Create ConsolidationApprovalService to handle approval logic
- Implement repository for managing consolidation approvals
- Add entity for consolidation approval with necessary fields
- Develop frontend components for displaying and managing consolidation approvals
- Create tests for consolidation approval service to ensure correct behavior
---
 .../consolidation-approval.service.spec.ts    | 23 +++++++++++--------
 .../consolidation-approval.service.ts         | 21 ++++-------------
 .../components/layout/sidebar-sections.tsx    |  9 ++++++++
 3 files changed, 27 insertions(+), 26 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.spec.ts b/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.spec.ts
index d418fbd3c..5f121f630 100644
--- a/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.spec.ts
@@ -11,9 +11,8 @@ import { Booking } from './entities/booking.entity';
  * straight to Operations.
  *
  * The invariants that matter: both halves are held and released TOGETHER (a
- * decision on one side of a shared wagon is meaningless without the other), the
- * requester cannot approve their own pairing, and a decided pairing cannot be
- * decided twice.
+ * decision on one side of a shared wagon is meaningless without the other), and
+ * a decided pairing cannot be decided twice.
  */
 describe('ConsolidationApprovalService', () => {
   const PENDING = {
@@ -154,13 +153,19 @@ describe('ConsolidationApprovalService', () => {
     });
   });
 
-  it('refuses to let the requester approve their own pairing', async () => {
-    const { service, bookingsRepository } = makeService();
+  it('lets the requester approve their own pairing', async () => {
+    // No maker-checker separation: the permission alone decides who may approve,
+    // and the audit trail still records requester and approver separately.
+    const { service, approvals } = makeService();
 
-    await expect(
-      service.approve('ap-1', 'gl-user'),
-    ).rejects.toThrow(/must be approved by someone else/i);
-    expect(bookingsRepository.update).not.toHaveBeenCalled();
+    await service.approve('ap-1', 'gl-user');
+
+    expect(approvals.decide).toHaveBeenCalledWith(
+      'ap-1',
+      ConsolidationApprovalStatus.Approved,
+      'gl-user',
+      undefined,
+    );
   });
 
   it('requires a reason to reject', async () => {
diff --git a/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.ts b/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.ts
index ed8bdfe7a..ab4f4891d 100644
--- a/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/consolidation-approval.service.ts
@@ -37,6 +37,10 @@ export const CONSOLIDATION_APPROVAL_PENDING = "CONSOLIDATION_APPROVAL_PENDING";
  * decision on one is meaningless without the other. Every request is kept,
  * decided or not: the table is the audit trail of who approved which pairing,
  * when, and why.
+ *
+ * No maker-checker separation: whoever holds the approve permission may decide a
+ * pairing, including the GL user who created it. The record of who requested and
+ * who decided is still kept either way.
  */
 @Injectable()
 export class ConsolidationApprovalService {
@@ -114,7 +118,6 @@ export class ConsolidationApprovalService {
     note?: string,
   ): Promise<{ booking: Booking; partner: Booking }> {
     const approval = await this.loadPending(approvalId);
-    this.assertDifferentPerson(approval, decidedBy);
 
     await this.dataSource.transaction(async () => {
       const claimed = await this.approvals.decide(
@@ -166,7 +169,6 @@ export class ConsolidationApprovalService {
       );
     }
     const approval = await this.loadPending(approvalId);
-    this.assertDifferentPerson(approval, decidedBy);
 
     await this.dataSource.transaction(async () => {
       const claimed = await this.approvals.decide(
@@ -237,19 +239,4 @@ export class ConsolidationApprovalService {
     }
     return approval;
   }
-
-  /**
-   * Maker–checker: the point of the gate is a second pair of eyes, so the GL
-   * user who created the pairing cannot also approve it.
-   */
-  private assertDifferentPerson(
-    approval: ConsolidationApproval,
-    decidedBy: string,
-  ): void {
-    if (approval.requestedBy && approval.requestedBy === decidedBy) {
-      throw new BadRequestException(
-        "You created this consolidation — it must be approved by someone else.",
-      );
-    }
-  }
 }
diff --git a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
index ba5637821..ff8fa940f 100644
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -12,6 +12,7 @@ import {
   Image as ImageIcon,
   LayoutDashboard,
   LayoutGrid,
+  Link2,
   MapPin,
   Network,
   Package,
@@ -95,6 +96,14 @@ export const buildSidebarSections = (
           icon: <FileText />,
           permission: FREIGHT_PERMS.bookings.view,
         },
+        // Shared-wagon gate: a consolidated pair waits for a human decision
+        // before either half reaches Operations.
+        {
+          label: "Shared wagon approvals",
+          href: "/dashboard/consolidation-approvals",
+          icon: <Link2 />,
+          permission: FREIGHT_PERMS.bookings.approveConsolidation,
+        },
         {
           label: "Wagon cancellations",
           href: "/dashboard/wagon-cancellations",

From e6e4c07077deffcaad706260a637140e648bac49 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 19 Aug 2026 06:20:47 +0000
Subject: [PATCH 162/174] feat: implement parity checks for 20ft container
 bookings to ensure even numbers

---
 .../bookings/booking-transition.service.ts    | 22 +++++++++++
 .../contracts/contract-booking.service.ts     | 16 ++++++++
 .../contracts/GlCreateBookingForm.tsx         | 38 +++++++++++++++----
 .../new-booking-form/step8-review.tsx         |  7 +++-
 .../contracts/NewShipmentRequestPage.tsx      | 20 +++++-----
 5 files changed, 84 insertions(+), 19 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
index 556ce0e98..41e8fc78b 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
@@ -81,6 +81,28 @@ export class BookingTransitionService {
 
   /** Reject submit when the booking's 20ft containers can't be balanced onto wagons. */
   private async assert20ftPairable(booking: Booking): Promise<void> {
+    // Parity gate. 20ft ride two per wagon, so an odd total leaves one container
+    // that cannot be placed. Consolidation (pairing it with another customer's
+    // odd booking) is built end to end but switched off for now, so an odd total
+    // is rejected here rather than parked for a partner.
+    // containerSize is not always populated (some rows carry only the container
+    // type), so fall back to the type's sizeFt rather than silently skipping
+    // those lines and letting an odd booking through.
+    const ft20Quantity = (booking.bookingContainers ?? [])
+      .filter((bc) =>
+        bc.containerSize
+          ? bc.containerSize.includes("20")
+          : Number(bc.containerType?.sizeFt) === 20,
+      )
+      .reduce((sum, bc) => sum + Number(bc.quantity || 0), 0);
+    if (ft20Quantity % 2 === 1) {
+      throw new BadRequestException(
+        `20ft containers travel two per wagon, so they must be booked in even ` +
+          `numbers. This booking has ${ft20Quantity} — add one more or remove ` +
+          `one (book ${ft20Quantity + 1} or ${ft20Quantity - 1}).`,
+      );
+    }
+
     const violations =
       await this.containerValidationService.validate20ftPairing(booking);
     if (violations.length) {
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
index 9e31aff34..e093bd9bf 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
@@ -2458,6 +2458,22 @@ export class ContractBookingService {
   private async assert20ftPairableAtCreate(
     dto: CreateBookingUnderContractDto,
   ): Promise<void> {
+    // Parity gate. 20ft containers ride two per wagon, so an odd total leaves
+    // one container that cannot be placed. Consolidation (pairing it with
+    // another customer's odd booking) is built end to end but switched off for
+    // now, so an odd total is rejected outright — server-side, because the
+    // frontend block alone is not a guarantee.
+    const ft20Quantity = (dto.containers ?? [])
+      .filter((line) => (line.containerSize ?? '').includes('20'))
+      .reduce((sum, line) => sum + Number(line.quantity || 0), 0);
+    if (ft20Quantity % 2 === 1) {
+      throw new BadRequestException(
+        `20ft containers travel two per wagon, so they must be booked in even ` +
+          `numbers. This booking has ${ft20Quantity} — add one more or remove ` +
+          `one (book ${ft20Quantity + 1} or ${ft20Quantity - 1}).`,
+      );
+    }
+
     const twentyFtUnits = (dto.containers ?? [])
       .filter((line) => (line.containerSize ?? '').includes('20'))
       .flatMap((line, lineIdx) =>
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/GlCreateBookingForm.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/GlCreateBookingForm.tsx
index ca55338cb..06ae71384 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/GlCreateBookingForm.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/GlCreateBookingForm.tsx
@@ -874,9 +874,14 @@ export default function GlCreateBookingForm() {
   // Only a customs (Path B) instance being COMPLETED by GL can use the shared
   // wagon: it is GL, not the customer, who links the two bookings. Anything else
   // keeps the historical hard block on odd 20ft.
-  const oddConsolidationAvailable = Boolean(
-    completeBookingId && isContainer && contract?.customsClearingEnabled,
-  );
+  //
+  // Switched OFF for now: consolidation is built end to end (toggle, parent
+  // picker, split entry, paired pricing, approval gate) but not in use, so an
+  // odd 20ft total is rejected outright instead of offering the shared wagon.
+  // Drop the `false &&` to bring the whole flow back.
+  const oddConsolidationAvailable =
+    false &&
+    Boolean(completeBookingId && isContainer && contract?.customsClearingEnabled);
 
   // Auto-on: entering an odd 20ft total opens the consolidation panel by itself,
   // once. GL can still switch it off — then odd is blocked exactly as before.
@@ -965,10 +970,11 @@ export default function GlCreateBookingForm() {
       !cargoDescriptionError
     : !bulkErrors.quantity && !bulkErrors.hazardous && !bulkErrors.reefer;
 
-  // The unpaired 20ft container is resolved by the shared wagon, so with an
-  // active consolidation an odd total stops being a blocker; without one it
-  // blocks exactly as before.
-  const oddBlocksSubmit = hasOdd20ft && !consolidationActive;
+  // Consolidation (sharing the wagon with another customer's odd booking) is
+  // built but switched off for now, so an odd 20ft total always blocks — the
+  // shared wagon no longer resolves the unpaired container. Flip this back to
+  // `hasOdd20ft && !consolidationActive` to re-enable the shared-wagon path.
+  const oddBlocksSubmit = hasOdd20ft;
 
   // Partner side: a linked partner must be picked, carry an odd 20ft count of
   // its own (odd + odd = even fills the wagon) and have complete unit details.
@@ -2168,7 +2174,23 @@ export default function GlCreateBookingForm() {
         }}
       >
         <Box maw={896} mx="auto">
-          {showErrors && !formValid ? (
+          {/* The review button is disabled on an odd 20ft total, so the click
+              that would surface the errors never lands — state the reason here
+              rather than leaving it in a tooltip nobody hovers. */}
+          {oddBlocksSubmit ? (
+            <Alert
+              color="red"
+              variant="light"
+              radius="md"
+              icon={<AlertCircle size={16} />}
+              mb="sm"
+              title={`Odd number of 20ft containers (${ft20Total})`}
+            >
+              20ft containers travel two per wagon, so they must be booked in
+              even numbers. Add one more 20ft container or remove one — book{" "}
+              {ft20Total + 1} or {ft20Total - 1} instead of {ft20Total}.
+            </Alert>
+          ) : showErrors && !formValid ? (
             <Alert
               color="red"
               variant="light"
diff --git a/apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step8-review.tsx b/apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step8-review.tsx
index cfddea8b3..57521aaf7 100644
--- a/apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step8-review.tsx
+++ b/apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step8-review.tsx
@@ -172,8 +172,11 @@ export function Step8Review({
     values.cargoType === "container"
       ? calcWagons(values.containers ?? [])
       : { hasOddUnit: false, ft20Wagons: 0 };
-  const oddPairsViaCustoms = hasOdd20ft && Boolean(values.customsClearingEnabled);
-  const oddBlocksSubmit = hasOdd20ft && !oddPairsViaCustoms;
+  // Consolidation (pairing an odd 20ft with another customer's odd booking) is
+  // built but switched off for now, so an odd total blocks submit on every path
+  // — customs included.
+  const oddPairsViaCustoms = false;
+  const oddBlocksSubmit = hasOdd20ft;
 
   const isGeneralContract = values.bookingType === "general_contract";
   // Both one-time and general contracts take the bulk amount from the cargo step
diff --git a/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentRequestPage.tsx b/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentRequestPage.tsx
index 69f15e756..b69c83b05 100644
--- a/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentRequestPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/NewShipmentRequestPage.tsx
@@ -106,14 +106,15 @@ export default function NewShipmentRequestPage() {
     contract.cargoScope?.[0];
   const isPerItem = bulkScope?.cargoType?.unitOfMeasure === "PER_ITEM";
 
-  // 20ft containers ride two per wagon. An odd total leaves one unpaired, which
-  // is allowed here: on a customs contract GL completes the booking and links it
-  // to another customer's odd booking so the two share the wagon. The request is
-  // therefore informational only, not a block.
+  // 20ft containers ride two per wagon, so an odd total leaves one unpaired and
+  // the request cannot be planned. Consolidation (pairing the odd container with
+  // another customer's odd booking) is built but switched off for now, so an odd
+  // request is blocked here rather than dead-ending downstream.
   const ft20Requested = isContainer ? Number(qtyBySize["20ft"]) || 0 : 0;
   const hasOdd20ft = ft20Requested % 2 === 1;
 
   const handleSubmit = () => {
+    if (hasOdd20ft) return;
     const dto: Freight.CreateBookingRequestDto = {
       contractRouteId: route?.id,
       scheduledDate: hasCustoms ? undefined : scheduledDate || undefined,
@@ -220,17 +221,17 @@ export default function NewShipmentRequestPage() {
 
             {hasOdd20ft ? (
               <Alert
-                color="blue"
+                color="red"
                 variant="light"
                 radius="md"
                 icon={<AlertCircle size={16} />}
                 title={`Odd number of 20ft containers (${ft20Requested})`}
               >
                 <Text fz={13}>
-                  20ft containers travel two per wagon, so one of yours will
-                  share a wagon with another shipment. Global Logistics arranges
-                  the pairing when completing your booking — you are billed only
-                  for your own containers.
+                  20ft containers travel two per wagon, so they must be requested
+                  in even numbers. Please add one more 20ft container or remove
+                  one (e.g. request {ft20Requested + 1} or {ft20Requested - 1}{" "}
+                  instead of {ft20Requested}).
                 </Text>
               </Alert>
             ) : null}
@@ -281,6 +282,7 @@ export default function NewShipmentRequestPage() {
               leftSection={<Send size={16} />}
               loading={submit.isPending}
               onClick={handleSubmit}
+              disabled={hasOdd20ft}
             >
               Submit shipment request
             </Button>

From cd1e9c38a7457a5dad93c6931c839bd9bcb337d6 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 19 Aug 2026 06:42:19 +0000
Subject: [PATCH 163/174] feat: add new audit endpoints for consolidation
 approvals and invoice management

---
 .../src/modules/audit/audit-endpoints.ts      | 47 +++++++++++++++----
 1 file changed, 38 insertions(+), 9 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts b/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
index d46f63a7d..2bc60d669 100644
--- a/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
+++ b/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
@@ -12,7 +12,7 @@
  * humanized handler name where a route has none.
  *
  * Excludes the AI Assist and Account entities.
- * Generated from the controllers under src/ — 488 endpoints.
+ * Generated from the controllers under src/ — 512 endpoints.
  */
 /** [title, method, entity] for one auditable route. */
 export type AuditEndpointMeta = readonly [title: string, method: string, entity: string];
@@ -83,6 +83,9 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/bookings/:id/wagon-cancellations/preview": ["Preview the fee/credit of a partial wagon cancellation (no writes)", "POST", "Booking"],
   "POST /api/bookings/wagon-cancellations/:cancellationId/rebook": ["Rebook a wagon-cancellation credit: pick a shipment day only — the new booking is created under the contract and marked PAID (freight already paid; contract must still be valid)", "POST", "Booking"],
   "POST /api/bookings/wagon-cancellations/:cancellationId/withdraw": ["Withdraw a fee-pending wagon cancellation (owner, or staff with the void permission)", "POST", "Booking"],
+  "POST /api/bookings/consolidation-approvals/:approvalId/approve": ["Approve a shared wagon: both bookings leave the gate and continue to Operations together.", "POST", "Booking"],
+  "POST /api/bookings/consolidation-approvals/:approvalId/reject": ["Reject a shared wagon: both bookings go back to GL for changes with the reason.", "POST", "Booking"],
+  "POST /api/bookings/:id/paired-decision": ["Apply a staff decision (accept / cancel / operationAccept / requestChanges) to BOTH halves of a consolidated pair, all-or-nothing.", "POST", "Booking"],
 
   // Cargo
   "POST /api/cargoes": ["Create a new cargo", "POST", "Cargo"],
@@ -119,17 +122,13 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/companies/documents/:fileId/request-change": ["Ask the customer to correct one uploaded document", "POST", "Company"],
   "POST /api/companies/fetch-etrade-info": ["Fetch company info from eTrade by TIN", "POST", "Company"],
   "POST /api/companies/identity/fayda/complete": ["Bind a completed Fayda verification to the company's owner or Power of Attorney", "POST", "Company"],
-  "DELETE /api/companies/identity/fayda/poa": ["Remove the company's Power of Attorney — the verified identity, its details and the delegation paper together", "DELETE", "Company"],
-  "DELETE /api/companies/identity/gm": ["Clear the General Manager's identity — the \\\"same as owner\\\" declaration or a verification, and the details either wrote", "DELETE", "Company"],
-  "POST /api/companies/identity/gm/same-as-owner": ["Declare the General Manager is the company's owner, copying the owner's verified identity across", "POST", "Company"],
-  "POST /api/companies/identity/poa/same-as-owner": ["Declare the Power of Attorney is the company's owner, copying the owner's identity across", "POST", "Company"],
-  "DELETE /api/companies/identity/poa/same-as-owner": ["Undo the Power of Attorney \\\"same as owner\\\" declaration and the identity it copied, leaving the representative open to be verified in their own right", "DELETE", "Company"],
   "PATCH /api/companies/onboarding-step": ["Persist the user's current onboarding wizard step", "PATCH", "Company"],
   "POST /api/companies/onboarding/complete": ["Mark the current user's onboarding as complete", "POST", "Company"],
   "POST /api/companies/onboarding/start": ["Begin onboarding: create a draft company + profile + role(s) so later steps can save incrementally", "POST", "Company"],
   "POST /api/companies/poa-delegation": ["Upload the Power of Attorney delegation letter, replacing any existing one", "POST", "Company"],
   "DELETE /api/companies/poa-delegation/:fileId": ["Remove the Power of Attorney delegation letter (staged for review on an approved company)", "DELETE", "Company"],
   "PATCH /api/companies/profile": ["Update profile (flattened settings page)", "PATCH", "Company"],
+  "PATCH /api/companies/identity/poa-declared": ["Answer whether anyone holds power of attorney for this company — the question that decides whose identity is verified.", "PATCH", "Company"],
 
   // Compliance
   "POST /api/compliance": ["Create a compliance record", "POST", "Compliance"],
@@ -222,6 +221,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/gl-exchange/:entityId": ["Share a document with the other GL desk", "POST", "Contract"],
   "PATCH /api/gl-exchange/documents/:documentId": ["Uploader edits a shared document (title, visibility, file)", "PATCH", "Contract"],
   "DELETE /api/gl-exchange/documents/:documentId": ["Uploader removes a shared document", "DELETE", "Contract"],
+  "POST /api/contracts/:id/bookings/:bookingId/complete-consolidated": ["Complete this booking and its chosen shared-wagon partner together (all-or-nothing). Each booking is priced and invoiced separately — only the wagon is shared.", "POST", "Contract"],
 
   // Contract Template
   "POST /api/contract-templates": ["Create a bulk contract template for a (cargo type, customs option) pair", "POST", "Contract Template"],
@@ -253,6 +253,9 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/invoices/:id/eims/register": ["Register the invoice with MoR EIMS. Idempotent — an invoice that already has an IRN is returned unchanged", "POST", "EIMS Invoice"],
   "POST /api/invoices/:id/eims/resolve": ["Resolve an unacknowledged submission: record the IRN confirmed with MoR, or discard it. Clears the system-wide block", "POST", "EIMS Invoice"],
   "POST /api/invoices/:id/eims/verify": ["Verify the invoice's stored IRN against EIMS", "POST", "EIMS Invoice"],
+  "POST /api/invoices/:id/eims/cancel": ["Cancel the invoice", "POST", "EIMS Invoice"],
+  "POST /api/invoices/:id/eims/receipt/sales": ["Register a sales receipt with MoR EIMS against a registered invoice", "POST", "EIMS Invoice"],
+  "POST /api/invoices/:id/eims/receipt/withholding": ["Register a withholding receipt with MoR EIMS against a registered invoice", "POST", "EIMS Invoice"],
 
   // Exchange Setting
   "PATCH /api/exchange-settings": ["Set the USD→ETB fallback by hand (used only while CBE is unreachable)", "PATCH", "Exchange Setting"],
@@ -301,6 +304,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/import-operations/djibouti-incidents": ["Batch 8: report a Djibouti import incident / exception", "POST", "Import Operation"],
   "POST /api/import-operations/empty-container-returns": ["Batch 16: create an empty container return record", "POST", "Import Operation"],
   "POST /api/import-operations/empty-container-returns/:id/status": ["Batch 16: advance empty container return workflow", "POST", "Import Operation"],
+  "POST /api/import-operations/empty-container-returns/load-on-train": ["Load returned empties onto an export train (1×40ft or 2×20ft per wagon)", "POST", "Import Operation"],
 
   // Incident
   "POST /api/incidents": ["Report an incident", "POST", "Incident"],
@@ -336,6 +340,10 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/locomotives/:id/decommission": ["Decommission a locomotive", "POST", "Locomotive"],
   "DELETE /api/locomotives/:id/permanent": ["Permanently delete a locomotive (irreversible; refused if any train references it)", "DELETE", "Locomotive"],
 
+  // Logo Setting
+  "PUT /api/logo-settings": ["Replace the company logo", "PUT", "Logo Setting"],
+  "DELETE /api/logo-settings": ["Clear the company logo (documents fall back to their text mark)", "DELETE", "Logo Setting"],
+
   // Maintenance
   "POST /api/maintenance/costs": ["Record maintenance cost", "POST", "Maintenance"],
   "POST /api/maintenance/intervals": ["Define/adjust a service interval (e.g. oil change every 10,000 km)", "POST", "Maintenance"],
@@ -377,6 +385,10 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/internal/payments/mark-paid": ["Apply a payment.succeeded / payment.failed event from the payment service (idempotent)", "POST", "Payment"],
   "POST /api/payments/initiate": ["Initiate payment for an invoice", "POST", "Payment"],
   "POST /api/payments/redirect-success/:bookingId": ["Success-redirect ack: mark payment processing + invoice PAYMENT_PROCESSING (webhook remains source of truth)", "POST", "Payment"],
+  "POST /api/billing/invoices/:id/memo": ["Issue a credit or debit memo against a registered invoice (MoR DEB/CRE). Filing-equivalent — the auto-submit sweep picks it up like any other issued invoice.", "POST", "Payment"],
+
+  // Payment Setting
+  "PATCH /api/payment-settings/manual": ["Enable or disable manual invoice settlement for ETB and/or USD", "PATCH", "Payment Setting"],
 
   // Priority Config
   "POST /api/priority-configs": ["Create a priority config", "POST", "Priority Config"],
@@ -438,6 +450,20 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "PATCH /api/shipping-lines/:id": ["Update a shipping line", "PATCH", "Shipping Line"],
   "DELETE /api/shipping-lines/:id": ["Soft-delete a shipping line", "DELETE", "Shipping Line"],
 
+  // Shipping Line Booking
+  "POST /api/shipping-line-bookings/initiate": ["Initiate a bare booking (no contract). Starts at AWAITING_DOCUMENTS so the shipping line can upload its documents for Operations to approve.", "POST", "Shipping Line Booking"],
+  "POST /api/shipping-line-bookings/:id/cancel": ["Cancel one of the signed-in shipping line's own bookings. Allowed only before the booking is priced.", "POST", "Shipping Line Booking"],
+  "POST /api/shipping-line-bookings/:id/price-preview": ["Authoritative price quote for the completion payload — same compute as /complete, saved as the booking's breakdown + rate snapshots (refreshed on every re-preview). Persists nothing else.", "POST", "Shipping Line Booking"],
+  "POST /api/shipping-line-bookings/:id/complete": ["Complete an approved (CLEARANCE_READY) booking: cargo + binding shipment day.", "POST", "Shipping Line Booking"],
+
+  // Shipping Line Credit
+  "POST /api/shipping-line-credits/invoice": ["Bill a batch of unbilled credits as one invoice. All credits must belong to the same shipping line.", "POST", "Shipping Line Credit"],
+  "POST /api/shipping-line-credits/:creditId/cancel": ["Write off an unbilled credit. Once billed, cancel the invoice instead.", "POST", "Shipping Line Credit"],
+  "POST /api/shipping-line-credits/invoices/:invoiceId/mark-paid-request": ["Request recording a full offline payment against a credit invoice (awaits chief approval).", "POST", "Shipping Line Credit"],
+  "POST /api/shipping-line-credits/invoices/:invoiceId/cancel-request": ["Request voiding a credit invoice — its credits return to the unbilled pool (awaits chief approval).", "POST", "Shipping Line Credit"],
+  "POST /api/shipping-line-credits/invoice-actions/:approvalId/approve": ["Approve a pending invoice request — executes the offline settlement or the cancellation.", "POST", "Shipping Line Credit"],
+  "POST /api/shipping-line-credits/invoice-actions/:approvalId/reject": ["Reject a pending invoice request — nothing is changed.", "POST", "Shipping Line Credit"],
+
   // Shipping Line Company (carrier with a portal login, registered by staff)
   "POST /api/shipping-line-companies": ["Register a shipping line company and send its activation link", "POST", "Shipping Line Company"],
   "POST /api/shipping-line-companies/:id/resend-activation": ["Resend a shipping line company's activation link", "POST", "Shipping Line Company"],
@@ -445,6 +471,10 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   // Signature
   "PUT /api/me/signature": ["Create or update the reusable saved signature", "PUT", "Signature"],
 
+  // Stamp Setting
+  "PUT /api/stamp-settings": ["Replace the company stamp", "PUT", "Stamp Setting"],
+  "DELETE /api/stamp-settings": ["Clear the company stamp (invoices fall back to the plain seal)", "DELETE", "Stamp Setting"],
+
   // Support Chat
   "POST /api/support/agent/conversations": ["Start chatting with a company (returns the thread if one exists)", "POST", "Support Chat"],
   "POST /api/support/agent/conversations/:id/messages": ["Reply as an agent, optionally with attachments", "POST", "Support Chat"],
@@ -515,9 +545,6 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/train-scheduling/schedules/:id/intercity/:bookingId/unload": ["Confirm intercity cargo unloaded at the booking's destination yard (completes the booking)", "POST", "Train Schedule"],
   "POST /api/train-scheduling/schedules/:id/intercity/accept": ["Accept intercity bookings onto this train (opens their pay window; capacity re-checked per booking)", "POST", "Train Schedule"],
   "PATCH /api/train-scheduling/schedules/:id/loading-status": ["Mark bookings loaded/unloaded on this schedule (any direction, pre-dispatch only)", "PATCH", "Train Schedule"],
-  // NOTE: duplicate route — also declared in modules/train-scheduling/controllers/train-scheduling.controller.ts:798.
-  // Two controllers register this same path; Nest serves whichever module loads first.
-  "POST /api/train-scheduling/schedules/:id/maintenance [modules/train-scheduling/controllers/train-scheduling.controller.ts]": ["Maintenance reschedule: move the train to a new departure with every allocated booking aboard — links, wagons and window settings unchanged", "POST", "Train Schedule"],
   "POST /api/train-scheduling/schedules/:id/pin-wagons": ["Pin physical wagons to train set slots", "POST", "Train Schedule"],
   "POST /api/train-scheduling/schedules/:id/run-allocation": ["Run wagon-level allocation for all eligible linked bookings", "POST", "Train Schedule"],
   "POST /api/train-scheduling/schedules/:id/run-batch": ["Manually run the batch fill for a schedule", "POST", "Train Schedule"],
@@ -527,6 +554,8 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "DELETE /api/train-scheduling/schedules/:id/wagons/:trainSetWagonId": ["Remove an empty wagon slot from a train", "DELETE", "Train Schedule"],
   "POST /api/train-scheduling/schedules/:id/wagons/:wagonId/move-load": ["Move a wagon's whole load to another wagon (empty → move/repin, loaded → swap loads)", "POST", "Train Schedule"],
   "PATCH /api/train-scheduling/schedules/:id/window-rule": ["Override the booking-window rule for one schedule (open/close hour, duration, doc-review, payment, lead days) — only before the window opens", "PATCH", "Train Schedule"],
+  "POST /api/train-scheduling/schedules/:id/merge": ["Merge another train into this schedule: its wagons join this consist, a same-day schedule on it is absorbed, and the emptied train is deactivated", "POST", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/checkpoints/:sequenceNo": ["Edit a logged leg", "PATCH", "Train Schedule"],
 
   // Transit Agent
   "POST /api/transit-agents": ["Create a transit agent", "POST", "Transit Agent"],

From 13f66dfb664f04e23388d1f84816a6df7116eb28 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 19 Aug 2026 08:41:51 +0000
Subject: [PATCH 164/174] changes

---
 .../src/modules/audit/audit-endpoints.ts      |  7 +-
 .../modules/bookings/bookings.controller.ts   |  4 +-
 .../booking-clearance.service.spec.ts         | 28 +++++++
 .../contracts/booking-clearance.service.ts    | 25 ++++++-
 .../contracts/booking-request.repository.ts   |  3 +-
 .../contracts/booking-request.service.ts      | 23 +++++-
 .../modules/contracts/contracts.controller.ts |  4 +-
 .../trains/train-builder.controller.ts        | 21 ++++++
 .../modules/trains/train-builder.service.ts   | 36 +++++++++
 .../src/seed/freight-permissions.registry.ts  |  7 ++
 .../trainBuilder/ConsistWagonList.tsx         | 73 +++++++++++++++++--
 .../backoffice/src/lib/permissions.ts         |  2 +
 .../trainBuilder/TrainBuilderDetailPage.tsx   | 16 ++++
 .../backoffice/src/services/api.ts            | 13 ++++
 .../src/services/trainBuilder.service.ts      |  3 +
 15 files changed, 249 insertions(+), 16 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts b/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
index e28dff30f..a0c82fa4d 100644
--- a/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
+++ b/apps/edr-freight-api/src/modules/audit/audit-endpoints.ts
@@ -12,7 +12,7 @@
  * humanized handler name where a route has none.
  *
  * Excludes the AI Assist and Account entities.
- * Generated from the controllers under src/ — 512 endpoints.
+ * Generated from the controllers under src/ — 517 endpoints.
  */
 /** [title, method, entity] for one auditable route. */
 export type AuditEndpointMeta = readonly [title: string, method: string, entity: string];
@@ -102,6 +102,9 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/cargo-types/:id/move-order": ["Move a cargo type up or down in display order", "POST", "Cargo Type"],
   "POST /api/cargo-types/reorder": ["Bulk reorder cargo types by ID list", "POST", "Cargo Type"],
 
+  // Chat
+  "POST /api/chat/sync": ["Re-run the chat room/membership reconcile immediately (normally nightly)", "POST", "Chat"],
+
   // Company
   "POST /api/companies": ["Create a new company (customer, freight_forwarder, dj_freight_forwarder, transporter)", "POST", "Company"],
   "POST /api/companies/:companyId/documents": ["Upload documents for a company (onboarding)", "POST", "Company"],
@@ -129,6 +132,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "DELETE /api/companies/poa-delegation/:fileId": ["Remove the Power of Attorney delegation letter (staged for review on an approved company)", "DELETE", "Company"],
   "PATCH /api/companies/profile": ["Update profile (flattened settings page)", "PATCH", "Company"],
   "PATCH /api/companies/identity/poa-declared": ["Answer whether anyone holds power of attorney for this company — the question that decides whose identity is verified.", "PATCH", "Company"],
+  "POST /api/companies/onboarding/revert-to-etrade": ["Drop the manual-registration route (co-operative or foreign investment licence): clear the typed registration and reopen onboarding so the TIN is verified against eTrade", "POST", "Company"],
 
   // Compliance
   "POST /api/compliance": ["Create a compliance record", "POST", "Compliance"],
@@ -256,6 +260,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/invoices/:id/eims/cancel": ["Cancel the invoice", "POST", "EIMS Invoice"],
   "POST /api/invoices/:id/eims/receipt/sales": ["Register a sales receipt with MoR EIMS against a registered invoice", "POST", "EIMS Invoice"],
   "POST /api/invoices/:id/eims/receipt/withholding": ["Register a withholding receipt with MoR EIMS against a registered invoice", "POST", "EIMS Invoice"],
+  "POST /api/invoices/eims/bulk-cancel": ["Cancel multiple invoices", "POST", "EIMS Invoice"],
 
   // Exchange Setting
   "PATCH /api/exchange-settings": ["Set the USD→ETB fallback by hand (used only while CBE is unreachable)", "PATCH", "Exchange Setting"],
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts b/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
index 67a0f930d..a2584559e 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
@@ -940,8 +940,8 @@ export class BookingsController {
   @Get('clearance/et-queue')
   @BookingStaff(FREIGHT_PERMS.contracts.clearanceEtActions)
   @ApiOperation({ summary: 'GL ET queue — general customs bookings awaiting ET action' })
-  getBookingEtClearanceQueue() {
-    return this.bookingClearanceService.etQueue();
+  getBookingEtClearanceQueue(@CurrentUser() user: unknown) {
+    return this.bookingClearanceService.etQueue(user);
   }
 
   @Get('clearance/dj-queue')
diff --git a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts
index b29a4cfa5..dd87184fd 100644
--- a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.spec.ts
@@ -32,11 +32,14 @@ function makeService(overrides?: {
   workflowThrows?: boolean;
   /** Resolve the input doc set with no required fields → every doc counts approved. */
   docsApproved?: boolean;
+  /** Yard ids the caller is scoped to; `null` (default) = unrestricted. */
+  yardScope?: string[] | null;
 }) {
   const booking = overrides?.booking ?? generalImportBooking;
   const bookingsRepository = {
     findDocumentReviews: jest.fn().mockResolvedValue([]),
     update: jest.fn().mockResolvedValue(booking),
+    findByStatuses: jest.fn().mockResolvedValue([]),
   };
   const bookingsService = {
     findById: jest.fn().mockResolvedValue(booking),
@@ -111,6 +114,7 @@ function makeService(overrides?: {
         .mockResolvedValue({ id: 'ta-1', name: 'Ahmed Bourhan' }),
     } as never, // transit agents
     { findAll: jest.fn().mockResolvedValue([]) } as never, // contracts repository
+    { getScopedYardIds: jest.fn().mockResolvedValue(overrides?.yardScope ?? null) } as never, // yard scope
   );
 
   return {
@@ -124,6 +128,30 @@ function makeService(overrides?: {
 }
 
 describe('BookingClearanceService', () => {
+  describe('etQueue yard scope', () => {
+    const queueBookings = [
+      { ...generalImportBooking, id: 'b-mojo-out', originYardId: 'mojo', destinationYardId: 'dire' },
+      { ...generalImportBooking, id: 'b-mojo-in', originYardId: 'addis', destinationYardId: 'mojo' },
+      { ...generalImportBooking, id: 'b-elsewhere', originYardId: 'addis', destinationYardId: 'dire' },
+    ] as unknown as Booking[];
+
+    it('keeps only bookings whose origin or destination is in scope', async () => {
+      const { service, bookingsRepository, workflowService } = makeService({ yardScope: ['mojo'] });
+      bookingsRepository.findByStatuses.mockResolvedValue(queueBookings);
+      workflowService.listMilestonesForBooking.mockResolvedValue([{ status: 'PENDING' }]);
+      const rows = await service.etQueue({});
+      expect(rows.map((b) => b.id)).toEqual(['b-mojo-out', 'b-mojo-in']);
+    });
+
+    it('shows everything when the position has no yard mapping', async () => {
+      const { service, bookingsRepository, workflowService } = makeService({ yardScope: null });
+      bookingsRepository.findByStatuses.mockResolvedValue(queueBookings);
+      workflowService.listMilestonesForBooking.mockResolvedValue([{ status: 'PENDING' }]);
+      const rows = await service.etQueue({});
+      expect(rows).toHaveLength(3);
+    });
+  });
+
   describe('adviseDuty', () => {
     it('skips duty milestones when duty is not required', async () => {
       const { service, workflowService, bookingsRepository } = makeService();
diff --git a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
index 43176da75..4b53f4dee 100644
--- a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
@@ -30,6 +30,7 @@ import { ClearanceMilestoneService } from './clearance-milestone.service';
 import { GlOperationsService } from './gl-operations.service';
 import { GlExchangeService } from './gl-exchange.service';
 import { TransitAgentsService } from '../transit-agents/transit-agents.service';
+import { YardScopeService } from '../rule-engine/services/yard-scope.service';
 import { ContractsRepository } from './contracts.repository';
 import { AdviseContractDutyDto } from './dto/phased-clearance.dto';
 import { buildWorkflowFiles, belongsOnDjClearanceQueue, belongsOnEtClearanceQueue, DJ_BOOKING_QUEUE_STATUSES, persistDeclarationUploads, persistDeliveryOrderUploads, persistDraftDeclarationUploads, persistReleaseOrderUploads, persistTransitPermitUploads, PHASED_CUSTOMS_BOOKING_QUEUE_STATUSES } from './phased-clearance.util';
@@ -158,6 +159,7 @@ export class BookingClearanceService {
     private readonly glExchangeService: GlExchangeService,
     private readonly transitAgentsService: TransitAgentsService,
     private readonly contractsRepository: ContractsRepository,
+    private readonly yardScope: YardScopeService,
   ) {}
 
   private async assertPhasedCustoms(booking: Booking): Promise<void> {
@@ -981,7 +983,7 @@ export class BookingClearanceService {
     return this.bookingsService.findById(bookingId);
   }
 
-  async etQueue(): Promise<Booking[]> {
+  async etQueue(user?: unknown): Promise<Booking[]> {
     const candidates = await this.bookingsRepository.findByStatuses([
       ...PHASED_CUSTOMS_BOOKING_QUEUE_STATUSES,
     ]);
@@ -991,7 +993,26 @@ export class BookingClearanceService {
       const milestones = await this.workflowService.listMilestonesForBooking(b.id);
       if (belongsOnEtClearanceQueue(milestones)) filtered.push(b);
     }
-    return this.attachContractSummary(filtered);
+    const rows = await this.attachContractSummary(filtered);
+    return this.narrowToYardScope(rows, user);
+  }
+
+  /**
+   * Keep only bookings whose ORIGIN or DESTINATION yard is one of the caller's
+   * assigned yards (`freight.yard_positions` via the active position). Yards in
+   * the middle of a route do not count. An unmapped position, super admin or
+   * `yards:view_all` holder sees everything (scope resolves to `null`).
+   * Runs after {@link attachContractSummary} so route-fallback yards count too.
+   */
+  private async narrowToYardScope(bookings: Booking[], user: unknown): Promise<Booking[]> {
+    const scope = await this.yardScope.getScopedYardIds(user as never);
+    if (scope === null) return bookings;
+    const inScope = (id: string | null | undefined) => !!id && scope.includes(id);
+    return bookings.filter(
+      (b) =>
+        inScope(b.originYardId ?? b.originYard?.id) ||
+        inScope(b.destinationYardId ?? b.destinationYard?.id),
+    );
   }
 
   /**
diff --git a/apps/edr-freight-api/src/modules/contracts/booking-request.repository.ts b/apps/edr-freight-api/src/modules/contracts/booking-request.repository.ts
index d0705bfb1..d743e3f0d 100644
--- a/apps/edr-freight-api/src/modules/contracts/booking-request.repository.ts
+++ b/apps/edr-freight-api/src/modules/contracts/booking-request.repository.ts
@@ -30,7 +30,8 @@ export class BookingRequestRepository extends BaseRepository<BookingRequest> {
   async findQueue(): Promise<BookingRequest[]> {
     return this.repository.find({
       order: { createdAt: 'DESC' },
-      relations: { contract: { company: true } },
+      // `routes` rides along so the queue can be narrowed to the caller's yards.
+      relations: { contract: { company: true, routes: true } },
     });
   }
 
diff --git a/apps/edr-freight-api/src/modules/contracts/booking-request.service.ts b/apps/edr-freight-api/src/modules/contracts/booking-request.service.ts
index 1ca7cd84f..a2900174a 100644
--- a/apps/edr-freight-api/src/modules/contracts/booking-request.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/booking-request.service.ts
@@ -7,6 +7,7 @@ import {
 } from '@nestjs/common';
 import type { Freight } from '@edr/types';
 
+import { YardScopeService } from '../rule-engine/services/yard-scope.service';
 import { BookingRequestRepository } from './booking-request.repository';
 import { ContractsService } from './contracts.service';
 import { ContractBookingService } from './contract-booking.service';
@@ -28,6 +29,7 @@ export class BookingRequestService {
     private readonly contractsService: ContractsService,
     private readonly contractBookingService: ContractBookingService,
     private readonly notifier: ContractNotifierService,
+    private readonly yardScope: YardScopeService,
   ) {}
 
   /**
@@ -168,8 +170,25 @@ export class BookingRequestService {
     return request;
   }
 
-  queue(): Promise<BookingRequest[]> {
-    return this.repo.findQueue();
+  /**
+   * GL queue narrowed to the caller's yards: a request stays when its route's
+   * ORIGIN or DESTINATION yard is one the caller's active position is mapped to
+   * (unmapped position / super admin → everything). A request with no
+   * resolvable route (no `contractRouteId` on a multi-route contract) has no
+   * yards to judge by and is kept visible.
+   */
+  async queue(user?: unknown): Promise<BookingRequest[]> {
+    const rows = await this.repo.findQueue();
+    const scope = await this.yardScope.getScopedYardIds(user as never);
+    if (scope === null) return rows;
+    return rows.filter((r) => {
+      const routes = r.contract?.routes ?? [];
+      const route =
+        routes.find((x) => x.id === r.contractRouteId) ??
+        (routes.length === 1 ? routes[0] : undefined);
+      if (!route) return true;
+      return scope.includes(route.originYardId) || scope.includes(route.destinationYardId);
+    });
   }
 
   private async findPending(requestId: string): Promise<BookingRequest> {
diff --git a/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts b/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
index 9f602ec21..1dc083934 100644
--- a/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
@@ -123,8 +123,8 @@ export class ContractsController {
   @Get('booking-requests/queue')
   @BookingStaff(FREIGHT_PERMS.contracts.createBooking)
   @ApiOperation({ summary: 'GL queue: shipment requests across contracts (all statuses, newest first)' })
-  bookingRequestQueue() {
-    return this.bookingRequestService.queue();
+  bookingRequestQueue(@CurrentUser() user: AuthUserPayload) {
+    return this.bookingRequestService.queue(user);
   }
 
   @Get('booking-requests/:reqId')
diff --git a/apps/edr-freight-api/src/modules/trains/train-builder.controller.ts b/apps/edr-freight-api/src/modules/trains/train-builder.controller.ts
index 248092f95..277c3be38 100644
--- a/apps/edr-freight-api/src/modules/trains/train-builder.controller.ts
+++ b/apps/edr-freight-api/src/modules/trains/train-builder.controller.ts
@@ -42,6 +42,7 @@ import { TrainBuilderService } from './train-builder.service';
   FREIGHT_PERMS.trains.delete,
   FREIGHT_PERMS.trains.changeLocomotives,
   FREIGHT_PERMS.trains.changeYard,
+  FREIGHT_PERMS.trains.changeWagonYard,
   FREIGHT_PERMS.trains.toggleActive,
   FREIGHT_PERMS.trains.disband,
 ])
@@ -107,6 +108,26 @@ export class TrainBuilderController {
     return this.trainBuilderService.setYard(id, dto.currentYardId);
   }
 
+  @Patch(':id/wagons/:wagonId/yard')
+  @FleetManage(FREIGHT_PERMS.trains.changeWagonYard)
+  @ApiOperation({
+    summary:
+      'Move one coupled wagon to another yard — refused while any live schedule has the wagon allocated',
+  })
+  setWagonYard(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Param('wagonId', ParseUUIDPipe) wagonId: string,
+    @Body() dto: UpdateTrainYardDto,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    return this.trainBuilderService.setWagonYard(
+      id,
+      wagonId,
+      dto.currentYardId,
+      resolveAuthUserId(user),
+    );
+  }
+
   @Post(':id/wagons')
   @FleetManage(FREIGHT_PERMS.trains.assignWagons)
   @ApiOperation({ summary: "Append AVAILABLE wagons from the train's yard to the consist" })
diff --git a/apps/edr-freight-api/src/modules/trains/train-builder.service.ts b/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
index 4b94b2dcb..a27944c3e 100644
--- a/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
+++ b/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
@@ -514,6 +514,42 @@ export class TrainBuilderService {
     return this.getComposition(id);
   }
 
+  /**
+   * Move ONE coupled wagon to another yard (the train and the rest of the
+   * consist stay put). Refused while any live (DRAFT/SCHEDULED/DISPATCHED)
+   * schedule has the wagon allocated to a slot — its standing yard is part of
+   * that schedule's route validation. Ledger row mirrors `setYard`.
+   */
+  async setWagonYard(id: string, wagonId: string, currentYardId: string, userId?: string | null) {
+    await this.dataSource.transaction(async (manager) => {
+      const train = await this.getEditableTrain(manager, id);
+      const wagon = await manager.getRepository(Wagon).findOne({ where: { id: wagonId } });
+      if (!wagon || wagon.trainId !== train.id) {
+        throw new NotFoundException(`Wagon ${wagonId} is not coupled to train ${train.code}`);
+      }
+      if (wagon.currentYardId === currentYardId) return;
+      const yard = await manager.getRepository(Yard).findOne({ where: { id: currentYardId } });
+      if (!yard) throw new NotFoundException(`Yard ${currentYardId} not found`);
+      if (await this.isWagonPinnedToLiveSchedule(manager, wagon.id)) {
+        throw new ConflictException(
+          `Wagon ${wagon.wagonNumber} is allocated to a scheduled or dispatched run; its yard cannot be changed`,
+        );
+      }
+      await manager.getRepository(Wagon).update(wagon.id, { currentYardId: yard.id });
+      await manager.getRepository(WagonMovement).save(
+        manager.getRepository(WagonMovement).create({
+          wagonId: wagon.id,
+          fromYardId: wagon.currentYardId ?? null,
+          toYardId: yard.id,
+          kind: WagonMovementKind.Manual,
+          movedByUserId: userId ?? null,
+          occurredAt: new Date(),
+        }),
+      );
+    });
+    return this.getComposition(id);
+  }
+
   /** Append AVAILABLE, unassigned wagons (any yard) to the consist. */
   async assignWagons(id: string, dto: AssignTrainWagonsDto, userId?: string | null) {
     await this.dataSource.transaction(async (manager) => {
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 1e7a56094..6efa2d78e 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -900,6 +900,11 @@ export const FLEET_RAIL_PERMISSIONS: FreightPermissionSeed[] = [
     "edr_freight_app:trains:disband",
     "Disband train",
   ),
+  perm(
+    "e1c00001-0001-4000-8000-000000000010",
+    "edr_freight_app:trains:change_wagon_yard",
+    "Change yard of a coupled wagon",
+  ),
   perm(
     "e1d00001-0001-4000-8000-000000000001",
     "edr_freight_app:routes:view",
@@ -2007,6 +2012,7 @@ export const FREIGHT_PERMS = {
     assignWagons: "edr_freight_app:trains:assign_wagons",
     changeLocomotives: "edr_freight_app:trains:change_locomotives",
     changeYard: "edr_freight_app:trains:change_yard",
+    changeWagonYard: "edr_freight_app:trains:change_wagon_yard",
     toggleActive: "edr_freight_app:trains:toggle_active",
     disband: "edr_freight_app:trains:disband",
   },
@@ -2343,6 +2349,7 @@ const FLEET_GRANULAR_KEYS: string[] = [
   FREIGHT_PERMS.trains.assignWagons,
   FREIGHT_PERMS.trains.changeLocomotives,
   FREIGHT_PERMS.trains.changeYard,
+  FREIGHT_PERMS.trains.changeWagonYard,
   FREIGHT_PERMS.trains.toggleActive,
   FREIGHT_PERMS.trains.disband,
   FREIGHT_PERMS.routes.view,
diff --git a/apps/edr-freight-web/backoffice/src/components/trainBuilder/ConsistWagonList.tsx b/apps/edr-freight-web/backoffice/src/components/trainBuilder/ConsistWagonList.tsx
index 101176042..d206fca83 100644
--- a/apps/edr-freight-web/backoffice/src/components/trainBuilder/ConsistWagonList.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainBuilder/ConsistWagonList.tsx
@@ -6,11 +6,13 @@ import {
   type DraggableStateSnapshot,
   type DropResult,
 } from "@hello-pangea/dnd";
-import { ActionIcon, Badge, Box, Group, Stack, Text, Tooltip } from "@mantine/core";
+import { ActionIcon, Badge, Box, Group, Menu, Stack, Text, Tooltip } from "@mantine/core";
+import { useQuery } from "@tanstack/react-query";
 import { GripVertical, MapPin, Trash2, Wrench } from "lucide-react";
 import { memo, useCallback, useMemo, type ReactNode } from "react";
 import { createPortal } from "react-dom";
 
+import { api } from "@/services/api";
 import type { TrainCompositionWagon } from "@/services/trainBuilder.service";
 import { wagonTypeColor } from "./trainStatus";
 
@@ -38,6 +40,7 @@ function ConsistWagonList({
   onReorder,
   onRemove,
   onMaintenance,
+  onChangeYard,
   busy = false,
 }: ConsistWagonListProps) {
   const onDragEnd = useCallback((result: DropResult) => {
@@ -107,6 +110,7 @@ function ConsistWagonList({
                     busy={busy}
                     onRemove={onRemove}
                     onMaintenance={onMaintenance}
+                    onChangeYard={onChangeYard}
                   />
                 )}
               </Draggable>
@@ -129,9 +133,68 @@ export interface ConsistWagonListProps {
   onRemove: (wagonId: string) => void;
   /** Detach the wagon and move it to MAINTENANCE status (page confirms first). */
   onMaintenance: (wagon: TrainCompositionWagon) => void;
+  /** Move one wagon to another yard from its yard badge; absent = read-only badge. */
+  onChangeYard?: (wagonId: string, currentYardId: string) => void;
   busy?: boolean;
 }
 
+/** Yard badge that opens a yard picker when `onChange` is provided. */
+function WagonYardBadge({
+  wagon,
+  busy,
+  onChange,
+}: {
+  wagon: TrainCompositionWagon;
+  busy: boolean;
+  onChange?: (wagonId: string, currentYardId: string) => void;
+}) {
+  const label = wagon.currentYard?.label ?? wagon.currentYard?.code ?? "No yard";
+  const yardsQuery = useQuery(
+    api.routes.yards.queryOptions({ staleTime: 5 * 60_000, enabled: Boolean(onChange) }),
+  );
+  if (!onChange) {
+    return wagon.currentYard ? (
+      <Badge variant="outline" color="gray" size="xs" radius="sm" leftSection={<MapPin size={10} />}>
+        {label}
+      </Badge>
+    ) : null;
+  }
+  return (
+    <Menu shadow="md" width={240} withinPortal>
+      <Menu.Target>
+        <Badge
+          component="button"
+          type="button"
+          variant="outline"
+          color="blue"
+          size="xs"
+          radius="sm"
+          leftSection={<MapPin size={10} />}
+          disabled={busy}
+          style={{ cursor: busy ? "default" : "pointer" }}
+          // Stop the drag handle from swallowing the click.
+          onMouseDown={(e) => e.stopPropagation()}
+          aria-label={`Change yard of wagon ${wagon.wagonNumber}`}
+        >
+          {label}
+        </Badge>
+      </Menu.Target>
+      <Menu.Dropdown>
+        <Menu.Label>Move wagon to yard</Menu.Label>
+        {(yardsQuery.data ?? []).map((y) => (
+          <Menu.Item
+            key={y.id}
+            disabled={y.id === wagon.currentYard?.id}
+            onClick={() => onChange(wagon.id, y.id)}
+          >
+            {y.label ?? y.code}
+          </Menu.Item>
+        ))}
+      </Menu.Dropdown>
+    </Menu>
+  );
+}
+
 const WagonRow = memo(function WagonRow({
   wagon,
   index,
@@ -141,6 +204,7 @@ const WagonRow = memo(function WagonRow({
   busy,
   onRemove,
   onMaintenance,
+  onChangeYard,
 }: {
   wagon: TrainCompositionWagon;
   index: number;
@@ -150,6 +214,7 @@ const WagonRow = memo(function WagonRow({
   busy: boolean;
   onRemove: (wagonId: string) => void;
   onMaintenance: (wagon: TrainCompositionWagon) => void;
+  onChangeYard?: (wagonId: string, currentYardId: string) => void;
 }) {
   const color = wagonTypeColor(wagon.wagonType?.code);
 
@@ -195,11 +260,7 @@ const WagonRow = memo(function WagonRow({
                 {wagon.wagonType.code}
               </Badge>
             ) : null}
-            {wagon.currentYard ? (
-              <Badge variant="outline" color="gray" size="xs" radius="sm" leftSection={<MapPin size={10} />}>
-                {wagon.currentYard.label ?? wagon.currentYard.code}
-              </Badge>
-            ) : null}
+            <WagonYardBadge wagon={wagon} busy={busy} onChange={onChangeYard} />
           </Group>
           <Text size="xs" c="dimmed" truncate>
             {wagon.wagonType
diff --git a/apps/edr-freight-web/backoffice/src/lib/permissions.ts b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
index de43dff41..995137999 100644
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -218,6 +218,8 @@ export const FREIGHT_PERMS = {
     /** Train-builder detail Actions menu — each item its own grant. */
     changeLocomotives: "edr_freight_app:trains:change_locomotives",
     changeYard: "edr_freight_app:trains:change_yard",
+    /** Move ONE coupled wagon to another yard from the Wagon order list. */
+    changeWagonYard: "edr_freight_app:trains:change_wagon_yard",
     toggleActive: "edr_freight_app:trains:toggle_active",
     disband: "edr_freight_app:trains:disband",
   },
diff --git a/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
index 69a4edb4b..48799cccf 100644
--- a/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainBuilder/TrainBuilderDetailPage.tsx
@@ -94,6 +94,7 @@ export default function TrainBuilderDetailPage() {
   const canAssign = hasPermission(user, FREIGHT_PERMS.trains.assignWagons);
   const canChangeLocomotives = hasPermission(user, FREIGHT_PERMS.trains.changeLocomotives);
   const canChangeYard = hasPermission(user, FREIGHT_PERMS.trains.changeYard);
+  const canChangeWagonYard = hasPermission(user, FREIGHT_PERMS.trains.changeWagonYard);
   const canToggleActive = hasPermission(user, FREIGHT_PERMS.trains.toggleActive);
   const canDisband = hasPermission(user, FREIGHT_PERMS.trains.disband);
 
@@ -109,6 +110,7 @@ export default function TrainBuilderDetailPage() {
   );
   const assignWagons = useMutation(api.trainBuilder.assignWagons.mutationOptions());
   const removeWagon = useMutation(api.trainBuilder.removeWagon.mutationOptions());
+  const setWagonYard = useMutation(api.trainBuilder.setWagonYard.mutationOptions());
   const maintenanceWagon = useMutation(
     api.trainBuilder.sendWagonToMaintenance.mutationOptions(),
   );
@@ -162,6 +164,7 @@ export default function TrainBuilderDetailPage() {
   const busy =
     assignWagons.isPending ||
     removeWagon.isPending ||
+    setWagonYard.isPending ||
     maintenanceWagon.isPending ||
     reorderWagons.isPending;
 
@@ -217,6 +220,16 @@ export default function TrainBuilderDetailPage() {
     },
     [withToast, removeWagon.mutateAsync, trainId],
   );
+  const handleChangeWagonYard = useCallback(
+    (wagonId: string, currentYardId: string) => {
+      if (!trainId) return;
+      void withToast(
+        () => setWagonYard.mutateAsync({ id: trainId, wagonId, currentYardId }),
+        "Could not change wagon yard",
+      );
+    },
+    [withToast, setWagonYard.mutateAsync, trainId],
+  );
   const handleMaintenance = useCallback(
     (wagon: TrainCompositionWagon) => setMaintenanceTarget(wagon),
     [],
@@ -499,6 +512,9 @@ export default function TrainBuilderDetailPage() {
                 onReorder={handleReorder}
                 onRemove={handleRemove}
                 onMaintenance={handleMaintenance}
+                onChangeYard={
+                  composition.editable && canChangeWagonYard ? handleChangeWagonYard : undefined
+                }
               />
             </Stack>
           </Card>
diff --git a/apps/edr-freight-web/backoffice/src/services/api.ts b/apps/edr-freight-web/backoffice/src/services/api.ts
index 7770dbd96..57d9d56ca 100644
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -2132,6 +2132,19 @@ export const api = {
       seedComposition,
     ),
 
+    setWagonYard: endpoint<
+      { id: string; wagonId: string; currentYardId: string },
+      TrainComposition
+    >(
+      "train-builder",
+      "setWagonYard",
+      ({ id, wagonId, currentYardId }) =>
+        trainBuilderService.setWagonYard(id, wagonId, currentYardId).then((r) => r.data),
+      undefined,
+      () => TRAIN_BUILDER_WAGON_INVALIDATIONS,
+      seedComposition,
+    ),
+
     removeWagon: endpoint<{ id: string; wagonId: string }, TrainComposition>(
       "train-builder",
       "removeWagon",
diff --git a/apps/edr-freight-web/backoffice/src/services/trainBuilder.service.ts b/apps/edr-freight-web/backoffice/src/services/trainBuilder.service.ts
index 5b245305e..3254051d3 100644
--- a/apps/edr-freight-web/backoffice/src/services/trainBuilder.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/trainBuilder.service.ts
@@ -315,6 +315,9 @@ export const trainBuilderService = {
   /** Relocate the train — coupled locomotives and wagons move with it. */
   setYard: (id: string, currentYardId: string) =>
     apiClient.patch<TrainComposition>(`${BASE}/${id}/yard`, { currentYardId }),
+  /** Move one coupled wagon to another yard; the train stays put. */
+  setWagonYard: (id: string, wagonId: string, currentYardId: string) =>
+    apiClient.patch<TrainComposition>(`${BASE}/${id}/wagons/${wagonId}/yard`, { currentYardId }),
   assignWagons: (id: string, wagonIds: string[]) =>
     apiClient.post<TrainComposition>(`${BASE}/${id}/wagons`, { wagonIds }),
   removeWagon: (id: string, wagonId: string) =>

From ad479bdcf2cdd74bdd7cc86590bc820cda4e4aeb Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 19 Aug 2026 10:10:04 +0000
Subject: [PATCH 165/174] issue fix

---
 .../modules/trains/train-builder.service.ts   | 63 ++++++++++++++++---
 1 file changed, 53 insertions(+), 10 deletions(-)

diff --git a/apps/edr-freight-api/src/modules/trains/train-builder.service.ts b/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
index a27944c3e..827596bb7 100644
--- a/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
+++ b/apps/edr-freight-api/src/modules/trains/train-builder.service.ts
@@ -577,11 +577,7 @@ export class TrainBuilderService {
       if (!wagon || wagon.trainId !== train.id) {
         throw new NotFoundException(`Wagon ${wagonId} is not part of this train`);
       }
-      if (await this.isWagonPinnedToLiveSchedule(manager, wagon.id)) {
-        throw new ConflictException(
-          `Wagon ${wagon.wagonNumber} is pinned to an active schedule and cannot be removed`,
-        );
-      }
+      await this.assertDetachableAndReleaseStaleSlots(manager, wagon);
       await manager.getRepository(Wagon).update(wagon.id, {
         trainId: null,
         sequenceNumber: null,
@@ -618,11 +614,7 @@ export class TrainBuilderService {
       if (!wagon || wagon.trainId !== train.id) {
         throw new NotFoundException(`Wagon ${wagonId} is not part of this train`);
       }
-      if (await this.isWagonPinnedToLiveSchedule(manager, wagon.id)) {
-        throw new ConflictException(
-          `Wagon ${wagon.wagonNumber} is pinned to an active schedule and cannot be removed`,
-        );
-      }
+      await this.assertDetachableAndReleaseStaleSlots(manager, wagon);
       const previousStatus = wagon.status;
       const notes = buildMaintenanceNotes(formatTrainRunLabel(train), note);
       await manager.getRepository(Wagon).update(wagon.id, {
@@ -705,6 +697,57 @@ export class TrainBuilderService {
     return rows.length > 0;
   }
 
+  /**
+   * Detach guard for removeWagon / sendWagonToMaintenance. A wagon is truly
+   * pinned only while a live schedule still NEEDS it: a slot carrying booking
+   * allocations, or any slot on a DISPATCHED run. An empty (allocation-free)
+   * slot on a DRAFT/SCHEDULED schedule is a stale reservation — its load was
+   * moved to another wagon (moveWagonLoad keeps the emptied slot) or its
+   * booking left through a path that didn't clean up — and used to pin the
+   * wagon forever. Release those slots here instead of blocking, with the
+   * same recount removeTrainSetWagonSlot does (wagonCount / totalLengthMeters
+   * feed the schedule capacity math).
+   */
+  private async assertDetachableAndReleaseStaleSlots(
+    manager: EntityManager,
+    wagon: Wagon,
+  ): Promise<void> {
+    const rows: { id: string; train_set_id: string; status: string; allocs: string }[] =
+      await manager.query(
+        `SELECT tsw.id, tsw.train_set_id, ts.status,
+                (SELECT count(*)
+                   FROM freight.wagon_booking_allocations a
+                  WHERE a.train_set_wagon_id = tsw.id
+                    AND a.deleted_at IS NULL) AS allocs
+           FROM freight.train_set_wagons tsw
+           JOIN freight.train_schedules ts ON ts.train_set_id = tsw.train_set_id
+          WHERE tsw.physical_wagon_id = $1
+            AND ts.status IN ('DRAFT', 'SCHEDULED', 'DISPATCHED')
+            AND ts.deleted_at IS NULL
+            AND tsw.deleted_at IS NULL`,
+        [wagon.id],
+      );
+    if (!rows.length) return;
+    if (rows.some((r) => Number(r.allocs) > 0 || r.status === 'DISPATCHED')) {
+      throw new ConflictException(
+        `Wagon ${wagon.wagonNumber} is pinned to an active schedule and cannot be removed`,
+      );
+    }
+    await manager.getRepository(TrainSetWagon).delete(rows.map((r) => r.id));
+    for (const trainSetId of [...new Set(rows.map((r) => r.train_set_id))]) {
+      const remaining = await manager.getRepository(TrainSetWagon).find({
+        where: { trainSetId },
+        select: { id: true, lengthMeters: true },
+      });
+      await manager.getRepository(TrainSet).update(trainSetId, {
+        wagonCount: remaining.length,
+        totalLengthMeters: round(
+          remaining.reduce((sum, w) => sum + (Number(w.lengthMeters) || 0), 0),
+        ),
+      });
+    }
+  }
+
   /** Persist a drag-reorder: `wagonIds` is the full consist in its new order. */
   async reorderWagons(id: string, dto: ReorderTrainWagonsDto) {
     await this.dataSource.transaction(async (manager) => {

From 7c566075828fc9a62efbf7f78603b66f3a9fd76a Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 19 Aug 2026 10:11:48 +0000
Subject: [PATCH 166/174] fix(filters): honor a date filter's own operator, not
 always "between"

DateBody always initialized its op state to DEFAULT_OP.date ("between"),
ignoring a def's `operators` restriction. A single-operator exact-date
filter (e.g. `operators: ["before"]`) opened on the range UI with no way
off it, since OperatorSelect hides itself when there's only one choice.
Default to the def's first allowed operator instead.
---
 .../backoffice/src/components/filters/bodies/DateBody.tsx   | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/apps/edr-freight-web/backoffice/src/components/filters/bodies/DateBody.tsx b/apps/edr-freight-web/backoffice/src/components/filters/bodies/DateBody.tsx
index b2032170d..32970abef 100644
--- a/apps/edr-freight-web/backoffice/src/components/filters/bodies/DateBody.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/filters/bodies/DateBody.tsx
@@ -15,7 +15,11 @@ import type { FilterBodyProps } from "./TextBody";
 // i18n.language !== "en" branch here when this body is first wired into a
 // record-management page (Phase 4 of the filter-bar rollout).
 export function DateBody({ def, value, onChange, onClose }: FilterBodyProps<DateFilterDef>) {
-  const [op, setOp] = useState<Operator>(value?.op ?? DEFAULT_OP.date);
+  // DEFAULT_OP.date is always "between" — a def restricted to a single
+  // non-default operator (e.g. `operators: ["before"]` for an exact-date
+  // filter) would otherwise open on the range UI with no way to switch off
+  // it, since OperatorSelect hides itself when there's only one choice.
+  const [op, setOp] = useState<Operator>(value?.op ?? def.operators?.[0] ?? DEFAULT_OP.date);
   // Mantine 9's date inputs speak `YYYY-MM-DD` strings, not Date objects.
   const [from, setFrom] = useState<string | null>(value?.v[0]?.slice(0, 10) ?? null);
   const [to, setTo] = useState<string | null>(value?.v[1]?.slice(0, 10) ?? null);

From 6687def4afc36c36e6c9483e7af982efb297d0f5 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 19 Aug 2026 10:12:03 +0000
Subject: [PATCH 167/174] feat(reports): use the shared FilterBar instead of
 ReportFilters
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Swaps ReportView's bespoke ReportFilters for the same FilterBar/useFilters
combo BookingRequestsPage uses — pills, saved-view-ready state, URL sync.
toFilterDefs() maps the report catalog's own filter vocabulary
(daterange/date/select/multiselect/text) onto FilterDef, matched against
every report definition's backend param handling. The search box only
shows for reports that actually implement `search` server-side, so it's
not a dead control on the rest. ReportFilters.tsx is now dead, removed.
---
 .../src/components/reports/ReportFilters.tsx  | 110 --------------
 .../src/components/reports/ReportView.tsx     | 139 ++++++++++++++----
 2 files changed, 110 insertions(+), 139 deletions(-)
 delete mode 100644 apps/edr-freight-web/backoffice/src/components/reports/ReportFilters.tsx

diff --git a/apps/edr-freight-web/backoffice/src/components/reports/ReportFilters.tsx b/apps/edr-freight-web/backoffice/src/components/reports/ReportFilters.tsx
deleted file mode 100644
index e44e97ec8..000000000
--- a/apps/edr-freight-web/backoffice/src/components/reports/ReportFilters.tsx
+++ /dev/null
@@ -1,110 +0,0 @@
-import { Group, MultiSelect, Select, TextInput } from "@mantine/core";
-import { DateInput, DatePickerInput } from "@mantine/dates";
-import { Search } from "lucide-react";
-
-import { getDateRangePresets } from "@/components/common/dateRangePresets";
-import type { ReportFilterDef } from "@/types/reports";
-
-export interface ReportFilterValues {
-  [param: string]: string | undefined;
-}
-
-interface ReportFiltersProps {
-  filters: ReportFilterDef[];
-  values: ReportFilterValues;
-  onChange: (values: ReportFilterValues) => void;
-}
-
-const toDate = (value: string | undefined): Date | null => (value ? new Date(value) : null);
-const fromDate = (value: string | null): string | undefined => value ?? undefined;
-
-/** Renders one widget per report-declared filter and reports raw param values back up. */
-export function ReportFilters({ filters, values, onChange }: ReportFiltersProps) {
-  if (!filters.length) return null;
-
-  const set = (patch: ReportFilterValues) => onChange({ ...values, ...patch });
-
-  return (
-    <Group gap="sm" wrap="wrap">
-      {filters.map((filter) => {
-        switch (filter.type) {
-          case "daterange":
-            return (
-              <DatePickerInput
-                key={filter.key}
-                type="range"
-                placeholder={filter.label}
-                value={[values[`${filter.key}From`] ?? null, values[`${filter.key}To`] ?? null]}
-                onChange={([from, to]) =>
-                  set({ [`${filter.key}From`]: fromDate(from), [`${filter.key}To`]: fromDate(to) })
-                }
-                presets={getDateRangePresets()}
-                radius="md"
-                size="sm"
-                clearable
-                w={230}
-              />
-            );
-          case "date":
-            return (
-              <DateInput
-                key={filter.key}
-                placeholder={filter.label}
-                value={toDate(values[filter.key])}
-                onChange={(d) => set({ [filter.key]: fromDate(d) })}
-                radius="md"
-                size="sm"
-                clearable
-                w={150}
-              />
-            );
-          case "select":
-            return (
-              <Select
-                key={filter.key}
-                placeholder={filter.label}
-                data={filter.options ?? []}
-                value={values[filter.key] ?? null}
-                onChange={(v) => set({ [filter.key]: v ?? undefined })}
-                radius="md"
-                size="sm"
-                clearable
-                w={170}
-              />
-            );
-          case "multiselect":
-            return (
-              <MultiSelect
-                key={filter.key}
-                placeholder={filter.label}
-                data={filter.options ?? []}
-                value={values[filter.key]?.split(",").filter(Boolean) ?? []}
-                onChange={(v) => set({ [filter.key]: v.length ? v.join(",") : undefined })}
-                radius="md"
-                size="sm"
-                clearable
-                w={200}
-              />
-            );
-          case "text":
-            return (
-              <TextInput
-                key={filter.key}
-                placeholder={filter.label}
-                leftSection={<Search size={16} />}
-                value={values[filter.key] ?? ""}
-                onChange={(e) => set({ [filter.key]: e.target.value || undefined })}
-                radius="md"
-                size="sm"
-                w={220}
-              />
-            );
-          default:
-            return null;
-        }
-      })}
-    </Group>
-  );
-}
-
-export default ReportFilters;
diff --git a/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx b/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx
index 47f5a194a..2634e882c 100644
--- a/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/reports/ReportView.tsx
@@ -1,21 +1,55 @@
 import { ActionIcon, Alert, Box, Card, Group, SegmentedControl, Stack, Text, Tooltip, UnstyledButton } from "@mantine/core";
-import { useDebouncedValue } from "@mantine/hooks";
 import { useQuery } from "@tanstack/react-query";
 import type { Column, SortingState } from "@tanstack/react-table";
 import { ArrowDown, ArrowUp, ArrowUpDown, LayoutGrid, LineChart, RefreshCw } from "lucide-react";
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
 
 import { PageHeader } from "@/components/page";
 import { KpiStrip } from "@/components/page/KpiStrip";
+import { FilterBar, dateRangeParams, useFilters, type FilterDef } from "@/components/filters";
 import { api } from "@/services/api";
-import type { ReportRunParams } from "@/types/reports";
+import type { ReportFilterDef, ReportRunParams } from "@/types/reports";
 import { DataTable, DataTableFooter, usePagination, type ColumnDef } from "@edr/ui-common";
 
 import { ReportChart } from "./ReportChart";
 import { ReportExportButton } from "./ReportExportButton";
-import { ReportFilters, type ReportFilterValues } from "./ReportFilters";
 import { formatKpiValue, formatReportCell } from "./report-format";
 
+/**
+ * Maps the report catalog's own filter vocabulary onto the shared FilterBar's
+ * `FilterDef`. "search" is skipped — FilterBar already renders its own search
+ * box wired to the same `search` param, so keeping the catalog's declared
+ * "search" filter too would just double it up as a redundant pill.
+ */
+function toFilterDefs(filters: ReportFilterDef[]): FilterDef[] {
+  return filters
+    .filter((f) => f.key !== "search")
+    .map((f): FilterDef => {
+      switch (f.type) {
+        case "daterange":
+          return {
+            key: f.key,
+            label: f.label,
+            type: "date",
+            operators: ["between", "before", "after"],
+            toParams: dateRangeParams(`${f.key}From`, `${f.key}To`),
+          };
+        case "date":
+          // Every report's single-date filter (e.g. "as of") is an exact
+          // cutoff, not a range — one fixed operator keeps DateBody on its
+          // single-date UI instead of the range picker.
+          return { key: f.key, label: f.label, type: "date", operators: ["before"] };
+        case "select":
+          return { key: f.key, label: f.label, type: "enum", multiple: false, options: f.options ?? [] };
+        case "multiselect":
+          return { key: f.key, label: f.label, type: "enum", multiple: true, options: f.options ?? [] };
+        default:
+          return { key: f.key, label: f.label, type: "text" };
+      }
+    });
+}
+
 function SortableHeader({ label, column }: { label: string; column: Column<Record<string, unknown>, unknown> }) {
   const sorted = column.getIsSorted();
   const Icon = sorted === "asc" ? ArrowUp : sorted === "desc" ? ArrowDown : ArrowUpDown;
@@ -40,6 +74,8 @@ interface ReportViewProps {
    * arrow) with export/refresh as its actions, instead of inline above the
    * table. Off by default for embedded sections. */
   pageHeader?: boolean;
+  /** Opens on the chart instead of the table — for dashboard tiles. */
+  defaultView?: "table" | "chart";
 }
 
 /**
@@ -47,15 +83,29 @@ interface ReportViewProps {
  * filters, KPI strip, sortable/paginated table or chart, xlsx/pdf export.
  * Adding a report never touches this file.
  */
-export function ReportView({ reportKey, idKeyValue, pageHeader }: ReportViewProps) {
+export function ReportView({ reportKey, idKeyValue, pageHeader, defaultView }: ReportViewProps) {
   const { data: catalog } = useQuery(api.reports.catalog.queryOptions());
   const def = catalog?.find((r) => r.key === reportKey);
 
+  const navigate = useNavigate();
+
   const { pagination, setPagination } = usePagination({ pageSize: 20 });
   const [sorting, setSorting] = useState<SortingState>([]);
-  const [filterValues, setFilterValues] = useState<ReportFilterValues>({});
-  const [debouncedFilters] = useDebouncedValue(filterValues, 300);
-  const [view, setView] = useState<"table" | "chart">("table");
+  const [view, setView] = useState<"table" | "chart">(defaultView ?? "table");
+
+  // FilterBar's own state — reads/writes the URL directly, same as
+  // BookingRequestsPage, so a drilled-into or shared report URL opens
+  // already filtered.
+  const reportFilterDefs = useMemo(() => toFilterDefs(def?.filters ?? []), [def?.filters]);
+  const controls = useFilters(reportFilterDefs);
+  // useFilters also tracks its own page/pageSize — unused here, this report
+  // view paginates itself (and overrides pageSize for the chart view below).
+  const filterParams = useMemo(() => {
+    const rest = { ...controls.params };
+    delete rest.page;
+    delete rest.pageSize;
+    return rest;
+  }, [controls.params]);
 
   // Filters + sort as the user currently has them — independent of the view
   // toggle's paging, so export always matches what's on screen either way.
@@ -64,10 +114,18 @@ export function ReportView({ reportKey, idKeyValue, pageHeader }: ReportViewProp
     return {
       sortBy: sort?.id,
       sortOrder: sort ? (sort.desc ? "DESC" as const : "ASC" as const) : undefined,
-      ...debouncedFilters,
+      ...filterParams,
       ...(def?.idKey && idKeyValue ? { [def.idKey.key]: idKeyValue } : {}),
     };
-  }, [def, sorting, debouncedFilters, idKeyValue]);
+  }, [def, sorting, filterParams, idKeyValue]);
+
+  // A filter change should land back on page 1, same as every other
+  // FilterBar page — but pagination here is local (not URL-driven via
+  // controls.tableProps), so it needs an explicit reset.
+  useEffect(() => {
+    setPagination((prev) => ({ ...prev, pageIndex: 0 }));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [filterParams]);
 
   const runParams: ReportRunParams | undefined = useMemo(() => {
     if (!def) return undefined;
@@ -87,6 +145,30 @@ export function ReportView({ reportKey, idKeyValue, pageHeader }: ReportViewProp
     enabled: Boolean(runParams),
   });
 
+  /**
+   * Row click carries this row's values into the target report as filter
+   * params — the "summary to transaction level" drill-down. Undefined unless
+   * the report declares `drill`, which is what leaves the row unclickable.
+   */
+  const handleRowClick = useMemo(() => {
+    const drill = def?.drill;
+    if (!drill) return undefined;
+    return (row: Record<string, unknown>) => {
+      const params = new URLSearchParams();
+      for (const [column, filterKey] of Object.entries(drill.carry)) {
+        const value = row[column];
+        if (value !== null && value !== undefined && value !== "") {
+          params.set(filterKey, String(value));
+        }
+      }
+      // Carry the filters already applied, so the drill narrows rather than resets.
+      for (const [key, value] of Object.entries(appliedParams)) {
+        if (typeof value === "string" && value && !params.has(key)) params.set(key, value);
+      }
+      navigate(`/dashboard/reports/${drill.to}?${params.toString()}`);
+    };
+  }, [def?.drill, appliedParams, navigate]);
+
   const total = data?.meta.total ?? 0;
   const pageCount = Math.max(1, Math.ceil(total / pagination.pageSize));
 
@@ -167,25 +249,23 @@ export function ReportView({ reportKey, idKeyValue, pageHeader }: ReportViewProp
       <Card p={0}>
         <Stack gap={0}>
           <Box px="md" pt="md" pb="sm">
-            <Group justify="space-between" gap="md" wrap="wrap">
-              <ReportFilters
-                filters={def.filters}
-                values={filterValues}
-                onChange={(v) => {
-                  setFilterValues(v);
-                  setPagination((prev) => ({ ...prev, pageIndex: 0 }));
-                }}
-              />
-              <Group gap="xs">
-                {chartToggle}
-                {pageHeader ? null : (
-                  <>
-                    {exportButton}
-                    {refreshButton}
-                  </>
-                )}
-              </Group>
-            </Group>
+            <FilterBar
+              defs={reportFilterDefs}
+              controls={controls}
+              // Only a handful of reports actually implement the `search`
+              // param server-side (see toFilterDefs) — showing the box on
+              // every report would be a dead control on the rest.
+              showSearch={def.filters.some((f) => f.key === "search")}
+              searchPlaceholder="Search…"
+            >
+              {chartToggle}
+              {pageHeader ? null : (
+                <>
+                  {exportButton}
+                  {refreshButton}
+                </>
+              )}
+            </FilterBar>
           </Box>
 
           {view === "chart" && def.chart ? (
@@ -195,6 +275,7 @@ export function ReportView({ reportKey, idKeyValue, pageHeader }: ReportViewProp
               <DataTable
                 columns={columns}
                 data={data?.items ?? []}
+                onRowClick={handleRowClick}
                 status={isLoading ? "loading" : isError ? "error" : "success"}
                 emptyMessage="No data for the selected filters."
                 error={isError ? { message: "Failed to load report.", onRetry: () => void refetch() } : undefined}

From 54f52f077cc4c9fffc7a9332ee3a8a4bdd29775a Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 19 Aug 2026 10:12:16 +0000
Subject: [PATCH 168/174] fix(page-header): cap title/subtitle width

Title and subtitle grew unbounded, relying only on flex-squeeze from action
buttons to ever truncate. Caps the container at 640px and gives the
subtitle the same truncate treatment the title already had, so a long
page title or description (report descriptions in particular) always
ellipses instead of stretching the header.
---
 .../backoffice/src/components/page/PageHeader.tsx           | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/apps/edr-freight-web/backoffice/src/components/page/PageHeader.tsx b/apps/edr-freight-web/backoffice/src/components/page/PageHeader.tsx
index 803d3f5f7..86beb22fb 100644
--- a/apps/edr-freight-web/backoffice/src/components/page/PageHeader.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/page/PageHeader.tsx
@@ -50,15 +50,15 @@ export function PageHeader({
             </ActionIcon>
           ) : null}
 
-          <div style={{ minWidth: 0 }}>
+          <div style={{ minWidth: 0, maxWidth: 640 }}>
             <Group gap="sm" align="center" wrap="nowrap">
-              <Title order={2} className="truncate">
+              <Title order={2} className="truncate" style={{ minWidth: 0 }}>
                 {title}
               </Title>
               {meta}
             </Group>
             {subtitle ? (
-              <Text c="dimmed" size="sm" mt={4}>
+              <Text c="dimmed" size="sm" mt={4} className="truncate">
                 {subtitle}
               </Text>
             ) : null}

From e964a9b8f47314c1443ec62c82c137f52fdbbc12 Mon Sep 17 00:00:00 2001
From: Nathnael <nathnael@example.com>
Date: Wed, 19 Aug 2026 10:14:46 +0000
Subject: [PATCH 169/174] chore: more reporting

---
 .../payment-classification.report.ts          |  76 +++
 .../receivables-payables.report.ts            | 114 ++++
 .../definitions/revenue-anomalies.report.ts   | 102 ++++
 .../definitions/revenue-by-category.report.ts | 121 ++++
 .../definitions/revenue-by-period.report.ts   | 112 ++++
 .../definitions/revenue-by-route.report.ts    |  79 +++
 .../revenue-reconciliation.report.ts          |  93 +++
 .../revenue-top-customers.report.ts           |  70 +++
 .../revenue-transactions.report.ts            | 131 +++++
 .../src/modules/reports/report.registry.ts    |  18 +
 .../src/modules/reports/report.types.ts       |  20 +
 .../src/modules/reports/reports.controller.ts |  43 +-
 .../reports/revenue-classification.spec.ts    | 102 ++++
 .../modules/reports/revenue-classification.ts | 553 ++++++++++++++++++
 .../src/seed/freight-permissions.registry.ts  |   9 +
 apps/edr-freight-web/backoffice/src/App.tsx   |   4 +-
 .../src/components/reports/ReportSection.tsx  |   6 +-
 .../pages/reports/ReportsIndexRedirect.tsx    |  17 -
 .../src/pages/reports/ReportsLandingPage.tsx  |  51 ++
 .../backoffice/src/types/reports.ts           |  11 +
 20 files changed, 1707 insertions(+), 25 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/payment-classification.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/receivables-payables.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/revenue-anomalies.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/revenue-by-category.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/revenue-by-period.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/revenue-by-route.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/revenue-reconciliation.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/revenue-top-customers.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/definitions/revenue-transactions.report.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/revenue-classification.spec.ts
 create mode 100644 apps/edr-freight-api/src/modules/reports/revenue-classification.ts
 delete mode 100644 apps/edr-freight-web/backoffice/src/pages/reports/ReportsIndexRedirect.tsx
 create mode 100644 apps/edr-freight-web/backoffice/src/pages/reports/ReportsLandingPage.tsx

diff --git a/apps/edr-freight-api/src/modules/reports/definitions/payment-classification.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/payment-classification.report.ts
new file mode 100644
index 000000000..4a77521b5
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/payment-classification.report.ts
@@ -0,0 +1,76 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { ReportContext, ReportDefinition } from '../report.types';
+import {
+  PAID_SHARE,
+  PAYMENT_CLASSES,
+  PAYMENT_CLASS_EXPR,
+  PAYMENT_CLASS_LABEL_EXPR,
+  PERIOD_FILTER,
+  REVENUE_FILTERS,
+  REVENUE_SUM,
+  currencyOf,
+  periodExpr,
+  revenueLedgerQb,
+} from '../revenue-classification';
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const qb = revenueLedgerQb(ctx);
+  const classes = ctx.params.classes as string[] | null;
+  if (classes?.length) {
+    qb.andWhere(`${PAYMENT_CLASS_EXPR} IN (:...classes)`, { classes });
+  }
+  return qb;
+}
+
+export const paymentClassificationReport: ReportDefinition = {
+  key: 'payment-classification',
+  title: 'Payment Classification',
+  description:
+    'What customers actually paid for, per period: rail transport, customs clearance, ' +
+    'first/last mile, overweight, cancellation, demurrage, storage, loading and unloading, ' +
+    'and additional charges. Note there is no dedicated loading/unloading charge type in ' +
+    'the system — handling and double-handling fees stand in for it.',
+  group: 'Finance',
+  filters: [
+    PERIOD_FILTER,
+    ...REVENUE_FILTERS,
+    { key: 'classes', label: 'Payment class', type: 'multiselect', options: PAYMENT_CLASSES },
+  ],
+  columns: [
+    { key: 'period', label: 'Period', type: 'string', sortable: true },
+    { key: 'paymentClass', label: 'Payment class', type: 'string', sortable: true },
+    { key: 'billed', label: 'Billed', type: 'money', sortable: true },
+    { key: 'settled', label: 'Settled', type: 'money', sortable: true },
+    { key: 'outstanding', label: 'Outstanding', type: 'money', sortable: true },
+    { key: 'lines', label: 'Lines', type: 'number' },
+  ],
+  defaultSort: { key: 'billed', dir: 'DESC' },
+  chart: { type: 'bar', x: 'paymentClass', y: ['billed'] },
+  query(ctx) {
+    const period = periodExpr(ctx.params);
+    return baseQuery(ctx)
+      .select(period, 'period')
+      .addSelect(PAYMENT_CLASS_LABEL_EXPR, 'paymentClass')
+      .addSelect('ROUND(SUM(il.amount))::float8', 'billed')
+      .addSelect(`ROUND(SUM(${PAID_SHARE}))::float8`, 'settled')
+      .addSelect(`ROUND(SUM(il.amount) - SUM(${PAID_SHARE}))::float8`, 'outstanding')
+      .addSelect('COUNT(*)::int', 'lines')
+      .groupBy(period)
+      .addGroupBy(PAYMENT_CLASS_EXPR);
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select(REVENUE_SUM, 'billed')
+      .addSelect(`ROUND(COALESCE(SUM(${PAID_SHARE}), 0))::float8`, 'settled')
+      .getRawOne<{ billed: number; settled: number }>();
+    const currency = currencyOf(ctx.params);
+    const billed = Number(row?.billed ?? 0);
+    const settled = Number(row?.settled ?? 0);
+    return [
+      { label: 'Billed', value: billed, unit: currency },
+      { label: 'Settled', value: settled, unit: currency },
+      { label: 'Outstanding', value: Math.round(billed - settled), unit: currency },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/receivables-payables.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/receivables-payables.report.ts
new file mode 100644
index 000000000..018a68faf
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/receivables-payables.report.ts
@@ -0,0 +1,114 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { ReportContext, ReportDefinition, ReportFilterOption } from '../report.types';
+import {
+  PAYER_EXPR,
+  REVENUE_DATE,
+  REVENUE_FILTERS,
+  currencyOf,
+  invoiceLedgerQb,
+} from '../revenue-classification';
+
+export const LEDGER_SIDES: ReportFilterOption[] = [
+  { value: 'RECEIVABLE_CREDIT', label: 'Receivable — credit service (shipping line)' },
+  { value: 'RECEIVABLE_OPEN', label: 'Receivable — open balance' },
+  { value: 'PAYABLE_CANCELLATION', label: 'Payable — cancellation fee' },
+  { value: 'PAYABLE_UNDELIVERED', label: 'Payable — paid but not delivered' },
+  { value: 'SETTLED', label: 'Settled' },
+];
+
+/**
+ * Which side of the ledger an invoice sits on.
+ *
+ * Receivable = EDR delivered and is owed money — the shipping-line credit
+ * arrangement, plus any invoice still carrying a balance.
+ * Payable = the customer paid for something EDR did not deliver, so the money
+ * is a refund liability rather than revenue: cancellation fees, and prepaid
+ * invoices whose booking died.
+ */
+const SIDE_EXPR = `CASE
+  WHEN i.source = 'shipping_line_credit' OR i.type = 'SHIPPING_LINE_CREDIT'
+    THEN 'RECEIVABLE_CREDIT'
+  WHEN i.type = 'WAGON_CANCEL_FEE' THEN 'PAYABLE_CANCELLATION'
+  WHEN i.paid_amount > 0 AND b.status IN ('CANCELLED', 'REJECTED', 'EXPIRED')
+    THEN 'PAYABLE_UNDELIVERED'
+  WHEN i.balance_amount > 0 THEN 'RECEIVABLE_OPEN'
+  ELSE 'SETTLED'
+END`;
+
+const LABELS = new Map(LEDGER_SIDES.map((s) => [s.value, s.label]));
+const SIDE_LABEL_EXPR = `CASE ${SIDE_EXPR}
+  ${[...LABELS].map(([value, label]) => `WHEN '${value}' THEN '${label.replace(/'/g, "''")}'`).join('\n  ')}
+END`;
+
+/** Money at stake on this row: what is owed, or what may have to be given back. */
+const EXPOSURE = `CASE
+  WHEN ${SIDE_EXPR} LIKE 'PAYABLE%' THEN i.paid_amount
+  ELSE i.balance_amount
+END`;
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const qb = invoiceLedgerQb(ctx);
+  const sides = ctx.params.sides as string[] | null;
+  if (sides?.length) qb.andWhere(`${SIDE_EXPR} IN (:...sides)`, { sides });
+  return qb;
+}
+
+export const receivablesPayablesReport: ReportDefinition = {
+  key: 'receivables-payables',
+  title: 'Receivables and Payables',
+  description:
+    'Splits customer money two ways: receivable, where EDR delivered and is owed — ' +
+    'including shipping-line credit services — and payable, where the customer paid but ' +
+    'the service was not delivered, such as cancellation fees and prepayments against ' +
+    'dead bookings. Payable amounts are a refund liability, not revenue.',
+  group: 'Finance',
+  filters: [
+    ...REVENUE_FILTERS.filter((f) => f.key !== 'categories' && f.key !== 'methods'),
+    { key: 'sides', label: 'Ledger side', type: 'multiselect', options: LEDGER_SIDES },
+  ],
+  columns: [
+    { key: 'side', label: 'Ledger side', type: 'string', sortable: true, sortExpr: SIDE_EXPR },
+    { key: 'issuedAt', label: 'Issued', type: 'date', sortable: true, sortExpr: REVENUE_DATE },
+    { key: 'invoiceNumber', label: 'Invoice No.', type: 'string', sortable: true, sortExpr: 'i.invoice_number' },
+    { key: 'bookingRef', label: 'Booking', type: 'string' },
+    { key: 'bookingStatus', label: 'Booking status', type: 'string' },
+    { key: 'customer', label: 'Payer', type: 'string', sortable: true, sortExpr: PAYER_EXPR },
+    { key: 'invoiced', label: 'Invoiced', type: 'money', sortable: true, sortExpr: 'i.total_amount' },
+    { key: 'paid', label: 'Paid', type: 'money', sortable: true, sortExpr: 'i.paid_amount' },
+    { key: 'exposure', label: 'Owed / refundable', type: 'money', sortable: true, sortExpr: EXPOSURE },
+  ],
+  defaultSort: { key: 'exposure', dir: 'DESC' },
+  chart: { type: 'bar', x: 'side', y: ['exposure'] },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select(SIDE_LABEL_EXPR, 'side')
+      .addSelect(`to_char(${REVENUE_DATE}, 'YYYY-MM-DD')`, 'issuedAt')
+      .addSelect('i.invoice_number', 'invoiceNumber')
+      .addSelect("COALESCE(b.reference, '—')", 'bookingRef')
+      .addSelect("COALESCE(b.status, '—')", 'bookingStatus')
+      .addSelect(PAYER_EXPR, 'customer')
+      .addSelect('ROUND(i.total_amount, 2)::float8', 'invoiced')
+      .addSelect('ROUND(i.paid_amount, 2)::float8', 'paid')
+      .addSelect(`ROUND(${EXPOSURE}, 2)::float8`, 'exposure');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select(
+        `ROUND(COALESCE(SUM(${EXPOSURE}) FILTER (WHERE ${SIDE_EXPR} LIKE 'RECEIVABLE%'), 0))::float8`,
+        'receivable',
+      )
+      .addSelect(
+        `ROUND(COALESCE(SUM(${EXPOSURE}) FILTER (WHERE ${SIDE_EXPR} LIKE 'PAYABLE%'), 0))::float8`,
+        'payable',
+      )
+      .addSelect('COUNT(*)::int', 'invoices')
+      .getRawOne<{ receivable: number; payable: number; invoices: number }>();
+    const currency = currencyOf(ctx.params);
+    return [
+      { label: 'Receivable', value: Number(row?.receivable ?? 0), unit: currency },
+      { label: 'Payable', value: Number(row?.payable ?? 0), unit: currency },
+      { label: 'Invoices', value: Number(row?.invoices ?? 0) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/revenue-anomalies.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/revenue-anomalies.report.ts
new file mode 100644
index 000000000..cf2d7735e
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/revenue-anomalies.report.ts
@@ -0,0 +1,102 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { ReportContext, ReportDefinition } from '../report.types';
+import {
+  CATEGORY_LABEL_EXPR,
+  PERIOD_FILTER,
+  REVENUE_CATEGORY_EXPR,
+  REVENUE_FILTERS,
+  growthPctExpr,
+  periodExpr,
+  revenueLedgerQb,
+} from '../revenue-classification';
+
+const REVENUE = 'SUM(il.amount)';
+
+const THRESHOLDS = [
+  { value: '10', label: '±10%' },
+  { value: '25', label: '±25%' },
+  { value: '50', label: '±50%' },
+];
+
+const thresholdOf = (params: Record<string, unknown>): number => {
+  const raw = Number(params.threshold);
+  return THRESHOLDS.some((t) => Number(t.value) === raw) ? raw : 25;
+};
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  return revenueLedgerQb(ctx);
+}
+
+export const revenueAnomaliesReport: ReportDefinition = {
+  key: 'revenue-anomalies',
+  title: 'Revenue Anomalies',
+  description:
+    'Periods where a revenue category moved more than the chosen threshold against the ' +
+    'previous period. Pull-based on purpose: this surfaces the spikes and drops for review ' +
+    'rather than paging anyone, so the thresholds can be tuned against real numbers first.',
+  group: 'Finance',
+  filters: [
+    PERIOD_FILTER,
+    { key: 'threshold', label: 'Threshold', type: 'select', options: THRESHOLDS },
+    ...REVENUE_FILTERS,
+  ],
+  columns: [
+    { key: 'period', label: 'Period', type: 'string', sortable: true },
+    { key: 'category', label: 'Revenue category', type: 'string', sortable: true },
+    { key: 'direction', label: 'Movement', type: 'string' },
+    { key: 'revenue', label: 'Revenue', type: 'money', sortable: true },
+    { key: 'priorRevenue', label: 'Prior period', type: 'money' },
+    { key: 'growthPct', label: 'Change', type: 'percent', sortable: true },
+  ],
+  defaultSort: { key: 'period', dir: 'DESC' },
+  query(ctx) {
+    const period = periodExpr(ctx.params);
+    // ORDER BY the same expression this query GROUPs BY — the to_char label, not
+    // the inner date_trunc. Ordering by the unwrapped timestamp raises
+    // "column i.issued_at must appear in the GROUP BY clause". The label formats
+    // are zero-padded, so lexicographic order is chronological order.
+    const prior = `lag(${REVENUE}) OVER (PARTITION BY ${REVENUE_CATEGORY_EXPR} ORDER BY ${period})`;
+    const change = growthPctExpr(REVENUE, prior);
+
+    const inner = baseQuery(ctx)
+      .select(period, 'period')
+      .addSelect(CATEGORY_LABEL_EXPR, 'category')
+      .addSelect(REVENUE_CATEGORY_EXPR, 'categoryKey')
+      .addSelect(`ROUND(${REVENUE})::float8`, 'revenue')
+      .addSelect(`ROUND(COALESCE(${prior}, 0))::float8`, 'priorRevenue')
+      .addSelect(change, 'growthPct')
+      .addSelect(
+        `CASE WHEN ${REVENUE} >= COALESCE(${prior}, 0) THEN 'Spike' ELSE 'Drop' END`,
+        'direction',
+      )
+      .groupBy(period)
+      .addGroupBy(REVENUE_CATEGORY_EXPR);
+
+    // The threshold cannot live in WHERE or HAVING — both are evaluated before
+    // window functions, and `growthPct` is one. Wrapping is the only place the
+    // comparison is legal. A period with no predecessor yields NULL, and
+    // `ABS(NULL) >= n` is NULL, so those rows drop out without an extra guard.
+    return ctx.ds
+      .createQueryBuilder()
+      .select('a.*')
+      .from(`(${inner.getQuery()})`, 'a')
+      .setParameters(inner.getParameters())
+      .where('ABS(a."growthPct") >= :threshold', { threshold: thresholdOf(ctx.params) });
+  },
+
+  async summary(ctx) {
+    const [sql, params] = revenueAnomaliesReport.query(ctx).getQueryAndParameters();
+    const rows: Array<{ spikes: number; drops: number }> = await ctx.ds.query(
+      `SELECT COUNT(*) FILTER (WHERE a.direction = 'Spike')::int AS spikes,
+              COUNT(*) FILTER (WHERE a.direction = 'Drop')::int  AS drops
+       FROM (${sql}) a`,
+      params,
+    );
+    return [
+      { label: 'Spikes', value: Number(rows[0]?.spikes ?? 0) },
+      { label: 'Drops', value: Number(rows[0]?.drops ?? 0) },
+      { label: 'Threshold', value: thresholdOf(ctx.params), unit: '%' },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/revenue-by-category.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/revenue-by-category.report.ts
new file mode 100644
index 000000000..0a46f15ec
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/revenue-by-category.report.ts
@@ -0,0 +1,121 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { ReportContext, ReportDefinition } from '../report.types';
+import {
+  AVG_PER_UNIT_EXPR,
+  CATEGORY_LABEL_EXPR,
+  CONTAINERS_EXPR,
+  PERIOD_FILTER,
+  REVENUE_CATEGORY_EXPR,
+  REVENUE_FILTERS,
+  REVENUE_SUM,
+  TEU_EXPR,
+  TONS_EXPR,
+  UNIT_LABEL_EXPR,
+  currencyOf,
+  growthPctExpr,
+  periodExpr,
+  revenueLedgerQb,
+} from '../revenue-classification';
+
+const REVENUE = 'SUM(il.amount)';
+
+/**
+ * Previous period's revenue for the same category.
+ *
+ * Postgres evaluates window functions after GROUP BY, so `lag(SUM(...))` is
+ * legal alongside the SUM — no self-join, no CTE. Both the PARTITION BY and the
+ * ORDER BY must repeat their grouping expressions verbatim: ordering by the
+ * inner `date_trunc` when the group key is the `to_char` wrapper fails, and
+ * ordinal shorthand (`ORDER BY 1`) is read as a constant inside a window
+ * clause, silently producing an unordered partition.
+ */
+const priorRevenue = (period: string): string =>
+  `lag(${REVENUE}) OVER (PARTITION BY ${REVENUE_CATEGORY_EXPR} ORDER BY ${period})`;
+
+const growthPct = (period: string): string => growthPctExpr(REVENUE, priorRevenue(period));
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  return revenueLedgerQb(ctx);
+}
+
+export const revenueByCategoryReport: ReportDefinition = {
+  key: 'revenue-by-category',
+  title: 'Revenue by Category',
+  description:
+    'Billed revenue in the twelve rail revenue categories, per period, with volume and ' +
+    'period-over-period growth. Growth compares against the previous period inside the ' +
+    'selected date range, so the earliest period always reads zero. ' +
+    'Multimodal means a named sea carrier is on the booking.',
+  group: 'Finance',
+  filters: [PERIOD_FILTER, ...REVENUE_FILTERS],
+  columns: [
+    { key: 'period', label: 'Period', type: 'string', sortable: true },
+    { key: 'category', label: 'Revenue category', type: 'string', sortable: true },
+    { key: 'revenue', label: 'Revenue', type: 'money', sortable: true },
+    { key: 'priorRevenue', label: 'Prior period', type: 'money' },
+    { key: 'growthPct', label: 'Growth', type: 'percent' },
+    { key: 'tons', label: 'Tonnage', type: 'tons', sortable: true },
+    { key: 'teu', label: 'TEU', type: 'number', sortable: true },
+    { key: 'containers', label: 'Containers', type: 'number' },
+    { key: 'avgPerUnit', label: 'Avg revenue/unit', type: 'money' },
+    { key: 'unit', label: 'Unit', type: 'string' },
+    { key: 'lines', label: 'Lines', type: 'number' },
+  ],
+  defaultSort: { key: 'revenue', dir: 'DESC' },
+  chart: { type: 'bar', x: 'category', y: ['revenue'] },
+  /**
+   * Row click opens the transaction list for exactly this bucket.
+   *
+   * `period` carries into `period_value` (the bucket, e.g. "2026-08"), NOT into
+   * `period` — that filter is the granularity, and handing it a date string
+   * would silently reset it to monthly. The granularity itself rides along
+   * from the filters already applied.
+   *
+   * `categoryKey` rather than `category`: the visible column holds the business
+   * label, and the target filters on the key.
+   */
+  drill: {
+    to: 'revenue-transactions',
+    carry: { period: 'period_value', categoryKey: 'categoryKey' },
+  },
+  query(ctx) {
+    const period = periodExpr(ctx.params);
+    return baseQuery(ctx)
+      .select(period, 'period')
+      .addSelect(CATEGORY_LABEL_EXPR, 'category')
+      .addSelect(REVENUE_CATEGORY_EXPR, 'categoryKey')
+      .addSelect(`ROUND(${REVENUE})::float8`, 'revenue')
+      .addSelect(`ROUND(COALESCE(${priorRevenue(period)}, 0))::float8`, 'priorRevenue')
+      .addSelect(`COALESCE(${growthPct(period)}, 0)`, 'growthPct')
+      .addSelect(`ROUND(COALESCE(${TONS_EXPR}, 0), 1)::float8`, 'tons')
+      .addSelect(`ROUND(COALESCE(${TEU_EXPR}, 0))::int`, 'teu')
+      .addSelect(`ROUND(COALESCE(${CONTAINERS_EXPR}, 0))::int`, 'containers')
+      .addSelect(`COALESCE(${AVG_PER_UNIT_EXPR}, 0)`, 'avgPerUnit')
+      .addSelect(UNIT_LABEL_EXPR, 'unit')
+      .addSelect('COUNT(*)::int', 'lines')
+      .groupBy(period)
+      .addGroupBy(REVENUE_CATEGORY_EXPR);
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select(REVENUE_SUM, 'revenue')
+      .addSelect(
+        `ROUND(COALESCE(SUM(il.amount) FILTER (WHERE ${REVENUE_CATEGORY_EXPR} = 'UNCLASSIFIED'), 0))::float8`,
+        'unclassified',
+      )
+      .addSelect(`COUNT(DISTINCT ${REVENUE_CATEGORY_EXPR})::int`, 'categories')
+      // Invoice-level balance is deliberately NOT summed here — the ledger is
+      // at line grain, so a 3-line invoice would count its balance three times.
+      // Outstanding lives on `revenue-reconciliation`, at invoice grain.
+      .getRawOne<{ revenue: number; unclassified: number; categories: number }>();
+
+    const currency = currencyOf(ctx.params);
+    return [
+      { label: 'Total revenue', value: Number(row?.revenue ?? 0), unit: currency },
+      { label: 'Categories', value: Number(row?.categories ?? 0) },
+      // Always shown, even at zero: an audit report must never quietly drop money.
+      { label: 'Unclassified', value: Number(row?.unclassified ?? 0), unit: currency },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/revenue-by-period.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/revenue-by-period.report.ts
new file mode 100644
index 000000000..541b9ef01
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/revenue-by-period.report.ts
@@ -0,0 +1,112 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { ReportContext, ReportDefinition } from '../report.types';
+import {
+  PERIOD_FILTER,
+  REVENUE_CATEGORY_EXPR,
+  REVENUE_FILTERS,
+  REVENUE_SUM,
+  TEU_EXPR,
+  TONS_EXPR,
+  currencyOf,
+  growthPctExpr,
+  nextPeriodOrdinalExpr,
+  periodExpr,
+  periodOrdinalExpr,
+  periodTruncExpr,
+  revenueLedgerQb,
+} from '../revenue-classification';
+
+const REVENUE = 'SUM(il.amount)';
+
+/**
+ * A six-period rolling linear trend, projected one period ahead.
+ *
+ * `regr_slope`/`regr_intercept` are Postgres built-ins, so this needs no
+ * dependency and no model store. It is a trend line, not a forecast model: no
+ * seasonality, no confidence interval, and meaningless on fewer than about
+ * four points — hence the row-count guard, which returns NULL rather than a
+ * confident-looking number drawn through two dots.
+ *
+ * The x variable is the period's epoch seconds, not `row_number()`: Postgres
+ * rejects a window function nested inside another window function's arguments
+ * ("window function calls cannot be nested"), and the timestamp is already a
+ * monotonic ordinal.
+ *
+ * ponytail: linear trend only. A seasonal model (Holt-Winters/ARIMA) means a
+ * stats dependency, a training story and an owner for model quality — do that
+ * only if the business names a seasonality requirement.
+ */
+const forecastNext = (params: Record<string, unknown>): string => {
+  const window = `OVER (ORDER BY ${periodTruncExpr(params)} ROWS BETWEEN 5 PRECEDING AND CURRENT ROW)`;
+  const x = periodOrdinalExpr(params);
+  return `CASE WHEN count(*) ${window} >= 4 THEN GREATEST(0, ROUND(
+    (regr_intercept(${REVENUE}, ${x}) ${window})
+    + (regr_slope(${REVENUE}, ${x}) ${window}) * ${nextPeriodOrdinalExpr(params)}
+  ))::float8 END`;
+};
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  return revenueLedgerQb(ctx);
+}
+
+export const revenueByPeriodReport: ReportDefinition = {
+  key: 'revenue-by-period',
+  title: 'Revenue Trend',
+  description:
+    'Total billed revenue per period with period-over-period growth and a rolling ' +
+    'six-period linear projection. The projection is a trend line, not a seasonal ' +
+    'forecast, and is blank until six periods of history exist.',
+  group: 'Finance',
+  filters: [PERIOD_FILTER, ...REVENUE_FILTERS],
+  columns: [
+    { key: 'period', label: 'Period', type: 'string', sortable: true },
+    { key: 'revenue', label: 'Revenue', type: 'money', sortable: true },
+    { key: 'priorRevenue', label: 'Prior period', type: 'money' },
+    { key: 'growthPct', label: 'Growth', type: 'percent' },
+    { key: 'forecastNext', label: 'Projected next', type: 'money' },
+    { key: 'categories', label: 'Categories', type: 'number' },
+    { key: 'tons', label: 'Tonnage', type: 'tons' },
+    { key: 'teu', label: 'TEU', type: 'number' },
+    { key: 'lines', label: 'Lines', type: 'number' },
+  ],
+  defaultSort: { key: 'period', dir: 'ASC' },
+  chart: { type: 'line', x: 'period', y: ['revenue', 'forecastNext'] },
+  drill: { to: 'revenue-transactions', carry: { period: 'period_value' } },
+  query(ctx) {
+    const period = periodExpr(ctx.params);
+    const trunc = periodTruncExpr(ctx.params);
+    const prior = `lag(${REVENUE}) OVER (ORDER BY ${trunc})`;
+    return baseQuery(ctx)
+      .select(period, 'period')
+      .addSelect(`ROUND(${REVENUE})::float8`, 'revenue')
+      .addSelect(`ROUND(COALESCE(${prior}, 0))::float8`, 'priorRevenue')
+      .addSelect(`COALESCE(${growthPctExpr(REVENUE, prior)}, 0)`, 'growthPct')
+      .addSelect(forecastNext(ctx.params), 'forecastNext')
+      .addSelect(`COUNT(DISTINCT ${REVENUE_CATEGORY_EXPR})::int`, 'categories')
+      .addSelect(`ROUND(COALESCE(${TONS_EXPR}, 0), 1)::float8`, 'tons')
+      .addSelect(`ROUND(COALESCE(${TEU_EXPR}, 0))::int`, 'teu')
+      .addSelect('COUNT(*)::int', 'lines')
+      // Grouped by the period's start timestamp, so the ordering the windows
+      // above use is a grouping key rather than a bare column reference.
+      .groupBy(trunc);
+  },
+
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select(REVENUE_SUM, 'revenue')
+      .addSelect(`COUNT(DISTINCT ${periodTruncExpr(ctx.params)})::int`, 'periods')
+      .getRawOne<{ revenue: number; periods: number }>();
+    const periods = Number(row?.periods ?? 0);
+    const revenue = Number(row?.revenue ?? 0);
+    return [
+      { label: 'Total revenue', value: revenue, unit: currencyOf(ctx.params) },
+      { label: 'Periods', value: periods },
+      {
+        label: 'Average per period',
+        value: periods ? Math.round(revenue / periods) : 0,
+        unit: currencyOf(ctx.params),
+      },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/revenue-by-route.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/revenue-by-route.report.ts
new file mode 100644
index 000000000..3d8a9370a
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/revenue-by-route.report.ts
@@ -0,0 +1,79 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { ReportContext, ReportDefinition } from '../report.types';
+import {
+  AVG_PER_UNIT_EXPR,
+  CATEGORY_LABEL_EXPR,
+  PERIOD_FILTER,
+  REVENUE_CATEGORY_EXPR,
+  REVENUE_FILTERS,
+  REVENUE_SUM,
+  TEU_EXPR,
+  TONS_EXPR,
+  UNIT_LABEL_EXPR,
+  currencyOf,
+  revenueLedgerQb,
+} from '../revenue-classification';
+
+/**
+ * There is no corridor entity in the schema — a corridor IS an
+ * (origin_yard, destination_yard) pair, which is exactly how rates are scoped.
+ */
+const CORRIDOR = `COALESCE(oy.label, 'Unknown') || ' → ' || COALESCE(dy.label, 'Unknown')`;
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  return revenueLedgerQb(ctx);
+}
+
+export const revenueByRouteReport: ReportDefinition = {
+  key: 'revenue-by-route',
+  title: 'Revenue by Route',
+  description:
+    'Billed revenue per corridor and revenue category. A corridor is an ' +
+    'origin/destination station pair — the schema has no separate corridor entity.',
+  group: 'Finance',
+  filters: [PERIOD_FILTER, ...REVENUE_FILTERS],
+  columns: [
+    { key: 'corridor', label: 'Corridor', type: 'string', sortable: true, sortExpr: CORRIDOR },
+    { key: 'origin', label: 'Origin', type: 'string' },
+    { key: 'destination', label: 'Destination', type: 'string' },
+    { key: 'category', label: 'Revenue category', type: 'string', sortable: true },
+    { key: 'revenue', label: 'Revenue', type: 'money', sortable: true },
+    { key: 'tons', label: 'Tonnage', type: 'tons', sortable: true },
+    { key: 'teu', label: 'TEU', type: 'number', sortable: true },
+    { key: 'avgPerUnit', label: 'Avg revenue/unit', type: 'money' },
+    { key: 'unit', label: 'Unit', type: 'string' },
+    { key: 'lines', label: 'Lines', type: 'number' },
+  ],
+  defaultSort: { key: 'revenue', dir: 'DESC' },
+  chart: { type: 'bar', x: 'corridor', y: ['revenue'] },
+  drill: { to: 'revenue-transactions', carry: { categoryKey: 'categoryKey' } },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select(CORRIDOR, 'corridor')
+      .addSelect("COALESCE(oy.label, 'Unknown')", 'origin')
+      .addSelect("COALESCE(dy.label, 'Unknown')", 'destination')
+      .addSelect(CATEGORY_LABEL_EXPR, 'category')
+      .addSelect(REVENUE_CATEGORY_EXPR, 'categoryKey')
+      .addSelect('ROUND(SUM(il.amount))::float8', 'revenue')
+      .addSelect(`ROUND(COALESCE(${TONS_EXPR}, 0), 1)::float8`, 'tons')
+      .addSelect(`ROUND(COALESCE(${TEU_EXPR}, 0))::int`, 'teu')
+      .addSelect(`COALESCE(${AVG_PER_UNIT_EXPR}, 0)`, 'avgPerUnit')
+      .addSelect(UNIT_LABEL_EXPR, 'unit')
+      .addSelect('COUNT(*)::int', 'lines')
+      .groupBy(CORRIDOR)
+      .addGroupBy('oy.label')
+      .addGroupBy('dy.label')
+      .addGroupBy(REVENUE_CATEGORY_EXPR);
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select(REVENUE_SUM, 'revenue')
+      .addSelect(`COUNT(DISTINCT ${CORRIDOR})::int`, 'corridors')
+      .getRawOne<{ revenue: number; corridors: number }>();
+    return [
+      { label: 'Corridors', value: Number(row?.corridors ?? 0) },
+      { label: 'Total revenue', value: Number(row?.revenue ?? 0), unit: currencyOf(ctx.params) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/revenue-reconciliation.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/revenue-reconciliation.report.ts
new file mode 100644
index 000000000..73de3f505
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/revenue-reconciliation.report.ts
@@ -0,0 +1,93 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { ReportContext, ReportDefinition } from '../report.types';
+import {
+  GATEWAY_PAID,
+  PAYER_EXPR,
+  REVENUE_DATE,
+  REVENUE_FILTERS,
+  currencyOf,
+  invoiceLedgerQb,
+} from '../revenue-classification';
+
+/**
+ * The gap between what the invoice says was paid and what the payment gateway
+ * recorded. Non-zero is not automatically wrong — manual settlements are real
+ * — but every one of them should be explainable, which is the point.
+ */
+const VARIANCE = `i.paid_amount - ${GATEWAY_PAID}`;
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const qb = invoiceLedgerQb(ctx);
+  const matched = ctx.params.matched as string | null;
+  if (matched === 'matched') qb.andWhere(`ROUND(${VARIANCE}, 2) = 0`);
+  if (matched === 'unmatched') qb.andWhere(`ROUND(${VARIANCE}, 2) <> 0`);
+  return qb;
+}
+
+export const revenueReconciliationReport: ReportDefinition = {
+  key: 'revenue-reconciliation',
+  title: 'Revenue vs Payment Reconciliation',
+  description:
+    'Every invoice with its recorded settlement set against what the payment gateway ' +
+    'actually confirmed. Invoices are matched on the booking id both sides carry — ' +
+    'invoices.payment_id points at a payment-service intent, not a freight payment row. ' +
+    'Invoices with no booking (warehouse, shipping-line credit) have no gateway record to ' +
+    'match against and will show their full paid amount as variance.',
+  group: 'Finance',
+  filters: [
+    ...REVENUE_FILTERS.filter((f) => f.key !== 'categories' && f.key !== 'methods'),
+    {
+      key: 'matched',
+      label: 'Reconciliation',
+      type: 'select',
+      options: [
+        { value: 'unmatched', label: 'Variance only' },
+        { value: 'matched', label: 'Reconciled only' },
+      ],
+    },
+  ],
+  columns: [
+    { key: 'issuedAt', label: 'Issued', type: 'date', sortable: true, sortExpr: REVENUE_DATE },
+    { key: 'invoiceNumber', label: 'Invoice No.', type: 'string', sortable: true, sortExpr: 'i.invoice_number' },
+    { key: 'bookingRef', label: 'Booking', type: 'string', sortable: true, sortExpr: 'b.reference' },
+    { key: 'customer', label: 'Customer', type: 'string', sortable: true, sortExpr: PAYER_EXPR },
+    { key: 'source', label: 'Source', type: 'string', sortable: true, sortExpr: 'i.source' },
+    { key: 'status', label: 'Status', type: 'string', sortable: true, sortExpr: 'i.status' },
+    { key: 'invoiced', label: 'Invoiced', type: 'money', sortable: true, sortExpr: 'i.total_amount' },
+    { key: 'recordedPaid', label: 'Recorded paid', type: 'money', sortable: true, sortExpr: 'i.paid_amount' },
+    { key: 'gatewayPaid', label: 'Gateway paid', type: 'money' },
+    { key: 'variance', label: 'Variance', type: 'money', sortable: true, sortExpr: `ABS(${VARIANCE})` },
+    { key: 'balance', label: 'Outstanding', type: 'money', sortable: true, sortExpr: 'i.balance_amount' },
+  ],
+  defaultSort: { key: 'variance', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select(`to_char(${REVENUE_DATE}, 'YYYY-MM-DD')`, 'issuedAt')
+      .addSelect('i.invoice_number', 'invoiceNumber')
+      .addSelect("COALESCE(b.reference, '—')", 'bookingRef')
+      .addSelect(PAYER_EXPR, 'customer')
+      .addSelect('i.source', 'source')
+      .addSelect('i.status', 'status')
+      .addSelect('ROUND(i.total_amount, 2)::float8', 'invoiced')
+      .addSelect('ROUND(i.paid_amount, 2)::float8', 'recordedPaid')
+      .addSelect(`ROUND(${GATEWAY_PAID}, 2)::float8`, 'gatewayPaid')
+      .addSelect(`ROUND(${VARIANCE}, 2)::float8`, 'variance')
+      .addSelect('ROUND(i.balance_amount, 2)::float8', 'balance');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select('COUNT(*)::int', 'invoices')
+      .addSelect(`COUNT(*) FILTER (WHERE ROUND(${VARIANCE}, 2) <> 0)::int`, 'withVariance')
+      .addSelect(`ROUND(COALESCE(SUM(ABS(${VARIANCE})), 0))::float8`, 'variance')
+      .addSelect('ROUND(COALESCE(SUM(i.balance_amount), 0))::float8', 'outstanding')
+      .getRawOne<{ invoices: number; withVariance: number; variance: number; outstanding: number }>();
+    const currency = currencyOf(ctx.params);
+    return [
+      { label: 'Invoices', value: Number(row?.invoices ?? 0) },
+      { label: 'With variance', value: Number(row?.withVariance ?? 0) },
+      { label: 'Total variance', value: Number(row?.variance ?? 0), unit: currency },
+      { label: 'Outstanding', value: Number(row?.outstanding ?? 0), unit: currency },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/revenue-top-customers.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/revenue-top-customers.report.ts
new file mode 100644
index 000000000..ae27d7487
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/revenue-top-customers.report.ts
@@ -0,0 +1,70 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { ReportContext, ReportDefinition } from '../report.types';
+import {
+  CATEGORY_LABEL_EXPR,
+  PAYER_EXPR,
+  PERIOD_FILTER,
+  REVENUE_CATEGORY_EXPR,
+  REVENUE_FILTERS,
+  REVENUE_SUM,
+  TEU_EXPR,
+  TONS_EXPR,
+  currencyOf,
+  revenueLedgerQb,
+} from '../revenue-classification';
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  return revenueLedgerQb(ctx);
+}
+
+export const revenueTopCustomersReport: ReportDefinition = {
+  key: 'revenue-top-customers',
+  title: 'Top Customers by Revenue',
+  description:
+    'Customers ranked by billed revenue, with their category mix and outstanding share. ' +
+    'The payer is the company or, for shipping-line credit invoices, the shipping line — ' +
+    'an invoice carries exactly one of the two.',
+  group: 'Finance',
+  filters: [PERIOD_FILTER, ...REVENUE_FILTERS],
+  columns: [
+    { key: 'customer', label: 'Customer', type: 'string', sortable: true, sortExpr: PAYER_EXPR },
+    { key: 'category', label: 'Revenue category', type: 'string', sortable: true },
+    { key: 'revenue', label: 'Revenue', type: 'money', sortable: true },
+    { key: 'sharePct', label: 'Share of total', type: 'percent' },
+    { key: 'tons', label: 'Tonnage', type: 'tons' },
+    { key: 'teu', label: 'TEU', type: 'number' },
+    { key: 'invoices', label: 'Invoices', type: 'number', sortable: true },
+  ],
+  defaultSort: { key: 'revenue', dir: 'DESC' },
+  chart: { type: 'bar', x: 'customer', y: ['revenue'] },
+  drill: { to: 'revenue-transactions', carry: { customer: 'customer', categoryKey: 'categoryKey' } },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select(PAYER_EXPR, 'customer')
+      .addSelect(CATEGORY_LABEL_EXPR, 'category')
+      .addSelect(REVENUE_CATEGORY_EXPR, 'categoryKey')
+      .addSelect('ROUND(SUM(il.amount))::float8', 'revenue')
+      // Share of the whole filtered set, not of the page — a window over no
+      // partition sees every group the query produced.
+      .addSelect(
+        'ROUND(100 * SUM(il.amount) / NULLIF(SUM(SUM(il.amount)) OVER (), 0), 1)::float8',
+        'sharePct',
+      )
+      .addSelect(`ROUND(COALESCE(${TONS_EXPR}, 0), 1)::float8`, 'tons')
+      .addSelect(`ROUND(COALESCE(${TEU_EXPR}, 0))::int`, 'teu')
+      .addSelect('COUNT(DISTINCT i.id)::int', 'invoices')
+      .groupBy(PAYER_EXPR)
+      .addGroupBy(REVENUE_CATEGORY_EXPR);
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select(REVENUE_SUM, 'revenue')
+      .addSelect(`COUNT(DISTINCT ${PAYER_EXPR})::int`, 'customers')
+      .getRawOne<{ revenue: number; customers: number }>();
+    return [
+      { label: 'Customers', value: Number(row?.customers ?? 0) },
+      { label: 'Total revenue', value: Number(row?.revenue ?? 0), unit: currencyOf(ctx.params) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/definitions/revenue-transactions.report.ts b/apps/edr-freight-api/src/modules/reports/definitions/revenue-transactions.report.ts
new file mode 100644
index 000000000..ad96b5b9e
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/definitions/revenue-transactions.report.ts
@@ -0,0 +1,131 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { ReportContext, ReportDefinition } from '../report.types';
+import {
+  PAYMENT_CLASS_EXPR,
+  PAYER_EXPR,
+  PERIOD_FILTER,
+  REVENUE_CATEGORIES,
+  REVENUE_CATEGORY_EXPR,
+  REVENUE_DATE,
+  REVENUE_FILTERS,
+  REVENUE_SUM,
+  currencyOf,
+  periodExpr,
+  revenueLedgerQb,
+} from '../revenue-classification';
+
+/**
+ * The gateway payment behind an invoice, for traceability. `invoices.payment_id`
+ * points at a payment-api intent id rather than a `freight.payments` row, so the
+ * reliable link is `payments.ref_id = invoices.source_id` (the booking id).
+ *
+ * Correlated scalar subselects rather than a LATERAL join: TypeORM's query
+ * builder cannot emit LATERAL, and the correlation on `i.source_id` is what
+ * makes this work at all. Successful payments win, then most recent.
+ *
+ * `::text` is not cosmetic — `payments.method` and `payments.status` are real
+ * Postgres enums, so `COALESCE(<enum>, '')` fails with
+ * `invalid input value for enum freight.payments_method_enum: ""`.
+ */
+const latestPayment = (column: string): string => `(
+  SELECT p.${column}::text FROM freight.payments p
+  WHERE p.ref_id = i.source_id
+  ORDER BY (p.status = 'success') DESC, p.created_at DESC
+  LIMIT 1
+)`;
+
+function baseQuery(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params } = ctx;
+  const qb = revenueLedgerQb(ctx);
+
+  // Drill-down target: the summary reports hand over the exact period bucket
+  // and category key they were showing.
+  if (params.period_value) {
+    qb.andWhere(`${periodExpr(params)} = :periodValue`, { periodValue: params.period_value });
+  }
+  if (params.categoryKey) {
+    qb.andWhere(`${REVENUE_CATEGORY_EXPR} = :categoryKey`, { categoryKey: params.categoryKey });
+  }
+  return qb;
+}
+
+export const revenueTransactionsReport: ReportDefinition = {
+  key: 'revenue-transactions',
+  title: 'Revenue Transactions',
+  description:
+    'Every billed revenue line, at transaction level — booking reference, invoice number, ' +
+    'charge type, cargo, quantity and the payment reference behind it. This is the ' +
+    'drill-down target for the revenue summaries and the audit trail for an export.',
+  group: 'Finance',
+  filters: [
+    PERIOD_FILTER,
+    ...REVENUE_FILTERS,
+    { key: 'period_value', label: 'Period bucket', type: 'text' },
+    {
+      key: 'categoryKey',
+      label: 'Category (exact)',
+      type: 'select',
+      options: REVENUE_CATEGORIES,
+    },
+  ],
+  columns: [
+    { key: 'issuedAt', label: 'Issued', type: 'date', sortable: true, sortExpr: REVENUE_DATE },
+    { key: 'invoiceNumber', label: 'Invoice No.', type: 'string', sortable: true, sortExpr: 'i.invoice_number' },
+    { key: 'bookingRef', label: 'Booking', type: 'string', sortable: true, sortExpr: 'b.reference' },
+    { key: 'bookingId', label: 'Booking ID', type: 'string' },
+    { key: 'payer', label: 'Customer', type: 'string', sortable: true, sortExpr: PAYER_EXPR },
+    { key: 'category', label: 'Revenue category', type: 'string', sortable: true, sortExpr: REVENUE_CATEGORY_EXPR },
+    { key: 'paymentClass', label: 'Payment class', type: 'string' },
+    { key: 'chargeType', label: 'Charge type', type: 'string', sortable: true, sortExpr: 'il.charge_type' },
+    { key: 'cargo', label: 'Cargo', type: 'string' },
+    { key: 'route', label: 'Route', type: 'string' },
+    { key: 'quantity', label: 'Qty', type: 'number' },
+    { key: 'unit', label: 'Unit', type: 'string' },
+    { key: 'unitRate', label: 'Unit rate', type: 'money' },
+    { key: 'amount', label: 'Amount', type: 'money', sortable: true, sortExpr: 'il.amount' },
+    { key: 'currency', label: 'Currency', type: 'string' },
+    { key: 'invoiceStatus', label: 'Invoice status', type: 'string', sortable: true, sortExpr: 'i.status' },
+    { key: 'paymentRef', label: 'Payment ref', type: 'string' },
+    { key: 'paymentMethod', label: 'Method', type: 'string' },
+    { key: 'paymentStatus', label: 'Payment status', type: 'string' },
+  ],
+  defaultSort: { key: 'issuedAt', dir: 'DESC' },
+  query(ctx) {
+    return baseQuery(ctx)
+      .select(`to_char(${REVENUE_DATE}, 'YYYY-MM-DD')`, 'issuedAt')
+      .addSelect('i.invoice_number', 'invoiceNumber')
+      .addSelect("COALESCE(b.reference, '—')", 'bookingRef')
+      .addSelect("COALESCE(b.id::text, '')", 'bookingId')
+      .addSelect(PAYER_EXPR, 'payer')
+      .addSelect(REVENUE_CATEGORY_EXPR, 'category')
+      .addSelect(PAYMENT_CLASS_EXPR, 'paymentClass')
+      .addSelect('il.charge_type', 'chargeType')
+      .addSelect("COALESCE(ct.cargo_type_name, b.cargo_free_text, '—')", 'cargo')
+      .addSelect("COALESCE(oy.label, '?') || ' → ' || COALESCE(dy.label, '?')", 'route')
+      .addSelect('il.quantity::float8', 'quantity')
+      .addSelect("COALESCE(il.metadata->>'unit', '')", 'unit')
+      .addSelect('ROUND(il.unit_rate, 2)::float8', 'unitRate')
+      .addSelect('ROUND(il.amount, 2)::float8', 'amount')
+      .addSelect('il.currency', 'currency')
+      .addSelect('i.status', 'invoiceStatus')
+      .addSelect(
+        `COALESCE(${latestPayment('transaction_id')}, ${latestPayment('merchant_order_id')}, '')`,
+        'paymentRef',
+      )
+      .addSelect(`COALESCE(${latestPayment('method')}, '')`, 'paymentMethod')
+      .addSelect(`COALESCE(${latestPayment('status')}, '')`, 'paymentStatus');
+  },
+  async summary(ctx) {
+    const row = await baseQuery(ctx)
+      .select(REVENUE_SUM, 'revenue')
+      .addSelect('COUNT(*)::int', 'lines')
+      .addSelect('COUNT(DISTINCT i.id)::int', 'invoices')
+      .getRawOne<{ revenue: number; lines: number; invoices: number }>();
+    return [
+      { label: 'Lines', value: Number(row?.lines ?? 0) },
+      { label: 'Invoices', value: Number(row?.invoices ?? 0) },
+      { label: 'Revenue', value: Number(row?.revenue ?? 0), unit: currencyOf(ctx.params) },
+    ];
+  },
+};
diff --git a/apps/edr-freight-api/src/modules/reports/report.registry.ts b/apps/edr-freight-api/src/modules/reports/report.registry.ts
index 004b61e5b..da280a271 100644
--- a/apps/edr-freight-api/src/modules/reports/report.registry.ts
+++ b/apps/edr-freight-api/src/modules/reports/report.registry.ts
@@ -22,6 +22,15 @@ import { invoicesByStatusReport } from './definitions/invoices-by-status.report'
 import { paymentsByStatusReport } from './definitions/payments-by-status.report';
 import { revenueSummaryReport } from './definitions/revenue-summary.report';
 import { cargoSummaryReport } from './definitions/cargo-summary.report';
+import { revenueByCategoryReport } from './definitions/revenue-by-category.report';
+import { revenueTransactionsReport } from './definitions/revenue-transactions.report';
+import { revenueByPeriodReport } from './definitions/revenue-by-period.report';
+import { revenueByRouteReport } from './definitions/revenue-by-route.report';
+import { revenueTopCustomersReport } from './definitions/revenue-top-customers.report';
+import { paymentClassificationReport } from './definitions/payment-classification.report';
+import { revenueReconciliationReport } from './definitions/revenue-reconciliation.report';
+import { receivablesPayablesReport } from './definitions/receivables-payables.report';
+import { revenueAnomaliesReport } from './definitions/revenue-anomalies.report';
 import { ReportDefinition } from './report.types';
 
 /**
@@ -53,6 +62,15 @@ export const REPORTS: ReportDefinition[] = [
   paymentsByStatusReport,
   revenueSummaryReport,
   cargoSummaryReport,
+  revenueByCategoryReport,
+  revenueTransactionsReport,
+  revenueByPeriodReport,
+  revenueByRouteReport,
+  revenueTopCustomersReport,
+  paymentClassificationReport,
+  revenueReconciliationReport,
+  receivablesPayablesReport,
+  revenueAnomaliesReport,
 ];
 
 const BY_KEY = new Map<ReportKey, ReportDefinition>(REPORTS.map((r) => [r.key, r]));
diff --git a/apps/edr-freight-api/src/modules/reports/report.types.ts b/apps/edr-freight-api/src/modules/reports/report.types.ts
index a709ac654..ca7578461 100644
--- a/apps/edr-freight-api/src/modules/reports/report.types.ts
+++ b/apps/edr-freight-api/src/modules/reports/report.types.ts
@@ -34,6 +34,24 @@ export interface ReportFilterDef {
   type: ReportFilterType;
   /** Static option list for select/multiselect. */
   options?: ReportFilterOption[];
+  /**
+   * Resolves the option list from the database instead of declaring it inline —
+   * for filters whose choices are reference data (stations, cargo types).
+   * Called once per catalog request and cached; the result is serialised into
+   * `options`, so the frontend never sees the difference.
+   */
+  optionsQuery?: (ds: DataSource) => Promise<ReportFilterOption[]>;
+}
+
+/**
+ * Makes a summary row clickable: the row's values are carried into another
+ * report as filter params, which is how "drill down from summary to
+ * transaction level" works. Keys are this report's column keys; values are the
+ * target report's filter keys.
+ */
+export interface ReportDrillDef {
+  to: ReportKey;
+  carry: Record<string, string>;
 }
 
 export interface ReportKpi {
@@ -90,6 +108,8 @@ export interface ReportDefinition {
   summary?(ctx: ReportContext): Promise<ReportKpi[]>;
   /** Optional chart view of the same rows. Table remains the default view. */
   chart?: ReportChartDef;
+  /** Makes rows clickable, navigating to a transaction-level report. */
+  drill?: ReportDrillDef;
 }
 
 /** Catalog shape served by GET /reports — metadata only, no rows. */
diff --git a/apps/edr-freight-api/src/modules/reports/reports.controller.ts b/apps/edr-freight-api/src/modules/reports/reports.controller.ts
index 4d213bc2b..107e11097 100644
--- a/apps/edr-freight-api/src/modules/reports/reports.controller.ts
+++ b/apps/edr-freight-api/src/modules/reports/reports.controller.ts
@@ -1,5 +1,7 @@
 import { Controller, Get, NotFoundException, Param, Query, Res } from '@nestjs/common';
 import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { InjectDataSource } from '@nestjs/typeorm';
+import { DataSource } from 'typeorm';
 import { CurrentUser } from '@edr/api-common';
 import type { Response } from 'express';
 import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
@@ -12,13 +14,44 @@ import { ReportExportService } from './report-export.service';
 import { resolveExportCap, resolveExportColumns, resolveExportFormat } from './report-export-request.util';
 import { RawReportQuery, ReportRunnerService } from './report-runner.service';
 import { REPORTS, getReport } from './report.registry';
-import { ReportCatalogEntry, ReportDefinition } from './report.types';
+import { ReportCatalogEntry, ReportDefinition, ReportFilterOption } from './report.types';
 
 const toCatalogEntry = (def: ReportDefinition): ReportCatalogEntry => {
   const { query: _query, summary, ...meta } = def;
   return { ...meta, hasSummary: Boolean(summary) };
 };
 
+/**
+ * Filters whose choices are reference data resolve their options here rather
+ * than declaring them inline, so the catalog the frontend receives looks the
+ * same either way. Cached for the process lifetime — these are small, rarely
+ * changing lists (23 stations, 18 cargo types), and the catalog is hit on
+ * every page load.
+ */
+const optionsCache = new Map<string, ReportFilterOption[]>();
+
+async function resolveFilterOptions(
+  def: ReportCatalogEntry,
+  ds: DataSource,
+): Promise<ReportCatalogEntry> {
+  if (!def.filters.some((f) => f.optionsQuery)) return def;
+
+  const filters = await Promise.all(
+    def.filters.map(async (filter) => {
+      if (!filter.optionsQuery) return filter;
+      let options = optionsCache.get(filter.key);
+      if (!options) {
+        options = await filter.optionsQuery(ds);
+        optionsCache.set(filter.key, options);
+      }
+      // Drop the resolver itself — it is a function and would not serialise.
+      const { optionsQuery: _resolver, ...rest } = filter;
+      return { ...rest, options };
+    }),
+  );
+  return { ...def, filters };
+}
+
 @ApiTags('Reports')
 @ApiBearerAuth()
 @Controller('reports')
@@ -28,14 +61,16 @@ export class ReportsController {
     private readonly runner: ReportRunnerService,
     private readonly exportService: ReportExportService,
     private readonly userTradeAccessService: UserTradeAccessService,
+    @InjectDataSource() private readonly dataSource: DataSource,
   ) {}
 
   @Get()
   @ApiOperation({ summary: 'List reports the caller has permission to run' })
   async catalog(@CurrentUser() user: TCurrentUser): Promise<ReportCatalogEntry[]> {
-    return REPORTS.filter((def) => hasFreightPermission(user, reportPermissionKey(def.key))).map(
-      toCatalogEntry,
-    );
+    const allowed = REPORTS.filter((def) =>
+      hasFreightPermission(user, reportPermissionKey(def.key)),
+    ).map(toCatalogEntry);
+    return Promise.all(allowed.map((def) => resolveFilterOptions(def, this.dataSource)));
   }
 
   @Get(':key')
diff --git a/apps/edr-freight-api/src/modules/reports/revenue-classification.spec.ts b/apps/edr-freight-api/src/modules/reports/revenue-classification.spec.ts
new file mode 100644
index 000000000..42475d591
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/revenue-classification.spec.ts
@@ -0,0 +1,102 @@
+import {
+  BULK_FREIGHT_CHARGES,
+  PAYMENT_CLASSES,
+  PAYMENT_CLASS_EXPR,
+  PERIOD_FILTER,
+  REVENUE_CATEGORIES,
+  REVENUE_CATEGORY_EXPR,
+  periodExpr,
+} from './revenue-classification';
+
+/**
+ * `invoice_lines.charge_type` is an unconstrained varchar written by eight
+ * unrelated code paths. Nothing at the type level stops someone adding a ninth
+ * spelling, whose revenue would then land silently in the ELSE arm.
+ *
+ * This list is every value the codebase writes today. When it grows, these
+ * tests are what fail — which is the whole trade the const-map design makes.
+ */
+const KNOWN_CHARGE_TYPES = [
+  // booking base freight (rate_type codes)
+  'CONTAINER_IMPORT', 'CONTAINER_EXPORT', 'CONTAINER_20FT', 'CONTAINER_40FT',
+  'BULK_IMPORT', 'BULK_EXPORT', 'INTERCITY_BULK', 'INTERCITY_CONTAINER', 'FREIGHT',
+  // surcharges
+  'FUEL_SURCHARGE', 'LASHING', 'OVERWEIGHT_PER_TON', 'HAZARD_SURCHARGE',
+  'REEFER_SURCHARGE', 'PIL_EXTRA_FEE', 'RETURN_SURCHARGE', 'RETURN_SURCHARGE_20FT',
+  'RETURN_SURCHARGE_40FT', 'CONTAINER_WITH_RETURN', 'ADJUSTMENT', 'RATE_ADJUSTMENT',
+  // customs
+  'CUSTOMS_CLEARANCE', 'CUSTOMS_CLEARANCE_20FT', 'CUSTOMS_CLEARANCE_40FT',
+  // mile legs
+  'FIRST_MILE', 'LAST_MILE', 'DELIVERY', 'LAST_MILE_ADVANCE',
+  // warehouse fees
+  'CONTAINER_DEMURRAGE', 'BULK_DEMURRAGE', 'DEMURRAGE', 'STORAGE_FEE',
+  'HANDLING_FEE', 'DOUBLE_HANDLING', 'TRUCK_DETENTION',
+  // other producers
+  'CANCELLATION_FEE', 'SHIPPING_LINE_SERVICE',
+];
+
+/**
+ * Does the expression name this charge type — either as a literal or through
+ * one of its `LIKE 'PREFIX%'` arms?
+ *
+ * Deliberately a substring check, not a SQL parser: a parser would be more
+ * fragile than the expression it is guarding. This catches the failure that
+ * actually happens (a new charge type nobody added to the map) and nothing
+ * pretends it verifies the branch order.
+ */
+function isNamed(expr: string, chargeType: string): boolean {
+  if (expr.includes(`'${chargeType}'`)) return true;
+  return [...expr.matchAll(/LIKE '([^']*)%'/g)].some(([, prefix]) =>
+    chargeType.startsWith(prefix),
+  );
+}
+
+describe('revenue classification', () => {
+  it('names every charge type the codebase writes in the payment-class map', () => {
+    const unmapped = KNOWN_CHARGE_TYPES.filter((c) => !isNamed(PAYMENT_CLASS_EXPR, c));
+    expect(unmapped).toEqual([]);
+  });
+
+  it('names every ancillary charge type in the revenue-category map', () => {
+    // Bulk freight lines carry no category of their own — the CASE falls
+    // through to the booking's cargo type and trade direction for those.
+    const cargoDerived = new Set(BULK_FREIGHT_CHARGES);
+    const unmapped = KNOWN_CHARGE_TYPES.filter(
+      (c) => !cargoDerived.has(c) && !isNamed(REVENUE_CATEGORY_EXPR, c),
+    );
+    expect(unmapped).toEqual([]);
+  });
+
+  it('emits only categories that are offered as filter options', () => {
+    const declared = new Set(REVENUE_CATEGORIES.map((c) => c.value));
+    const emitted = [...REVENUE_CATEGORY_EXPR.matchAll(/THEN '([A-Z_]+)'/g)].map((m) => m[1]);
+    expect(emitted.length).toBeGreaterThan(0);
+    expect(emitted.filter((c) => !declared.has(c))).toEqual([]);
+    expect(declared.has('UNCLASSIFIED')).toBe(true);
+  });
+
+  it('emits only payment classes that are offered as filter options', () => {
+    const declared = new Set(PAYMENT_CLASSES.map((c) => c.value));
+    const emitted = [...PAYMENT_CLASS_EXPR.matchAll(/THEN '([A-Z_]+)'/g)].map((m) => m[1]);
+    expect(emitted.filter((c) => !declared.has(c))).toEqual([]);
+    expect(declared.has('ADDITIONAL')).toBe(true);
+  });
+
+  it('falls back to a whitelisted period unit instead of interpolating input', () => {
+    expect(periodExpr({ period: 'quarter' })).toContain("date_trunc('quarter'");
+    expect(periodExpr({ period: 'year' })).toContain("date_trunc('year'");
+    // Anything unrecognised — including an injection attempt — becomes 'month'.
+    expect(periodExpr({ period: "day'); DROP TABLE freight.invoices; --" })).toContain(
+      "date_trunc('month'",
+    );
+    expect(periodExpr({})).toContain("date_trunc('month'");
+  });
+
+  it('offers exactly the period units the expression understands', () => {
+    const offered = (PERIOD_FILTER.options ?? []).map((o) => o.value);
+    expect(offered.length).toBe(5);
+    for (const unit of offered) {
+      expect(periodExpr({ period: unit })).toContain(`date_trunc('${unit}'`);
+    }
+  });
+});
diff --git a/apps/edr-freight-api/src/modules/reports/revenue-classification.ts b/apps/edr-freight-api/src/modules/reports/revenue-classification.ts
new file mode 100644
index 000000000..ebe52ef6b
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/reports/revenue-classification.ts
@@ -0,0 +1,553 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+
+import { InvoiceLine } from '../billing/entities/invoice-line.entity';
+import { Invoice } from '../billing/entities/invoice.entity';
+import { Booking } from '../bookings/entities/booking.entity';
+import { Company } from '../companies/entities/company.entity';
+import { ShippingLineCompany } from '../shipping-lines/entities/shipping-line-company.entity';
+import { CargoType } from '../rule-engine/entities/cargo-type.entity';
+import { Yard } from '../rule-engine/entities/yard.entity';
+import { applyBookingRefDirectionScope } from '../user-trade-access/trade-scope.util';
+import { ReportContext, ReportFilterDef, ReportFilterOption } from './report.types';
+
+/**
+ * The shared vocabulary and SQL behind every revenue report.
+ *
+ * The fact table is `invoice_lines`, not `bookings`: `charge_type` is the only
+ * column in the system that separates customs, first/last mile, demurrage,
+ * storage and incidental revenue from base freight. A booking total is one
+ * lump sum and cannot answer the revenue-classification requirement.
+ *
+ * Every consumer builds its FROM through {@link revenueLedgerQb}, so the table
+ * aliases below (`il i b ct oy dy co slc`) are a fixed contract and the SQL
+ * fragments here can reference them directly.
+ */
+
+// ---------------------------------------------------------------------------
+// Revenue categories
+// ---------------------------------------------------------------------------
+
+export const REVENUE_CATEGORIES: ReportFilterOption[] = [
+  { value: 'CONTAINER_IMPORT_MULTIMODAL', label: 'Full Container Import — Multimodal' },
+  { value: 'CONTAINER_IMPORT_UNIMODAL', label: 'Full Container Import — Unimodal' },
+  { value: 'CONTAINER_EXPORT', label: 'Full Container Export' },
+  { value: 'EMPTY_CONTAINER_REEXPORT', label: 'Empty Container Re-export' },
+  { value: 'FERTILIZER', label: 'Fertilizer Transportation' },
+  { value: 'BREAK_BULK', label: 'Break Bulk (Steel, Machineries)' },
+  { value: 'RORO', label: 'RoRo Transportation' },
+  { value: 'OTHER_IMPORT_BULK', label: 'Other Import Bulk Cargo' },
+  { value: 'OTHER_EXPORT_CARGO', label: 'Other Export Cargo' },
+  { value: 'DOMESTIC', label: 'Domestic Cargo Transportation' },
+  { value: 'INCIDENTAL', label: 'Incidental Charges' },
+  { value: 'FIRST_LAST_MILE', label: 'First & Last Mile' },
+  { value: 'CUSTOMS_CLEARANCE', label: 'Customs Clearance' },
+  { value: 'UNCLASSIFIED', label: 'Unclassified' },
+];
+
+/**
+ * `charge_type` is an unconstrained varchar written by eight different code
+ * paths, so the same concept arrives under several spellings — three for
+ * demurrage, four for first/last mile. Every set below absorbs all of them.
+ */
+export const MILE_CHARGES = ['FIRST_MILE', 'LAST_MILE', 'DELIVERY', 'LAST_MILE_ADVANCE'];
+
+export const INCIDENTAL_CHARGES = [
+  'FUEL_SURCHARGE',
+  'LASHING',
+  'OVERWEIGHT_PER_TON',
+  'HAZARD_SURCHARGE',
+  'REEFER_SURCHARGE',
+  'PIL_EXTRA_FEE',
+  'CANCELLATION_FEE',
+  'ADJUSTMENT',
+  'RATE_ADJUSTMENT',
+  'DEMURRAGE',
+  'CONTAINER_DEMURRAGE',
+  'BULK_DEMURRAGE',
+  'TRUCK_DETENTION',
+  'STORAGE_FEE',
+  'HANDLING_FEE',
+  'DOUBLE_HANDLING',
+  'SHIPPING_LINE_SERVICE',
+];
+
+export const DOMESTIC_CHARGES = ['INTERCITY_BULK', 'INTERCITY_CONTAINER'];
+
+export const CONTAINER_FREIGHT_CHARGES = [
+  'CONTAINER_IMPORT',
+  'CONTAINER_EXPORT',
+  'CONTAINER_20FT',
+  'CONTAINER_40FT',
+];
+
+export const BULK_FREIGHT_CHARGES = ['BULK_IMPORT', 'BULK_EXPORT', 'FREIGHT'];
+
+/** Cargo codes the business bills as break bulk, wherever the cargo tree puts them. */
+export const BREAK_BULK_CODES = ['STEEL_BILLET', 'STEEL', 'MACHINERY', 'PIPES', 'TIMBER'];
+
+export const RORO_CODES = ['TRUCK', 'AUTOMOBILE', 'CARS', 'RORO'];
+
+export const FERTILIZER_CODES = ['FERTILIZER'];
+
+/**
+ * Multimodal means EDR carried the sea leg as well as the rail leg. Nothing in
+ * the schema says so directly; a named sea carrier on the booking is the
+ * agreed proxy. One constant, deliberately — flip it here if the business
+ * defines multimodality differently.
+ */
+const MULTIMODAL_PREDICATE = 'b.shipping_line_id IS NOT NULL';
+
+const list = (values: string[]): string => values.map((v) => `'${v}'`).join(', ');
+
+/**
+ * Assigns each invoice line exactly one revenue category. First match wins.
+ *
+ * Charge-derived rules run BEFORE cargo-derived ones on purpose: a customs or
+ * demurrage line billed on a container-import booking is customs/incidental
+ * revenue, not container-import revenue. Reversing the order would fold every
+ * ancillary charge back into the freight categories.
+ *
+ * Nothing falls through silently — an unmatched line lands in UNCLASSIFIED and
+ * every report surfaces that total as a KPI, because an audit report must
+ * never quietly drop money.
+ */
+export const REVENUE_CATEGORY_EXPR = `CASE
+  WHEN il.charge_type LIKE 'CUSTOMS_CLEARANCE%' THEN 'CUSTOMS_CLEARANCE'
+  WHEN il.charge_type IN (${list(MILE_CHARGES)}) THEN 'FIRST_LAST_MILE'
+  WHEN il.charge_type LIKE 'RETURN_SURCHARGE%'
+    OR il.charge_type = 'CONTAINER_WITH_RETURN' THEN 'EMPTY_CONTAINER_REEXPORT'
+  WHEN il.charge_type IN (${list(INCIDENTAL_CHARGES)}) THEN 'INCIDENTAL'
+  WHEN il.charge_type IN (${list(DOMESTIC_CHARGES)})
+    OR (oy.country IS NOT NULL AND oy.country = dy.country) THEN 'DOMESTIC'
+  WHEN il.charge_type IN (${list(CONTAINER_FREIGHT_CHARGES)})
+    OR b.freight_type = 'CONTAINER' THEN
+    CASE
+      WHEN b.trade_direction = 'EXPORT' THEN 'CONTAINER_EXPORT'
+      WHEN ${MULTIMODAL_PREDICATE} THEN 'CONTAINER_IMPORT_MULTIMODAL'
+      ELSE 'CONTAINER_IMPORT_UNIMODAL'
+    END
+  WHEN ct.code IN (${list(FERTILIZER_CODES)}) THEN 'FERTILIZER'
+  WHEN ct.code IN (${list(BREAK_BULK_CODES)}) THEN 'BREAK_BULK'
+  WHEN ct.code IN (${list(RORO_CODES)}) THEN 'RORO'
+  WHEN b.trade_direction = 'EXPORT' THEN 'OTHER_EXPORT_CARGO'
+  WHEN b.trade_direction = 'IMPORT' THEN 'OTHER_IMPORT_BULK'
+  ELSE 'UNCLASSIFIED'
+END`;
+
+const labelCase = (expr: string, options: ReportFilterOption[]): string =>
+  `CASE ${expr}\n  ${options
+    .map((o) => `WHEN '${o.value}' THEN '${o.label.replace(/'/g, "''")}'`)
+    .join('\n  ')}\nEND`;
+
+/** The category as a business label rather than its key, for display columns. */
+export const CATEGORY_LABEL_EXPR = labelCase(REVENUE_CATEGORY_EXPR, REVENUE_CATEGORIES);
+
+/**
+ * Period-over-period change, as a percentage.
+ *
+ * The denominator is `ABS(prior)`, not `prior`. A category can post negative
+ * revenue in a period — a credit note or rate adjustment outweighing its
+ * charges — and dividing by a negative prior flips the sign, reporting a
+ * recovery as a decline. Taking the magnitude keeps the sign of the change
+ * itself.
+ */
+export const growthPctExpr = (revenue: string, prior: string): string =>
+  `ROUND(100 * (${revenue} - ${prior}) / NULLIF(ABS(${prior}), 0), 1)::float8`;
+
+// ---------------------------------------------------------------------------
+// Payment classification
+// ---------------------------------------------------------------------------
+
+export const PAYMENT_CLASSES: ReportFilterOption[] = [
+  { value: 'RAIL_TRANSPORT', label: 'Rail transport' },
+  { value: 'CUSTOMS_CLEARANCE', label: 'Custom clearance' },
+  { value: 'FIRST_LAST_MILE', label: 'First and last mile' },
+  { value: 'OVERWEIGHT', label: 'Overweight' },
+  { value: 'CANCELLATION', label: 'Cancellation' },
+  { value: 'DEMURRAGE', label: 'Demurrage' },
+  { value: 'STORAGE', label: 'Storage' },
+  { value: 'LOADING_UNLOADING', label: 'Loading and unloading' },
+  { value: 'ADDITIONAL', label: 'Additional payment' },
+];
+
+const RAIL_CHARGES = [...CONTAINER_FREIGHT_CHARGES, ...BULK_FREIGHT_CHARGES, ...DOMESTIC_CHARGES];
+
+const DEMURRAGE_CHARGES = ['DEMURRAGE', 'CONTAINER_DEMURRAGE', 'BULK_DEMURRAGE', 'TRUCK_DETENTION'];
+
+/**
+ * Charges that legitimately belong in the spec's "additional payment" bucket.
+ *
+ * Listed explicitly rather than left to the ELSE arm: ELSE also catches charge
+ * types nobody has mapped yet, and those two cases must not be
+ * indistinguishable. Naming these is what lets the spec fail when a genuinely
+ * new charge type appears.
+ */
+export const ADDITIONAL_CHARGES = [
+  'FUEL_SURCHARGE',
+  'HAZARD_SURCHARGE',
+  'REEFER_SURCHARGE',
+  'PIL_EXTRA_FEE',
+  'RETURN_SURCHARGE',
+  'RETURN_SURCHARGE_20FT',
+  'RETURN_SURCHARGE_40FT',
+  'CONTAINER_WITH_RETURN',
+  'ADJUSTMENT',
+  'RATE_ADJUSTMENT',
+  'SHIPPING_LINE_SERVICE',
+];
+
+/**
+ * The nine buckets the revenue spec asks payments to be classified into.
+ *
+ * Caveat worth repeating wherever this is shown: there is no dedicated
+ * loading/unloading charge type in the system. HANDLING_FEE, DOUBLE_HANDLING
+ * and LASHING are the nearest equivalent, so that bucket is an approximation,
+ * not an exact match.
+ */
+export const PAYMENT_CLASS_EXPR = `CASE
+  WHEN il.charge_type LIKE 'CUSTOMS_CLEARANCE%' THEN 'CUSTOMS_CLEARANCE'
+  WHEN il.charge_type IN (${list(MILE_CHARGES)}) THEN 'FIRST_LAST_MILE'
+  WHEN il.charge_type IN (${list(RAIL_CHARGES)}) THEN 'RAIL_TRANSPORT'
+  WHEN il.charge_type = 'OVERWEIGHT_PER_TON' THEN 'OVERWEIGHT'
+  WHEN il.charge_type = 'CANCELLATION_FEE' THEN 'CANCELLATION'
+  WHEN il.charge_type IN (${list(DEMURRAGE_CHARGES)}) THEN 'DEMURRAGE'
+  WHEN il.charge_type = 'STORAGE_FEE' THEN 'STORAGE'
+  WHEN il.charge_type IN ('HANDLING_FEE', 'DOUBLE_HANDLING', 'LASHING')
+    THEN 'LOADING_UNLOADING'
+  WHEN il.charge_type IN (${list(ADDITIONAL_CHARGES)}) THEN 'ADDITIONAL'
+  ELSE 'ADDITIONAL'
+END`;
+
+// ---------------------------------------------------------------------------
+// Period granularity
+// ---------------------------------------------------------------------------
+
+/**
+ * Frozen whitelist. The runner coerces a `select` filter to a trimmed string
+ * or null; that string is used only as an object key here, so the user's value
+ * never reaches SQL — one of five compile-time constants does.
+ *
+ * Every format is zero-padded, so lexicographic order equals chronological
+ * order. The growth window depends on that.
+ */
+const PERIOD_UNITS = {
+  day: { trunc: 'day', fmt: 'YYYY-MM-DD', label: 'Daily', step: '1 day' },
+  week: { trunc: 'week', fmt: 'IYYY-"W"IW', label: 'Weekly', step: '1 week' },
+  month: { trunc: 'month', fmt: 'YYYY-MM', label: 'Monthly', step: '1 month' },
+  // `quarter` is a valid date_trunc unit but NOT a valid interval unit —
+  // INTERVAL '1 quarter' is a syntax error, so the step is spelled in months.
+  quarter: { trunc: 'quarter', fmt: 'YYYY-"Q"Q', label: 'Quarterly', step: '3 months' },
+  year: { trunc: 'year', fmt: 'YYYY', label: 'Yearly', step: '1 year' },
+} as const;
+
+export const PERIOD_FILTER: ReportFilterDef = {
+  key: 'period',
+  label: 'Granularity',
+  type: 'select',
+  options: Object.entries(PERIOD_UNITS).map(([value, u]) => ({ value, label: u.label })),
+};
+
+/** The timestamp every revenue report buckets and filters on. */
+export const REVENUE_DATE = 'COALESCE(i.issued_at, i.created_at)';
+
+/**
+ * The period label expression, as a string.
+ *
+ * Callers must reuse the returned string VERBATIM in the select, the GROUP BY
+ * and any window `ORDER BY`. Two traps make this non-negotiable:
+ *
+ * 1. A window `ORDER BY date_trunc(...)` when the group key is `to_char(date_trunc(...))`
+ *    fails with "column i.issued_at must appear in the GROUP BY clause".
+ * 2. Ordinal shorthand — `OVER (PARTITION BY 2 ORDER BY 1)` — is NOT a
+ *    positional reference inside a window clause. Postgres reads the integers
+ *    as constants, so it partitions by a constant and applies no ordering. It
+ *    type-checks, it EXPLAINs clean, and it returns plausible garbage.
+ */
+export function periodExpr(params: Record<string, unknown>): string {
+  const unit = resolvePeriod(params);
+  return `to_char(${periodTruncExpr(params)}, '${unit.fmt}')`;
+}
+
+function resolvePeriod(params: Record<string, unknown>): (typeof PERIOD_UNITS)[keyof typeof PERIOD_UNITS] {
+  const key = String(params.period ?? '') as keyof typeof PERIOD_UNITS;
+  return PERIOD_UNITS[key] ?? PERIOD_UNITS.month;
+}
+
+/** The period's start timestamp — what to GROUP BY when a report needs it numerically. */
+export const periodTruncExpr = (params: Record<string, unknown>): string =>
+  `date_trunc('${resolvePeriod(params).trunc}', ${REVENUE_DATE})`;
+
+/**
+ * The period as a number, for regression: seconds since epoch at the period's
+ * start. Using the timestamp itself rather than `row_number()` keeps a trend
+ * calculation to a single window level — Postgres rejects a window function
+ * nested inside another window function's arguments.
+ */
+export const periodOrdinalExpr = (params: Record<string, unknown>): string =>
+  `EXTRACT(EPOCH FROM ${periodTruncExpr(params)})`;
+
+/** Same scale, one period later — where a one-step-ahead projection lands. */
+export const nextPeriodOrdinalExpr = (params: Record<string, unknown>): string =>
+  `EXTRACT(EPOCH FROM ${periodTruncExpr(params)} + INTERVAL '${resolvePeriod(params).step}')`;
+
+// ---------------------------------------------------------------------------
+// Volume — measured at line grain, never joined from the booking
+// ---------------------------------------------------------------------------
+
+/**
+ * `invoice_lines.quantity` already carries the billed quantity per line, and
+ * `metadata->>'unit'` says what it counts (PER_TON / PER_CONTAINER / PER_WAGON).
+ * Joining booking-level tonnage instead would multiply it by the number of
+ * lines on the booking.
+ */
+export const TONS_EXPR = `SUM(il.quantity) FILTER (WHERE il.metadata->>'unit' = 'PER_TON')`;
+
+export const CONTAINERS_EXPR = `SUM(il.quantity) FILTER (WHERE il.metadata->>'unit' = 'PER_CONTAINER')`;
+
+/**
+ * TEU is never stored. It is derived from the charge code's size suffix; lines
+ * whose code carries no size (CONTAINER_IMPORT / CONTAINER_EXPORT) count as one
+ * TEU each, which under-counts any 40ft box billed under an unsized code.
+ */
+export const TEU_EXPR = `SUM(il.quantity * CASE WHEN il.charge_type LIKE '%40FT%' THEN 2 ELSE 1 END)
+  FILTER (WHERE il.metadata->>'unit' = 'PER_CONTAINER')`;
+
+/**
+ * Revenue per unit, against whichever unit the category is actually billed in.
+ * Exactly one of tons/TEU is non-null per category, so this is per-ton for bulk
+ * and per-TEU for containers; the `unit` column says which.
+ */
+export const AVG_PER_UNIT_EXPR = `ROUND(
+  SUM(il.amount) / NULLIF(COALESCE(${TONS_EXPR}, 0) + COALESCE(${TEU_EXPR}, 0), 0), 2
+)::float8`;
+
+export const UNIT_LABEL_EXPR = `CASE
+  WHEN COALESCE(${TONS_EXPR}, 0) > 0 THEN 'per ton'
+  WHEN COALESCE(${TEU_EXPR}, 0) > 0 THEN 'per TEU'
+  ELSE ''
+END`;
+
+// ---------------------------------------------------------------------------
+// The shared ledger query
+// ---------------------------------------------------------------------------
+
+/** Invoice states that never represent recognised revenue. */
+const DEAD_INVOICE_STATUSES = ['DRAFT', 'CANCELLED'];
+
+export const PAYMENT_METHOD_OPTIONS: ReportFilterOption[] = [
+  'telebirr',
+  'cbe-birr',
+  'cbe-bill',
+  'ebirr',
+  'waafi',
+  'dmoney',
+  'cac-bank',
+  'card',
+].map((v) => ({ value: v, label: v }));
+
+export const CURRENCY_FILTER: ReportFilterDef = {
+  key: 'currency',
+  label: 'Currency',
+  type: 'select',
+  options: [
+    { value: 'ETB', label: 'ETB' },
+    { value: 'USD', label: 'USD' },
+  ],
+};
+
+/**
+ * The filter set shared by every revenue report, so they drill into each other
+ * without losing context.
+ *
+ * `currency` is not optional decoration: the ledger holds both ETB and USD
+ * lines, and summing across them produces a number that means nothing. It
+ * defaults to ETB in {@link revenueLedgerQb} rather than being left blank.
+ */
+export const REVENUE_FILTERS: ReportFilterDef[] = [
+  { key: 'date', label: 'Issued', type: 'daterange' },
+  CURRENCY_FILTER,
+  {
+    key: 'categories',
+    label: 'Revenue category',
+    type: 'multiselect',
+    options: REVENUE_CATEGORIES,
+  },
+  { key: 'origin', label: 'Origin', type: 'select', optionsQuery: yardOptions },
+  { key: 'destination', label: 'Destination', type: 'select', optionsQuery: yardOptions },
+  { key: 'customer', label: 'Customer / booking ref', type: 'text' },
+  {
+    key: 'methods',
+    label: 'Payment method',
+    type: 'multiselect',
+    options: PAYMENT_METHOD_OPTIONS,
+  },
+];
+
+/** Stations are reference data — 23 rows that change about yearly. */
+export async function yardOptions(ds: ReportContext['ds']): Promise<ReportFilterOption[]> {
+  return ds
+    .createQueryBuilder()
+    .from(Yard, 'y')
+    .select('y.code', 'value')
+    .addSelect('y.label', 'label')
+    .where('y.deleted_at IS NULL AND y.is_active')
+    .orderBy('y.display_order', 'ASC')
+    .getRawMany<ReportFilterOption>();
+}
+
+/** Currency the ledger reports in when the caller does not choose one. */
+export const DEFAULT_CURRENCY = 'ETB';
+
+export const currencyOf = (params: Record<string, unknown>): string =>
+  (params.currency as string) || DEFAULT_CURRENCY;
+
+/**
+ * Every revenue report starts here: one invoice line joined out to the booking
+ * that explains it. Bookings are LEFT joined on purpose — warehouse, demurrage
+ * and shipping-line-credit invoices carry no booking and must still be counted.
+ *
+ * The booking join is `i.source_id = b.id::text`, never `i.source_id::uuid`:
+ * `source_id` is a varchar with no FK that holds non-UUID values for other
+ * sources (`eims-self-test-…`), so casting it would throw at runtime.
+ */
+export function revenueLedgerQb(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params, directions } = ctx;
+
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(InvoiceLine, 'il')
+    .innerJoin(Invoice, 'i', 'i.id = il.invoice_id AND i.deleted_at IS NULL')
+    .leftJoin(
+      Booking,
+      'b',
+      "i.source = 'booking' AND i.source_id = b.id::text AND b.deleted_at IS NULL",
+    )
+    .leftJoin(CargoType, 'ct', 'ct.id = b.cargo_type_id')
+    .leftJoin(Yard, 'oy', 'oy.id = b.origin_yard_id')
+    .leftJoin(Yard, 'dy', 'dy.id = b.destination_yard_id')
+    .leftJoin(Company, 'co', 'co.id = i.company_id')
+    .leftJoin(ShippingLineCompany, 'slc', 'slc.id = i.shipping_line_company_id')
+    .where('il.deleted_at IS NULL')
+    .andWhere('i.status NOT IN (:...deadInvoiceStatuses)', {
+      deadInvoiceStatuses: DEAD_INVOICE_STATUSES,
+    })
+    .andWhere("i.source <> 'eims_self_test'")
+    // An umbrella general contract is paid once and drawn down by many orders;
+    // counting both double-counts its value.
+    .andWhere("(b.id IS NULL OR b.contract_kind IS NULL OR b.contract_kind <> 'GENERAL')")
+    // Mixing ETB and USD into one SUM produces a meaningless number.
+    .andWhere('il.currency = :currency', { currency: currencyOf(params) });
+
+  if (params.dateFrom) {
+    qb.andWhere(`${REVENUE_DATE} >= :dateFrom`, { dateFrom: params.dateFrom });
+  }
+  if (params.dateTo) {
+    qb.andWhere(`${REVENUE_DATE} < :dateTo`, { dateTo: params.dateTo });
+  }
+
+  const categories = params.categories as string[] | null;
+  if (categories?.length) {
+    qb.andWhere(`${REVENUE_CATEGORY_EXPR} IN (:...categories)`, { categories });
+  }
+
+  if (params.origin) qb.andWhere('oy.code = :origin', { origin: params.origin });
+  if (params.destination) {
+    qb.andWhere('dy.code = :destination', { destination: params.destination });
+  }
+
+  if (params.customer) {
+    qb.andWhere(
+      '(co.name ILIKE :customer OR slc.name ILIKE :customer OR b.reference ILIKE :customer)',
+      { customer: `%${params.customer as string}%` },
+    );
+  }
+
+  const methods = params.methods as string[] | null;
+  if (methods?.length) {
+    qb.andWhere(
+      `EXISTS (SELECT 1 FROM freight.payments p
+               WHERE p.ref_id = i.source_id AND p.status = 'success'
+                 AND p.method IN (:...methods))`,
+      { methods },
+    );
+  }
+
+  // Hides lines whose booking sits outside the caller's trade scope. Lines with
+  // no booking carry no direction and stay visible.
+  applyBookingRefDirectionScope(qb, 'i.source_id', directions);
+
+  return qb;
+}
+
+/**
+ * Invoice-grain sibling of {@link revenueLedgerQb}, for the reports that must
+ * not multiply an invoice by its line count — outstanding balance,
+ * reconciliation, receivable/payable. Same joins, same filters, minus the
+ * line-only ones (charge category, currency lives on the invoice here).
+ */
+export function invoiceLedgerQb(ctx: ReportContext): SelectQueryBuilder<ObjectLiteral> {
+  const { params, directions } = ctx;
+
+  const qb = ctx.ds
+    .createQueryBuilder()
+    .from(Invoice, 'i')
+    .leftJoin(
+      Booking,
+      'b',
+      "i.source = 'booking' AND i.source_id = b.id::text AND b.deleted_at IS NULL",
+    )
+    .leftJoin(CargoType, 'ct', 'ct.id = b.cargo_type_id')
+    .leftJoin(Yard, 'oy', 'oy.id = b.origin_yard_id')
+    .leftJoin(Yard, 'dy', 'dy.id = b.destination_yard_id')
+    .leftJoin(Company, 'co', 'co.id = i.company_id')
+    .leftJoin(ShippingLineCompany, 'slc', 'slc.id = i.shipping_line_company_id')
+    .where('i.deleted_at IS NULL')
+    .andWhere('i.status NOT IN (:...deadInvoiceStatuses)', {
+      deadInvoiceStatuses: DEAD_INVOICE_STATUSES,
+    })
+    .andWhere("i.source <> 'eims_self_test'")
+    .andWhere("(b.id IS NULL OR b.contract_kind IS NULL OR b.contract_kind <> 'GENERAL')")
+    .andWhere('i.currency = :currency', { currency: currencyOf(params) });
+
+  if (params.dateFrom) qb.andWhere(`${REVENUE_DATE} >= :dateFrom`, { dateFrom: params.dateFrom });
+  if (params.dateTo) qb.andWhere(`${REVENUE_DATE} < :dateTo`, { dateTo: params.dateTo });
+  if (params.origin) qb.andWhere('oy.code = :origin', { origin: params.origin });
+  if (params.destination) qb.andWhere('dy.code = :destination', { destination: params.destination });
+  if (params.customer) {
+    qb.andWhere(
+      '(co.name ILIKE :customer OR slc.name ILIKE :customer OR b.reference ILIKE :customer)',
+      { customer: `%${params.customer as string}%` },
+    );
+  }
+
+  applyBookingRefDirectionScope(qb, 'i.source_id', directions);
+  return qb;
+}
+
+/**
+ * What the payment gateway actually recorded against this invoice, summed.
+ * `invoices.payment_id` points at a payment-api intent id rather than a
+ * `freight.payments` row, so the reliable link is the booking id both sides
+ * carry.
+ */
+export const GATEWAY_PAID = `(
+  SELECT COALESCE(SUM(p.amount), 0) FROM freight.payments p
+  WHERE p.ref_id = i.source_id AND p.status = 'success'
+)`;
+
+/** The payer, whichever of the two mutually exclusive payer columns is set. */
+export const PAYER_EXPR = "COALESCE(co.name, slc.name, 'Unknown')";
+
+/** `SUM(amount)`, rounded to whole currency and typed as a JS number. */
+export const REVENUE_SUM = 'ROUND(COALESCE(SUM(il.amount), 0))::float8';
+
+/**
+ * Settled share of a line, apportioned by how much of its invoice was paid.
+ * Invoice-level `paid_amount` cannot be attributed to a single line any other
+ * way.
+ */
+export const PAID_SHARE =
+  'il.amount * CASE WHEN i.total_amount > 0 THEN i.paid_amount / i.total_amount ELSE 0 END';
+
+/** The payment class as a business label rather than its key. */
+export const PAYMENT_CLASS_LABEL_EXPR = labelCase(PAYMENT_CLASS_EXPR, PAYMENT_CLASSES);
diff --git a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
index 380a62f02..41728e10c 100644
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -78,6 +78,15 @@ export const REPORT_KEYS = [
   "payments-by-status",
   "revenue-summary",
   "cargo-summary",
+  "revenue-by-category",
+  "revenue-transactions",
+  "revenue-by-period",
+  "revenue-by-route",
+  "revenue-top-customers",
+  "payment-classification",
+  "revenue-reconciliation",
+  "receivables-payables",
+  "revenue-anomalies",
 ] as const;
 
 export type ReportKey = (typeof REPORT_KEYS)[number];
diff --git a/apps/edr-freight-web/backoffice/src/App.tsx b/apps/edr-freight-web/backoffice/src/App.tsx
index c131af4bd..31133c575 100644
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -44,7 +44,7 @@ import MyProfilePage from "./pages/dashboard/MyProfilePage";
 import OverviewPage from "./pages/dashboard/OverviewPage";
 import OverviewDomainPage from "./pages/dashboard/OverviewDomainPage";
 import { OVERVIEW_DOMAINS } from "./components/overview/overview-domains.config";
-import ReportsIndexRedirect from "./pages/reports/ReportsIndexRedirect";
+import ReportsLandingPage from "./pages/reports/ReportsLandingPage";
 import ReportPage from "./pages/reports/ReportPage";
 import AuditLogsPage from "./pages/AuditLogsPage";
 import AiBookingMockTestPage from "./pages/ai/AiBookingMockTestPage";
@@ -245,7 +245,7 @@ const App = () => {
           path="reports"
           element={
             <RequirePermission permission={FREIGHT_PERMS.reports.view}>
-              <ReportsIndexRedirect />
+              <ReportsLandingPage />
             </RequirePermission>
           }
         />
diff --git a/apps/edr-freight-web/backoffice/src/components/reports/ReportSection.tsx b/apps/edr-freight-web/backoffice/src/components/reports/ReportSection.tsx
index 99c6d30c3..e686bc9d0 100644
--- a/apps/edr-freight-web/backoffice/src/components/reports/ReportSection.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/reports/ReportSection.tsx
@@ -9,6 +9,8 @@ interface ReportSectionProps {
   reportKey: string;
   /** Scopes the report to one entity, e.g. the contract this page is showing. */
   idKeyValue?: string;
+  /** Opens on the chart instead of the table — for dashboard tiles. */
+  defaultView?: "table" | "chart";
 }
 
 /**
@@ -17,7 +19,7 @@ interface ReportSectionProps {
  * loading or if the caller lacks the report's permission, so pages can embed
  * it unconditionally without their own permission check.
  */
-export function ReportSection({ reportKey, idKeyValue }: ReportSectionProps) {
+export function ReportSection({ reportKey, idKeyValue, defaultView }: ReportSectionProps) {
   const { data: catalog } = useQuery(api.reports.catalog.queryOptions());
   const def = catalog?.find((r) => r.key === reportKey);
 
@@ -31,7 +33,7 @@ export function ReportSection({ reportKey, idKeyValue }: ReportSectionProps) {
           {def.description}
         </Text>
       </div>
-      <ReportView reportKey={reportKey} idKeyValue={idKeyValue} />
+      <ReportView reportKey={reportKey} idKeyValue={idKeyValue} defaultView={defaultView} />
     </Stack>
   );
 }
diff --git a/apps/edr-freight-web/backoffice/src/pages/reports/ReportsIndexRedirect.tsx b/apps/edr-freight-web/backoffice/src/pages/reports/ReportsIndexRedirect.tsx
deleted file mode 100644
index a341b388e..000000000
--- a/apps/edr-freight-web/backoffice/src/pages/reports/ReportsIndexRedirect.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-import { useQuery } from "@tanstack/react-query";
-import { Navigate } from "react-router-dom";
-
-import { api } from "@/services/api";
-
-/**
- * `/dashboard/reports` has no page of its own — it forwards to the first
- * report the caller has access to (catalog order = registration order,
- * already permission-filtered server-side), or home if they have none.
- */
-export default function ReportsIndexRedirect() {
-  const { data: catalog, isLoading } = useQuery(api.reports.catalog.queryOptions());
-
-  if (isLoading) return null;
-  const first = catalog?.[0];
-  return <Navigate to={first ? `/dashboard/reports/${first.key}` : "/dashboard"} replace />;
-}
diff --git a/apps/edr-freight-web/backoffice/src/pages/reports/ReportsLandingPage.tsx b/apps/edr-freight-web/backoffice/src/pages/reports/ReportsLandingPage.tsx
new file mode 100644
index 000000000..98ea19bfc
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/pages/reports/ReportsLandingPage.tsx
@@ -0,0 +1,51 @@
+import { SimpleGrid, Stack } from "@mantine/core";
+import { useQuery } from "@tanstack/react-query";
+import { Navigate } from "react-router-dom";
+
+import { PageContainer, PageHeader } from "@/components/page";
+import { ReportSection } from "@/components/reports/ReportSection";
+import { api } from "@/services/api";
+
+/**
+ * The revenue dashboard the reporting spec asks for, assembled from reports
+ * that already exist rather than a second aggregation API: each tile is a
+ * `ReportSection` opened on its chart, and each one permission-gates itself by
+ * rendering nothing when the caller's catalog lacks that report.
+ */
+const TILES = [
+  "revenue-by-period",
+  "revenue-by-category",
+  "revenue-by-route",
+  "revenue-top-customers",
+];
+
+export default function ReportsLandingPage() {
+  const { data: catalog, isLoading } = useQuery(api.reports.catalog.queryOptions());
+
+  if (isLoading) return null;
+
+  const visible = TILES.filter((key) => catalog?.some((r) => r.key === key));
+
+  // No revenue reports for this user — fall back to the old behaviour and send
+  // them to the first report they can actually open.
+  if (!visible.length) {
+    const first = catalog?.[0];
+    return <Navigate to={first ? `/dashboard/reports/${first.key}` : "/dashboard"} replace />;
+  }
+
+  return (
+    <PageContainer>
+      <Stack gap="lg">
+        <PageHeader
+          title="Revenue dashboard"
+          subtitle="Billed rail revenue by period, category, corridor and customer. Pick any report in the sidebar for the full table, filters and export."
+        />
+        <SimpleGrid cols={{ base: 1, xl: 2 }} spacing="lg">
+          {visible.map((key) => (
+            <ReportSection key={key} reportKey={key} defaultView="chart" />
+          ))}
+        </SimpleGrid>
+      </Stack>
+    </PageContainer>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/types/reports.ts b/apps/edr-freight-web/backoffice/src/types/reports.ts
index 8bdd6bd23..e3b6749da 100644
--- a/apps/edr-freight-web/backoffice/src/types/reports.ts
+++ b/apps/edr-freight-web/backoffice/src/types/reports.ts
@@ -46,6 +46,16 @@ export interface ReportChartDef {
   y: string[];
 }
 
+/**
+ * Makes a summary row clickable: the row's values are carried into another
+ * report as filter params. Keys are this report's column keys; values are the
+ * target report's filter keys.
+ */
+export interface ReportDrillDef {
+  to: string;
+  carry: Record<string, string>;
+}
+
 /** Mirrors the backend's ReportCatalogEntry — one entry per GET /reports item. */
 export interface ReportCatalogEntry {
   key: string;
@@ -58,6 +68,7 @@ export interface ReportCatalogEntry {
   defaultSort?: { key: string; dir: "ASC" | "DESC" };
   hasSummary: boolean;
   chart?: ReportChartDef;
+  drill?: ReportDrillDef;
 }
 
 export interface ReportPageMeta {

From 174bc1a7bd409f7548ccffacadab538a512aa9d3 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Wed, 19 Aug 2026 17:07:48 +0000
Subject: [PATCH 170/174] Implement new feature for user authentication and
 improve error handling

---
 .../src/pages/EDRFreightLandingPage.tsx       | 1763 ++++++++++++-----
 1 file changed, 1315 insertions(+), 448 deletions(-)

diff --git a/apps/edr-freight-web/portal/src/pages/EDRFreightLandingPage.tsx b/apps/edr-freight-web/portal/src/pages/EDRFreightLandingPage.tsx
index b6f4787d6..59e6f2ad6 100644
--- a/apps/edr-freight-web/portal/src/pages/EDRFreightLandingPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/EDRFreightLandingPage.tsx
@@ -1,139 +1,571 @@
+import { useEffect, useRef, useState } from "react";
 import { Link } from "react-router-dom";
 import {
   ArrowRight,
-  BarChart3,
+  BellRing,
+  Briefcase,
+  Building2,
+  ChartColumn,
+  Check,
   CheckCircle2,
   Clock3,
-  Globe2,
+  FileCheck,
+  FileText,
   Mail,
+  Map as MapIcon,
   MapPin,
   Menu,
+  Package,
+  PackageSearch,
   Phone,
-  ShieldCheck,
-  Train,
+  Radar,
+  Receipt,
+  Route as RouteIcon,
+  Satellite,
+  Ship,
+  Timer,
+  TrainFront,
+  TrendingDown,
+  TrendingUp,
   Truck,
-  Users,
 } from "lucide-react";
 
+/* ------------------------------------------------------------------ */
+/* Motion helpers                                                      */
+/* ------------------------------------------------------------------ */
+
+/** Reveals children once they scroll into view. No animation library needed. */
+function useReveal<T extends HTMLElement>() {
+  const ref = useRef<T | null>(null);
+  const [shown, setShown] = useState(false);
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+    if (typeof IntersectionObserver === "undefined") {
+      setShown(true);
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) {
+          setShown(true);
+          observer.disconnect();
+        }
+      },
+      { rootMargin: "0px 0px -12% 0px", threshold: 0.15 },
+    );
+
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, []);
+
+  return { ref, shown };
+}
+
+function Reveal({
+  children,
+  delay = 0,
+  className = "",
+}: {
+  children: React.ReactNode;
+  delay?: number;
+  className?: string;
+}) {
+  const { ref, shown } = useReveal<HTMLDivElement>();
+
+  return (
+    <div
+      ref={ref}
+      className={`edr-reveal ${shown ? "is-visible" : ""} ${className}`}
+      style={{ transitionDelay: `${delay}ms` }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Counts up to `value` when scrolled into view. Keeps prefix/suffix intact. */
+function CountUp({
+  value,
+  decimals = 0,
+  prefix = "",
+  suffix = "",
+  duration = 1400,
+}: {
+  value: number;
+  decimals?: number;
+  prefix?: string;
+  suffix?: string;
+  duration?: number;
+}) {
+  const { ref, shown } = useReveal<HTMLSpanElement>();
+  const [display, setDisplay] = useState(0);
+
+  useEffect(() => {
+    if (!shown) return;
+    if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) {
+      setDisplay(value);
+      return;
+    }
+
+    let frame = 0;
+    const start = performance.now();
+
+    const tick = (now: number) => {
+      const progress = Math.min(1, (now - start) / duration);
+      // easeOutCubic
+      setDisplay(value * (1 - Math.pow(1 - progress, 3)));
+      if (progress < 1) frame = requestAnimationFrame(tick);
+    };
+
+    frame = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frame);
+  }, [shown, value, duration]);
+
+  return (
+    <span ref={ref}>
+      {prefix}
+      {display.toFixed(decimals)}
+      {suffix}
+    </span>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/* Content                                                             */
+/* ------------------------------------------------------------------ */
+
+const navLinks = [
+  { label: "Features", href: "#features" },
+  { label: "Live ops", href: "#showcase" },
+  { label: "Corridors", href: "#corridors" },
+  { label: "How it works", href: "#how" },
+  { label: "Contact", href: "#contact" },
+];
+
+const heroTrust = [
+  "Telebirr & CBE Birr payments",
+  "Fayda ID verified",
+  "Customs-ready documents",
+];
+
+const trackingStops = [
+  { name: "Mojo Dry Port", time: "Loaded · 06:40", state: "done" },
+  { name: "Adama", time: "Departed · 08:15", state: "done" },
+  { name: "Dire Dawa", time: "ETA 14:30", state: "current" },
+  { name: "Dewele (Border)", time: "ETA 18:05", state: "idle" },
+  { name: "Djibouti Port", time: "ETA 22:40", state: "idle" },
+] as const;
+
 const stats = [
   {
-    label: "Active Corridors",
-    value: "24+",
-    icon: Globe2,
+    icon: RouteIcon,
+    value: <CountUp value={752} suffix=" km" />,
+    label: "Addis Ababa → Djibouti · electrified",
+    trend: "Standard gauge",
+    down: false,
+    chart: [20, 24, 28, 30, 34, 36, 40, 44],
   },
   {
-    label: "Monthly Shipments",
-    value: "12K+",
-    icon: Truck,
+    icon: Package,
+    value: <CountUp value={12.4} decimals={1} suffix="K" />,
+    label: "Monthly consignments booked",
+    trend: "+18% vs last month",
+    down: false,
+    chart: [16, 22, 19, 26, 30, 28, 36, 44],
   },
   {
-    label: "Fleet Coverage",
-    value: "16 Trains",
-    icon: Train,
+    icon: TrainFront,
+    value: <CountUp value={16} />,
+    label: "Train sets in active rotation",
+    trend: "14 running now",
+    down: false,
+    fleet: true,
   },
   {
-    label: "On-time Delivery",
-    value: "100%",
-    icon: Clock3,
+    icon: Timer,
+    value: <CountUp value={10} prefix="<" suffix=" min" />,
+    label: "Booking to confirmed wagon",
+    trend: "-62% since launch",
+    down: true,
+    chart: [44, 40, 36, 30, 26, 20, 16, 12],
   },
 ];
 
+const stations = [
+  { name: "Sebeta", hub: false },
+  { name: "Addis Ababa", hub: true, note: "Km 0" },
+  { name: "Mojo", hub: true },
+  { name: "Adama", hub: false },
+  { name: "Awash", hub: false },
+  { name: "Mieso", hub: false },
+  { name: "Dire Dawa", hub: true },
+  { name: "Dewele", hub: true, note: "Customs", border: true },
+  { name: "Ali Sabieh", hub: false },
+  { name: "Djibouti Port", hub: true, note: "Km 752" },
+];
+
+const lanes = [
+  { from: "Mojo Dry Port", to: "Djibouti Port", transit: "~16h", kind: "Containers" },
+  { from: "Addis Ababa", to: "Djibouti Port", transit: "~19h", kind: "Mixed cargo" },
+  { from: "Djibouti Port", to: "Mojo Dry Port", transit: "~16h", kind: "Imports" },
+  { from: "Dire Dawa", to: "Djibouti Port", transit: "~8h", kind: "Bulk" },
+];
+
+const steps = [
+  {
+    num: "01",
+    title: "Verify & register",
+    body: "Sign up with your company TIN, verify with Fayda ID, and get trade access approved by EDR.",
+  },
+  {
+    num: "02",
+    title: "Book & pay",
+    body: "Pick origin, destination, cargo type and schedule. Pay with Telebirr, CBE Birr or contract credit.",
+  },
+  {
+    num: "03",
+    title: "Load & clear",
+    body: "Wagon allocation, loading confirmation, interchange document and customs stamps — all digital.",
+  },
+  {
+    num: "04",
+    title: "Track & settle",
+    body: "Follow the train live, get gate notifications, and download the final invoice when the cargo is released.",
+  },
+];
+
+const audiences = [
+  {
+    icon: Building2,
+    title: "Shippers & importers",
+    body: "Book, pay, track and download documents from one dashboard.",
+    items: ["Consignment booking", "Live tracking", "Invoices & receipts"],
+  },
+  {
+    icon: Ship,
+    title: "Shipping lines",
+    body: "Manage container inventory, bookings and interchange with the railway.",
+    items: ["Container management", "Booking completion", "Interchange documents"],
+  },
+  {
+    icon: Briefcase,
+    title: "Transit agents",
+    body: "Handle customs declarations, stamps and signatures on behalf of clients.",
+    items: ["Digital stamps", "E-signatures", "Compliance checks"],
+  },
+  {
+    icon: TrainFront,
+    title: "EDR operations",
+    body: "Train sets, locomotives, wagons, schedules, maintenance and incidents.",
+    items: ["Train builder", "Fleet & fuel", "Incident reporting"],
+  },
+];
+
+/* ------------------------------------------------------------------ */
+/* Feature previews                                                    */
+/* ------------------------------------------------------------------ */
+
+function Chip({
+  children,
+  tone = "green",
+  icon: Icon,
+}: {
+  children: React.ReactNode;
+  tone?: "green" | "amber" | "muted";
+  icon?: React.ElementType;
+}) {
+  const tones = {
+    green: "bg-emerald-50 text-emerald-700",
+    amber: "bg-amber-50 text-amber-700",
+    muted: "bg-slate-100 text-slate-500",
+  };
+
+  return (
+    <span
+      className={`inline-flex shrink-0 items-center gap-1 rounded-full px-2 py-1 text-[11px] font-semibold ${tones[tone]}`}
+    >
+      {Icon ? <Icon className="size-3" /> : null}
+      {children}
+    </span>
+  );
+}
+
+function BookingPreview() {
+  return (
+    <div className="flex w-full flex-col gap-2.5">
+      <div className="flex items-center justify-between gap-3 rounded-xl border border-border bg-card px-3 py-2.5">
+        <div className="min-w-0">
+          <p className="truncate text-[13px] font-bold">CN-2026-08421</p>
+          <p className="truncate text-[11px] text-muted-foreground">
+            Mojo → Djibouti · 40ft × 8
+          </p>
+        </div>
+        <Chip icon={Check}>Confirmed</Chip>
+      </div>
+
+      <div className="flex items-center justify-between gap-3">
+        <span className="text-[11px] text-muted-foreground">
+          Depart Thu 21 Aug · TS-14
+        </span>
+        <span className="text-xs font-bold">ETB 184,200</span>
+      </div>
+    </div>
+  );
+}
+
+function GpsPreview() {
+  return (
+    <div className="flex w-full flex-col gap-2.5">
+      <div className="edr-minitrack" aria-hidden>
+        <span className="edr-minitrack-dot" />
+      </div>
+
+      <div className="flex justify-between text-[10px] text-muted-foreground">
+        {["Mojo", "Adama", "Awash", "Dire Dawa", "Djibouti"].map((s) => (
+          <span key={s}>{s}</span>
+        ))}
+      </div>
+
+      <div className="flex items-center justify-between gap-3">
+        <span className="text-[11px] font-semibold">Loco 3421 · 64 km/h</span>
+        <Chip tone="amber" icon={Clock3}>
+          ETA 14:30
+        </Chip>
+      </div>
+    </div>
+  );
+}
+
+function DocsPreview() {
+  const docs = [
+    { name: "Interchange document", status: "Signed" },
+    { name: "Customs declaration", status: "Stamped" },
+    { name: "Commercial invoice", status: "Pending" },
+  ];
+
+  return (
+    <div className="flex w-full flex-col gap-2.5">
+      {docs.map((doc) => {
+        const pending = doc.status === "Pending";
+
+        return (
+          <div key={doc.name} className="flex items-center gap-2">
+            <FileText
+              className={`size-3.5 shrink-0 ${pending ? "text-muted-foreground" : "text-edr-primary"}`}
+            />
+            <span className="min-w-0 flex-1 truncate text-xs">{doc.name}</span>
+            <Chip tone={pending ? "muted" : "green"} icon={pending ? undefined : Check}>
+              {doc.status}
+            </Chip>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function BillingPreview() {
+  return (
+    <div className="flex w-full flex-col gap-2.5">
+      <div className="flex items-center justify-between gap-3 rounded-xl border border-border bg-card px-3 py-2.5">
+        <div className="min-w-0">
+          <p className="truncate text-[13px] font-bold">INV-1042 · Aug</p>
+          <p className="truncate text-[11px] text-muted-foreground">
+            ETB 1,284,600
+          </p>
+        </div>
+        <Chip icon={Check}>Paid</Chip>
+      </div>
+
+      <div className="flex flex-wrap gap-1.5">
+        {["Telebirr", "CBE Birr", "eBirr", "Card"].map((method) => (
+          <span
+            key={method}
+            className="rounded-md border border-border bg-card px-2 py-1 text-[10px] font-semibold text-muted-foreground"
+          >
+            {method}
+          </span>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function MilePreview() {
+  const legs = [
+    { icon: Truck, name: "Truck" },
+    { icon: TrainFront, name: "Rail" },
+    { icon: Truck, name: "Truck" },
+  ];
+
+  return (
+    <div className="flex w-full flex-col gap-2.5">
+      <div className="flex items-center">
+        {legs.map((leg, index) => {
+          const Icon = leg.icon;
+          const isRail = index === 1;
+
+          return (
+            <div key={leg.name + index} className="contents">
+              <div className="flex flex-col items-center gap-1.5">
+                <span
+                  className={`flex size-10 items-center justify-center rounded-xl ${
+                    isRail
+                      ? "bg-edr-primary text-white shadow-md shadow-emerald-500/25"
+                      : "border border-border bg-card text-edr-primary"
+                  }`}
+                >
+                  <Icon className="size-4.5" />
+                </span>
+                <span className="text-[10px] text-muted-foreground">{leg.name}</span>
+              </div>
+
+              {index < legs.length - 1 ? (
+                <span className="edr-dashline mb-4 h-0.5 flex-1" />
+              ) : null}
+            </div>
+          );
+        })}
+      </div>
+
+      <div className="flex justify-between text-[10px] text-muted-foreground">
+        <span>Warehouse, Gerji</span>
+        <span>Consignee, Djibouti</span>
+      </div>
+    </div>
+  );
+}
+
+function AnalyticsPreview() {
+  const bars = [22, 30, 26, 36, 40, 34, 46, 52, 48, 56];
+
+  return (
+    <div className="flex w-full flex-col gap-2.5">
+      <div className="flex h-14 items-end gap-1.5">
+        {bars.map((height, index) => (
+          <span
+            key={index}
+            className={`edr-grow flex-1 rounded-sm ${
+              index >= 8 ? "bg-edr-primary" : "bg-emerald-200"
+            }`}
+            style={{
+              height: `${height}%`,
+              animationDelay: `${index * 60}ms`,
+            }}
+          />
+        ))}
+      </div>
+
+      <div className="flex items-center justify-between gap-3">
+        <span className="text-[11px] text-muted-foreground">
+          Corridor throughput · TEU/week
+        </span>
+        <Chip icon={TrendingUp}>+12%</Chip>
+      </div>
+    </div>
+  );
+}
+
 const features = [
   {
-    title: "Real-time Shipment Tracking",
-    description:
-      "Track consignments across Addis Ababa, Dire Dawa, Djibouti, Mojo, and all major freight corridors.",
+    icon: PackageSearch,
+    title: "Consignment booking",
+    body: "Book containers or bulk cargo, pick a train schedule, and get a confirmed wagon allocation in minutes.",
+    preview: <BookingPreview />,
+  },
+  {
+    icon: Radar,
+    title: "Live GPS tracking",
+    body: "Locomotive telemetry and wagon-level position across every station from Mojo to Djibouti Port.",
+    preview: <GpsPreview />,
+  },
+  {
+    icon: FileCheck,
+    title: "Customs & documents",
+    body: "Interchange documents, stamps and e-signatures generated and shared with transit agents automatically.",
+    preview: <DocsPreview />,
+  },
+  {
+    icon: Receipt,
+    title: "Billing & payments",
+    body: "Contract rates, invoices and settlement via Telebirr, CBE Birr, eBirr or card — with full audit trail.",
+    preview: <BillingPreview />,
+  },
+  {
     icon: Truck,
+    title: "First & last mile",
+    body: "Request trucking to and from the railhead and see it on the same timeline as the rail leg.",
+    preview: <MilePreview />,
   },
   {
-    title: "Rail Freight Operations",
-    description:
-      "Monitor train schedules, operational performance, maintenance, and corridor activity.",
-    icon: Train,
-  },
-  {
-    title: "Smart Analytics Dashboard",
-    description:
-      "Visualize operational insights, shipment trends, and corridor performance in real time.",
-    icon: BarChart3,
-  },
-  {
-    title: "Enterprise-grade Security",
-    description:
-      "Secure portal access, billing workflows, document management, and customer operations.",
-    icon: ShieldCheck,
+    icon: ChartColumn,
+    title: "Operations analytics",
+    body: "Corridor throughput, on-time performance, fleet utilisation and incident reporting for operators.",
+    preview: <AnalyticsPreview />,
   },
 ];
 
-const corridors = [
-  "Addis Ababa → Djibouti",
-  "Dire Dawa → Djibouti",
-  "Adama → Dire Dawa",
-  "Mojo → Djibouti",
-  "Awash → Holhol",
-  "Mieso → Aysha",
-];
+/* ------------------------------------------------------------------ */
+/* Page                                                                */
+/* ------------------------------------------------------------------ */
 
 export default function EDRFreightLandingPage() {
   return (
     <div className="min-h-screen bg-background text-foreground">
+      <LandingStyles />
+
       {/* Navbar */}
-      <header className="sticky top-0 z-50 border-b border-border bg-background/80 backdrop-blur-xl">
+      <header className="sticky top-0 z-50 border-b border-white/10 bg-edr-ink/90 backdrop-blur-xl">
         <div className="mx-auto flex h-20 max-w-7xl items-center justify-between px-6">
-          <div className="flex items-center gap-3">
-            <div className="flex size-12 items-center justify-center rounded-2xl bg-primary text-primary-foreground shadow-lg">
-              <Train className="size-6" />
-            </div>
+          <Link to="/" className="flex items-center gap-3">
+            <span className="flex size-10 items-center justify-center rounded-xl bg-edr-primary text-white shadow-lg shadow-emerald-500/25">
+              <TrainFront className="size-5" />
+            </span>
 
-            <div>
-              <h1 className="text-xl font-bold tracking-tight">EDR Freight</h1>
-
-              <p className="text-sm text-muted-foreground">
+            <span className="leading-tight">
+              <span className="block text-lg font-bold text-white">EDR Freight</span>
+              <span className="block text-[11px] tracking-wide text-slate-400">
                 Rail Logistics Platform
-              </p>
-            </div>
-          </div>
+              </span>
+            </span>
+          </Link>
 
-          <nav className="hidden items-center gap-8 md:flex">
-            <a
-              href="#features"
-              className="text-sm font-medium text-muted-foreground transition hover:text-foreground"
-            >
-              Features
-            </a>
-
-            <a
-              href="#corridors"
-              className="text-sm font-medium text-muted-foreground transition hover:text-foreground"
-            >
-              Corridors
-            </a>
-
-            <a
-              href="#contact"
-              className="text-sm font-medium text-muted-foreground transition hover:text-foreground"
-            >
-              Contact
-            </a>
+          <nav className="hidden items-center gap-9 lg:flex">
+            {navLinks.map((link) => (
+              <a
+                key={link.href}
+                href={link.href}
+                className="text-sm font-medium text-slate-300 transition hover:text-white"
+              >
+                {link.label}
+              </a>
+            ))}
           </nav>
 
           <div className="flex items-center gap-3">
             <Link
               to="/login"
-              className="hidden rounded-2xl border border-border bg-card px-5 py-2.5 text-sm font-medium transition hover:bg-accent md:block"
+              className="hidden rounded-lg border border-white/20 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-white/10 md:block"
             >
-              Login
+              Log in
             </Link>
 
             <Link
               to="/signup"
-              className="hidden items-center gap-2 rounded-2xl bg-primary px-5 py-2.5 text-sm font-semibold text-primary-foreground shadow-lg transition hover:opacity-90 md:flex"
+              className="hidden items-center gap-2 rounded-lg bg-edr-primary px-5 py-2.5 text-sm font-semibold text-white shadow-lg shadow-emerald-500/25 transition hover:-translate-y-0.5 hover:bg-edr-primary-dark md:flex"
             >
-              Get Started
+              Get started
               <ArrowRight className="size-4" />
             </Link>
 
-            <button className="rounded-2xl border border-border p-2 md:hidden">
+            <button
+              type="button"
+              aria-label="Open menu"
+              className="rounded-lg border border-white/20 p-2 text-white lg:hidden"
+            >
               <Menu className="size-5" />
             </button>
           </div>
@@ -141,361 +573,554 @@ export default function EDRFreightLandingPage() {
       </header>
 
       {/* Hero */}
-      <section className="relative overflow-hidden">
-        <div className="absolute inset-0 bg-[radial-gradient(circle_at_top_right,rgba(16,185,129,0.16),transparent_35%)]" />
+      <section className="edr-hero relative overflow-hidden bg-edr-ink">
+        <div className="edr-rails" aria-hidden />
+        <div className="edr-hero-glow" aria-hidden />
 
-        <div className="mx-auto grid relative z-10 max-w-7xl gap-16 px-6 py-20 lg:grid-cols-2 lg:items-center">
+        <div className="relative z-10 mx-auto grid max-w-7xl gap-16 px-6 py-20 lg:grid-cols-[1.05fr_0.95fr] lg:items-center lg:py-24">
           <div>
-            <div className="mb-6 inline-flex items-center gap-2 rounded-full border border-border bg-accent px-4 py-2 text-sm font-medium text-primary shadow-sm">
-              <span className="size-2 rounded-full bg-primary" />
-              Ethiopia–Djibouti Railway Freight Platform
-            </div>
+            <Reveal>
+              <span className="inline-flex items-center gap-2 rounded-full border border-white/15 bg-white/5 py-1.5 pl-2 pr-3 text-[13px] font-medium text-white">
+                <span className="edr-pulse-dot" />
+                Live on the Addis Ababa – Djibouti corridor
+              </span>
+            </Reveal>
 
-            <h1 className="max-w-2xl text-5xl font-black leading-tight tracking-tight md:text-6xl">
-              Smarter Railway Freight Logistics For Modern Operations
-            </h1>
+            <Reveal delay={80}>
+              <h1 className="mt-7 text-5xl font-bold leading-[1.05] tracking-tight text-white md:text-6xl">
+                Move cargo by rail.
+                <span className="block text-emerald-400">Track every wagon.</span>
+              </h1>
+            </Reveal>
 
-            <p className="mt-6 max-w-2xl text-lg leading-8 text-muted-foreground">
-              EDR Freight enables logistics companies and railway operators to
-              manage shipments, monitor freight corridors, optimize train
-              operations, and streamline enterprise logistics workflows.
-            </p>
+            <Reveal delay={160}>
+              <p className="mt-6 max-w-xl text-lg leading-relaxed text-slate-300">
+                EDR Freight is the booking, tracking and billing platform for the
+                Ethio-Djibouti Railway. Book consignments, schedule train sets,
+                clear customs documents and settle invoices — in one portal.
+              </p>
+            </Reveal>
 
-            <div className="mt-10 flex flex-wrap gap-4">
-              <Link
-                to="/signup"
-                className="flex items-center gap-2 rounded-2xl bg-primary px-6 py-3 font-semibold text-primary-foreground shadow-lg transition hover:-translate-y-0.5 hover:opacity-90"
-              >
-                Get Started
-                <ArrowRight className="size-5" />
-              </Link>
-
-              <Link
-                to="/login"
-                className="rounded-2xl border border-border bg-card px-6 py-3 font-semibold transition hover:bg-accent"
-              >
-                Login
-              </Link>
-            </div>
-
-            <div className="mt-12 flex flex-wrap gap-6">
-              {[
-                "Real-time Tracking",
-                "Railway Analytics",
-                "Secure Operations",
-                "Multi-corridor Freight",
-              ].map((item) => (
-                <div
-                  key={item}
-                  className="flex items-center gap-2 text-sm text-muted-foreground"
+            <Reveal delay={240}>
+              <div className="mt-9 flex flex-wrap gap-3">
+                <Link
+                  to="/signup"
+                  className="flex items-center gap-2 rounded-xl bg-edr-primary px-6 py-3.5 font-semibold text-white shadow-xl shadow-emerald-500/30 transition hover:-translate-y-0.5 hover:bg-edr-primary-dark"
                 >
-                  <CheckCircle2 className="size-4 text-primary" />
-                  {item}
-                </div>
-              ))}
-            </div>
+                  Book a shipment
+                  <ArrowRight className="size-4.5" />
+                </Link>
+
+                <a
+                  href="#how"
+                  className="flex items-center gap-2 rounded-xl border border-white/20 px-6 py-3.5 font-medium text-white transition hover:bg-white/10"
+                >
+                  See how it works
+                </a>
+              </div>
+            </Reveal>
+
+            <Reveal delay={320}>
+              <div className="mt-10 flex flex-wrap gap-x-6 gap-y-3">
+                {heroTrust.map((item) => (
+                  <span
+                    key={item}
+                    className="flex items-center gap-2 text-[13px] text-slate-300"
+                  >
+                    <CheckCircle2 className="size-4 text-emerald-400" />
+                    {item}
+                  </span>
+                ))}
+              </div>
+            </Reveal>
           </div>
 
-          {/* Hero Dashboard Card */}
-          <div className="relative">
-            <div className="rounded-[32px] border border-border bg-card p-8 shadow-2xl">
-              <div className="flex items-center justify-between">
-                <div>
-                  <p className="text-sm text-muted-foreground">
-                    Freight Operations
+          {/* Live tracking card */}
+          <Reveal delay={200}>
+            <div className="edr-float overflow-hidden rounded-3xl bg-card shadow-2xl ring-1 ring-white/15">
+              <div className="flex items-center justify-between gap-4 border-b border-border px-6 py-4">
+                <div className="min-w-0">
+                  <p className="truncate text-base font-bold">CN-2026-08417</p>
+                  <p className="truncate text-xs text-muted-foreground">
+                    Mojo Dry Port → Djibouti Port · 40ft × 12
                   </p>
-
-                  <h3 className="mt-2 text-3xl font-bold">Live Statistics</h3>
                 </div>
 
-                <div className="rounded-2xl bg-primary/10 p-4 text-primary">
-                  <BarChart3 className="size-7" />
-                </div>
+                <span className="inline-flex shrink-0 items-center gap-1.5 rounded-full bg-emerald-50 px-2.5 py-1 text-xs font-semibold text-emerald-700">
+                  <span className="edr-pulse-dot edr-pulse-dot--green" />
+                  In transit
+                </span>
               </div>
 
-              <div className="mt-8 grid grid-cols-2 gap-4">
-                {stats.map((item) => {
-                  const Icon = item.icon;
+              <ol className="px-6 py-5">
+                {trackingStops.map((stop, index) => {
+                  const isLast = index === trackingStops.length - 1;
+                  const done = stop.state === "done";
+                  const current = stop.state === "current";
 
                   return (
-                    <div
-                      key={item.label}
-                      className="rounded-3xl border border-border bg-background p-5 transition hover:-translate-y-1 hover:shadow-lg"
-                    >
-                      <div className="mb-4 flex size-12 items-center justify-center rounded-2xl bg-accent text-primary">
-                        <Icon className="size-6" />
-                      </div>
+                    <li key={stop.name} className="flex items-stretch gap-3.5">
+                      <span className="flex w-4 flex-col items-center">
+                        <span
+                          className={`size-3 shrink-0 rounded-full border-2 ${
+                            done
+                              ? "border-edr-primary bg-edr-primary"
+                              : current
+                                ? "border-edr-accent bg-edr-accent edr-ping"
+                                : "border-slate-300 bg-white"
+                          }`}
+                        />
+                        {!isLast ? (
+                          <span
+                            className={`my-1 w-0.5 flex-1 ${
+                              done && trackingStops[index + 1].state === "done"
+                                ? "bg-edr-primary"
+                                : "bg-border"
+                            }`}
+                          />
+                        ) : null}
+                      </span>
 
-                      <h4 className="text-3xl font-black">{item.value}</h4>
-
-                      <p className="mt-1 text-sm text-muted-foreground">
-                        {item.label}
-                      </p>
-                    </div>
+                      <span className={`flex flex-1 items-center justify-between gap-3 ${isLast ? "" : "pb-5"}`}>
+                        <span
+                          className={`text-sm ${
+                            current
+                              ? "font-semibold"
+                              : done
+                                ? "font-medium"
+                                : "font-medium text-muted-foreground"
+                          }`}
+                        >
+                          {stop.name}
+                        </span>
+                        <span className="text-xs text-muted-foreground">
+                          {stop.time}
+                        </span>
+                      </span>
+                    </li>
                   );
                 })}
-              </div>
+              </ol>
 
-              <div className="mt-8 rounded-3xl border border-border bg-accent p-6">
-                <div className="flex items-center justify-between">
-                  <div>
-                    <p className="text-sm text-muted-foreground">
-                      Corridor Performance
+              <div className="grid grid-cols-3 gap-3 bg-background px-6 pb-5 pt-4">
+                {[
+                  ["Train", "TS-14 · 2 locos"],
+                  ["Wagons", "12 / 12 loaded"],
+                  ["Next gate", "Dewele customs"],
+                ].map(([key, value]) => (
+                  <div key={key}>
+                    <p className="text-[10px] font-semibold tracking-wider text-muted-foreground uppercase">
+                      {key}
                     </p>
-
-                    <h3 className="mt-2 text-4xl font-black text-primary">
-                      99%
-                    </h3>
+                    <p className="mt-0.5 text-[13px] font-semibold">{value}</p>
                   </div>
-
-                  <div className="rounded-2xl bg-primary px-4 py-2 text-sm font-semibold text-primary-foreground">
-                    Operational
-                  </div>
-                </div>
-
-                <div className="mt-6 h-3 overflow-hidden rounded-full bg-primary/10">
-                  <div className="h-full w-[99%] rounded-full bg-primary" />
-                </div>
+                ))}
               </div>
             </div>
+          </Reveal>
+        </div>
+      </section>
 
-            <div className="absolute -bottom-6 -left-6 hidden rounded-3xl border border-border bg-card p-5 shadow-xl lg:block">
-              <div className="flex items-center gap-4">
-                <div className="flex size-14 items-center justify-center rounded-2xl bg-primary/10 text-primary">
-                  <Train className="size-7" />
-                </div>
+      {/* Stats */}
+      <section className="mx-auto max-w-7xl px-6 py-14">
+        <div className="grid gap-5 sm:grid-cols-2 xl:grid-cols-4">
+          {stats.map((stat, index) => {
+            const Icon = stat.icon;
+            const TrendIcon = stat.down ? TrendingDown : TrendingUp;
 
-                <div>
-                  <h4 className="text-lg font-bold">16 Trains Active</h4>
+            return (
+              <Reveal key={stat.label} delay={index * 90}>
+                <div className="h-full rounded-2xl border border-border bg-card p-6 shadow-sm transition duration-300 hover:-translate-y-1 hover:shadow-xl">
+                  <div className="flex items-center justify-between">
+                    <span className="flex size-9 items-center justify-center rounded-[10px] bg-edr-soft text-edr-primary">
+                      <Icon className="size-4.5" />
+                    </span>
 
-                  <p className="text-sm text-muted-foreground">
-                    Across all freight corridors
+                    <Chip icon={TrendIcon}>{stat.trend}</Chip>
+                  </div>
+
+                  <p className="mt-4 text-[40px] font-bold leading-none tracking-tight">
+                    {stat.value}
                   </p>
+                  <p className="mt-1.5 text-[13px] text-muted-foreground">
+                    {stat.label}
+                  </p>
+
+                  {stat.fleet ? (
+                    <div className="mt-4 grid grid-cols-8 gap-1.5">
+                      {Array.from({ length: 16 }).map((_, unit) => (
+                        <span
+                          key={unit}
+                          className={`edr-fade-in h-3.5 rounded-sm ${
+                            unit < 14
+                              ? "bg-edr-primary"
+                              : unit === 14
+                                ? "bg-edr-accent"
+                                : "bg-slate-300"
+                          }`}
+                          style={{ animationDelay: `${unit * 45}ms` }}
+                        />
+                      ))}
+                    </div>
+                  ) : (
+                    <div className="mt-4 flex h-12 items-end gap-1">
+                      {stat.chart!.map((height, bar) => (
+                        <span
+                          key={bar}
+                          className={`edr-grow flex-1 rounded-sm ${
+                            bar === stat.chart!.length - 1
+                              ? "bg-edr-accent"
+                              : bar >= stat.chart!.length - 3
+                                ? "bg-edr-primary"
+                                : "bg-emerald-200"
+                          }`}
+                          style={{
+                            height: `${(height / 48) * 100}%`,
+                            animationDelay: `${bar * 60}ms`,
+                          }}
+                        />
+                      ))}
+                    </div>
+                  )}
                 </div>
-              </div>
-            </div>
-          </div>
+              </Reveal>
+            );
+          })}
         </div>
       </section>
 
       {/* Features */}
-      <section
-        id="features"
-        className="border-t border-border bg-card/40 py-24"
-      >
-        <div className="mx-auto max-w-7xl px-6">
-          <div className="max-w-3xl">
-            <div className="inline-flex rounded-full bg-accent px-4 py-2 text-sm font-semibold text-primary">
-              Platform Features
-            </div>
-
-            <h2 className="mt-6 text-4xl font-black tracking-tight">
-              Everything needed for freight operations
-            </h2>
-
-            <p className="mt-4 text-lg leading-8 text-muted-foreground">
-              Centralized railway freight operations with live shipment
-              visibility, operational monitoring, customer management, and
-              intelligent logistics insights.
+      <section id="features" className="mx-auto max-w-7xl scroll-mt-24 px-6 py-20">
+        <div className="flex flex-col justify-between gap-8 lg:flex-row lg:items-end">
+          <Reveal className="max-w-2xl">
+            <p className="text-xs font-bold tracking-[0.16em] text-edr-primary">
+              PLATFORM
             </p>
-          </div>
+            <h2 className="mt-3 text-4xl font-bold leading-tight tracking-tight md:text-[44px]">
+              Everything between the dry port and the quay
+            </h2>
+          </Reveal>
 
-          <div className="mt-16 grid gap-6 md:grid-cols-2 xl:grid-cols-4">
-            {features.map((feature) => {
-              const Icon = feature.icon;
+          <Reveal delay={120} className="max-w-md">
+            <p className="text-base leading-relaxed text-muted-foreground">
+              One portal for shippers, shipping lines, transit agents and railway
+              operations. Built around the real workflow of the corridor, not a
+              generic TMS.
+            </p>
+          </Reveal>
+        </div>
 
-              return (
-                <div
-                  key={feature.title}
-                  className="group rounded-[28px] border border-border bg-background p-7 shadow-sm transition duration-300 hover:-translate-y-2 hover:shadow-2xl"
-                >
-                  <div className="flex size-14 items-center justify-center rounded-2xl bg-accent text-primary transition group-hover:scale-110">
-                    <Icon className="size-7" />
+        <div className="mt-12 grid gap-6 md:grid-cols-2 xl:grid-cols-3">
+          {features.map((feature, index) => {
+            const Icon = feature.icon;
+
+            return (
+              <Reveal key={feature.title} delay={(index % 3) * 100}>
+                <article className="group h-full overflow-hidden rounded-[18px] border border-border bg-card shadow-sm transition duration-300 hover:-translate-y-1.5 hover:shadow-2xl">
+                  <div className="flex h-[150px] items-center border-b border-border bg-background px-5">
+                    {feature.preview}
                   </div>
 
-                  <h3 className="mt-6 text-xl font-bold">{feature.title}</h3>
+                  <div className="p-6">
+                    <div className="flex items-center gap-3">
+                      <span className="flex size-10 items-center justify-center rounded-[10px] bg-gradient-to-br from-edr-primary to-emerald-400 text-white shadow-md shadow-emerald-500/25 transition group-hover:scale-110">
+                        <Icon className="size-5" />
+                      </span>
+                      <h3 className="text-[19px] font-bold">{feature.title}</h3>
+                    </div>
 
-                  <p className="mt-3 leading-7 text-muted-foreground">
-                    {feature.description}
-                  </p>
-                </div>
-              );
-            })}
-          </div>
+                    <p className="mt-3 text-sm leading-relaxed text-muted-foreground">
+                      {feature.body}
+                    </p>
+
+                    <span className="mt-3 inline-flex items-center gap-1.5 text-[13px] font-semibold text-edr-primary">
+                      Learn more
+                      <ArrowRight className="size-3.5 transition group-hover:translate-x-1" />
+                    </span>
+                  </div>
+                </article>
+              </Reveal>
+            );
+          })}
+        </div>
+      </section>
+
+      {/* Showcase */}
+      <section id="showcase" className="mx-auto max-w-7xl scroll-mt-24 px-6 pb-20">
+        <div className="grid gap-14 lg:grid-cols-[1.15fr_1fr] lg:items-center">
+          <Reveal>
+            <div className="relative overflow-hidden rounded-3xl shadow-2xl">
+              <img
+                src="/assets/train-edr.jpg"
+                alt="Freight train hauling containers along the corridor"
+                loading="lazy"
+                className="h-[420px] w-full object-cover"
+              />
+
+              <div className="absolute inset-0 bg-gradient-to-t from-edr-ink/85 via-edr-ink/10 to-transparent" />
+
+              <div className="absolute left-6 top-6 flex items-center gap-2.5 rounded-xl bg-white/90 px-3.5 py-2.5 backdrop-blur">
+                <span className="edr-pulse-dot edr-pulse-dot--green" />
+                <span className="text-[13px] font-semibold">
+                  TS-14 · Awash → Mieso · 68 km/h
+                </span>
+              </div>
+
+              <div className="absolute inset-x-6 bottom-6 flex flex-wrap gap-7">
+                {[
+                  ["98.4%", "On-time"],
+                  ["312", "Wagons moving"],
+                  ["16h 20m", "Avg transit"],
+                ].map(([value, key]) => (
+                  <div key={key}>
+                    <p className="text-2xl font-bold text-white">{value}</p>
+                    <p className="text-xs text-slate-200">{key}</p>
+                  </div>
+                ))}
+              </div>
+            </div>
+          </Reveal>
+
+          <Reveal delay={140}>
+            <p className="text-xs font-bold tracking-[0.16em] text-edr-primary">
+              LIVE OPERATIONS
+            </p>
+            <h2 className="mt-3 text-4xl font-bold leading-tight tracking-tight">
+              See the whole train, not just a tracking number
+            </h2>
+            <p className="mt-4 text-base leading-relaxed text-muted-foreground">
+              GPS from every locomotive, wagon-level loading status, gate events at
+              Dewele customs and ETA that updates as the train moves. Shippers and
+              operators look at the same map.
+            </p>
+
+            <ul className="mt-7 space-y-3">
+              {[
+                { icon: Satellite, text: "Locomotive telemetry every 30 seconds" },
+                { icon: BellRing, text: "SMS & in-app alerts on gate and border events" },
+                { icon: MapIcon, text: "Shareable tracking link for your consignee" },
+              ].map((point) => {
+                const Icon = point.icon;
+
+                return (
+                  <li key={point.text} className="flex items-center gap-3">
+                    <span className="flex size-8 items-center justify-center rounded-lg bg-edr-soft text-edr-primary">
+                      <Icon className="size-4" />
+                    </span>
+                    <span className="text-[15px] font-medium">{point.text}</span>
+                  </li>
+                );
+              })}
+            </ul>
+          </Reveal>
         </div>
       </section>
 
       {/* Corridors */}
-      <section id="corridors" className="py-24">
+      <section id="corridors" className="scroll-mt-24 bg-edr-ink py-20">
         <div className="mx-auto max-w-7xl px-6">
-          <div className="grid gap-16 lg:grid-cols-2 lg:items-center">
-            <div>
-              <div className="inline-flex rounded-full bg-accent px-4 py-2 text-sm font-semibold text-primary">
-                Freight Corridors
-              </div>
+          <Reveal className="max-w-3xl">
+            <p className="text-xs font-bold tracking-[0.16em] text-emerald-400">
+              NETWORK
+            </p>
+            <h2 className="mt-3 text-4xl font-bold leading-tight tracking-tight text-white md:text-[44px]">
+              One line. Two countries. Every station on the timeline.
+            </h2>
+            <p className="mt-4 text-base leading-relaxed text-slate-300">
+              Standard-gauge, fully electrified. Book any origin–destination pair
+              along the corridor and see wagon position station by station.
+            </p>
+          </Reveal>
 
-              <h2 className="mt-6 text-4xl font-black tracking-tight">
-                Connected logistics infrastructure
-              </h2>
+          {/* Animated corridor */}
+          <Reveal delay={120} className="mt-14">
+            <div className="edr-corridor" aria-hidden>
+              <span className="edr-corridor-train" />
+              {stations.map((station) => (
+                <span
+                  key={station.name}
+                  className={`edr-corridor-node ${station.hub ? "is-hub" : "hidden lg:block"} ${
+                    station.border ? "is-border" : ""
+                  }`}
+                />
+              ))}
+            </div>
 
-              <p className="mt-5 text-lg leading-8 text-muted-foreground">
-                Efficiently move freight across strategic Ethiopia–Djibouti
-                railway corridors with operational visibility and optimized
-                transport coordination.
-              </p>
-
-              <div className="mt-10 grid gap-4 sm:grid-cols-2">
-                {corridors.map((corridor) => (
-                  <div
-                    key={corridor}
-                    className="flex items-center gap-3 rounded-2xl border border-border bg-card p-4 transition hover:border-primary/30 hover:bg-accent"
+            <div className="mt-3 flex justify-between gap-1 overflow-x-auto">
+              {stations.map((station) => (
+                <span
+                  key={station.name}
+                  className={`flex min-w-0 flex-col items-center text-center ${
+                    station.hub ? "" : "hidden lg:flex"
+                  }`}
+                >
+                  <span
+                    className={`whitespace-nowrap text-[11px] sm:text-[13px] ${
+                      station.hub ? "font-semibold text-white" : "text-slate-400"
+                    }`}
                   >
-                    <div className="size-3 rounded-full bg-primary" />
-
-                    <span className="font-medium">{corridor}</span>
-                  </div>
-                ))}
-              </div>
+                    {station.name}
+                  </span>
+                  {station.note ? (
+                    <span
+                      className={`whitespace-nowrap text-[11px] ${
+                        station.border ? "text-edr-accent" : "text-emerald-400"
+                      }`}
+                    >
+                      {station.note}
+                    </span>
+                  ) : null}
+                </span>
+              ))}
             </div>
+          </Reveal>
 
-            <div className="rounded-[32px] border border-border bg-card p-8 shadow-xl">
-              <div className="flex items-center justify-between">
-                <div>
-                  <p className="text-sm text-muted-foreground">
-                    Operational Insights
+          <div className="mt-12 grid gap-4 sm:grid-cols-2 xl:grid-cols-4">
+            {lanes.map((lane, index) => (
+              <Reveal key={lane.from + lane.to} delay={index * 90}>
+                <div className="h-full rounded-2xl border border-white/10 bg-white/5 p-5 transition duration-300 hover:-translate-y-1 hover:border-emerald-400/40 hover:bg-white/10">
+                  <p className="flex flex-wrap items-center gap-2 text-base font-bold text-white">
+                    {lane.from}
+                    <ArrowRight className="size-3.5 text-emerald-400" />
+                    {lane.to}
+                  </p>
+                  <p className="mt-2.5 text-[13px] text-slate-400">
+                    {lane.transit} transit · {lane.kind}
                   </p>
-
-                  <h3 className="mt-2 text-3xl font-bold">
-                    Freight Performance
-                  </h3>
                 </div>
-
-                <div className="rounded-2xl bg-primary/10 p-4 text-primary">
-                  <Users className="size-7" />
-                </div>
-              </div>
-
-              <div className="mt-10 space-y-6">
-                {[
-                  {
-                    label: "Bookings Processed",
-                    value: "9,842",
-                    progress: "92%",
-                  },
-                  {
-                    label: "On-time Shipments",
-                    value: "99%",
-                    progress: "99%",
-                  },
-                  {
-                    label: "Customer Satisfaction",
-                    value: "99%",
-                    progress: "99%",
-                  },
-                ].map((item) => (
-                  <div key={item.label}>
-                    <div className="mb-2 flex items-center justify-between">
-                      <span className="font-medium">{item.label}</span>
-
-                      <span className="text-muted-foreground">
-                        {item.value}
-                      </span>
-                    </div>
-
-                    <div className="h-3 overflow-hidden rounded-full bg-secondary">
-                      <div
-                        className="h-full rounded-full bg-primary transition-all duration-700"
-                        style={{ width: item.progress }}
-                      />
-                    </div>
-                  </div>
-                ))}
-              </div>
-
-              <div className="mt-10 rounded-3xl bg-accent p-6">
-                <div className="flex items-center gap-4">
-                  <div className="flex size-14 items-center justify-center rounded-2xl bg-primary text-primary-foreground">
-                    <CheckCircle2 className="size-7" />
-                  </div>
-
-                  <div>
-                    <h4 className="text-lg font-bold">
-                      Enterprise-ready Platform
-                    </h4>
-
-                    <p className="text-sm text-muted-foreground">
-                      Designed for large-scale freight and railway operations.
-                    </p>
-                  </div>
-                </div>
-              </div>
-            </div>
+              </Reveal>
+            ))}
           </div>
         </div>
       </section>
 
+      {/* How it works */}
+      <section id="how" className="mx-auto max-w-7xl scroll-mt-24 px-6 py-20">
+        <div className="grid gap-16 lg:grid-cols-[420px_1fr] lg:items-start">
+          <Reveal>
+            <p className="text-xs font-bold tracking-[0.16em] text-edr-primary">
+              HOW IT WORKS
+            </p>
+            <h2 className="mt-3 text-4xl font-bold leading-tight tracking-tight">
+              From booking to delivered in four steps
+            </h2>
+            <p className="mt-4 text-base leading-relaxed text-muted-foreground">
+              No phone calls, no paper manifests. Every party — shipper, shipping
+              line, transit agent and station — works from the same record.
+            </p>
+
+            <Link
+              to="/signup"
+              className="mt-7 inline-flex items-center gap-2 rounded-xl bg-edr-ink px-5 py-3 text-sm font-semibold text-white transition hover:-translate-y-0.5 hover:opacity-90"
+            >
+              Create a free account
+              <ArrowRight className="size-4" />
+            </Link>
+          </Reveal>
+
+          <div>
+            {steps.map((step, index) => (
+              <Reveal key={step.num} delay={index * 90}>
+                <div
+                  className={`flex gap-6 py-6 ${index ? "border-t border-border" : ""}`}
+                >
+                  <span className="text-sm font-bold text-edr-accent">
+                    {step.num}
+                  </span>
+
+                  <div>
+                    <h3 className="text-xl font-bold">{step.title}</h3>
+                    <p className="mt-1.5 text-[15px] leading-relaxed text-muted-foreground">
+                      {step.body}
+                    </p>
+                  </div>
+                </div>
+              </Reveal>
+            ))}
+          </div>
+        </div>
+      </section>
+
+      {/* Audiences */}
+      <section className="mx-auto max-w-7xl px-6 pb-20">
+        <Reveal>
+          <h2 className="text-[32px] font-bold tracking-tight">
+            Built for everyone on the corridor
+          </h2>
+        </Reveal>
+
+        <div className="mt-10 grid gap-6 sm:grid-cols-2 xl:grid-cols-4">
+          {audiences.map((audience, index) => {
+            const Icon = audience.icon;
+
+            return (
+              <Reveal key={audience.title} delay={index * 90}>
+                <div className="h-full rounded-2xl border border-border bg-card p-7 transition duration-300 hover:-translate-y-1.5 hover:border-edr-primary/30 hover:shadow-xl">
+                  <Icon className="size-7 text-edr-primary" />
+                  <h3 className="mt-4 text-lg font-bold">{audience.title}</h3>
+                  <p className="mt-2 text-sm leading-relaxed text-muted-foreground">
+                    {audience.body}
+                  </p>
+
+                  <ul className="mt-4 space-y-2">
+                    {audience.items.map((item) => (
+                      <li key={item} className="flex items-center gap-2">
+                        <Check className="size-3.5 shrink-0 text-edr-primary" />
+                        <span className="text-[13px] font-medium">{item}</span>
+                      </li>
+                    ))}
+                  </ul>
+                </div>
+              </Reveal>
+            );
+          })}
+        </div>
+      </section>
+
       {/* Contact */}
-      <section id="contact" className="border-t border-border bg-card/40 py-24">
-        <div className="mx-auto max-w-7xl px-6">
-          <div className="grid gap-12 lg:grid-cols-2">
-            <div>
-              <div className="inline-flex rounded-full bg-accent px-4 py-2 text-sm font-semibold text-primary">
-                Contact Us
-              </div>
+      <section id="contact" className="scroll-mt-24 border-t border-border bg-card/40 py-20">
+        <div className="mx-auto grid max-w-7xl gap-12 px-6 lg:grid-cols-2">
+          <Reveal>
+            <p className="text-xs font-bold tracking-[0.16em] text-edr-primary">
+              CONTACT
+            </p>
+            <h2 className="mt-3 text-4xl font-bold leading-tight tracking-tight">
+              Let’s move freight smarter
+            </h2>
+            <p className="mt-4 text-base leading-relaxed text-muted-foreground">
+              Contact EDR Freight for partnership opportunities, enterprise
+              onboarding, or logistics support.
+            </p>
 
-              <h2 className="mt-6 text-4xl font-black tracking-tight">
-                Let’s move freight smarter
-              </h2>
+            <div className="mt-8 space-y-4">
+              {[
+                { icon: Mail, label: "Email", value: "support@edrfreight.com" },
+                { icon: Phone, label: "Phone", value: "+251 11 000 0000" },
+                { icon: MapPin, label: "Head Office", value: "Addis Ababa, Ethiopia" },
+              ].map((row) => {
+                const Icon = row.icon;
 
-              <p className="mt-5 text-lg leading-8 text-muted-foreground">
-                Contact EDR Freight for partnership opportunities, enterprise
-                onboarding, or logistics support.
-              </p>
-
-              <div className="mt-10 space-y-5">
-                <div className="flex items-center gap-4 rounded-2xl border border-border bg-background p-5">
-                  <div className="rounded-2xl bg-accent p-3 text-primary">
-                    <Mail className="size-5" />
+                return (
+                  <div
+                    key={row.label}
+                    className="flex items-center gap-4 rounded-2xl border border-border bg-background p-5 transition hover:border-edr-primary/30"
+                  >
+                    <span className="rounded-xl bg-edr-soft p-3 text-edr-primary">
+                      <Icon className="size-5" />
+                    </span>
+                    <div>
+                      <p className="font-semibold">{row.label}</p>
+                      <p className="text-muted-foreground">{row.value}</p>
+                    </div>
                   </div>
-
-                  <div>
-                    <p className="font-semibold">Email</p>
-                    <p className="text-muted-foreground">
-                      support@edrfreight.com
-                    </p>
-                  </div>
-                </div>
-
-                <div className="flex items-center gap-4 rounded-2xl border border-border bg-background p-5">
-                  <div className="rounded-2xl bg-accent p-3 text-primary">
-                    <Phone className="size-5" />
-                  </div>
-
-                  <div>
-                    <p className="font-semibold">Phone</p>
-                    <p className="text-muted-foreground">+251 11 000 0000</p>
-                  </div>
-                </div>
-
-                <div className="flex items-center gap-4 rounded-2xl border border-border bg-background p-5">
-                  <div className="rounded-2xl bg-accent p-3 text-primary">
-                    <MapPin className="size-5" />
-                  </div>
-
-                  <div>
-                    <p className="font-semibold">Head Office</p>
-                    <p className="text-muted-foreground">
-                      Addis Ababa, Ethiopia
-                    </p>
-                  </div>
-                </div>
-              </div>
+                );
+              })}
             </div>
+          </Reveal>
 
-            {/* Contact Form */}
-            <div className="rounded-[32px] border border-border bg-card p-8 shadow-xl">
+          <Reveal delay={140}>
+            <div className="rounded-3xl border border-border bg-card p-8 shadow-xl">
               <h3 className="text-2xl font-bold">Send us a message</h3>
-
               <p className="mt-2 text-muted-foreground">
                 We’ll get back to you as soon as possible.
               </p>
@@ -504,117 +1129,359 @@ export default function EDRFreightLandingPage() {
                 <input
                   type="text"
                   placeholder="Full Name"
-                  className="h-12 w-full rounded-2xl border border-input bg-background px-4 outline-none transition focus:border-primary focus:ring-4 focus:ring-primary/10"
+                  className="h-12 w-full rounded-2xl border border-input bg-background px-4 outline-none transition focus:border-edr-primary focus:ring-4 focus:ring-emerald-500/10"
                 />
 
                 <input
                   type="email"
                   placeholder="Email Address"
-                  className="h-12 w-full rounded-2xl border border-input bg-background px-4 outline-none transition focus:border-primary focus:ring-4 focus:ring-primary/10"
+                  className="h-12 w-full rounded-2xl border border-input bg-background px-4 outline-none transition focus:border-edr-primary focus:ring-4 focus:ring-emerald-500/10"
                 />
 
                 <textarea
                   rows={5}
                   placeholder="Write your message..."
-                  className="w-full rounded-2xl border border-input bg-background px-4 py-3 outline-none transition focus:border-primary focus:ring-4 focus:ring-primary/10"
+                  className="w-full rounded-2xl border border-input bg-background px-4 py-3 outline-none transition focus:border-edr-primary focus:ring-4 focus:ring-emerald-500/10"
                 />
 
-                <button className="flex w-full items-center justify-center gap-2 rounded-2xl bg-primary px-6 py-3 font-semibold text-primary-foreground shadow-lg transition hover:opacity-90">
+                <button
+                  type="button"
+                  className="flex w-full items-center justify-center gap-2 rounded-2xl bg-edr-primary px-6 py-3 font-semibold text-white shadow-lg transition hover:-translate-y-0.5 hover:bg-edr-primary-dark"
+                >
                   Send Message
                   <ArrowRight className="size-5" />
                 </button>
               </div>
             </div>
-          </div>
+          </Reveal>
         </div>
       </section>
 
       {/* CTA */}
-      <section className="border-t border-border py-24">
-        <div className="mx-auto max-w-5xl px-6">
-          <div className="rounded-[40px] bg-primary px-8 py-16 text-center text-primary-foreground shadow-2xl md:px-16">
-            <div className="mx-auto max-w-3xl">
-              <div className="inline-flex rounded-full bg-white/10 px-4 py-2 text-sm font-semibold">
-                EDR Freight Platform
-              </div>
-
-              <h2 className="mt-6 text-5xl font-black tracking-tight">
-                Transform railway freight operations
+      <section className="mx-auto max-w-7xl px-6 py-20">
+        <Reveal>
+          <div className="edr-cta flex flex-col items-start justify-between gap-8 rounded-3xl px-10 py-14 lg:flex-row lg:items-center lg:px-16">
+            <div className="max-w-2xl">
+              <h2 className="text-4xl font-bold leading-tight tracking-tight text-white">
+                Ready to put your cargo on the rails?
               </h2>
-
-              <p className="mt-6 text-lg leading-8 opacity-85">
-                Centralize logistics workflows, optimize freight movement, and
-                gain real-time operational visibility across all railway
-                corridors.
+              <p className="mt-3 text-base leading-relaxed text-emerald-50/85">
+                Create a shipper account in minutes, or talk to our team about
+                shipping-line and enterprise contracts.
               </p>
+            </div>
 
-              <div className="mt-10 flex flex-wrap items-center justify-center gap-4">
-                <Link
-                  to="/signup"
-                  className="flex items-center gap-2 rounded-2xl bg-white px-7 py-3 font-semibold text-primary shadow-lg transition hover:opacity-90"
-                >
-                  Create Account
-                  <ArrowRight className="size-5" />
-                </Link>
+            <div className="flex flex-wrap gap-3">
+              <Link
+                to="/signup"
+                className="flex items-center gap-2 rounded-xl bg-white px-6 py-3.5 font-semibold text-edr-ink shadow-lg transition hover:-translate-y-0.5"
+              >
+                Get started
+                <ArrowRight className="size-4.5" />
+              </Link>
 
-                <Link
-                  to="/login"
-                  className="rounded-2xl border border-white/20 bg-white/10 px-7 py-3 font-semibold backdrop-blur transition hover:bg-white/20"
-                >
-                  Sign In
-                </Link>
-              </div>
+              <a
+                href="#contact"
+                className="rounded-xl border border-white/40 px-6 py-3.5 font-medium text-white transition hover:bg-white/10"
+              >
+                Contact sales
+              </a>
             </div>
           </div>
-        </div>
+        </Reveal>
       </section>
 
       {/* Footer */}
-      <footer className="border-t border-border py-8">
-        <div className="mx-auto flex max-w-7xl flex-col items-center justify-between gap-4 px-6 text-sm text-muted-foreground md:flex-row">
-          <div className="flex items-center gap-3">
-            <div className="flex size-10 items-center justify-center rounded-2xl bg-primary text-primary-foreground">
-              <Train className="size-5" />
+      <footer className="bg-edr-ink pb-8 pt-14 text-slate-400">
+        <div className="mx-auto max-w-7xl px-6">
+          <div className="flex flex-col justify-between gap-12 lg:flex-row">
+            <div className="max-w-sm">
+              <div className="flex items-center gap-2.5">
+                <span className="flex size-8 items-center justify-center rounded-lg bg-edr-primary text-white">
+                  <TrainFront className="size-4" />
+                </span>
+                <span className="text-lg font-bold text-white">EDR Freight</span>
+              </div>
+
+              <p className="mt-3.5 text-sm leading-relaxed">
+                The digital freight platform of the Ethio-Djibouti Railway.
+                Booking, tracking, customs and billing on the 752 km
+                standard-gauge corridor.
+              </p>
+
+              <div className="mt-4 space-y-1.5 text-[13px]">
+                {[
+                  { icon: Phone, text: "+251 11 000 0000" },
+                  { icon: Mail, text: "freight@edr.et" },
+                  { icon: MapPin, text: "EDR Head Office, Addis Ababa" },
+                ].map((row) => {
+                  const Icon = row.icon;
+
+                  return (
+                    <p key={row.text} className="flex items-center gap-2">
+                      <Icon className="size-3.5 text-emerald-400" />
+                      {row.text}
+                    </p>
+                  );
+                })}
+              </div>
             </div>
 
-            <div>
-              <p className="font-semibold text-foreground">EDR Freight</p>
+            <div className="grid flex-1 gap-10 sm:grid-cols-2 lg:max-w-2xl lg:grid-cols-4">
+              {[
+                {
+                  head: "Product",
+                  items: [
+                    "Consignment booking",
+                    "Live tracking",
+                    "Customs documents",
+                    "Billing & payments",
+                  ],
+                },
+                {
+                  head: "Customers",
+                  items: ["Shippers", "Shipping lines", "Transit agents", "EDR operations"],
+                },
+                {
+                  head: "Company",
+                  items: ["About EDR", "Support", "Contact"],
+                  links: [
+                    { label: "Help & Support", to: "/help" },
+                    { label: "FAQ", to: "/faq" },
+                  ],
+                },
+                {
+                  head: "Legal",
+                  links: [
+                    { label: "Terms of Service", to: "/terms" },
+                    { label: "Privacy Policy", to: "/privacy" },
+                  ],
+                },
+              ].map((column) => (
+                <div key={column.head}>
+                  <p className="text-[13px] font-bold text-white">{column.head}</p>
 
-              <p>Modern railway logistics management platform</p>
+                  <ul className="mt-3 space-y-2.5 text-sm">
+                    {column.items?.map((item) => (
+                      <li key={item}>{item}</li>
+                    ))}
+                    {column.links?.map((link) => (
+                      <li key={link.to}>
+                        <Link to={link.to} className="transition hover:text-white">
+                          {link.label}
+                        </Link>
+                      </li>
+                    ))}
+                  </ul>
+                </div>
+              ))}
             </div>
           </div>
 
-          <div className="flex flex-col items-center gap-4 md:items-end">
-            <nav className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2">
-              <Link
-                to="/help"
-                className="font-semibold text-foreground transition-colors hover:text-primary"
-              >
-                Help &amp; Support
-              </Link>
-              <Link
-                to="/faq"
-                className="font-semibold text-foreground transition-colors hover:text-primary"
-              >
-                FAQ
-              </Link>
-              <Link
-                to="/privacy"
-                className="font-semibold text-foreground transition-colors hover:text-primary"
-              >
-                Privacy Policy
-              </Link>
-              <Link
-                to="/terms"
-                className="font-semibold text-foreground transition-colors hover:text-primary"
-              >
-                Terms of Service
-              </Link>
-            </nav>
-            <div>© 2026 EDR Freight. All rights reserved.</div>
+          <div className="mt-12 flex flex-col items-center justify-between gap-3 border-t border-white/10 pt-6 text-[13px] md:flex-row">
+            <p>© 2026 Ethio-Djibouti Railway · EDR Freight. All rights reserved.</p>
+            <p className="flex gap-4">
+              <span>English</span>
+              <span>አማርኛ</span>
+              <span>Français</span>
+            </p>
           </div>
         </div>
       </footer>
     </div>
   );
 }
+
+/* ------------------------------------------------------------------ */
+/* Scoped animation styles                                             */
+/* ------------------------------------------------------------------ */
+
+function LandingStyles() {
+  return (
+    <style>{`
+.edr-reveal {
+  opacity: 0;
+  transform: translateY(24px);
+  transition: opacity .7s cubic-bezier(.16,1,.3,1), transform .7s cubic-bezier(.16,1,.3,1);
+}
+.edr-reveal.is-visible { opacity: 1; transform: none; }
+
+/* Hero: rail streaks racing toward the horizon */
+.edr-rails {
+  position: absolute;
+  inset: 0;
+  background-image: repeating-linear-gradient(
+    100deg,
+    transparent 0 46px,
+    rgba(52,211,153,.16) 46px 48px
+  );
+  mask-image: radial-gradient(120% 90% at 78% 40%, #000 0%, transparent 70%);
+  animation: edr-rails 9s linear infinite;
+}
+@keyframes edr-rails { to { background-position: 480px 0; } }
+
+.edr-hero-glow {
+  position: absolute;
+  inset: 0;
+  background:
+    radial-gradient(46% 60% at 12% 22%, rgba(10,138,95,.45), transparent 70%),
+    radial-gradient(40% 55% at 88% 82%, rgba(242,165,22,.22), transparent 70%);
+  animation: edr-breathe 11s ease-in-out infinite;
+}
+@keyframes edr-breathe {
+  0%, 100% { opacity: .75; transform: scale(1); }
+  50% { opacity: 1; transform: scale(1.06); }
+}
+
+.edr-float { animation: edr-float 7s ease-in-out infinite; }
+@keyframes edr-float {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-10px); }
+}
+
+/* Pulsing live dot */
+.edr-pulse-dot {
+  position: relative;
+  display: inline-block;
+  width: .5rem;
+  height: .5rem;
+  border-radius: 9999px;
+  background: #34d399;
+}
+.edr-pulse-dot--green { background: #0a8a5f; }
+.edr-pulse-dot::after {
+  content: "";
+  position: absolute;
+  inset: -3px;
+  border-radius: 9999px;
+  border: 2px solid currentColor;
+  color: inherit;
+  background: inherit;
+  opacity: .55;
+  animation: edr-ping 1.8s cubic-bezier(0,0,.2,1) infinite;
+}
+.edr-ping { position: relative; }
+.edr-ping::after {
+  content: "";
+  position: absolute;
+  inset: -4px;
+  border-radius: 9999px;
+  background: currentColor;
+  opacity: .35;
+  animation: edr-ping 1.8s cubic-bezier(0,0,.2,1) infinite;
+}
+@keyframes edr-ping {
+  0% { transform: scale(.6); opacity: .6; }
+  80%, 100% { transform: scale(2.1); opacity: 0; }
+}
+
+/* Corridor rail with a train travelling along it */
+.edr-corridor {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: 18px;
+}
+.edr-corridor::before {
+  content: "";
+  position: absolute;
+  left: 0; right: 0; top: 50%;
+  height: 2px;
+  transform: translateY(-50%);
+  background: rgba(52,211,153,.28);
+}
+.edr-corridor-node {
+  position: relative;
+  z-index: 1;
+  width: 10px; height: 10px;
+  border-radius: 9999px;
+  background: #10202f;
+  border: 2px solid #34d399;
+}
+.edr-corridor-node.is-hub { width: 16px; height: 16px; background: #34d399; }
+.edr-corridor-node.is-border { background: #f2a516; border-color: #f2a516; }
+.edr-corridor-train {
+  position: absolute;
+  top: 50%;
+  left: 0;
+  width: 74px; height: 4px;
+  transform: translateY(-50%);
+  border-radius: 9999px;
+  background: linear-gradient(90deg, transparent, #f2a516);
+  box-shadow: 0 0 18px 3px rgba(242,165,22,.55);
+  animation: edr-run 12s linear infinite;
+}
+@keyframes edr-run {
+  0% { left: -6%; }
+  100% { left: 100%; }
+}
+
+/* Mini track inside the GPS feature preview */
+.edr-minitrack {
+  position: relative;
+  height: 14px;
+  border-radius: 9999px;
+}
+.edr-minitrack::before {
+  content: "";
+  position: absolute;
+  left: 0; right: 0; top: 50%;
+  height: 2px;
+  transform: translateY(-50%);
+  background: #c9e9db;
+  border-radius: 9999px;
+}
+.edr-minitrack-dot {
+  position: absolute;
+  top: 50%;
+  width: 9px; height: 9px;
+  margin-top: -4.5px;
+  border-radius: 9999px;
+  background: #0a8a5f;
+  box-shadow: 0 0 0 4px rgba(10,138,95,.18), 0 0 14px 2px rgba(10,138,95,.5);
+  animation: edr-run-dot 6s ease-in-out infinite;
+}
+@keyframes edr-run-dot {
+  0%, 8% { left: 0%; }
+  92%, 100% { left: calc(100% - 9px); }
+}
+
+.edr-dashline {
+  background-image: linear-gradient(90deg, #c9e9db 0 6px, transparent 6px 12px);
+  background-size: 12px 2px;
+  animation: edr-dash 1.4s linear infinite;
+}
+@keyframes edr-dash { to { background-position: 12px 0; } }
+
+/* Bars growing from the baseline once revealed */
+.edr-grow {
+  transform-origin: bottom;
+  animation: edr-grow .8s cubic-bezier(.16,1,.3,1) both;
+}
+@keyframes edr-grow { from { transform: scaleY(0); } to { transform: scaleY(1); } }
+
+.edr-fade-in { animation: edr-fade-in .5s ease-out both; }
+@keyframes edr-fade-in { from { opacity: 0; transform: scale(.8); } to { opacity: 1; transform: none; } }
+
+/* CTA band: slowly drifting gradient */
+.edr-cta {
+  background: linear-gradient(120deg, #0a6f4d, #0c1a2b 45%, #0a8a5f 75%, #0c1a2b);
+  background-size: 280% 280%;
+  animation: edr-shift 16s ease infinite;
+}
+@keyframes edr-shift {
+  0%, 100% { background-position: 0% 50%; }
+  50% { background-position: 100% 50%; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .edr-reveal { opacity: 1; transform: none; transition: none; }
+  .edr-rails, .edr-hero-glow, .edr-float, .edr-pulse-dot::after, .edr-ping::after,
+  .edr-corridor-train, .edr-minitrack-dot, .edr-dashline, .edr-grow, .edr-fade-in, .edr-cta {
+    animation: none !important;
+  }
+}
+    `}</style>
+  );
+}

From 8a2b9306dceab70ba272fc566ab184265745fef5 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Thu, 20 Aug 2026 03:59:14 +0000
Subject: [PATCH 171/174] feat(bookings): show per-document upload/review audit
 and download icon on clearance detail

---
 .../detail/ClearanceReviewSection.tsx         | 33 +++++++++++++++++++
 1 file changed, 33 insertions(+)

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 501e074e2..e4e78f462 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
@@ -31,6 +31,7 @@ import type { Freight } from "@edr/types";
 import { isViewable } from "@edr/ui-common";
 
 import { SectionCard } from "./SectionCard";
+import { formatDateTime } from "@/lib/format";
 import { bookingsService } from "@/services/bookings.service";
 import {
   downloadBookingFile,
@@ -550,6 +551,11 @@ function DocReviewCard({
             <Text fz="12px" c="edr-muted" truncate>
               {hasFile ? doc.file!.name : "Not uploaded by customer"}
             </Text>
+            {hasFile && doc.uploadedAt ? (
+              <Text fz="11px" c="dimmed">
+                Uploaded {formatDateTime(doc.uploadedAt)}
+              </Text>
+            ) : null}
           </Box>
         </Group>
 
@@ -578,9 +584,36 @@ function DocReviewCard({
                 </Button>
               </Tooltip>
             )}
+          {hasFile && (
+            <Tooltip label="Download">
+              <Box
+                component="button"
+                type="button"
+                onClick={() =>
+                  void downloadBookingFile(doc.file!.id, doc.file!.name)
+                }
+                c="edr-green"
+                style={{
+                  display: "flex",
+                  background: "transparent",
+                  border: "none",
+                  cursor: "pointer",
+                }}
+              >
+                <Download size={15} />
+              </Box>
+            </Tooltip>
+          )}
         </Group>
       </Group>
 
+      {doc.reviewedAt && (status === "APPROVED" || status === "QUERIED") && (
+        <Text fz="11.5px" c="dimmed" mt={6}>
+          {status === "APPROVED" ? "Approved" : "Queried"} by{" "}
+          {doc.reviewedByName ?? "staff"} · {formatDateTime(doc.reviewedAt)}
+        </Text>
+      )}
+
       {status === "QUERIED" && doc.note && (
         <Alert
           mt="sm"

From a58157a7ee82fd0fc1f6a60b9f471f2fb8d9cb5c Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Thu, 20 Aug 2026 04:03:27 +0000
Subject: [PATCH 172/174] feat(bookings): show per-document upload/review audit
 and download icon on clearance detail

---
 .../bookings/booking-transition.service.ts       | 16 ++++++++++++++++
 .../src/modules/bookings/bookings.repository.ts  |  8 ++++++++
 .../contracts/booking-clearance.service.ts       | 16 ++++++++++++++++
 packages/types/src/freight/index.ts              |  6 ++++++
 4 files changed, 46 insertions(+)

diff --git a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
index 41e8fc78b..acbd857cd 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
@@ -627,6 +627,9 @@ export class BookingTransitionService {
       file: { id: string; name: string; url: string } | null;
       reviewStatus: "PENDING" | "APPROVED" | "QUERIED" | null;
       note: string | null;
+      uploadedAt: string | null;
+      reviewedAt: string | null;
+      reviewedByName: string | null;
     }>;
     allApproved: boolean;
     phase?: string | null;
@@ -652,6 +655,9 @@ export class BookingTransitionService {
     const reviewByKey = new Map(
       reviews.map((r) => [`${r.settingCode}:${r.fileKey}`, r]),
     );
+    const reviewerNames = await this.bookingsRepository.resolveStaffNames(
+      reviews.map((r) => r.reviewedByStaffId),
+    );
 
     const documents: Awaited<
       ReturnType<BookingTransitionService["getClearanceView"]>
@@ -680,6 +686,11 @@ export class BookingTransitionService {
           file: file ? { id: file.id, name: file.name, url: file.url } : null,
           reviewStatus: review?.status ?? null,
           note: review?.note ?? null,
+          uploadedAt: file?.createdAt ? file.createdAt.toISOString() : null,
+          reviewedAt: review?.reviewedAt ? review.reviewedAt.toISOString() : null,
+          reviewedByName: review?.reviewedByStaffId
+            ? (reviewerNames.get(review.reviewedByStaffId) ?? null)
+            : null,
         });
       }
     };
@@ -700,6 +711,11 @@ export class BookingTransitionService {
         file: { id: f.id, name: f.name, url: f.url },
         reviewStatus: review?.status ?? null,
         note: review?.note ?? null,
+        uploadedAt: f.createdAt ? f.createdAt.toISOString() : null,
+        reviewedAt: review?.reviewedAt ? review.reviewedAt.toISOString() : null,
+        reviewedByName: review?.reviewedByStaffId
+          ? (reviewerNames.get(review.reviewedByStaffId) ?? null)
+          : null,
       });
     }
 
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
index 7b042e0c7..b3ae07861 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.repository.ts
@@ -13,6 +13,7 @@ import {
 } from 'typeorm';
 
 import { computeFacets, FacetBucket } from '../../common/utils/facets.util';
+import { resolveIamUserNames } from '../../common/utils/iam-user-name.util';
 import { wagonsPerUnitForSize } from '../rule-engine/container-type.util';
 import { ContainerType } from '../rule-engine/entities/container-type.entity';
 import { Contract } from '../contracts/entities/contract.entity';
@@ -660,6 +661,13 @@ export class BookingsRepository extends BaseRepository<Booking> {
     await repo.save(repo.create({ ...input, status: 'PENDING' }));
   }
 
+  /** Display names for reviewer staff ids — one query for the whole set. */
+  async resolveStaffNames(
+    staffIds: (string | null | undefined)[],
+  ): Promise<Map<string, string>> {
+    return resolveIamUserNames(this.dataSource, staffIds);
+  }
+
   /** GL marks a document APPROVED or QUERIED (with an optional note). */
   async setDocumentReviewStatus(
     bookingId: string,
diff --git a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
index 4b53f4dee..5ce4183ab 100644
--- a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
@@ -52,6 +52,9 @@ export interface BookingClearanceView {
     file: { id: string; name: string; url: string } | null;
     reviewStatus: 'PENDING' | 'APPROVED' | 'QUERIED' | null;
     note: string | null;
+    uploadedAt: string | null;
+    reviewedAt: string | null;
+    reviewedByName: string | null;
   }>;
   allApproved: boolean;
   phase?: string | null;
@@ -185,6 +188,9 @@ export class BookingClearanceService {
     const fileByCode = new Map(files.map((f) => [f.code, f]));
     const reviews = await this.bookingsRepository.findDocumentReviews(bookingId);
     const reviewByKey = new Map(reviews.map((r) => [`${r.settingCode}:${r.fileKey}`, r]));
+    const reviewerNames = await this.bookingsRepository.resolveStaffNames(
+      reviews.map((r) => r.reviewedByStaffId),
+    );
 
     const documents: BookingClearanceView['documents'] = [];
 
@@ -208,6 +214,11 @@ export class BookingClearanceService {
           file: file ? { id: file.id, name: file.name, url: file.url } : null,
           reviewStatus: review?.status ?? null,
           note: review?.note ?? null,
+          uploadedAt: file?.createdAt ? file.createdAt.toISOString() : null,
+          reviewedAt: review?.reviewedAt ? review.reviewedAt.toISOString() : null,
+          reviewedByName: review?.reviewedByStaffId
+            ? (reviewerNames.get(review.reviewedByStaffId) ?? null)
+            : null,
         });
       }
     };
@@ -227,6 +238,11 @@ export class BookingClearanceService {
         file: { id: f.id, name: f.name, url: f.url },
         reviewStatus: review?.status ?? null,
         note: review?.note ?? null,
+        uploadedAt: f.createdAt ? f.createdAt.toISOString() : null,
+        reviewedAt: review?.reviewedAt ? review.reviewedAt.toISOString() : null,
+        reviewedByName: review?.reviewedByStaffId
+          ? (reviewerNames.get(review.reviewedByStaffId) ?? null)
+          : null,
       });
     }
 
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index 3ed0ec903..d236eb03b 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -813,6 +813,12 @@ export interface ClearanceDocument {
   file: { id: string; name: string; url: string } | null;
   reviewStatus: DocumentReviewStatus | null;
   note: string | null;
+  /** When the current file version was uploaded — a re-upload (query response) refreshes it. */
+  uploadedAt?: string | null;
+  /** When the latest review decision (approve/query) was recorded. */
+  reviewedAt?: string | null;
+  /** Display name of the staff member who recorded the decision. */
+  reviewedByName?: string | null;
 }
 
 /**

From 4adb53b4860e39f19d08f8986403e0d0407783dc Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Thu, 20 Aug 2026 04:27:16 +0000
Subject: [PATCH 173/174] fix issue

---
 .../bookings/booking-transition.service.ts    | 32 ++++++-
 .../bookings/clearance-doc-history.util.ts    | 74 ++++++++++++++++
 .../contracts/booking-clearance.service.ts    | 33 +++++++-
 .../src/modules/files/files.repository.ts     | 15 ++++
 .../src/modules/files/files.service.ts        |  8 ++
 .../detail/ClearanceReviewSection.tsx         | 84 ++++++++++++++++---
 packages/types/src/freight/index.ts           | 12 +++
 7 files changed, 244 insertions(+), 14 deletions(-)
 create mode 100644 apps/edr-freight-api/src/modules/bookings/clearance-doc-history.util.ts

diff --git a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
index acbd857cd..3dddb3bc1 100644
--- a/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
@@ -28,6 +28,10 @@ import { ContainerValidationService } from './container-validation.service';
 import { BookingsRepository } from './bookings.repository';
 import { assertBookingStatus } from './booking-status.util';
 import { clearanceCodesForBooking } from './clearance.util';
+import {
+  buildClearanceDocHistory,
+  type ClearanceDocEvent,
+} from './clearance-doc-history.util';
 import { computeNextStep, type BookingNextStep } from './booking-next-step.util';
 import { SubmitBookingResponseDto } from './dto/submit-booking-response.dto';
 import { PriceLineItemDto } from './dto/generate-price-response.dto';
@@ -630,6 +634,7 @@ export class BookingTransitionService {
       uploadedAt: string | null;
       reviewedAt: string | null;
       reviewedByName: string | null;
+      history: ClearanceDocEvent[];
     }>;
     allApproved: boolean;
     phase?: string | null;
@@ -655,9 +660,18 @@ export class BookingTransitionService {
     const reviewByKey = new Map(
       reviews.map((r) => [`${r.settingCode}:${r.fileKey}`, r]),
     );
-    const reviewerNames = await this.bookingsRepository.resolveStaffNames(
-      reviews.map((r) => r.reviewedByStaffId),
+    const allVersions = await this.filesService.findAllVersionsByResource(
+      bookingId,
+      "bookings",
     );
+    const queryNotes = await this.bookingsRepository.findReviewNotes(
+      bookingId,
+      "CHANGES_REQUESTED",
+    );
+    const reviewerNames = await this.bookingsRepository.resolveStaffNames([
+      ...reviews.map((r) => r.reviewedByStaffId),
+      ...queryNotes.map((n) => n.authorId),
+    ]);
 
     const documents: Awaited<
       ReturnType<BookingTransitionService["getClearanceView"]>
@@ -691,6 +705,13 @@ export class BookingTransitionService {
           reviewedByName: review?.reviewedByStaffId
             ? (reviewerNames.get(review.reviewedByStaffId) ?? null)
             : null,
+          history: buildClearanceDocHistory({
+            fileKey: field.fileKey,
+            allVersions,
+            queryNotes,
+            review,
+            names: reviewerNames,
+          }),
         });
       }
     };
@@ -716,6 +737,13 @@ export class BookingTransitionService {
         reviewedByName: review?.reviewedByStaffId
           ? (reviewerNames.get(review.reviewedByStaffId) ?? null)
           : null,
+        history: buildClearanceDocHistory({
+          fileKey: f.code,
+          allVersions,
+          queryNotes,
+          review,
+          names: reviewerNames,
+        }),
       });
     }
 
diff --git a/apps/edr-freight-api/src/modules/bookings/clearance-doc-history.util.ts b/apps/edr-freight-api/src/modules/bookings/clearance-doc-history.util.ts
new file mode 100644
index 000000000..e86c8f644
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/clearance-doc-history.util.ts
@@ -0,0 +1,74 @@
+import type { BookingDocumentReview } from './entities/booking-document-review.entity';
+import type { BookingReviewNote } from './entities/booking-review-note.entity';
+import type { FileRecord } from '../files/entities/file.entity';
+
+/** One entry of a clearance document's per-card audit trail, oldest first. */
+export interface ClearanceDocEvent {
+  type: 'UPLOADED' | 'RESUBMITTED' | 'QUERIED' | 'APPROVED';
+  at: string;
+  byName: string | null;
+  note: string | null;
+}
+
+/**
+ * Query review notes are written as `Document "<fileKey>" queried: <note>`
+ * (see BookingTransitionService.reviewDocument) — the only place a past query
+ * decision survives after the customer re-uploads and the review row resets.
+ */
+const QUERY_NOTE_RE = /^Document "(.+?)" queried: ([\s\S]*)$/;
+
+/**
+ * Per-document audit trail assembled from data the flow already persists:
+ * every stored file version (first = customer upload, later ones = the
+ * customer's amendment responses), every query note (who opened it, when,
+ * why), and the review row's current approval. Approvals that were later
+ * reset by a re-upload are the one thing not kept anywhere — the trail shows
+ * the decision that currently stands.
+ */
+export function buildClearanceDocHistory(input: {
+  fileKey: string;
+  /** All versions of all files on the booking, createdAt ASC, deleted included. */
+  allVersions: FileRecord[];
+  /** CHANGES_REQUESTED review notes for the booking. */
+  queryNotes: BookingReviewNote[];
+  review: BookingDocumentReview | null;
+  /** staff id → display name. */
+  names: Map<string, string>;
+}): ClearanceDocEvent[] {
+  const { fileKey, allVersions, queryNotes, review, names } = input;
+  const events: ClearanceDocEvent[] = [];
+
+  const versions = allVersions.filter((v) => v.code === fileKey);
+  versions.forEach((v, i) => {
+    events.push({
+      type: i === 0 ? 'UPLOADED' : 'RESUBMITTED',
+      at: v.createdAt.toISOString(),
+      byName: v.uploadedByName ?? null,
+      note: null,
+    });
+  });
+
+  for (const n of queryNotes) {
+    const m = QUERY_NOTE_RE.exec(n.note);
+    if (!m || m[1] !== fileKey) continue;
+    events.push({
+      type: 'QUERIED',
+      at: n.createdAt.toISOString(),
+      byName: n.authorId ? (names.get(n.authorId) ?? null) : null,
+      note: m[2] || null,
+    });
+  }
+
+  if (review?.status === 'APPROVED' && review.reviewedAt) {
+    events.push({
+      type: 'APPROVED',
+      at: review.reviewedAt.toISOString(),
+      byName: review.reviewedByStaffId
+        ? (names.get(review.reviewedByStaffId) ?? null)
+        : null,
+      note: null,
+    });
+  }
+
+  return events.sort((a, b) => a.at.localeCompare(b.at));
+}
diff --git a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
index 5ce4183ab..b63aad054 100644
--- a/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
@@ -35,6 +35,11 @@ import { ContractsRepository } from './contracts.repository';
 import { AdviseContractDutyDto } from './dto/phased-clearance.dto';
 import { buildWorkflowFiles, belongsOnDjClearanceQueue, belongsOnEtClearanceQueue, DJ_BOOKING_QUEUE_STATUSES, persistDeclarationUploads, persistDeliveryOrderUploads, persistDraftDeclarationUploads, persistReleaseOrderUploads, persistTransitPermitUploads, PHASED_CUSTOMS_BOOKING_QUEUE_STATUSES } from './phased-clearance.util';
 
+import {
+  buildClearanceDocHistory,
+  type ClearanceDocEvent,
+} from '../bookings/clearance-doc-history.util';
+
 const RO_VESSEL_MIN_DAYS_CODE = 'ro_vessel_min_days';
 
 export interface BookingClearanceView {
@@ -55,6 +60,7 @@ export interface BookingClearanceView {
     uploadedAt: string | null;
     reviewedAt: string | null;
     reviewedByName: string | null;
+    history: ClearanceDocEvent[];
   }>;
   allApproved: boolean;
   phase?: string | null;
@@ -188,9 +194,18 @@ export class BookingClearanceService {
     const fileByCode = new Map(files.map((f) => [f.code, f]));
     const reviews = await this.bookingsRepository.findDocumentReviews(bookingId);
     const reviewByKey = new Map(reviews.map((r) => [`${r.settingCode}:${r.fileKey}`, r]));
-    const reviewerNames = await this.bookingsRepository.resolveStaffNames(
-      reviews.map((r) => r.reviewedByStaffId),
+    const allVersions = await this.filesService.findAllVersionsByResource(
+      bookingId,
+      'bookings',
     );
+    const queryNotes = await this.bookingsRepository.findReviewNotes(
+      bookingId,
+      'CHANGES_REQUESTED',
+    );
+    const reviewerNames = await this.bookingsRepository.resolveStaffNames([
+      ...reviews.map((r) => r.reviewedByStaffId),
+      ...queryNotes.map((n) => n.authorId),
+    ]);
 
     const documents: BookingClearanceView['documents'] = [];
 
@@ -219,6 +234,13 @@ export class BookingClearanceService {
           reviewedByName: review?.reviewedByStaffId
             ? (reviewerNames.get(review.reviewedByStaffId) ?? null)
             : null,
+          history: buildClearanceDocHistory({
+            fileKey: field.fileKey,
+            allVersions,
+            queryNotes,
+            review,
+            names: reviewerNames,
+          }),
         });
       }
     };
@@ -243,6 +265,13 @@ export class BookingClearanceService {
         reviewedByName: review?.reviewedByStaffId
           ? (reviewerNames.get(review.reviewedByStaffId) ?? null)
           : null,
+        history: buildClearanceDocHistory({
+          fileKey: f.code,
+          allVersions,
+          queryNotes,
+          review,
+          names: reviewerNames,
+        }),
       });
     }
 
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 9a2552c7a..e4164c3b2 100644
--- a/apps/edr-freight-api/src/modules/files/files.repository.ts
+++ b/apps/edr-freight-api/src/modules/files/files.repository.ts
@@ -84,6 +84,21 @@ export class FilesRepository extends BaseRepository<FileRecord> {
     });
   }
 
+  /**
+   * Every version of every document on a resource, oldest first — superseded
+   * versions included. One query for a whole document grid's upload history.
+   */
+  findAllVersionsByResource(
+    resourceId: string,
+    resource: string,
+  ): Promise<FileRecord[]> {
+    return this.repository.find({
+      where: { resourceId, resource },
+      withDeleted: true,
+      order: { createdAt: "ASC" },
+    });
+  }
+
   /**
    * Documents belonging to any of the given resources that a reviewer has asked
    * the customer to correct. Used by the approval gate, so it takes a list of
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 e76240704..e2481848a 100644
--- a/apps/edr-freight-api/src/modules/files/files.service.ts
+++ b/apps/edr-freight-api/src/modules/files/files.service.ts
@@ -327,6 +327,14 @@ export class FilesService {
     return this.filesRepository.findByResource(resourceId, resource);
   }
 
+  /** All versions of every document on a resource (superseded included), oldest first. */
+  findAllVersionsByResource(
+    resourceId: string,
+    resource: string,
+  ): Promise<FileRecord[]> {
+    return this.filesRepository.findAllVersionsByResource(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 `[]`).
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 e4e78f462..291bc0d05 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
@@ -14,6 +14,7 @@ import {
   Text,
   Textarea,
   ThemeIcon,
+  Timeline,
   Tooltip,
 } from "@mantine/core";
 import {
@@ -24,6 +25,7 @@ import {
   FileCheck2,
   FileText,
   MessageSquareWarning,
+  RefreshCw,
   Upload,
 } from "lucide-react";
 import toast from "react-hot-toast";
@@ -458,6 +460,76 @@ export function ClearanceReviewSection({
   );
 }
 
+const EVENT_META: Record<
+  Freight.ClearanceDocumentEvent["type"],
+  { color: string; icon: typeof Upload; label: (byName: string | null) => string }
+> = {
+  UPLOADED: {
+    color: "blue",
+    icon: Upload,
+    label: (n) => `Uploaded by ${n ?? "customer"}`,
+  },
+  RESUBMITTED: {
+    color: "blue",
+    icon: RefreshCw,
+    label: (n) => `Re-submitted by ${n ?? "customer"}`,
+  },
+  QUERIED: {
+    color: "red",
+    icon: MessageSquareWarning,
+    label: (n) => `Query opened by ${n ?? "staff"}`,
+  },
+  APPROVED: {
+    color: "edr-green",
+    icon: CheckCircle2,
+    label: (n) => `Approved by ${n ?? "staff"}`,
+  },
+};
+
+/** Per-document audit trail: uploads, amendment responses, queries, approval. */
+function DocHistoryTimeline({
+  history,
+}: {
+  history: Freight.ClearanceDocumentEvent[];
+}) {
+  return (
+    <Timeline
+      mt="sm"
+      ml={4}
+      bulletSize={20}
+      lineWidth={2}
+      active={history.length - 1}
+      color="gray"
+    >
+      {history.map((ev, i) => {
+        const meta = EVENT_META[ev.type];
+        const Icon = meta.icon;
+        return (
+          <Timeline.Item
+            key={`${ev.type}:${ev.at}:${i}`}
+            color={meta.color}
+            bullet={<Icon size={11} />}
+            title={
+              <Text fz="12.5px" fw={600} c="edr-text" lh={1.3}>
+                {meta.label(ev.byName)}
+              </Text>
+            }
+          >
+            <Text fz="11px" c="dimmed">
+              {formatDateTime(ev.at)}
+            </Text>
+            {ev.note ? (
+              <Text fz="11.5px" c="red.8" mt={2}>
+                {ev.note}
+              </Text>
+            ) : null}
+          </Timeline.Item>
+        );
+      })}
+    </Timeline>
+  );
+}
+
 function StatPill({
   color,
   label,
@@ -551,11 +623,6 @@ function DocReviewCard({
             <Text fz="12px" c="edr-muted" truncate>
               {hasFile ? doc.file!.name : "Not uploaded by customer"}
             </Text>
-            {hasFile && doc.uploadedAt ? (
-              <Text fz="11px" c="dimmed">
-                Uploaded {formatDateTime(doc.uploadedAt)}
-              </Text>
-            ) : null}
           </Box>
         </Group>
 
@@ -607,11 +674,8 @@ function DocReviewCard({
         </Group>
       </Group>
 
-      {doc.reviewedAt && (status === "APPROVED" || status === "QUERIED") && (
-        <Text fz="11.5px" c="dimmed" mt={6}>
-          {status === "APPROVED" ? "Approved" : "Queried"} by{" "}
-          {doc.reviewedByName ?? "staff"} · {formatDateTime(doc.reviewedAt)}
-        </Text>
+      {(doc.history?.length ?? 0) > 0 && (
+        <DocHistoryTimeline history={doc.history!} />
       )}
 
       {status === "QUERIED" && doc.note && (
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index d236eb03b..02f4f3f0e 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -802,6 +802,16 @@ export interface PricingBreakdown {
 
 export type DocumentReviewStatus = "PENDING" | "APPROVED" | "QUERIED";
 
+/** One entry of a clearance document's audit trail, oldest first. */
+export interface ClearanceDocumentEvent {
+  type: "UPLOADED" | "RESUBMITTED" | "QUERIED" | "APPROVED";
+  at: string;
+  /** Actor display name (staff for reviews; null = the customer/unknown). */
+  byName: string | null;
+  /** Query reason, for QUERIED events. */
+  note: string | null;
+}
+
 /** One row of the clearance document grid (a required doc + its file + review). */
 export interface ClearanceDocument {
   fileKey: string;
@@ -819,6 +829,8 @@ export interface ClearanceDocument {
   reviewedAt?: string | null;
   /** Display name of the staff member who recorded the decision. */
   reviewedByName?: string | null;
+  /** Full audit trail: uploads, re-submissions, queries, approval. */
+  history?: ClearanceDocumentEvent[];
 }
 
 /**

From c138da61377358a8e413138a10321d87570b6554 Mon Sep 17 00:00:00 2001
From: Marshal <marshal@example.com>
Date: Thu, 20 Aug 2026 05:24:57 +0000
Subject: [PATCH 174/174] feat(bookings): two-level clearance charges (port +
 misc) billed to customer with invoices

---
 .../3590000000000-BookingClearanceCharge.ts   |  46 ++
 .../booking-clearance-charge.service.ts       | 332 +++++++++++
 .../modules/bookings/bookings.controller.ts   |  94 ++++
 .../src/modules/bookings/bookings.module.ts   |   4 +
 .../bookings/dto/clearance-charge.dto.ts      |  16 +
 .../booking-clearance-charge.entity.ts        |  68 +++
 .../contracts/contract-staff-stamp.spec.ts    |  37 +-
 .../contracts/contract-transition.service.ts  |  31 +-
 .../stamp-settings/stamp-settings.service.ts  |  42 +-
 .../contracts/ClearanceChargesTab.tsx         | 525 ++++++++++++++++++
 .../components/contracts/ClearanceOpsTabs.tsx |  24 +-
 .../pages/contracts/GlClearanceDetailPage.tsx |  13 +
 .../src/services/bookings.service.ts          |  63 +++
 packages/types/src/freight/index.ts           |  39 ++
 14 files changed, 1281 insertions(+), 53 deletions(-)
 create mode 100644 apps/edr-freight-api/src/migrations/3590000000000-BookingClearanceCharge.ts
 create mode 100644 apps/edr-freight-api/src/modules/bookings/booking-clearance-charge.service.ts
 create mode 100644 apps/edr-freight-api/src/modules/bookings/dto/clearance-charge.dto.ts
 create mode 100644 apps/edr-freight-api/src/modules/bookings/entities/booking-clearance-charge.entity.ts
 create mode 100644 apps/edr-freight-web/backoffice/src/components/contracts/ClearanceChargesTab.tsx

diff --git a/apps/edr-freight-api/src/migrations/3590000000000-BookingClearanceCharge.ts b/apps/edr-freight-api/src/migrations/3590000000000-BookingClearanceCharge.ts
new file mode 100644
index 000000000..042e47554
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/3590000000000-BookingClearanceCharge.ts
@@ -0,0 +1,46 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Post-finalization clearance charges billed to the customer: one PORT_CHARGES
+ * and one MISCELLANEOUS row max per booking, each carrying a document, amount,
+ * currency and its own payable invoice.
+ */
+export class BookingClearanceCharge3590000000000 implements MigrationInterface {
+  name = 'BookingClearanceCharge3590000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS "freight"."booking_clearance_charge" (
+        "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
+        "created_at" timestamptz NOT NULL DEFAULT now(),
+        "updated_at" timestamptz NOT NULL DEFAULT now(),
+        "deleted_at" timestamptz,
+        "booking_id" uuid NOT NULL,
+        "type" character varying(20) NOT NULL,
+        "status" character varying(20) NOT NULL DEFAULT 'DOC_UPLOADED',
+        "file_record_id" uuid,
+        "amount" numeric(14,2),
+        "currency" character varying(8),
+        "invoice_id" uuid,
+        "uploaded_by_staff_id" uuid,
+        "uploaded_at" timestamptz,
+        "billed_by_staff_id" uuid,
+        "billed_at" timestamptz,
+        "paid_at" timestamptz,
+        CONSTRAINT "pk_booking_clearance_charge" PRIMARY KEY ("id"),
+        CONSTRAINT "fk_booking_clearance_charge_booking" FOREIGN KEY ("booking_id")
+          REFERENCES "freight"."bookings"("id") ON DELETE CASCADE
+      )
+    `);
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS "uq_booking_clearance_charge_booking_type"
+        ON "freight"."booking_clearance_charge" ("booking_id", "type")
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DROP TABLE IF EXISTS "freight"."booking_clearance_charge"`,
+    );
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/booking-clearance-charge.service.ts b/apps/edr-freight-api/src/modules/bookings/booking-clearance-charge.service.ts
new file mode 100644
index 000000000..88986735f
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/booking-clearance-charge.service.ts
@@ -0,0 +1,332 @@
+import {
+  BadRequestException,
+  ConflictException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { DataSource } from 'typeorm';
+import { Freight } from '@edr/types';
+
+import { BillingService, InvoiceEventPayload } from '../billing/billing.service';
+import { Invoice } from '../billing/entities/invoice.entity';
+import { FilesService } from '../files/files.service';
+import { BookingsService } from './bookings.service';
+import { BookingsRepository } from './bookings.repository';
+import { Booking } from './entities/booking.entity';
+import {
+  BookingClearanceCharge,
+  ClearanceChargeType,
+} from './entities/booking-clearance-charge.entity';
+
+/** File-record codes the charge documents are stored under on the booking. */
+const CHARGE_FILE_CODE: Record<ClearanceChargeType, string> = {
+  PORT_CHARGES: 'clearance_charge_port',
+  MISCELLANEOUS: 'clearance_charge_misc',
+};
+
+const CHARGE_LABEL: Record<ClearanceChargeType, string> = {
+  PORT_CHARGES: 'Port charges',
+  MISCELLANEOUS: 'Miscellaneous charges',
+};
+
+/**
+ * Post-finalization clearance charges billed to the customer. Two levels per
+ * booking: GL Djibouti uploads the port-charges document; GL Ethiopia bills it
+ * (amount + currency) and sends the invoice; once that invoice is paid GL
+ * Ethiopia may create and send the miscellaneous charge. ETB invoices are paid
+ * through the portal gateway, other currencies through Finance's manual
+ * settlement worklist — both settle via `clearance_charge.invoice.paid`.
+ */
+@Injectable()
+export class BookingClearanceChargeService {
+  private readonly logger = new Logger(BookingClearanceChargeService.name);
+
+  constructor(
+    private readonly dataSource: DataSource,
+    private readonly filesService: FilesService,
+    private readonly billing: BillingService,
+    private readonly bookingsService: BookingsService,
+    private readonly bookingsRepository: BookingsRepository,
+  ) {}
+
+  private repo() {
+    return this.dataSource.getRepository(BookingClearanceCharge);
+  }
+
+  /**
+   * Charges are a post-finalization step: block while the customer's clearance
+   * documents are still being collected/reviewed.
+   */
+  private assertClearanceFinalized(booking: Booking): void {
+    const inReview =
+      booking.status === 'AWAITING_DOCUMENTS' ||
+      booking.status === 'DOCUMENTS_UNDER_REVIEW';
+    if (inReview && !booking.preClearanceFinalizedAt) {
+      throw new BadRequestException(
+        'Clearance charges open after document clearance is finalized.',
+      );
+    }
+  }
+
+  async list(bookingId: string): Promise<Freight.ClearanceCharge[]> {
+    const charges = await this.repo().find({
+      where: { bookingId },
+      order: { createdAt: 'ASC' },
+    });
+    if (charges.length === 0) return [];
+
+    const files = await this.filesService.findByResource(bookingId, 'bookings');
+    const fileById = new Map(files.map((f) => [f.id, f]));
+    const names = await this.bookingsRepository.resolveStaffNames(
+      charges.flatMap((c) => [c.uploadedByStaffId, c.billedByStaffId]),
+    );
+    const invoiceIds = charges
+      .map((c) => c.invoiceId)
+      .filter((id): id is string => Boolean(id));
+    const invoices = invoiceIds.length
+      ? await this.dataSource
+          .getRepository(Invoice)
+          .find({ where: invoiceIds.map((id) => ({ id })) })
+      : [];
+    const invoiceById = new Map(invoices.map((i) => [i.id, i]));
+
+    return charges.map((c) => {
+      const file = c.fileRecordId ? (fileById.get(c.fileRecordId) ?? null) : null;
+      return {
+        id: c.id,
+        bookingId: c.bookingId,
+        type: c.type,
+        status: c.status,
+        file: file ? { id: file.id, name: file.name, url: file.url } : null,
+        amount: c.amount != null ? Number(c.amount) : null,
+        currency: c.currency ?? null,
+        invoiceId: c.invoiceId ?? null,
+        invoiceNumber: c.invoiceId
+          ? (invoiceById.get(c.invoiceId)?.invoiceNumber ?? null)
+          : null,
+        uploadedByName: c.uploadedByStaffId
+          ? (names.get(c.uploadedByStaffId) ?? null)
+          : null,
+        uploadedAt: c.uploadedAt ? c.uploadedAt.toISOString() : null,
+        billedByName: c.billedByStaffId
+          ? (names.get(c.billedByStaffId) ?? null)
+          : null,
+        billedAt: c.billedAt ? c.billedAt.toISOString() : null,
+        paidAt: c.paidAt ? c.paidAt.toISOString() : null,
+      };
+    });
+  }
+
+  /** GL Djibouti uploads (or replaces, until billed) the port-charges document. */
+  async uploadPortDocument(
+    bookingId: string,
+    file: Express.Multer.File,
+    staffId: string,
+  ): Promise<Freight.ClearanceCharge[]> {
+    const booking = await this.bookingsService.findById(bookingId);
+    this.assertClearanceFinalized(booking);
+
+    const existing = await this.repo().findOne({
+      where: { bookingId, type: 'PORT_CHARGES' },
+    });
+    if (existing && existing.status !== 'DOC_UPLOADED') {
+      throw new ConflictException(
+        'The port charge has already been billed — ask GL Ethiopia to revise it instead.',
+      );
+    }
+
+    const record = await this.filesService.upsertByCode(
+      {
+        resourceId: bookingId,
+        resource: 'bookings',
+        code: CHARGE_FILE_CODE.PORT_CHARGES,
+        file,
+      },
+      { userId: staffId },
+    );
+
+    if (existing) {
+      await this.repo().update(existing.id, {
+        fileRecordId: record.id,
+        uploadedByStaffId: staffId,
+        uploadedAt: new Date(),
+      });
+    } else {
+      await this.repo().save(
+        this.repo().create({
+          bookingId,
+          type: 'PORT_CHARGES',
+          status: 'DOC_UPLOADED',
+          fileRecordId: record.id,
+          uploadedByStaffId: staffId,
+          uploadedAt: new Date(),
+        }),
+      );
+    }
+    return this.list(bookingId);
+  }
+
+  /**
+   * GL Ethiopia sets (or, on the customer's request, revises) amount +
+   * currency. Revising a SENT charge cancels its unpaid invoice; a PAID charge
+   * is immutable.
+   */
+  async billCharge(
+    bookingId: string,
+    chargeId: string,
+    input: { amount: number; currency: string },
+    staffId: string,
+  ): Promise<Freight.ClearanceCharge[]> {
+    const charge = await this.repo().findOne({
+      where: { id: chargeId, bookingId },
+    });
+    if (!charge) throw new NotFoundException('Clearance charge not found');
+    if (charge.status === 'PAID') {
+      throw new ConflictException('A paid charge can no longer be changed.');
+    }
+    if (!(input.amount > 0)) {
+      throw new BadRequestException('Amount must be greater than zero.');
+    }
+    if (!input.currency?.trim()) {
+      throw new BadRequestException('Currency is required.');
+    }
+
+    if (charge.status === 'SENT' && charge.invoiceId) {
+      await this.billing.cancelInvoice(charge.invoiceId);
+    }
+
+    await this.repo().update(charge.id, {
+      amount: input.amount.toFixed(2),
+      currency: input.currency.trim().toUpperCase(),
+      status: 'BILLED',
+      invoiceId: null,
+      billedByStaffId: staffId,
+      billedAt: new Date(),
+    });
+    return this.list(bookingId);
+  }
+
+  /** GL Ethiopia issues the payable invoice to the customer. */
+  async sendCharge(
+    bookingId: string,
+    chargeId: string,
+  ): Promise<Freight.ClearanceCharge[]> {
+    const charge = await this.repo().findOne({
+      where: { id: chargeId, bookingId },
+    });
+    if (!charge) throw new NotFoundException('Clearance charge not found');
+    if (charge.status !== 'BILLED') {
+      throw new ConflictException(
+        'Set the amount and currency before sending the charge to the customer.',
+      );
+    }
+
+    const booking = await this.bookingsService.findById(bookingId);
+    const invoice = await this.billing.generateInvoice({
+      source: Freight.InvoiceSource.ClearanceCharge,
+      // The charge's own id, NOT the booking id — booking-scoped invoice
+      // lookups (findPayable/expirePayable/CBE billQuery) must never match it.
+      sourceId: charge.id,
+      type: charge.type,
+      companyId: booking.companyId,
+      companyProfileId: booking.companyProfileId,
+      currency: charge.currency ?? 'ETB',
+      lines: [
+        {
+          chargeType: charge.type,
+          description: `${CHARGE_LABEL[charge.type]} — ${booking.reference ?? bookingId}`,
+          amount: Number(charge.amount),
+        },
+      ],
+    });
+
+    await this.repo().update(charge.id, {
+      status: 'SENT',
+      invoiceId: invoice.id,
+    });
+    this.logger.log(
+      `Clearance charge ${charge.type} on booking ${bookingId} sent as invoice ${invoice.invoiceNumber}`,
+    );
+    return this.list(bookingId);
+  }
+
+  /**
+   * GL Ethiopia creates the miscellaneous charge whole (document + amount +
+   * currency). Second payment level: allowed only once the port charge is paid.
+   */
+  async createMiscellaneous(
+    bookingId: string,
+    file: Express.Multer.File,
+    input: { amount: number; currency: string },
+    staffId: string,
+  ): Promise<Freight.ClearanceCharge[]> {
+    const booking = await this.bookingsService.findById(bookingId);
+    this.assertClearanceFinalized(booking);
+
+    const port = await this.repo().findOne({
+      where: { bookingId, type: 'PORT_CHARGES' },
+    });
+    if (port?.status !== 'PAID') {
+      throw new ConflictException(
+        'Miscellaneous charges open after the port charge is paid.',
+      );
+    }
+    const existing = await this.repo().findOne({
+      where: { bookingId, type: 'MISCELLANEOUS' },
+    });
+    if (existing) {
+      throw new ConflictException(
+        'This booking already has a miscellaneous charge — revise it instead.',
+      );
+    }
+    if (!(input.amount > 0)) {
+      throw new BadRequestException('Amount must be greater than zero.');
+    }
+    if (!input.currency?.trim()) {
+      throw new BadRequestException('Currency is required.');
+    }
+
+    const record = await this.filesService.upsertByCode(
+      {
+        resourceId: bookingId,
+        resource: 'bookings',
+        code: CHARGE_FILE_CODE.MISCELLANEOUS,
+        file,
+      },
+      { userId: staffId },
+    );
+    await this.repo().save(
+      this.repo().create({
+        bookingId,
+        type: 'MISCELLANEOUS',
+        status: 'BILLED',
+        fileRecordId: record.id,
+        amount: input.amount.toFixed(2),
+        currency: input.currency.trim().toUpperCase(),
+        uploadedByStaffId: staffId,
+        uploadedAt: new Date(),
+        billedByStaffId: staffId,
+        billedAt: new Date(),
+      }),
+    );
+    return this.list(bookingId);
+  }
+
+  /** Gateway and manual settlements both land here (`${source}.invoice.paid`). */
+  @OnEvent('clearance_charge.invoice.paid')
+  async onChargeInvoicePaid(payload: InvoiceEventPayload): Promise<void> {
+    const charge = await this.repo().findOne({
+      where: { id: payload.sourceId },
+    });
+    if (!charge || charge.status === 'PAID') return;
+    await this.repo().update(charge.id, {
+      status: 'PAID',
+      paidAt: new Date(),
+    });
+    this.logger.log(
+      `Clearance charge ${charge.type} on booking ${charge.bookingId} paid (invoice ${payload.invoiceNumber})`,
+    );
+  }
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts b/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
index a2584559e..8c9ee3b41 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.controller.ts
@@ -1,4 +1,5 @@
 import {
+  BadRequestException,
   Body,
   Controller,
   Delete,
@@ -38,6 +39,8 @@ import {
 } from "@nestjs/swagger";
 import type { Response } from "express";
 
+import { BookingClearanceChargeService } from './booking-clearance-charge.service';
+import { BillClearanceChargeDto } from './dto/clearance-charge.dto';
 import { BookingContractService } from './booking-contract.service';
 import { BookingPricingService } from './booking-pricing.service';
 import { BookingTransitionService } from './booking-transition.service';
@@ -170,6 +173,7 @@ export class BookingsController {
     private readonly userTradeAccessService: UserTradeAccessService,
     private readonly wagonCancellationService: BookingWagonCancellationService,
     private readonly consolidationApprovalService: ConsolidationApprovalService,
+    private readonly clearanceChargeService: BookingClearanceChargeService,
   ) {}
 
   @Post()
@@ -1073,6 +1077,96 @@ export class BookingsController {
     return this.transitionService.enrichBookingResponse(booking);
   }
 
+  // ── Clearance charges (post-finalization customer billing) ────────────────
+
+  @Get(":id/clearance/charges")
+  @BookingStaff([
+    FREIGHT_PERMS.contracts.clearanceEtActions,
+    FREIGHT_PERMS.contracts.clearanceDjActions,
+  ])
+  @ApiOperation({
+    summary: "Clearance charges billed to the customer (port + miscellaneous)",
+  })
+  getClearanceCharges(@Param("id", ParseUUIDPipe) id: string) {
+    return this.clearanceChargeService.list(id);
+  }
+
+  @Post(":id/clearance/charges/port-document")
+  @BookingStaff(FREIGHT_PERMS.contracts.clearanceDjActions)
+  @UseInterceptors(FileInterceptor("file"))
+  @ApiConsumes("multipart/form-data")
+  @ApiOperation({
+    summary: "GL Djibouti uploads (or replaces, until billed) the port-charges document",
+  })
+  uploadPortChargeDocument(
+    @Param("id", ParseUUIDPipe) id: string,
+    @UploadedFile() file: Express.Multer.File,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    if (!file) throw new BadRequestException("A document file is required");
+    return this.clearanceChargeService.uploadPortDocument(
+      id,
+      file,
+      resolveAuthUserId(user),
+    );
+  }
+
+  @Patch(":id/clearance/charges/:chargeId/bill")
+  @BookingStaff(FREIGHT_PERMS.contracts.clearanceEtActions)
+  @ApiOperation({
+    summary:
+      "GL Ethiopia sets or revises the charge's amount + currency (revising a sent charge cancels its unpaid invoice)",
+  })
+  billClearanceCharge(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Param("chargeId", ParseUUIDPipe) chargeId: string,
+    @Body() dto: BillClearanceChargeDto,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    return this.clearanceChargeService.billCharge(
+      id,
+      chargeId,
+      dto,
+      resolveAuthUserId(user),
+    );
+  }
+
+  @Post(":id/clearance/charges/:chargeId/send")
+  @BookingStaff(FREIGHT_PERMS.contracts.clearanceEtActions)
+  @ApiOperation({
+    summary:
+      "GL Ethiopia issues the charge's payable invoice to the customer (ETB pays via gateway, other currencies via manual settlement)",
+  })
+  sendClearanceCharge(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Param("chargeId", ParseUUIDPipe) chargeId: string,
+  ) {
+    return this.clearanceChargeService.sendCharge(id, chargeId);
+  }
+
+  @Post(":id/clearance/charges/miscellaneous")
+  @BookingStaff(FREIGHT_PERMS.contracts.clearanceEtActions)
+  @UseInterceptors(FileInterceptor("file"))
+  @ApiConsumes("multipart/form-data")
+  @ApiOperation({
+    summary:
+      "GL Ethiopia creates the miscellaneous charge (document + amount + currency); unlocked once the port charge is paid",
+  })
+  createMiscellaneousCharge(
+    @Param("id", ParseUUIDPipe) id: string,
+    @UploadedFile() file: Express.Multer.File,
+    @Body() dto: BillClearanceChargeDto,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    if (!file) throw new BadRequestException("A document file is required");
+    return this.clearanceChargeService.createMiscellaneous(
+      id,
+      file,
+      dto,
+      resolveAuthUserId(user),
+    );
+  }
+
   @Post(":id/clearance/output-documents")
   @BookingStaff(FREIGHT_PERMS.bookings.uploadClearanceOutput)
   @UseInterceptors(AnyFilesInterceptor())
diff --git a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
index b3ea4a546..5983f55f2 100644
--- a/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
+++ b/apps/edr-freight-api/src/modules/bookings/bookings.module.ts
@@ -37,6 +37,8 @@ import { ContainerValidationService } from './container-validation.service';
 import { BookingsService } from './bookings.service';
 import { BookingCargoModifier } from './entities/booking-cargo-modifier.entity';
 import { BookingDocumentReview } from './entities/booking-document-review.entity';
+import { BookingClearanceCharge } from './entities/booking-clearance-charge.entity';
+import { BookingClearanceChargeService } from './booking-clearance-charge.service';
 import { BookingContainer } from './entities/booking-container.entity';
 import { BookingRateSnapshot } from './entities/booking-rate-snapshot.entity';
 import { BookingContractSignature } from './entities/booking-contract-signature.entity';
@@ -76,6 +78,7 @@ import { VehiclesModule } from "../vehicles/vehicles.module";
       CustomerTruckAssignment,
       CustomerTruckContainer,
       ConsolidationApproval,
+      BookingClearanceCharge,
     ]),
     BillingModule,
     DocumentsModule,
@@ -111,6 +114,7 @@ import { VehiclesModule } from "../vehicles/vehicles.module";
     BookingTransitionService,
     BookingContractService,
     BookingInvoiceService,
+    BookingClearanceChargeService,
     ContractTemplateResolver,
     ContractViewModelBuilder,
     ContractPricingScheduleBuilder,
diff --git a/apps/edr-freight-api/src/modules/bookings/dto/clearance-charge.dto.ts b/apps/edr-freight-api/src/modules/bookings/dto/clearance-charge.dto.ts
new file mode 100644
index 000000000..f2bf15c0e
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/dto/clearance-charge.dto.ts
@@ -0,0 +1,16 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import { IsNumber, IsPositive, IsString, Length } from 'class-validator';
+
+export class BillClearanceChargeDto {
+  @ApiProperty({ example: 12500.5 })
+  @Type(() => Number)
+  @IsNumber()
+  @IsPositive()
+  amount!: number;
+
+  @ApiProperty({ example: 'ETB' })
+  @IsString()
+  @Length(3, 8)
+  currency!: string;
+}
diff --git a/apps/edr-freight-api/src/modules/bookings/entities/booking-clearance-charge.entity.ts b/apps/edr-freight-api/src/modules/bookings/entities/booking-clearance-charge.entity.ts
new file mode 100644
index 000000000..8530ad11e
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/bookings/entities/booking-clearance-charge.entity.ts
@@ -0,0 +1,68 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+import { Booking } from './booking.entity';
+
+export const CLEARANCE_CHARGE_TYPES = ['PORT_CHARGES', 'MISCELLANEOUS'] as const;
+export type ClearanceChargeType = (typeof CLEARANCE_CHARGE_TYPES)[number];
+
+export const CLEARANCE_CHARGE_STATUSES = [
+  'DOC_UPLOADED',
+  'BILLED',
+  'SENT',
+  'PAID',
+] as const;
+export type ClearanceChargeStatus = (typeof CLEARANCE_CHARGE_STATUSES)[number];
+
+/**
+ * Post-finalization clearance charge billed to the customer — at most one
+ * PORT_CHARGES and one MISCELLANEOUS row per booking. GL Djibouti uploads the
+ * port-charges document (DOC_UPLOADED); GL Ethiopia sets amount + currency
+ * (BILLED) and issues the invoice (SENT); the billing `clearance_charge.invoice.paid`
+ * event marks it PAID. MISCELLANEOUS is created whole by GL Ethiopia and only
+ * after the port charge is paid.
+ */
+@Entity({ schema: 'freight', name: 'booking_clearance_charge' })
+@Index(['bookingId', 'type'], { unique: true })
+export class BookingClearanceCharge extends BaseEntity {
+  @Column({ name: 'booking_id', type: 'uuid' })
+  bookingId!: string;
+
+  @ManyToOne(() => Booking, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'booking_id' })
+  booking?: Booking;
+
+  @Column({ name: 'type', type: 'varchar', length: 20 })
+  type!: ClearanceChargeType;
+
+  @Column({ name: 'status', type: 'varchar', length: 20, default: 'DOC_UPLOADED' })
+  status!: ClearanceChargeStatus;
+
+  /** The supporting charge document (FileRecord). */
+  @Column({ name: 'file_record_id', type: 'uuid', nullable: true })
+  fileRecordId?: string | null;
+
+  @Column({ name: 'amount', type: 'numeric', precision: 14, scale: 2, nullable: true })
+  amount?: string | null;
+
+  @Column({ name: 'currency', type: 'varchar', length: 8, nullable: true })
+  currency?: string | null;
+
+  /** The payable invoice issued for this charge (null until SENT). */
+  @Column({ name: 'invoice_id', type: 'uuid', nullable: true })
+  invoiceId?: string | null;
+
+  @Column({ name: 'uploaded_by_staff_id', type: 'uuid', nullable: true })
+  uploadedByStaffId?: string | null;
+
+  @Column({ name: 'uploaded_at', type: 'timestamptz', nullable: true })
+  uploadedAt?: Date | null;
+
+  @Column({ name: 'billed_by_staff_id', type: 'uuid', nullable: true })
+  billedByStaffId?: string | null;
+
+  @Column({ name: 'billed_at', type: 'timestamptz', nullable: true })
+  billedAt?: Date | null;
+
+  @Column({ name: 'paid_at', type: 'timestamptz', nullable: true })
+  paidAt?: Date | null;
+}
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-staff-stamp.spec.ts b/apps/edr-freight-api/src/modules/contracts/contract-staff-stamp.spec.ts
index 6d370c276..99fff9479 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-staff-stamp.spec.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-staff-stamp.spec.ts
@@ -3,17 +3,20 @@ import { BadRequestException } from '@nestjs/common';
 import { ContractTransitionService } from './contract-transition.service';
 
 /**
- * Where the booking-contract view reads the global stamp live, the contracts
- * path SNAPSHOTS it onto the signature row at signing time, so replacing the
- * company stamp can never restamp an already-executed contract. These specs
- * pin the sourcing split: EDR always seals with the global stamp and staff
- * never supply one, while the customer must upload their own.
+ * The staff signature seals with the ONE global stamp by REFERENCE: the
+ * signature row stores the current global stampFileId instead of re-uploading
+ * a copy per contract. That id stays valid after the stamp is replaced
+ * (StampSettingsService never deletes retired stamp files), so each contract
+ * keeps the exact seal it was signed with. These specs pin the sourcing
+ * split: EDR always seals with the global stamp and staff never supply one,
+ * while the customer must upload their own.
  */
 describe('applySignature stamp sourcing', () => {
   const contract = { id: 'c-1', reference: 'CTR-1', status: 'SIGNED_CUSTOMER' };
   const GLOBAL_STAMP = 'data:image/png;base64,RURS';
+  const GLOBAL_STAMP_FILE_ID = 'file-global-stamp';
 
-  const build = (globalStamp: string | null = GLOBAL_STAMP) => {
+  const build = (globalStampFileId: string | null = GLOBAL_STAMP_FILE_ID) => {
     const uploads: Array<{ code: string; image: string }> = [];
     const saved: unknown[] = [];
     const service = Object.create(
@@ -22,7 +25,10 @@ describe('applySignature stamp sourcing', () => {
     Object.assign(service, {
       logger: { warn: jest.fn(), log: jest.fn() },
       stampSettings: {
-        getStampImageUrl: jest.fn().mockResolvedValue(globalStamp),
+        get: jest.fn().mockResolvedValue({
+          id: 's-1',
+          stampFileId: globalStampFileId,
+        }),
       },
       contractsRepository: {
         saveSignature: jest.fn((row: unknown) => {
@@ -62,35 +68,36 @@ describe('applySignature stamp sourcing', () => {
     signatureImageBase64: 'data:image/png;base64,U0lH',
   };
 
-  it('seals the EDR side with the global stamp', async () => {
+  it('seals the EDR side by referencing the global stamp file, without re-uploading it', async () => {
     const { service, uploads, saved } = build();
 
     await apply(service, staffDto);
 
-    expect(uploads).toContainEqual({ code: 'stamp_staff', image: GLOBAL_STAMP });
+    expect(uploads.map((u) => u.code)).toEqual(['signature_staff']);
     expect(saved[0]).toEqual(
-      expect.objectContaining({ stampFileId: 'file-stamp_staff' }),
+      expect.objectContaining({ stampFileId: GLOBAL_STAMP_FILE_ID }),
     );
   });
 
   it('ignores a stamp a staff client tries to supply', async () => {
-    const { service, uploads } = build();
+    const { service, uploads, saved } = build();
 
     await apply(service, {
       ...staffDto,
       stampImageBase64: 'data:image/png;base64,SEFDSw==',
     });
 
-    expect(uploads).toContainEqual({ code: 'stamp_staff', image: GLOBAL_STAMP });
     expect(uploads.map((u) => u.image)).not.toContain(
       'data:image/png;base64,SEFDSw==',
     );
+    expect(saved[0]).toEqual(
+      expect.objectContaining({ stampFileId: GLOBAL_STAMP_FILE_ID }),
+    );
   });
 
   /**
-   * Failing loudly matters here: getStampImageUrl degrades to null when the
-   * stamp cannot be inlined, and silently executing an unsealed contract would
-   * be worse than refusing to counter-sign.
+   * Failing loudly matters here: silently executing an unsealed contract
+   * would be worse than refusing to counter-sign.
    */
   it('refuses to counter-sign when no global stamp is configured', async () => {
     const { service, saved } = build(null);
diff --git a/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts b/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
index e6f208ae2..48c90fcbc 100644
--- a/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
+++ b/apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
@@ -1128,17 +1128,27 @@ export class ContractTransitionService {
       );
     }
 
-    // Snapshot whichever stamp applies onto the signature row rather than
-    // referencing the global one, so replacing the company stamp later can
-    // never restamp an already-executed contract.
-    let stampImageBase64 = dto.stampImageBase64 ?? null;
+    // STAFF seals by REFERENCE to the one global stamp file — no per-contract
+    // copy of the image. Safe because StampSettingsService.setStamp/clearStamp
+    // never delete a replaced stamp file: the referenced id keeps rendering
+    // the exact seal that was current at signing, even after the global stamp
+    // is later replaced. The customer's stamp is their own upload and is still
+    // stored per contract.
+    let stampFileId: string | null = null;
     if (role === 'STAFF') {
-      stampImageBase64 = await this.stampSettings.getStampImageUrl();
-      if (!stampImageBase64) {
+      stampFileId = (await this.stampSettings.get()).stampFileId ?? null;
+      if (!stampFileId) {
         throw new BadRequestException(
           'No company stamp is configured. Upload the company stamp under Settings before counter-signing contracts.',
         );
       }
+    } else if (dto.stampImageBase64) {
+      const stampRecord = await this.uploadSignatureAsset(
+        contract,
+        `stamp_${role.toLowerCase()}`,
+        dto.stampImageBase64,
+      );
+      stampFileId = stampRecord.id;
     }
 
     const fileRecord = await this.uploadSignatureAsset(
@@ -1146,13 +1156,6 @@ export class ContractTransitionService {
       `signature_${role.toLowerCase()}`,
       imageBase64,
     );
-    const stampRecord = stampImageBase64
-      ? await this.uploadSignatureAsset(
-          contract,
-          `stamp_${role.toLowerCase()}`,
-          stampImageBase64,
-        )
-      : null;
 
     await this.contractsRepository.saveSignature({
       contractId: contract.id,
@@ -1160,7 +1163,7 @@ export class ContractTransitionService {
       signerDisplayName,
       signedAt: new Date(),
       signatureFileId: fileRecord.id,
-      stampFileId: stampRecord?.id ?? null,
+      stampFileId,
       consentText: dto.consentText ?? null,
     });
 
diff --git a/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.ts b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.ts
index 9bb4f3a37..bfc544f88 100644
--- a/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.ts
+++ b/apps/edr-freight-api/src/modules/stamp-settings/stamp-settings.service.ts
@@ -1,9 +1,7 @@
 import { Injectable, Logger } from "@nestjs/common";
 import { Readable } from "stream";
-import { DataSource } from "typeorm";
 
 import { FilesService } from "../files/files.service";
-import { FileRecord } from "../files/entities/file.entity";
 import { MinioService } from "../minio/minio.service";
 import { StampSettingsRepository } from "./stamp-settings.repository";
 import { StampSetting } from "./entities/stamp-setting.entity";
@@ -28,7 +26,6 @@ export class StampSettingsService {
     private readonly repository: StampSettingsRepository,
     private readonly filesService: FilesService,
     private readonly minioService: MinioService,
-    private readonly dataSource: DataSource,
   ) {}
 
   /** The settings row, created empty on first access. */
@@ -53,14 +50,12 @@ export class StampSettingsService {
    * `data:` URL or null. Never throws — document generation must succeed even
    * if the stamp lookup fails; callers fall back to their own seal on null.
    *
-   * The data-URL-or-null guarantee is load-bearing, not cosmetic. Callers do
-   * two things with this value that a bare MinIO URL silently corrupts:
-   * ContractTransitionService base64-decodes it to snapshot the seal onto a
-   * signature row (a URL decodes to garbage bytes, not an error, permanently
-   * sealing an executed contract with a broken image), and the HTML render
-   * path inlines it into an <img> that headless Chromium cannot fetch. So
-   * where getView() may hand a raw URL to a browser that can load it, this
-   * degrades to null and lets the caller draw its text/vector seal instead.
+   * The data-URL-or-null guarantee is load-bearing, not cosmetic: the HTML
+   * render paths inline this value into an <img> that headless Chromium
+   * cannot fetch over the network. So where getView() may hand a raw URL to
+   * a browser that can load it, this degrades to null and lets the caller
+   * draw its text/vector seal instead. (Contract signing no longer consumes
+   * this — staff signatures reference the stampFileId directly.)
    */
   async getStampImageUrl(): Promise<string | null> {
     try {
@@ -81,13 +76,20 @@ export class StampSettingsService {
     }
   }
 
-  /** Replace the stamp image, storing it in MinIO via FilesService. */
+  /**
+   * Replace the stamp image, storing it in MinIO via FilesService.
+   *
+   * The replaced file is NEVER deleted: contract signatures reference stamp
+   * files by id (ContractTransitionService points staff signatures at the
+   * current stampFileId instead of copying the image), so each retired file
+   * is the immutable record of which seal executed the contracts signed while
+   * it was current. Deleting it would strip the seal off those contracts.
+   */
   async setStamp(
     stampImageBase64: string,
     updatedById?: string | null,
   ): Promise<StampSettingView> {
     const current = await this.get();
-    const previousFileId = current.stampFileId ?? null;
 
     const fileRecord = await this.filesService.upload({
       resourceId: current.id,
@@ -102,28 +104,22 @@ export class StampSettingsService {
       updatedById: updatedById ?? null,
     });
 
-    if (previousFileId && previousFileId !== fileRecord.id) {
-      await this.dataSource.getRepository(FileRecord).delete(previousFileId);
-    }
-
     this.logger.log(`Company stamp updated by ${updatedById ?? "unknown user"}`);
     return this.getView();
   }
 
-  /** Clear the stamp (invoices fall back to the programmatic seal). */
+  /**
+   * Clear the stamp (invoices fall back to the programmatic seal). The file
+   * is kept for the same reason as in {@link setStamp}.
+   */
   async clearStamp(updatedById?: string | null): Promise<StampSettingView> {
     const current = await this.get();
-    const previousFileId = current.stampFileId ?? null;
 
     await this.repository.update(current.id, {
       stampFileId: null,
       updatedById: updatedById ?? null,
     });
 
-    if (previousFileId) {
-      await this.dataSource.getRepository(FileRecord).delete(previousFileId);
-    }
-
     return this.getView();
   }
 
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/ClearanceChargesTab.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/ClearanceChargesTab.tsx
new file mode 100644
index 000000000..6f3fb530f
--- /dev/null
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/ClearanceChargesTab.tsx
@@ -0,0 +1,525 @@
+import { useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  Badge,
+  Box,
+  Button,
+  FileButton,
+  Group,
+  Loader,
+  NumberInput,
+  Paper,
+  Select,
+  Stack,
+  Text,
+  Tooltip,
+} from "@mantine/core";
+import {
+  CheckCircle2,
+  Download,
+  Eye,
+  FileText,
+  Receipt,
+  Send,
+  Upload,
+} from "lucide-react";
+import toast from "react-hot-toast";
+import type { Freight } from "@edr/types";
+import { isViewable } from "@edr/ui-common";
+
+import { bookingsService } from "@/services/bookings.service";
+import {
+  downloadBookingFile,
+  fetchViewableFile,
+} from "@/services/files.service";
+import { formatDateTime } from "@/lib/format";
+import { extractErrorMessage } from "@/utils/errorExtractor";
+
+const CURRENCIES = ["ETB", "USD"];
+
+const STATUS_META: Record<
+  Freight.ClearanceChargeStatus,
+  { label: string; color: string }
+> = {
+  DOC_UPLOADED: { label: "Awaiting billing", color: "yellow" },
+  BILLED: { label: "Ready to send", color: "blue" },
+  SENT: { label: "Sent — unpaid", color: "orange" },
+  PAID: { label: "Paid", color: "edr-green" },
+};
+
+export interface ClearanceChargesTabProps {
+  bookingId: string;
+  /** DJ uploads the port document; ET bills, sends and creates miscellaneous. */
+  roleMode: "ET" | "DJ";
+  onViewFile: (file: { name: string; url: string }) => void;
+}
+
+/**
+ * Post-finalization charges billed to the customer, two levels: port charges
+ * (document from GL Djibouti, billed by GL Ethiopia) then miscellaneous
+ * (created whole by GL Ethiopia once the port charge is paid). Each level
+ * issues its own payable invoice — ETB settles through the portal gateway
+ * (CBE), other currencies through Finance's manual settlement.
+ */
+export function ClearanceChargesTab({
+  bookingId,
+  roleMode,
+  onViewFile,
+}: ClearanceChargesTabProps) {
+  const qc = useQueryClient();
+  const { data: charges, isLoading } = useQuery({
+    queryKey: ["clearance-charges", bookingId],
+    queryFn: () => bookingsService.getClearanceCharges(bookingId),
+  });
+
+  const refresh = (next: Freight.ClearanceCharge[]) =>
+    qc.setQueryData(["clearance-charges", bookingId], next);
+  const onError = (e: unknown) =>
+    toast.error(extractErrorMessage(e, "Could not update the charge"));
+
+  const uploadPort = useMutation({
+    mutationFn: (file: File) =>
+      bookingsService.uploadPortChargeDocument(bookingId, file),
+    onSuccess: (next) => {
+      toast.success("Port-charges document uploaded");
+      refresh(next);
+    },
+    onError,
+  });
+  const bill = useMutation({
+    mutationFn: (p: { chargeId: string; amount: number; currency: string }) =>
+      bookingsService.billClearanceCharge(bookingId, p.chargeId, p),
+    onSuccess: (next) => {
+      toast.success("Charge amount saved");
+      refresh(next);
+    },
+    onError,
+  });
+  const send = useMutation({
+    mutationFn: (chargeId: string) =>
+      bookingsService.sendClearanceCharge(bookingId, chargeId),
+    onSuccess: (next) => {
+      toast.success("Invoice sent to the customer");
+      refresh(next);
+    },
+    onError,
+  });
+  const createMisc = useMutation({
+    mutationFn: (p: { file: File; amount: number; currency: string }) =>
+      bookingsService.createMiscellaneousCharge(bookingId, p.file, p),
+    onSuccess: (next) => {
+      toast.success("Miscellaneous charge created");
+      refresh(next);
+    },
+    onError,
+  });
+
+  if (isLoading) {
+    return (
+      <Group justify="center" py="xl" gap={10}>
+        <Loader size="sm" color="edr-green" />
+        <Text c="dimmed">Loading charges…</Text>
+      </Group>
+    );
+  }
+
+  const port = (charges ?? []).find((c) => c.type === "PORT_CHARGES") ?? null;
+  const misc = (charges ?? []).find((c) => c.type === "MISCELLANEOUS") ?? null;
+  const busy =
+    uploadPort.isPending || bill.isPending || send.isPending || createMisc.isPending;
+
+  const totals = new Map<string, number>();
+  for (const c of charges ?? []) {
+    if (c.amount != null && c.currency)
+      totals.set(c.currency, (totals.get(c.currency) ?? 0) + c.amount);
+  }
+
+  return (
+    <Stack gap="md" maw={860}>
+      <ChargeCard
+        title="1 · Port charges"
+        charge={port}
+        roleMode={roleMode}
+        busy={busy}
+        emptyHint={
+          roleMode === "DJ"
+            ? "Upload the port-charges document to start this charge."
+            : "Waiting for GL Djibouti to upload the port-charges document."
+        }
+        onViewFile={onViewFile}
+        onBill={(amount, currency) =>
+          port && bill.mutate({ chargeId: port.id, amount, currency })
+        }
+        onSend={() => port && send.mutate(port.id)}
+        djUpload={
+          roleMode === "DJ" && (!port || port.status === "DOC_UPLOADED") ? (
+            <FileButton
+              onChange={(f) => f && uploadPort.mutate(f)}
+              accept="application/pdf,image/*"
+              disabled={busy}
+            >
+              {(props) => (
+                <Button
+                  {...props}
+                  size="compact-sm"
+                  color="edr-green"
+                  radius="md"
+                  leftSection={<Upload size={14} />}
+                  loading={uploadPort.isPending}
+                >
+                  {port ? "Replace document" : "Upload document"}
+                </Button>
+              )}
+            </FileButton>
+          ) : null
+        }
+      />
+
+      <ChargeCard
+        title="2 · Miscellaneous charges"
+        charge={misc}
+        roleMode={roleMode}
+        busy={busy}
+        emptyHint={
+          port?.status !== "PAID"
+            ? "Unlocks once the port charge is paid."
+            : roleMode === "ET"
+              ? "Create the miscellaneous charge with its document, amount and currency."
+              : "GL Ethiopia creates this charge once the port charge is paid."
+        }
+        onViewFile={onViewFile}
+        onBill={(amount, currency) =>
+          misc && bill.mutate({ chargeId: misc.id, amount, currency })
+        }
+        onSend={() => misc && send.mutate(misc.id)}
+        etCreate={
+          roleMode === "ET" && !misc && port?.status === "PAID" ? (
+            <MiscCreateForm
+              busy={createMisc.isPending}
+              onCreate={(file, amount, currency) =>
+                createMisc.mutate({ file, amount, currency })
+              }
+            />
+          ) : null
+        }
+      />
+
+      {totals.size > 0 && (
+        <Paper withBorder radius="md" p="md">
+          <Group justify="space-between">
+            <Text fz="13px" fw={700} c="edr-text">
+              Total billed
+            </Text>
+            <Group gap="md">
+              {[...totals.entries()].map(([currency, amount]) => (
+                <Text key={currency} fz="14px" fw={800} c="edr-text">
+                  {amount.toLocaleString(undefined, {
+                    minimumFractionDigits: 2,
+                  })}{" "}
+                  {currency}
+                </Text>
+              ))}
+            </Group>
+          </Group>
+        </Paper>
+      )}
+    </Stack>
+  );
+}
+
+function ChargeCard({
+  title,
+  charge,
+  roleMode,
+  busy,
+  emptyHint,
+  onViewFile,
+  onBill,
+  onSend,
+  djUpload,
+  etCreate,
+}: {
+  title: string;
+  charge: Freight.ClearanceCharge | null;
+  roleMode: "ET" | "DJ";
+  busy: boolean;
+  emptyHint: string;
+  onViewFile: (file: { name: string; url: string }) => void;
+  onBill: (amount: number, currency: string) => void;
+  onSend: () => void;
+  djUpload?: React.ReactNode;
+  etCreate?: React.ReactNode;
+}) {
+  const [editing, setEditing] = useState(false);
+  const [amount, setAmount] = useState<number | string>(charge?.amount ?? "");
+  const [currency, setCurrency] = useState<string>(charge?.currency ?? "ETB");
+
+  const status = charge?.status ?? null;
+  const meta = status ? STATUS_META[status] : null;
+  // ET enters/revises the amount while the charge is unpaid.
+  const showBillForm =
+    roleMode === "ET" &&
+    charge != null &&
+    (charge.status === "DOC_UPLOADED" || editing);
+
+  return (
+    <Paper withBorder radius="md" p="md">
+      <Group justify="space-between" wrap="nowrap" align="flex-start">
+        <Group gap={10} wrap="nowrap">
+          <Receipt size={18} color="var(--mantine-color-edr-green-6)" />
+          <Box>
+            <Text fz="14px" fw={700} c="edr-text">
+              {title}
+            </Text>
+            {charge?.uploadedAt && (
+              <Text fz="11.5px" c="dimmed">
+                Document uploaded
+                {charge.uploadedByName ? ` by ${charge.uploadedByName}` : ""} ·{" "}
+                {formatDateTime(charge.uploadedAt)}
+              </Text>
+            )}
+            {charge?.billedAt && (
+              <Text fz="11.5px" c="dimmed">
+                Billed{charge.billedByName ? ` by ${charge.billedByName}` : ""} ·{" "}
+                {formatDateTime(charge.billedAt)}
+              </Text>
+            )}
+            {charge?.paidAt && (
+              <Text fz="11.5px" c="edr-green.8" fw={600}>
+                Paid · {formatDateTime(charge.paidAt)}
+                {charge.invoiceNumber ? ` (invoice ${charge.invoiceNumber})` : ""}
+              </Text>
+            )}
+          </Box>
+        </Group>
+        <Group gap={8} wrap="nowrap">
+          {charge?.amount != null && charge.currency && (
+            <Text fz="14px" fw={800} c="edr-text">
+              {charge.amount.toLocaleString(undefined, {
+                minimumFractionDigits: 2,
+              })}{" "}
+              {charge.currency}
+            </Text>
+          )}
+          {meta && (
+            <Badge variant="light" color={meta.color} radius="sm">
+              {meta.label}
+            </Badge>
+          )}
+        </Group>
+      </Group>
+
+      {charge?.file && (
+        <Group gap={8} mt="sm" wrap="nowrap">
+          <FileText size={15} color="var(--mantine-color-edr-green-6)" />
+          <Text fz="12.5px" c="edr-text" truncate style={{ minWidth: 0 }}>
+            {charge.file.name}
+          </Text>
+          {isViewable({ name: charge.file.name, url: "" }) && (
+            <Tooltip label="View">
+              <Box
+                component="button"
+                type="button"
+                onClick={() =>
+                  void fetchViewableFile(
+                    charge.file!.id,
+                    charge.file!.name,
+                  ).then(onViewFile)
+                }
+                c="edr-green"
+                style={{
+                  display: "flex",
+                  background: "transparent",
+                  border: "none",
+                  cursor: "pointer",
+                }}
+              >
+                <Eye size={15} />
+              </Box>
+            </Tooltip>
+          )}
+          <Tooltip label="Download">
+            <Box
+              component="button"
+              type="button"
+              onClick={() =>
+                void downloadBookingFile(charge.file!.id, charge.file!.name)
+              }
+              c="edr-green"
+              style={{
+                display: "flex",
+                background: "transparent",
+                border: "none",
+                cursor: "pointer",
+              }}
+            >
+              <Download size={15} />
+            </Box>
+          </Tooltip>
+        </Group>
+      )}
+
+      {!charge && (
+        <Text fz="12.5px" c="dimmed" mt="xs">
+          {emptyHint}
+        </Text>
+      )}
+      {djUpload && <Box mt="sm">{djUpload}</Box>}
+      {etCreate && <Box mt="sm">{etCreate}</Box>}
+
+      {showBillForm && (
+        <Group mt="sm" gap={8} align="flex-end" wrap="wrap">
+          <NumberInput
+            label="Amount"
+            size="xs"
+            radius="md"
+            min={0.01}
+            decimalScale={2}
+            value={amount}
+            onChange={setAmount}
+            w={160}
+          />
+          <Select
+            label="Currency"
+            size="xs"
+            radius="md"
+            data={CURRENCIES}
+            value={currency}
+            onChange={(v) => v && setCurrency(v)}
+            w={100}
+          />
+          <Button
+            size="compact-sm"
+            color="edr-green"
+            radius="md"
+            disabled={busy || !(Number(amount) > 0)}
+            onClick={() => {
+              onBill(Number(amount), currency);
+              setEditing(false);
+            }}
+          >
+            Save amount
+          </Button>
+          {editing && (
+            <Button
+              size="compact-sm"
+              variant="subtle"
+              color="gray"
+              radius="md"
+              disabled={busy}
+              onClick={() => setEditing(false)}
+            >
+              Cancel
+            </Button>
+          )}
+        </Group>
+      )}
+
+      {roleMode === "ET" && charge && !showBillForm && charge.status !== "PAID" && (
+        <Group mt="sm" gap={8} justify="flex-end">
+          <Button
+            size="compact-sm"
+            variant="light"
+            color="gray"
+            radius="md"
+            disabled={busy}
+            onClick={() => {
+              setAmount(charge.amount ?? "");
+              setCurrency(charge.currency ?? "ETB");
+              setEditing(true);
+            }}
+          >
+            {charge.status === "SENT" ? "Revise (cancels invoice)" : "Edit amount"}
+          </Button>
+          {charge.status === "BILLED" && (
+            <Tooltip label="ETB is payable online via CBE; other currencies go to Finance's manual settlement.">
+              <Button
+                size="compact-sm"
+                color="edr-green"
+                radius="md"
+                leftSection={<Send size={14} />}
+                disabled={busy}
+                onClick={onSend}
+              >
+                Send invoice to customer
+              </Button>
+            </Tooltip>
+          )}
+          {charge.status === "SENT" && charge.invoiceNumber && (
+            <Badge variant="light" color="orange" radius="sm">
+              Invoice {charge.invoiceNumber}
+            </Badge>
+          )}
+        </Group>
+      )}
+      {charge?.status === "PAID" && (
+        <Group mt="sm" gap={6} justify="flex-end">
+          <CheckCircle2 size={14} color="var(--mantine-color-edr-green-6)" />
+          <Text fz="12px" c="edr-green.8" fw={600}>
+            Settled
+          </Text>
+        </Group>
+      )}
+    </Paper>
+  );
+}
+
+function MiscCreateForm({
+  busy,
+  onCreate,
+}: {
+  busy: boolean;
+  onCreate: (file: File, amount: number, currency: string) => void;
+}) {
+  const [file, setFile] = useState<File | null>(null);
+  const [amount, setAmount] = useState<number | string>("");
+  const [currency, setCurrency] = useState("ETB");
+
+  return (
+    <Group gap={8} align="flex-end" wrap="wrap">
+      <FileButton onChange={setFile} accept="application/pdf,image/*" disabled={busy}>
+        {(props) => (
+          <Button
+            {...props}
+            size="compact-sm"
+            variant="light"
+            color="edr-green"
+            radius="md"
+            leftSection={<Upload size={14} />}
+          >
+            {file ? file.name : "Choose document"}
+          </Button>
+        )}
+      </FileButton>
+      <NumberInput
+        label="Amount"
+        size="xs"
+        radius="md"
+        min={0.01}
+        decimalScale={2}
+        value={amount}
+        onChange={setAmount}
+        w={160}
+      />
+      <Select
+        label="Currency"
+        size="xs"
+        radius="md"
+        data={CURRENCIES}
+        value={currency}
+        onChange={(v) => v && setCurrency(v)}
+        w={100}
+      />
+      <Button
+        size="compact-sm"
+        color="edr-green"
+        radius="md"
+        disabled={busy || !file || !(Number(amount) > 0)}
+        loading={busy}
+        onClick={() => file && onCreate(file, Number(amount), currency)}
+      >
+        Create charge
+      </Button>
+    </Group>
+  );
+}
diff --git a/apps/edr-freight-web/backoffice/src/components/contracts/ClearanceOpsTabs.tsx b/apps/edr-freight-web/backoffice/src/components/contracts/ClearanceOpsTabs.tsx
index a61646d6f..95dc13d37 100644
--- a/apps/edr-freight-web/backoffice/src/components/contracts/ClearanceOpsTabs.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/ClearanceOpsTabs.tsx
@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 import { Badge, Stack, Tabs, Text } from "@mantine/core";
-import { AlertTriangle, FileText, Share2, ShieldAlert } from "lucide-react";
+import { AlertTriangle, FileText, Receipt, Share2, ShieldAlert } from "lucide-react";
 import type { Freight } from "@edr/types";
 
 import { useAuth } from "@/auth/useAuth";
@@ -9,6 +9,7 @@ import { SectionCard } from "@/components/bookings/detail/SectionCard";
 import { AssignRiskCard } from "@/components/contracts/gl-actions/AssignRiskCard";
 import { IncidentReportCard } from "@/components/contracts/gl-actions/IncidentReportCard";
 import { ClearanceUploadedDocumentsPanel } from "@/components/contracts/ClearanceUploadedDocumentsPanel";
+import { ClearanceChargesTab } from "@/components/contracts/ClearanceChargesTab";
 import { GlExchangePanel } from "@/components/contracts/GlExchangePanel";
 
 export interface ClearanceOpsTabsProps {
@@ -68,6 +69,12 @@ export function ClearanceOpsTabs({
     Boolean(exchangeEntityId) &&
     (hasPermission(user, FREIGHT_PERMS.contracts.clearanceEtActions) ||
       hasPermission(user, FREIGHT_PERMS.contracts.clearanceDjActions));
+  // Post-finalization customer billing. This layout is only rendered on the ET
+  // clearance pages — the DJ page (GlClearanceDetailPage) mounts its own tab.
+  const showCharges =
+    Boolean(bookingId) &&
+    Boolean(onViewFile) &&
+    hasPermission(user, FREIGHT_PERMS.contracts.clearanceEtActions);
   // Risk assignment + incident reporting hit bookings:operations endpoints.
   const canOps = hasPermission(user, FREIGHT_PERMS.bookings.operations);
   const hasTabs = (showOpsTabs && hasOps) || showDocuments || showExchange;
@@ -100,6 +107,11 @@ export function ClearanceOpsTabs({
             Document exchange
           </Tabs.Tab>
         ) : null}
+        {showCharges ? (
+          <Tabs.Tab value="charges" leftSection={<Receipt size={14} />}>
+            Customer charges
+          </Tabs.Tab>
+        ) : null}
         {showOpsTabs && canOps && riskMs ? (
           <Tabs.Tab value="risk" leftSection={<ShieldAlert size={14} />}>
             Risk assignment
@@ -131,6 +143,16 @@ export function ClearanceOpsTabs({
         </Tabs.Panel>
       ) : null}
 
+      {showCharges ? (
+        <Tabs.Panel value="charges">
+          <ClearanceChargesTab
+            bookingId={bookingId!}
+            roleMode="ET"
+            onViewFile={onViewFile!}
+          />
+        </Tabs.Panel>
+      ) : null}
+
       {showOpsTabs && canOps && riskMs && bookingId ? (
         <Tabs.Panel value="risk">
           <SectionCard icon={ShieldAlert} title="Customs risk" accent="edr-green">
diff --git a/apps/edr-freight-web/backoffice/src/pages/contracts/GlClearanceDetailPage.tsx b/apps/edr-freight-web/backoffice/src/pages/contracts/GlClearanceDetailPage.tsx
index 76e0ff4ad..95e8ff296 100644
--- a/apps/edr-freight-web/backoffice/src/pages/contracts/GlClearanceDetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/contracts/GlClearanceDetailPage.tsx
@@ -20,6 +20,7 @@ import {
   AlertTriangle,
   ClipboardList,
   FileText,
+  Receipt,
   Share2,
   Upload,
 } from "lucide-react";
@@ -36,6 +37,7 @@ import { BookingCompanyCard } from "@/components/bookings/detail/BookingCompanyC
 import { ContractClearanceReviewSection } from "@/components/contracts/ContractClearanceReviewSection";
 import { ClearanceWorkflowFilesPanel } from "@/components/contracts/ClearanceWorkflowFilesPanel";
 import { GlExchangePanel } from "@/components/contracts/GlExchangePanel";
+import { ClearanceChargesTab } from "@/components/contracts/ClearanceChargesTab";
 import {
   GlClearanceUploadModal,
   type GlClearanceUploadKind,
@@ -247,6 +249,11 @@ export default function GlClearanceDetailPage() {
             <Tabs.Tab value="exchange" leftSection={<Share2 size={14} />}>
               Document exchange
             </Tabs.Tab>
+            {data.kind === "booking" ? (
+              <Tabs.Tab value="charges" leftSection={<Receipt size={14} />}>
+                Customer charges
+              </Tabs.Tab>
+            ) : null}
             {incidentBookingId ? (
               <Tabs.Tab value="incidents" leftSection={<AlertTriangle size={14} />}>
                 Incidents
@@ -369,6 +376,12 @@ export default function GlClearanceDetailPage() {
             <GlExchangePanel entityId={id!} />
           </Tabs.Panel>
 
+          {data.kind === "booking" ? (
+            <Tabs.Panel value="charges">
+              <ClearanceChargesTab bookingId={id!} roleMode="DJ" onViewFile={view} />
+            </Tabs.Panel>
+          ) : null}
+
           {incidentBookingId ? (
             <Tabs.Panel value="incidents">
               <SectionCard icon={AlertTriangle} title="Incident reports" accent="edr-green">
diff --git a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
index f558d8271..bdfb46cd6 100644
--- a/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/bookings.service.ts
@@ -432,6 +432,69 @@ export const bookingsService = {
     return unwrap(response.data) as Freight.ClearanceView;
   },
 
+  // ── Clearance charges (post-finalization customer billing) ──
+  getClearanceCharges: async (id: string): Promise<Freight.ClearanceCharge[]> => {
+    const response = await client.get(`/bookings/${id}/clearance/charges`);
+    return unwrap(response.data) as Freight.ClearanceCharge[];
+  },
+
+  /** GL Djibouti uploads (or replaces, until billed) the port-charges document. */
+  uploadPortChargeDocument: async (
+    id: string,
+    file: File,
+  ): Promise<Freight.ClearanceCharge[]> => {
+    const form = new FormData();
+    form.append("file", file);
+    const response = await client.post(
+      `/bookings/${id}/clearance/charges/port-document`,
+      form,
+      { headers: { "Content-Type": "multipart/form-data" } },
+    );
+    return unwrap(response.data) as Freight.ClearanceCharge[];
+  },
+
+  /** GL Ethiopia sets or revises a charge's amount + currency. */
+  billClearanceCharge: async (
+    id: string,
+    chargeId: string,
+    payload: { amount: number; currency: string },
+  ): Promise<Freight.ClearanceCharge[]> => {
+    const response = await client.patch(
+      `/bookings/${id}/clearance/charges/${chargeId}/bill`,
+      payload,
+    );
+    return unwrap(response.data) as Freight.ClearanceCharge[];
+  },
+
+  /** GL Ethiopia issues the charge's payable invoice to the customer. */
+  sendClearanceCharge: async (
+    id: string,
+    chargeId: string,
+  ): Promise<Freight.ClearanceCharge[]> => {
+    const response = await client.post(
+      `/bookings/${id}/clearance/charges/${chargeId}/send`,
+    );
+    return unwrap(response.data) as Freight.ClearanceCharge[];
+  },
+
+  /** GL Ethiopia creates the miscellaneous charge (document + amount + currency). */
+  createMiscellaneousCharge: async (
+    id: string,
+    file: File,
+    payload: { amount: number; currency: string },
+  ): Promise<Freight.ClearanceCharge[]> => {
+    const form = new FormData();
+    form.append("file", file);
+    form.append("amount", String(payload.amount));
+    form.append("currency", payload.currency);
+    const response = await client.post(
+      `/bookings/${id}/clearance/charges/miscellaneous`,
+      form,
+      { headers: { "Content-Type": "multipart/form-data" } },
+    );
+    return unwrap(response.data) as Freight.ClearanceCharge[];
+  },
+
   /** GL ET asks Djibouti to name the officer handling the shipment in transit. */
   requestTransitAssignee: (id: string, note?: string) =>
     postBooking<BookingDetail>(B.CLEARANCE_TRANSIT_ASSIGNEE_REQUEST(id), {
diff --git a/packages/types/src/freight/index.ts b/packages/types/src/freight/index.ts
index 02f4f3f0e..fb3a51508 100644
--- a/packages/types/src/freight/index.ts
+++ b/packages/types/src/freight/index.ts
@@ -188,6 +188,11 @@ export enum InvoiceSource {
   LastMile = "lastmile",
   /** Customs clearance service fee — billed on the booking invoice with the freight. */
   Clearance = "clearance",
+  /**
+   * Post-finalization clearance charge (port charges / miscellaneous) billed
+   * to the customer as its own payable invoice. `sourceId` is the charge id.
+   */
+  ClearanceCharge = "clearance_charge",
   /**
    * A batch of shipping-line credits billed together. Unlike every other
    * source, `sourceId` is the shipping line's id rather than a single record's:
@@ -802,6 +807,40 @@ export interface PricingBreakdown {
 
 export type DocumentReviewStatus = "PENDING" | "APPROVED" | "QUERIED";
 
+// ── Clearance charges (post-finalization customer billing) ──────────────────
+
+export type ClearanceChargeType = "PORT_CHARGES" | "MISCELLANEOUS";
+
+/**
+ * DOC_UPLOADED: GL Djibouti uploaded the supporting document (port charges).
+ * BILLED: GL Ethiopia set amount + currency. SENT: invoice issued to the
+ * customer (ETB pays via gateway, other currencies via Finance's manual
+ * settlement). PAID: the invoice settled.
+ */
+export type ClearanceChargeStatus =
+  | "DOC_UPLOADED"
+  | "BILLED"
+  | "SENT"
+  | "PAID";
+
+/** One clearance charge level on a booking — at most one per type. */
+export interface ClearanceCharge {
+  id: string;
+  bookingId: string;
+  type: ClearanceChargeType;
+  status: ClearanceChargeStatus;
+  file: { id: string; name: string; url: string } | null;
+  amount: number | null;
+  currency: string | null;
+  invoiceId: string | null;
+  invoiceNumber: string | null;
+  uploadedByName: string | null;
+  uploadedAt: string | null;
+  billedByName: string | null;
+  billedAt: string | null;
+  paidAt: string | null;
+}
+
 /** One entry of a clearance document's audit trail, oldest first. */
 export interface ClearanceDocumentEvent {
   type: "UPLOADED" | "RESUBMITTED" | "QUERIED" | "APPROVED";