Merge branch 'dev' of github.com:Tria-plc/edr-platform into freight_feature/usermanagement

2026-08-30 02:58:11 +00:00 · 2026-07-03 18:48:18 +00:00
parent 8db19dfacf 5e8fb306d7
commit ff9cb4e6cd
106 changed files with 4924 additions and 876 deletions
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -121,6 +121,7 @@ import WarehouseInvoicesPage from "./pages/warehouses/WarehouseInvoicesPage";
 import WarehouseListPage from "./pages/warehouses/WarehouseListPage";
 import WarehouseRulesPage from "./pages/warehouses/WarehouseRulesPage";
 import { HealthCheck } from "./features/health/HealthCheck";
+import FaydaCallbackPage from "./pages/FaydaCallbackPage";

 const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[] => [
  {
@@ -330,7 +331,7 @@ const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[] => [
          },
          {
            label: "Terminal Inventory",
-            href: "/dashboard/warehouse-inventory",
+            href: "/dashboard/warehouse-inventory?direction=IMPORT",
            icon: <Package />,
          },
          {
@@ -377,7 +378,7 @@ const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[] => [
          },
          {
            label: "Terminal Inventory",
-            href: "/dashboard/warehouse-inventory",
+            href: "/dashboard/warehouse-inventory?direction=EXPORT",
            icon: <Package />,
          },
        ],
@@ -569,6 +570,7 @@ const App = () => {
      <Routes>
        <Route path="/auth" element={<LoginPage />} />
        <Route path="/um/*" element={<UserManagementHostPage />} />
+        <Route path="/callback" element={<FaydaCallbackPage />} />
        <Route path="*" element={<Navigate to="/auth" replace />} />
      </Routes>
    );
@@ -578,6 +580,7 @@ const App = () => {
    <Routes>
      <Route path="/um/*" element={<UserManagementHostPage />} />
      <Route path="/health" element={<HealthCheck />} />
+      <Route path="/callback" element={<FaydaCallbackPage />} />
      <Route path="/" element={<Navigate to="/dashboard/overview" replace />} />
      <Route
        path="/dashboard"
--- a/apps/edr-freight-web/backoffice/src/components/fleet/FleetFormDialog.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/fleet/FleetFormDialog.tsx
@@ -1,6 +1,8 @@
 import { useEffect, useMemo, useState } from "react";
-import { Loader2, Calendar } from "lucide-react";
+import { Loader2, ShieldCheck } from "lucide-react";
 import {
+  Alert,
+  Badge,
  Button,
  Group,
  Modal,
@@ -12,7 +14,6 @@ import {
  Text,
  Textarea,
  TextInput,
-  ActionIcon,
 } from "@mantine/core";

 import {
@@ -20,6 +21,10 @@ import {
  type FleetFormFieldDef,
 } from "@/pages/fleet/config/resources";
 import type { FleetRecord } from "@/services/fleet/fleet.service";
+import {
+  verifaydaService,
+  type FaydaCallbackMessage,
+} from "@/services/verifayda.service";

 export interface FleetFormDialogProps {
  open: boolean;
@@ -31,8 +36,32 @@ export interface FleetFormDialogProps {
  isSubmitting: boolean;
  selectOptionsLoading?: boolean;
  onSubmit: (values: Record<string, unknown>) => void;
+  /**
+   * Show a "Verify with Fayda" step: opens the eSignet popup and prefills
+   * firstName/lastName/email/phoneNumber/dateOfBirth from the verified
+   * identity, stamping faydaVerified + faydaSub on the payload.
+   */
+  verifyWithFayda?: boolean;
 }

+// Fayda returns gender as "Male"/"Female"; snap it onto the form's uppercase
+// option values (MALE/FEMALE/OTHER) so the Select prefills instead of rendering
+// blank. Unknown/empty values fall through to undefined (field left untouched).
+const normalizeGender = (raw?: string): string | undefined => {
+  const up = (raw ?? "").trim().toUpperCase();
+  if (up === "MALE" || up === "M") return "MALE";
+  if (up === "FEMALE" || up === "F") return "FEMALE";
+  return up ? "OTHER" : undefined;
+};
+
+// Fayda may return the birthdate as "2001/12/01" (slashes), but the date input
+// and validator expect ISO "2001-12-01". Normalize separators + trim to 10 chars
+// so the DOB field prefills instead of silently staying blank.
+const normalizeBirthdate = (raw?: string): string | undefined => {
+  const iso = (raw ?? "").trim().replace(/\//g, "-").slice(0, 10);
+  return /^\d{4}-\d{2}-\d{2}$/.test(iso) ? iso : undefined;
+};
+
 const buildInitialValues = (
  fields: FleetFormFieldDef[],
  emptyValues: Record<string, unknown>,
@@ -72,9 +101,12 @@ const FleetFormDialog = ({
  isSubmitting,
  selectOptionsLoading,
  onSubmit,
+  verifyWithFayda,
 }: FleetFormDialogProps) => {
  const [values, setValues] = useState<Record<string, unknown>>({});
  const [errors, setErrors] = useState<Record<string, string>>({});
+  const [faydaLoading, setFaydaLoading] = useState(false);
+  const [faydaError, setFaydaError] = useState<string | null>(null);

  // Seed the form ONLY when the dialog opens or the edited record changes — NOT
  // when `fields`/`emptyValues` get new object refs (they're rebuilt whenever the
@@ -87,10 +119,88 @@ const FleetFormDialog = ({
    if (open) {
      setValues(buildInitialValues(fields, emptyValues, initialRecord));
      setErrors({});
+      setFaydaError(null);
+      setFaydaLoading(false);
    }
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [open, recordId]);

+  // Receive the ?code&state relayed by the /callback popup, exchange it for
+  // the verified identity, and prefill the matching form fields.
+  useEffect(() => {
+    if (!open || !verifyWithFayda) return;
+    const onMessage = async (event: MessageEvent<FaydaCallbackMessage>) => {
+      if (event.origin !== window.location.origin) return;
+      if (event.data?.type !== "fayda-callback") return;
+
+      if (event.data.error) {
+        setFaydaLoading(false);
+        setFaydaError(event.data.errorDescription ?? event.data.error);
+        return;
+      }
+      if (!event.data.code || !event.data.state) return;
+
+      try {
+        const result = await verifaydaService.complete(event.data.code, event.data.state);
+        if (!result.verified) {
+          setFaydaError("Identity could not be verified");
+          return;
+        }
+        const nameParts = (result.fullName ?? "").trim().split(/\s+/).filter(Boolean);
+        const [firstName, ...rest] = nameParts;
+        const gender = normalizeGender(result.gender);
+        const dateOfBirth = normalizeBirthdate(result.birthdate);
+        setValues((current) => ({
+          ...current,
+          ...(firstName ? { firstName } : {}),
+          ...(rest.length ? { lastName: rest.join(" ") } : {}),
+          ...(result.email ? { email: result.email } : {}),
+          ...(result.phoneNumber ? { phoneNumber: result.phoneNumber } : {}),
+          ...(dateOfBirth ? { dateOfBirth } : {}),
+          ...(gender ? { gender } : {}),
+          faydaVerified: true,
+          ...(result.iamUserId ? { faydaSub: result.iamUserId } : {}),
+        }));
+        setFaydaError(null);
+      } catch (err) {
+        const message =
+          (err as { response?: { data?: { message?: string } } })?.response?.data?.message ??
+          (err instanceof Error ? err.message : "Verification failed");
+        setFaydaError(message);
+      } finally {
+        setFaydaLoading(false);
+      }
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [open, verifyWithFayda]);
+
+  const handleFaydaVerify = async () => {
+    setFaydaError(null);
+    setFaydaLoading(true);
+    try {
+      const { authorizationUrl } = await verifaydaService.start();
+      const popup = window.open(
+        authorizationUrl,
+        "fayda-verify",
+        "width=480,height=760,noopener=no",
+      );
+      if (!popup) {
+        setFaydaLoading(false);
+        setFaydaError("Pop-up blocked — allow pop-ups for this site and retry.");
+      }
+      // Loading stays on until the popup posts back; reopening the dialog resets it.
+    } catch (err) {
+      setFaydaLoading(false);
+      const message =
+        (err as { response?: { data?: { message?: string } } })?.response?.data?.message ??
+        (err instanceof Error ? err.message : "Could not start verification");
+      setFaydaError(message);
+    }
+  };
+
+  const faydaVerified = values.faydaVerified === true;
+
  const shortFields = useMemo(
    () => fields.filter((f) => f.type !== "textarea"),
    [fields],
@@ -127,6 +237,12 @@ const FleetFormDialog = ({
          const date = new Date(stringValue + "T00:00:00Z");
          if (isNaN(date.getTime())) {
            next[field.name] = `${field.label} is not a valid date`;
+          } else if (field.dateBound === "future") {
+            const startOfToday = new Date();
+            startOfToday.setUTCHours(0, 0, 0, 0);
+            if (date <= startOfToday) {
+              next[field.name] = `${field.label} must be in the future`;
+            }
          } else if (date > new Date()) {
            next[field.name] = `${field.label} cannot be in the future`;
          }
@@ -147,6 +263,12 @@ const FleetFormDialog = ({
  }, [fields]);

  const handleSubmit = () => {
+    // Hard gate: a driver record cannot be saved until its identity is verified
+    // with Fayda. Mirrored server-side in DriversService.
+    if (verifyWithFayda && !faydaVerified) {
+      setFaydaError("Verify the driver's identity with Fayda before saving.");
+      return;
+    }
    if (!validate()) return;
    const payload = Object.fromEntries(
      Object.entries(values)
@@ -167,6 +289,9 @@ const FleetFormDialog = ({
  const renderField = (field: FleetFormFieldDef) => {
    const value = values[field.name];
    const error = errors[field.name];
+    // Fayda-owned identity fields (name/email/phone/DOB/gender) are populated
+    // only by verification and never hand-edited.
+    const isDisabled = Boolean(field.disabled || field.faydaLocked);

    if (field.type === "select") {
      return (
@@ -186,7 +311,7 @@ const FleetFormDialog = ({
          }
          error={error}
          searchable
-          disabled={selectOptionsLoading}
+          disabled={selectOptionsLoading || isDisabled}
          rightSection={
            selectOptionsLoading ? (
              <Loader2 size={14} className="animate-spin" />
@@ -216,7 +341,7 @@ const FleetFormDialog = ({
          error={error}
          searchable
          clearable
-          disabled={selectOptionsLoading}
+          disabled={selectOptionsLoading || isDisabled}
          rightSection={
            selectOptionsLoading ? (
              <Loader2 size={14} className="animate-spin" />
@@ -240,7 +365,7 @@ const FleetFormDialog = ({
            }))
          }
          error={error}
-          disabled={field.disabled}
+          disabled={isDisabled}
        />
      );
    }
@@ -260,7 +385,7 @@ const FleetFormDialog = ({
          }
          error={error}
          minRows={3}
-          disabled={field.disabled}
+          disabled={isDisabled}
        />
      );
    }
@@ -280,13 +405,8 @@ const FleetFormDialog = ({
            }))
          }
          error={error}
-          disabled={field.disabled}
+          disabled={isDisabled}
          description={field.description || "Select a date"}
-          rightSection={
-            <ActionIcon size="sm" variant="subtle" color="green">
-              <Calendar size={16} />
-            </ActionIcon>
-          }
          size="sm"
          radius="md"
          styles={{
@@ -318,7 +438,7 @@ const FleetFormDialog = ({
          }))
        }
        error={error}
-        disabled={field.disabled}
+        disabled={isDisabled}
      />
    );
  };
@@ -333,6 +453,40 @@ const FleetFormDialog = ({
      centered
    >
      <Stack gap="md">
+        {verifyWithFayda && (
+          <Group justify="space-between" wrap="nowrap">
+            {faydaVerified ? (
+              <Badge
+                color="green"
+                variant="light"
+                size="lg"
+                leftSection={<ShieldCheck size={14} />}
+              >
+                Identity verified with Fayda
+              </Badge>
+            ) : (
+              <Text size="sm" c="dimmed">
+                Identity must be verified with Fayda before this driver can be
+                saved.
+              </Text>
+            )}
+            <Button
+              variant={faydaVerified ? "default" : "light"}
+              color="edr-green"
+              size="xs"
+              leftSection={<ShieldCheck size={14} />}
+              loading={faydaLoading}
+              onClick={handleFaydaVerify}
+            >
+              {faydaVerified ? "Re-verify" : "Verify with Fayda"}
+            </Button>
+          </Group>
+        )}
+        {verifyWithFayda && faydaError && (
+          <Alert color="red" variant="light">
+            {faydaError}
+          </Alert>
+        )}
        <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
          {shortFields.map(renderField)}
        </SimpleGrid>
@@ -345,6 +499,7 @@ const FleetFormDialog = ({
            color="edr-green"
            loading={isSubmitting}
            onClick={handleSubmit}
+            disabled={verifyWithFayda && !faydaVerified}
          >
            Save
          </Button>
--- a/apps/edr-freight-web/backoffice/src/components/fleet/FleetHistoryModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/fleet/FleetHistoryModal.tsx
@@ -0,0 +1,207 @@
+import { Center, Loader, Modal, Text, Timeline } from "@mantine/core";
+import { useQuery } from "@tanstack/react-query";
+import {
+  Activity,
+  CircleDot,
+  Route,
+  Truck,
+  UserCheck,
+  UserMinus,
+  UserPlus,
+} from "lucide-react";
+
+import {
+  fleetHistoryService,
+  type FleetHistoryEvent,
+} from "@/services/fleet-history.service";
+import type { FleetRecord } from "@/services/fleet/fleet.service";
+
+export interface FleetHistoryModalProps {
+  opened: boolean;
+  onClose: () => void;
+  entity: "driver" | "vehicle";
+  record: FleetRecord | null;
+}
+
+const asObj = (r: FleetRecord | null) => (r ?? {}) as Record<string, unknown>;
+
+const titleFor = (entity: "driver" | "vehicle", record: FleetRecord | null) => {
+  const r = asObj(record);
+  if (entity === "vehicle") {
+    return `Vehicle history — ${r.plateNumber ?? r.code ?? ""}`.trim();
+  }
+  return `Driver history — ${[r.firstName, r.lastName]
+    .filter(Boolean)
+    .join(" ")}`.trim();
+};
+
+const mileLabel = (e: FleetHistoryEvent) =>
+  e.metadata?.mile === "LAST" ? "Last-mile" : "First-mile";
+
+const arrow = (from?: string | null, to?: string | null) =>
+  `${from ?? "—"} → ${to ?? "—"}`;
+
+const metaStr = (e: FleetHistoryEvent, key: string) => {
+  const v = e.metadata?.[key];
+  return typeof v === "string" && v ? v : null;
+};
+
+function describe(e: FleetHistoryEvent, entity: "driver" | "vehicle") {
+  const vehiclePlate = metaStr(e, "vehiclePlate");
+  const driverName = metaStr(e, "driverName") ?? (e.label || null);
+  const bookingRef = metaStr(e, "bookingRef");
+
+  // Compose the detail line with whatever the current view doesn't already
+  // know: on a driver's timeline show which vehicle; always show the booking.
+  const detail = (extra?: string) =>
+    [
+      entity === "driver" && vehiclePlate ? `Vehicle ${vehiclePlate}` : "",
+      bookingRef ? `Booking ${bookingRef}` : "",
+      extra ?? "",
+    ]
+      .filter(Boolean)
+      .join(" · ");
+
+  switch (e.eventType) {
+    case "DRIVER_REGISTERED":
+      return {
+        icon: <UserCheck size={14} />,
+        title: "Driver registered",
+        text: e.toValue ? `Status: ${e.toValue}` : "",
+      };
+    case "VEHICLE_REGISTERED":
+      return {
+        icon: <Truck size={14} />,
+        title: "Vehicle registered",
+        text: e.toValue ? `Availability: ${e.toValue}` : "",
+      };
+    case "DRIVER_ASSIGNED":
+      return {
+        icon: <UserPlus size={14} />,
+        title: entity === "vehicle" ? "Driver assigned" : "Assigned to vehicle",
+        text:
+          entity === "vehicle"
+            ? driverName
+              ? `Driver ${driverName}`
+              : ""
+            : vehiclePlate
+              ? `Vehicle ${vehiclePlate}`
+              : "",
+      };
+    case "DRIVER_UNASSIGNED":
+      return {
+        icon: <UserMinus size={14} />,
+        title:
+          entity === "vehicle"
+            ? "Driver unassigned"
+            : "Unassigned from vehicle",
+        text:
+          entity === "vehicle"
+            ? driverName
+              ? `Driver ${driverName}`
+              : ""
+            : vehiclePlate
+              ? `Vehicle ${vehiclePlate}`
+              : "",
+      };
+    case "VEHICLE_STATUS_CHANGED":
+      return {
+        icon: <CircleDot size={14} />,
+        title: "Status changed",
+        text: arrow(e.fromValue, e.toValue),
+      };
+    case "VEHICLE_AVAILABILITY_CHANGED":
+      return {
+        icon: <Activity size={14} />,
+        title: `Marked ${e.toValue ?? ""}`.trim(),
+        text: e.fromValue ? arrow(e.fromValue, e.toValue) : "",
+      };
+    case "MILE_VEHICLE_ASSIGNED":
+      return {
+        icon: <Route size={14} />,
+        title: `${mileLabel(e)}: vehicle assigned`,
+        text: detail(e.label ? `Status: ${e.label}` : ""),
+      };
+    case "MILE_VEHICLE_RELEASED":
+      return {
+        icon: <Route size={14} />,
+        title: `${mileLabel(e)}: vehicle released`,
+        text: detail(),
+      };
+    case "MILE_STATUS_CHANGED":
+      return {
+        icon: <Route size={14} />,
+        title: `${mileLabel(e)} status`,
+        text: detail(arrow(e.fromValue, e.toValue)),
+      };
+    default:
+      return { icon: <CircleDot size={14} />, title: e.eventType, text: "" };
+  }
+}
+
+const fmt = (iso: string) => {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? iso : d.toLocaleString();
+};
+
+const FleetHistoryModal = ({
+  opened,
+  onClose,
+  entity,
+  record,
+}: FleetHistoryModalProps) => {
+  const id = asObj(record).id ? String(asObj(record).id) : "";
+
+  const { data, isLoading } = useQuery({
+    queryKey: ["fleet-history", entity, id],
+    queryFn: () =>
+      entity === "vehicle"
+        ? fleetHistoryService.vehicle(id)
+        : fleetHistoryService.driver(id),
+    enabled: opened && Boolean(id),
+  });
+
+  const events = data ?? [];
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      title={<Text fw={600}>{titleFor(entity, record)}</Text>}
+      radius="lg"
+      size="lg"
+      centered
+    >
+      {isLoading ? (
+        <Center py="xl">
+          <Loader size="sm" />
+        </Center>
+      ) : events.length === 0 ? (
+        <Text c="dimmed" ta="center" py="lg" size="sm">
+          No history recorded yet. Activity appears here as this{" "}
+          {entity} is assigned, reassigned, or its status changes.
+        </Text>
+      ) : (
+        <Timeline active={events.length} bulletSize={24} lineWidth={2}>
+          {events.map((e) => {
+            const d = describe(e, entity);
+            return (
+              <Timeline.Item key={e.id} bullet={d.icon} title={d.title}>
+                {d.text && (
+                  <Text size="sm" c="dimmed">
+                    {d.text}
+                  </Text>
+                )}
+                <Text size="xs" mt={4} c="dimmed">
+                  {fmt(e.createdAt)}
+                </Text>
+              </Timeline.Item>
+            );
+          })}
+        </Timeline>
+      )}
+    </Modal>
+  );
+};
+
+export default FleetHistoryModal;
--- a/apps/edr-freight-web/backoffice/src/components/fleet/FleetRecordActions.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/fleet/FleetRecordActions.tsx
@@ -1,4 +1,4 @@
-import { Edit2, Trash2, Eye, Users, MoreVertical } from "lucide-react";
+import { Edit2, Trash2, Eye, Users, MoreVertical, History } from "lucide-react";
 import { ActionIcon, Menu, MenuItem, Tooltip } from "@mantine/core";
 import { useNavigate } from "react-router-dom";

@@ -11,6 +11,7 @@ export interface FleetRecordActionsProps {
  onEdit: (record: FleetRecord) => void;
  onRemove: (record: FleetRecord) => void;
  onAssignDriver?: (record: FleetRecord) => void;
+  onHistory?: (record: FleetRecord) => void;
  layout?: "row" | "compact";
 }

@@ -20,12 +21,16 @@ const FleetRecordActions = ({
  onEdit,
  onRemove,
  onAssignDriver,
+  onHistory,
  layout = "row",
 }: FleetRecordActionsProps) => {
  const navigate = useNavigate();
  const removeLabel = config.removeActionLabel ?? "Delete";
  const showDetail = Boolean(config.detailPath && "id" in record);
  const isVehicle = config.slug === "vehicles";
+  const showHistory =
+    Boolean(onHistory) &&
+    (config.slug === "drivers" || config.slug === "vehicles");

  const handleDetail = () => {
    if (!config.detailPath || !("id" in record)) return;
@@ -57,6 +62,14 @@ const FleetRecordActions = ({
          >
            Edit
          </MenuItem>
+          {showHistory ? (
+            <MenuItem
+              onClick={() => onHistory?.(record)}
+              leftSection={<History size={14} strokeWidth={2} />}
+            >
+              History
+            </MenuItem>
+          ) : null}
          {showDetail ? (
            <MenuItem
              onClick={handleDetail}
--- a/apps/edr-freight-web/backoffice/src/components/fleet/fleetFormat.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/fleet/fleetFormat.tsx
@@ -4,7 +4,7 @@ import { Badge, Text } from "@mantine/core";
 import type { ColumnFormat } from "@/pages/ruleEngine/config/resources";
 import { formatCell as formatRuleEngineCell } from "@/components/ruleEngine/ruleEngineFormat";

-export type FleetColumnFormat = ColumnFormat | "statusBadge";
+export type FleetColumnFormat = ColumnFormat | "statusBadge" | "verifiedBadge";

 const optionLabelMap = new Map<string, Map<string, string>>();

@@ -20,6 +20,16 @@ export const formatFleetCell = (
  format?: FleetColumnFormat,
  accessorKey?: string,
 ): ReactNode => {
+  if (format === "verifiedBadge") {
+    return value === true ? (
+      <Badge variant="light" color="green" size="sm" radius="md">
+        Verified
+      </Badge>
+    ) : (
+      <Text size="sm" c="dimmed">—</Text>
+    );
+  }
+
  if (format === "statusBadge") {
    const status = value == null || value === "" ? "—" : String(value);
    const getStatusColor = (st: string): string => {
--- a/apps/edr-freight-web/backoffice/src/components/operations/LastMileSteps.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/operations/LastMileSteps.tsx
@@ -0,0 +1,93 @@
+import { Group, Stack, Text, Timeline, Tooltip } from "@mantine/core";
+import { Check } from "lucide-react";
+
+/** One stage of the last-mile delivery workflow. */
+export interface LastMileStepState {
+  label: string;
+  done: boolean;
+  active: boolean;
+  /** Optional stamp/value shown next to the step (plate, time, distance…). */
+  detail?: string | null;
+}
+
+/**
+ * Compact 6-dot progress bar for a table row — filled = done, ringed = current,
+ * hollow = pending. Hover a dot for its label + stamp.
+ */
+export function LastMileStepBar({ steps }: { steps: LastMileStepState[] }) {
+  return (
+    <Group gap={4} wrap="nowrap">
+      {steps.map((s, i) => {
+        const color = s.done
+          ? "var(--mantine-color-green-6)"
+          : s.active
+            ? "var(--mantine-color-blue-5)"
+            : "var(--mantine-color-gray-4)";
+        return (
+          <Tooltip
+            key={i}
+            withArrow
+            label={`${s.label}${s.detail ? ` · ${s.detail}` : ""}`}
+          >
+            <span
+              style={{
+                width: 10,
+                height: 10,
+                borderRadius: "50%",
+                background: s.done ? color : "transparent",
+                border: `2px solid ${color}`,
+                boxShadow: s.active
+                  ? "0 0 0 2px var(--mantine-color-blue-1)"
+                  : undefined,
+                display: "inline-block",
+                flex: "0 0 auto",
+              }}
+            />
+          </Tooltip>
+        );
+      })}
+    </Group>
+  );
+}
+
+/**
+ * Vertical stepper for the detail view — completed steps bulleted + green, the
+ * current step highlighted, each showing its stamp/value when known.
+ */
+export function LastMileStepper({ steps }: { steps: LastMileStepState[] }) {
+  const activeIndex = steps.findIndex((s) => s.active);
+  // Timeline highlights items with index < `active`; count of done steps drives it.
+  const doneCount = steps.filter((s) => s.done).length;
+  return (
+    <Timeline
+      active={activeIndex === -1 ? steps.length : doneCount}
+      bulletSize={22}
+      lineWidth={2}
+      color="green"
+    >
+      {steps.map((s, i) => (
+        <Timeline.Item
+          key={i}
+          bullet={s.done ? <Check size={12} /> : undefined}
+          title={
+            <Text size="sm" fw={s.active ? 600 : 500} c={s.active ? "blue" : undefined}>
+              {s.label}
+            </Text>
+          }
+          lineVariant={s.done ? "solid" : "dashed"}
+        >
+          <Stack gap={0}>
+            <Text size="xs" c="dimmed">
+              {s.done ? "Done" : s.active ? "Current step" : "Pending"}
+            </Text>
+            {s.detail && (
+              <Text size="xs" c="dimmed">
+                {s.detail}
+              </Text>
+            )}
+          </Stack>
+        </Timeline.Item>
+      ))}
+    </Timeline>
+  );
+}
--- a/apps/edr-freight-web/backoffice/src/components/trainScheduling/ImportLoadingConfirmationPanel.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/trainScheduling/ImportLoadingConfirmationPanel.tsx
@@ -0,0 +1,172 @@
+import { useMemo, useState } from "react";
+import { PackageCheck } from "lucide-react";
+import { Badge, Button, Checkbox, Group, Loader, Paper, Stack, Text } from "@mantine/core";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import toast from "react-hot-toast";
+
+import { api } from "@/services/api";
+import type {
+  ImportLoadingBooking,
+  ImportLoadingBookingsResponse,
+  LoadingStatus,
+} from "@/types/trainScheduling";
+
+function ImportLoadingBookingRow({
+  booking,
+  selected,
+  onToggle,
+}: {
+  booking: ImportLoadingBooking;
+  selected: boolean;
+  onToggle: () => void;
+}) {
+  return (
+    <Group
+      align="flex-start"
+      wrap="nowrap"
+      p="sm"
+      style={{
+        border: `1px solid ${
+          selected ? "var(--mantine-color-edr-green-3)" : "var(--mantine-color-gray-2)"
+        }`,
+        borderRadius: 12,
+        background: selected ? "var(--mantine-color-edr-green-0)" : "white",
+        transition: "border-color 120ms ease, background 120ms ease",
+      }}
+    >
+      <Checkbox checked={selected} onChange={onToggle} mt={4} color="edr-green" />
+      <Stack gap={4} style={{ flex: 1 }}>
+        <Group gap="xs" wrap="wrap">
+          <PackageCheck size={14} />
+          <Text fw={600} size="sm">
+            {booking.reference ?? booking.id}
+          </Text>
+          <Badge
+            variant="light"
+            size="xs"
+            color={booking.loadingStatus === "LOADED" ? "edr-green" : "gray"}
+          >
+            {booking.loadingStatus}
+          </Badge>
+        </Group>
+        <Text size="xs" c="dimmed">
+          {booking.customer ?? "Unknown customer"}
+        </Text>
+        <Text size="xs" c="dimmed">
+          {booking.weightTons}T
+        </Text>
+      </Stack>
+    </Group>
+  );
+}
+
+export function ImportLoadingConfirmationPanel({
+  scheduleId,
+  items,
+  isLoading,
+}: {
+  scheduleId: string;
+  items: ImportLoadingBooking[];
+  isLoading?: boolean;
+}) {
+  const [selectedIds, setSelectedIds] = useState<string[]>([]);
+  const queryClient = useQueryClient();
+
+  const updateStatus = useMutation<
+    ImportLoadingBookingsResponse,
+    Error,
+    { id: string; bookingIds: string[]; loadingStatus: LoadingStatus }
+  >({
+    ...api.trainScheduling.updateImportLoadingStatus.mutationOptions(),
+    onSuccess: () => {
+      setSelectedIds([]);
+      queryClient.invalidateQueries({
+        queryKey: api.trainScheduling.importLoadingBookings.queryKey({ id: scheduleId }),
+      });
+    },
+    onError: (error) => {
+      toast.error(error instanceof Error ? error.message : "Could not update loading status");
+    },
+  });
+
+  const toggle = (id: string) => {
+    setSelectedIds((prev) =>
+      prev.includes(id) ? prev.filter((x) => x !== id) : [...prev, id],
+    );
+  };
+
+  const allIds = useMemo(() => items.map((b) => b.id), [items]);
+
+  if (isLoading) {
+    return (
+      <Group justify="center" py="md">
+        <Loader size="sm" />
+        <Text size="sm" c="dimmed">
+          Loading import bookings…
+        </Text>
+      </Group>
+    );
+  }
+
+  if (!items.length) {
+    return (
+      <Paper p="lg" radius="lg" withBorder bg="gray.0">
+        <Text size="sm" c="dimmed" ta="center">
+          No paid import bookings with wagons allocated on this schedule
+        </Text>
+      </Paper>
+    );
+  }
+
+  return (
+    <Stack gap="md">
+      <Group justify="space-between" wrap="wrap">
+        <Text size="sm" fw={500}>
+          Import bookings ({items.length})
+        </Text>
+        <Group gap="sm">
+          <Button variant="light" size="compact-sm" onClick={() => setSelectedIds(allIds)}>
+            Select all
+          </Button>
+          <Button variant="subtle" size="compact-sm" onClick={() => setSelectedIds([])}>
+            Clear
+          </Button>
+        </Group>
+      </Group>
+
+      <Stack gap="sm">
+        {items.map((booking) => (
+          <ImportLoadingBookingRow
+            key={booking.id}
+            booking={booking}
+            selected={selectedIds.includes(booking.id)}
+            onToggle={() => toggle(booking.id)}
+          />
+        ))}
+      </Stack>
+
+      <Group gap="sm">
+        <Button
+          color="edr-green"
+          disabled={!selectedIds.length}
+          loading={updateStatus.isPending}
+          onClick={() =>
+            updateStatus.mutate({ id: scheduleId, bookingIds: selectedIds, loadingStatus: "LOADED" })
+          }
+        >
+          Mark loaded
+        </Button>
+        <Button
+          variant="outline"
+          disabled={!selectedIds.length}
+          loading={updateStatus.isPending}
+          onClick={() =>
+            updateStatus.mutate({ id: scheduleId, bookingIds: selectedIds, loadingStatus: "UNLOADED" })
+          }
+        >
+          Mark unloaded
+        </Button>
+      </Group>
+    </Stack>
+  );
+}
--- a/apps/edr-freight-web/backoffice/src/components/warehouses/CreateWarehouseModal.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/CreateWarehouseModal.tsx
@@ -14,7 +14,7 @@ import { useMutation, useQuery } from '@tanstack/react-query';
 import { api } from '@/services/api';
 import { useToast } from '@/hooks/use-toast';
 import type { SaveWarehousePayload, Warehouse, WarehouseType } from '@/types/warehouse';
-import { extractErrorMessage, statusOptions, warehouseTypeOptions } from './options';
+import { extractErrorMessage, lettersOnly, statusOptions, warehouseTypeOptions } from './options';

 interface CreateWarehouseModalProps {
  opened: boolean;
@@ -120,7 +120,7 @@ export function CreateWarehouseModal({ opened, onClose, warehouse }: CreateWareh
            placeholder="Modjo Open Warehouse"
            required
            value={form.name}
-            onChange={(e) => { const v = e.currentTarget.value; setForm((f) => ({ ...f, name: v })); }}
+            onChange={(e) => { const v = lettersOnly(e.currentTarget.value); setForm((f) => ({ ...f, name: v })); }}
          />
          <TextInput
            label="Code"
--- a/apps/edr-freight-web/backoffice/src/components/warehouses/options.ts
+++ b/apps/edr-freight-web/backoffice/src/components/warehouses/options.ts
@@ -48,6 +48,9 @@ export const formatDate = (value: string | null | undefined) => {
  });
 };

+// 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, '');
+
 export const extractErrorMessage = (error: unknown, fallback = 'Something went wrong') => {
  const responseData = (error as { response?: { data?: unknown } })?.response?.data;
  const data = responseData && typeof responseData === 'object' ? (responseData as Record<string, unknown>) : undefined;
--- a/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts
@@ -109,6 +109,8 @@ export const QUERY_KEYS = {
      ["train-scheduling", "unassigned", id] as const,
    compositionRemovals: (id: string) =>
      ["train-scheduling", "removals", id] as const,
+    importLoadingBookings: (id: string) =>
+      ["train-scheduling", "import-loading-bookings", id] as const,
  },

  FLEET: {
--- a/apps/edr-freight-web/backoffice/src/constants/URLS.ts
+++ b/apps/edr-freight-web/backoffice/src/constants/URLS.ts
@@ -324,6 +324,10 @@ export const URL_CONSTANTS = {
    PIN_WAGONS: (id: string) => `/train-scheduling/schedules/${id}/pin-wagons`,
    FINALIZE: (id: string) => `/train-scheduling/schedules/${id}/finalize`,
    DISPATCH: (id: string) => `/train-scheduling/schedules/${id}/dispatch`,
+    IMPORT_LOADING_BOOKINGS: (id: string) =>
+      `/train-scheduling/schedules/${id}/import-loading-bookings`,
+    IMPORT_LOADING_STATUS: (id: string) =>
+      `/train-scheduling/schedules/${id}/import-loading-status`,
    IMPORT_DJIBOUTI: (id: string) =>
      `/train-scheduling/schedules/${id}/import-djibouti`,
    IMPORT_DJIBOUTI_DOCUMENTS: (id: string) =>
--- a/apps/edr-freight-web/backoffice/src/pages/FaydaCallbackPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/FaydaCallbackPage.tsx
@@ -0,0 +1,56 @@
+import { useEffect, useState } from "react";
+import { Center, Loader, Stack, Text } from "@mantine/core";
+
+import type { FaydaCallbackMessage } from "@/services/verifayda.service";
+
+/**
+ * Landing page for the eSignet redirect_uri (FAYDA_WEB_REDIRECT_URI →
+ * http://localhost:5183/callback). Runs inside the verification popup:
+ * relays ?code&state (or ?error) to the window that opened it via
+ * postMessage, then closes itself. The opener performs the /complete call
+ * so the single-use session is only consumed once, in one place.
+ */
+const FaydaCallbackPage = () => {
+  const [standalone, setStandalone] = useState(false);
+
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    const message: FaydaCallbackMessage = {
+      type: "fayda-callback",
+      code: params.get("code") ?? undefined,
+      state: params.get("state") ?? undefined,
+      error: params.get("error") ?? undefined,
+      errorDescription: params.get("error_description") ?? undefined,
+    };
+
+    if (window.opener && window.opener !== window) {
+      (window.opener as Window).postMessage(message, window.location.origin);
+      window.close();
+    } else {
+      // Opened as a full-page redirect instead of a popup — nothing to relay to.
+      setStandalone(true);
+    }
+  }, []);
+
+  return (
+    <Center h="100vh">
+      <Stack align="center" gap="sm">
+        {standalone ? (
+          <>
+            <Text fw={600}>Verification window lost its parent page</Text>
+            <Text size="sm" c="dimmed">
+              Close this tab and restart the verification from the form.
+            </Text>
+          </>
+        ) : (
+          <>
+            <Loader size="sm" />
+            <Text size="sm" c="dimmed">Completing Fayda verification…</Text>
+          </>
+        )}
+      </Stack>
+    </Center>
+  );
+};
+
+export default FaydaCallbackPage;
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/FleetResourcePage.tsx
@@ -10,6 +10,7 @@ import { Navigate, useLocation } from "react-router-dom";

 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 { formatFleetCell, registerFleetOptionLabels } from "@/components/fleet/fleetFormat";
@@ -42,6 +43,7 @@ const FleetResourcePage = () => {
  const [editing, setEditing] = useState<FleetRecord | null>(null);
  const [removeTarget, setRemoveTarget] = useState<FleetRecord | null>(null);
  const [assigningDriver, setAssigningDriver] = useState<FleetRecord | null>(null);
+  const [historyTarget, setHistoryTarget] = useState<FleetRecord | null>(null);
  const [selectedDriver, setSelectedDriver] = useState<string>("");
  const { viewMode, setViewMode } = useFleetViewMode(slug);

@@ -273,6 +275,7 @@ const FleetResourcePage = () => {
            }}
            onRemove={setRemoveTarget}
            onAssignDriver={setAssigningDriver}
+            onHistory={setHistoryTarget}
          />
        </div>
      ),
@@ -510,6 +513,7 @@ const FleetResourcePage = () => {
        isSubmitting={create.isPending || update.isPending}
        selectOptionsLoading={selectOptionsLoading}
        onSubmit={handleFormSubmit}
+        verifyWithFayda={Boolean(config.faydaVerification)}
      />

      <Modal
@@ -580,6 +584,13 @@ const FleetResourcePage = () => {
          </Group>
        </Stack>
      </Modal>
+
+      <FleetHistoryModal
+        opened={Boolean(historyTarget)}
+        onClose={() => setHistoryTarget(null)}
+        entity={slug === "vehicles" ? "vehicle" : "driver"}
+        record={historyTarget}
+      />
    </Container>
  );
 };
--- a/apps/edr-freight-web/backoffice/src/pages/fleet/config/drivers.ts
+++ b/apps/edr-freight-web/backoffice/src/pages/fleet/config/drivers.ts
@@ -8,6 +8,12 @@ const DRIVER_STATUS_OPTIONS = [
  { label: "On leave", value: "ON_LEAVE" },
 ];

+const DRIVER_GENDER_OPTIONS = [
+  { label: "Male", value: "MALE" },
+  { label: "Female", value: "FEMALE" },
+  { label: "Other", value: "OTHER" },
+];
+
 export const driversConfig: FleetResourceConfig = {
  slug: "drivers",
  label: "Drivers",
@@ -29,24 +35,28 @@ export const driversConfig: FleetResourceConfig = {
      options: DRIVER_STATUS_OPTIONS,
    },
  ],
+  faydaVerification: true,
  searchKeys: ["firstName", "lastName", "email", "phoneNumber", "licenseNumber", "status"],
  columns: [
-    { id: "licenseNumber", header: "License Number", accessorKey: "licenseNumber", format: "code", size: 140 },
+    { id: "licenseNumber", header: "Driver's License Number", accessorKey: "licenseNumber", format: "code", size: 180 },
    { id: "firstName", header: "First Name", accessorKey: "firstName", format: "code", size: 120 },
    { id: "lastName", header: "Last Name", accessorKey: "lastName", format: "code", size: 120 },
    { id: "email", header: "Email", accessorKey: "email", format: "code", size: 180 },
    { id: "phoneNumber", header: "Phone", accessorKey: "phoneNumber", format: "code", size: 120 },
+    { id: "gender", header: "Gender", accessorKey: "gender", format: "code", size: 90 },
    { id: "licenseExpiryDate", header: "License Expiry", accessorKey: "licenseExpiryDate", format: "code", size: 130 },
    { id: "status", header: "Status", accessorKey: "status", format: "statusBadge", size: 100 },
+    { id: "faydaVerified", header: "Fayda", accessorKey: "faydaVerified", format: "verifiedBadge", size: 90 },
  ],
  formFields: [
-    { name: "licenseNumber", label: "License Number", type: "text", required: true },
-    { name: "firstName", label: "First Name", type: "text", required: true },
-    { name: "lastName", label: "Last Name", type: "text", required: true },
-    { name: "email", label: "Email", type: "email", required: true },
-    { name: "phoneNumber", label: "Phone Number", type: "text", required: true },
-    { name: "dateOfBirth", label: "Date of Birth", type: "date", required: true },
-    { name: "licenseExpiryDate", label: "License Expiry Date", type: "date", required: true },
+    { name: "licenseNumber", label: "Driver's License Number", type: "text", required: true },
+    { name: "firstName", label: "First Name", type: "text", required: true, faydaLocked: true },
+    { name: "lastName", label: "Last Name", type: "text", required: true, faydaLocked: true },
+    { name: "email", label: "Email", type: "email", required: true, faydaLocked: true },
+    { name: "phoneNumber", label: "Phone Number", type: "text", required: true, faydaLocked: true },
+    { name: "dateOfBirth", label: "Date of Birth", type: "date", required: true, faydaLocked: true },
+    { name: "gender", label: "Gender", type: "select", options: DRIVER_GENDER_OPTIONS, faydaLocked: true },
+    { name: "licenseExpiryDate", label: "License Expiry Date", type: "date", required: true, dateBound: "future" },
    { name: "status", label: "Status", type: "select", required: true, options: DRIVER_STATUS_OPTIONS },
    { name: "vehicleTypesAuthorized", label: "Authorized Vehicle Types", type: "multiselect", options: VEHICLE_TYPE_OPTIONS },
    { name: "address", label: "Address", type: "textarea" },
@@ -60,6 +70,7 @@ export const driversConfig: FleetResourceConfig = {
    email: "",
    phoneNumber: "",
    dateOfBirth: "",
+    gender: "",
    licenseExpiryDate: "",
    status: "ACTIVE",
    vehicleTypesAuthorized: [],
--- 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,13 +33,23 @@ export interface FleetResourceColumn {
  id: string;
  header: string;
  accessorKey: string;
-  format?: ColumnFormat | "statusBadge";
+  format?: ColumnFormat | "statusBadge" | "verifiedBadge";
  size?: number;
 }

 export interface FleetFormFieldDef extends FormFieldDef {
  dynamicOptions?: FleetDynamicOptions;
  noneOption?: boolean;
+  /**
+   * Field is owned by the Fayda identity — populated only by verification and
+   * never hand-edited. Rendered disabled in the form.
+   */
+  faydaLocked?: boolean;
+  /**
+   * Direction a `date` field is constrained to. "future" = must be after today
+   * (e.g. a license expiry); "past" (default) = cannot be in the future.
+   */
+  dateBound?: "past" | "future";
 }

 export interface FleetListFilterDef {
@@ -73,6 +83,8 @@ export interface FleetResourceConfig {
  cardCodeKey?: string;
  cardSubtitleKey?: string;
  searchKeys: string[];
+  /** Offer Fayda identity verification in the add/edit form (drivers). */
+  faydaVerification?: boolean;
 }

 export const FLEET_BASE_PATH_BY_SLUG: Record<FleetResourceSlug, string> = {
--- a/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/operations/FirstMilePage.tsx
@@ -6,6 +6,7 @@ import {
  MoreHorizontal,
  PackageCheck,
  Printer,
+  Receipt,
  RefreshCw,
  Ruler,
  Trash,
@@ -879,10 +880,14 @@ const FirstMilePage = () => {
                <Menu.Dropdown>
                  <Menu.Item
                    leftSection={<ArrowRight size={15} />}
-                    disabled={!nextStatus}
+                    disabled={!nextStatus || (nextStatus === "IN_TRANSIT" && !assigned)}
                    onClick={() => handleAdvanceStatus(row.original)}
                  >
-                    {nextStatus ? `Mark ${STATUS_META[nextStatus].label}` : STATUS_META[row.original.status].label}
+                    {nextStatus === "IN_TRANSIT" && !assigned
+                      ? "Assign a vehicle first"
+                      : nextStatus
+                        ? `Mark ${STATUS_META[nextStatus].label}`
+                        : STATUS_META[row.original.status].label}
                  </Menu.Item>
                  <Menu.Divider />
                  <Menu.Item
@@ -919,6 +924,13 @@ const FirstMilePage = () => {
                  >
                    Add distance
                  </Menu.Item>
+                  <Menu.Item
+                    leftSection={<Receipt size={15} />}
+                    disabled={!(row.original.exactKm != null && row.original.exactKm > 0)}
+                    onClick={() => openInvoice(row.original)}
+                  >
+                    Generate Invoice
+                  </Menu.Item>
                  {canPrint && (
                    <Menu.Item
                      leftSection={<Printer size={15} />}
@@ -954,7 +966,7 @@ const FirstMilePage = () => {
  }, [vehicleOptions]);

  return (
-    <Stack gap="md">
+    <Stack gap="md" p="md">
      <Card radius="lg" padding={0} withBorder style={{ borderColor: "var(--mantine-color-gray-2)" }}>
        <Stack gap={0}>
          <Box px="md" pt="md" pb="sm" w="100%">
--- a/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/operations/LastMilePage.tsx
@@ -4,6 +4,7 @@ import {
  Eye,
  MoreHorizontal,
  Printer,
+  Receipt,
  RefreshCw,
  Ruler,
  Trash,
@@ -49,6 +50,7 @@ import { driversService, type Driver } from "@/services/drivers.service";
 import { ratesService } from "@/services/rates.service";
 import { LastMileContainerAllocationTable, type LastMileContainerRow } from "@/components/LastMileContainerAllocationTable";
 import { ReleaseOrderModal, type ReleaseOrderTruckPrefill } from "@/components/warehouses/ReleaseOrderModal";
+import { LastMileStepper, type LastMileStepState } from "@/components/operations/LastMileSteps";
 import { api } from "@/auth/http";

 const formatPrice = (amount: number) =>
@@ -92,6 +94,58 @@ const vehicleLabel = (record: LastMileRecord) => {

 const isAssigned = (record: LastMileRecord) => Boolean(record.vehicleId);

+const fmtStamp = (iso?: string | null) => {
+  if (!iso) return null;
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? null : d.toLocaleString();
+};
+
+/**
+ * Derive the 6-step last-mile workflow state for a record. Step completion is
+ * read from the record + its pickup-ready (warehouse release) row:
+ * assign→vehicleId, arrived→release order issued, leave→releaseDate,
+ * in-transit/delivered→status, distance→exactKm.
+ */
+const computeLastMileSteps = (
+  record: LastMileRecord,
+  releaseRow?: ImportUnloadedItem,
+): LastMileStepState[] => {
+  const exactKm = (record as { exactKm?: number | null }).exactKm;
+  // Truck arrival/leave live in the transient warehouse pickup-ready queue and
+  // vanish once the item is released. So once the leg is IN_TRANSIT/DELIVERED,
+  // treat both as done (the truck must have arrived + left to get there).
+  const past = record.status === "IN_TRANSIT" || record.status === "DELIVERED";
+  const flags = [
+    record.status !== "PAYMENT_PENDING",
+    Boolean(record.vehicleId),
+    past || Boolean(releaseRow?.releaseOrderReference),
+    past || Boolean(releaseRow?.releaseDate),
+    past,
+    exactKm != null,
+    exactKm != null, // Generate Invoice — auto-generated when distance is saved
+    record.status === "DELIVERED",
+  ];
+  // Current step = earliest incomplete one.
+  const activeIdx = flags.findIndex((f) => !f);
+  const labels = ["Ready to Transit", "Assign vehicle", "Truck arrived", "Truck leave", "In transit", "Add distance", "Generate Invoice", "Delivered"];
+  const details: (string | null)[] = [
+    null,
+    record.vehicle?.plateNumber ?? null,
+    releaseRow?.releaseOrderReference ?? null,
+    fmtStamp(releaseRow?.releaseDate),
+    null,
+    exactKm != null ? `${exactKm} KM` : null,
+    exactKm != null ? "Invoice ready" : null,
+    fmtStamp(releaseRow?.deliveredAt),
+  ];
+  return labels.map((label, i) => ({
+    label,
+    done: flags[i],
+    active: i === activeIdx,
+    detail: details[i],
+  }));
+};
+
 const bookingRef = (r: LastMileRecord) => r.booking?.reference ?? r.bookingId;
 const customerName = (r: LastMileRecord) => r.booking?.company?.name ?? "—";
 const deliveryLocation = (r: LastMileRecord) => r.booking?.lastMileDeliveryAddress ?? "—";
@@ -955,7 +1009,24 @@ const LastMilePage = () => {
          const delivered = row.original.status === "DELIVERED";
          const releaseRow =
            pickupReadyByBooking.get(row.original.bookingId) ?? pickupReadyByBooking.get(bookingRef(row.original));
-          const truckArrivalLabel = releaseRow?.releaseOrderReference ? "Truck Leaving" : "Truck Arrival";
+          // Gate on PERSISTENT state (status/vehicle/distance), not the truck
+          // arrival/leave signals — those live in the warehouse queue and vanish
+          // once the item is released, so they can't gate the status advance.
+          const status = row.original.status;
+          const hasDistance = row.original.exactKm != null;
+          // Advance: PAYMENT_PENDING→Ready, READY_TO_TRANSIT→In-transit (needs a
+          // vehicle), IN_TRANSIT→Delivered (needs distance/invoice).
+          const canAdvance =
+            status === "PAYMENT_PENDING" ||
+            (status === "READY_TO_TRANSIT" && assigned) ||
+            (status === "IN_TRANSIT" && hasDistance);
+          const canAssignStep = !assigned && status !== "DELIVERED";
+          const canDistance = status === "IN_TRANSIT";
+          // Truck arrival/leaving are independent — each driven only by its own
+          // warehouse state: arrive once assigned & not arrived, leave once
+          // arrived & not departed.
+          const canArrive = assigned && !releaseRow?.releaseOrderReference;
+          const canLeave = Boolean(releaseRow?.releaseOrderReference) && !releaseRow?.releaseDate;
          return (
            <Group gap={4} justify="flex-end" wrap="nowrap">
              <Menu position="bottom-end" width={200} withinPortal>
@@ -967,15 +1038,17 @@ const LastMilePage = () => {
                <Menu.Dropdown>
                  <Menu.Item
                    leftSection={<ArrowRight size={15} />}
-                    disabled={!nextStatus}
+                    disabled={!nextStatus || !canAdvance}
                    onClick={() => handleAdvanceStatus(row.original)}
                  >
-                    {nextStatus ? `Mark ${STATUS_META[nextStatus].label}` : STATUS_META[row.original.status].label}
+                    {nextStatus
+                      ? `Mark ${STATUS_META[nextStatus].label}`
+                      : STATUS_META[row.original.status].label}
                  </Menu.Item>
                  <Menu.Divider />
                  <Menu.Item
                    leftSection={<Truck size={15} />}
-                    disabled={assigned || delivered}
+                    disabled={!canAssignStep}
                    onClick={() => openAssign(row.original.id)}
                  >
                    Assign
@@ -989,10 +1062,17 @@ const LastMilePage = () => {
                  </Menu.Item>
                  <Menu.Item
                    leftSection={<Truck size={15} />}
-                    disabled={!assigned}
+                    disabled={!canArrive}
                    onClick={() => openTruckArrival(row.original)}
                  >
-                    {truckArrivalLabel}
+                    Truck Arrival
+                  </Menu.Item>
+                  <Menu.Item
+                    leftSection={<Truck size={15} />}
+                    disabled={!canLeave}
+                    onClick={() => openTruckArrival(row.original)}
+                  >
+                    Truck Leaving
                  </Menu.Item>
                  <Menu.Divider />
                  <Menu.Item
@@ -1003,11 +1083,18 @@ const LastMilePage = () => {
                  </Menu.Item>
                  <Menu.Item
                    leftSection={<Ruler size={15} />}
-                    disabled={delivered}
+                    disabled={!canDistance}
                    onClick={() => openDistance(row.original.id)}
                  >
                    Add distance
                  </Menu.Item>
+                  <Menu.Item
+                    leftSection={<Receipt size={15} />}
+                    disabled={!(row.original.exactKm != null && row.original.exactKm > 0)}
+                    onClick={() => openInvoice(row.original)}
+                  >
+                    Generate Invoice
+                  </Menu.Item>
                  {canPrint && (
                    <Menu.Item
                      leftSection={<Printer size={15} />}
@@ -1044,7 +1131,7 @@ const LastMilePage = () => {
  }, [vehicleOptions, pickupReadyByBooking]);

  return (
-    <Stack gap="md">
+    <Stack gap="md" p="md">
      <Card radius="lg" padding={0} withBorder style={{ borderColor: "var(--mantine-color-gray-2)" }}>
        <Stack gap={0}>
          <Box px="md" pt="md" pb="sm" w="100%">
@@ -1320,6 +1407,18 @@ const LastMilePage = () => {
      >
        <Stack gap="md">
          {activeRecord && <BookingInfo record={activeRecord} />}
+          {activeRecord && (
+            <Card withBorder padding="md" radius="md">
+              <Text fw={600} size="sm" mb="sm">Delivery steps</Text>
+              <LastMileStepper
+                steps={computeLastMileSteps(
+                  activeRecord,
+                  pickupReadyByBooking.get(activeRecord.bookingId) ??
+                    pickupReadyByBooking.get(bookingRef(activeRecord)),
+                )}
+              />
+            </Card>
+          )}
          <Group justify="flex-end">
            <Button variant="default" onClick={() => { setDetailOpen(false); setActiveId(null); }}>Close</Button>
          </Group>
--- a/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx
@@ -45,6 +45,7 @@ import {
 } from "@/components/trainScheduling/containerPlacement.util";
 import { ContainerPlacementGrid } from "@/components/trainScheduling/ContainerPlacementGrid";
 import { FleetAvailabilitySummary } from "@/components/trainScheduling/FleetAvailabilitySummary";
+import { ImportLoadingConfirmationPanel } from "@/components/trainScheduling/ImportLoadingConfirmationPanel";
 import { RescheduleTrainDialog } from "@/components/trainScheduling/RescheduleTrainDialog";
 import { ScheduleBatchPanel } from "@/components/trainScheduling/ScheduleBatchPanel";
 import { ScheduleBookingsStep } from "@/components/trainScheduling/ScheduleBookingsStep";
@@ -145,6 +146,13 @@ export default function TrainScheduleV2DetailPage() {
    },
  });

+  const importLoadingQuery = useQuery(
+    api.trainScheduling.importLoadingBookings.queryOptions({
+      input: { id: scheduleId ?? "" },
+      enabled: Boolean(scheduleId && schedule?.direction === "IMPORT"),
+    }),
+  );
+
  const eligibleFilters = useMemo(
    () =>
      schedule
@@ -955,6 +963,23 @@ export default function TrainScheduleV2DetailPage() {
        ]}
      />

+      {schedule?.direction === "IMPORT" ? (
+        <Paper radius="xl" p="lg" withBorder>
+          <Stack gap="md">
+            <Text fw={600}>Import loading confirmation</Text>
+            <Text size="sm" c="dimmed">
+              Paid import bookings with a wagon allocated on this schedule. Marking loaded/unloaded
+              is tracking only — it does not block dispatch.
+            </Text>
+            <ImportLoadingConfirmationPanel
+              scheduleId={scheduleId as string}
+              items={importLoadingQuery.data?.items ?? []}
+              isLoading={importLoadingQuery.isLoading}
+            />
+          </Stack>
+        </Paper>
+      ) : null}
+
      {gatepassApplies ? (
        <Paper radius="xl" p="lg" withBorder>
          <Stack gap="md">
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/ExportDjiboutiUnloadingQueuePage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/ExportDjiboutiUnloadingQueuePage.tsx
@@ -14,7 +14,17 @@ import {
  Text,
 } from '@mantine/core';
 import { useNavigate } from 'react-router-dom';
-import { ChevronDown, ChevronRight, Eye, FileText, History, PackageOpen, Truck } from 'lucide-react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import {
+  ChevronDown,
+  ChevronRight,
+  Eye,
+  FileText,
+  History,
+  PackageOpen,
+  ShieldCheck,
+  Truck,
+} from 'lucide-react';

 import { PageHeader } from '@/components/page';
 import Breadcrumbs from '@/components/ui/Breadcrumbs';
@@ -36,6 +46,7 @@ import {
  useInterchangeDocuments,
 } from '@/hooks/useInterchangeDocuments';
 import { useToast } from '@/hooks/use-toast';
+import { trainSchedulingService } from '@/services/trainScheduling.service';
 import type {
  AutoUnloadExportDjiboutiResult,
  ExportTrain,
@@ -179,6 +190,14 @@ export default function ExportDjiboutiUnloadingQueuePage() {
  const { data: interchangeDocuments = [] } = useInterchangeDocuments({ direction: 'EXPORT' });
  const autoUnload = useAutoUnloadExportAtDjibouti();
  const generateInterchange = useGenerateInterchangeDocument();
+  const qc = useQueryClient();
+  const secureGatePass = useMutation({
+    mutationFn: (scheduleId: string) => trainSchedulingService.grantImportDjiboutiGatepass(scheduleId),
+    onSuccess: () =>
+      qc.invalidateQueries({
+        queryKey: ['warehouse-inventory', 'export-djibouti-arrival-queue'],
+      }),
+  });
  const [openScheduleId, setOpenScheduleId] = useState<string | null>(null);
  const [busyScheduleId, setBusyScheduleId] = useState<string | null>(null);
  const [historyInventoryId, setHistoryInventoryId] = useState<string | null>(null);
@@ -189,6 +208,25 @@ export default function ExportDjiboutiUnloadingQueuePage() {
      .map((doc) => [doc.scheduleId as string, doc]),
  );

+  const secureGate = async (train: ExportTrain) => {
+    setBusyScheduleId(train.scheduleId);
+    try {
+      await secureGatePass.mutateAsync(train.scheduleId);
+      toast({
+        title: 'Gate pass secured',
+        description: `Djibouti Port entry allowed for ${train.trainNumber ?? 'the train'}. You can now auto unload.`,
+      });
+    } catch (error) {
+      toast({
+        variant: 'destructive',
+        title: 'Could not secure gate pass',
+        description: getErrorMessage(error),
+      });
+    } finally {
+      setBusyScheduleId(null);
+    }
+  };
+
  const unloadTrain = async (train: ExportTrain) => {
    setBusyScheduleId(train.scheduleId);
    try {
@@ -346,6 +384,16 @@ export default function ExportDjiboutiUnloadingQueuePage() {
                              >
                                Open
                              </Button>
+                              <Button
+                                size="compact-xs"
+                                variant="light"
+                                color="teal"
+                                leftSection={<ShieldCheck size={14} />}
+                                loading={busyScheduleId === train.scheduleId && secureGatePass.isPending}
+                                onClick={() => secureGate(train)}
+                              >
+                                Secure Gate Pass
+                              </Button>
                              <Button
                                size="compact-xs"
                                color="green"
@@ -356,7 +404,7 @@ export default function ExportDjiboutiUnloadingQueuePage() {
                                    <Truck size={14} />
                                  )
                                }
-                                loading={busyScheduleId === train.scheduleId}
+                                loading={busyScheduleId === train.scheduleId && autoUnload.isPending}
                                onClick={() => unloadTrain(train)}
                              >
                                Auto Unload Export Items
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseInventoryPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseInventoryPage.tsx
@@ -21,6 +21,7 @@ export default function WarehouseInventoryPage() {
  const navigate = useNavigate();
  const [searchParams] = useSearchParams();
  const initialStatus = (searchParams.get('status') as InventoryStatus | null) ?? undefined;
+  const direction = (searchParams.get('direction') as 'IMPORT' | 'EXPORT' | null) ?? undefined;
  const [filter, setFilter] = useState<InventoryFilter>(
    initialStatus ? { status: initialStatus } : {},
  );
@@ -28,8 +29,8 @@ export default function WarehouseInventoryPage() {

  const [debouncedSearch] = useDebouncedValue(search, 300);
  const queryFilter = useMemo<InventoryFilter>(
-    () => ({ ...filter, search: debouncedSearch || undefined }),
-    [filter, debouncedSearch],
+    () => ({ ...filter, direction, search: debouncedSearch || undefined }),
+    [filter, direction, debouncedSearch],
  );

  const warehousesQuery = useWarehouses();
@@ -53,7 +54,13 @@ export default function WarehouseInventoryPage() {
  return (
    <PageContainer>
      <PageHeader
-        title="Warehouse Inventory"
+        title={
+          direction === 'IMPORT'
+            ? 'Import Terminal Inventory'
+            : direction === 'EXPORT'
+              ? 'Export Terminal Inventory'
+              : 'Warehouse Inventory'
+        }
        subtitle="Track received items through the storage, reservation, loading and dispatch lifecycle."
        action={
          <Group gap="xs">
--- a/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseRulesPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/warehouses/WarehouseRulesPage.tsx
@@ -33,7 +33,7 @@ import {
 } from '@/hooks/useWarehouses';
 import { api } from '@/services/api';
 import { FEE_RULE_TYPES, type FeeRuleType } from '@/types/warehouse';
-import { extractErrorMessage } from '@/components/warehouses/options';
+import { extractErrorMessage, lettersOnly } from '@/components/warehouses/options';

 const FREIGHT = [
  { value: 'CONTAINER', label: 'Container' },
@@ -253,7 +253,7 @@ function AllocationRules() {
              required
              value={form.name}
              onChange={(e) => {
-                const value = e.currentTarget.value;
+                const value = lettersOnly(e.currentTarget.value);
                setForm((f) => ({ ...f, name: value }));
              }}
            />
@@ -569,7 +569,7 @@ function FeeRules() {
              required
              value={form.name}
              onChange={(e) => {
-                const value = e.currentTarget.value;
+                const value = lettersOnly(e.currentTarget.value);
                setForm((f) => ({ ...f, name: value }));
              }}
            />
--- a/apps/edr-freight-web/backoffice/src/services/api.ts
+++ b/apps/edr-freight-web/backoffice/src/services/api.ts
@@ -49,6 +49,8 @@ import type {
  CreateTrainSchedulePayload,
  EligibleContainerBookingsResponse,
  FreightType,
+  ImportLoadingBookingsResponse,
+  LoadingStatus,
  LocomotiveRecord,
  PinWagonsPayload,
  RecordCheckpointPayload,
@@ -370,6 +372,25 @@ export const api = {
        QUERY_KEYS.TRAIN_SCHEDULING.compositionRemovals(scheduleId),
    ),

+    importLoadingBookings: endpoint<{ id: string }, ImportLoadingBookingsResponse>(
+      "train-scheduling",
+      "import-loading-bookings",
+      ({ id }) => trainSchedulingService.getImportLoadingBookings(id),
+      ({ id }) => QUERY_KEYS.TRAIN_SCHEDULING.importLoadingBookings(id),
+    ),
+
+    updateImportLoadingStatus: endpoint<
+      { id: string; bookingIds: string[]; loadingStatus: LoadingStatus },
+      ImportLoadingBookingsResponse
+    >(
+      "train-scheduling",
+      "update-import-loading-status",
+      ({ id, bookingIds, loadingStatus }) =>
+        trainSchedulingService.updateImportLoadingStatus(id, { bookingIds, loadingStatus }),
+      undefined,
+      ({ id }) => [QUERY_KEYS.TRAIN_SCHEDULING.importLoadingBookings(id)],
+    ),
+
    // ── Mutations ──────────────────────────────────────────────────────────
    runAllocation: endpoint<
      { scheduleId: string },
--- a/apps/edr-freight-web/backoffice/src/services/drivers.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/drivers.service.ts
@@ -26,6 +26,8 @@ export interface Driver {
  address?: string | null;
  emergencyContact?: string | null;
  notes?: string | null;
+  faydaVerified?: boolean;
+  faydaSub?: string | null;
  totalTrips: number;
  rating: number;
  createdAt: string;
--- a/apps/edr-freight-web/backoffice/src/services/fleet-history.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/fleet-history.service.ts
@@ -0,0 +1,38 @@
+import { api as apiClient } from "../auth/http";
+
+export type FleetEventType =
+  | "DRIVER_REGISTERED"
+  | "VEHICLE_REGISTERED"
+  | "DRIVER_ASSIGNED"
+  | "DRIVER_UNASSIGNED"
+  | "VEHICLE_STATUS_CHANGED"
+  | "VEHICLE_AVAILABILITY_CHANGED"
+  | "MILE_VEHICLE_ASSIGNED"
+  | "MILE_VEHICLE_RELEASED"
+  | "MILE_STATUS_CHANGED";
+
+export interface FleetHistoryEvent {
+  id: string;
+  eventType: FleetEventType;
+  vehicleId?: string | null;
+  driverId?: string | null;
+  firstMileId?: string | null;
+  lastMileId?: string | null;
+  fromValue?: string | null;
+  toValue?: string | null;
+  label?: string | null;
+  metadata?: Record<string, unknown> | null;
+  createdAt: string;
+}
+
+/** Timeline of fleet events for a driver or a vehicle (newest first). */
+export const fleetHistoryService = {
+  driver: (id: string) =>
+    apiClient
+      .get<FleetHistoryEvent[]>(`/drivers/${id}/history`)
+      .then((r) => r.data),
+  vehicle: (id: string) =>
+    apiClient
+      .get<FleetHistoryEvent[]>(`/vehicles/${id}/history`)
+      .then((r) => r.data),
+};
--- a/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/trainScheduling.service.ts
@@ -16,6 +16,8 @@ import type {
  ImportDjiboutiActionPayload,
  ImportDjiboutiLoadList,
  ImportDjiboutiOperation,
+  ImportLoadingBookingsResponse,
+  LoadingStatus,
  LocomotiveRecord,
  PinWagonsPayload,
  RecordCheckpointPayload,
@@ -312,6 +314,26 @@ export const trainSchedulingService = {
    return unwrap(response.data);
  },

+  getImportLoadingBookings: async (
+    scheduleId: string,
+  ): Promise<ImportLoadingBookingsResponse> => {
+    const response = await client.get<ImportLoadingBookingsResponse>(
+      URL_CONSTANTS.TRAIN_SCHEDULING.IMPORT_LOADING_BOOKINGS(scheduleId),
+    );
+    return unwrap(response.data);
+  },
+
+  updateImportLoadingStatus: async (
+    scheduleId: string,
+    payload: { bookingIds: string[]; loadingStatus: LoadingStatus },
+  ): Promise<ImportLoadingBookingsResponse> => {
+    const response = await client.patch<ImportLoadingBookingsResponse>(
+      URL_CONSTANTS.TRAIN_SCHEDULING.IMPORT_LOADING_STATUS(scheduleId),
+      payload,
+    );
+    return unwrap(response.data);
+  },
+
  getImportDjiboutiOperation: async (
    scheduleId: string,
  ): Promise<ImportDjiboutiOperation> => {
--- a/apps/edr-freight-web/backoffice/src/services/verifayda.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/verifayda.service.ts
@@ -0,0 +1,46 @@
+import { api as apiClient } from '../auth/http';
+
+export interface FaydaStartResponse {
+  authorizationUrl: string;
+}
+
+export interface FaydaCompleteResult {
+  purpose: 'LOGIN' | 'VERIFY';
+  verified: boolean;
+  fullName?: string;
+  email?: string;
+  phoneNumber?: string;
+  /** ISO yyyy-MM-dd */
+  birthdate?: string;
+  gender?: string;
+  iamUserId?: string;
+  userDataSaved?: boolean;
+}
+
+/** Message posted from the /callback popup back to the opener window. */
+export interface FaydaCallbackMessage {
+  type: 'fayda-callback';
+  code?: string;
+  state?: string;
+  error?: string;
+  errorDescription?: string;
+}
+
+export const verifaydaService = {
+  /** Returns the eSignet authorize URL to open in a popup. */
+  start: () =>
+    apiClient
+      .post<FaydaStartResponse>('/fayda/verification/start', {
+        purpose: 'VERIFY',
+        platform: 'WEB',
+      })
+      .then((r) => r.data),
+
+  /** Exchange the callback code+state for the verified identity attributes. */
+  complete: (code: string, state: string) =>
+    apiClient
+      .get<FaydaCompleteResult>(
+        `/fayda/verification/complete?code=${encodeURIComponent(code)}&state=${encodeURIComponent(state)}`,
+      )
+      .then((r) => r.data),
+};
--- a/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
+++ b/apps/edr-freight-web/backoffice/src/types/trainScheduling.ts
@@ -479,6 +479,21 @@ export interface ImportDjiboutiDocumentRecord {
  notes?: string | null;
 }

+export type LoadingStatus = "LOADED" | "UNLOADED";
+
+export interface ImportLoadingBooking {
+  id: string;
+  reference: string | null;
+  customer: string | null;
+  weightTons: number;
+  loadingStatus: LoadingStatus;
+}
+
+export interface ImportLoadingBookingsResponse {
+  count: number;
+  items: ImportLoadingBooking[];
+}
+
 export interface ImportDjiboutiOperation {
  trainScheduleId: string;
  trainNumber: string | null;
--- a/apps/edr-freight-web/backoffice/src/types/warehouse.ts
+++ b/apps/edr-freight-web/backoffice/src/types/warehouse.ts
@@ -1013,6 +1013,7 @@ export interface InventoryFilter {
  containerId?: string;
  goodsId?: string;
  status?: InventoryStatus;
+  direction?: 'IMPORT' | 'EXPORT';
  search?: string;
  dateFrom?: string;
  dateTo?: string;
--- a/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
+++ b/apps/edr-freight-web/portal/src/components/onboarding/OnboardingWizardDialog.tsx
@@ -10,10 +10,8 @@ import {
 } from "@mantine/core";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import {
-  ArrowLeft,
  ArrowRight,
  Building2,
-  CheckCircle2,
  Clock,
  FileText,
  Globe2,
@@ -42,44 +40,29 @@ import type { UpdateProfilePayload } from "@/types/profile";
 import { extractApiError } from "@/utils/result";

 /** Form steps rendered by CompanyProfileForm. */
-type FormStep =
-  | "company"
-  | "personnel"
-  | "contact"
-  | "verify"
-  | "poa"
-  | "documents"
-  | "additional";
+type FormStep = "company" | "personnel" | "contact" | "poa" | "documents";
 const FORM_STEPS: FormStep[] = [
  "company",
  "personnel",
  "contact",
-  "verify",
  "poa",
  "documents",
-  "additional",
 ];

 /** The full onboarding journey: the two pre-form phases + the form steps. */
-type WizardStep = "nationality" | "role" | FormStep;
-const WIZARD_STEPS: WizardStep[] = ["nationality", "role", ...FORM_STEPS];
+type WizardStep = "nationality-role" | FormStep;
+const WIZARD_STEPS: WizardStep[] = ["nationality-role", ...FORM_STEPS];

 /** Icon + title + description shown in the global dialog header per step. */
 const STEP_META: Record<
  WizardStep,
  { icon: ReactNode; title: string; description: string }
 > = {
-  nationality: {
+  "nationality-role": {
    icon: <Globe2 size={20} />,
-    title: "Where is your company registered?",
+    title: "Tell us about your company",
    description: "This determines the documents we'll ask you to provide.",
  },
-  role: {
-    icon: <Building2 size={20} />,
-    title: "What does your company do?",
-    description:
-      "Pick any combination of Importer, Exporter and Freight Forwarder — each is set up with its own business license.",
-  },
  company: {
    icon: <Building2 size={20} />,
    title: "Company Information",
@@ -95,11 +78,6 @@ const STEP_META: Record<
    title: "Contact Person",
    description: "Who should we reach out to about this account?",
  },
-  verify: {
-    icon: <ShieldCheck size={20} />,
-    title: "Verify Contact Person",
-    description: "Confirm the contact phone with a one-time SMS code.",
-  },
  poa: {
    icon: <FileText size={20} />,
    title: "Power of Attorney",
@@ -110,11 +88,6 @@ const STEP_META: Record<
    title: "Upload Documents",
    description: "Provide the required company documents.",
  },
-  additional: {
-    icon: <CheckCircle2 size={20} />,
-    title: "Business License",
-    description: "Upload a business license for each operational profile.",
-  },
 };

 interface OnboardingWizardDialogProps {
@@ -172,12 +145,8 @@ export default function OnboardingWizardDialog({

  // Phases: nationality → role → form. If a draft already exists, resume
  // straight into the form with nationality + roles pre-selected.
-  const [phase, setPhase] = useState<"nationality" | "role" | "form">(
-    companyAlreadyStarted
-      ? hasOperationalProfiles
-        ? "form"
-        : "role"
-      : "nationality",
+  const [phase, setPhase] = useState<"nationality-role" | "form">(
+    companyAlreadyStarted ? "form" : "nationality-role",
  );
  const [nationality, setNationality] = useState<CompanyNationality | null>(
    savedNationality,
@@ -302,16 +271,12 @@ export default function OnboardingWizardDialog({
    setNationality(savedNationality);
    // 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" : "role");
+    setPhase(hasOperationalProfiles ? "form" : "nationality-role");
    const idx = FORM_STEPS.indexOf(resumeFormStep);
    if (idx > furthestIdxRef.current) furthestIdxRef.current = idx;
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [companyAlreadyStarted, resumeFormStep]);

-  const handleNationalityContinue = useCallback(() => {
-    if (nationality) setPhase("role");
-  }, [nationality]);
-
  const handleRolesContinue = useCallback(() => {
    setStartError(null);
    startMutation.mutate({
@@ -394,6 +359,7 @@ export default function OnboardingWizardDialog({
  // The active step across the whole journey, driving the header + progress pill.
  const activeStep: WizardStep = phase === "form" ? formStep : phase;
  const stepMeta = STEP_META[activeStep];
+  console.log({ stepMeta, activeStep, STEP_META });
  const activeIdx = WIZARD_STEPS.indexOf(activeStep);

  // Closing from the congratulations panel also clears the completed flag so a
@@ -425,7 +391,7 @@ export default function OnboardingWizardDialog({
  );
  const effectiveResumeStep: FormStep =
    requiredDocsMissing &&
-    FORM_STEPS.indexOf(resumeFormStep) > FORM_STEPS.indexOf("documents")
+      FORM_STEPS.indexOf(resumeFormStep) > FORM_STEPS.indexOf("documents")
      ? "documents"
      : resumeFormStep;

@@ -497,26 +463,19 @@ export default function OnboardingWizardDialog({
        <OnboardingCompletePanel onClose={handleClose} />
      ) : (
        <Stack gap="xl">
-          {phase === "nationality" ? (
+          {phase === "nationality-role" ? (
            <Stack gap="lg">
+              <Text fw={600} size="lg" c="edr-text">
+                Where is your company registered?
+              </Text>
              <NationalitySelect
                value={nationality}
                onChange={setNationality}
                embedded
              />
-              <Group justify="flex-end" pt="xs">
-                <Button
-                  color="edr-green"
-                  onClick={handleNationalityContinue}
-                  disabled={!nationality}
-                  rightSection={<ArrowRight size={16} />}
-                >
-                  Continue
-                </Button>
-              </Group>
-            </Stack>
-          ) : phase === "role" ? (
-            <Stack gap="lg">
+              <Text fw={600} size="lg" c="edr-text">
+                What does your company do?(multiple)
+              </Text>
              <OnboardingRoleSelect
                value={roles}
                onChange={setRoles}
@@ -527,14 +486,7 @@ export default function OnboardingWizardDialog({
                  {startError}
                </Text>
              )}
-              <Group justify="space-between" pt="xs">
-                <Button
-                  variant="default"
-                  leftSection={<ArrowLeft size={16} />}
-                  onClick={() => setPhase("nationality")}
-                >
-                  Back
-                </Button>
+              <Group justify="flex-end" pt="xs">
                <Button
                  color="edr-green"
                  onClick={handleRolesContinue}
@@ -616,7 +568,7 @@ function OnboardingCompletePanel({ onClose }: { onClose: () => void }) {
      </Stack>

      <Button color="edr-green" size="md" onClick={onClose} mt="xs">
-        Go to my dashboard
+        Continue to Dashboard
      </Button>
    </Stack>
  );
--- a/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/CompanyProfileForm.tsx
@@ -4,7 +4,6 @@ import {
  Divider,
  Group,
  Loader,
-  PinInput,
  SimpleGrid,
  Stack,
  Text,
@@ -12,15 +11,7 @@ import {
 } from "@mantine/core";
 import { zodResolver } from "@hookform/resolvers/zod";
 import { useQuery } from "@tanstack/react-query";
-import {
-  AlertCircle,
-  ArrowLeft,
-  ArrowRight,
-  CheckCircle2,
-  RotateCw,
-  Smartphone,
-  UserCheck,
-} from "lucide-react";
+import { AlertCircle, ArrowLeft, ArrowRight, UserCheck } from "lucide-react";
 import { useEffect, useRef, useState } from "react";
 import { useForm } from "react-hook-form";

@@ -35,7 +26,6 @@ import RoleLicenseStep, {
  type RoleLicenseProfile,
 } from "@/components/onboarding/RoleLicenseStep";
 import ETradeInfo from "@/components/onboarding/ETradeInfo";
-import { extractApiError } from "@/utils/result";
 import {
  type CompanyStep,
  type FormData,
@@ -44,8 +34,6 @@ import {
 } from "./companyProfileForm/schema";
 import {
  buildPayload,
-  maskPhone,
-  samePhone,
  stepPayload,
  toFormValues,
 } from "./companyProfileForm/helpers";
@@ -295,6 +283,7 @@ export default function CompanyProfileForm({
  const useOwnerAsManager = () => {
    if (!etradeOwner) return;
    setValue("generalManagerName", etradeOwner.name);
+    setValue("generalManagerEmail", user.email);
    setValue("generalManagerPhone", etradeOwner.phone ?? "", {
      shouldValidate: true,
    });
@@ -350,85 +339,6 @@ export default function CompanyProfileForm({
    }
  };

-  // --- Contact-phone SMS OTP verification -----------------------------------
-  // The phone we verify is the contact-person phone, normalised to E.164 so it
-  // matches what the backend persists as `contactVerifiedPhone`.
-  const contactPhoneE164 = toEthiopianE164(watch("contactPersonPhone") ?? "");
-  // Source of truth for "already verified" comes from the onboarding/profile
-  // info (rehydrate) — so a refresh resumes the verify step's "done" state.
-  const [verifiedPhone, setVerifiedPhone] = useState<string | null>(
-    rehydrate?.contactVerifiedPhone ?? null,
-  );
-  useEffect(() => {
-    if (rehydrate?.contactVerifiedPhone) {
-      setVerifiedPhone(rehydrate.contactVerifiedPhone);
-    }
-  }, [rehydrate?.contactVerifiedPhone]);
-  const phoneVerified = samePhone(verifiedPhone, contactPhoneE164);
-
-  const [otpSent, setOtpSent] = useState(false);
-  const [otpCode, setOtpCode] = useState("");
-  const [sendingOtp, setSendingOtp] = useState(false);
-  const [verifyingOtp, setVerifyingOtp] = useState(false);
-  const [otpError, setOtpError] = useState<string | null>(null);
-  const [resendIn, setResendIn] = useState(0);
-
-  // Resend cooldown countdown (no Date.now needed — pure setTimeout ticks).
-  useEffect(() => {
-    if (resendIn <= 0) return;
-    const t = setTimeout(() => setResendIn((s) => s - 1), 1000);
-    return () => clearTimeout(t);
-  }, [resendIn]);
-
-  // A changed contact phone invalidates any in-flight code entry (the previous
-  // code was for a different number). Verified state is handled separately via
-  // the phone comparison, so this only resets the send/enter UI.
-  useEffect(() => {
-    setOtpSent(false);
-    setOtpCode("");
-    setOtpError(null);
-  }, [contactPhoneE164]);
-
-  const sendContactOtp = async () => {
-    setOtpError(null);
-    if (!contactPhoneE164) {
-      setOtpError("Enter a valid contact phone number first.");
-      return;
-    }
-    setSendingOtp(true);
-    try {
-      await api.auth.sendOTP.call({ phone: contactPhoneE164 });
-      setOtpSent(true);
-      setOtpCode("");
-      setResendIn(60);
-    } catch (err) {
-      setOtpError(extractApiError(err).message);
-    } finally {
-      setSendingOtp(false);
-    }
-  };
-
-  const verifyContactOtp = async () => {
-    setOtpError(null);
-    if (otpCode.length !== 6) {
-      setOtpError("Enter the 6-digit code we sent you.");
-      return;
-    }
-    setVerifyingOtp(true);
-    try {
-      await api.auth.verifyOTP.call({ phone: contactPhoneE164, otp: otpCode });
-      setVerifiedPhone(contactPhoneE164);
-      setOtpSent(false);
-      // Persist the verified phone so the step resumes as "done" after a refresh
-      // (best-effort — the OTP itself already succeeded server-side).
-      onSaveStep?.({ contactVerifiedPhone: contactPhoneE164 }).catch(() => { });
-    } catch (err) {
-      setOtpError(extractApiError(err).message);
-    } finally {
-      setVerifyingOtp(false);
-    }
-  };
-
  const hasDocuments = Boolean(uploadSetting?.fields?.length);

  // The registration/license details come straight from the eTrade lookup and
@@ -451,10 +361,8 @@ export default function CompanyProfileForm({
    "company",
    "personnel",
    "contact",
-    "verify",
    "poa",
    "documents",
-    "additional",
  ];
  const currentIdx = stepOrder.indexOf(step);

@@ -485,30 +393,6 @@ export default function CompanyProfileForm({

  const nextStep = async () => {
    userNavigatedRef.current = true;
-    if (step === "additional") {
-      if (!licenseComplete) {
-        setSaveError(
-          "Please upload a business license for each of your operational profiles.",
-        );
-        return;
-      }
-      handleSubmit((data) => onSubmit(buildPayload(data, user)))();
-      return;
-    }
-    // Contact-phone verification gates advancing past the verify step. The
-    // verified phone is already persisted (on verify success), so there's
-    // nothing extra to save here.
-    if (step === "verify") {
-      if (!phoneVerified) {
-        setSaveError(
-          "Please verify the contact person's phone number to continue.",
-        );
-        return;
-      }
-      setSaveError(null);
-      setStep(stepOrder[currentIdx + 1]);
-      return;
-    }
    // The documents step auto-uploads whatever the user selected as they
    // continue (partial uploads are allowed — required-doc completeness is
    // re-checked on resume). A failed upload holds them on the step.
@@ -525,8 +409,15 @@ export default function CompanyProfileForm({
          setSaving(false);
        }
      }
+
+      if (!licenseComplete) {
+        setSaveError(
+          "Please upload a business license for each of your operational profiles.",
+        );
+        return;
+      }
      setSaveError(null);
-      setStep(stepOrder[currentIdx + 1]);
+      handleSubmit((data) => onSubmit(buildPayload(data, user)))();
      return;
    }
    // Field steps validate + save before advancing.
@@ -551,10 +442,7 @@ export default function CompanyProfileForm({
      <form onSubmit={(e) => e.preventDefault()}>
        <Stack gap="md">
          {step === "company" && (
-            <>
-              <Text fw={600} size="sm" c="edr-text">
-                Enter your TIN to auto-fill company information from eTrade
-              </Text>
+            <Stack gap="sm">
              <ETradeInfo
                tin={watch("tinNumber")}
                register={register("tinNumber")}
@@ -693,7 +581,7 @@ export default function CompanyProfileForm({
                  {...register("houseNo")}
                />
              </SimpleGrid>
-            </>
+            </Stack>
          )}

          {step === "personnel" && (
@@ -783,107 +671,6 @@ export default function CompanyProfileForm({
            </>
          )}

-          {step === "verify" && (
-            <Stack gap="md">
-              <Text size="sm" c="edr-muted">
-                We'll text a one-time code to the contact person's phone to
-                confirm it's reachable. This is required before you continue.
-              </Text>
-
-              {!contactPhoneE164 ? (
-                <Alert
-                  color="yellow"
-                  variant="light"
-                  icon={<AlertCircle size={18} />}
-                >
-                  Add a valid contact phone number on the previous step first.
-                </Alert>
-              ) : phoneVerified ? (
-                <Alert
-                  color="edr-green"
-                  variant="light"
-                  icon={<CheckCircle2 size={18} />}
-                  title="Phone verified"
-                >
-                  {maskPhone(contactPhoneE164)} has been verified.
-                </Alert>
-              ) : (
-                <Stack gap="sm">
-                  <Group gap="xs" align="center">
-                    <Smartphone
-                      size={16}
-                      className="text-[var(--mantine-color-edr-muted)]"
-                    />
-                    <Text size="sm" c="edr-text">
-                      {maskPhone(contactPhoneE164)}
-                    </Text>
-                  </Group>
-
-                  {!otpSent ? (
-                    <Button
-                      color="edr-green"
-                      variant="light"
-                      onClick={sendContactOtp}
-                      loading={sendingOtp}
-                      leftSection={<Smartphone size={16} />}
-                      style={{ alignSelf: "flex-start" }}
-                    >
-                      Send code via SMS
-                    </Button>
-                  ) : (
-                    <Stack gap="sm">
-                      <PinInput
-                        length={6}
-                        type="number"
-                        oneTimeCode
-                        value={otpCode}
-                        placeholder="0"
-                        styles={{
-                          input: {
-                            textAlign: "center",
-                          },
-                        }}
-                        onChange={setOtpCode}
-                      />
-                      <Group gap="sm">
-                        <Button
-                          color="edr-green"
-                          onClick={verifyContactOtp}
-                          loading={verifyingOtp}
-                          disabled={otpCode.length !== 6}
-                        >
-                          Verify
-                        </Button>
-                        <Button
-                          variant="subtle"
-                          color="edr-green"
-                          onClick={sendContactOtp}
-                          loading={sendingOtp}
-                          disabled={resendIn > 0 || sendingOtp}
-                          leftSection={<RotateCw size={14} />}
-                        >
-                          {resendIn > 0
-                            ? `Resend in ${resendIn}s`
-                            : "Resend code"}
-                        </Button>
-                      </Group>
-                    </Stack>
-                  )}
-
-                  {otpError && (
-                    <Alert
-                      color="red"
-                      variant="light"
-                      icon={<AlertCircle size={18} />}
-                    >
-                      {otpError}
-                    </Alert>
-                  )}
-                </Stack>
-              )}
-            </Stack>
-          )}
-
          {step === "poa" && (
            <>
              <Text size="sm" c="edr-muted">
@@ -954,15 +741,13 @@ export default function CompanyProfileForm({
                  onChange={setDocumentFiles}
                />
              )}
-            </>
-          )}

-          {step === "additional" && (
-            <RoleLicenseStep
-              profiles={roleProfiles ?? []}
-              value={licenseFiles ?? {}}
-              onChange={onLicenseChange ?? (() => { })}
-            />
+              <RoleLicenseStep
+                profiles={roleProfiles ?? []}
+                value={licenseFiles ?? {}}
+                onChange={onLicenseChange ?? (() => { })}
+              />
+            </>
          )}

          {saveError && (
@@ -970,11 +755,7 @@ export default function CompanyProfileForm({
              color="red"
              variant="light"
              icon={<AlertCircle size={18} />}
-              title={
-                step === "additional"
-                  ? "Business license required"
-                  : "Couldn't save this step"
-              }
+              title={"Couldn't save this step"}
            >
              {saveError}
            </Alert>
@@ -998,7 +779,7 @@ export default function CompanyProfileForm({
                onClick={prevStep}
                leftSection={<ArrowLeft size={16} />}
              >
-                {step === "additional" ? "Back to Documents" : "Back"}
+                Back
              </Button>
            ) : (
              <span />
@@ -1009,17 +790,14 @@ export default function CompanyProfileForm({
              disabled={
                isPending ||
                saving ||
-                (step === "documents" && !hasDocuments && loadingDocuments) ||
-                (step === "verify" && !phoneVerified)
+                (step === "documents" && !hasDocuments && loadingDocuments)
              }
              loading={isPending || saving}
              rightSection={
-                !isPending && !saving && step !== "additional" ? (
-                  <ArrowRight size={16} />
-                ) : undefined
+                !isPending && !saving ? <ArrowRight size={16} /> : undefined
              }
            >
-              {step === "additional" ? "Submit for review" : "Continue"}
+              {step === "documents" ? "Submit for review" : "Continue"}
            </Button>
          </Group>
        </Stack>
--- a/apps/edr-freight-web/portal/src/pages/accounts/SignupPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/accounts/SignupPage.tsx
@@ -1,18 +1,38 @@
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { zodResolver } from "@hookform/resolvers/zod";
-import { ArrowRight, Check, Eye, EyeOff, X } from "lucide-react";
-import { Controller, useForm } from "react-hook-form";
+import {
+  Alert,
+  Button,
+  PasswordInput,
+  PinInput,
+  SegmentedControl,
+  SimpleGrid,
+  Stack,
+  Text,
+  TextInput,
+} from "@mantine/core";
+import {
+  AlertCircle,
+  ArrowLeft,
+  ArrowRight,
+  Check,
+  Mail,
+  RotateCw,
+  ShieldCheck,
+  Smartphone,
+  X,
+} from "lucide-react";
+import { useForm } from "react-hook-form";
 import { useNavigate } from "react-router-dom";
 import { z } from "zod";
-import RPNInput from "react-phone-number-input";
-import "react-phone-number-input/style.css";

 import { userType } from "@/enums/userType";
 import useAuth from "@/hooks/useAuth";
 import type { SignupPayload } from "@/types/auth";
-import AuthShell, { fieldClass, primaryButtonClass } from "@/components/auth/AuthShell";
-import { isValidPhone } from "@/components/PhoneField";
-import "@/components/phone-field.css";
+import AuthShell from "@/components/auth/AuthShell";
+import { ControlledPhoneField, isValidPhone } from "@/components/PhoneField";
+import { api } from "@/services/api";
+import { extractApiError } from "@/utils/result";

 const EDR_LOGO = "/assets/edr-logo.png";

@@ -50,16 +70,46 @@ const userSchema = z

 type FormData = z.infer<typeof userSchema>;

-const errorText = (msg?: string) =>
-  msg ? <p className="mt-1 text-xs text-red-600">{msg}</p> : null;
+/** Mask all but the first 7 chars of an E.164 phone for display. */
+const maskPhone = (p: string) =>
+  p.length > 4 ? `${p.slice(0, 7)}${"*".repeat(Math.max(0, p.length - 7))}` : p;
+
+/** Mask the local part of an email for display (j***e@example.com). */
+const maskEmail = (email: string) => {
+  const [local, domain] = email.split("@");
+  if (!local || !domain) return email;
+  if (local.length <= 2) return `${local[0] ?? ""}***@${domain}`;
+  return `${local[0]}***${local[local.length - 1]}@${domain}`;
+};
+
+type OtpChannel = "phone" | "email";

 export default function SignupPage() {
  const navigate = useNavigate();
  const { signup } = useAuth();
  const [error, setError] = useState<string | null>(null);
-  const [loading, setLoading] = useState(false);
-  const [showPassword, setShowPassword] = useState(false);
-  const [showConfirm, setShowConfirm] = useState(false);
+
+  // Two-stage signup: fill the form, then a mandatory SMS OTP challenge on the
+  // phone number before the account is actually created. The account is only
+  // created after the code is verified — the OTP is a hard requirement.
+  const [stage, setStage] = useState<"form" | "otp">("form");
+  const [pendingData, setPendingData] = useState<FormData | null>(null);
+  // Which contact method the code was sent to — chosen on the form, locked in
+  // once the challenge is sent.
+  const [channel, setChannel] = useState<OtpChannel>("phone");
+  const [otpChannel, setOtpChannel] = useState<OtpChannel>("phone");
+  const [sending, setSending] = useState(false);
+  const [verifying, setVerifying] = useState(false);
+  const [otpCode, setOtpCode] = useState("");
+  const [otpError, setOtpError] = useState<string | null>(null);
+  const [resendIn, setResendIn] = useState(0);
+
+  // Resend cooldown countdown (pure setTimeout ticks — no Date.now needed).
+  useEffect(() => {
+    if (resendIn <= 0) return;
+    const t = setTimeout(() => setResendIn((s) => s - 1), 1000);
+    return () => clearTimeout(t);
+  }, [resendIn]);

  const {
    register,
@@ -80,226 +130,329 @@ export default function SignupPage() {
    },
  });

-  const onSubmit = async (data: FormData) => {
+  const passwordValue = watch("password") ?? "";
+
+  // Step 1 — form is valid: send a fresh code to the chosen channel, then
+  // move to the OTP challenge.
+  const requestOtp = async (data: FormData) => {
    setError(null);
-    setLoading(true);
+    setSending(true);
    try {
+      await api.auth.sendOTP.call(
+        channel === "email" ? { email: data.email } : { phone: data.phone },
+      );
+      setPendingData(data);
+      setOtpChannel(channel);
+      setOtpCode("");
+      setOtpError(null);
+      setResendIn(60);
+      setStage("otp");
+    } catch (err) {
+      setError(extractApiError(err).message);
+    } finally {
+      setSending(false);
+    }
+  };
+
+  const resendOtp = async () => {
+    if (!pendingData) return;
+    setOtpError(null);
+    setSending(true);
+    try {
+      await api.auth.sendOTP.call(
+        otpChannel === "email"
+          ? { email: pendingData.email }
+          : { phone: pendingData.phone },
+      );
+      setOtpCode("");
+      setResendIn(60);
+    } catch (err) {
+      setOtpError(extractApiError(err).message);
+    } finally {
+      setSending(false);
+    }
+  };
+
+  // Step 2 — verify the code, then (only on success) create the account.
+  const confirmOtp = async () => {
+    if (!pendingData) return;
+    setOtpError(null);
+    if (otpCode.trim().length !== 6) {
+      setOtpError("Enter the 6-digit code we sent you.");
+      return;
+    }
+    setVerifying(true);
+    try {
+      await api.auth.verifyOTP.call({
+        ...(otpChannel === "email"
+          ? { email: pendingData.email }
+          : { phone: pendingData.phone }),
+        otp: otpCode.trim(),
+      });
      const payload: SignupPayload = {
-        email: data.email,
-        username: data.email,
+        email: pendingData.email,
+        username: pendingData.email,
        // Already a canonical E.164 string from the phone field (e.g. +251912345678).
-        phoneNumber: data.phone,
-        userType: data.userType,
+        phoneNumber: pendingData.phone,
+        userType: pendingData.userType,
        name: {
-          en: `${data.firstName.en} ${data.lastName.en}`,
-          am: `${data.firstName.en} ${data.lastName.en}`,
+          en: `${pendingData.firstName.en} ${pendingData.lastName.en}`,
+          am: `${pendingData.firstName.en} ${pendingData.lastName.en}`,
        },
-        password: data.password,
-        confirmPassword: data.confirmPassword,
+        password: pendingData.password,
+        confirmPassword: pendingData.confirmPassword,
      };
      const result = await signup(payload);
      if (result.success) {
        navigate("/portal");
      } else {
-        setError(result.error.message);
+        setOtpError(result.error.message);
      }
-    } catch {
-      setError("An unexpected error occurred");
+    } catch (err) {
+      setOtpError(extractApiError(err).message);
    } finally {
-      setLoading(false);
+      setVerifying(false);
    }
  };

-  const passwordValue = watch("password") ?? "";
-
  return (
    <AuthShell
      tagline="Smart Freight Operations"
      taglineBody="Join EDR Freight to manage shipments, track consignments, and streamline logistics workflows across Ethiopia and Djibouti."
    >
-      <form className="flex w-full flex-col" onSubmit={handleSubmit(onSubmit)}>
+      <div className="flex w-full flex-col">
        <div className="mb-4 flex justify-center sm:mb-6">
          <img src={EDR_LOGO} alt="EDR Freight" className="h-9 w-auto sm:h-11" />
        </div>

-        <div className="mb-4 space-y-1.5 text-center sm:mb-5">
-          <h1 className="text-xl font-bold tracking-tight text-gray-900 sm:text-2xl">
-            Create account
-          </h1>
-          <p className="text-sm leading-relaxed text-gray-500">
-            Register to access EDR Freight services.
-          </p>
-        </div>
-
-        <div className="flex w-full flex-col gap-4">
-          <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
-            <div className="space-y-1.5">
-              <label className="text-sm font-medium text-gray-800">
-                First name <span className="text-red-500">*</span>
-              </label>
-              <input
-                placeholder="John"
-                disabled={loading}
-                className={fieldClass}
-                {...register("firstName.en")}
-              />
-              {errorText(errors.firstName?.en?.message)}
+        {stage === "form" ? (
+          <form onSubmit={handleSubmit(requestOtp)} className="flex w-full flex-col">
+            <div className="mb-4 space-y-1.5 text-center sm:mb-5">
+              <h1 className="text-xl font-bold tracking-tight text-gray-900 sm:text-2xl">
+                Create account
+              </h1>
+              <p className="text-sm leading-relaxed text-gray-500">
+                Register to access EDR Freight services.
+              </p>
            </div>
-            <div className="space-y-1.5">
-              <label className="text-sm font-medium text-gray-800">
-                Last name <span className="text-red-500">*</span>
-              </label>
-              <input
-                placeholder="Doe"
-                disabled={loading}
-                className={fieldClass}
-                {...register("lastName.en")}
+
+            <Stack gap="md">
+              <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+                <TextInput
+                  label="First name"
+                  placeholder="John"
+                  required
+                  disabled={sending}
+                  error={errors.firstName?.en?.message}
+                  {...register("firstName.en")}
+                />
+                <TextInput
+                  label="Last name"
+                  placeholder="Doe"
+                  required
+                  disabled={sending}
+                  error={errors.lastName?.en?.message}
+                  {...register("lastName.en")}
+                />
+              </SimpleGrid>
+
+              <TextInput
+                label="Email"
+                type="email"
+                placeholder="john@example.com"
+                required
+                disabled={sending}
+                error={errors.email?.message}
+                {...register("email")}
              />
-              {errorText(errors.lastName?.en?.message)}
-            </div>
-          </div>

-          <div className="space-y-1.5">
-            <label className="text-sm font-medium text-gray-800">
-              Email <span className="text-red-500">*</span>
-            </label>
-            <input
-              type="email"
-              placeholder="john@example.com"
-              disabled={loading}
-              className={fieldClass}
-              {...register("email")}
-            />
-            {errorText(errors.email?.message)}
-          </div>
-
-          <div className="space-y-1.5">
-            <label htmlFor="signup-phone" className="text-sm font-medium text-gray-800">
-              Phone <span className="text-red-500">*</span>
-            </label>
-            <Controller
-              control={control}
-              name="phone"
-              render={({ field }) => (
-                <div
-                  className={`edr-phone-wrapper${
-                    errors.phone ? " edr-phone-wrapper--error" : ""
-                  }`}
-                >
-                  <RPNInput
-                    international
-                    defaultCountry="ET"
-                    countryCallingCodeEditable={false}
-                    addInternationalOption
-                    id="signup-phone"
-                    placeholder="912 345 678"
-                    disabled={loading}
-                    value={field.value || undefined}
-                    onChange={(v) => field.onChange(v ?? "")}
-                    onBlur={field.onBlur}
-                  />
-                </div>
-              )}
-            />
-            {errorText(errors.phone?.message)}
-          </div>
-
-          <div className="space-y-1.5">
-            <label className="text-sm font-medium text-gray-800">
-              Password <span className="text-red-500">*</span>
-            </label>
-            <div className="relative">
-              <input
-                type={showPassword ? "text" : "password"}
-                placeholder="Create a strong password"
-                disabled={loading}
-                className={`${fieldClass} pr-11`}
-                {...register("password")}
+              <ControlledPhoneField
+                control={control}
+                name="phone"
+                label="Phone"
+                required
+                disabled={sending}
              />
-              <button
-                type="button"
-                onClick={() => setShowPassword((current) => !current)}
-                className="absolute right-3 top-1/2 -translate-y-1/2 text-gray-400 transition-colors hover:text-gray-600"
-                aria-label={showPassword ? "Hide password" : "Show password"}
-              >
-                {showPassword ? <EyeOff className="h-5 w-5" /> : <Eye className="h-5 w-5" />}
-              </button>
-            </div>
-            {errorText(errors.password?.message)}
-            {passwordValue.length > 0 ? (
-              <div className="mt-2 space-y-1">
-                {passwordRequirements.map((req) => {
-                  const met = req.test(passwordValue);
-                  return (
-                    <div key={req.label} className="flex items-center gap-2">
-                      <span
-                        className={`flex h-4 w-4 shrink-0 items-center justify-center rounded-full ${
-                          met ? "bg-primary text-primary-foreground" : "bg-gray-200 text-gray-500"
-                        }`}
-                      >
-                        {met ? <Check className="h-2.5 w-2.5" /> : <X className="h-2.5 w-2.5" />}
-                      </span>
-                      <span className={`text-xs ${met ? "text-primary" : "text-gray-500"}`}>
-                        {req.label}
-                      </span>
-                    </div>
-                  );
-                })}
+
+              <div className="space-y-1.5">
+                <Text size="sm" fw={500} c="edr-text">
+                  Send verification code via
+                </Text>
+                <SegmentedControl
+                  fullWidth
+                  disabled={sending}
+                  value={channel}
+                  onChange={(v) => setChannel(v as OtpChannel)}
+                  data={[
+                    {
+                      value: "phone",
+                      label: (
+                        <span className="flex items-center justify-center gap-1.5">
+                          <Smartphone size={14} /> Phone
+                        </span>
+                      ),
+                    },
+                    {
+                      value: "email",
+                      label: (
+                        <span className="flex items-center justify-center gap-1.5">
+                          <Mail size={14} /> Email
+                        </span>
+                      ),
+                    },
+                  ]}
+                />
              </div>
-            ) : null}
-          </div>

-          <div className="space-y-1.5">
-            <label className="text-sm font-medium text-gray-800">
-              Confirm password <span className="text-red-500">*</span>
-            </label>
-            <div className="relative">
-              <input
-                type={showConfirm ? "text" : "password"}
+              <div>
+                <PasswordInput
+                  label="Password"
+                  placeholder="Create a strong password"
+                  required
+                  disabled={sending}
+                  error={errors.password?.message}
+                  {...register("password")}
+                />
+                {passwordValue.length > 0 ? (
+                  <div className="mt-2 space-y-1">
+                    {passwordRequirements.map((req) => {
+                      const met = req.test(passwordValue);
+                      return (
+                        <div key={req.label} className="flex items-center gap-2">
+                          <span
+                            className={`flex h-4 w-4 shrink-0 items-center justify-center rounded-full ${
+                              met ? "bg-primary text-primary-foreground" : "bg-gray-200 text-gray-500"
+                            }`}
+                          >
+                            {met ? <Check className="h-2.5 w-2.5" /> : <X className="h-2.5 w-2.5" />}
+                          </span>
+                          <span className={`text-xs ${met ? "text-primary" : "text-gray-500"}`}>
+                            {req.label}
+                          </span>
+                        </div>
+                      );
+                    })}
+                  </div>
+                ) : null}
+              </div>
+
+              <PasswordInput
+                label="Confirm password"
                placeholder="Re-enter your password"
-                disabled={loading}
-                className={`${fieldClass} pr-11`}
+                required
+                disabled={sending}
+                error={errors.confirmPassword?.message}
                {...register("confirmPassword")}
              />
-              <button
-                type="button"
-                onClick={() => setShowConfirm((current) => !current)}
-                className="absolute right-3 top-1/2 -translate-y-1/2 text-gray-400 transition-colors hover:text-gray-600"
-                aria-label={showConfirm ? "Hide password" : "Show password"}
+
+              {error ? (
+                <Alert color="red" variant="light" icon={<AlertCircle size={18} />}>
+                  {error}
+                </Alert>
+              ) : null}
+
+              <Button
+                type="submit"
+                color="edr-green"
+                fullWidth
+                loading={sending}
+                rightSection={!sending ? <ArrowRight size={16} /> : undefined}
              >
-                {showConfirm ? <EyeOff className="h-5 w-5" /> : <Eye className="h-5 w-5" />}
-              </button>
+                Continue
+              </Button>
+
+              <p className="text-center text-sm text-gray-500">
+                Already have an account?{" "}
+                <button
+                  type="button"
+                  onClick={() => navigate("/login")}
+                  className="font-semibold text-primary hover:underline"
+                >
+                  Sign In
+                </button>
+              </p>
+            </Stack>
+          </form>
+        ) : (
+          <Stack gap="md">
+            <div className="mb-1 flex justify-center">
+              <span className="flex h-12 w-12 items-center justify-center rounded-full bg-primary/10 text-primary">
+                <ShieldCheck size={22} />
+              </span>
            </div>
-            {errorText(errors.confirmPassword?.message)}
-          </div>
-
-          {error ? (
-            <div className="rounded-lg border border-red-200 bg-red-50 px-3 py-2.5 text-sm text-red-700">
-              {error}
+            <div className="space-y-1.5 text-center">
+              <h1 className="text-xl font-bold tracking-tight text-gray-900 sm:text-2xl">
+                Verify your {otpChannel === "email" ? "email" : "phone"}
+              </h1>
+              <p className="text-sm leading-relaxed text-gray-500">
+                We sent a 6-digit code to{" "}
+                <span className="font-medium text-gray-700">
+                  {otpChannel === "email"
+                    ? maskEmail(pendingData?.email ?? "")
+                    : maskPhone(pendingData?.phone ?? "")}
+                </span>
+                . Enter it to finish creating your account.
+              </p>
            </div>
-          ) : null}

-          <button
-            type="submit"
-            disabled={loading}
-            className={`${primaryButtonClass} flex items-center justify-center gap-2`}
-          >
-            {loading ? "Creating account..." : "Create Account"}
-            {!loading ? <ArrowRight className="h-4 w-4" /> : null}
-          </button>
+            {otpError ? (
+              <Alert color="red" variant="light" icon={<AlertCircle size={18} />}>
+                {otpError}
+              </Alert>
+            ) : null}

-          <p className="text-center text-sm text-gray-500">
-            Already have an account?{" "}
-            <button
-              type="button"
-              onClick={() => navigate("/login")}
-              className="font-semibold text-primary hover:underline"
+            <Stack gap={6} align="center">
+              <Text size="sm" fw={500} c="edr-text">
+                Verification code
+              </Text>
+              <PinInput
+                length={6}
+                type="number"
+                oneTimeCode
+                value={otpCode}
+                placeholder="0"
+                disabled={verifying}
+                styles={{ input: { textAlign: "center" } }}
+                onChange={setOtpCode}
+              />
+            </Stack>
+
+            <Button
+              color="edr-green"
+              fullWidth
+              loading={verifying}
+              disabled={verifying || otpCode.trim().length !== 6}
+              onClick={confirmOtp}
            >
-              Sign In
-            </button>
-          </p>
-        </div>
-      </form>
+              Verify &amp; create account
+            </Button>
+
+            <div className="flex items-center justify-between">
+              <Button
+                variant="subtle"
+                color="gray"
+                leftSection={<ArrowLeft size={14} />}
+                disabled={sending || verifying}
+                onClick={() => {
+                  setStage("form");
+                  setOtpError(null);
+                }}
+              >
+                Back
+              </Button>
+              <Button
+                variant="subtle"
+                color="edr-green"
+                leftSection={<RotateCw size={14} />}
+                disabled={resendIn > 0 || sending || verifying}
+                onClick={resendOtp}
+              >
+                {resendIn > 0 ? `Resend in ${resendIn}s` : "Resend code"}
+              </Button>
+            </div>
+          </Stack>
+        )}
+      </div>
    </AuthShell>
  );
 }
--- a/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts
+++ b/apps/edr-freight-web/portal/src/pages/accounts/companyProfileForm/schema.ts
@@ -6,7 +6,6 @@ export type CompanyStep =
  | "company"
  | "personnel"
  | "contact"
-  | "verify"
  | "poa"
  | "documents"
  | "additional";
@@ -103,7 +102,6 @@ export const stepFields: Record<CompanyStep, (keyof FormData)[]> = {
    "contactPersonEmail",
    "contactPersonPhone",
  ],
-  verify: [],
  poa: [],
  documents: [],
  additional: [],
--- a/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
+++ b/apps/edr-freight-web/portal/src/pages/contracts/ContractViewPage.tsx
@@ -11,17 +11,27 @@ import {
  Loader,
  Modal,
  Paper,
+  PinInput,
  Stack,
  Text,
  TextInput,
 } from "@mantine/core";
-import { ArrowLeft, Download, FileSignature, Printer } from "lucide-react";
+import {
+  ArrowLeft,
+  Download,
+  FileSignature,
+  Printer,
+  RotateCw,
+  ShieldCheck,
+} from "lucide-react";
 import toast from "react-hot-toast";

 import { ContractSignSuccessModal } from "@/components/contracts/ContractSignSuccessModal";
 import { ContractSignaturePad } from "@/components/bookings/ContractSignaturePad";
 import { contractsService } from "@/services/contracts.service";
 import { api } from "@/services/api";
+import useAuth from "@/hooks/useAuth";
+import { extractApiError } from "@/utils/result";

 const CONSENT_TEXT =
  "I have read the entire contract and agree to its terms.";
@@ -34,9 +44,13 @@ export default function ContractViewPage() {
  const { id } = useParams<{ id: string }>();
  const navigate = useNavigate();
  const qc = useQueryClient();
+  const { user } = useAuth();
  const iframeRef = useRef<HTMLIFrameElement>(null);

  const [signOpen, setSignOpen] = useState(false);
+  const [otpOpen, setOtpOpen] = useState(false);
+  const [otpCode, setOtpCode] = useState("");
+  const [otpError, setOtpError] = useState<string | null>(null);
  const [successOpen, setSuccessOpen] = useState(false);
  const [signerName, setSignerName] = useState("");
  const [signatureData, setSignatureData] = useState<string | null>(null);
@@ -44,6 +58,15 @@ export default function ContractViewPage() {
  const [hasScrolledToBottom, setHasScrolledToBottom] = useState(false);
  const [agreedToTerms, setAgreedToTerms] = useState(false);

+  // The signed-in customer's registered phone — where the sudo-mode OTP is sent.
+  const customerPhone = user?.phoneNumber ?? "";
+  const maskedPhone =
+    customerPhone.length > 4
+      ? `${customerPhone.slice(0, 4)}${"*".repeat(
+          Math.max(customerPhone.length - 6, 0),
+        )}${customerPhone.slice(-2)}`
+      : customerPhone;
+
  const { data, isLoading, isError, refetch } = useQuery({
    queryKey: ["contract-view", id],
    queryFn: () => contractsService.getContractView(id!),
@@ -95,6 +118,18 @@ export default function ContractViewPage() {
    };
  }, [checkScrollBottom]);

+  // Send (or resend) the fresh OTP challenge to the customer's phone. On success
+  // we swap the signature modal for the OTP entry modal.
+  const sendOtpMutation = useMutation({
+    mutationFn: () => api.auth.sendOTP.call({ phone: customerPhone }),
+    onSuccess: () => {
+      setSignOpen(false);
+      setOtpError(null);
+      setOtpOpen(true);
+    },
+    onError: () => toast.error("Failed to send verification code"),
+  });
+
  const signMutation = useMutation({
    mutationFn: () =>
      contractsService.signContract(id!, {
@@ -104,16 +139,22 @@ export default function ContractViewPage() {
          : (signatureData as string),
        signerDisplayName: signerName.trim(),
        consentText: CONSENT_TEXT,
+        otp: otpCode.trim(),
+        otpPhone: customerPhone,
      }),
    onSuccess: () => {
-      setSignOpen(false);
+      setOtpOpen(false);
+      setOtpCode("");
      setSuccessOpen(true);
      void refetch();
      void qc.invalidateQueries({
        queryKey: api.contracts.get.queryKey({ id: id! }),
      });
    },
-    onError: () => toast.error("Failed to sign contract"),
+    onError: (err) =>
+      setOtpError(
+        extractApiError(err).message ?? "Failed to verify code and sign",
+      ),
  });

  const openSign = () => {
@@ -128,6 +169,17 @@ export default function ContractViewPage() {
    if (!signerName.trim()) return;
    const image = usingSaved ? savedSignatureImage : signatureData;
    if (!image) return;
+    if (!customerPhone) {
+      toast.error("No phone number on file to verify your signature.");
+      return;
+    }
+    setOtpCode("");
+    sendOtpMutation.mutate();
+  };
+
+  const confirmOtp = () => {
+    if (otpCode.trim().length !== 6) return;
+    setOtpError(null);
    signMutation.mutate();
  };

@@ -315,20 +367,114 @@ export default function ContractViewPage() {
            </Button>
            <Button
              color="edr-green"
-              loading={signMutation.isPending}
+              loading={sendOtpMutation.isPending}
              disabled={
-                signMutation.isPending ||
+                sendOtpMutation.isPending ||
                !signerName.trim() ||
                (!usingSaved && !signatureData)
              }
              onClick={confirmSign}
            >
-              {usingSaved ? "Approve & sign" : "Confirm signature"}
+              Continue to verification
            </Button>
          </Group>
        </Stack>
      </Modal>

+      <Modal
+        opened={otpOpen}
+        onClose={() => setOtpOpen(false)}
+        title="Verify it's you"
+        centered
+        radius="lg"
+      >
+        <Stack gap="md">
+          <Group gap="sm" wrap="nowrap">
+            <Box
+              w={40}
+              h={40}
+              style={{
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                borderRadius: 12,
+                background: "var(--mantine-color-edr-green-0)",
+                flexShrink: 0,
+              }}
+            >
+              <ShieldCheck
+                size={20}
+                color="var(--mantine-color-edr-green-6)"
+              />
+            </Box>
+            <Text size="sm" c="dimmed">
+              For security, enter the 6-digit code we sent by SMS to{" "}
+              <Text span fw={600} c="edr-text">
+                {maskedPhone}
+              </Text>{" "}
+              to confirm and apply your signature.
+            </Text>
+          </Group>
+
+          {otpError && (
+            <Alert color="red" variant="light" radius="md">
+              {otpError}
+            </Alert>
+          )}
+
+          <Stack gap={6}>
+            <Text size="sm" fw={500} c="edr-text">
+              Verification code
+            </Text>
+            <PinInput
+              length={6}
+              type="number"
+              oneTimeCode
+              value={otpCode}
+              placeholder="0"
+              disabled={signMutation.isPending}
+              styles={{ input: { textAlign: "center" } }}
+              onChange={setOtpCode}
+            />
+          </Stack>
+
+          <Group justify="space-between" gap="sm">
+            <Button
+              variant="subtle"
+              color="gray"
+              size="compact-sm"
+              leftSection={<RotateCw size={14} />}
+              loading={sendOtpMutation.isPending}
+              disabled={sendOtpMutation.isPending || signMutation.isPending}
+              onClick={() => {
+                setOtpError(null);
+                sendOtpMutation.mutate();
+              }}
+            >
+              Resend code
+            </Button>
+            <Group gap="sm">
+              <Button
+                variant="default"
+                onClick={() => setOtpOpen(false)}
+                disabled={signMutation.isPending}
+              >
+                Cancel
+              </Button>
+              <Button
+                color="edr-green"
+                leftSection={<FileSignature size={16} />}
+                loading={signMutation.isPending}
+                disabled={signMutation.isPending || otpCode.trim().length !== 6}
+                onClick={confirmOtp}
+              >
+                Verify &amp; sign
+              </Button>
+            </Group>
+          </Group>
+        </Stack>
+      </Modal>
+
      <ContractSignSuccessModal
        opened={successOpen}
        reference={data.reference}
--- a/apps/edr-freight-web/portal/src/services/bookings.service.ts
+++ b/apps/edr-freight-web/portal/src/services/bookings.service.ts
@@ -93,6 +93,10 @@ export interface SignContractPayload {
  signatureImageBase64: string;
  signerDisplayName: string;
  consentText?: string;
+  /** Sudo-mode OTP challenge; required when role=CUSTOMER. */
+  otp?: string;
+  /** Phone the OTP was sent to; required when role=CUSTOMER. */
+  otpPhone?: string;
 }

 export interface ApproveDeliveryResponse {
--- a/apps/edr-freight-web/portal/src/types/auth.ts
+++ b/apps/edr-freight-web/portal/src/types/auth.ts
@@ -33,7 +33,9 @@ export interface SignupResponse {
 }

 export interface OtpPayload {
-  phone: string;
+  /** Exactly one of phone/email — the channel the code is sent through. */
+  phone?: string;
+  email?: string;
  /** Required on verify; omitted on send (the server generates the code). */
  otp?: string;
 }