chore: merge origin/dev into slide-over media branch

Sync with latest dev (CompDoc/completedDate from PR #45) and resolve
conflicts while preserving slide-over detail, workOrderVersion on media
mutations, and the consolidated list page hook.

e2e/vendors/vendor-uplift-workflow.spec.ts

@@ -0,0 +1,356 @@
+import { expect, test, type Route } from "@playwright/test";
+
+const INTERNAL_USER = {
+  token: "uplift-approver-token",
+  expiration: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
+  email: "approver@seahavenind.com",
+  userRoles: "Admin,Tier2Approver",
+  fullname: "Uplift Approver",
+  id: "1",
+};
+
+async function fulfillJson(route: Route, data: unknown, status = 200) {
+  await route.fulfill({
+    status,
+    contentType: "application/json",
+    body: JSON.stringify({ status: status < 400 ? "Success" : "Error", data }),
+  });
+}
+
+test("vendor uploads scanned evidence and submits a dispatch-scoped uplift", async ({ page }) => {
+  let requestBody: Record<string, unknown> | undefined;
+  let uploadPurpose = "";
+  let created = false;
+
+  await page.route("**/api/vendor-portal/**", async (route) => {
+    const request = route.request();
+    const path = new URL(request.url()).pathname;
+
+    if (path.endsWith("/session")) {
+      await fulfillJson(route, { id: 9, companyName: "Gateway Plumbing" });
+      return;
+    }
+    if (path.endsWith("/dispatches/7/documents") && request.method() === "POST") {
+      uploadPurpose = request.postData() ?? "";
+      await fulfillJson(route, {
+        id: 22,
+        originalFileName: "estimate.pdf",
+        scanStatus: "Pending",
+        reviewStatus: "Processing",
+        purpose: "UpliftEvidence",
+      });
+      return;
+    }
+    if (path.endsWith("/dispatches/7/documents/22/status")) {
+      await fulfillJson(route, {
+        id: 22,
+        originalFileName: "estimate.pdf",
+        scanStatus: "Passed",
+        reviewStatus: "Approved",
+        purpose: "UpliftEvidence",
+      });
+      return;
+    }
+    if (path.endsWith("/dispatches/7/uplift-request") && request.method() === "POST") {
+      requestBody = request.postDataJSON();
+      created = true;
+      await fulfillJson(route, {
+        id: 31,
+        status: "Pending",
+        noApprovalRequired: false,
+      });
+      return;
+    }
+    if (path.endsWith("/dispatches/7")) {
+      await fulfillJson(route, {
+        id: 7,
+        dispatchNumber: "DSP-7",
+        poNumber: "PO-7",
+        status: "In Progress",
+        nteAmount: 100,
+        checklist: [],
+        comments: [],
+        signoffs: [],
+        documents: [],
+        upliftRequests: created
+          ? [
+              {
+                id: 31,
+                status: "Pending",
+                currentNTE: 100,
+                requestedNTE: 125,
+                vendorReason: "Replacement compressor",
+                evidenceDocumentId: 22,
+                evidenceFileName: "estimate.pdf",
+                notificationStatus: "Sent",
+              },
+            ]
+          : [],
+      });
+      return;
+    }
+    await fulfillJson(route, []);
+  });
+
+  await page.goto("/v/portal-token/dispatch/7");
+  await expect(page.getByRole("heading", { name: /DSP-7|PO-7/ })).toBeVisible();
+
+  await page.getByLabel("New total NTE").fill("125");
+  await page.getByLabel("Reason").fill("Replacement compressor");
+  await page.getByLabel("Evidence (PDF/JPG/PNG)").setInputFiles({
+    name: "estimate.pdf",
+    mimeType: "application/pdf",
+    buffer: Buffer.from("%PDF-1.4\nmock estimate"),
+  });
+  await page.getByRole("button", { name: "Request uplift" }).click();
+
+  await expect(page.getByText("Pending", { exact: true })).toBeVisible();
+  expect(uploadPurpose).toContain('name="purpose"');
+  expect(uploadPurpose).toContain("UpliftEvidence");
+  expect(requestBody).toMatchObject({
+    requestedNTE: 125,
+    reason: "Replacement compressor",
+    evidenceDocumentId: 22,
+  });
+  expect(requestBody?.requestKey).toMatch(/^[0-9a-f-]{36}$/i);
+});
+
+test("vendor can withdraw a pending uplift from the dispatch", async ({ page }) => {
+  let withdrawnPath = "";
+  let pending = true;
+
+  await page.route("**/api/vendor-portal/**", async (route) => {
+    const request = route.request();
+    const path = new URL(request.url()).pathname;
+    if (path.endsWith("/session")) {
+      await fulfillJson(route, { id: 9, companyName: "Gateway Plumbing" });
+      return;
+    }
+    if (path.endsWith("/dispatches/7/uplift-request/31/withdraw")) {
+      withdrawnPath = path;
+      pending = false;
+      await fulfillJson(route, { id: 31, status: "Withdrawn" });
+      return;
+    }
+    if (path.endsWith("/dispatches/7")) {
+      await fulfillJson(route, {
+        id: 7,
+        dispatchNumber: "DSP-7",
+        status: "In Progress",
+        nteAmount: 100,
+        checklist: [],
+        comments: [],
+        signoffs: [],
+        documents: [],
+        upliftRequests: [
+          {
+            id: 31,
+            status: pending ? "Pending" : "Withdrawn",
+            currentNTE: 100,
+            requestedNTE: 125,
+            vendorReason: "Parts",
+          },
+        ],
+      });
+      return;
+    }
+    await fulfillJson(route, []);
+  });
+
+  page.on("dialog", (dialog) => void dialog.accept());
+  await page.goto("/v/portal-token/dispatch/7");
+  await page.getByRole("button", { name: "Withdraw request" }).click();
+
+  await expect(page.getByText("Withdrawn", { exact: true })).toBeVisible();
+  expect(withdrawnPath).toBe("/api/vendor-portal/dispatches/7/uplift-request/31/withdraw");
+});
+
+test("vendor receives the no-approval result for a request within the current NTE", async ({
+  page,
+}) => {
+  let requestBody: Record<string, unknown> | undefined;
+  await page.route("**/api/vendor-portal/**", async (route) => {
+    const request = route.request();
+    const path = new URL(request.url()).pathname;
+    if (path.endsWith("/session")) {
+      await fulfillJson(route, { id: 9, companyName: "Gateway Plumbing" });
+      return;
+    }
+    if (path.endsWith("/dispatches/7/uplift-request") && request.method() === "POST") {
+      requestBody = request.postDataJSON();
+      await fulfillJson(route, { noApprovalRequired: true, status: "Approved" });
+      return;
+    }
+    if (path.endsWith("/dispatches/7")) {
+      await fulfillJson(route, {
+        id: 7,
+        dispatchNumber: "DSP-7",
+        status: "In Progress",
+        nteAmount: 100,
+        checklist: [],
+        comments: [],
+        signoffs: [],
+        documents: [],
+        upliftRequests: [],
+      });
+      return;
+    }
+    await fulfillJson(route, []);
+  });
+
+  await page.goto("/v/portal-token/dispatch/7");
+  await page.getByLabel("New total NTE").fill("90");
+  await expect(page.getByLabel("Reason")).toHaveCount(0);
+  await page.getByRole("button", { name: "Request uplift" }).click();
+
+  await expect(
+    page.getByText("No approval required — the existing NTE already covers this amount."),
+  ).toBeVisible();
+  expect(requestBody).toMatchObject({ requestedNTE: 90, reason: "" });
+  expect(requestBody).not.toHaveProperty("evidenceDocumentId");
+});
+
+test("vendor revises a changes-requested uplift using its existing evidence", async ({ page }) => {
+  let revisionBody: Record<string, unknown> | undefined;
+  let revised = false;
+  await page.route("**/api/vendor-portal/**", async (route) => {
+    const request = route.request();
+    const path = new URL(request.url()).pathname;
+    if (path.endsWith("/session")) {
+      await fulfillJson(route, { id: 9, companyName: "Gateway Plumbing" });
+      return;
+    }
+    if (path.endsWith("/dispatches/7/uplift-request/31/revise")) {
+      revisionBody = request.postDataJSON();
+      revised = true;
+      await fulfillJson(route, { id: 31, status: "Pending" });
+      return;
+    }
+    if (path.endsWith("/dispatches/7")) {
+      await fulfillJson(route, {
+        id: 7,
+        dispatchNumber: "DSP-7",
+        status: "In Progress",
+        nteAmount: 100,
+        checklist: [],
+        comments: [],
+        signoffs: [],
+        documents: [],
+        upliftRequests: [
+          {
+            id: 31,
+            status: revised ? "Pending" : "ChangesRequested",
+            currentNTE: 100,
+            requestedNTE: 125,
+            vendorReason: "Parts",
+            decisionNote: "Itemize the estimate",
+            evidenceDocumentId: 22,
+            evidenceFileName: "estimate.pdf",
+          },
+        ],
+      });
+      return;
+    }
+    await fulfillJson(route, []);
+  });
+
+  await page.goto("/v/portal-token/dispatch/7");
+  await page.getByRole("button", { name: "Revise" }).click();
+  await page.getByLabel("New total NTE").fill("120");
+  await page.getByLabel("Reason").fill("Parts itemized in the attached estimate");
+  await page.getByRole("button", { name: "Submit revision" }).click();
+
+  await expect(page.getByText("Pending", { exact: true })).toBeVisible();
+  expect(revisionBody).toEqual({
+    requestedNTE: 120,
+    reason: "Parts itemized in the attached estimate",
+    evidenceDocumentId: 22,
+  });
+});
+
+test("internal approver can approve and request changes with audited notes", async ({ page }) => {
+  const decisions: Array<{ path: string; body: unknown }> = [];
+  const statuses = new Map<number, string>([
+    [41, "Pending"],
+    [42, "Pending"],
+  ]);
+
+  await page.addInitScript(
+    (user) => localStorage.setItem("auth", JSON.stringify(user)),
+    INTERNAL_USER,
+  );
+  await page.route("**/api/Dashboard/Stats", (route) => fulfillJson(route, {}));
+  await page.route("**/api/User*", (route) => fulfillJson(route, []));
+  await page.route(/\/api\/uplifts(?:[/?]|$)/, async (route) => {
+    const request = route.request();
+    const path = new URL(request.url()).pathname;
+    const action = path.match(/\/uplifts\/(41|42)\/(approve|request-changes)$/);
+    if (action && request.method() === "POST") {
+      const id = Number(action[1]);
+      statuses.set(id, action[2] === "approve" ? "Approved" : "ChangesRequested");
+      decisions.push({ path, body: request.postDataJSON() });
+      await fulfillJson(route, { id, status: statuses.get(id) });
+      return;
+    }
+
+    await fulfillJson(route, {
+      total: 2,
+      items: [
+        {
+          id: 41,
+          dispatchId: 7,
+          dispatchNumber: "DSP-41",
+          poNumber: "PO-41",
+          vendorCompanyName: "Gateway Plumbing",
+          currentNTE: 100,
+          requestedNTE: 125,
+          delta: 25,
+          requiredTier: 1,
+          status: statuses.get(41),
+          canDecide: true,
+          evidenceDocumentId: 22,
+          evidenceFileName: "estimate.pdf",
+          evidenceContentType: "application/pdf",
+          evidenceSizeBytes: 2048,
+        },
+        {
+          id: 42,
+          dispatchId: 8,
+          dispatchNumber: "DSP-42",
+          poNumber: "PO-42",
+          vendorCompanyName: "Metro HVAC",
+          currentNTE: 200,
+          requestedNTE: 260,
+          delta: 60,
+          requiredTier: 2,
+          status: statuses.get(42),
+          canDecide: true,
+          evidenceDocumentId: 23,
+          evidenceFileName: "quote.pdf",
+        },
+      ],
+    });
+  });
+
+  await page.goto("/uplifts");
+  await expect(page.getByRole("heading", { name: "Uplift Queue" })).toBeVisible();
+
+  const approvalRow = page.getByRole("row").filter({ hasText: "DSP-41" });
+  await approvalRow.getByRole("button", { name: "Approve" }).click();
+  await page.getByRole("button", { name: "Confirm" }).click();
+
+  const changesRow = page.getByRole("row").filter({ hasText: "DSP-42" });
+  await changesRow.getByRole("button", { name: "Request Changes" }).click();
+  await page.getByLabel("Note (required)").fill("Please itemize labor and parts.");
+  await page.getByRole("button", { name: "Confirm" }).click();
+
+  await expect
+    .poll(() => decisions)
+    .toEqual([
+      { path: "/api/uplifts/41/approve", body: {} },
+      {
+        path: "/api/uplifts/42/request-changes",
+        body: { note: "Please itemize labor and parts." },
+      },
+    ]);
+});

src/app/(protected)/uplifts/index.tsx

@@ -27,28 +27,319 @@ import {
   Tooltip,
   Typography,
 } from "@mui/material";
+import { upliftsApi } from "@/domain/uplifts/api/uplifts-api";
 import type { UpliftQueueItem } from "@/domain/uplifts/types/uplift";
-import { useApproveUplift, useDenyUplift } from "@/domain/uplifts/use-cases/use-uplift-actions";
+import { UPLIFT_STATUSES } from "@/domain/uplifts/types/uplift";
+import {
+  useApproveUplift,
+  useRejectUplift,
+  useRequestChangesUplift,
+} from "@/domain/uplifts/use-cases/use-uplift-actions";
 import { useUpliftsQueue } from "@/domain/uplifts/use-cases/use-uplifts-queue";
 import { formatDateTime } from "@/lib/time-utils";
+import { toast } from "react-toastify";
 
-const STATUS_OPTIONS = ["Pending", "Approved", "Denied", "Cancelled", ""];
+const STATUS_OPTIONS = ["", ...UPLIFT_STATUSES];
+
+type UpliftActionType = "approve" | "reject" | "request-changes";
+
+type UpliftDecision = { type: UpliftActionType; item: UpliftQueueItem };
 
 function formatMoney(value: number | null | undefined): string {
   return `$${Number(value ?? 0).toFixed(2)}`;
 }
 
+function formatBytes(value: number | null | undefined): string {
+  if (value == null) return "";
+  if (value < 1024) return `${value} B`;
+  if (value < 1024 * 1024) return `${(value / 1024).toFixed(0)} KB`;
+  return `${(value / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function UpliftQueueHeader({
+  totalCount,
+  isFetching,
+  isLoading,
+}: {
+  totalCount: number;
+  isFetching: boolean;
+  isLoading: boolean;
+}) {
+  return (
+    <Stack direction="row" spacing={2} sx={{ alignItems: "baseline" }}>
+      <Typography variant="h5" component="h1">
+        Uplift Queue
+      </Typography>
+      <Typography variant="body2" sx={{ color: "text.secondary" }}>
+        {totalCount} total
+      </Typography>
+      {isFetching && !isLoading && <CircularProgress size={16} />}
+    </Stack>
+  );
+}
+
+function UpliftQueueFilters({
+  status,
+  tier,
+  onStatusChange,
+  onTierChange,
+}: {
+  status: string;
+  tier: string;
+  onStatusChange: (value: string) => void;
+  onTierChange: (value: string) => void;
+}) {
+  return (
+    <Stack direction="row" spacing={2}>
+      <FormControl size="small" className="min-w-[140px]">
+        <InputLabel>Status</InputLabel>
+        <Select label="Status" value={status} onChange={(e) => onStatusChange(e.target.value)}>
+          {STATUS_OPTIONS.map((s) => (
+            <MenuItem key={s || "all"} value={s}>
+              {s || "All"}
+            </MenuItem>
+          ))}
+        </Select>
+      </FormControl>
+      <FormControl size="small" className="min-w-[120px]">
+        <InputLabel>Tier</InputLabel>
+        <Select label="Tier" value={tier} onChange={(e) => onTierChange(e.target.value)}>
+          <MenuItem value="">All</MenuItem>
+          <MenuItem value="1">Tier 1</MenuItem>
+          <MenuItem value="2">Tier 2</MenuItem>
+        </Select>
+      </FormControl>
+    </Stack>
+  );
+}
+
+function UpliftQueueRow({
+  row,
+  onViewWorkOrder,
+  onDownloadEvidence,
+  onDecide,
+}: {
+  row: UpliftQueueItem;
+  onViewWorkOrder: (row: UpliftQueueItem) => void;
+  onDownloadEvidence: (row: UpliftQueueItem) => void;
+  onDecide: (type: UpliftActionType, row: UpliftQueueItem) => void;
+}) {
+  const decisionable = row.status === "Pending";
+  return (
+    <TableRow hover>
+      <TableCell>{row.dispatchNumber}</TableCell>
+      <TableCell>{row.poNumber}</TableCell>
+      <TableCell>{row.vendorCompanyName}</TableCell>
+      <TableCell>{formatMoney(row.currentNTE)}</TableCell>
+      <TableCell>{formatMoney(row.requestedNTE)}</TableCell>
+      <TableCell>
+        <Chip size="small" label={`Tier ${row.requiredTier}`} />
+      </TableCell>
+      <TableCell>
+        <Chip size="small" label={row.status} />
+      </TableCell>
+      <TableCell>
+        {row.evidenceDocumentId != null ? (
+          <Stack direction="column" spacing={0.5}>
+            <Typography variant="caption">{row.evidenceFileName}</Typography>
+            {Boolean(row.evidenceContentType) && (
+              <Typography variant="caption" color="text.secondary">
+                {row.evidenceContentType} · {formatBytes(row.evidenceSizeBytes)}
+              </Typography>
+            )}
+            <Button size="small" variant="text" onClick={() => void onDownloadEvidence(row)}>
+              Download
+            </Button>
+          </Stack>
+        ) : (
+          <Typography variant="caption" color="text.secondary">
+            —
+          </Typography>
+        )}
+      </TableCell>
+      <TableCell>{row.requestedAt ? formatDateTime(row.requestedAt) : ""}</TableCell>
+      <TableCell>
+        <Stack direction="row" spacing={1}>
+          {Boolean(row.workOrderId) && (
+            <Button size="small" variant="outlined" onClick={() => onViewWorkOrder(row)}>
+              View
+            </Button>
+          )}
+          {decisionable && (
+            <>
+              <Tooltip title={!row.canDecide ? `Requires Tier ${row.requiredTier} role` : ""}>
+                <span>
+                  <Button
+                    size="small"
+                    variant="contained"
+                    color="success"
+                    disabled={!row.canDecide}
+                    onClick={() => onDecide("approve", row)}
+                  >
+                    Approve
+                  </Button>
+                </span>
+              </Tooltip>
+              <Tooltip title={!row.canDecide ? `Requires Tier ${row.requiredTier} role` : ""}>
+                <span>
+                  <Button
+                    size="small"
+                    variant="contained"
+                    color="error"
+                    disabled={!row.canDecide}
+                    onClick={() => onDecide("reject", row)}
+                  >
+                    Reject
+                  </Button>
+                </span>
+              </Tooltip>
+              <Tooltip title={!row.canDecide ? `Requires Tier ${row.requiredTier} role` : ""}>
+                <span>
+                  <Button
+                    size="small"
+                    variant="outlined"
+                    disabled={!row.canDecide}
+                    onClick={() => onDecide("request-changes", row)}
+                  >
+                    Request Changes
+                  </Button>
+                </span>
+              </Tooltip>
+            </>
+          )}
+        </Stack>
+      </TableCell>
+    </TableRow>
+  );
+}
+
+function UpliftQueueTable({
+  isLoading,
+  rows,
+  onViewWorkOrder,
+  onDownloadEvidence,
+  onDecide,
+}: {
+  isLoading: boolean;
+  rows: UpliftQueueItem[];
+  onViewWorkOrder: (row: UpliftQueueItem) => void;
+  onDownloadEvidence: (row: UpliftQueueItem) => void;
+  onDecide: (type: UpliftActionType, row: UpliftQueueItem) => void;
+}) {
+  return (
+    <TableContainer component={Paper} variant="outlined">
+      <Table size="small">
+        <TableHead>
+          <TableRow>
+            <TableCell className="font-semibold">Dispatch</TableCell>
+            <TableCell className="font-semibold">PO</TableCell>
+            <TableCell className="font-semibold">Vendor</TableCell>
+            <TableCell className="font-semibold">Current NTE</TableCell>
+            <TableCell className="font-semibold">Requested</TableCell>
+            <TableCell className="font-semibold">Tier</TableCell>
+            <TableCell className="font-semibold">Status</TableCell>
+            <TableCell className="font-semibold">Evidence</TableCell>
+            <TableCell className="font-semibold">Requested At</TableCell>
+            <TableCell className="font-semibold">Actions</TableCell>
+          </TableRow>
+        </TableHead>
+        <TableBody>
+          {isLoading ? (
+            <TableRow>
+              <TableCell colSpan={10} align="center" className="py-10">
+                <CircularProgress size={28} />
+              </TableCell>
+            </TableRow>
+          ) : rows.length === 0 ? (
+            <TableRow>
+              <TableCell colSpan={10} align="center" className="py-10">
+                <Typography sx={{ color: "text.secondary" }}>
+                  No uplift requests match these filters.
+                </Typography>
+              </TableCell>
+            </TableRow>
+          ) : (
+            rows.map((row) => (
+              <UpliftQueueRow
+                key={String(row.id)}
+                row={row}
+                onViewWorkOrder={onViewWorkOrder}
+                onDownloadEvidence={onDownloadEvidence}
+                onDecide={onDecide}
+              />
+            ))
+          )}
+        </TableBody>
+      </Table>
+    </TableContainer>
+  );
+}
+
+function UpliftDecisionDialog({
+  action,
+  note,
+  noteRequired,
+  decisionPending,
+  onNoteChange,
+  onClose,
+  onConfirm,
+}: {
+  action: UpliftDecision | null;
+  note: string;
+  noteRequired: boolean;
+  decisionPending: boolean;
+  onNoteChange: (value: string) => void;
+  onClose: () => void;
+  onConfirm: () => void;
+}) {
+  return (
+    <Dialog open={Boolean(action)} onClose={onClose}>
+      <DialogTitle>
+        {action?.type === "approve"
+          ? `Approve uplift to ${formatMoney(action.item.requestedNTE)}?`
+          : action?.type === "reject"
+            ? "Reject Uplift"
+            : "Request Changes"}
+      </DialogTitle>
+      <DialogContent>
+        {action?.type === "approve" && (
+          <Typography variant="body2" className="mt-1 mb-3">
+            {formatMoney(action.item.currentNTE)} → {formatMoney(action.item.requestedNTE)}
+          </Typography>
+        )}
+        <TextField
+          fullWidth
+          multiline
+          minRows={2}
+          className="mt-2"
+          label={noteRequired ? "Note (required)" : "Optional note"}
+          value={note}
+          required={noteRequired}
+          onChange={(e) => onNoteChange(e.target.value)}
+        />
+      </DialogContent>
+      <DialogActions>
+        <Button onClick={onClose}>Cancel</Button>
+        <Button
+          variant="contained"
+          color={action?.type === "approve" ? "success" : "primary"}
+          disabled={noteRequired ? !note.trim() || decisionPending : decisionPending}
+          onClick={onConfirm}
+        >
+          Confirm
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+}
+
 export default function UpliftQueuePage() {
   const navigate = useNavigate();
   const [status, setStatus] = useState("Pending");
   const [tier, setTier] = useState("");
   const [page, setPage] = useState(0);
   const [pageSize] = useState(25);
-
-  const [upliftAction, setUpliftAction] = useState<{
-    type: "approve" | "deny";
-    item: UpliftQueueItem;
-  } | null>(null);
+  const [upliftAction, setUpliftAction] = useState<UpliftDecision | null>(null);
   const [note, setNote] = useState("");
 
   const listParams = useMemo(
@@ -58,39 +349,59 @@ export default function UpliftQueuePage() {
 
   const { data, isLoading, isFetching, error, refetch } = useUpliftsQueue(listParams);
   const approveUplift = useApproveUplift();
-  const denyUplift = useDenyUplift();
+  const rejectUplift = useRejectUplift();
+  const requestChangesUplift = useRequestChangesUplift();
 
   const rows = data?.items ?? [];
   const totalCount = data?.totalCount ?? 0;
+  const noteRequired = upliftAction?.type === "reject" || upliftAction?.type === "request-changes";
+  const decisionPending =
+    approveUplift.isPending || rejectUplift.isPending || requestChangesUplift.isPending;
+
+  const handleStatusChange = (value: string) => {
+    setStatus(value);
+    setPage(0);
+  };
+  const handleTierChange = (value: string) => {
+    setTier(value);
+    setPage(0);
+  };
+
+  const closeDialog = () => {
+    setUpliftAction(null);
+    setNote("");
+  };
 
   const handleConfirm = () => {
     if (!upliftAction) return;
+    if (noteRequired && !note.trim()) return;
+    const id = upliftAction.item.id;
+    const onDone = () => {
+      closeDialog();
+      void refetch();
+    };
     if (upliftAction.type === "approve") {
-      approveUplift.mutate(
-        { id: upliftAction.item.id, note: note || undefined },
-        {
-          onSuccess: () => {
-            setUpliftAction(null);
-            setNote("");
-            void refetch();
-          },
-        },
-      );
+      approveUplift.mutate({ id, note: note || undefined }, { onSuccess: onDone });
+    } else if (upliftAction.type === "reject") {
+      rejectUplift.mutate({ id, note: note.trim() }, { onSuccess: onDone });
     } else {
-      if (!note.trim()) return;
-      denyUplift.mutate(
-        { id: upliftAction.item.id, note: note.trim() },
-        {
-          onSuccess: () => {
-            setUpliftAction(null);
-            setNote("");
-            void refetch();
-          },
-        },
-      );
+      requestChangesUplift.mutate({ id, note: note.trim() }, { onSuccess: onDone });
     }
   };
 
+  const downloadEvidence = async (item: UpliftQueueItem) => {
+    try {
+      await upliftsApi.downloadEvidence(item.id, item.evidenceFileName || "uplift-evidence");
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : "Unable to download evidence.");
+    }
+  };
+
+  const handleDecide = (type: UpliftActionType, item: UpliftQueueItem) => {
+    setUpliftAction({ type, item });
+    setNote("");
+  };
+
   return (
     <Box className="flex flex-col gap-4 p-4">
       <Stack
@@ -101,177 +412,26 @@ export default function UpliftQueuePage() {
           justifyContent: "space-between",
         }}
       >
-        <Stack
-          direction="row"
-          spacing={2}
-          sx={{
-            alignItems: "baseline",
-          }}
-        >
-          <Typography variant="h5" component="h1">
-            Uplift Queue
-          </Typography>
-          <Typography
-            variant="body2"
-            sx={{
-              color: "text.secondary",
-            }}
-          >
-            {totalCount} total
-          </Typography>
-          {isFetching && !isLoading && <CircularProgress size={16} />}
-        </Stack>
-
-        <Stack direction="row" spacing={2}>
-          <FormControl size="small" className="min-w-[140px]">
-            <InputLabel>Status</InputLabel>
-            <Select
-              label="Status"
-              value={status}
-              onChange={(e) => {
-                setStatus(e.target.value);
-                setPage(0);
-              }}
-            >
-              {STATUS_OPTIONS.map((s) => (
-                <MenuItem key={s || "all"} value={s}>
-                  {s || "All"}
-                </MenuItem>
-              ))}
-            </Select>
-          </FormControl>
-          <FormControl size="small" className="min-w-[120px]">
-            <InputLabel>Tier</InputLabel>
-            <Select
-              label="Tier"
-              value={tier}
-              onChange={(e) => {
-                setTier(e.target.value);
-                setPage(0);
-              }}
-            >
-              <MenuItem value="">All</MenuItem>
-              <MenuItem value="1">Tier 1</MenuItem>
-              <MenuItem value="2">Tier 2</MenuItem>
-            </Select>
-          </FormControl>
-        </Stack>
+        <UpliftQueueHeader totalCount={totalCount} isFetching={isFetching} isLoading={isLoading} />
+        <UpliftQueueFilters
+          status={status}
+          tier={tier}
+          onStatusChange={handleStatusChange}
+          onTierChange={handleTierChange}
+        />
       </Stack>
       {Boolean(error) && (
         <Alert severity="error">
           {error instanceof Error ? error.message : "Failed to load uplift queue"}
         </Alert>
       )}
-      <TableContainer component={Paper} variant="outlined">
-        <Table size="small">
-          <TableHead>
-            <TableRow>
-              <TableCell className="font-semibold">Dispatch</TableCell>
-              <TableCell className="font-semibold">PO</TableCell>
-              <TableCell className="font-semibold">Vendor</TableCell>
-              <TableCell className="font-semibold">Current NTE</TableCell>
-              <TableCell className="font-semibold">Requested</TableCell>
-              <TableCell className="font-semibold">Delta</TableCell>
-              <TableCell className="font-semibold">Tier</TableCell>
-              <TableCell className="font-semibold">Status</TableCell>
-              <TableCell className="font-semibold">Requested At</TableCell>
-              <TableCell className="font-semibold">Actions</TableCell>
-            </TableRow>
-          </TableHead>
-          <TableBody>
-            {isLoading ? (
-              <TableRow>
-                <TableCell colSpan={10} align="center" className="py-10">
-                  <CircularProgress size={28} />
-                </TableCell>
-              </TableRow>
-            ) : rows.length === 0 ? (
-              <TableRow>
-                <TableCell colSpan={10} align="center" className="py-10">
-                  <Typography
-                    sx={{
-                      color: "text.secondary",
-                    }}
-                  >
-                    No uplift requests match these filters.
-                  </Typography>
-                </TableCell>
-              </TableRow>
-            ) : (
-              rows.map((row) => (
-                <TableRow key={String(row.id)} hover>
-                  <TableCell>{row.dispatchNumber}</TableCell>
-                  <TableCell>{row.poNumber}</TableCell>
-                  <TableCell>{row.vendorCompanyName}</TableCell>
-                  <TableCell>{formatMoney(row.currentNTE)}</TableCell>
-                  <TableCell>{formatMoney(row.requestedNTE)}</TableCell>
-                  <TableCell>{formatMoney(row.delta)}</TableCell>
-                  <TableCell>
-                    <Chip size="small" label={`Tier ${row.requiredTier}`} />
-                  </TableCell>
-                  <TableCell>
-                    <Chip size="small" label={row.status} />
-                  </TableCell>
-                  <TableCell>{row.requestedAt ? formatDateTime(row.requestedAt) : ""}</TableCell>
-                  <TableCell>
-                    <Stack direction="row" spacing={1}>
-                      {Boolean(row.workOrderId) && (
-                        <Button
-                          size="small"
-                          variant="outlined"
-                          onClick={() => navigate(`/workorders/${row.workOrderId}`)}
-                        >
-                          View
-                        </Button>
-                      )}
-                      {row.status === "Pending" && (
-                        <>
-                          <Tooltip
-                            title={!row.canDecide ? `Requires Tier ${row.requiredTier} role` : ""}
-                          >
-                            <span>
-                              <Button
-                                size="small"
-                                variant="contained"
-                                color="success"
-                                disabled={!row.canDecide}
-                                onClick={() => {
-                                  setUpliftAction({ type: "approve", item: row });
-                                  setNote("");
-                                }}
-                              >
-                                Approve
-                              </Button>
-                            </span>
-                          </Tooltip>
-                          <Tooltip
-                            title={!row.canDecide ? `Requires Tier ${row.requiredTier} role` : ""}
-                          >
-                            <span>
-                              <Button
-                                size="small"
-                                variant="contained"
-                                color="error"
-                                disabled={!row.canDecide}
-                                onClick={() => {
-                                  setUpliftAction({ type: "deny", item: row });
-                                  setNote("");
-                                }}
-                              >
-                                Deny
-                              </Button>
-                            </span>
-                          </Tooltip>
-                        </>
-                      )}
-                    </Stack>
-                  </TableCell>
-                </TableRow>
-              ))
-            )}
-          </TableBody>
-        </Table>
-      </TableContainer>
+      <UpliftQueueTable
+        isLoading={isLoading}
+        rows={rows}
+        onViewWorkOrder={(r) => navigate(`/workorders/${r.workOrderId}`)}
+        onDownloadEvidence={(r) => void downloadEvidence(r)}
+        onDecide={handleDecide}
+      />
       <TablePagination
         component="div"
         count={totalCount}
@@ -280,46 +440,15 @@ export default function UpliftQueuePage() {
         rowsPerPage={pageSize}
         rowsPerPageOptions={[25]}
       />
-      <Dialog open={Boolean(upliftAction)} onClose={() => setUpliftAction(null)}>
-        <DialogTitle>
-          {upliftAction?.type === "approve"
-            ? `Approve uplift to ${formatMoney(upliftAction.item.requestedNTE)}?`
-            : "Deny Uplift"}
-        </DialogTitle>
-        <DialogContent>
-          {upliftAction?.type === "approve" && (
-            <Typography variant="body2" className="mt-1 mb-3">
-              {formatMoney(upliftAction.item.currentNTE)} →{" "}
-              {formatMoney(upliftAction.item.requestedNTE)} (+
-              {formatMoney(upliftAction.item.delta)})
-            </Typography>
-          )}
-          <TextField
-            fullWidth
-            multiline
-            minRows={2}
-            className="mt-2"
-            label={upliftAction?.type === "deny" ? "Denial reason (required)" : "Optional note"}
-            value={note}
-            onChange={(e) => setNote(e.target.value)}
-          />
-        </DialogContent>
-        <DialogActions>
-          <Button onClick={() => setUpliftAction(null)}>Cancel</Button>
-          <Button
-            variant="contained"
-            color={upliftAction?.type === "approve" ? "success" : "error"}
-            disabled={
-              upliftAction?.type === "deny"
-                ? !note.trim() || denyUplift.isPending
-                : approveUplift.isPending
-            }
-            onClick={handleConfirm}
-          >
-            Confirm
-          </Button>
-        </DialogActions>
-      </Dialog>
+      <UpliftDecisionDialog
+        action={upliftAction}
+        note={note}
+        noteRequired={noteRequired}
+        decisionPending={decisionPending}
+        onNoteChange={setNote}
+        onClose={closeDialog}
+        onConfirm={handleConfirm}
+      />
     </Box>
   );
 }

src/app/(protected)/vendor-pos/[id].tsx

@@ -1,90 +1,82 @@
-import { useState, type ReactNode } from "react";
+import { useState } from "react";
 import { useNavigate, useParams } from "react-router";
-import {
-  Alert,
-  Box,
-  Button,
-  Chip,
-  CircularProgress,
-  Dialog,
-  DialogActions,
-  DialogContent,
-  DialogTitle,
-  Paper,
-  Stack,
-  Table,
-  TableBody,
-  TableCell,
-  TableHead,
-  TableRow,
-  TextField,
-  Typography,
-} from "@mui/material";
-import { useApproveUplift, useDenyUplift } from "@/domain/uplifts/use-cases/use-uplift-actions";
-import { useVendorPoDetail } from "@/domain/vendor-pos/use-cases/use-vendor-po-detail";
+import { Alert, Box, Button, Chip, CircularProgress, Stack, Typography } from "@mui/material";
+import { toast } from "react-toastify";
+import { upliftsApi } from "@/domain/uplifts/api/uplifts-api";
 import type { UpliftRequest } from "@/domain/uplifts/types/uplift";
-import { formatDateTime, toDateInputValue } from "@/lib/time-utils";
+import {
+  useApproveUplift,
+  useRejectUplift,
+  useRequestChangesUplift,
+} from "@/domain/uplifts/use-cases/use-uplift-actions";
+import { useVendorPoDetail } from "@/domain/vendor-pos/use-cases/use-vendor-po-detail";
+import {
+  PoDetailsPaper,
+  SitePaper,
+  UpliftDecisionDialog,
+  UpliftHistoryPaper,
+  VendorSummaryPaper,
+  WorkOrdersPaper,
+  type UpliftActionType,
+  type VendorPoUpliftDecision,
+} from "@/app/(protected)/vendor-pos/_components/vendor-po-sections";
 
 function formatMoney(value: number | null | undefined): string {
   if (value == null) return "—";
   return `$${Number(value).toFixed(2)}`;
 }
 
-function InfoRow({ label, children }: { label: string; children: ReactNode }) {
-  return (
-    <Box>
-      <Typography variant="caption" color="text.secondary" sx={{ display: "block" }}>
-        {label}
-      </Typography>
-      <Typography variant="body2">
-        {children == null || children === "" ? "—" : children}
-      </Typography>
-    </Box>
-  );
-}
-
 export default function VendorPoViewPage() {
   const { id } = useParams();
   const navigate = useNavigate();
   const { data: dispatch, isLoading, error, refetch } = useVendorPoDetail(id);
 
   const approveUplift = useApproveUplift(id);
-  const denyUplift = useDenyUplift(id);
+  const rejectUplift = useRejectUplift(id);
+  const requestChangesUplift = useRequestChangesUplift(id);
 
-  const [upliftAction, setUpliftAction] = useState<{
-    type: "approve" | "deny";
-    uplift: UpliftRequest;
-  } | null>(null);
+  const [upliftAction, setUpliftAction] = useState<VendorPoUpliftDecision | null>(null);
   const [note, setNote] = useState("");
 
+  const noteRequired = upliftAction?.type === "reject" || upliftAction?.type === "request-changes";
+  const decisionPending =
+    approveUplift.isPending || rejectUplift.isPending || requestChangesUplift.isPending;
+
+  const closeUpliftDialog = () => {
+    setUpliftAction(null);
+    setNote("");
+  };
+
   const handleUpliftConfirm = () => {
     if (!upliftAction) return;
+    if (noteRequired && !note.trim()) return;
+    const upliftId = upliftAction.uplift.id;
+    const onDone = () => {
+      closeUpliftDialog();
+      void refetch();
+    };
     if (upliftAction.type === "approve") {
-      approveUplift.mutate(
-        { id: upliftAction.uplift.id, note: note || undefined },
-        {
-          onSuccess: () => {
-            setUpliftAction(null);
-            setNote("");
-            void refetch();
-          },
-        },
-      );
+      approveUplift.mutate({ id: upliftId, note: note || undefined }, { onSuccess: onDone });
+    } else if (upliftAction.type === "reject") {
+      rejectUplift.mutate({ id: upliftId, note: note.trim() }, { onSuccess: onDone });
     } else {
-      if (!note.trim()) return;
-      denyUplift.mutate(
-        { id: upliftAction.uplift.id, note: note.trim() },
-        {
-          onSuccess: () => {
-            setUpliftAction(null);
-            setNote("");
-            void refetch();
-          },
-        },
-      );
+      requestChangesUplift.mutate({ id: upliftId, note: note.trim() }, { onSuccess: onDone });
     }
   };
 
+  const downloadEvidence = async (uplift: UpliftRequest) => {
+    try {
+      await upliftsApi.downloadEvidence(uplift.id, uplift.evidenceFileName || "uplift-evidence");
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : "Unable to download evidence.");
+    }
+  };
+
+  const handleDecide = (type: UpliftActionType, uplift: UpliftRequest) => {
+    setUpliftAction({ type, uplift });
+    setNote("");
+  };
+
   if (isLoading) {
     return (
       <Box className="flex justify-center p-10">
@@ -141,212 +133,29 @@ export default function VendorPoViewPage() {
       </Stack>
 
       <Stack spacing={3}>
-        <Paper variant="outlined" className="p-4">
-          <Typography variant="subtitle1" className="mb-3 font-semibold">
-            Vendor
-          </Typography>
-          {vendor ? (
-            <Box className="grid grid-cols-1 gap-3 sm:grid-cols-2 md:grid-cols-3">
-              <InfoRow label="Company">{vendor.companyName}</InfoRow>
-              <InfoRow label="Contact">{vendor.contactName}</InfoRow>
-              <InfoRow label="Email">{vendor.email}</InfoRow>
-              <InfoRow label="Phone">{vendor.phone}</InfoRow>
-              <InfoRow label="Address">
-                {[vendor.address, vendor.city, vendor.state, vendor.zip].filter(Boolean).join(", ")}
-              </InfoRow>
-              <InfoRow label="Trades">{vendor.tradeSpecialties}</InfoRow>
-            </Box>
-          ) : (
-            <Typography color="text.secondary">No vendor attached.</Typography>
-          )}
-        </Paper>
-
-        <Paper variant="outlined" className="p-4">
-          <Typography variant="subtitle1" className="mb-3 font-semibold">
-            PO Details
-          </Typography>
-          <Box className="grid grid-cols-1 gap-3 sm:grid-cols-2 md:grid-cols-3">
-            <InfoRow label="PO #">{dispatch.poNumber}</InfoRow>
-            <InfoRow label="Dispatch #">{dispatch.dispatchNumber}</InfoRow>
-            <InfoRow label="Status">{dispatch.status}</InfoRow>
-            <InfoRow label="NTE">{formatMoney(dispatch.nteAmount)}</InfoRow>
-            <InfoRow label="Dispatched">{formatDateTime(dispatch.dispatchedAt)}</InfoRow>
-            <InfoRow label="Acknowledged">{formatDateTime(dispatch.acknowledgedAt)}</InfoRow>
-            <InfoRow label="Scheduled">{toDateInputValue(dispatch.scheduledDate) || "—"}</InfoRow>
-            <InfoRow label="Completed">{toDateInputValue(dispatch.completedDate) || "—"}</InfoRow>
-            <InfoRow label="Verified">{formatDateTime(dispatch.verifiedAt)}</InfoRow>
-            <InfoRow label="Email sent">{dispatch.emailSent ? "Yes" : "No"}</InfoRow>
-          </Box>
-          {Boolean(dispatch.description) && (
-            <Box className="mt-3">
-              <Typography variant="caption" color="text.secondary">
-                Description
-              </Typography>
-              <Typography variant="body2" className="whitespace-pre-wrap">
-                {dispatch.description}
-              </Typography>
-            </Box>
-          )}
-        </Paper>
-
-        {dispatch.primaryLocation != null && (
-          <Paper variant="outlined" className="p-4">
-            <Typography variant="subtitle1" className="mb-3 font-semibold">
-              Site
-            </Typography>
-            <Box className="grid grid-cols-1 gap-3 sm:grid-cols-2">
-              <InfoRow label="Location">{dispatch.primaryLocation.name}</InfoRow>
-              <InfoRow label="Address">
-                {[
-                  dispatch.primaryLocation.address,
-                  dispatch.primaryLocation.city,
-                  dispatch.primaryLocation.state,
-                  dispatch.primaryLocation.zipCode,
-                ]
-                  .filter(Boolean)
-                  .join(", ")}
-              </InfoRow>
-            </Box>
-          </Paper>
-        )}
-
-        <Paper variant="outlined" className="p-4">
-          <Typography variant="subtitle1" className="mb-3 font-semibold">
-            Linked Work Orders ({dispatch.workOrders.length})
-          </Typography>
-          {dispatch.workOrders.length === 0 ? (
-            <Typography color="text.secondary">No work orders linked.</Typography>
-          ) : (
-            <Table size="small">
-              <TableHead>
-                <TableRow>
-                  <TableCell>WO #</TableCell>
-                  <TableCell>Title</TableCell>
-                  <TableCell>Trade</TableCell>
-                  <TableCell>Status</TableCell>
-                  <TableCell>Location</TableCell>
-                </TableRow>
-              </TableHead>
-              <TableBody>
-                {dispatch.workOrders.map((wo) => (
-                  <TableRow key={String(wo.workOrderId)}>
-                    <TableCell>
-                      <Button
-                        variant="text"
-                        size="small"
-                        onClick={() => navigate(`/workorders/${wo.workOrderId}`)}
-                      >
-                        {wo.internalWONumber || wo.workOrderId}
-                      </Button>
-                    </TableCell>
-                    <TableCell>{wo.title}</TableCell>
-                    <TableCell>{wo.trade}</TableCell>
-                    <TableCell>{wo.status}</TableCell>
-                    <TableCell>{wo.locationName}</TableCell>
-                  </TableRow>
-                ))}
-              </TableBody>
-            </Table>
-          )}
-        </Paper>
-
-        <Paper variant="outlined" className="p-4">
-          <Typography variant="subtitle1" className="mb-3 font-semibold">
-            NTE Uplift History ({dispatch.upliftRequests.length})
-          </Typography>
-          {dispatch.upliftRequests.length === 0 ? (
-            <Typography color="text.secondary">No uplift requests on this PO.</Typography>
-          ) : (
-            <Stack spacing={2}>
-              {dispatch.upliftRequests.map((u) => (
-                <Box key={String(u.id)} className="rounded border border-border p-3">
-                  <Stack
-                    direction="row"
-                    sx={{ justifyContent: "space-between", alignItems: "center" }}
-                  >
-                    <Typography variant="body2" className="font-semibold">
-                      {formatMoney(u.currentNTE)} → {formatMoney(u.requestedNTE)}
-                      <Typography
-                        component="span"
-                        variant="caption"
-                        color="text.secondary"
-                        className="ml-2"
-                      >
-                        (Δ {formatMoney(u.delta)}, Tier {u.requiredTier})
-                      </Typography>
-                    </Typography>
-                    <Chip size="small" label={u.status} />
-                  </Stack>
-                  {Boolean(u.vendorReason) && (
-                    <Typography variant="body2" className="mt-1">
-                      <strong>Reason:</strong> {u.vendorReason}
-                    </Typography>
-                  )}
-                  {u.status === "Pending" && (
-                    <Stack direction="row" spacing={1} className="mt-2">
-                      <Button
-                        size="small"
-                        variant="contained"
-                        color="success"
-                        onClick={() => {
-                          setUpliftAction({ type: "approve", uplift: u });
-                          setNote("");
-                        }}
-                      >
-                        Approve
-                      </Button>
-                      <Button
-                        size="small"
-                        variant="contained"
-                        color="error"
-                        onClick={() => {
-                          setUpliftAction({ type: "deny", uplift: u });
-                          setNote("");
-                        }}
-                      >
-                        Deny
-                      </Button>
-                    </Stack>
-                  )}
-                </Box>
-              ))}
-            </Stack>
-          )}
-        </Paper>
+        <VendorSummaryPaper vendor={vendor} />
+        <PoDetailsPaper dispatch={dispatch} />
+        <SitePaper location={dispatch.primaryLocation} />
+        <WorkOrdersPaper
+          workOrders={dispatch.workOrders}
+          onView={(workOrderId) => navigate(`/workorders/${workOrderId}`)}
+        />
+        <UpliftHistoryPaper
+          upliftRequests={dispatch.upliftRequests}
+          onDownload={(uplift) => void downloadEvidence(uplift)}
+          onDecide={handleDecide}
+        />
       </Stack>
 
-      <Dialog open={Boolean(upliftAction)} onClose={() => setUpliftAction(null)}>
-        <DialogTitle>
-          {upliftAction?.type === "approve" ? "Approve Uplift" : "Deny Uplift"}
-        </DialogTitle>
-        <DialogContent>
-          <TextField
-            fullWidth
-            multiline
-            minRows={2}
-            className="mt-2"
-            label={upliftAction?.type === "deny" ? "Denial reason (required)" : "Optional note"}
-            value={note}
-            onChange={(e) => setNote(e.target.value)}
-            required={upliftAction?.type === "deny"}
-          />
-        </DialogContent>
-        <DialogActions>
-          <Button onClick={() => setUpliftAction(null)}>Cancel</Button>
-          <Button
-            variant="contained"
-            color={upliftAction?.type === "approve" ? "success" : "error"}
-            disabled={
-              upliftAction?.type === "deny"
-                ? !note.trim() || denyUplift.isPending
-                : approveUplift.isPending
-            }
-            onClick={handleUpliftConfirm}
-          >
-            Confirm
-          </Button>
-        </DialogActions>
-      </Dialog>
+      <UpliftDecisionDialog
+        action={upliftAction}
+        note={note}
+        noteRequired={noteRequired}
+        decisionPending={decisionPending}
+        onNoteChange={setNote}
+        onClose={closeUpliftDialog}
+        onConfirm={handleUpliftConfirm}
+      />
     </Box>
   );
 }

src/app/(protected)/vendor-pos/_components/vendor-po-sections.tsx

@@ -0,0 +1,341 @@
+import { type ReactNode } from "react";
+import {
+  Box,
+  Button,
+  Chip,
+  Dialog,
+  DialogActions,
+  DialogContent,
+  DialogTitle,
+  Paper,
+  Stack,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableRow,
+  TextField,
+  Typography,
+} from "@mui/material";
+import type { UpliftRequest } from "@/domain/uplifts/types/uplift";
+import type {
+  VendorPoDetail,
+  VendorPoLocation,
+  VendorPoVendor,
+  VendorPoWorkOrder,
+} from "@/domain/vendor-pos/types/vendor-po";
+import { formatDateTime, toDateInputValue } from "@/lib/time-utils";
+
+export type UpliftActionType = "approve" | "reject" | "request-changes";
+
+export type VendorPoUpliftDecision = { type: UpliftActionType; uplift: UpliftRequest };
+
+function formatMoney(value: number | null | undefined): string {
+  if (value == null) return "—";
+  return `$${Number(value).toFixed(2)}`;
+}
+
+function InfoRow({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <Box>
+      <Typography variant="caption" color="text.secondary" sx={{ display: "block" }}>
+        {label}
+      </Typography>
+      <Typography variant="body2">
+        {children == null || children === "" ? "—" : children}
+      </Typography>
+    </Box>
+  );
+}
+
+export function VendorSummaryPaper({ vendor }: { vendor: VendorPoVendor | null }) {
+  return (
+    <Paper variant="outlined" className="p-4">
+      <Typography variant="subtitle1" className="mb-3 font-semibold">
+        Vendor
+      </Typography>
+      {vendor ? (
+        <Box className="grid grid-cols-1 gap-3 sm:grid-cols-2 md:grid-cols-3">
+          <InfoRow label="Company">{vendor.companyName}</InfoRow>
+          <InfoRow label="Contact">{vendor.contactName}</InfoRow>
+          <InfoRow label="Email">{vendor.email}</InfoRow>
+          <InfoRow label="Phone">{vendor.phone}</InfoRow>
+          <InfoRow label="Address">
+            {[vendor.address, vendor.city, vendor.state, vendor.zip].filter(Boolean).join(", ")}
+          </InfoRow>
+          <InfoRow label="Trades">{vendor.tradeSpecialties}</InfoRow>
+        </Box>
+      ) : (
+        <Typography color="text.secondary">No vendor attached.</Typography>
+      )}
+    </Paper>
+  );
+}
+
+export function PoDetailsPaper({ dispatch }: { dispatch: VendorPoDetail }) {
+  return (
+    <Paper variant="outlined" className="p-4">
+      <Typography variant="subtitle1" className="mb-3 font-semibold">
+        PO Details
+      </Typography>
+      <Box className="grid grid-cols-1 gap-3 sm:grid-cols-2 md:grid-cols-3">
+        <InfoRow label="PO #">{dispatch.poNumber}</InfoRow>
+        <InfoRow label="Dispatch #">{dispatch.dispatchNumber}</InfoRow>
+        <InfoRow label="Status">{dispatch.status}</InfoRow>
+        <InfoRow label="NTE">{formatMoney(dispatch.nteAmount)}</InfoRow>
+        <InfoRow label="Dispatched">{formatDateTime(dispatch.dispatchedAt)}</InfoRow>
+        <InfoRow label="Acknowledged">{formatDateTime(dispatch.acknowledgedAt)}</InfoRow>
+        <InfoRow label="Scheduled">{toDateInputValue(dispatch.scheduledDate) || "—"}</InfoRow>
+        <InfoRow label="Completed">{toDateInputValue(dispatch.completedDate) || "—"}</InfoRow>
+        <InfoRow label="Verified">{formatDateTime(dispatch.verifiedAt)}</InfoRow>
+        <InfoRow label="Email sent">{dispatch.emailSent ? "Yes" : "No"}</InfoRow>
+      </Box>
+      {Boolean(dispatch.description) && (
+        <Box className="mt-3">
+          <Typography variant="caption" color="text.secondary">
+            Description
+          </Typography>
+          <Typography variant="body2" className="whitespace-pre-wrap">
+            {dispatch.description}
+          </Typography>
+        </Box>
+      )}
+    </Paper>
+  );
+}
+
+export function SitePaper({ location }: { location: VendorPoLocation | null }) {
+  if (location == null) return null;
+  return (
+    <Paper variant="outlined" className="p-4">
+      <Typography variant="subtitle1" className="mb-3 font-semibold">
+        Site
+      </Typography>
+      <Box className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+        <InfoRow label="Location">{location.name}</InfoRow>
+        <InfoRow label="Address">
+          {[location.address, location.city, location.state, location.zipCode]
+            .filter(Boolean)
+            .join(", ")}
+        </InfoRow>
+      </Box>
+    </Paper>
+  );
+}
+
+export function WorkOrdersPaper({
+  workOrders,
+  onView,
+}: {
+  workOrders: VendorPoWorkOrder[];
+  onView: (workOrderId: string | number) => void;
+}) {
+  return (
+    <Paper variant="outlined" className="p-4">
+      <Typography variant="subtitle1" className="mb-3 font-semibold">
+        Linked Work Orders ({workOrders.length})
+      </Typography>
+      {workOrders.length === 0 ? (
+        <Typography color="text.secondary">No work orders linked.</Typography>
+      ) : (
+        <Table size="small">
+          <TableHead>
+            <TableRow>
+              <TableCell>WO #</TableCell>
+              <TableCell>Title</TableCell>
+              <TableCell>Trade</TableCell>
+              <TableCell>Status</TableCell>
+              <TableCell>Location</TableCell>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {workOrders.map((wo) => (
+              <TableRow key={String(wo.workOrderId)}>
+                <TableCell>
+                  <Button variant="text" size="small" onClick={() => onView(wo.workOrderId)}>
+                    {wo.internalWONumber || wo.workOrderId}
+                  </Button>
+                </TableCell>
+                <TableCell>{wo.title}</TableCell>
+                <TableCell>{wo.trade}</TableCell>
+                <TableCell>{wo.status}</TableCell>
+                <TableCell>{wo.locationName}</TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      )}
+    </Paper>
+  );
+}
+
+function UpliftHistoryItem({
+  uplift,
+  onDownload,
+  onDecide,
+}: {
+  uplift: UpliftRequest;
+  onDownload: (uplift: UpliftRequest) => void;
+  onDecide: (type: UpliftActionType, uplift: UpliftRequest) => void;
+}) {
+  const decisionable = uplift.status === "Pending";
+  return (
+    <Box className="rounded border border-border p-3">
+      <Stack direction="row" sx={{ justifyContent: "space-between", alignItems: "center" }}>
+        <Typography variant="body2" className="font-semibold">
+          {formatMoney(uplift.currentNTE)} → {formatMoney(uplift.requestedNTE)}
+          <Typography component="span" variant="caption" color="text.secondary" className="ml-2">
+            (Tier {uplift.requiredTier})
+          </Typography>
+        </Typography>
+        <Chip size="small" label={uplift.status} />
+      </Stack>
+      {Boolean(uplift.expiresAt) && (
+        <Typography variant="caption" color="text.secondary" className="mt-1 block">
+          Expires {formatDateTime(uplift.expiresAt)}
+        </Typography>
+      )}
+      {Boolean(uplift.vendorReason) && (
+        <Typography variant="body2" className="mt-1">
+          <strong>Reason:</strong> {uplift.vendorReason}
+        </Typography>
+      )}
+      {uplift.evidenceDocumentId != null && (
+        <Stack direction="row" spacing={1} sx={{ alignItems: "center" }} className="mt-1">
+          <Typography variant="body2">
+            <strong>Evidence:</strong>{" "}
+            {uplift.evidenceFileName || `Document #${uplift.evidenceDocumentId}`}
+          </Typography>
+          <Button size="small" variant="text" onClick={() => onDownload(uplift)}>
+            Download
+          </Button>
+        </Stack>
+      )}
+      {Boolean(uplift.decisionNote) && (
+        <Typography variant="body2" className="mt-1">
+          <strong>Decision:</strong> {uplift.decisionNote}
+        </Typography>
+      )}
+      {uplift.notificationStatus === "Error" && Boolean(uplift.notificationError) && (
+        <Typography variant="body2" color="error" className="mt-1">
+          Notification error: {uplift.notificationError}
+        </Typography>
+      )}
+      {decisionable && (
+        <Stack direction="row" spacing={1} className="mt-2">
+          <Button
+            size="small"
+            variant="contained"
+            color="success"
+            disabled={!uplift.canDecide}
+            onClick={() => onDecide("approve", uplift)}
+          >
+            Approve
+          </Button>
+          <Button
+            size="small"
+            variant="contained"
+            color="error"
+            disabled={!uplift.canDecide}
+            onClick={() => onDecide("reject", uplift)}
+          >
+            Reject
+          </Button>
+          <Button
+            size="small"
+            variant="outlined"
+            disabled={!uplift.canDecide}
+            onClick={() => onDecide("request-changes", uplift)}
+          >
+            Request Changes
+          </Button>
+        </Stack>
+      )}
+    </Box>
+  );
+}
+
+export function UpliftHistoryPaper({
+  upliftRequests,
+  onDownload,
+  onDecide,
+}: {
+  upliftRequests: UpliftRequest[];
+  onDownload: (uplift: UpliftRequest) => void;
+  onDecide: (type: UpliftActionType, uplift: UpliftRequest) => void;
+}) {
+  return (
+    <Paper variant="outlined" className="p-4">
+      <Typography variant="subtitle1" className="mb-3 font-semibold">
+        NTE Uplift History ({upliftRequests.length})
+      </Typography>
+      {upliftRequests.length === 0 ? (
+        <Typography color="text.secondary">No uplift requests on this PO.</Typography>
+      ) : (
+        <Stack spacing={2}>
+          {upliftRequests.map((uplift) => (
+            <UpliftHistoryItem
+              key={String(uplift.id)}
+              uplift={uplift}
+              onDownload={onDownload}
+              onDecide={onDecide}
+            />
+          ))}
+        </Stack>
+      )}
+    </Paper>
+  );
+}
+
+export function UpliftDecisionDialog({
+  action,
+  note,
+  noteRequired,
+  decisionPending,
+  onNoteChange,
+  onClose,
+  onConfirm,
+}: {
+  action: VendorPoUpliftDecision | null;
+  note: string;
+  noteRequired: boolean;
+  decisionPending: boolean;
+  onNoteChange: (value: string) => void;
+  onClose: () => void;
+  onConfirm: () => void;
+}) {
+  return (
+    <Dialog open={Boolean(action)} onClose={onClose}>
+      <DialogTitle>
+        {action?.type === "approve"
+          ? "Approve Uplift"
+          : action?.type === "reject"
+            ? "Reject Uplift"
+            : "Request Changes"}
+      </DialogTitle>
+      <DialogContent>
+        <TextField
+          fullWidth
+          multiline
+          minRows={2}
+          className="mt-2"
+          label={noteRequired ? "Note (required)" : "Optional note"}
+          value={note}
+          required={noteRequired}
+          onChange={(e) => onNoteChange(e.target.value)}
+        />
+      </DialogContent>
+      <DialogActions>
+        <Button onClick={onClose}>Cancel</Button>
+        <Button
+          variant="contained"
+          color={action?.type === "approve" ? "success" : "primary"}
+          disabled={noteRequired ? !note.trim() || decisionPending : decisionPending}
+          onClick={onConfirm}
+        >
+          Confirm
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+}

src/app/(protected)/workorders/[id].tsx

@@ -1,39 +1,21 @@
-import { useState } from "react";
-import { useNavigate, useParams } from "react-router";
+import { useParams } from "react-router";
 import { Alert, Box, CircularProgress } from "@mui/material";
 import { DispatchCreateModal } from "./_components/dispatch-create-modal";
 import { DispatchDetailModal } from "./_components/dispatch-detail-modal";
-import { VendorEditorDialog } from "./_components/vendor-editor-dialog";
-import { useVendorEditor } from "./_components/use-vendor-editor";
-import { WorkOrderActivity } from "./_components/work-order-activity";
-import {
-  DispatchAccordion,
-  WorkOrderDetailsSection,
-  WorkOrderHeader,
-  WorkOrderSummaryAccordions,
-} from "./_components/work-order-view-sections";
-import { useWorkOrderDetail } from "@/domain/work-orders/use-cases/use-work-order-detail";
-import {
-  useChangeWorkOrderAssignment,
-  useChangeWorkOrderStatus,
-} from "@/domain/work-orders/use-cases/use-work-order-mutations";
-import { useWorkOrderUsers } from "@/domain/work-orders/use-cases/use-work-orders-list";
+import { WorkOrderActivityPanel } from "./_components/view/work-order-activity-panel";
+import { WorkOrderDispatchesAccordion } from "./_components/view/work-order-dispatches-accordion";
+import { WorkOrderVendorEditorDialog } from "./_components/view/work-order-vendor-editor-dialog";
+import { WorkOrderViewAccordions } from "./_components/view/work-order-view-accordions";
+import { WorkOrderViewDetails } from "./_components/view/work-order-view-details";
+import { WorkOrderViewHeader } from "./_components/view/work-order-view-header";
+import { useWorkOrderViewPage } from "./_hooks/use-work-order-view-page";
 
 export default function WorkOrderViewPage() {
   const { id } = useParams();
-  const navigate = useNavigate();
   const workOrderId = id ?? "";
+  const view = useWorkOrderViewPage(workOrderId);
 
-  const { data: wo, isLoading, error, refetch } = useWorkOrderDetail(workOrderId);
-  const { data: users = [] } = useWorkOrderUsers();
-  const statusMutation = useChangeWorkOrderStatus(workOrderId);
-  const assignmentMutation = useChangeWorkOrderAssignment(workOrderId);
-  const vendorEditor = useVendorEditor({ workOrderId, onSaved: () => void refetch() });
-
-  const [dispatchOpen, setDispatchOpen] = useState(false);
-  const [dispatchDetailId, setDispatchDetailId] = useState<string | number | null>(null);
-
-  if (isLoading) {
+  if (view.isLoading) {
     return (
       <Box className="flex justify-center p-12">
         <CircularProgress />
@@ -41,11 +23,11 @@ export default function WorkOrderViewPage() {
     );
   }
 
-  if (error || !wo) {
+  if (view.error || !view.wo) {
     return (
       <Box className="p-4">
         <Alert severity="error">
-          {error instanceof Error ? error.message : "Work order not found."}
+          {view.error instanceof Error ? view.error.message : "Work order not found."}
         </Alert>
       </Box>
     );
@@ -53,56 +35,67 @@ export default function WorkOrderViewPage() {
 
   return (
     <Box className="flex flex-col gap-4 p-4">
-      <WorkOrderHeader
-        wo={wo}
-        onSelectStatus={(status) => statusMutation.mutate(status)}
-        onDispatch={() => setDispatchOpen(true)}
-        onEdit={() => navigate(`/workorders/edit/${id}`)}
-        onBack={() => navigate("/workorders")}
-      />
-      <WorkOrderDetailsSection
-        wo={wo}
-        users={users}
-        onAssign={(payload) => assignmentMutation.mutate(payload)}
-      />
-      <WorkOrderSummaryAccordions wo={wo} />
-      <DispatchAccordion
-        wo={wo}
-        onEditVendor={(event, vendorId, vendorName) =>
-          void vendorEditor.open(event, vendorId, vendorName)
-        }
-        onViewDispatch={setDispatchDetailId}
-      />
-      <WorkOrderActivity
+      <WorkOrderViewHeader
+        wo={view.wo}
         workOrderId={workOrderId}
-        comments={wo.comments ?? []}
-        auditLog={wo.auditLog ?? []}
+        statusAnchor={view.statusAnchor}
+        onStatusAnchorChange={view.setStatusAnchor}
+        onStatusChange={(status) => view.statusMutation.mutate(status)}
+        onOpenDispatch={() => view.setDispatchOpen(true)}
       />
-      {dispatchOpen && (
+
+      <WorkOrderViewDetails
+        wo={view.wo}
+        users={view.users}
+        assignAnchor={view.assignAnchor}
+        onAssignAnchorChange={view.setAssignAnchor}
+        onAssign={(userId, userName) => view.assignmentMutation.mutate({ userId, userName })}
+        onUnassign={() => view.assignmentMutation.mutate({ userId: "", userName: "" })}
+      />
+
+      <WorkOrderViewAccordions wo={view.wo} />
+
+      <WorkOrderDispatchesAccordion
+        wo={view.wo}
+        onOpenDispatchDetail={view.setDispatchDetailId}
+        onOpenVendorEditor={view.openVendorEditor}
+      />
+
+      <WorkOrderActivityPanel
+        customerComments={view.customerComments}
+        internalComments={view.internalComments}
+        auditLog={view.auditLog}
+        mentionUsers={view.mentionUsers}
+        isSubmitting={view.commentMutation.isPending}
+        onSubmitComment={view.submitComment}
+      />
+
+      {view.dispatchOpen && (
         <DispatchCreateModal
-          workOrder={wo}
-          onClose={() => setDispatchOpen(false)}
-          onDispatched={() => void refetch()}
+          workOrder={view.wo}
+          onClose={() => view.setDispatchOpen(false)}
+          onDispatched={() => void view.refetch()}
         />
       )}
-      {dispatchDetailId != null && (
+      {view.dispatchDetailId != null && (
         <DispatchDetailModal
-          dispatchId={dispatchDetailId}
+          dispatchId={view.dispatchDetailId}
           workOrderId={workOrderId}
-          onClose={() => setDispatchDetailId(null)}
-          onUpdated={() => void refetch()}
+          onClose={() => view.setDispatchDetailId(null)}
+          onUpdated={() => void view.refetch()}
         />
       )}
-      <VendorEditorDialog
-        editor={vendorEditor.editor}
-        loading={vendorEditor.loading}
-        error={vendorEditor.error}
-        isPending={vendorEditor.isPending}
-        phoneInvalid={vendorEditor.phoneInvalid}
-        isValid={vendorEditor.isValid}
-        onClose={vendorEditor.close}
-        onSave={vendorEditor.save}
-        onFieldChange={vendorEditor.updateField}
+
+      <WorkOrderVendorEditorDialog
+        editor={view.vendorEditor}
+        loading={view.vendorEditorLoading}
+        error={view.vendorEditorError}
+        isSaving={view.vendorMutation.isPending}
+        onClose={() => {
+          if (!view.vendorMutation.isPending) view.setVendorEditor(null);
+        }}
+        onSave={view.saveVendorEditor}
+        onEditorChange={view.setVendorEditor}
       />
     </Box>
   );

src/app/(protected)/workorders/_components/comp-doc/comp-doc-details-section.tsx

@@ -0,0 +1,75 @@
+import { Building2, MapPin, Users, Wrench } from "lucide-react";
+import type { CompDocSiteInfo } from "@/domain/work-orders/types/completion-doc";
+import type { WorkOrderTableRow } from "@/domain/work-orders/types/work-order-table-row";
+import { CompDocDetailRow } from "./comp-doc-detail-row";
+import { CompDocEditableRow } from "./comp-doc-editable-row";
+
+type CompDocDetailsSectionProps = {
+  row: WorkOrderTableRow;
+  site: CompDocSiteInfo;
+  editAddress: string;
+  onAddressChange: (value: string) => void;
+  editDateCompleted: string;
+  onDateCompletedChange: (value: string) => void;
+  amazonRep: string;
+  seaRep: string;
+  isGenerated: boolean;
+};
+
+export function CompDocDetailsSection({
+  row,
+  site,
+  editAddress,
+  onAddressChange,
+  editDateCompleted,
+  onDateCompletedChange,
+  amazonRep,
+  seaRep,
+  isGenerated,
+}: CompDocDetailsSectionProps) {
+  return (
+    <div style={{ marginTop: 20 }}>
+      <div
+        style={{
+          fontFamily: "var(--font-mono)",
+          fontSize: 10,
+          fontWeight: 600,
+          letterSpacing: "0.1em",
+          textTransform: "uppercase",
+          color: "var(--muted-foreground)",
+        }}
+      >
+        Work Order Details
+      </div>
+      <div style={{ marginTop: 6 }}>
+        <CompDocDetailRow icon={Building2} label="WO #" value={`#${row.woNumber}`} />
+        <CompDocDetailRow
+          icon={MapPin}
+          label="Site Code"
+          value={`${row.site} · Amazon.com Services LLC`}
+        />
+        <CompDocEditableRow
+          label="Address"
+          value={editAddress}
+          onChange={onAddressChange}
+          placeholder={site.fullAddress !== "—" ? site.fullAddress : "Street address"}
+          disabled={isGenerated}
+        />
+        <CompDocEditableRow
+          label="Date Work Completed"
+          value={editDateCompleted}
+          onChange={onDateCompletedChange}
+          type="date"
+          disabled={isGenerated}
+        />
+        <CompDocDetailRow icon={Users} label="Amazon Representative" value={amazonRep || "—"} />
+        <CompDocDetailRow
+          icon={Wrench}
+          label="Seahaven Representative"
+          value={seaRep || "—"}
+          last
+        />
+      </div>
+    </div>
+  );
+}

src/app/(protected)/workorders/_components/comp-doc/comp-doc-dialog-footer-draft.tsx

@@ -0,0 +1,50 @@
+import { Ban, Save, Sparkles } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { COMP_DOC_FOOTER_BTN_SX } from "./comp-doc-footer-btn-sx";
+
+type CompDocDialogFooterDraftProps = {
+  onMarkNotRequired: () => void;
+  onSaveDraft: () => void;
+  onGenerate: () => void;
+};
+
+export function CompDocDialogFooterDraft({
+  onMarkNotRequired,
+  onSaveDraft,
+  onGenerate,
+}: CompDocDialogFooterDraftProps) {
+  return (
+    <>
+      <Button
+        variant="ghost"
+        size="default"
+        className="gap-1.5 whitespace-nowrap text-[12px]"
+        sx={COMP_DOC_FOOTER_BTN_SX}
+        style={{ color: "var(--muted-foreground)" }}
+        onClick={onMarkNotRequired}
+      >
+        <Ban size={14} /> Mark as not required
+      </Button>
+      <div className="flex shrink-0 items-center gap-2">
+        <Button
+          variant="outline"
+          size="default"
+          className="gap-1.5 whitespace-nowrap text-[12px]"
+          sx={COMP_DOC_FOOTER_BTN_SX}
+          onClick={onSaveDraft}
+        >
+          <Save size={14} /> Save draft
+        </Button>
+        <Button
+          size="default"
+          className="gap-1.5 whitespace-nowrap text-[12px]"
+          sx={COMP_DOC_FOOTER_BTN_SX}
+          style={{ background: "var(--color-primary)", color: "#fff" }}
+          onClick={onGenerate}
+        >
+          <Sparkles size={14} /> Generate
+        </Button>
+      </div>
+    </>
+  );
+}

src/app/(protected)/workorders/_components/comp-doc/comp-doc-dialog-footer-generated.tsx

@@ -0,0 +1,35 @@
+import { CheckCircle2, Download } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { COMP_DOC_FOOTER_BTN_SX } from "./comp-doc-footer-btn-sx";
+
+type CompDocDialogFooterGeneratedProps = {
+  generatedAt: string;
+  onDownloadPdf: () => void;
+};
+
+export function CompDocDialogFooterGenerated({
+  generatedAt,
+  onDownloadPdf,
+}: CompDocDialogFooterGeneratedProps) {
+  return (
+    <>
+      <span
+        className="inline-flex items-center gap-1.5 whitespace-nowrap"
+        style={{ fontSize: 12, color: "var(--color-success)" }}
+      >
+        <CheckCircle2 size={14} /> Generated {generatedAt}
+      </span>
+      <div className="flex shrink-0 items-center gap-2">
+        <Button
+          size="default"
+          className="gap-1.5 whitespace-nowrap text-[12px]"
+          sx={COMP_DOC_FOOTER_BTN_SX}
+          style={{ background: "var(--color-primary)", color: "#fff" }}
+          onClick={onDownloadPdf}
+        >
+          <Download size={14} /> Download PDF
+        </Button>
+      </div>
+    </>
+  );
+}

src/app/(protected)/workorders/_components/comp-doc/comp-doc-dialog-footer-not-required.tsx

@@ -0,0 +1,47 @@
+import { Ban, Sparkles, Undo2 } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { COMP_DOC_FOOTER_BTN_SX } from "./comp-doc-footer-btn-sx";
+
+type CompDocDialogFooterNotRequiredProps = {
+  onUndo: () => void;
+};
+
+export function CompDocDialogFooterNotRequired({ onUndo }: CompDocDialogFooterNotRequiredProps) {
+  return (
+    <>
+      <span
+        className="inline-flex items-center gap-1.5 whitespace-nowrap"
+        style={{ fontSize: 12, color: "var(--muted-foreground)" }}
+      >
+        <Ban size={14} style={{ color: "var(--warning)" }} /> Marked{" "}
+        <b style={{ fontWeight: 600 }}>not required</b> for this work order
+      </span>
+      <div className="flex shrink-0 items-center gap-2">
+        <Button
+          variant="outline"
+          size="default"
+          className="gap-1.5 whitespace-nowrap text-[12px]"
+          sx={COMP_DOC_FOOTER_BTN_SX}
+          onClick={onUndo}
+        >
+          <Undo2 size={14} /> Undo
+        </Button>
+        <Button
+          size="default"
+          disabled
+          title="Marked not required — undo to generate"
+          className="gap-1.5 whitespace-nowrap text-[12px]"
+          sx={COMP_DOC_FOOTER_BTN_SX}
+          style={{
+            background: "var(--color-primary)",
+            color: "#fff",
+            opacity: 0.5,
+            pointerEvents: "none",
+          }}
+        >
+          <Sparkles size={14} /> Generate
+        </Button>
+      </div>
+    </>
+  );
+}

src/app/(protected)/workorders/_components/comp-doc/comp-doc-draft-toast.tsx

@@ -0,0 +1,29 @@
+import { CheckCircle2 } from "lucide-react";
+import { toast } from "react-toastify";
+
+export function showCompDocDraftSavedToast() {
+  toast(
+    <div
+      className="flex items-center gap-2"
+      style={{
+        background: "var(--foreground)",
+        color: "#fff",
+        padding: "10px 18px",
+        borderRadius: 9999,
+        fontSize: 13,
+        fontWeight: 600,
+        boxShadow: "0 10px 30px -10px rgba(0,0,0,.45)",
+      }}
+    >
+      <CheckCircle2 size={16} /> Draft saved
+    </div>,
+    {
+      position: "bottom-center",
+      autoClose: 3000,
+      hideProgressBar: true,
+      closeButton: false,
+      icon: false,
+      className: "!min-h-0 !bg-transparent !p-0 !shadow-none",
+    },
+  );
+}

src/app/(protected)/workorders/_components/comp-doc/comp-doc-editable-row.tsx

@@ -0,0 +1,54 @@
+import type { CSSProperties } from "react";
+
+const COMP_DOC_INPUT_CLS = "w-full rounded-md px-2.5 py-1.5 focus:outline-none focus:ring-1";
+
+const COMP_DOC_INPUT_STYLE: CSSProperties = {
+  fontSize: 13,
+  border: "1px solid var(--color-border)",
+  color: "var(--color-text-primary)",
+  background: "var(--color-bg-surface)",
+};
+
+const COMP_DOC_INPUT_DISABLED_STYLE: CSSProperties = {
+  opacity: 0.6,
+  cursor: "default",
+  pointerEvents: "none",
+};
+
+type CompDocEditableRowProps = {
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+  type?: string;
+  placeholder?: string;
+  disabled?: boolean;
+};
+
+export function CompDocEditableRow({
+  label,
+  value,
+  onChange,
+  type = "text",
+  placeholder = "",
+  disabled = false,
+}: CompDocEditableRowProps) {
+  return (
+    <div style={{ padding: "8px 0", borderBottom: "1px solid var(--color-border)" }}>
+      <div style={{ fontSize: 11.5, color: "var(--muted-foreground)", marginBottom: 4 }}>
+        {label}
+      </div>
+      <input
+        type={type}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        readOnly={disabled}
+        placeholder={placeholder}
+        className={COMP_DOC_INPUT_CLS}
+        style={{
+          ...COMP_DOC_INPUT_STYLE,
+          ...(disabled ? COMP_DOC_INPUT_DISABLED_STYLE : {}),
+        }}
+      />
+    </div>
+  );
+}

src/app/(protected)/workorders/_components/comp-doc/comp-doc-footer-btn-sx.ts

@@ -0,0 +1,8 @@
+export const COMP_DOC_FOOTER_BTN_SX = {
+  minHeight: 28,
+  height: 28,
+  fontSize: 12,
+  px: 1.25,
+  py: 0.5,
+  gap: 0.75,
+} as const;

src/app/(protected)/workorders/_components/comp-doc/comp-doc-not-required-stamp.tsx

@@ -0,0 +1,25 @@
+import { Ban } from "lucide-react";
+
+export function CompDocNotRequiredStamp() {
+  return (
+    <div className="pointer-events-none absolute inset-0 flex items-start justify-center">
+      <div
+        className="inline-flex items-center gap-2"
+        style={{
+          marginTop: "30%",
+          transform: "rotate(-15deg)",
+          border: "3px solid var(--warning)",
+          color: "var(--warning)",
+          borderRadius: 8,
+          padding: "8px 18px",
+          fontWeight: 800,
+          fontSize: 22,
+          letterSpacing: "0.06em",
+          background: "rgba(255,255,255,0.65)",
+        }}
+      >
+        <Ban size={20} /> NOT REQUIRED
+      </div>
+    </div>
+  );
+}

src/app/(protected)/workorders/_components/comp-doc/comp-doc-notes-field.tsx

@@ -0,0 +1,50 @@
+type CompDocNotesFieldProps = {
+  notes: string;
+  onNotesChange: (value: string) => void;
+  isGenerated: boolean;
+};
+
+export function CompDocNotesField({ notes, onNotesChange, isGenerated }: CompDocNotesFieldProps) {
+  return (
+    <div style={{ marginTop: 18 }}>
+      <label
+        style={{
+          fontSize: 13,
+          fontWeight: 600,
+          color: "var(--color-text-primary)",
+        }}
+      >
+        PM Comments{" "}
+        <span style={{ fontWeight: 400, color: "var(--muted-foreground)" }}>
+          — optional, included in the document
+        </span>
+      </label>
+      <textarea
+        value={notes}
+        onChange={(e) => onNotesChange(e.target.value)}
+        readOnly={isGenerated}
+        rows={3}
+        placeholder="Add findings, parts used, access notes, or anything the site POC should see…"
+        className="mt-2 w-full resize-none"
+        style={{
+          fontSize: 13,
+          fontFamily: "var(--font-sans)",
+          color: "var(--color-text-primary)",
+          background: "var(--color-bg-surface)",
+          border: "1px solid var(--color-border)",
+          borderRadius: 8,
+          padding: "10px 12px",
+          lineHeight: 1.5,
+          outline: "none",
+          ...(isGenerated
+            ? {
+                opacity: 0.6,
+                cursor: "default",
+                pointerEvents: "none" as const,
+              }
+            : {}),
+        }}
+      />
+    </div>
+  );
+}

src/app/(protected)/workorders/_components/comp-doc/comp-doc-preview-badge.tsx

@@ -0,0 +1,32 @@
+import { CheckCircle2, FileText } from "lucide-react";
+
+type CompDocPreviewBadgeProps = {
+  isGenerated: boolean;
+};
+
+export function CompDocPreviewBadge({ isGenerated }: CompDocPreviewBadgeProps) {
+  return (
+    <div className="flex shrink-0 items-center justify-center" style={{ padding: "12px 0" }}>
+      <span
+        className="inline-flex items-center gap-1.5"
+        style={{
+          height: 28,
+          padding: "0 12px",
+          borderRadius: 9999,
+          background: "var(--color-bg-surface)",
+          border: "1px solid var(--color-border)",
+          fontSize: 12,
+          fontWeight: 500,
+          color: "var(--muted-foreground)",
+        }}
+      >
+        {isGenerated ? (
+          <CheckCircle2 size={13} style={{ color: "var(--color-success)" }} />
+        ) : (
+          <FileText size={13} />
+        )}
+        {isGenerated ? "Generated document" : "Preview — not yet generated"}
+      </span>
+    </div>
+  );
+}

src/app/(protected)/workorders/_components/comp-doc/comp-doc-preview-header.tsx

@@ -0,0 +1,36 @@
+import { Building2, Mail, MapPin, Phone, Printer } from "lucide-react";
+import { SEAHAVEN_HEADER } from "@/domain/work-orders/utils/completion-doc-html";
+import { CompDocCoLine } from "./comp-doc-co-line";
+
+export function CompDocPreviewHeader() {
+  return (
+    <>
+      <div
+        className="flex flex-wrap items-start justify-between gap-y-3"
+        style={{ padding: "20px 0 12px" }}
+      >
+        <div className="flex items-center">
+          <img
+            src="/seahaven-logo.svg"
+            alt="Seahaven Industries"
+            style={{ height: 34, width: "auto", display: "block" }}
+          />
+        </div>
+        <div className="space-y-1">
+          <CompDocCoLine icon={Building2} text={SEAHAVEN_HEADER.name} bold />
+          <CompDocCoLine icon={MapPin} text={SEAHAVEN_HEADER.address} />
+          <CompDocCoLine icon={Phone} text={SEAHAVEN_HEADER.phone} />
+          <CompDocCoLine icon={Printer} text={SEAHAVEN_HEADER.fax} />
+          <CompDocCoLine icon={Mail} text={SEAHAVEN_HEADER.email} />
+        </div>
+      </div>
+      <div
+        style={{
+          height: 3,
+          borderRadius: 2,
+          background: "linear-gradient(90deg,#27AAE1,#1C75BC)",
+        }}
+      />
+    </>
+  );
+}

src/app/(protected)/workorders/_components/comp-doc/comp-doc-preview-procedure.tsx

@@ -0,0 +1,87 @@
+import { Text } from "@/components/ui/text";
+import type { WorkOrderTableRow } from "@/domain/work-orders/types/work-order-table-row";
+import { procedureFor, SAFETY_BULLETS } from "@/domain/work-orders/utils/completion-doc-procedures";
+import { CompDocProcedureList } from "./comp-doc-procedure-list";
+
+type CompDocPreviewProcedureProps = {
+  row: WorkOrderTableRow;
+  notes: string;
+};
+
+export function CompDocPreviewProcedure({ row, notes }: CompDocPreviewProcedureProps) {
+  const proc = procedureFor(row.pm);
+
+  return (
+    <>
+      <ul style={{ listStyle: "disc", paddingLeft: 18, margin: "8px 0 0" }}>
+        {SAFETY_BULLETS.map((b, i) => (
+          <li
+            key={i}
+            style={{
+              fontSize: 12.5,
+              lineHeight: 1.5,
+              margin: "5px 0",
+              color: "#161E38",
+            }}
+          >
+            {b}
+          </li>
+        ))}
+      </ul>
+
+      <Text
+        as="h3"
+        variant="heading"
+        sx={{
+          fontSize: 13,
+          fontWeight: 700,
+          color: "#161E38",
+          margin: "16px 0 4px",
+        }}
+      >
+        {proc.heading}
+      </Text>
+      <Text
+        variant="body"
+        sx={{
+          fontSize: 12.5,
+          lineHeight: 1.5,
+          color: "#58595B",
+          margin: "0 0 8px",
+        }}
+      >
+        {proc.intro}
+      </Text>
+      <CompDocProcedureList proc={proc} />
+
+      {notes.length > 0 && (
+        <>
+          <Text
+            as="h3"
+            variant="heading"
+            sx={{
+              fontSize: 13,
+              fontWeight: 700,
+              color: "#161E38",
+              margin: "16px 0 4px",
+            }}
+          >
+            PM Comments
+          </Text>
+          <Text
+            variant="body"
+            sx={{
+              fontSize: 12.5,
+              lineHeight: 1.5,
+              color: "#161E38",
+              margin: 0,
+              whiteSpace: "pre-wrap",
+            }}
+          >
+            {notes}
+          </Text>
+        </>
+      )}
+    </>
+  );
+}

src/app/(protected)/workorders/_components/comp-doc/comp-doc-preview-summary.tsx

@@ -0,0 +1,96 @@
+import { CheckCircle2 } from "lucide-react";
+import { Text } from "@/components/ui/text";
+import type { CompDocSiteInfo } from "@/domain/work-orders/types/completion-doc";
+import type { WorkOrderTableRow } from "@/domain/work-orders/types/work-order-table-row";
+import { serviceTitle } from "@/domain/work-orders/utils/completion-doc-service-title";
+
+type CompDocPreviewSummaryProps = {
+  row: WorkOrderTableRow;
+  site: CompDocSiteInfo;
+  generatedAt: string;
+  isGenerated: boolean;
+};
+
+export function CompDocPreviewSummary({
+  row,
+  site,
+  generatedAt,
+  isGenerated,
+}: CompDocPreviewSummaryProps) {
+  return (
+    <>
+      {isGenerated && (
+        <div
+          className="inline-flex items-center gap-1.5"
+          style={{
+            marginTop: 16,
+            padding: "4px 10px",
+            borderRadius: 9999,
+            background: "var(--doc-yes-bg)",
+            color: "var(--color-success)",
+            fontSize: 11.5,
+            fontWeight: 600,
+          }}
+        >
+          <CheckCircle2 size={13} /> Generated · {generatedAt} · v1
+        </div>
+      )}
+
+      <Text
+        as="h2"
+        variant="heading"
+        sx={{
+          fontFamily: "var(--font-sans)",
+          fontSize: 13,
+          fontWeight: 700,
+          letterSpacing: "0.02em",
+          color: "#161E38",
+          margin: "16px 0 4px",
+        }}
+      >
+        {serviceTitle(row).toUpperCase()}
+      </Text>
+      <Text
+        family="mono"
+        variant="body"
+        sx={{
+          fontSize: 12.5,
+          fontWeight: 600,
+          color: "#1C75BC",
+          margin: "2px 0",
+        }}
+      >
+        WO# {row.woNumber}
+      </Text>
+
+      <div style={{ marginTop: 14 }}>
+        <Text
+          variant="body"
+          sx={{
+            fontSize: 13,
+            fontWeight: 600,
+            color: "#161E38",
+            margin: "2px 0",
+          }}
+        >
+          Site ID — {row.site}
+        </Text>
+        <Text variant="body" sx={{ fontSize: 13, color: "#161E38", margin: "2px 0" }}>
+          Amazon.com Services LLC {row.site}
+        </Text>
+        <Text variant="body" sx={{ fontSize: 13, color: "#58595B", margin: "2px 0" }}>
+          {site.street},
+        </Text>
+        <Text variant="body" sx={{ fontSize: 13, color: "#58595B", margin: "2px 0" }}>
+          {site.label}
+        </Text>
+      </div>
+
+      <Text variant="body" sx={{ fontSize: 13, color: "#161E38", margin: "14px 0 6px" }}>
+        <span style={{ fontWeight: 700 }}>Vendor / Technician:&nbsp;</span>
+        {row.tech || "—"}
+        {row.company ? ` · ${row.company}` : ""}
+      </Text>
+    </>
+  );
+}

src/app/(protected)/workorders/_components/comp-doc/comp-doc-status-card.tsx

@@ -0,0 +1,61 @@
+import type { DocState } from "@/domain/work-orders/types/completion-doc";
+import {
+  DOC_STATE_CFG,
+  docStatusCardDescription,
+} from "@/domain/work-orders/utils/completion-doc-state";
+
+type CompDocStatusCardProps = {
+  docState: DocState;
+  generatedAt: string;
+};
+
+export function CompDocStatusCard({ docState, generatedAt }: CompDocStatusCardProps) {
+  const cfg = DOC_STATE_CFG[docState];
+  const StateIcon = cfg.icon;
+
+  return (
+    <div
+      className="flex items-start gap-3"
+      style={{
+        padding: 14,
+        borderRadius: 10,
+        background: cfg.cardBg,
+        border: `1px solid ${cfg.cardBorder}`,
+      }}
+    >
+      <div
+        className="flex shrink-0 items-center justify-center"
+        style={{
+          width: 34,
+          height: 34,
+          borderRadius: 8,
+          background: cfg.cardIconBg,
+          border: `1px solid ${cfg.cardBorder}`,
+        }}
+      >
+        <StateIcon size={17} style={{ color: cfg.iconColor }} />
+      </div>
+      <div className="min-w-0">
+        <div
+          style={{
+            fontSize: 13.5,
+            fontWeight: 600,
+            color: "var(--color-text-primary)",
+          }}
+        >
+          {cfg.cardTitle}
+        </div>
+        <div
+          style={{
+            fontSize: 12.5,
+            lineHeight: 1.45,
+            color: "var(--muted-foreground)",
+            marginTop: 3,
+          }}
+        >
+          {docStatusCardDescription(docState, generatedAt)}
+        </div>
+      </div>
+    </div>
+  );
+}

src/app/(protected)/workorders/_components/detail/use-slide-over-media-state.ts

@@ -56,6 +56,8 @@ export function useSlideOverMediaState({
     deleteMediaMutation.isPending ||
     categorizeMediaMutation.isPending;
 
+  const workOrderVersion = detailForRow?.info.rowVersion?.trim() ?? "";
+
   const uploadMediaRequests = (requests: MediaUploadRequest[]) => {
     startUploads(requests);
   };
@@ -72,7 +74,8 @@ export function useSlideOverMediaState({
   };
 
   const categorizeMedia = (mediaId: string, category: UploadableMediaCategory) => {
-    categorizeMediaMutation.mutate({ mediaId, category });
+    if (!workOrderVersion) return;
+    categorizeMediaMutation.mutate({ mediaId, category, workOrderVersion });
   };
 
   const removeMedia = (id: string) => {
@@ -80,7 +83,8 @@ export function useSlideOverMediaState({
       removeLocal(id);
       return;
     }
-    deleteMediaMutation.mutate(id);
+    if (!workOrderVersion) return;
+    deleteMediaMutation.mutate({ mediaId: id, workOrderVersion });
   };
 
   return {

src/app/(protected)/workorders/_components/detail/work-order-slide-over-tabs.tsx

@@ -147,7 +147,7 @@ export function WorkOrderSlideOverTabs({
             onUpload={(files) => {
               void state.uploadExtraFiles(files);
             }}
-            onRemove={(id) => state.deleteMediaMutation.mutate(id)}
+            onRemove={state.removeMedia}
           />
         </WorkOrderSlideOverTabPanel>
       )}

src/app/(protected)/workorders/_components/dispatch/dispatch-detail/dispatch-uplifts-section.tsx

@@ -1,82 +1,178 @@
 import { Box, Button, Chip, Stack, Tooltip, Typography } from "@mui/material";
 import type { UpliftRequest } from "@/domain/uplifts/types/uplift";
+import { upliftsApi } from "@/domain/uplifts/api/uplifts-api";
 import { formatDateTime } from "@/lib/time-utils";
+import { toast } from "react-toastify";
+
+type UpliftAction = "approve" | "reject" | "request-changes";
 
 type DispatchUpliftsSectionProps = {
   uplifts: UpliftRequest[];
   isLocked: boolean;
   onApprove: (uplift: UpliftRequest) => void;
-  onDeny: (uplift: UpliftRequest) => void;
+  onReject: (uplift: UpliftRequest) => void;
+  onRequestChanges: (uplift: UpliftRequest) => void;
 };
 
+const ACTION_LABELS: Record<Exclude<UpliftAction, "approve">, string> = {
+  reject: "Reject",
+  "request-changes": "Request Changes",
+};
+
+function actionColor(action: UpliftAction): "success" | "error" | "primary" {
+  if (action === "approve") return "success";
+  if (action === "reject") return "error";
+  return "primary";
+}
+
+function actionVariant(action: UpliftAction): "contained" | "outlined" {
+  return action === "request-changes" ? "outlined" : "contained";
+}
+
 type UpliftCardProps = Omit<DispatchUpliftsSectionProps, "uplifts"> & {
   uplift: UpliftRequest;
 };
 
-function UpliftCard({ uplift, isLocked, onApprove, onDeny }: UpliftCardProps) {
-  const canDecide = uplift.canDecide && uplift.status === "Pending" && !isLocked;
+type UpliftCardActionsProps = Pick<
+  UpliftCardProps,
+  "isLocked" | "onApprove" | "onReject" | "onRequestChanges"
+> & {
+  uplift: UpliftRequest;
+};
 
+function downloadUpliftEvidence(uplift: UpliftRequest) {
+  return upliftsApi
+    .downloadEvidence(uplift.id, uplift.evidenceFileName || "uplift-evidence")
+    .catch((err: unknown) => {
+      toast.error(err instanceof Error ? err.message : "Unable to download evidence.");
+    });
+}
+
+function UpliftCardHeader({ uplift }: { uplift: UpliftRequest }) {
+  const evidenceDocumentId = uplift.evidenceDocumentId;
   return (
-    <Box className="rounded border border-border p-3">
+    <>
       <Stack direction="row" spacing={1} sx={{ alignItems: "center", flexWrap: "wrap" }}>
         <Chip label={uplift.status} size="small" />
         {uplift.requiredTier === 2 && (
           <Typography variant="caption">Tier 2 · Manager approval</Typography>
         )}
         <Typography variant="body2">
-          ${Number(uplift.currentNTE ?? 0).toFixed(2)} → ${Number(uplift.requestedNTE).toFixed(2)}{" "}
-          (+${Number(uplift.delta).toFixed(2)})
+          ${Number(uplift.currentNTE ?? 0).toFixed(2)} → ${Number(uplift.requestedNTE).toFixed(2)}
         </Typography>
       </Stack>
+      {Boolean(uplift.expiresAt) && (
+        <Typography variant="caption" color="text.secondary" className="mt-1 block">
+          Expires {formatDateTime(uplift.expiresAt)}
+        </Typography>
+      )}
       {Boolean(uplift.vendorReason) && (
         <Typography variant="body2" className="mt-1">
           <strong>Reason:</strong> {uplift.vendorReason}
         </Typography>
       )}
+      {evidenceDocumentId != null && (
+        <Stack direction="row" spacing={1} sx={{ alignItems: "center" }} className="mt-1">
+          <Typography variant="body2">
+            <strong>Evidence:</strong>{" "}
+            {uplift.evidenceFileName || `Document #${evidenceDocumentId}`}
+          </Typography>
+          <Button size="small" variant="text" onClick={() => void downloadUpliftEvidence(uplift)}>
+            Download
+          </Button>
+        </Stack>
+      )}
+      {uplift.notificationStatus === "Error" && Boolean(uplift.notificationError) && (
+        <Typography variant="body2" color="error" className="mt-1">
+          Notification error: {uplift.notificationError}
+        </Typography>
+      )}
       {Boolean(uplift.requestedByVendorName || uplift.requestedAt) && (
         <Typography variant="body2" color="text.secondary" className="mt-1">
           Requested by {uplift.requestedByVendorName || "vendor"}
           {uplift.requestedAt ? ` · ${formatDateTime(uplift.requestedAt)}` : ""}
         </Typography>
       )}
-      {uplift.status !== "Pending" &&
-        Boolean(uplift.decidedByName || uplift.decidedAt || uplift.decisionNote) && (
-          <Box className="mt-1">
-            {Boolean(uplift.decidedByName || uplift.decidedAt) && (
-              <Typography variant="body2" color="text.secondary">
-                {uplift.status} by {uplift.decidedByName || "—"}
-                {uplift.decidedAt ? ` · ${formatDateTime(uplift.decidedAt)}` : ""}
-              </Typography>
-            )}
-            {Boolean(uplift.decisionNote) && (
-              <Typography variant="body2" className="mt-0.5">
-                <strong>Note:</strong> {uplift.decisionNote}
-              </Typography>
-            )}
-          </Box>
-        )}
-      {uplift.status === "Pending" && (
-        <Stack direction="row" spacing={1} className="mt-2">
-          {(["approve", "deny"] as const).map((action) => (
-            <Tooltip
-              key={action}
-              title={!canDecide ? `Requires Tier ${uplift.requiredTier} role` : ""}
-            >
-              <span>
-                <Button
-                  size="small"
-                  color={action === "approve" ? "success" : "error"}
-                  variant="contained"
-                  disabled={!canDecide}
-                  onClick={() => (action === "approve" ? onApprove(uplift) : onDeny(uplift))}
-                >
-                  {action === "approve" ? "Approve" : "Deny"}
-                </Button>
-              </span>
-            </Tooltip>
-          ))}
-        </Stack>
+    </>
+  );
+}
+
+function UpliftCardDecisionSummary({ uplift }: { uplift: UpliftRequest }) {
+  if (uplift.status === "Pending") return null;
+  if (!uplift.decidedByName && !uplift.decidedAt && !uplift.decisionNote) return null;
+  return (
+    <Box className="mt-1">
+      {Boolean(uplift.decidedByName || uplift.decidedAt) && (
+        <Typography variant="body2" color="text.secondary">
+          {uplift.status} by {uplift.decidedByName || "—"}
+          {uplift.decidedAt ? ` · ${formatDateTime(uplift.decidedAt)}` : ""}
+        </Typography>
       )}
+      {Boolean(uplift.decisionNote) && (
+        <Typography variant="body2" className="mt-0.5">
+          <strong>Note:</strong> {uplift.decisionNote}
+        </Typography>
+      )}
+    </Box>
+  );
+}
+
+function UpliftCardActions({
+  uplift,
+  isLocked,
+  onApprove,
+  onReject,
+  onRequestChanges,
+}: UpliftCardActionsProps) {
+  if (uplift.status !== "Pending") return null;
+  const canDecide = uplift.canDecide && !isLocked;
+  const decisionActions: Exclude<UpliftAction, "approve">[] = ["reject", "request-changes"];
+  return (
+    <Stack direction="row" spacing={1} className="mt-2">
+      <Tooltip title={!canDecide ? `Requires Tier ${uplift.requiredTier} role` : ""}>
+        <span>
+          <Button
+            size="small"
+            color="success"
+            variant="contained"
+            disabled={!canDecide}
+            onClick={() => onApprove(uplift)}
+          >
+            Approve
+          </Button>
+        </span>
+      </Tooltip>
+      {decisionActions.map((action) => (
+        <Tooltip key={action} title={!canDecide ? `Requires Tier ${uplift.requiredTier} role` : ""}>
+          <span>
+            <Button
+              size="small"
+              color={actionColor(action)}
+              variant={actionVariant(action)}
+              disabled={!canDecide}
+              onClick={() => (action === "reject" ? onReject(uplift) : onRequestChanges(uplift))}
+            >
+              {ACTION_LABELS[action]}
+            </Button>
+          </span>
+        </Tooltip>
+      ))}
+    </Stack>
+  );
+}
+
+function UpliftCard({ uplift, isLocked, onApprove, onReject, onRequestChanges }: UpliftCardProps) {
+  return (
+    <Box className="rounded border border-border p-3">
+      <UpliftCardHeader uplift={uplift} />
+      <UpliftCardDecisionSummary uplift={uplift} />
+      <UpliftCardActions
+        uplift={uplift}
+        isLocked={isLocked}
+        onApprove={onApprove}
+        onReject={onReject}
+        onRequestChanges={onRequestChanges}
+      />
     </Box>
   );
 }
@@ -85,7 +181,8 @@ export function DispatchUpliftsSection({
   uplifts,
   isLocked,
   onApprove,
-  onDeny,
+  onReject,
+  onRequestChanges,
 }: DispatchUpliftsSectionProps) {
   return (
     <Box>
@@ -102,7 +199,8 @@ export function DispatchUpliftsSection({
               uplift={uplift}
               isLocked={isLocked}
               onApprove={onApprove}
-              onDeny={onDeny}
+              onReject={onReject}
+              onRequestChanges={onRequestChanges}
             />
           ))}
         </Stack>

src/app/(protected)/workorders/_components/dispatch/dispatch-detail/index.tsx

@@ -99,7 +99,10 @@ export function DispatchDetailModal({
             uplifts={controller.uplifts}
             isLocked={controller.isLocked}
             onApprove={(uplift) => controller.setUpliftAction({ type: "approve", uplift })}
-            onDeny={(uplift) => controller.setUpliftAction({ type: "deny", uplift })}
+            onReject={(uplift) => controller.setUpliftAction({ type: "reject", uplift })}
+            onRequestChanges={(uplift) =>
+              controller.setUpliftAction({ type: "request-changes", uplift })
+            }
           />
 
           <DispatchVendorCommunication
@@ -151,7 +154,9 @@ export function DispatchDetailModal({
           onClose={() => controller.setUpliftAction(null)}
           onConfirm={controller.handleUpliftConfirm}
           isPending={
-            controller.approveUpliftMutation.isPending || controller.denyUpliftMutation.isPending
+            controller.approveUpliftMutation.isPending ||
+            controller.rejectUpliftMutation.isPending ||
+            controller.requestChangesUpliftMutation.isPending
           }
         />
       )}

src/app/(protected)/workorders/_components/dispatch/dispatch-detail/uplift-decision-dialog.tsx

@@ -11,7 +11,7 @@ import {
 
 type UpliftDecisionDialogProps = {
   open: boolean;
-  type: "approve" | "deny";
+  type: "approve" | "reject" | "request-changes";
   requestedNTE: number;
   currentNTE: number | null;
   onClose: () => void;
@@ -19,6 +19,13 @@ type UpliftDecisionDialogProps = {
   isPending?: boolean;
 };
 
+function titleFor(type: UpliftDecisionDialogProps["type"], requestedNTE: number): string {
+  if (type === "approve") {
+    return `Approve uplift to $${requestedNTE.toFixed(2)}?`;
+  }
+  return type === "reject" ? "Reject Uplift" : "Request Changes";
+}
+
 export function UpliftDecisionDialog({
   open,
   type,
@@ -29,6 +36,7 @@ export function UpliftDecisionDialog({
   isPending = false,
 }: UpliftDecisionDialogProps) {
   const [note, setNote] = useState("");
+  const noteRequired = type === "reject" || type === "request-changes";
 
   const handleClose = () => {
     setNote("");
@@ -36,15 +44,14 @@ export function UpliftDecisionDialog({
   };
 
   const handleConfirm = () => {
+    if (noteRequired && !note.trim()) return;
     onConfirm(note.trim());
     setNote("");
   };
 
   return (
     <Dialog open={open} onClose={handleClose}>
-      <DialogTitle>
-        {type === "approve" ? `Approve uplift to $${requestedNTE.toFixed(2)}?` : "Deny Uplift"}
-      </DialogTitle>
+      <DialogTitle>{titleFor(type, requestedNTE)}</DialogTitle>
       <DialogContent>
         {type === "approve" && (
           <Typography variant="body2" className="mt-1 mb-3">
@@ -57,7 +64,8 @@ export function UpliftDecisionDialog({
           multiline
           minRows={2}
           className="mt-2"
-          label={type === "deny" ? "Denial reason (required)" : "Optional note"}
+          label={noteRequired ? "Note (required)" : "Optional note"}
+          required={noteRequired}
           value={note}
           onChange={(event) => setNote(event.target.value)}
         />
@@ -66,8 +74,8 @@ export function UpliftDecisionDialog({
         <Button onClick={handleClose}>Cancel</Button>
         <Button
           variant="contained"
-          color={type === "approve" ? "success" : "error"}
-          disabled={type === "deny" ? !note.trim() || isPending : isPending}
+          color={type === "approve" ? "success" : "primary"}
+          disabled={noteRequired ? !note.trim() || isPending : isPending}
           onClick={handleConfirm}
         >
           Confirm

src/app/(protected)/workorders/_components/list/table/cells/comp-doc-cell.tsx

@@ -1,6 +1,7 @@
 import { Ban, FileText, Image as ImageIcon } from "lucide-react";
 import type { CompletionDocStatus } from "@/domain/work-orders/types/work-order-table-row";
 import type { WOType } from "@/domain/work-orders/types/work-order-wizard";
+import { hasCompletionDocService } from "@/domain/work-orders/utils/completion-doc-service-gate";
 
 function isMediaWO(type: WOType | ""): boolean {
   return type === "Emergency" || type === "Reactive";
@@ -9,6 +10,8 @@ function isMediaWO(type: WOType | ""): boolean {
 type CompDocCellProps = {
   status: CompletionDocStatus;
   woType: WOType | "";
+  /** Primary service (`pm`). Required before CompDoc can open. */
+  pm?: string;
   mediaCount?: number;
   /** Omit until completion-doc slice mounts CompDocDialog. */
   onOpen?: () => void;
@@ -18,6 +21,7 @@ type CompDocCellProps = {
 export function CompDocCell({
   status,
   woType,
+  pm = "",
   mediaCount = 0,
   onOpen,
   onOpenMedia,
@@ -43,6 +47,20 @@ export function CompDocCell({
     return null;
   }
 
+  if (!hasCompletionDocService(pm)) {
+    return (
+      <span
+        title="Select a service before opening the completion document"
+        className="flex w-full items-center gap-1.5 whitespace-nowrap text-xs font-semibold"
+        style={{ color: "var(--color-text-muted)", opacity: 0.65 }}
+        aria-disabled="true"
+      >
+        <FileText size={15} className="shrink-0" style={{ color: "var(--color-text-muted)" }} />
+        Select service
+      </span>
+    );
+  }
+
   const generated = status === "Yes";
   const notRequired = status === "NN";
   const color = generated ? "var(--color-success)" : "var(--color-text-muted)";

src/app/(protected)/workorders/_components/list/table/cells/resolve-technician-key.ts

@@ -0,0 +1,36 @@
+import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
+
+/**
+ * Board rows often have tech/company but no vendorId — resolve via vendors list.
+ * Prefers a stable vendor id over name+company matching.
+ */
+export function resolveTechnicianKey(
+  vendorId: string | number,
+  tech: string,
+  company: string,
+  vendors: VendorDropdownItem[],
+): string {
+  const idStr = vendorId !== "" && vendorId != null ? String(vendorId) : "";
+  if (idStr && vendors.some((vendor) => String(vendor.id) === idStr)) {
+    return idStr;
+  }
+  if (idStr && vendors.length === 0) {
+    return idStr;
+  }
+
+  const name = tech.trim();
+  if (!name) {
+    return idStr;
+  }
+
+  const byNameAndCompany =
+    vendors.find((vendor) => vendor.contactName === name && vendor.companyName === company) ??
+    vendors.find((vendor) => vendor.contactName === name);
+
+  if (byNameAndCompany) {
+    return String(byNameAndCompany.id);
+  }
+
+  // Orphan tech string used as option key when no vendor row matches (legacy board cells).
+  return idStr || name;
+}

src/app/(protected)/workorders/_components/list/table/cells/resolve-vendor-company-anchor.ts

@@ -0,0 +1,53 @@
+import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
+
+type ResolveVendorCompanyAnchorInput = {
+  company: string;
+  resolvedCompany: string;
+  selectedVendor: VendorDropdownItem | undefined;
+  vendors: VendorDropdownItem[];
+};
+
+export function resolveVendorCompanyAnchor({
+  company,
+  resolvedCompany,
+  selectedVendor,
+  vendors,
+}: ResolveVendorCompanyAnchorInput): {
+  companyName: string;
+  companyVendor: VendorDropdownItem | null;
+} {
+  const companyName = resolvedCompany || company;
+  if (!companyName) {
+    return { companyName: "", companyVendor: null };
+  }
+
+  const companyVendor =
+    selectedVendor ??
+    vendors.find((vendor) => vendor.companyName === companyName) ??
+    ({
+      id: "",
+      companyName,
+      contactName: "",
+      tradeSpecialties: "",
+      address: "",
+      distanceMiles: null,
+    } satisfies VendorDropdownItem);
+
+  return { companyName, companyVendor };
+}
+
+export function mergeVendorDropdownItems(
+  vendors: VendorDropdownItem[],
+  addedVendors: VendorDropdownItem[],
+): VendorDropdownItem[] {
+  const byId = new Map<string, VendorDropdownItem>();
+  for (const vendor of vendors) {
+    if (vendor.id === "") continue;
+    byId.set(String(vendor.id), vendor);
+  }
+  for (const vendor of addedVendors) {
+    if (vendor.id === "") continue;
+    byId.set(String(vendor.id), vendor);
+  }
+  return Array.from(byId.values());
+}

src/app/(protected)/workorders/_components/list/table/cells/use-vendor-dialog-save.ts

@@ -0,0 +1,75 @@
+import { isDraftVendorId } from "@/domain/vendors/utils/draft-vendor";
+import { vendorToDropdownItem } from "@/domain/vendors/utils/vendor-to-dropdown-item";
+import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
+import type { VendorFormValues } from "@/domain/vendors/schemas/vendor-schema";
+import type { VendorPatch } from "@/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-types";
+import type { useCreateVendor } from "@/domain/vendors/use-cases/use-create-vendor";
+
+type UseVendorDialogSaveArgs = {
+  allVendors: VendorDropdownItem[];
+  pendingCreates: Record<string, VendorFormValues>;
+  selectedKey: string;
+  selectedVendor: VendorDropdownItem | undefined;
+  resolvedCompany: string;
+  anchorCompanyName: string;
+  tech: string;
+  phone: string;
+  createVendor: ReturnType<typeof useCreateVendor>;
+  onSave: (patch: VendorPatch) => void;
+  onOpenChange: (open: boolean) => void;
+  setSaveError: (error: string | null) => void;
+};
+
+export function useVendorDialogSave({
+  allVendors,
+  pendingCreates,
+  selectedKey,
+  selectedVendor,
+  resolvedCompany,
+  anchorCompanyName,
+  tech,
+  phone,
+  createVendor,
+  onSave,
+  onOpenChange,
+  setSaveError,
+}: UseVendorDialogSaveArgs) {
+  const resolveSaveVendor = () =>
+    allVendors.find((vendor) => String(vendor.id) === selectedKey) ??
+    allVendors.find(
+      (vendor) =>
+        vendor.contactName === tech &&
+        vendor.companyName === (resolvedCompany || anchorCompanyName),
+    ) ??
+    selectedVendor;
+
+  const handleSave = async () => {
+    setSaveError(null);
+    let saveVendor = resolveSaveVendor();
+    const pendingPayload = saveVendor ? pendingCreates[String(saveVendor.id)] : undefined;
+
+    if (saveVendor != null && isDraftVendorId(saveVendor.id) && pendingPayload) {
+      try {
+        const created = await createVendor.mutateAsync({
+          ...pendingPayload,
+          phone: phone.trim() || pendingPayload.phone,
+        });
+        saveVendor = vendorToDropdownItem(created);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to create technician";
+        setSaveError(message);
+        return;
+      }
+    }
+
+    onSave({
+      vendorId: saveVendor ? String(saveVendor.id) : "",
+      company: resolvedCompany || anchorCompanyName,
+      tech: saveVendor?.contactName ?? tech,
+      techPhone: phone,
+    });
+    onOpenChange(false);
+  };
+
+  return { handleSave };
+}

src/app/(protected)/workorders/_components/list/table/cells/vendor-cell.tsx

@@ -5,6 +5,7 @@ import { HoverChevron } from "./hover-chevron";
 import { VendorDialog, type VendorPatch } from "./vendor-dialog";
 
 type VendorCellProps = {
+  vendorId?: string | number;
   company: string;
   tech: string;
   techPhone?: string;
@@ -13,7 +14,15 @@ type VendorCellProps = {
   onSave: (patch: VendorPatch) => void;
 };
 
-export function VendorCell({ company, tech, techPhone, vendors, q, onSave }: VendorCellProps) {
+export function VendorCell({
+  vendorId = "",
+  company,
+  tech,
+  techPhone,
+  vendors,
+  q,
+  onSave,
+}: VendorCellProps) {
   const [open, setOpen] = useState(false);
   const hasAny = !!(tech || company);
 
@@ -46,6 +55,7 @@ export function VendorCell({ company, tech, techPhone, vendors, q, onSave }: Ven
       <VendorDialog
         open={open}
         onOpenChange={setOpen}
+        vendorId={vendorId}
         company={company}
         tech={tech}
         techPhone={techPhone}

src/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-add-technician.tsx

@@ -0,0 +1,134 @@
+import { useState } from "react";
+import { Plus } from "lucide-react";
+import {
+  DLG_INPUT_CLS,
+  DLG_INPUT_STYLE,
+} from "@/app/(protected)/workorders/_components/wizard/wizard-input-styles";
+import { Button } from "@/components/ui/button";
+import { Text } from "@/components/ui/text";
+import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
+import { vendorSchema, type VendorFormValues } from "@/domain/vendors/schemas/vendor-schema";
+import { buildTechnicianCreatePayload } from "@/domain/vendors/utils/build-technician-create-payload";
+import { createDraftVendorDropdownItem } from "@/domain/vendors/utils/draft-vendor";
+import { FieldLabel } from "@/app/(protected)/workorders/_components/list/table/cells/dialog-field-label";
+
+type VendorDialogAddTechnicianProps = {
+  companyName: string;
+  companyVendor: VendorDropdownItem;
+  onCreated: (vendor: VendorDropdownItem, phone: string, payload: VendorFormValues) => void;
+};
+
+export function VendorDialogAddTechnician({
+  companyName,
+  companyVendor,
+  onCreated,
+}: VendorDialogAddTechnicianProps) {
+  const [expanded, setExpanded] = useState(false);
+  const [contactName, setContactName] = useState("");
+  const [phone, setPhone] = useState("");
+  const [error, setError] = useState<string | null>(null);
+
+  const resetForm = () => {
+    setContactName("");
+    setPhone("");
+    setError(null);
+  };
+
+  const handleAdd = () => {
+    const payload = buildTechnicianCreatePayload({
+      companyVendor,
+      contactName,
+      phone,
+    });
+    const parsed = vendorSchema.safeParse(payload);
+    if (!parsed.success) {
+      const fieldErrors = parsed.error.flatten().fieldErrors;
+      const message =
+        fieldErrors.contactName?.[0] ??
+        fieldErrors.phone?.[0] ??
+        fieldErrors.companyName?.[0] ??
+        "Enter a valid technician name";
+      setError(message);
+      return;
+    }
+
+    setError(null);
+    const draftItem = createDraftVendorDropdownItem(parsed.data);
+    onCreated(draftItem, parsed.data.phone || phone.trim(), parsed.data);
+    resetForm();
+    setExpanded(false);
+  };
+
+  if (!expanded) {
+    return (
+      <button
+        type="button"
+        onClick={() => setExpanded(true)}
+        className="flex items-center gap-1.5 text-[12px] font-medium transition-opacity hover:opacity-80"
+        style={{ color: "var(--color-primary)" }}
+      >
+        <Plus size={12} className="shrink-0" aria-hidden />+ Add technician
+      </button>
+    );
+  }
+
+  return (
+    <div
+      className="space-y-2 rounded-lg p-3"
+      style={{
+        background: "var(--color-bg-muted)",
+        border: "1px solid var(--color-border)",
+      }}
+    >
+      <Text as="p" variant="caption" sx={{ fontSize: 12, color: "var(--muted-foreground)" }}>
+        New technician for {companyName}
+      </Text>
+      <div>
+        <FieldLabel>Technician Name</FieldLabel>
+        <input
+          autoFocus
+          value={contactName}
+          onChange={(e) => setContactName(e.target.value)}
+          placeholder="Full name"
+          className={DLG_INPUT_CLS}
+          style={DLG_INPUT_STYLE}
+        />
+      </div>
+      <div>
+        <FieldLabel>Technician Phone</FieldLabel>
+        <input
+          type="tel"
+          value={phone}
+          onChange={(e) => setPhone(e.target.value)}
+          placeholder="(000) 000-0000"
+          className={DLG_INPUT_CLS}
+          style={DLG_INPUT_STYLE}
+        />
+      </div>
+      {Boolean(error) && (
+        <Text as="p" variant="caption" sx={{ fontSize: 11.5, color: "var(--color-destructive)" }}>
+          {error}
+        </Text>
+      )}
+      <div className="flex items-center justify-end gap-2 pt-1">
+        <Button
+          variant="ghost"
+          className="min-h-0 px-2 py-1 text-[12px]"
+          onClick={() => {
+            resetForm();
+            setExpanded(false);
+          }}
+        >
+          Cancel
+        </Button>
+        <Button
+          className="min-h-0 px-3 py-1 text-[12px]"
+          disabled={contactName.trim() === ""}
+          onClick={handleAdd}
+        >
+          Add
+        </Button>
+      </div>
+    </div>
+  );
+}

src/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-body.tsx

@@ -0,0 +1,121 @@
+import { Wrench } from "lucide-react";
+import {
+  DLG_INPUT_CLS,
+  DLG_INPUT_STYLE,
+} from "@/app/(protected)/workorders/_components/wizard/wizard-input-styles";
+import { WizardFieldSelect } from "@/app/(protected)/workorders/_components/wizard/wizard-field-select";
+import { Text } from "@/components/ui/text";
+import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
+import { FieldLabel } from "@/app/(protected)/workorders/_components/list/table/cells/dialog-field-label";
+import { VendorDialogAddTechnician } from "@/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-add-technician";
+import { VendorDialogCompanyCard } from "@/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-company-card";
+import type { VendorFormValues } from "@/domain/vendors/schemas/vendor-schema";
+import type { TechnicianOption } from "@/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-options";
+
+type VendorDialogBodyProps = {
+  selectedKey: string;
+  technicianOptions: TechnicianOption[];
+  anchorCompanyName: string;
+  companyVendorForAdd: VendorDropdownItem | undefined;
+  tech: string;
+  phone: string;
+  notes: string;
+  resolvedCompany: string;
+  selectedVendor: VendorDropdownItem | undefined;
+  saveError: string | null;
+  onPick: (key: string) => void;
+  onPhoneChange: (phone: string) => void;
+  onNotesChange: (notes: string) => void;
+  onTechnicianCreated: (
+    created: VendorDropdownItem,
+    createdPhone: string,
+    payload: VendorFormValues,
+  ) => void;
+};
+
+export function VendorDialogBody({
+  selectedKey,
+  technicianOptions,
+  anchorCompanyName,
+  companyVendorForAdd,
+  tech,
+  phone,
+  notes,
+  resolvedCompany,
+  selectedVendor,
+  saveError,
+  onPick,
+  onPhoneChange,
+  onNotesChange,
+  onTechnicianCreated,
+}: VendorDialogBodyProps) {
+  return (
+    <>
+      <div className="mt-3 space-y-3">
+        <div>
+          <FieldLabel>Technician</FieldLabel>
+          <WizardFieldSelect
+            value={selectedKey}
+            placeholder="Search technician …"
+            icon={
+              <Wrench size={14} className="shrink-0" style={{ color: "var(--color-text-muted)" }} />
+            }
+            searchPlaceholder="Search technician…"
+            options={technicianOptions.map((option) => ({
+              key: option.key,
+              label: option.label,
+            }))}
+            onPick={onPick}
+          />
+          {companyVendorForAdd != null && (
+            <div className="mt-2">
+              <VendorDialogAddTechnician
+                companyName={anchorCompanyName}
+                companyVendor={companyVendorForAdd}
+                onCreated={onTechnicianCreated}
+              />
+            </div>
+          )}
+        </div>
+
+        {Boolean(tech) && (
+          <div>
+            <FieldLabel>Technician Phone</FieldLabel>
+            <input
+              type="tel"
+              value={phone}
+              onChange={(e) => onPhoneChange(e.target.value)}
+              className={DLG_INPUT_CLS}
+              style={DLG_INPUT_STYLE}
+            />
+          </div>
+        )}
+
+        {Boolean(resolvedCompany) && (
+          <div>
+            <FieldLabel>Company</FieldLabel>
+            <VendorDialogCompanyCard company={resolvedCompany} vendor={selectedVendor} />
+          </div>
+        )}
+
+        <div>
+          <FieldLabel>Notes</FieldLabel>
+          <textarea
+            value={notes}
+            onChange={(e) => onNotesChange(e.target.value)}
+            placeholder="Contact preferences, availability, etc."
+            rows={3}
+            className={`${DLG_INPUT_CLS} resize-none`}
+            style={{ ...DLG_INPUT_STYLE, fontFamily: "inherit" }}
+          />
+        </div>
+      </div>
+
+      {Boolean(saveError) && (
+        <Text as="p" variant="caption" sx={{ fontSize: 11.5, color: "var(--color-destructive)" }}>
+          {saveError}
+        </Text>
+      )}
+    </>
+  );
+}

src/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-footer.tsx

@@ -0,0 +1,29 @@
+import { Button } from "@/components/ui/button";
+
+type VendorDialogFooterProps = {
+  isPending: boolean;
+  onCancel: () => void;
+  onSave: () => void;
+};
+
+export function VendorDialogFooter({ isPending, onCancel, onSave }: VendorDialogFooterProps) {
+  return (
+    <div className="mt-4 flex items-center justify-end gap-2">
+      <Button
+        variant="ghost"
+        className="min-h-0 px-2 py-1 text-[12px]"
+        disabled={isPending}
+        onClick={onCancel}
+      >
+        Cancel
+      </Button>
+      <Button
+        className="min-h-0 px-3 py-1 text-[12px]"
+        disabled={isPending}
+        onClick={() => void onSave()}
+      >
+        {isPending ? "Saving…" : "Save"}
+      </Button>
+    </div>
+  );
+}

src/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-types.ts

@@ -0,0 +1,6 @@
+export type VendorPatch = {
+  vendorId: string;
+  company: string;
+  tech: string;
+  techPhone: string;
+};

src/app/(protected)/workorders/_components/list/table/cells/vendor-dialog.tsx

@@ -1,32 +1,30 @@
 import { useEffect, useMemo, useState, type MouseEvent } from "react";
-import { Wrench } from "lucide-react";
 import { Dialog, DialogContent, DialogTitle } from "@mui/material";
-import { WizardFieldSelect } from "@/app/(protected)/workorders/_components/wizard/wizard-field-select";
-import {
-  DLG_INPUT_CLS,
-  DLG_INPUT_STYLE,
-} from "@/app/(protected)/workorders/_components/wizard/wizard-input-styles";
-import { Button } from "@/components/ui/button";
 import { Text } from "@/components/ui/text";
 import { dialogBlurBackdropSlotProps } from "@/components/ui/dialog-blur-backdrop";
 import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
-import { FieldLabel } from "@/app/(protected)/workorders/_components/list/table/cells/dialog-field-label";
+import type { VendorFormValues } from "@/domain/vendors/schemas/vendor-schema";
+import { useCreateVendor } from "@/domain/vendors/use-cases/use-create-vendor";
 import {
   buildTechnicianOptions,
   phoneForOption,
 } from "@/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-options";
-import { VendorDialogCompanyCard } from "@/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-company-card";
+import { VendorDialogBody } from "@/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-body";
+import { VendorDialogFooter } from "@/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-footer";
+import {
+  mergeVendorDropdownItems,
+  resolveVendorCompanyAnchor,
+} from "@/app/(protected)/workorders/_components/list/table/cells/resolve-vendor-company-anchor";
+import { resolveTechnicianKey } from "@/app/(protected)/workorders/_components/list/table/cells/resolve-technician-key";
+import { useVendorDialogSave } from "@/app/(protected)/workorders/_components/list/table/cells/use-vendor-dialog-save";
+import type { VendorPatch } from "@/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-types";
 
-export type VendorPatch = {
-  vendorId: string;
-  company: string;
-  tech: string;
-  techPhone: string;
-};
+export type { VendorPatch } from "@/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-types";
 
 type VendorDialogProps = {
   open: boolean;
   onOpenChange: (open: boolean) => void;
+  vendorId?: string | number;
   company: string;
   tech: string;
   techPhone?: string;
@@ -37,43 +35,94 @@ type VendorDialogProps = {
 export function VendorDialog({
   open,
   onOpenChange,
+  vendorId = "",
   company,
   tech,
   techPhone = "",
   vendors,
   onSave,
 }: VendorDialogProps) {
+  const createVendor = useCreateVendor();
+  const [selectedKey, setSelectedKey] = useState(() =>
+    resolveTechnicianKey(vendorId, tech, company, vendors),
+  );
   const [t, setT] = useState(tech);
   const [phone, setPhone] = useState(techPhone);
   const [notes, setNotes] = useState("");
+  const [addedVendors, setAddedVendors] = useState<VendorDropdownItem[]>([]);
+  const [pendingCreates, setPendingCreates] = useState<Record<string, VendorFormValues>>({});
+  const [saveError, setSaveError] = useState<string | null>(null);
+
+  const allVendors = useMemo(
+    () => mergeVendorDropdownItems(vendors, addedVendors),
+    [vendors, addedVendors],
+  );
 
   const technicianOptions = useMemo(
-    () => buildTechnicianOptions(vendors, tech, company),
-    [vendors, tech, company],
+    () => buildTechnicianOptions(allVendors, tech, company),
+    [allVendors, tech, company],
   );
 
   useEffect(() => {
     if (open) {
+      const key = resolveTechnicianKey(vendorId, tech, company, vendors);
+      setSelectedKey(key);
       setT(tech);
-      setPhone(techPhone || phoneForOption(tech, technicianOptions));
+      setPhone(techPhone || phoneForOption(tech, buildTechnicianOptions(vendors, tech, company)));
       setNotes("");
+      setAddedVendors([]);
+      setPendingCreates({});
+      setSaveError(null);
     }
-  }, [open, tech, techPhone, technicianOptions]);
+    // Intentionally omit technicianOptions: rebuilding options after Add must not clear staged drafts.
+  }, [open, tech, techPhone, vendors, company, vendorId]);
 
-  const selected =
-    technicianOptions.find((o) => o.name === t && (!company || o.company === company)) ??
-    technicianOptions.find((o) => o.name === t || o.key === t);
-  const selectedKey = selected?.key ?? "";
-  const resolvedCompany = t ? (selected?.company ?? company) : "";
-  const selectedVendor = selected?.vendor ?? vendors.find((v) => v.companyName === resolvedCompany);
+  const selected = technicianOptions.find((option) => option.key === selectedKey);
+  const resolvedCompany = selectedKey ? (selected?.company ?? company) : company;
+  const selectedVendor =
+    selected?.vendor ?? allVendors.find((vendor) => String(vendor.id) === selectedKey);
+
+  const { companyName: anchorCompanyName, companyVendor } = resolveVendorCompanyAnchor({
+    company,
+    resolvedCompany,
+    selectedVendor,
+    vendors: allVendors,
+  });
 
   const handlePick = (key: string) => {
     const option = technicianOptions.find((o) => o.key === key);
-    const name = option?.name ?? key;
-    setT(name);
-    setPhone(phoneForOption(name, technicianOptions));
+    setSelectedKey(key);
+    setT(option?.name ?? key);
+    setPhone(option?.phone || phoneForOption(option?.name ?? key, technicianOptions));
   };
 
+  const handleTechnicianCreated = (
+    created: VendorDropdownItem,
+    createdPhone: string,
+    payload: VendorFormValues,
+  ) => {
+    setAddedVendors((current) => [...current, created]);
+    setPendingCreates((current) => ({ ...current, [String(created.id)]: payload }));
+    setSelectedKey(String(created.id));
+    setT(created.contactName);
+    setPhone(createdPhone);
+  };
+
+  const { handleSave } = useVendorDialogSave({
+    allVendors,
+    pendingCreates,
+    selectedKey,
+    selectedVendor,
+    resolvedCompany,
+    anchorCompanyName,
+    tech: selected?.name ?? t,
+    phone,
+    createVendor,
+    onSave,
+    onOpenChange,
+    setSaveError,
+  });
+
   return (
     <Dialog
       open={open}
@@ -96,84 +145,28 @@ export function VendorDialog({
           Search and select the technician
         </Text>
 
-        <div className="mt-3 space-y-3">
-          <div>
-            <FieldLabel>Technician</FieldLabel>
-            <WizardFieldSelect
-              value={selectedKey}
-              placeholder="Search technician …"
-              icon={
-                <Wrench
-                  size={14}
-                  className="shrink-0"
-                  style={{ color: "var(--color-text-muted)" }}
-                />
-              }
-              searchPlaceholder="Search technician…"
-              options={technicianOptions.map((option) => ({
-                key: option.key,
-                label: option.label,
-              }))}
-              onPick={handlePick}
-            />
-          </div>
+        <VendorDialogBody
+          selectedKey={selectedKey}
+          technicianOptions={technicianOptions}
+          anchorCompanyName={anchorCompanyName}
+          companyVendorForAdd={companyVendor ?? undefined}
+          tech={selected?.name ?? t}
+          phone={phone}
+          notes={notes}
+          resolvedCompany={resolvedCompany}
+          selectedVendor={selectedVendor}
+          saveError={saveError}
+          onPick={handlePick}
+          onPhoneChange={setPhone}
+          onNotesChange={setNotes}
+          onTechnicianCreated={handleTechnicianCreated}
+        />
 
-          {Boolean(t) && (
-            <div>
-              <FieldLabel>Technician Phone</FieldLabel>
-              <input
-                type="tel"
-                value={phone}
-                onChange={(e) => setPhone(e.target.value)}
-                className={DLG_INPUT_CLS}
-                style={DLG_INPUT_STYLE}
-              />
-            </div>
-          )}
-
-          {Boolean(t) && (
-            <div>
-              <FieldLabel>Company</FieldLabel>
-              <VendorDialogCompanyCard company={resolvedCompany} vendor={selectedVendor} />
-            </div>
-          )}
-
-          <div>
-            <FieldLabel>Notes</FieldLabel>
-            <textarea
-              value={notes}
-              onChange={(e) => setNotes(e.target.value)}
-              placeholder="Contact preferences, availability, etc."
-              rows={3}
-              className={`${DLG_INPUT_CLS} resize-none`}
-              style={{ ...DLG_INPUT_STYLE, fontFamily: "inherit" }}
-            />
-          </div>
-        </div>
-
-        <div className="mt-4 flex items-center justify-end gap-2">
-          <Button
-            variant="ghost"
-            className="min-h-0 px-2 py-1 text-[12px]"
-            onClick={() => onOpenChange(false)}
-          >
-            Cancel
-          </Button>
-          <Button
-            className="min-h-0 px-3 py-1 text-[12px]"
-            onClick={() => {
-              onSave({
-                vendorId: selectedVendor ? String(selectedVendor.id) : "",
-                company: resolvedCompany,
-                tech: t,
-                techPhone: phone,
-              });
-              onOpenChange(false);
-            }}
-          >
-            Save
-          </Button>
-        </div>
+        <VendorDialogFooter
+          isPending={createVendor.isPending}
+          onCancel={() => onOpenChange(false)}
+          onSave={handleSave}
+        />
       </DialogContent>
     </Dialog>
   );

src/app/(protected)/workorders/_components/list/table/wo-table-inline-row-cells.tsx

@@ -134,6 +134,7 @@ export function WoTableInlineRowCells({
 
       <td className="group/cell" style={{ padding: "0 14px" }}>
         <VendorCell
+          vendorId={draft.vendorId}
           company={draft.company}
           tech={draft.tech}
           techPhone={draft.techPhone}

src/app/(protected)/workorders/_components/list/table/wo-table-row-service-cells.tsx

@@ -1,3 +1,4 @@
+import type { CSSProperties } from "react";
 import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
 import type { WorkOrderTableRow } from "@/domain/work-orders/types/work-order-table-row";
 import { ApptTimeCell } from "./cells/appt-time-cell";
@@ -12,7 +13,7 @@ type WoTableRowServiceCellsProps = {
   vendors: VendorDropdownItem[];
   pmTypes: string[];
   search?: string;
-  mutationCellStyle?: React.CSSProperties;
+  mutationCellStyle?: CSSProperties;
   handlers: WoTableRowHandlers;
   onPatchRow: (patch: Partial<WorkOrderTableRow>) => void;
 };
@@ -56,6 +57,7 @@ export function WoTableRowServiceCells({
         onClick={(e) => e.stopPropagation()}
       >
         <VendorCell
+          vendorId={row.vendorId}
           company={row.company}
           tech={row.tech}
           techPhone={row.techPhone}
@@ -94,6 +96,7 @@ export function WoTableRowServiceCells({
         <CompDocCell
           status={row.docStatus}
           woType={row.type}
+          pm={row.pm}
           mediaCount={row.mediaCount}
           onOpen={handlers.onOpenCompDoc ? () => handlers.onOpenCompDoc!(row) : undefined}
           onOpenMedia={() => handlers.onOpenMedia(row)}

src/app/(protected)/workorders/_components/list/work-orders-list-overlays.tsx

@@ -0,0 +1,90 @@
+import { CompDocDialog } from "@/app/(protected)/workorders/_components/comp-doc/comp-doc-dialog";
+import { MediaUploadModal } from "@/app/(protected)/workorders/_components/media/media-upload-modal";
+import { WorkOrdersAdvancedSearchSheet } from "@/app/(protected)/workorders/_components/list/advanced-search/work-orders-advanced-search-sheet";
+import { NewWoWizard } from "@/app/(protected)/workorders/_components/wizard/new-wo-wizard";
+import type { CompDocData, CompDocSaveStatus } from "@/domain/work-orders/types/completion-doc";
+import type { WorkOrderAdvancedFilters } from "@/domain/work-orders/types/work-order-advanced-filters";
+import type { LocationOption } from "@/domain/work-orders/types/work-order-common";
+import type { WorkOrderUser } from "@/domain/work-orders/types/work-order-list";
+import type { WorkOrderTableRow } from "@/domain/work-orders/types/work-order-table-row";
+
+type WorkOrdersListOverlaysProps = {
+  wizardOpen: boolean;
+  onWizardOpenChange: (open: boolean) => void;
+  users: WorkOrderUser[];
+  sites: LocationOption[];
+  pmTypes: string[];
+  vendorTechs: string[];
+  advOpen: boolean;
+  onAdvOpenChange: (open: boolean) => void;
+  advInitial: WorkOrderAdvancedFilters;
+  onApplyAdvanced: (next: WorkOrderAdvancedFilters) => void;
+  onClearAdvanced: () => void;
+  activeDocRow: WorkOrderTableRow | null;
+  onDocOpenChange: (open: boolean) => void;
+  completionDocs: Record<string, CompDocData>;
+  onSaveCompDoc: (data: CompDocData, status: CompDocSaveStatus) => void | Promise<void>;
+  onDateCompletedChange: (date: string) => void | Promise<void>;
+  activeMediaRow: WorkOrderTableRow | null;
+  onMediaOpenChange: (open: boolean) => void;
+};
+
+export function WorkOrdersListOverlays({
+  wizardOpen,
+  onWizardOpenChange,
+  users,
+  sites,
+  pmTypes,
+  vendorTechs,
+  advOpen,
+  onAdvOpenChange,
+  advInitial,
+  onApplyAdvanced,
+  onClearAdvanced,
+  activeDocRow,
+  onDocOpenChange,
+  completionDocs,
+  onSaveCompDoc,
+  onDateCompletedChange,
+  activeMediaRow,
+  onMediaOpenChange,
+}: WorkOrdersListOverlaysProps) {
+  return (
+    <>
+      <WorkOrdersAdvancedSearchSheet
+        open={advOpen}
+        onOpenChange={onAdvOpenChange}
+        initial={advInitial}
+        onApply={onApplyAdvanced}
+        onClearAll={onClearAdvanced}
+        sites={sites}
+        users={users}
+        pmTypes={pmTypes}
+        vendorTechs={vendorTechs}
+      />
+
+      <NewWoWizard open={wizardOpen} onOpenChange={onWizardOpenChange} users={users} />
+
+      {activeDocRow != null && (
+        <CompDocDialog
+          row={activeDocRow}
+          open={!!activeDocRow}
+          onOpenChange={onDocOpenChange}
+          data={completionDocs[String(activeDocRow.id)]}
+          // docStatus + completedDate persist via board PATCH (not legacy EditWorkorder).
+          // Notes/generatedAt stay client-local (no content endpoint on this branch).
+          onSave={onSaveCompDoc}
+          onDateCompletedChange={onDateCompletedChange}
+        />
+      )}
+
+      {activeMediaRow != null && (
+        <MediaUploadModal
+          row={activeMediaRow}
+          open={!!activeMediaRow}
+          onOpenChange={onMediaOpenChange}
+        />
+      )}
+    </>
+  );
+}

src/app/(protected)/workorders/_components/media/media-upload-modal.tsx

@@ -1,6 +1,7 @@
 import { type MouseEvent } from "react";
 import { Dialog, DialogContent, DialogTitle, Skeleton, Stack } from "@mui/material";
 import { Image as ImageIcon } from "lucide-react";
+import { toast } from "react-toastify";
 import { Button } from "@/components/ui/button";
 import { dialogBlurBackdropSlotProps } from "@/components/ui/dialog-blur-backdrop";
 import { LoadingRegion } from "@/components/ui/loading-region";
@@ -23,6 +24,14 @@ type MediaUploadModalProps = {
   onOpenChange: (open: boolean) => void;
 };
 
+function resolveWorkOrderVersion(
+  detailRowVersion: string | null | undefined,
+  rowVersion: string | null | undefined,
+): string | null {
+  const version = detailRowVersion?.trim() || rowVersion?.trim() || "";
+  return version || null;
+}
+
 export function MediaUploadModal({ row, open, onOpenChange }: MediaUploadModalProps) {
   const { data: detail, isLoading } = useWorkOrderBoardDetail(row.id, open);
   const uploadMutation = useUploadWorkOrderMedia(row.id);
@@ -36,6 +45,15 @@ export function MediaUploadModal({ row, open, onOpenChange }: MediaUploadModalPr
     uploadMutation.isPending || deleteMutation.isPending || categorizeMutation.isPending;
   const handleClose = guardDialogClose(pending, () => onOpenChange(false));
 
+  const requireVersion = (): string | null => {
+    const version = resolveWorkOrderVersion(detail?.info.rowVersion, row.rowVersion);
+    if (!version) {
+      toast.error("Missing work order version. Refresh and try again.");
+      return null;
+    }
+    return version;
+  };
+
   return (
     <Dialog
       open={open}
@@ -79,9 +97,15 @@ export function MediaUploadModal({ row, open, onOpenChange }: MediaUploadModalPr
                   removeLocal(id);
                   return;
                 }
-                deleteMutation.mutate(id);
+                const workOrderVersion = requireVersion();
+                if (!workOrderVersion) return;
+                deleteMutation.mutate({ mediaId: id, workOrderVersion });
+              }}
+              onCategorize={(id, category) => {
+                const workOrderVersion = requireVersion();
+                if (!workOrderVersion) return;
+                categorizeMutation.mutate({ mediaId: id, category, workOrderVersion });
               }}
-              onCategorize={(id, category) => categorizeMutation.mutate({ mediaId: id, category })}
               onRetry={retryUpload}
               onCancel={cancelUpload}
               readOnly={isReadOnly}

src/app/(protected)/workorders/_components/media/media-uploader.tsx

@@ -1,4 +1,4 @@
-import { useRef } from "react";
+import { useRef } from "react";
 import { toast } from "react-toastify";
 import type { UploadableMediaCategory } from "@/domain/work-orders/mappers/work-order-board-detail-mapper";
 import type { MediaFile } from "@/domain/work-orders/types/work-order-media";
@@ -20,7 +20,7 @@ export type MediaUploadRequest = {
 
 type MediaUploaderProps = {
   uploads: MediaFile[];
-  /** Upload-then-categorize: files only — category assigned after persist. */
+  /** Upload-then-categorize: files only ÔÇö category assigned after persist. */
   onUpload?: (requests: MediaUploadRequest[]) => void;
   onRemove?: (id: string) => void;
   onCategorize?: (id: string, category: UploadableMediaCategory) => void;

src/app/(protected)/workorders/_components/view/work-order-activity-panel.tsx

@@ -0,0 +1,107 @@
+import { useMemo, useState } from "react";
+import { Box, Button, Paper, Tab, Tabs } from "@mui/material";
+import { CommentMentionComposer } from "@/components/common/comment-mention-composer";
+import { CommentTimeline } from "@/components/common/comment-timeline";
+import { mapWorkOrderCommentsToTimeline } from "@/components/common/comment-timeline-mappers";
+import type {
+  WorkOrderAuditEntry,
+  WorkOrderComment,
+} from "@/domain/work-orders/types/work-order-detail";
+import { WorkOrderAuditTimeline } from "@/app/(protected)/workorders/_components/view/work-order-audit-timeline";
+import { Text } from "@/components/ui/text";
+
+export type WorkOrderActivityTab = "customer" | "internal" | "audit";
+
+type MentionUser = { id: string | number; name: string };
+
+type WorkOrderActivityPanelProps = {
+  customerComments: WorkOrderComment[];
+  internalComments: WorkOrderComment[];
+  auditLog: WorkOrderAuditEntry[];
+  mentionUsers: MentionUser[];
+  isSubmitting: boolean;
+  onSubmitComment: (text: string) => void | Promise<void>;
+};
+
+export function WorkOrderActivityPanel({
+  customerComments,
+  internalComments,
+  auditLog,
+  mentionUsers,
+  isSubmitting,
+  onSubmitComment,
+}: WorkOrderActivityPanelProps) {
+  const [activeTab, setActiveTab] = useState<WorkOrderActivityTab>("customer");
+  const [commentText, setCommentText] = useState("");
+
+  const customerTimelineItems = useMemo(
+    () => mapWorkOrderCommentsToTimeline(customerComments),
+    [customerComments],
+  );
+  const internalTimelineItems = useMemo(
+    () => mapWorkOrderCommentsToTimeline(internalComments),
+    [internalComments],
+  );
+
+  return (
+    <Paper variant="outlined" className="p-4">
+      <Text as="p" variant="heading" className="mb-3 font-semibold">
+        Activity
+      </Text>
+      <Tabs
+        value={activeTab}
+        onChange={(_event, value: WorkOrderActivityTab) => setActiveTab(value)}
+        className="mb-3"
+      >
+        <Tab value="customer" label={`Customer (${customerComments.length})`} />
+        <Tab value="internal" label={`Internal (${internalComments.length})`} />
+        <Tab value="audit" label={`Audit Log (${auditLog.length})`} />
+      </Tabs>
+
+      {activeTab === "customer" && (
+        <CommentTimeline items={customerTimelineItems} mentionUsers={mentionUsers} />
+      )}
+      {activeTab === "internal" && (
+        <CommentTimeline items={internalTimelineItems} mentionUsers={mentionUsers} />
+      )}
+      {activeTab === "audit" && <WorkOrderAuditTimeline entries={auditLog} />}
+
+      {activeTab === "internal" && (
+        <Box
+          component="form"
+          onSubmit={(event) => {
+            event.preventDefault();
+            const trimmed = commentText.trim();
+            if (!trimmed) {
+              return;
+            }
+            void (async () => {
+              try {
+                await onSubmitComment(trimmed);
+                setCommentText("");
+              } catch {
+                // Mutation toast handles failure; keep the draft for retry.
+              }
+            })();
+          }}
+          className="mt-4 flex flex-col gap-2"
+        >
+          <CommentMentionComposer
+            value={commentText}
+            onChange={setCommentText}
+            candidates={mentionUsers}
+            disabled={isSubmitting}
+          />
+          <Button
+            type="submit"
+            variant="contained"
+            className="self-end"
+            disabled={isSubmitting || !commentText.trim()}
+          >
+            {isSubmitting ? "Sending..." : "Send"}
+          </Button>
+        </Box>
+      )}
+    </Paper>
+  );
+}

src/app/(protected)/workorders/_components/view/work-order-audit-timeline.tsx

@@ -0,0 +1,38 @@
+import { useMemo } from "react";
+import { Box, Stack, Typography } from "@mui/material";
+import type { WorkOrderAuditEntry } from "@/domain/work-orders/types/work-order";
+import { formatDateTime } from "@/lib/time-utils";
+
+export function WorkOrderAuditTimeline({ entries }: { entries: WorkOrderAuditEntry[] }) {
+  const sorted = useMemo(
+    () =>
+      [...entries].sort(
+        (a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
+      ),
+    [entries],
+  );
+
+  if (!sorted.length) {
+    return <Typography sx={{ color: "text.secondary" }}>No changes recorded.</Typography>;
+  }
+
+  return (
+    <Stack spacing={2} className="max-h-72 overflow-y-auto">
+      {sorted.map((entry) => (
+        <Box key={String(entry.id)} className="rounded border border-border p-3">
+          <Stack direction="row" className="mb-1" sx={{ justifyContent: "space-between" }}>
+            <Typography variant="caption" className="font-semibold">
+              {entry.userName || "System"}
+            </Typography>
+            <Typography variant="caption" sx={{ color: "text.secondary" }}>
+              {entry.createdAt ? formatDateTime(entry.createdAt) : ""}
+            </Typography>
+          </Stack>
+          <Typography variant="body2">
+            <strong>{entry.fieldName}</strong> {entry.oldValue} → {entry.newValue}
+          </Typography>
+        </Box>
+      ))}
+    </Stack>
+  );
+}

src/app/(protected)/workorders/_components/view/work-order-detail-field.tsx

@@ -0,0 +1,12 @@
+import { Box, Typography } from "@mui/material";
+
+export function WorkOrderDetailField({ label, value }: { label: string; value: string }) {
+  return (
+    <Box>
+      <Typography variant="caption" sx={{ color: "text.secondary", display: "block" }}>
+        {label}
+      </Typography>
+      <Typography variant="body2">{value}</Typography>
+    </Box>
+  );
+}

src/app/(protected)/workorders/_components/view/work-order-dispatches-accordion.tsx

@@ -0,0 +1,113 @@
+import {
+  Accordion,
+  AccordionDetails,
+  AccordionSummary,
+  Button,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableRow,
+  Typography,
+} from "@mui/material";
+import ExpandMoreIcon from "@mui/icons-material/ExpandMore";
+import type { WorkOrderDetail } from "@/domain/work-orders/types/work-order-detail";
+import { formatDateTime, timeSince, waitTimeColor } from "@/lib/time-utils";
+
+type WorkOrderDispatchesAccordionProps = {
+  wo: WorkOrderDetail;
+  onOpenDispatchDetail: (dispatchId: string | number) => void;
+  onOpenVendorEditor: (
+    event: React.MouseEvent,
+    vendorId: string | number,
+    vendorName: string,
+  ) => void;
+};
+
+export function WorkOrderDispatchesAccordion({
+  wo,
+  onOpenDispatchDetail,
+  onOpenVendorEditor,
+}: WorkOrderDispatchesAccordionProps) {
+  return (
+    <Accordion defaultExpanded={Boolean(wo.dispatches.length)}>
+      <AccordionSummary expandIcon={<ExpandMoreIcon />}>
+        <Typography sx={{ fontWeight: 600 }}>Dispatches ({wo.dispatches.length})</Typography>
+      </AccordionSummary>
+      <AccordionDetails>
+        {wo.dispatches.length ? (
+          <TableContainer>
+            <Table size="small">
+              <TableHead>
+                <TableRow>
+                  <TableCell>Dispatch #</TableCell>
+                  <TableCell>Vendor</TableCell>
+                  <TableCell>NTE</TableCell>
+                  <TableCell>Status</TableCell>
+                  <TableCell>Date</TableCell>
+                  <TableCell>Wait</TableCell>
+                  <TableCell align="right">Actions</TableCell>
+                </TableRow>
+              </TableHead>
+              <TableBody>
+                {wo.dispatches.map((dispatch) => {
+                  const waitColor = waitTimeColor(dispatch.dispatchedAt);
+                  return (
+                    <TableRow
+                      key={String(dispatch.id)}
+                      hover
+                      className="cursor-pointer"
+                      onClick={() => onOpenDispatchDetail(dispatch.id)}
+                    >
+                      <TableCell>{dispatch.dispatchNumber || dispatch.poNumber}</TableCell>
+                      <TableCell>{dispatch.vendorName}</TableCell>
+                      <TableCell>
+                        {dispatch.nteAmount != null ? `$${dispatch.nteAmount.toFixed(2)}` : "—"}
+                      </TableCell>
+                      <TableCell>{dispatch.status}</TableCell>
+                      <TableCell>
+                        {dispatch.dispatchedAt ? formatDateTime(dispatch.dispatchedAt) : "—"}
+                      </TableCell>
+                      <TableCell>
+                        {dispatch.status === "Sent" ? (
+                          <Typography
+                            variant="caption"
+                            className={
+                              waitColor === "green"
+                                ? "text-green-600"
+                                : waitColor === "yellow"
+                                  ? "text-yellow-600"
+                                  : "text-red-600"
+                            }
+                          >
+                            {timeSince(dispatch.dispatchedAt)}
+                          </Typography>
+                        ) : (
+                          "—"
+                        )}
+                      </TableCell>
+                      <TableCell align="right">
+                        <Button
+                          size="small"
+                          onClick={(event) =>
+                            void onOpenVendorEditor(event, dispatch.vendorId, dispatch.vendorName)
+                          }
+                          disabled={dispatch.vendorId === ""}
+                        >
+                          Edit vendor
+                        </Button>
+                      </TableCell>
+                    </TableRow>
+                  );
+                })}
+              </TableBody>
+            </Table>
+          </TableContainer>
+        ) : (
+          <Typography sx={{ color: "text.secondary" }}>No dispatches yet.</Typography>
+        )}
+      </AccordionDetails>
+    </Accordion>
+  );
+}

src/app/(protected)/workorders/_components/view/work-order-vendor-editor-dialog.tsx

@@ -0,0 +1,114 @@
+import {
+  Alert,
+  Box,
+  Button,
+  CircularProgress,
+  Dialog,
+  DialogActions,
+  DialogContent,
+  DialogTitle,
+  Stack,
+  TextField,
+  Typography,
+} from "@mui/material";
+import type { VendorEditorState } from "./work-order-vendor-editor-types";
+import { formatPhoneMask, isVendorEditorValid } from "./work-order-vendor-editor-utils";
+
+type WorkOrderVendorEditorDialogProps = {
+  editor: VendorEditorState | null;
+  loading: boolean;
+  error: string;
+  isSaving: boolean;
+  onClose: () => void;
+  onSave: () => void;
+  onEditorChange: (
+    updater: (current: VendorEditorState | null) => VendorEditorState | null,
+  ) => void;
+};
+
+export function WorkOrderVendorEditorDialog({
+  editor,
+  loading,
+  error,
+  isSaving,
+  onClose,
+  onSave,
+  onEditorChange,
+}: WorkOrderVendorEditorDialogProps) {
+  return (
+    <Dialog open={editor !== null} onClose={onClose} fullWidth maxWidth="sm">
+      <DialogTitle>Edit assigned vendor</DialogTitle>
+      <DialogContent>
+        <Stack spacing={2} className="pt-2">
+          <Typography variant="body2" color="text.secondary">
+            {editor?.vendorName}
+          </Typography>
+          {Boolean(error) && <Alert severity="error">{error}</Alert>}
+          {loading ? (
+            <Box className="flex justify-center p-6">
+              <CircularProgress size={28} />
+            </Box>
+          ) : (
+            <>
+              <TextField
+                label="Technician name"
+                value={editor?.contactName ?? ""}
+                onChange={(event) =>
+                  onEditorChange((current) =>
+                    current ? { ...current, contactName: event.target.value } : current,
+                  )
+                }
+                slotProps={{ htmlInput: { maxLength: 200 } }}
+              />
+              <TextField
+                label="Phone"
+                value={editor?.phone ?? ""}
+                onChange={(event) =>
+                  onEditorChange((current) =>
+                    current ? { ...current, phone: formatPhoneMask(event.target.value) } : current,
+                  )
+                }
+                error={Boolean(editor?.phone && !/^\(\d{3}\) \d{3}-\d{4}$/.test(editor.phone))}
+                helperText="Use (XXX) XXX-XXXX"
+              />
+              <TextField
+                label="Email"
+                type="email"
+                value={editor?.email ?? ""}
+                onChange={(event) =>
+                  onEditorChange((current) =>
+                    current ? { ...current, email: event.target.value } : current,
+                  )
+                }
+              />
+              <TextField
+                label="Notes"
+                multiline
+                minRows={3}
+                value={editor?.notes ?? ""}
+                onChange={(event) =>
+                  onEditorChange((current) =>
+                    current ? { ...current, notes: event.target.value } : current,
+                  )
+                }
+                slotProps={{ htmlInput: { maxLength: 2000 } }}
+              />
+            </>
+          )}
+        </Stack>
+      </DialogContent>
+      <DialogActions>
+        <Button onClick={onClose} disabled={isSaving}>
+          Cancel
+        </Button>
+        <Button
+          variant="contained"
+          onClick={onSave}
+          disabled={!editor || loading || isSaving || !isVendorEditorValid(editor)}
+        >
+          {isSaving ? "Saving..." : "Save"}
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+}

src/app/(protected)/workorders/_components/view/work-order-vendor-editor-types.ts

@@ -0,0 +1,8 @@
+export interface VendorEditorState {
+  vendorId: string | number;
+  vendorName: string;
+  contactName: string;
+  phone: string;
+  email: string;
+  notes: string;
+}

src/app/(protected)/workorders/_components/view/work-order-vendor-editor-utils.ts

@@ -0,0 +1,16 @@
+import type { VendorEditorState } from "./work-order-vendor-editor-types";
+
+export function formatPhoneMask(input: string): string {
+  const digits = input.replace(/\D/g, "").slice(0, 10);
+  if (digits.length <= 3) return digits;
+  if (digits.length <= 6) return `(${digits.slice(0, 3)}) ${digits.slice(3)}`;
+  return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
+}
+
+export function isVendorEditorValid(editor: VendorEditorState): boolean {
+  const phoneValid = editor.phone === "" || /^\(\d{3}\) \d{3}-\d{4}$/.test(editor.phone);
+  const emailValid = editor.email === "" || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(editor.email);
+  return (
+    phoneValid && emailValid && editor.notes.length <= 2000 && editor.contactName.length <= 200
+  );
+}

src/app/(protected)/workorders/_components/view/work-order-view-accordions.tsx

@@ -0,0 +1,66 @@
+import { Accordion, AccordionDetails, AccordionSummary, Box, Typography } from "@mui/material";
+import ExpandMoreIcon from "@mui/icons-material/ExpandMore";
+import type { WorkOrderDetail } from "@/domain/work-orders/types/work-order-detail";
+import { WorkOrderDetailField } from "@/app/(protected)/workorders/_components/view/work-order-detail-field";
+import { formatDateTime } from "@/lib/time-utils";
+
+export function WorkOrderViewAccordions({ wo }: { wo: WorkOrderDetail }) {
+  return (
+    <>
+      <Accordion>
+        <AccordionSummary expandIcon={<ExpandMoreIcon />}>
+          <Typography sx={{ fontWeight: 600 }}>Classification</Typography>
+        </AccordionSummary>
+        <AccordionDetails>
+          <Box className="grid grid-cols-1 gap-4 sm:grid-cols-3">
+            <WorkOrderDetailField label="Problem" value={wo.problem || "—"} />
+            <WorkOrderDetailField label="Trade" value={wo.trade || "—"} />
+            <WorkOrderDetailField label="Sub-Trade" value={wo.subTrade || "—"} />
+          </Box>
+        </AccordionDetails>
+      </Accordion>
+
+      <Accordion>
+        <AccordionSummary expandIcon={<ExpandMoreIcon />}>
+          <Typography sx={{ fontWeight: 600 }}>Schedule</Typography>
+        </AccordionSummary>
+        <AccordionDetails>
+          <Box className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
+            <WorkOrderDetailField
+              label="Created"
+              value={wo.createdDateFull ? formatDateTime(wo.createdDateFull) : "—"}
+            />
+            <WorkOrderDetailField label="Due Date" value={wo.dueDate || "—"} />
+            <WorkOrderDetailField label="Scheduled" value={wo.scheduledDate || "—"} />
+            <WorkOrderDetailField label="Completed" value={wo.completedDate || "—"} />
+          </Box>
+        </AccordionDetails>
+      </Accordion>
+
+      <Accordion>
+        <AccordionSummary expandIcon={<ExpandMoreIcon />}>
+          <Typography sx={{ fontWeight: 600 }}>Financial</Typography>
+        </AccordionSummary>
+        <AccordionDetails>
+          <Box className="grid grid-cols-1 gap-4 sm:grid-cols-3">
+            <WorkOrderDetailField
+              label="Vendor NTE"
+              value={wo.vendorNTE ? `$${parseFloat(wo.vendorNTE).toFixed(2)}` : "—"}
+            />
+            <WorkOrderDetailField label="Customer PO" value={wo.po || "—"} />
+            <WorkOrderDetailField label="Customer NTE" value="Not connected" />
+          </Box>
+        </AccordionDetails>
+      </Accordion>
+
+      <Accordion>
+        <AccordionSummary expandIcon={<ExpandMoreIcon />}>
+          <Typography sx={{ fontWeight: 600 }}>Description</Typography>
+        </AccordionSummary>
+        <AccordionDetails>
+          <Typography>{wo.description || "No description provided."}</Typography>
+        </AccordionDetails>
+      </Accordion>
+    </>
+  );
+}

src/app/(protected)/workorders/_components/view/work-order-view-details.tsx

@@ -0,0 +1,73 @@
+import { Box, Button, Menu, MenuItem, Paper, Typography } from "@mui/material";
+import type { WorkOrderUser } from "@/domain/work-orders/types/work-order";
+import type { WorkOrderDetail } from "@/domain/work-orders/types/work-order-detail";
+import { WorkOrderDetailField } from "@/app/(protected)/workorders/_components/view/work-order-detail-field";
+import { Text } from "@/components/ui/text";
+
+type WorkOrderViewDetailsProps = {
+  wo: WorkOrderDetail;
+  users: WorkOrderUser[];
+  assignAnchor: HTMLElement | null;
+  onAssignAnchorChange: (anchor: HTMLElement | null) => void;
+  onAssign: (userId: string | number, userName: string) => void;
+  onUnassign: () => void;
+};
+
+export function WorkOrderViewDetails({
+  wo,
+  users,
+  assignAnchor,
+  onAssignAnchorChange,
+  onAssign,
+  onUnassign,
+}: WorkOrderViewDetailsProps) {
+  return (
+    <Paper variant="outlined" className="p-4">
+      <Text as="p" variant="heading" className="mb-3 font-semibold">
+        Details
+      </Text>
+      <Box className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+        <WorkOrderDetailField label="Internal WO" value={wo.internalWONumber} />
+        <WorkOrderDetailField label="Customer WO" value={wo.workOrderNumber || "—"} />
+        <WorkOrderDetailField label="Priority" value={wo.priority || "—"} />
+        <WorkOrderDetailField label="Location" value={wo.location || "—"} />
+        <Box>
+          <Typography variant="caption" sx={{ color: "text.secondary", display: "block" }}>
+            Assigned To
+          </Typography>
+          <Button size="small" onClick={(event) => onAssignAnchorChange(event.currentTarget)}>
+            {wo.assignedTo || "Unassigned"}
+          </Button>
+          <Menu
+            anchorEl={assignAnchor}
+            open={Boolean(assignAnchor)}
+            onClose={() => onAssignAnchorChange(null)}
+          >
+            <MenuItem
+              onClick={() => {
+                onAssignAnchorChange(null);
+                onUnassign();
+              }}
+            >
+              Unassigned
+            </MenuItem>
+            {users.map((user) => (
+              <MenuItem
+                key={String(user.id)}
+                selected={wo.assignedTo === user.name}
+                onClick={() => {
+                  onAssignAnchorChange(null);
+                  onAssign(user.id, user.name);
+                }}
+              >
+                {user.name}
+              </MenuItem>
+            ))}
+          </Menu>
+        </Box>
+        <WorkOrderDetailField label="Source" value={wo.source || "—"} />
+        <WorkOrderDetailField label="TT" value={wo.tt || "—"} />
+      </Box>
+    </Paper>
+  );
+}

src/app/(protected)/workorders/_components/view/work-order-view-header.tsx

@@ -0,0 +1,95 @@
+import { Link as RouterLink, useNavigate } from "react-router";
+import { Breadcrumbs, Button, Chip, Link, Menu, MenuItem, Stack, Typography } from "@mui/material";
+import { WORK_ORDER_STATUS_OPTIONS } from "@/domain/work-orders/types/work-order";
+import type { WorkOrderDetail } from "@/domain/work-orders/types/work-order-detail";
+
+const STATUS_COLORS: Record<
+  string,
+  "default" | "primary" | "secondary" | "error" | "info" | "success" | "warning"
+> = {
+  Open: "primary",
+  "In Progress": "info",
+  "On Hold": "warning",
+  Done: "success",
+  Cancelled: "default",
+};
+
+type WorkOrderViewHeaderProps = {
+  wo: WorkOrderDetail;
+  workOrderId: string;
+  statusAnchor: HTMLElement | null;
+  onStatusAnchorChange: (anchor: HTMLElement | null) => void;
+  onStatusChange: (status: string) => void;
+  onOpenDispatch: () => void;
+};
+
+export function WorkOrderViewHeader({
+  wo,
+  workOrderId,
+  statusAnchor,
+  onStatusAnchorChange,
+  onStatusChange,
+  onOpenDispatch,
+}: WorkOrderViewHeaderProps) {
+  const navigate = useNavigate();
+
+  return (
+    <>
+      <Breadcrumbs>
+        <Link component={RouterLink} to="/workorders" underline="hover">
+          Work Orders
+        </Link>
+        <Typography sx={{ color: "text.primary" }}>{wo.internalWONumber}</Typography>
+      </Breadcrumbs>
+      <Stack
+        direction={{ xs: "column", md: "row" }}
+        spacing={2}
+        sx={{ justifyContent: "space-between", alignItems: { xs: "stretch", md: "flex-start" } }}
+      >
+        <Stack spacing={1}>
+          <Typography variant="h5" component="h1">
+            {wo.title}
+          </Typography>
+          <Chip
+            label={wo.status}
+            color={STATUS_COLORS[wo.status] ?? "default"}
+            onClick={(event) => onStatusAnchorChange(event.currentTarget)}
+            className="w-fit cursor-pointer"
+          />
+          <Menu
+            anchorEl={statusAnchor}
+            open={Boolean(statusAnchor)}
+            onClose={() => onStatusAnchorChange(null)}
+          >
+            {WORK_ORDER_STATUS_OPTIONS.map((status) => (
+              <MenuItem
+                key={status}
+                selected={status === wo.status}
+                onClick={() => {
+                  onStatusAnchorChange(null);
+                  if (status !== wo.status) {
+                    onStatusChange(status);
+                  }
+                }}
+              >
+                {status}
+              </MenuItem>
+            ))}
+          </Menu>
+        </Stack>
+
+        <Stack direction="row" spacing={1} sx={{ flexWrap: "wrap" }}>
+          <Button variant="contained" color="success" onClick={onOpenDispatch}>
+            Dispatch
+          </Button>
+          <Button variant="contained" onClick={() => navigate(`/workorders/edit/${workOrderId}`)}>
+            Edit
+          </Button>
+          <Button variant="outlined" onClick={() => navigate("/workorders")}>
+            Back to List
+          </Button>
+        </Stack>
+      </Stack>
+    </>
+  );
+}

src/app/(protected)/workorders/_hooks/create-comp-doc-dialog-actions.ts

@@ -0,0 +1,170 @@
+import type { QueryClient } from "@tanstack/react-query";
+import { toast } from "react-toastify";
+import { showCompDocDraftSavedToast } from "@/app/(protected)/workorders/_components/comp-doc/comp-doc-draft-toast";
+import { locationsApi } from "@/domain/locations/api/locations-api";
+import type { Location } from "@/domain/locations/types/location";
+import type {
+  CompDocData,
+  CompDocSaveStatus,
+  DocFields,
+  DocState,
+} from "@/domain/work-orders/types/completion-doc";
+import type { WorkOrderTableRow } from "@/domain/work-orders/types/work-order-table-row";
+import { buildDocHtml, printDoc } from "@/domain/work-orders/utils/completion-doc-html";
+import { fmtDocNow } from "@/domain/work-orders/utils/completion-doc-state";
+import { queryKeys } from "@/infra/query-key/query-key";
+
+type CompDocSite = { street: string; fullAddress: string };
+
+export function buildCompDocAddressLine(site: CompDocSite): string {
+  if (site.street.trim()) return site.street.trim();
+  return site.fullAddress !== "—" ? site.fullAddress : "";
+}
+
+function locationUpdatePayload(location: Location, address: string): Location {
+  return {
+    ...location,
+    address,
+  };
+}
+
+type CreateCompDocDialogActionsParams = {
+  row: WorkOrderTableRow;
+  notes: string;
+  generatedAt: string;
+  editDateCompleted: string;
+  editAddress: string;
+  docState: DocState;
+  docFields: DocFields;
+  site: CompDocSite;
+  locId: string;
+  isMockLocation: boolean;
+  locationDetail: Location | undefined;
+  queryClient: QueryClient;
+  onSave: (data: CompDocData, status: CompDocSaveStatus) => void | Promise<void>;
+  onDateCompletedChange?: (date: string) => void | Promise<void>;
+  setDocState: (state: DocState) => void;
+  setGeneratedAt: (value: string) => void;
+};
+
+export function createCompDocDialogActions({
+  row,
+  notes,
+  generatedAt,
+  editDateCompleted,
+  editAddress,
+  docState,
+  docFields,
+  site,
+  locId,
+  isMockLocation,
+  locationDetail,
+  queryClient,
+  onSave,
+  onDateCompletedChange,
+  setDocState,
+  setGeneratedAt,
+}: CreateCompDocDialogActionsParams) {
+  async function persist(extra: Partial<CompDocData>, status: CompDocSaveStatus): Promise<void> {
+    await onSave({ notes, generatedAt, ...extra }, status);
+  }
+
+  async function syncCompletedDateIfChanged(): Promise<void> {
+    if (editDateCompleted !== (row.completedDate || "")) {
+      await onDateCompletedChange?.(editDateCompleted);
+    }
+  }
+
+  async function syncAddressIfChanged(): Promise<void> {
+    const next = editAddress.trim();
+    const current = buildCompDocAddressLine(site);
+    if (next === current) return;
+    if (isMockLocation || !locId) return;
+    if (!locationDetail) {
+      throw new Error("Location details are still loading. Try saving again.");
+    }
+
+    await locationsApi.update(locId, locationUpdatePayload(locationDetail, next));
+    void queryClient.invalidateQueries({ queryKey: queryKeys.locations.detail(locId) });
+    void queryClient.invalidateQueries({ queryKey: queryKeys.locations.all });
+    void queryClient.invalidateQueries({ queryKey: queryKeys.workOrders.all });
+  }
+
+  function refreshAuthoritativeState() {
+    void queryClient.invalidateQueries({ queryKey: queryKeys.workOrders.all });
+    if (locId && !isMockLocation) {
+      void queryClient.invalidateQueries({ queryKey: queryKeys.locations.detail(locId) });
+      void queryClient.invalidateQueries({ queryKey: queryKeys.locations.all });
+    }
+  }
+
+  async function handleMarkNotRequired() {
+    const previous = docState;
+    setDocState("not-required");
+    try {
+      await persist({}, "NN");
+    } catch (error) {
+      setDocState(previous);
+      refreshAuthoritativeState();
+      toast.error(
+        error instanceof Error ? error.message : "Failed to mark document as not required",
+      );
+    }
+  }
+
+  async function handleUndo() {
+    const previous = docState;
+    setDocState("draft");
+    try {
+      await persist({}, "No");
+    } catch (error) {
+      setDocState(previous);
+      refreshAuthoritativeState();
+      toast.error(error instanceof Error ? error.message : "Failed to undo not-required");
+    }
+  }
+
+  async function handleSaveDraft() {
+    try {
+      await syncCompletedDateIfChanged();
+      await syncAddressIfChanged();
+      await persist({}, "No");
+      showCompDocDraftSavedToast();
+    } catch (error) {
+      refreshAuthoritativeState();
+      toast.error(error instanceof Error ? error.message : "Failed to save draft");
+    }
+  }
+
+  async function handleGenerate() {
+    if (!editDateCompleted.trim()) {
+      toast.error("Date Work Completed is required to generate the document.");
+      return;
+    }
+    const ts = fmtDocNow();
+    try {
+      // Prerequisites first; only mark Generated after completedDate/address persist.
+      await syncCompletedDateIfChanged();
+      await syncAddressIfChanged();
+      await persist({ generatedAt: ts }, "Yes");
+      setGeneratedAt(ts);
+      setDocState("generated");
+    } catch (error) {
+      // Keep Draft UI; refresh so any partially persisted date/address is authoritative.
+      refreshAuthoritativeState();
+      toast.error(error instanceof Error ? error.message : "Failed to generate document");
+    }
+  }
+
+  function handleDownloadPdf() {
+    printDoc(buildDocHtml(row, { notes, generatedAt }, docFields));
+  }
+
+  return {
+    handleMarkNotRequired,
+    handleUndo,
+    handleSaveDraft,
+    handleGenerate,
+    handleDownloadPdf,
+  };
+}

src/app/(protected)/workorders/_hooks/use-comp-doc-dialog.ts

@@ -0,0 +1,157 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import {
+  buildCompDocAddressLine,
+  createCompDocDialogActions,
+} from "@/app/(protected)/workorders/_hooks/create-comp-doc-dialog-actions";
+import { useLocationDetail } from "@/domain/locations/use-cases/use-location-detail";
+import type {
+  CompDocData,
+  CompDocSaveStatus,
+  DocFields,
+  DocState,
+} from "@/domain/work-orders/types/completion-doc";
+import type { WorkOrderTableRow } from "@/domain/work-orders/types/work-order-table-row";
+import { getMockWoWizardLocationDetail } from "@/domain/work-orders/mocks/wo-wizard-mock-data";
+import { resolveCompDocSite } from "@/domain/work-orders/utils/completion-doc-site";
+import { DOC_STATE_CFG, docStateOf } from "@/domain/work-orders/utils/completion-doc-state";
+
+type UseCompDocDialogParams = {
+  row: WorkOrderTableRow;
+  open: boolean;
+  data?: CompDocData;
+  onSave: (data: CompDocData, status: CompDocSaveStatus) => void | Promise<void>;
+  onDateCompletedChange?: (date: string) => void | Promise<void>;
+};
+
+export function useCompDocDialog({
+  row,
+  open,
+  data,
+  onSave,
+  onDateCompletedChange,
+}: UseCompDocDialogParams) {
+  const queryClient = useQueryClient();
+  const locId = String(row.locationId || "");
+  const isMockLocation = locId.startsWith("mock-");
+  const { data: apiLocationDetail } = useLocationDetail(
+    isMockLocation || !locId ? undefined : locId,
+  );
+  const locationDetail = isMockLocation ? getMockWoWizardLocationDetail(locId) : apiLocationDetail;
+  const site = useMemo(() => resolveCompDocSite(row, locationDetail), [row, locationDetail]);
+
+  const [notes, setNotes] = useState("");
+  const [docState, setDocState] = useState<DocState>("draft");
+  const [generatedAt, setGeneratedAt] = useState("");
+  const [editDateCompleted, setEditDateCompleted] = useState("");
+  const [editAddress, setEditAddress] = useState("");
+  const seedKeyRef = useRef<string | null>(null);
+  const addressSeededRef = useRef(false);
+  const addressTouchedRef = useRef(false);
+
+  // Seed once per open/WO — row/detail refetches must not wipe in-progress edits.
+  // Address waits for authoritative locationDetail (when a real location id exists)
+  // and still accepts that first response without overwriting later user edits.
+  useEffect(() => {
+    if (!open) {
+      seedKeyRef.current = null;
+      addressSeededRef.current = false;
+      addressTouchedRef.current = false;
+      return;
+    }
+
+    const key = String(row.id);
+    if (seedKeyRef.current !== key) {
+      seedKeyRef.current = key;
+      addressSeededRef.current = false;
+      addressTouchedRef.current = false;
+      setNotes(data?.notes ?? "");
+      setDocState(docStateOf(row.docStatus));
+      setGeneratedAt(data?.generatedAt ?? "");
+      setEditDateCompleted(row.completedDate || "");
+    }
+
+    if (addressTouchedRef.current || addressSeededRef.current) {
+      return;
+    }
+
+    const awaitingLocation = Boolean(locId) && !isMockLocation && !locationDetail;
+    if (awaitingLocation) {
+      return;
+    }
+
+    setEditAddress(buildCompDocAddressLine(resolveCompDocSite(row, locationDetail)));
+    addressSeededRef.current = true;
+  }, [open, row, data?.notes, data?.generatedAt, locationDetail, locId, isMockLocation]);
+
+  const handleAddressChange = (value: string) => {
+    addressTouchedRef.current = true;
+    setEditAddress(value);
+  };
+
+  const amazonRep = row.pocName || "";
+  const seaRep = row.tech || "";
+  const cfg = DOC_STATE_CFG[docState];
+  const isNotRequired = docState === "not-required";
+  const isGenerated = docState === "generated";
+
+  const effectiveStreet = editAddress.trim() || site.street;
+  const docFields: DocFields = {
+    street: effectiveStreet,
+    city: site.city,
+    state: site.state,
+    zip: site.zip,
+    dateCompleted: editDateCompleted,
+    amazonRep,
+    seaRep,
+  };
+
+  const previewSite = useMemo(
+    () => ({
+      ...site,
+      street: effectiveStreet,
+      fullAddress:
+        [effectiveStreet, site.label, site.zip].filter(Boolean).join(", ") ||
+        effectiveStreet ||
+        "—",
+    }),
+    [site, effectiveStreet],
+  );
+
+  const actions = createCompDocDialogActions({
+    row,
+    notes,
+    generatedAt,
+    editDateCompleted,
+    editAddress,
+    docState,
+    docFields,
+    site,
+    locId,
+    isMockLocation,
+    locationDetail,
+    queryClient,
+    onSave,
+    onDateCompletedChange,
+    setDocState,
+    setGeneratedAt,
+  });
+
+  return {
+    site: previewSite,
+    notes,
+    setNotes,
+    docState,
+    generatedAt,
+    editAddress,
+    setEditAddress: handleAddressChange,
+    editDateCompleted,
+    setEditDateCompleted,
+    amazonRep,
+    seaRep,
+    cfg,
+    isNotRequired,
+    isGenerated,
+    ...actions,
+  };
+}

src/app/(protected)/workorders/_hooks/use-dispatch-detail-controller.ts

@@ -1,7 +1,8 @@
 import { useMemo, useState } from "react";
 import {
   useApproveUplift,
-  useDenyUplift,
+  useRejectUplift,
+  useRequestChangesUplift,
   useUpliftsForDispatch,
 } from "@/domain/uplifts/use-cases/use-uplift-actions";
 import type { UpliftRequest } from "@/domain/uplifts/types/uplift";
@@ -68,7 +69,7 @@ export function useDispatchDetailController(
   const [sendEmail, setSendEmail] = useState(true);
   const [sigCaptureType, setSigCaptureType] = useState<string | null>(null);
   const [upliftAction, setUpliftAction] = useState<{
-    type: "approve" | "deny";
+    type: "approve" | "reject" | "request-changes";
     uplift: UpliftRequest;
   } | null>(null);
 
@@ -79,7 +80,8 @@ export function useDispatchDetailController(
   const addSignoffMutation = useAddDispatchSignoff(dispatchId);
   const verifyMutation = useVerifyDispatch(dispatchId, workOrderId);
   const approveUpliftMutation = useApproveUplift(dispatchId);
-  const denyUpliftMutation = useDenyUplift(dispatchId);
+  const rejectUpliftMutation = useRejectUplift(dispatchId);
+  const requestChangesUpliftMutation = useRequestChangesUplift(dispatchId);
 
   const userName =
     (typeof user?.name === "string" ? user.name : undefined) ??
@@ -143,18 +145,19 @@ export function useDispatchDetailController(
       return;
     }
 
+    const id = upliftAction.uplift.id;
     if (upliftAction.type === "approve") {
-      approveUpliftMutation.mutate(
-        { id: upliftAction.uplift.id, note },
-        { onSuccess: () => setUpliftAction(null) },
-      );
+      approveUpliftMutation.mutate({ id, note }, { onSuccess: () => setUpliftAction(null) });
       return;
     }
 
-    denyUpliftMutation.mutate(
-      { id: upliftAction.uplift.id, note },
-      { onSuccess: () => setUpliftAction(null) },
-    );
+    if (!note.trim()) {
+      return;
+    }
+
+    const mutation =
+      upliftAction.type === "reject" ? rejectUpliftMutation : requestChangesUpliftMutation;
+    mutation.mutate({ id, note }, { onSuccess: () => setUpliftAction(null) });
   };
 
   return {
@@ -189,7 +192,8 @@ export function useDispatchDetailController(
     addSignoffMutation,
     verifyMutation,
     approveUpliftMutation,
-    denyUpliftMutation,
+    rejectUpliftMutation,
+    requestChangesUpliftMutation,
     addCommentMutation,
   };
 }

src/app/(protected)/workorders/_hooks/use-media-upload-session.ts

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import type { MediaUploadRequest } from "@/app/(protected)/workorders/_components/media/media-uploader";
 import { boardMediaItemsToMediaFiles } from "@/domain/work-orders/mappers/work-order-board-detail-mapper";
 import type { MediaFile } from "@/domain/work-orders/types/work-order-media";
@@ -55,7 +55,7 @@ export function useMediaUploadSession(
   const previousWorkOrderIdRef = useRef(workOrderId);
 
   // Drop local tiles and abort in-flight uploads when the bound WO changes.
-  // Skip the first bind (undefined → id) so an early upload is not cleared.
+  // Skip the first bind (undefined  id) so an early upload is not cleared.
   useEffect(() => {
     if (previousWorkOrderIdRef.current === workOrderId) return;
     const hadPrevious = previousWorkOrderIdRef.current != null;

src/app/(protected)/workorders/_hooks/use-work-order-view-page.ts

@@ -0,0 +1,149 @@
+import { useMemo, useState } from "react";
+import type { VendorEditorState } from "@/app/(protected)/workorders/_components/view/work-order-vendor-editor-types";
+import { isVendorEditorValid } from "@/app/(protected)/workorders/_components/view/work-order-vendor-editor-utils";
+import { useWorkOrderDetail } from "@/domain/work-orders/use-cases/use-work-order-detail";
+import {
+  useAddWorkOrderComment,
+  useChangeWorkOrderAssignment,
+  useChangeWorkOrderStatus,
+  useUpdateWorkOrderVendor,
+} from "@/domain/work-orders/use-cases/use-work-order-mutations";
+import { useWorkOrderUsers } from "@/domain/work-orders/use-cases/use-work-orders-list";
+import { vendorsApi } from "@/domain/vendors/api/vendors-api";
+import { extractMentionIds } from "@/domain/work-orders/utils/comment-mentions";
+
+export function useWorkOrderViewPage(workOrderId: string) {
+  const { data: wo, isLoading, error, refetch } = useWorkOrderDetail(workOrderId);
+  const { data: users = [] } = useWorkOrderUsers();
+  const statusMutation = useChangeWorkOrderStatus(workOrderId);
+  const assignmentMutation = useChangeWorkOrderAssignment(workOrderId);
+  const commentMutation = useAddWorkOrderComment(workOrderId);
+  const vendorMutation = useUpdateWorkOrderVendor(workOrderId);
+
+  const [dispatchOpen, setDispatchOpen] = useState(false);
+  const [dispatchDetailId, setDispatchDetailId] = useState<string | number | null>(null);
+  const [statusAnchor, setStatusAnchor] = useState<HTMLElement | null>(null);
+  const [assignAnchor, setAssignAnchor] = useState<HTMLElement | null>(null);
+  const [vendorEditor, setVendorEditor] = useState<VendorEditorState | null>(null);
+  const [vendorEditorLoading, setVendorEditorLoading] = useState(false);
+  const [vendorEditorError, setVendorEditorError] = useState("");
+
+  const customerComments = useMemo(
+    () => (wo?.comments ?? []).filter((comment) => comment.commentType === "customer"),
+    [wo?.comments],
+  );
+  const internalComments = useMemo(
+    () => (wo?.comments ?? []).filter((comment) => comment.commentType === "internal"),
+    [wo?.comments],
+  );
+  const auditLog = wo?.auditLog ?? [];
+  const mentionUsers = useMemo(
+    () => users.map((user) => ({ id: user.id, name: user.name })),
+    [users],
+  );
+
+  const submitComment = async (text: string) => {
+    const mentions = extractMentionIds(text);
+    await commentMutation.mutateAsync({
+      text,
+      mentions: mentions.length > 0 ? mentions : undefined,
+      commentType: "internal",
+    });
+  };
+
+  const openVendorEditor = async (
+    event: React.MouseEvent,
+    vendorId: string | number,
+    vendorName: string,
+  ) => {
+    event.stopPropagation();
+    setVendorEditorError("");
+    setVendorEditorLoading(true);
+    setVendorEditor({
+      vendorId,
+      vendorName,
+      contactName: "",
+      phone: "",
+      email: "",
+      notes: "",
+    });
+
+    try {
+      const vendor = await vendorsApi.getById(vendorId);
+      setVendorEditor({
+        vendorId,
+        vendorName: vendor.companyName || vendorName,
+        contactName: vendor.contactName,
+        phone: vendor.phone,
+        email: vendor.email,
+        notes: vendor.notes,
+      });
+    } catch (vendorError) {
+      setVendorEditorError(
+        vendorError instanceof Error ? vendorError.message : "Unable to load vendor details",
+      );
+    } finally {
+      setVendorEditorLoading(false);
+    }
+  };
+
+  const saveVendorEditor = () => {
+    if (!vendorEditor || !isVendorEditorValid(vendorEditor)) return;
+    const numericWorkOrderId = Number(workOrderId);
+    if (!Number.isInteger(numericWorkOrderId) || numericWorkOrderId <= 0) {
+      setVendorEditorError("A valid work order is required");
+      return;
+    }
+
+    vendorMutation.mutate(
+      {
+        vendorId: vendorEditor.vendorId,
+        payload: {
+          workOrderId: numericWorkOrderId,
+          contactName: vendorEditor.contactName.trim(),
+          phone: vendorEditor.phone,
+          email: vendorEditor.email.trim(),
+          notes: vendorEditor.notes.trim(),
+        },
+      },
+      {
+        onSuccess: () => {
+          setVendorEditor(null);
+          void refetch();
+        },
+        onError: (vendorError) => setVendorEditorError(vendorError.message),
+      },
+    );
+  };
+
+  return {
+    wo,
+    isLoading,
+    error,
+    refetch,
+    users,
+    customerComments,
+    internalComments,
+    auditLog,
+    mentionUsers,
+    submitComment,
+    dispatchOpen,
+    setDispatchOpen,
+    dispatchDetailId,
+    setDispatchDetailId,
+    statusAnchor,
+    setStatusAnchor,
+    assignAnchor,
+    setAssignAnchor,
+    vendorEditor,
+    setVendorEditor,
+    vendorEditorLoading,
+    vendorEditorError,
+    openVendorEditor,
+    saveVendorEditor,
+    statusMutation,
+    assignmentMutation,
+    commentMutation,
+    vendorMutation,
+  };
+}

src/app/(protected)/workorders/index.tsx

@@ -132,7 +132,7 @@ export default function WorkOrdersListPage() {
       {page.activeMediaRow != null && (
         <MediaUploadModal
           row={page.activeMediaRow}
-          open={!!page.activeMediaRow}
+          open={Boolean(page.activeMediaRow)}
           onOpenChange={(open) => {
             if (!open) page.setMediaRow(null);
           }}
@@ -142,7 +142,7 @@ export default function WorkOrdersListPage() {
       {activeDocRow != null && (
         <CompDocDialog
           row={activeDocRow}
-          open={!!activeDocRow}
+          open={Boolean(activeDocRow)}
           onOpenChange={(open) => {
             if (!open) page.setDocRow(null);
           }}

src/app/v/[token]/dispatch/[id].tsx

@@ -31,6 +31,11 @@ export default function VendorPortalDispatchPage() {
     await queryClient.invalidateQueries({ queryKey: queryKeys.vendorPortal.dispatches(token) });
   }, [refetch, queryClient, token]);
 
+  const pollEvidenceDocument = useCallback(
+    (documentId: number) => vendorPortalApi.getDocumentStatus(token, dispatchId, documentId),
+    [token, dispatchId],
+  );
+
   const runAction = async (action: () => Promise<void>, confirmMsg?: string) => {
     if (confirmMsg && !window.confirm(confirmMsg)) return;
     setActionError("");
@@ -109,6 +114,7 @@ export default function VendorPortalDispatchPage() {
         data={data}
         locked={locked}
         refresh={refresh}
+        pollEvidenceDocument={pollEvidenceDocument}
         updateLocal={updateLocal}
       />
 

src/app/v/[token]/dispatch/_components/dispatch-detail-sections.tsx

@@ -4,7 +4,10 @@ import { CommentsSection } from "@/app/v/[token]/dispatch/_components/comments-s
 import { SignoffSection } from "@/app/v/[token]/dispatch/_components/signoff-section";
 import { UpliftRequestsSection } from "@/app/v/[token]/dispatch/_components/uplift-requests-section";
 import { VendorPortalDocuments } from "@/app/v/_components/vendor-portal-documents";
-import type { VendorPortalDispatchDetail } from "@/domain/vendor-portal/types/vendor-portal";
+import type {
+  VendorPortalDispatchDetail,
+  VendorPortalDocumentStatus,
+} from "@/domain/vendor-portal/types/vendor-portal";
 
 type DispatchDetailSectionsProps = {
   token: string;
@@ -12,6 +15,7 @@ type DispatchDetailSectionsProps = {
   data: VendorPortalDispatchDetail;
   locked: boolean;
   refresh: () => Promise<void>;
+  pollEvidenceDocument: (documentId: number) => Promise<VendorPortalDocumentStatus | undefined>;
   updateLocal: (
     updater: (current: VendorPortalDispatchDetail) => VendorPortalDispatchDetail,
   ) => void;
@@ -23,6 +27,7 @@ export function DispatchDetailSections({
   data,
   locked,
   refresh,
+  pollEvidenceDocument,
   updateLocal,
 }: DispatchDetailSectionsProps) {
   return (
@@ -65,6 +70,7 @@ export function DispatchDetailSections({
           upliftRequests={data.upliftRequests ?? []}
           locked={locked}
           onChanged={refresh}
+          pollDocument={pollEvidenceDocument}
         />
       </div>
 

src/app/v/[token]/dispatch/_components/uplift-request-card.tsx

@@ -0,0 +1,136 @@
+import { useState } from "react";
+import { Text } from "@/components/ui/text";
+import { UpliftRequestForm } from "@/app/v/[token]/dispatch/_components/uplift-request-form";
+import type { UpliftFormValues } from "@/domain/vendor-portal/lib/uplift-validation";
+import type { VendorPortalUpliftRequest } from "@/domain/vendor-portal/types/vendor-portal";
+import { formatDateTime } from "@/lib/time-utils";
+
+type UpliftRequestCardProps = {
+  request: VendorPortalUpliftRequest;
+  locked: boolean;
+  canAct: boolean;
+  uploadingPercent: number | undefined;
+  submitting: boolean;
+  errorMessage: string;
+  onWithdraw: (request: VendorPortalUpliftRequest) => void;
+  onRevise: (request: VendorPortalUpliftRequest, values: UpliftFormValues) => void;
+  onCancelRevise: () => void;
+};
+
+const WITHDRAWABLE_STATUSES = new Set(["Pending", "ChangesRequested"]);
+
+function statusClassName(status: string): string {
+  return `vp-uplift-status-${String(status).toLowerCase()}`;
+}
+
+export function UpliftRequestCard({
+  request,
+  locked,
+  canAct,
+  uploadingPercent,
+  submitting,
+  errorMessage,
+  onWithdraw,
+  onRevise,
+  onCancelRevise,
+}: UpliftRequestCardProps) {
+  const [revising, setRevising] = useState(false);
+  const canWithdraw = !locked && canAct && WITHDRAWABLE_STATUSES.has(request.status);
+  const canRevise = !locked && canAct && request.status === "ChangesRequested";
+
+  return (
+    <div className="vp-uplift-row">
+      <div className="vp-row">
+        <strong>Requested</strong>
+        <span>
+          ${Number(request.requestedNTE).toFixed(2)} (was $
+          {Number(request.currentNTE ?? 0).toFixed(2)})
+        </span>
+      </div>
+      <div className="vp-row">
+        <strong>Status</strong>
+        <span>
+          <span className={statusClassName(request.status)}>{request.status}</span>
+        </span>
+      </div>
+      {Boolean(request.expiresAt) && (
+        <div className="vp-row">
+          <strong>Expires</strong>
+          <span>{formatDateTime(request.expiresAt as string)}</span>
+        </div>
+      )}
+      {Boolean(request.vendorReason) && (
+        <div className="vp-row">
+          <strong>Reason</strong>
+          <span>{request.vendorReason}</span>
+        </div>
+      )}
+      {Boolean(request.evidenceFileName) && (
+        <div className="vp-row">
+          <strong>Evidence</strong>
+          <span>
+            {request.evidenceFileName}
+            {request.evidenceContentType ? ` · ${request.evidenceContentType}` : ""}
+          </span>
+        </div>
+      )}
+      {Boolean(request.decisionNote) && (
+        <div className="vp-row">
+          <strong>Decision</strong>
+          <span>
+            {request.decisionNote}
+            {request.decidedByName ? ` — ${request.decidedByName}` : ""}
+          </span>
+        </div>
+      )}
+      {request.notificationStatus === "Error" && Boolean(request.notificationError) && (
+        <div className="vp-row">
+          <strong>Notification</strong>
+          <span className="vp-error-inline">{request.notificationError}</span>
+        </div>
+      )}
+      <Text variant="error" when={Boolean(errorMessage)}>
+        {errorMessage}
+      </Text>
+
+      {revising && canRevise ? (
+        <UpliftRequestForm
+          mode="revise"
+          currentNte={request.currentNTE}
+          initialRequested={String(request.requestedNTE)}
+          initialReason={request.vendorReason ?? ""}
+          hasExistingEvidence={request.evidenceDocumentId != null}
+          submitting={submitting}
+          uploadingPercent={uploadingPercent}
+          errorMessage=""
+          onSubmit={(values) => onRevise(request, values)}
+          onCancel={() => {
+            setRevising(false);
+            onCancelRevise();
+          }}
+        />
+      ) : (
+        <div className="vp-actions">
+          {canWithdraw && (
+            <button
+              type="button"
+              className="vp-btn vp-btn-ghost"
+              onClick={() => onWithdraw(request)}
+            >
+              Withdraw request
+            </button>
+          )}
+          {canRevise && (
+            <button
+              type="button"
+              className="vp-btn vp-btn-primary"
+              onClick={() => setRevising(true)}
+            >
+              Revise
+            </button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

src/app/v/[token]/dispatch/_components/uplift-request-form.tsx

@@ -0,0 +1,148 @@
+import { useState } from "react";
+import { Text } from "@/components/ui/text";
+import { validateVendorDocument } from "@/domain/vendor-portal/lib/document-validation";
+import {
+  isApprovalRequired,
+  validateUpliftAmount,
+  type UpliftFormValues,
+} from "@/domain/vendor-portal/lib/uplift-validation";
+
+type UpliftRequestFormProps = {
+  mode: "create" | "revise";
+  currentNte?: number;
+  initialRequested?: string;
+  initialReason?: string;
+  hasExistingEvidence?: boolean;
+  submitting: boolean;
+  uploadingPercent: number | undefined;
+  errorMessage: string;
+  onSubmit: (values: UpliftFormValues) => void;
+  onCancel?: () => void;
+};
+
+export function UpliftRequestForm({
+  mode,
+  currentNte,
+  initialRequested = "",
+  initialReason = "",
+  hasExistingEvidence = false,
+  submitting,
+  uploadingPercent,
+  errorMessage,
+  onSubmit,
+  onCancel,
+}: UpliftRequestFormProps) {
+  const [requested, setRequested] = useState(initialRequested);
+  const [reason, setReason] = useState(initialReason);
+  const [evidenceFile, setEvidenceFile] = useState<File | undefined>();
+  const [formError, setFormError] = useState("");
+
+  const showApprovalFields = mode === "revise" || isApprovalRequired(requested, currentNte);
+
+  const submit = (event: React.FormEvent) => {
+    event.preventDefault();
+    const amount = Number.parseFloat(requested);
+    const validationError = validateUpliftAmount(requested, currentNte, reason, {
+      file: evidenceFile,
+      hasExisting: hasExistingEvidence,
+      mode,
+    });
+    setFormError(validationError);
+    if (validationError) {
+      return;
+    }
+    onSubmit({ amount, reason: reason.trim(), evidenceFile });
+  };
+
+  const chooseFile = (file?: File) => {
+    const validationMessage = file ? validateVendorDocument(file) : undefined;
+    setFormError(validationMessage ?? "");
+    setEvidenceFile(file);
+  };
+
+  const shownError = errorMessage || formError;
+  const busy = submitting || uploadingPercent !== undefined;
+
+  return (
+    <form
+      onSubmit={(event) => void submit(event)}
+      className="vp-uplift-form"
+      aria-label={mode === "revise" ? "Revise uplift request" : "Request NTE uplift"}
+    >
+      {mode === "create" && (
+        <div className="vp-row">
+          <strong>Current NTE</strong>
+          <span>${Number(currentNte ?? 0).toFixed(2)}</span>
+        </div>
+      )}
+      <div className="vp-row">
+        <strong>
+          <label htmlFor={`uplift-amount-${mode}`}>New total NTE</label>
+        </strong>
+        <input
+          id={`uplift-amount-${mode}`}
+          type="number"
+          step="0.01"
+          min="0"
+          className="vp-input"
+          value={requested}
+          onChange={(event) => {
+            setRequested(event.target.value);
+            setFormError("");
+          }}
+          placeholder="0.00"
+        />
+      </div>
+      {showApprovalFields && (
+        <>
+          <div className="vp-row">
+            <strong>
+              <label htmlFor={`uplift-reason-${mode}`}>Reason</label>
+            </strong>
+            <textarea
+              id={`uplift-reason-${mode}`}
+              className="vp-textarea"
+              value={reason}
+              onChange={(event) => {
+                setReason(event.target.value);
+                setFormError("");
+              }}
+              placeholder="Why is the uplift needed?"
+            />
+          </div>
+          <div className="vp-row">
+            <strong>
+              <label htmlFor={`uplift-evidence-${mode}`}>Evidence (PDF/JPG/PNG)</label>
+            </strong>
+            <input
+              id={`uplift-evidence-${mode}`}
+              type="file"
+              className="vp-input"
+              accept=".pdf,.jpg,.jpeg,.png,application/pdf,image/jpeg,image/png"
+              onChange={(event) => chooseFile(event.target.files?.[0])}
+            />
+          </div>
+        </>
+      )}
+      {uploadingPercent !== undefined && (
+        <div className="vp-row" role="status" aria-live="polite">
+          <strong>Uploading</strong>
+          <span>{uploadingPercent}%</span>
+        </div>
+      )}
+      <Text variant="error" when={Boolean(shownError)}>
+        {shownError}
+      </Text>
+      <div className="vp-actions">
+        <button type="submit" className="vp-btn vp-btn-primary" disabled={busy}>
+          {busy ? "Submitting…" : mode === "revise" ? "Submit revision" : "Request uplift"}
+        </button>
+        {mode === "revise" && (
+          <button type="button" className="vp-btn vp-btn-ghost" onClick={onCancel} disabled={busy}>
+            Cancel
+          </button>
+        )}
+      </div>
+    </form>
+  );
+}

src/app/v/[token]/dispatch/_components/uplift-requests-section.tsx

@@ -1,7 +1,20 @@
-import { useState } from "react";
-import { Text } from "@/components/ui/text";
+import { useCallback, useState } from "react";
+import { VendorPortalFeedback } from "@/app/v/_components/vendor-portal-feedback";
 import { vendorPortalApi } from "@/domain/vendor-portal/api/vendor-portal-api";
-import type { VendorPortalUpliftRequest } from "@/domain/vendor-portal/types/vendor-portal";
+import { createUpliftRequestKey } from "@/domain/vendor-portal/lib/request-key";
+import type {
+  VendorPortalDocumentStatus,
+  VendorPortalUpliftRequest,
+} from "@/domain/vendor-portal/types/vendor-portal";
+import { UpliftRequestForm } from "@/app/v/[token]/dispatch/_components/uplift-request-form";
+import type { UpliftFormValues } from "@/domain/vendor-portal/lib/uplift-validation";
+import { UpliftRequestCard } from "@/app/v/[token]/dispatch/_components/uplift-request-card";
+import {
+  useVendorUpliftEvidence,
+  type EvidenceScanState,
+} from "@/app/v/[token]/dispatch/_components/use-uplift-evidence";
+
+const ACTIVE_STATUSES = new Set(["Pending", "ChangesRequested"]);
 
 type UpliftRequestsSectionProps = {
   token: string;
@@ -10,20 +23,141 @@ type UpliftRequestsSectionProps = {
   upliftRequests: VendorPortalUpliftRequest[];
   locked: boolean;
   onChanged: () => Promise<void>;
+  pollDocument: (documentId: number) => Promise<VendorPortalDocumentStatus | undefined>;
 };
 
-function validateUpliftRequest(requested: string, currentNte: number | undefined, reason: string) {
-  const amount = Number.parseFloat(requested);
-  if (!Number.isFinite(amount) || amount <= 0) {
-    return "Enter a valid requested NTE amount.";
+type UseVendorUpliftActionsArgs = {
+  token: string;
+  dispatchId: number;
+  currentNte?: number;
+  onChanged: () => Promise<void>;
+  evidence: ReturnType<typeof useVendorUpliftEvidence>;
+};
+
+function scanErrorMessage(scan: EvidenceScanState): string {
+  if (scan === "Rejected") {
+    return "The evidence file was rejected by the security scan.";
   }
-  if (currentNte != null && amount <= currentNte) {
-    return `Requested NTE must be greater than the current NTE ($${currentNte.toFixed(2)}).`;
-  }
-  if (!reason.trim()) {
-    return "Please include a reason for the uplift request.";
-  }
-  return "";
+  return "Security scan timed out. Please try again once the file finishes scanning.";
+}
+
+function useVendorUpliftActions({
+  token,
+  dispatchId,
+  currentNte,
+  onChanged,
+  evidence,
+}: UseVendorUpliftActionsArgs) {
+  const [submitting, setSubmitting] = useState(false);
+  const [formError, setFormError] = useState("");
+  const [infoMessage, setInfoMessage] = useState("");
+  const [requestError, setRequestError] = useState("");
+  const [errorRequestId, setErrorRequestId] = useState<string | number | null>(null);
+
+  const uploadAndScan = useCallback(
+    async (file: File): Promise<{ documentId: number; scan: EvidenceScanState }> => {
+      const document = await evidence.uploadEvidence({ token, dispatchId, file });
+      const scan = await evidence.waitForScan(document.id);
+      evidence.setScanState(scan);
+      return { documentId: document.id, scan };
+    },
+    [evidence, token, dispatchId],
+  );
+
+  const handleCreate = async (values: UpliftFormValues) => {
+    setFormError("");
+    setInfoMessage("");
+    setSubmitting(true);
+    try {
+      const requiresApproval = currentNte == null || values.amount > (currentNte ?? 0);
+      let evidenceDocumentId: number | undefined;
+      if (requiresApproval) {
+        if (!values.evidenceFile) {
+          setFormError(
+            "Attach PDF, JPG, or PNG evidence — approval-required requests need evidence.",
+          );
+          return;
+        }
+        const result = await uploadAndScan(values.evidenceFile);
+        if (result.scan !== "Passed") {
+          setFormError(scanErrorMessage(result.scan));
+          return;
+        }
+        evidenceDocumentId = result.documentId;
+      }
+      const outcome = await vendorPortalApi.requestUplift(token, dispatchId, {
+        requestedNTE: values.amount,
+        reason: values.reason,
+        requestKey: createUpliftRequestKey(),
+        evidenceDocumentId,
+      });
+      evidence.reset();
+      await onChanged();
+      if (outcome.outcome === "NoApprovalRequired") {
+        setInfoMessage("No approval required — the existing NTE already covers this amount.");
+      }
+    } catch {
+      setFormError("Unable to request the NTE uplift. Please try again.");
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleWithdraw = async (request: VendorPortalUpliftRequest) => {
+    if (!window.confirm("Withdraw this uplift request?")) return;
+    setErrorRequestId(request.id);
+    setRequestError("");
+    setSubmitting(true);
+    try {
+      await vendorPortalApi.withdrawUplift(token, dispatchId, request.id);
+      await onChanged();
+    } catch {
+      setRequestError("Unable to withdraw the uplift request. Please try again.");
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleRevise = async (request: VendorPortalUpliftRequest, values: UpliftFormValues) => {
+    setErrorRequestId(request.id);
+    setRequestError("");
+    setSubmitting(true);
+    try {
+      const requiresApproval =
+        request.currentNTE == null || values.amount > (request.currentNTE ?? 0);
+      let evidenceDocumentId = request.evidenceDocumentId;
+      if (requiresApproval && values.evidenceFile) {
+        const result = await uploadAndScan(values.evidenceFile);
+        if (result.scan !== "Passed") {
+          setRequestError(scanErrorMessage(result.scan));
+          return;
+        }
+        evidenceDocumentId = result.documentId;
+      }
+      await vendorPortalApi.reviseUplift(token, dispatchId, request.id, {
+        requestedNTE: values.amount,
+        reason: values.reason,
+        evidenceDocumentId,
+      });
+      evidence.reset();
+      await onChanged();
+    } catch {
+      setRequestError("Unable to revise the uplift request. Please try again.");
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return {
+    submitting,
+    formError,
+    infoMessage,
+    requestError,
+    errorRequestId,
+    handleCreate,
+    handleWithdraw,
+    handleRevise,
+  };
 }
 
 export function UpliftRequestsSection({
@@ -33,136 +167,56 @@ export function UpliftRequestsSection({
   upliftRequests,
   locked,
   onChanged,
+  pollDocument,
 }: UpliftRequestsSectionProps) {
-  const [requested, setRequested] = useState("");
-  const [reason, setReason] = useState("");
-  const [submitting, setSubmitting] = useState(false);
-  const [errorMessage, setErrorMessage] = useState("");
+  const evidence = useVendorUpliftEvidence({ pollDocument });
+  const {
+    submitting,
+    formError,
+    infoMessage,
+    requestError,
+    errorRequestId,
+    handleCreate,
+    handleWithdraw,
+    handleRevise,
+  } = useVendorUpliftActions({ token, dispatchId, currentNte, onChanged, evidence });
 
-  const pending = upliftRequests.find((request) => request.status === "Pending");
-
-  const submit = async (event: React.FormEvent) => {
-    event.preventDefault();
-    const amount = Number.parseFloat(requested);
-    const validationError = validateUpliftRequest(requested, currentNte, reason);
-    setErrorMessage(validationError);
-    if (validationError) {
-      return;
-    }
-    setSubmitting(true);
-    try {
-      await vendorPortalApi.requestUplift(token, dispatchId, {
-        requestedNTE: amount,
-        reason: reason.trim(),
-      });
-      setRequested("");
-      setReason("");
-      await onChanged();
-    } catch {
-      setErrorMessage("Unable to request the NTE uplift. Please try again.");
-    } finally {
-      setSubmitting(false);
-    }
-  };
-
-  const cancel = async (requestId: number) => {
-    if (!window.confirm("Cancel this uplift request?")) return;
-    setErrorMessage("");
-    try {
-      await vendorPortalApi.cancelUplift(token, dispatchId, requestId);
-      await onChanged();
-    } catch {
-      setErrorMessage("Unable to cancel the NTE uplift request. Please try again.");
-    }
-  };
+  const activeRequest = upliftRequests.find((request) => ACTIVE_STATUSES.has(request.status));
+  const canShowForm = !locked && !activeRequest;
 
   return (
     <>
-      {upliftRequests.length === 0 && !pending && (
-        <div className="vp-muted" style={{ marginBottom: 12 }}>
+      {upliftRequests.length === 0 && !activeRequest && (
+        <VendorPortalFeedback>
           No uplift requests yet. Use the form below if the work will exceed the current NTE.
-        </div>
+        </VendorPortalFeedback>
       )}
+      {Boolean(infoMessage) && <VendorPortalFeedback>{infoMessage}</VendorPortalFeedback>}
 
       {upliftRequests.map((request) => (
-        <div key={request.id} className="vp-uplift-row">
-          <div className="vp-row">
-            <strong>Requested</strong>
-            <span>
-              ${Number(request.requestedNTE).toFixed(2)} (was $
-              {Number(request.currentNTE ?? 0).toFixed(2)})
-            </span>
-          </div>
-          <div className="vp-row">
-            <strong>Status</strong>
-            <span>
-              <span className={`vp-uplift-status-${String(request.status).toLowerCase()}`}>
-                {request.status}
-              </span>
-            </span>
-          </div>
-          {Boolean(request.vendorReason) && (
-            <div className="vp-row">
-              <strong>Reason</strong>
-              <span>{request.vendorReason}</span>
-            </div>
-          )}
-          {request.status === "Pending" && (
-            <div className="vp-actions">
-              <button
-                type="button"
-                className="vp-btn vp-btn-ghost"
-                onClick={() => void cancel(request.id)}
-              >
-                Cancel Request
-              </button>
-            </div>
-          )}
-        </div>
+        <UpliftRequestCard
+          key={request.id}
+          request={request}
+          locked={locked}
+          canAct={!locked}
+          uploadingPercent={evidence.uploadingPercent}
+          submitting={submitting}
+          errorMessage={errorRequestId === request.id ? requestError : ""}
+          onWithdraw={(r) => void handleWithdraw(r)}
+          onRevise={(r, values) => void handleRevise(r, values)}
+          onCancelRevise={evidence.reset}
+        />
       ))}
-      <Text variant="error" when={Boolean(errorMessage)}>
-        {errorMessage}
-      </Text>
 
-      {!locked && !pending && (
-        <form onSubmit={(event) => void submit(event)} style={{ marginTop: 12 }}>
-          <div className="vp-row">
-            <strong>Current NTE</strong>
-            <span>${Number(currentNte ?? 0).toFixed(2)}</span>
-          </div>
-          <div className="vp-row">
-            <strong>New total NTE</strong>
-            <input
-              type="number"
-              step="0.01"
-              min="0"
-              className="vp-input"
-              value={requested}
-              onChange={(event) => {
-                setRequested(event.target.value);
-                setErrorMessage("");
-              }}
-              placeholder="0.00"
-            />
-          </div>
-          <div className="vp-row">
-            <strong>Reason</strong>
-            <textarea
-              className="vp-textarea"
-              value={reason}
-              onChange={(event) => {
-                setReason(event.target.value);
-                setErrorMessage("");
-              }}
-              placeholder="Why is the uplift needed?"
-            />
-          </div>
-          <div className="vp-actions">
-            <button type="submit" className="vp-btn vp-btn-primary" disabled={submitting}>
-              {submitting ? "Submitting…" : "Request Uplift"}
-            </button>
-          </div>
-        </form>
+      {canShowForm && (
+        <UpliftRequestForm
+          mode="create"
+          currentNte={currentNte}
+          submitting={submitting}
+          uploadingPercent={evidence.uploadingPercent}
+          errorMessage={formError}
+          onSubmit={(values) => void handleCreate(values)}
+        />
       )}
     </>
   );

src/app/v/[token]/dispatch/_components/use-uplift-evidence.ts

@@ -0,0 +1,72 @@
+import { useCallback, useState } from "react";
+import { useMutation } from "@tanstack/react-query";
+import {
+  VENDOR_EVIDENCE_PURPOSE,
+  vendorPortalApi,
+} from "@/domain/vendor-portal/api/vendor-portal-api";
+import type { VendorPortalDocumentStatus } from "@/domain/vendor-portal/types/vendor-portal";
+
+const POLL_INTERVAL_MS = 1000;
+const MAX_POLL_ATTEMPTS = 30;
+
+export type EvidenceScanState = "Passed" | "Rejected" | "Timeout";
+
+export type UploadEvidenceArgs = {
+  token: string;
+  dispatchId: number;
+  file: File;
+};
+
+type UseVendorUpliftEvidenceOptions = {
+  pollDocument: (documentId: number) => Promise<VendorPortalDocumentStatus | undefined>;
+};
+
+export function useVendorUpliftEvidence({ pollDocument }: UseVendorUpliftEvidenceOptions) {
+  const [uploadingPercent, setUploadingPercent] = useState<number | undefined>();
+  const [scanState, setScanState] = useState<EvidenceScanState | undefined>();
+
+  const uploadMutation = useMutation({
+    mutationFn: ({ token, dispatchId, file }: UploadEvidenceArgs) =>
+      vendorPortalApi.uploadDocument({
+        token,
+        dispatchId,
+        file,
+        purpose: VENDOR_EVIDENCE_PURPOSE,
+        onProgress: setUploadingPercent,
+      }),
+  });
+
+  const waitForScan = useCallback(
+    async (documentId: number): Promise<EvidenceScanState> => {
+      for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt += 1) {
+        const document = await pollDocument(documentId);
+        if (document?.scanStatus === "Passed") {
+          return "Passed";
+        }
+        if (document?.scanStatus === "Rejected") {
+          return "Rejected";
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+      }
+      return "Timeout";
+    },
+    [pollDocument],
+  );
+
+  const reset = useCallback(() => {
+    setUploadingPercent(undefined);
+    setScanState(undefined);
+    uploadMutation.reset();
+  }, [uploadMutation]);
+
+  return {
+    uploadEvidence: uploadMutation.mutateAsync,
+    uploadError: uploadMutation.error ? "Unable to upload the evidence file." : undefined,
+    uploadingPercent,
+    scanState,
+    setScanState,
+    waitForScan,
+    isUploading: uploadMutation.isPending,
+    reset,
+  };
+}

src/app/v/_components/vendor-portal.css

@@ -300,6 +300,56 @@
   color: var(--status-pending-text);
 }
 
+.vp-uplift-status-approved {
+  display: inline-block;
+  padding: 3px 9px;
+  border-radius: 999px;
+  font-size: 12px;
+  font-weight: 600;
+  background: var(--status-completed-bg);
+  color: var(--status-completed-text);
+}
+
+.vp-uplift-status-rejected {
+  display: inline-block;
+  padding: 3px 9px;
+  border-radius: 999px;
+  font-size: 12px;
+  font-weight: 600;
+  background: var(--doc-no-bg);
+  color: var(--doc-no-text);
+}
+
+.vp-uplift-status-changesrequested {
+  display: inline-block;
+  padding: 3px 9px;
+  border-radius: 999px;
+  font-size: 12px;
+  font-weight: 600;
+  background: var(--status-scheduled-bg);
+  color: var(--status-scheduled-text);
+}
+
+.vp-uplift-status-withdrawn,
+.vp-uplift-status-expired {
+  display: inline-block;
+  padding: 3px 9px;
+  border-radius: 999px;
+  font-size: 12px;
+  font-weight: 600;
+  background: var(--input-background);
+  color: var(--muted-foreground);
+}
+
+.vp-uplift-form {
+  margin-top: 12px;
+}
+
+.vp-error-inline {
+  color: var(--doc-no-text);
+  font-weight: 600;
+}
+
 .vp-nav {
   background: var(--background);
   border-bottom: 1px solid var(--border);

src/components/common/comment-body-with-mentions.tsx

@@ -0,0 +1,44 @@
+import { useMemo } from "react";
+import { Box } from "@mui/material";
+import { Text } from "@/components/ui/text";
+import {
+  buildCommentBodySegments,
+  type MentionLookup,
+} from "@/domain/work-orders/utils/comment-mentions";
+
+type CommentBodyWithMentionsProps = {
+  text: string;
+  mentions?: string[];
+  users?: MentionLookup[];
+};
+
+export function CommentBodyWithMentions({ text, mentions, users }: CommentBodyWithMentionsProps) {
+  const segments = useMemo(
+    () => buildCommentBodySegments(text, mentions, users),
+    [text, mentions, users],
+  );
+
+  if (segments.length === 0) {
+    return null;
+  }
+
+  return (
+    <Text variant="description" as="span">
+      {segments.map((segment, index) => {
+        if (segment.type === "text") {
+          return <span key={`text-${index}`}>{segment.value}</span>;
+        }
+
+        return (
+          <Box
+            component="span"
+            key={`mention-${segment.userId}-${index}`}
+            className="font-semibold text-primary"
+          >
+            @{segment.label}
+          </Box>
+        );
+      })}
+    </Text>
+  );
+}

src/components/common/comment-mention-composer.tsx

@@ -0,0 +1,205 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  Box,
+  ClickAwayListener,
+  List,
+  ListItemButton,
+  Paper,
+  Popper,
+  TextField,
+} from "@mui/material";
+import {
+  filterMentionCandidates,
+  findActiveMentionQuery,
+  insertMentionToken,
+  type MentionLookup,
+} from "@/domain/work-orders/utils/comment-mentions";
+
+type CommentMentionComposerProps = {
+  value: string;
+  onChange: (value: string) => void;
+  candidates: MentionLookup[];
+  placeholder?: string;
+  disabled?: boolean;
+  rows?: number;
+  onSubmit?: () => void;
+};
+
+type MentionCandidateMenuProps = {
+  open: boolean;
+  anchorEl: HTMLElement | null;
+  candidates: MentionLookup[];
+  highlightIndex: number;
+  onSelect: (user: MentionLookup) => void;
+};
+
+function MentionCandidateMenu({
+  open,
+  anchorEl,
+  candidates,
+  highlightIndex,
+  onSelect,
+}: MentionCandidateMenuProps) {
+  return (
+    <Popper open={open} anchorEl={anchorEl} placement="bottom-start" className="z-50">
+      <Paper elevation={4} className="mt-1 max-h-48 overflow-y-auto">
+        <List dense disablePadding>
+          {candidates.map((candidate, index) => (
+            <ListItemButton
+              key={String(candidate.id)}
+              selected={index === highlightIndex}
+              onMouseDown={(event) => event.preventDefault()}
+              onClick={() => onSelect(candidate)}
+            >
+              @{candidate.name}
+            </ListItemButton>
+          ))}
+        </List>
+      </Paper>
+    </Popper>
+  );
+}
+
+export function CommentMentionComposer({
+  value,
+  onChange,
+  candidates,
+  placeholder = "Type a comment...",
+  disabled = false,
+  rows = 2,
+  onSubmit,
+}: CommentMentionComposerProps) {
+  const inputRef = useRef<HTMLTextAreaElement | HTMLInputElement>(null);
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null);
+  const [cursor, setCursor] = useState(0);
+  const [menuOpen, setMenuOpen] = useState(false);
+  const [highlightIndex, setHighlightIndex] = useState(0);
+
+  const activeQuery = useMemo(() => findActiveMentionQuery(value, cursor), [value, cursor]);
+
+  const filteredCandidates = useMemo(
+    () => filterMentionCandidates(candidates, activeQuery?.query ?? ""),
+    [activeQuery?.query, candidates],
+  );
+
+  const showMenu = Boolean(menuOpen && activeQuery && filteredCandidates.length > 0);
+
+  useEffect(() => {
+    setHighlightIndex(0);
+  }, [activeQuery?.query, activeQuery?.start]);
+
+  const syncCursor = useCallback((textOverride?: string) => {
+    const element = inputRef.current;
+    if (!element) {
+      return;
+    }
+
+    const text = textOverride ?? element.value;
+    const nextCursor = element.selectionStart ?? text.length;
+    setCursor(nextCursor);
+    setMenuOpen(Boolean(findActiveMentionQuery(text, nextCursor)));
+  }, []);
+
+  const handleChange = (nextValue: string) => {
+    onChange(nextValue);
+    requestAnimationFrame(() => {
+      syncCursor(nextValue);
+    });
+  };
+
+  const applyMention = useCallback(
+    (user: MentionLookup) => {
+      if (!activeQuery) {
+        return;
+      }
+
+      const { nextText, nextCursor } = insertMentionToken(value, activeQuery.start, cursor, user);
+      onChange(nextText);
+      setMenuOpen(false);
+      setHighlightIndex(0);
+
+      requestAnimationFrame(() => {
+        const element = inputRef.current;
+        if (!element) {
+          return;
+        }
+        element.focus();
+        element.setSelectionRange(nextCursor, nextCursor);
+        setCursor(nextCursor);
+      });
+    },
+    [activeQuery, cursor, onChange, value],
+  );
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    if (showMenu) {
+      if (event.key === "ArrowDown") {
+        event.preventDefault();
+        setHighlightIndex((current) => (current + 1) % filteredCandidates.length);
+        return;
+      }
+
+      if (event.key === "ArrowUp") {
+        event.preventDefault();
+        setHighlightIndex(
+          (current) => (current - 1 + filteredCandidates.length) % filteredCandidates.length,
+        );
+        return;
+      }
+
+      if (event.key === "Enter" && !event.shiftKey) {
+        event.preventDefault();
+        const selected = filteredCandidates[highlightIndex];
+        if (selected) {
+          applyMention(selected);
+        }
+        return;
+      }
+
+      if (event.key === "Escape") {
+        event.preventDefault();
+        setMenuOpen(false);
+        return;
+      }
+    }
+
+    if (event.key === "Enter" && (event.metaKey || event.ctrlKey) && onSubmit) {
+      event.preventDefault();
+      onSubmit();
+    }
+  };
+
+  return (
+    <ClickAwayListener onClickAway={() => setMenuOpen(false)}>
+      <Box
+        className="relative"
+        ref={(node: HTMLDivElement | null) => {
+          setAnchorEl(node);
+        }}
+      >
+        <TextField
+          inputRef={inputRef}
+          multiline
+          rows={rows}
+          fullWidth
+          value={value}
+          onChange={(event) => handleChange(event.target.value)}
+          onClick={() => syncCursor()}
+          onKeyUp={() => syncCursor()}
+          onSelect={() => syncCursor()}
+          onKeyDown={handleKeyDown}
+          placeholder={placeholder}
+          disabled={disabled}
+        />
+
+        <MentionCandidateMenu
+          open={showMenu}
+          anchorEl={anchorEl}
+          candidates={filteredCandidates}
+          highlightIndex={highlightIndex}
+          onSelect={applyMention}
+        />
+      </Box>
+    </ClickAwayListener>
+  );
+}

src/components/common/comment-timeline-mappers.ts

@@ -6,6 +6,7 @@ type CommentSource = {
   commenter?: string | null;
   createdDate?: string;
   commenttext: string;
+  mentions?: string[];
 };
 
 export function mapWorkOrderCommentsToTimeline(comments: CommentSource[]): CommentTimelineItem[] {
@@ -14,6 +15,7 @@ export function mapWorkOrderCommentsToTimeline(comments: CommentSource[]): Comme
     author: comment.userName || comment.commenter || "System",
     createdAt: comment.createdDate,
     body: comment.commenttext,
+    mentions: comment.mentions,
   }));
 }
 

src/components/common/comment-timeline.tsx

@@ -1,5 +1,8 @@
 import { useMemo } from "react";
-import { Box, Stack, Typography } from "@mui/material";
+import { Box, Stack } from "@mui/material";
+import { CommentBodyWithMentions } from "@/components/common/comment-body-with-mentions";
+import { Text } from "@/components/ui/text";
+import type { MentionLookup } from "@/domain/work-orders/utils/comment-mentions";
 import { formatDateTime } from "@/lib/time-utils";
 
 export type CommentTimelineItem = {
@@ -7,18 +10,20 @@ export type CommentTimelineItem = {
   author: string;
   createdAt?: string;
   body: string;
+  mentions?: string[];
 };
 
 type CommentTimelineProps = {
   items: CommentTimelineItem[];
   emptyMessage?: string;
   maxHeightClass?: string;
+  mentionUsers?: MentionLookup[];
 };
-
 export function CommentTimeline({
   items,
   emptyMessage = "No comments yet.",
   maxHeightClass = "max-h-72",
+  mentionUsers,
 }: CommentTimelineProps) {
   const sorted = useMemo(
     () =>
@@ -31,7 +36,7 @@ export function CommentTimeline({
   );
 
   if (!sorted.length) {
-    return <Typography color="text.secondary">{emptyMessage}</Typography>;
+    return <Text tone="muted">{emptyMessage}</Text>;
   }
 
   return (
@@ -39,14 +44,14 @@ export function CommentTimeline({
       {sorted.map((item) => (
         <Box key={String(item.id)} className="rounded border border-border p-3">
           <Stack direction="row" className="mb-1" sx={{ justifyContent: "space-between" }}>
-            <Typography variant="caption" className="font-semibold">
+            <Text variant="caption" className="font-semibold">
               {item.author}
-            </Typography>
-            <Typography variant="caption" color="text.secondary">
+            </Text>
+            <Text variant="caption" tone="muted">
               {item.createdAt ? formatDateTime(item.createdAt) : ""}
-            </Typography>
+            </Text>
           </Stack>
-          <Typography variant="body2">{item.body}</Typography>
+          <CommentBodyWithMentions text={item.body} mentions={item.mentions} users={mentionUsers} />
         </Box>
       ))}
     </Stack>

src/domain/uplifts/api/uplifts-api.ts

@@ -1,9 +1,9 @@
+import { HTTPError } from "ky";
 import { API_PATHS } from "@/api/api-paths";
-import { apiGet, apiPost } from "@/api/api";
+import { api, apiGet, apiPost } from "@/api/api";
 import { handleApiResponse } from "@/api/handle-api-response";
-import { mapUpliftQueueItems } from "@/domain/uplifts/mappers/uplift-mapper";
+import { mapUpliftQueueItems, mapUpliftRequests } from "@/domain/uplifts/mappers/uplift-mapper";
 import type { UpliftsQueueParams, UpliftsQueueResult } from "@/domain/uplifts/types/uplift";
-import { mapUpliftRequests } from "@/domain/work-orders/mappers/work-order-mapper";
 import type { UpliftRequest } from "@/domain/uplifts/types/uplift";
 
 function buildQueueParams(params: UpliftsQueueParams): Record<string, string | number> {
@@ -16,6 +16,26 @@ function buildQueueParams(params: UpliftsQueueParams): Record<string, string | n
   return searchParams;
 }
 
+function evidenceUrl(id: string | number): string {
+  return `${API_PATHS.rest.uplifts}/${id}/evidence`;
+}
+
+function readContentDispositionFilename(response: Response, fallback: string): string {
+  const disposition = response.headers.get("Content-Disposition") ?? "";
+  const match = /filename="?([^";]+)"?/i.exec(disposition);
+  return match ? match[1] : fallback;
+}
+
+function evidenceHttpError(status: number): Error {
+  if (status === 423) {
+    return new Error("Evidence is still being scanned. Try again shortly.");
+  }
+  if (status === 403) {
+    return new Error("You are not authorized to view this evidence.");
+  }
+  return new Error("Unable to download evidence right now.");
+}
+
 export const upliftsApi = {
   list: async (params: UpliftsQueueParams = {}): Promise<UpliftsQueueResult> => {
     const data = await apiGet<unknown>(API_PATHS.rest.uplifts, {
@@ -57,7 +77,35 @@ export const upliftsApi = {
     await apiPost<unknown>(`${API_PATHS.rest.uplifts}/${id}/approve`, { note });
   },
 
-  deny: async (id: string | number, note: string): Promise<void> => {
-    await apiPost<unknown>(`${API_PATHS.rest.uplifts}/${id}/deny`, { note });
+  reject: async (id: string | number, note: string): Promise<void> => {
+    await apiPost<unknown>(`${API_PATHS.rest.uplifts}/${id}/reject`, { note });
+  },
+
+  requestChanges: async (id: string | number, note: string): Promise<void> => {
+    await apiPost<unknown>(`${API_PATHS.rest.uplifts}/${id}/request-changes`, { note });
+  },
+
+  downloadEvidence: async (
+    id: string | number,
+    fallbackFileName = "uplift-evidence",
+  ): Promise<void> => {
+    let response: Response;
+    try {
+      response = await api.get(evidenceUrl(id));
+    } catch (error) {
+      if (error instanceof HTTPError) {
+        throw evidenceHttpError(error.response.status);
+      }
+      throw error;
+    }
+
+    const blob = await response.blob();
+    const fileName = readContentDispositionFilename(response, fallbackFileName);
+    const url = URL.createObjectURL(blob);
+    const anchor = window.document.createElement("a");
+    anchor.href = url;
+    anchor.download = fileName;
+    anchor.click();
+    URL.revokeObjectURL(url);
   },
 };

src/domain/uplifts/mappers/uplift-mapper.ts

@@ -1,5 +1,4 @@
-import type { UpliftQueueItem } from "@/domain/uplifts/types/uplift";
-import { mapUpliftRequest } from "@/domain/work-orders/mappers/work-order-mapper";
+import type { UpliftQueueItem, UpliftRequest } from "@/domain/uplifts/types/uplift";
 
 function asRecord(raw: unknown): Record<string, unknown> {
   return typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>) : {};
@@ -14,6 +13,21 @@ function readString(record: Record<string, unknown>, ...keys: string[]): string
   return "";
 }
 
+function readNumber(record: Record<string, unknown>, ...keys: string[]): number | null {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+    if (typeof value === "string" && value.trim() && Number.isFinite(Number(value))) {
+      return Number(value);
+    }
+  }
+  return null;
+}
+
+function readBool(record: Record<string, unknown>, ...keys: string[]): boolean {
+  return keys.some((key) => record[key] === true);
+}
+
 function readOptionalId(
   record: Record<string, unknown>,
   ...keys: string[]
@@ -25,6 +39,36 @@ function readOptionalId(
   return null;
 }
 
+export function mapUpliftRequest(raw: unknown): UpliftRequest {
+  const item = asRecord(raw);
+  return {
+    id: readOptionalId(item, "id", "Id") ?? "",
+    status: readString(item, "status", "Status"),
+    currentNTE: readNumber(item, "currentNTE", "CurrentNTE"),
+    requestedNTE: readNumber(item, "requestedNTE", "RequestedNTE") ?? 0,
+    delta: readNumber(item, "delta", "Delta") ?? 0,
+    vendorReason: readString(item, "vendorReason", "VendorReason"),
+    requestedAt: readString(item, "requestedAt", "RequestedAt"),
+    requestedByVendorName: readString(item, "requestedByVendorName", "RequestedByVendorName"),
+    decidedAt: readString(item, "decidedAt", "DecidedAt"),
+    decidedByName: readString(item, "decidedByName", "DecidedByName"),
+    decisionNote: readString(item, "decisionNote", "DecisionNote"),
+    requiredTier: readNumber(item, "requiredTier", "RequiredTier") ?? 1,
+    canDecide: readBool(item, "canDecide", "CanDecide"),
+    expiresAt: readString(item, "expiresAt", "ExpiresAt"),
+    notificationStatus: readString(item, "notificationStatus", "NotificationStatus"),
+    notificationError: readString(item, "notificationError", "NotificationError"),
+    evidenceDocumentId: readOptionalId(item, "evidenceDocumentId", "EvidenceDocumentId"),
+    evidenceFileName: readString(item, "evidenceFileName", "EvidenceFileName"),
+    evidenceContentType: readString(item, "evidenceContentType", "EvidenceContentType"),
+    evidenceSizeBytes: readNumber(item, "evidenceSizeBytes", "EvidenceSizeBytes"),
+  };
+}
+
+export function mapUpliftRequests(rawItems: unknown[]): UpliftRequest[] {
+  return rawItems.map(mapUpliftRequest);
+}
+
 export function mapUpliftQueueItem(raw: unknown): UpliftQueueItem {
   const base = mapUpliftRequest(raw);
   const item = asRecord(raw);

src/domain/uplifts/types/uplift.ts

@@ -1,3 +1,19 @@
+export const UPLIFT_STATUSES = [
+  "Pending",
+  "Approved",
+  "Rejected",
+  "ChangesRequested",
+  "Withdrawn",
+  "Expired",
+] as const;
+
+export type UpliftStatus = (typeof UPLIFT_STATUSES)[number];
+
+export const UPLIFT_DECISIONABLE_STATUSES = ["Pending"] as const;
+
+export const UPLIFT_NOTIFICATION_STATUSES = ["Pending", "Sent", "Error"] as const;
+export type UpliftNotificationStatus = (typeof UPLIFT_NOTIFICATION_STATUSES)[number];
+
 export interface UpliftRequest {
   id: string | number;
   status: string;
@@ -12,6 +28,13 @@ export interface UpliftRequest {
   decisionNote: string;
   requiredTier: number;
   canDecide: boolean;
+  expiresAt: string;
+  notificationStatus: string;
+  notificationError: string;
+  evidenceDocumentId: string | number | null;
+  evidenceFileName: string;
+  evidenceContentType: string;
+  evidenceSizeBytes: number | null;
 }
 
 export interface UpliftQueueItem extends UpliftRequest {

src/domain/uplifts/use-cases/use-uplift-actions.ts

@@ -38,7 +38,7 @@ export interface ApproveUpliftInput {
   note?: string;
 }
 
-export interface DenyUpliftInput {
+export interface DecisionUpliftInput {
   id: string | number;
   note: string;
 }
@@ -61,19 +61,38 @@ export function useApproveUplift(
   });
 }
 
-export function useDenyUplift(
+export function useRejectUplift(
   dispatchId?: string | number,
-): UseMutationResult<void, Error, DenyUpliftInput> {
+): UseMutationResult<void, Error, DecisionUpliftInput> {
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: ({ id, note }: { id: string | number; note: string }) => upliftsApi.deny(id, note),
+    mutationFn: ({ id, note }: { id: string | number; note: string }) =>
+      upliftsApi.reject(id, note),
     onSuccess: () => {
       invalidateUpliftQueries(queryClient, dispatchId);
-      toast.success("Uplift denied");
+      toast.success("Uplift rejected");
     },
     onError: (error: Error) => {
-      toast.error(error.message || "Failed to deny uplift");
+      toast.error(error.message || "Failed to reject uplift");
+    },
+  });
+}
+
+export function useRequestChangesUplift(
+  dispatchId?: string | number,
+): UseMutationResult<void, Error, DecisionUpliftInput> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ id, note }: { id: string | number; note: string }) =>
+      upliftsApi.requestChanges(id, note),
+    onSuccess: () => {
+      invalidateUpliftQueries(queryClient, dispatchId);
+      toast.success("Changes requested");
+    },
+    onError: (error: Error) => {
+      toast.error(error.message || "Failed to request changes");
     },
   });
 }

src/domain/vendor-portal/api/vendor-portal-api.ts

@@ -6,8 +6,12 @@ import type {
   VendorPortalDispatchDetail,
   VendorPortalDispatchSummary,
   VendorPortalDocument,
+  VendorPortalDocumentStatus,
   VendorPortalSession,
   VendorPortalSignoff,
+  VendorUpliftRequestBody,
+  VendorUpliftRequestOutcome,
+  VendorUpliftReviseBody,
 } from "@/domain/vendor-portal/types/vendor-portal";
 
 function resolveVendorPortalUrl(path: string): string {
@@ -15,11 +19,14 @@ function resolveVendorPortalUrl(path: string): string {
   return `${base}/${API_PATHS.vendorPortal.base}${path}`;
 }
 
+export const VENDOR_EVIDENCE_PURPOSE = "UpliftEvidence" as const;
+
 type UploadVendorDocumentOptions = {
   token: string;
   dispatchId: string | number;
   file: File;
   replacesDocumentId?: number;
+  purpose?: string;
   onProgress: (percent: number) => void;
 };
 
@@ -28,6 +35,7 @@ function uploadVendorDocument({
   dispatchId,
   file,
   replacesDocumentId,
+  purpose,
   onProgress,
 }: UploadVendorDocumentOptions): Promise<VendorPortalDocument> {
   return new Promise((resolve, reject) => {
@@ -51,6 +59,7 @@ function uploadVendorDocument({
     if (replacesDocumentId !== undefined) {
       body.append("replacesDocumentId", String(replacesDocumentId));
     }
+    body.append("purpose", purpose ?? "Completion");
     request.send(body);
   });
 }
@@ -106,6 +115,23 @@ async function vendorPortalCall<T>(
   return (payload.data ?? payload.Data ?? payload) as T;
 }
 
+function isNoApprovalRequired(payload: unknown): boolean {
+  if (typeof payload !== "object" || payload === null) return false;
+  const record = payload as Record<string, unknown>;
+  return (
+    record.outcome === "NoApprovalRequired" ||
+    record.status === "NoApprovalRequired" ||
+    record.noApprovalRequired === true
+  );
+}
+
+function toVendorUpliftOutcome(payload: unknown): VendorUpliftRequestOutcome {
+  if (isNoApprovalRequired(payload)) {
+    return { outcome: "NoApprovalRequired" };
+  }
+  return { outcome: "Created" };
+}
+
 export const vendorPortalApi = {
   session: (token: string) =>
     vendorPortalCall<VendorPortalSession>(token, API_PATHS.vendorPortal.session),
@@ -186,23 +212,41 @@ export const vendorPortalApi = {
       { method: "POST", body: { commentText } },
     ),
 
-  requestUplift: (
-    token: string,
-    id: string | number,
-    payload: { requestedNTE: number; reason: string },
-  ) =>
-    vendorPortalCall<void>(token, `${API_PATHS.vendorPortal.dispatches}/${id}/uplift-request`, {
-      method: "POST",
-      body: payload,
-    }),
+  requestUplift: (token: string, dispatchId: string | number, payload: VendorUpliftRequestBody) =>
+    vendorPortalCall<VendorUpliftRequestOutcome>(
+      token,
+      `${API_PATHS.vendorPortal.dispatches}/${dispatchId}/uplift-request`,
+      {
+        method: "POST",
+        body: payload,
+      },
+    ).then(toVendorUpliftOutcome),
 
-  cancelUplift: (token: string, id: string | number, requestId: string | number) =>
+  withdrawUplift: (token: string, dispatchId: string | number, requestId: string | number) =>
     vendorPortalCall<void>(
       token,
-      `${API_PATHS.vendorPortal.dispatches}/${id}/uplift-request/${requestId}/cancel`,
+      `${API_PATHS.vendorPortal.dispatches}/${dispatchId}/uplift-request/${requestId}/withdraw`,
       { method: "POST" },
     ),
 
+  reviseUplift: (
+    token: string,
+    dispatchId: string | number,
+    requestId: string | number,
+    payload: VendorUpliftReviseBody,
+  ) =>
+    vendorPortalCall<void>(
+      token,
+      `${API_PATHS.vendorPortal.dispatches}/${dispatchId}/uplift-request/${requestId}/revise`,
+      { method: "POST", body: payload },
+    ),
+
+  getDocumentStatus: (token: string, dispatchId: string | number, documentId: string | number) =>
+    vendorPortalCall<VendorPortalDocumentStatus>(
+      token,
+      `${API_PATHS.vendorPortal.dispatches}/${dispatchId}/documents/${documentId}/status`,
+    ),
+
   uploadDocument: uploadVendorDocument,
   downloadDocument: downloadVendorDocument,
 };

src/domain/vendor-portal/lib/request-key.ts

@@ -0,0 +1,6 @@
+export function createUpliftRequestKey(): string {
+  if (typeof globalThis.crypto?.randomUUID !== "function") {
+    throw new Error("Secure request identifiers are unavailable in this browser");
+  }
+  return globalThis.crypto.randomUUID();
+}

src/domain/vendor-portal/lib/uplift-validation.ts

@@ -0,0 +1,54 @@
+export type UpliftFormValues = {
+  amount: number;
+  reason: string;
+  evidenceFile?: File;
+};
+
+export type UpliftMode = "create" | "revise";
+
+export type UpliftValidationOptions = {
+  file?: File;
+  hasExisting?: boolean;
+  mode?: UpliftMode;
+};
+
+export function isApprovalRequired(
+  requested: string,
+  currentNte: number | undefined,
+  mode: UpliftMode = "create",
+): boolean {
+  const amount = Number.parseFloat(requested);
+  if (!Number.isFinite(amount)) {
+    return currentNte == null;
+  }
+  if (mode === "revise") {
+    return true;
+  }
+  return currentNte == null || amount > currentNte;
+}
+
+export function validateUpliftAmount(
+  requested: string,
+  currentNte: number | undefined,
+  reason: string,
+  options: UpliftValidationOptions = {},
+): string {
+  const mode = options.mode ?? "create";
+  const amount = Number.parseFloat(requested);
+  if (!Number.isFinite(amount) || amount <= 0) {
+    return "Enter a valid requested NTE amount.";
+  }
+  if (mode === "revise" && currentNte != null && amount <= currentNte) {
+    return `The revised NTE must be greater than the current NTE ($${currentNte.toFixed(2)}).`;
+  }
+  if (!isApprovalRequired(requested, currentNte, mode)) {
+    return "";
+  }
+  if (!reason.trim()) {
+    return "Please include a reason for the uplift request.";
+  }
+  if (!options.file && !options.hasExisting) {
+    return "Attach PDF, JPG, or PNG evidence — approval-required requests need evidence.";
+  }
+  return "";
+}

src/domain/vendor-portal/types/vendor-portal.ts

@@ -33,12 +33,18 @@ export interface VendorPortalDocument {
   rejectionReason?: string;
   version: number;
   replacesDocumentId?: number;
+  purpose?: string;
   createdDate?: string;
   scannedAt?: string;
   reviewedAt?: string;
   canDownload: boolean;
 }
 
+export type VendorPortalDocumentStatus = Pick<
+  VendorPortalDocument,
+  "id" | "originalFileName" | "scanStatus" | "reviewStatus" | "purpose"
+>;
+
 export interface VendorPortalChecklistItem {
   id: number;
   itemText: string;
@@ -65,6 +71,29 @@ export interface VendorPortalUpliftRequest {
   decidedByName?: string;
   decisionNote?: string;
   requiredTier?: number;
+  expiresAt?: string;
+  notificationStatus?: string;
+  notificationError?: string;
+  evidenceDocumentId?: number;
+  evidenceFileName?: string;
+  evidenceContentType?: string;
+  evidenceSizeBytes?: number;
+}
+
+export type VendorUpliftRequestOutcome =
+  { outcome: "NoApprovalRequired" } | { outcome: "Created"; request?: VendorPortalUpliftRequest };
+
+export interface VendorUpliftRequestBody {
+  requestedNTE: number;
+  reason: string;
+  requestKey: string;
+  evidenceDocumentId?: number;
+}
+
+export interface VendorUpliftReviseBody {
+  requestedNTE: number;
+  reason: string;
+  evidenceDocumentId?: number;
 }
 
 export interface VendorPortalSignoff {

src/domain/vendor-pos/mappers/vendor-po-mapper.ts

@@ -9,7 +9,7 @@ import type {
   VendorPoVendor,
   VendorPoWorkOrder,
 } from "@/domain/vendor-pos/types/vendor-po";
-import { mapUpliftRequests } from "@/domain/work-orders/mappers/work-order-mapper";
+import { mapUpliftRequests } from "@/domain/uplifts/mappers/uplift-mapper";
 
 function asRecord(raw: unknown): Record<string, unknown> {
   return typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>) : {};

src/domain/vendors/utils/build-technician-create-payload.ts

@@ -0,0 +1,36 @@
+import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
+import type { VendorFormValues } from "@/domain/vendors/schemas/vendor-schema";
+
+type BuildTechnicianCreatePayloadInput = {
+  companyVendor: Pick<VendorDropdownItem, "companyName" | "email" | "address" | "tradeSpecialties">;
+  contactName: string;
+  phone?: string;
+  companyId?: string | number | null;
+};
+
+/** Builds a vendor create payload for a new technician under an existing company. */
+export function buildTechnicianCreatePayload({
+  companyVendor,
+  contactName,
+  phone = "",
+  companyId = null,
+}: BuildTechnicianCreatePayloadInput): VendorFormValues {
+  return {
+    companyName: companyVendor.companyName,
+    contactName: contactName.trim(),
+    email: companyVendor.email ?? "",
+    phone: phone.trim(),
+    companyPhone: "",
+    googleMapsUrl: "",
+    notes: "",
+    totalJobs: 0,
+    address: companyVendor.address ?? "",
+    city: "",
+    state: "",
+    zip: "",
+    tradeSpecialties: companyVendor.tradeSpecialties ?? "",
+    isActive: true,
+    companyId,
+    preferredContact: "Phone",
+  };
+}

src/domain/vendors/utils/draft-vendor.ts

@@ -0,0 +1,21 @@
+import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
+import type { VendorFormValues } from "@/domain/vendors/schemas/vendor-schema";
+
+export const DRAFT_VENDOR_ID_PREFIX = "draft:";
+
+export function isDraftVendorId(id: string | number | null | undefined): boolean {
+  return String(id ?? "").startsWith(DRAFT_VENDOR_ID_PREFIX);
+}
+
+export function createDraftVendorDropdownItem(payload: VendorFormValues): VendorDropdownItem {
+  const email = (payload.email ?? "").trim();
+  return {
+    id: `${DRAFT_VENDOR_ID_PREFIX}${crypto.randomUUID()}`,
+    companyName: payload.companyName,
+    contactName: payload.contactName,
+    tradeSpecialties: payload.tradeSpecialties ?? "",
+    address: payload.address ?? "",
+    distanceMiles: null,
+    email: email || undefined,
+  };
+}

src/domain/vendors/utils/vendor-to-dropdown-item.ts

@@ -0,0 +1,15 @@
+import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
+import type { Vendor } from "@/domain/vendors/types/vendor";
+
+export function vendorToDropdownItem(vendor: Vendor): VendorDropdownItem {
+  const email = vendor.email.trim();
+  return {
+    id: vendor.id ?? "",
+    companyName: vendor.companyName,
+    contactName: vendor.contactName,
+    tradeSpecialties: vendor.tradeSpecialties,
+    address: vendor.address,
+    distanceMiles: null,
+    email: email || undefined,
+  };
+}

src/domain/work-orders/api/work-order-board-documents-api.ts

@@ -20,6 +20,11 @@ import type {
 } from "@/domain/work-orders/types/work-order-board-detail";
 import type { WorkOrderComment } from "@/domain/work-orders/types/work-order";
 
+export interface CreateWorkOrderCommentPayload {
+  text: string;
+  mentions?: string[];
+}
+
 async function readResponseJson(response: Response): Promise<unknown> {
   try {
     return await response.json();
@@ -57,8 +62,17 @@ export const workOrderBoardDocumentsApi = {
     return Array.isArray(items) ? items.map(mapBoardDetailComment) : [];
   },
 
-  createComment: async (workOrderId: string | number, text: string): Promise<WorkOrderComment> => {
-    const data = await apiPost<unknown>(API_PATHS.workOrder.comments(workOrderId), { text });
+  createComment: async (
+    workOrderId: string | number,
+    text: string,
+    mentions?: string[],
+  ): Promise<WorkOrderComment> => {
+    const payload: CreateWorkOrderCommentPayload = { text };
+    if (mentions && mentions.length > 0) {
+      payload.mentions = mentions.map(String);
+    }
+
+    const data = await apiPost<unknown>(API_PATHS.workOrder.comments(workOrderId), payload);
     return mapBoardDetailComment(handleApiResponse(data));
   },
 
@@ -126,9 +140,18 @@ export const workOrderBoardDocumentsApi = {
     workOrderId: string | number,
     mediaId: string | number,
     category: UploadableMediaCategory,
+    workOrderVersion: string,
   ): Promise<WorkOrderBoardMediaItem> => {
+    if (!workOrderVersion) {
+      throw new BoardPatchValidationError(
+        "WorkOrderVersionRequired",
+        "workOrderVersion is required to update media category.",
+      );
+    }
+
     const formData = new FormData();
     formData.append("category", category);
+    formData.append("workOrderVersion", workOrderVersion);
     const response = await api.patch(API_PATHS.workOrder.mediaItem(workOrderId, mediaId), {
       body: formData,
       throwHttpErrors: false,
@@ -140,7 +163,18 @@ export const workOrderBoardDocumentsApi = {
     throwDocumentHttpError(response, data);
   },
 
-  deleteMedia: async (workOrderId: string | number, mediaId: string | number): Promise<void> => {
+  deleteMedia: async (
+    workOrderId: string | number,
+    mediaId: string | number,
+    workOrderVersion: string,
+  ): Promise<void> => {
+    if (!workOrderVersion) {
+      throw new BoardPatchValidationError(
+        "WorkOrderVersionRequired",
+        "workOrderVersion is required to delete media.",
+      );
+    }
+
     const numericId = typeof mediaId === "number" ? mediaId : Number(mediaId);
     if (!Number.isFinite(numericId) || numericId <= 0) {
       throw new BoardPatchValidationError(
@@ -150,6 +184,7 @@ export const workOrderBoardDocumentsApi = {
     }
 
     const response = await api.delete(API_PATHS.workOrder.mediaItem(workOrderId, numericId), {
+      searchParams: { workOrderVersion },
       throwHttpErrors: false,
     });
 

src/domain/work-orders/mappers/doc-status-mapper.ts

@@ -0,0 +1,28 @@
+import type { CompletionDocStatus } from "@/domain/work-orders/types/work-order-table-row";
+
+/** UI uses `NN`; board/API enum uses `NotNeeded` (also numeric 3). */
+export function mapDocStatusToApi(value: string): string {
+  if (value === "NN") {
+    return "NotNeeded";
+  }
+  return value;
+}
+
+export function readDocStatusFromRecord(record: Record<string, unknown>): CompletionDocStatus {
+  const rawValue =
+    record.docStatus ?? record.DocStatus ?? record.completionDoc ?? record.CompletionDoc;
+  if (typeof rawValue === "number") {
+    if (rawValue === 1) return "Yes";
+    if (rawValue === 2) return "No";
+    if (rawValue === 3) return "NN";
+  }
+  if (typeof rawValue === "string") {
+    if (rawValue === "Yes" || rawValue === "No" || rawValue === "NN") {
+      return rawValue;
+    }
+    if (rawValue === "NotNeeded") {
+      return "NN";
+    }
+  }
+  return "";
+}

src/domain/work-orders/mappers/expand-scalar-board-ops.ts

@@ -1,17 +1,13 @@
 import type { WorkOrderBoardEditableField } from "@/domain/work-orders/types/work-order-board";
 import type { WorkOrderTablePatch } from "@/domain/work-orders/types/work-order-table-row";
+import { mapDocStatusToApi } from "@/domain/work-orders/mappers/doc-status-mapper";
 
 export type BoardFieldOp = {
   field: WorkOrderBoardEditableField;
   value: string;
 };
 
-export function mapDocStatusToApi(value: string): string {
-  if (value === "NN") {
-    return "NotNeeded";
-  }
-  return value;
-}
+export { mapDocStatusToApi };
 
 type ScalarBoardOpRule = {
   key: keyof WorkOrderTablePatch;

src/domain/work-orders/mappers/wizard-draft-mapper.ts

@@ -109,6 +109,7 @@ export function mapWizardDraftToFormValues(draft: WorkOrderWizardDraft): WorkOrd
     dueDate: draft.dueDate,
     scheduledDate: draft.scheduleWeekOnly ? "" : draft.scheduledOn,
     completedDate: "",
+    docStatus: "",
     assignedTo: draft.assigneeName,
     description: buildDescription(draft),
     po: "",

src/domain/work-orders/mappers/work-order-board-detail-mapper.ts

@@ -61,6 +61,33 @@ function readBoolean(record: Record<string, unknown>, ...keys: string[]): boolea
   return false;
 }
 
+function readStringArray(record: Record<string, unknown>, ...keys: string[]): string[] {
+  for (const key of keys) {
+    const value = record[key];
+    if (!Array.isArray(value)) {
+      continue;
+    }
+
+    const mapped = value
+      .map((entry) => {
+        if (typeof entry === "string") {
+          return entry;
+        }
+        if (typeof entry === "number" || typeof entry === "boolean") {
+          return String(entry);
+        }
+        return "";
+      })
+      .filter(Boolean);
+
+    if (mapped.length > 0) {
+      return mapped;
+    }
+  }
+
+  return [];
+}
+
 function mapDocStatus(raw: unknown): CompletionDocStatus {
   const numeric = typeof raw === "number" ? raw : Number(raw);
   if (numeric === DOC_STATUS_API.Yes) return "Yes";
@@ -93,6 +120,7 @@ export function mapBoardDetailComment(raw: unknown): WorkOrderComment {
     authorId,
     commenter: readString(item, "commenter", "Commenter") || null,
     recordType: readString(item, "recordType", "RecordType") || null,
+    mentions: readStringArray(item, "mentions", "Mentions"),
   };
 }
 

src/domain/work-orders/mappers/work-order-mapper.ts

@@ -1,3 +1,4 @@
+import { readDocStatusFromRecord } from "@/domain/work-orders/mappers/doc-status-mapper";
 import { parseSiteCodeFromLocationName } from "@/domain/work-orders/mappers/work-order-board-mapper";
 import type {
   EmployeeOption,
@@ -10,11 +11,12 @@ import type {
   WorkOrderFormValues,
   WorkOrderListItem,
 } from "@/domain/work-orders/types/work-order";
-import type { UpliftRequest } from "@/domain/uplifts/types/uplift";
 import type { WorkOrderStatus } from "@/domain/work-orders/types/work-order-common";
 import { WORK_ORDER_STATUS_OPTIONS } from "@/domain/work-orders/types/work-order-common";
 import { toDateInputValue } from "@/lib/time-utils";
 
+export { mapDocStatusToApi } from "@/domain/work-orders/mappers/doc-status-mapper";
+
 function asRecord(raw: unknown): Record<string, unknown> {
   return typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>) : {};
 }
@@ -215,15 +217,24 @@ export { mapWorkOrderTableRow, mapWorkOrderTableRows } from "./work-order-table-
 
 export function mapWorkOrderComment(raw: unknown): WorkOrderComment {
   const item = asRecord(raw);
+  const authorId = readString(item, "authorId", "AuthorId") || null;
+  const mentionsRaw = item.mentions ?? item.Mentions;
+  const mentions = Array.isArray(mentionsRaw)
+    ? mentionsRaw
+        .map((entry) => (typeof entry === "string" ? entry : String(entry)))
+        .filter(Boolean)
+    : undefined;
 
   return {
     id: readId(item),
     createdDate: readString(item, "createdDate", "CreatedDate"),
     commenttext: readString(item, "commenttext", "Commenttext", "text", "Text"),
     commentType: readString(item, "commentType", "CommentType"),
-    userName: readString(item, "userName", "UserName"),
+    userName: readString(item, "userName", "UserName", "authorName", "AuthorName"),
+    authorId,
     commenter: readString(item, "commenter", "Commenter") || null,
     recordType: readString(item, "recordType", "RecordType") || null,
+    mentions,
   };
 }
 
@@ -303,6 +314,8 @@ export function mapWorkOrderDetail(raw: unknown): WorkOrderDetail {
     vendorNTE: wo.vendorNTE != null ? String(wo.vendorNTE) : "",
     scheduledDate: toDateInputValue(readString(wo, "scheduledDate", "ScheduledDate")),
     completedDate: toDateInputValue(readString(wo, "completedDate", "CompletedDate")),
+    // DocStatus is a board field — persist via PATCH …/board, not EditWorkorder.
+    docStatus: readDocStatusFromRecord(wo),
     source: readString(wo, "source", "Source"),
     ...(contactIds !== undefined ? { contactIds } : {}),
     ...(categoryIds !== undefined ? { categoryIds } : {}),
@@ -336,6 +349,7 @@ export function mapWorkOrderDetailToFormValues(detail: WorkOrderDetail): WorkOrd
     dueDate: detail.dueDate,
     scheduledDate: detail.scheduledDate,
     completedDate: detail.completedDate,
+    docStatus: detail.docStatus,
     assignedTo: detail.assignedTo,
     description: detail.description,
     po: detail.po,
@@ -455,27 +469,3 @@ export {
   mapDispatchWorkOrderRef,
   mapUpdateDispatchPayload,
 } from "./work-order-dispatch-mapper";
-
-export function mapUpliftRequest(raw: unknown): UpliftRequest {
-  const item = asRecord(raw);
-
-  return {
-    id: readId(item),
-    status: readString(item, "status", "Status"),
-    currentNTE: readNumber(item, "currentNTE", "CurrentNTE"),
-    requestedNTE: readNumber(item, "requestedNTE", "RequestedNTE") ?? 0,
-    delta: readNumber(item, "delta", "Delta") ?? 0,
-    vendorReason: readString(item, "vendorReason", "VendorReason"),
-    requestedAt: readString(item, "requestedAt", "RequestedAt"),
-    requestedByVendorName: readString(item, "requestedByVendorName", "RequestedByVendorName"),
-    decidedAt: readString(item, "decidedAt", "DecidedAt"),
-    decidedByName: readString(item, "decidedByName", "DecidedByName"),
-    decisionNote: readString(item, "decisionNote", "DecisionNote"),
-    requiredTier: readNumber(item, "requiredTier", "RequiredTier") ?? 1,
-    canDecide: readBool(item, "canDecide", "CanDecide"),
-  };
-}
-
-export function mapUpliftRequests(rawItems: unknown[]): UpliftRequest[] {
-  return rawItems.map(mapUpliftRequest);
-}

src/domain/work-orders/mocks/wo-wizard-mock-data.ts

@@ -153,6 +153,7 @@ export function buildMockWorkOrderDetail(values: WorkOrderFormValues): WorkOrder
     vendorNTE: values.vendorNTE,
     scheduledDate: values.scheduledDate,
     completedDate: values.completedDate,
+    docStatus: values.docStatus ?? "",
     source: values.source,
     comments: [],
     auditLog: [],

src/domain/work-orders/types/work-order-board-detail.ts

@@ -94,6 +94,7 @@ export interface WorkOrderBoardDetailCommentApi {
   text?: string | null;
   time?: string | null;
   documents?: unknown;
+  mentions?: string[] | null;
 }
 
 export interface WorkOrderBoardDetailAuditApi {

src/domain/work-orders/types/work-order-board-patch.ts

@@ -0,0 +1,8 @@
+/** Payload for PATCH /workorders/{id}/board (one field per request). */
+export interface WorkOrderBoardPatchPayload {
+  field: string;
+  value?: string | null;
+  workOrderVersion: string;
+  dispatchVersion?: string | null;
+  primaryDispatchId?: number | null;
+}

src/domain/work-orders/types/work-order-detail.ts

@@ -1,5 +1,6 @@
 import type { WorkOrderCommentType, WorkOrderPriority, WorkOrderStatus } from "./work-order-common";
 import type { WorkOrderDispatchSummary } from "./dispatch";
+import type { CompletionDocStatus } from "./work-order-table-row";
 
 export interface WorkOrderComment {
   id: string | number;
@@ -11,6 +12,8 @@ export interface WorkOrderComment {
   authorId?: string | null;
   commenter: string | null;
   recordType: string | null;
+  /** Mentioned user ids when returned by board comments API. */
+  mentions?: string[];
 }
 
 export interface WorkOrderAuditEntry {
@@ -49,6 +52,8 @@ export interface WorkOrderDetail {
   vendorNTE: string;
   scheduledDate: string;
   completedDate: string;
+  /** Completion-document status (API DocStatus); persisted via board PATCH. */
+  docStatus: CompletionDocStatus;
   source: string;
   /** Present when GetById returns contacts; used to re-send on edit so backend does not wipe. */
   contactIds?: number[];
@@ -70,6 +75,8 @@ export interface WorkOrderFormValues {
   dueDate: string;
   scheduledDate: string;
   completedDate: string;
+  /** Optional: absent from the wizard's zod-validated shape, present once loaded from the server. */
+  docStatus?: CompletionDocStatus;
   assignedTo: string;
   description: string;
   po: string;
@@ -97,6 +104,7 @@ export function createDefaultWorkOrderFormValues(): WorkOrderFormValues {
     dueDate: "",
     scheduledDate: "",
     completedDate: "",
+    docStatus: "",
     assignedTo: "",
     description: "",
     po: "",

src/domain/work-orders/use-cases/use-work-order-mutations.ts

@@ -40,6 +40,7 @@ function invalidateBoardDetail(
 
 export interface AddWorkOrderCommentInput {
   text: string;
+  mentions?: string[];
   commentType?: "customer" | "internal";
 }
 
@@ -58,6 +59,12 @@ export interface UploadWorkOrderMediaInput {
 export interface UpdateWorkOrderMediaCategoryInput {
   mediaId: string | number;
   category: UploadableMediaCategory;
+  workOrderVersion: string;
+}
+
+export interface DeleteWorkOrderMediaInput {
+  mediaId: string | number;
+  workOrderVersion: string;
 }
 
 export interface UploadCompletionDocInput {
@@ -85,12 +92,12 @@ export interface AddDispatchSignoffInput {
   signatureMethod: string;
 }
 
-interface ChangeWorkOrderAssignmentInput {
+export interface ChangeWorkOrderAssignmentInput {
   userId: string | number;
   userName: string;
 }
 
-interface UpdateWorkOrderVendorInput {
+export interface UpdateWorkOrderVendorInput {
   vendorId: string | number;
   payload: WorkOrderVendorUpdatePayload;
 }
@@ -164,8 +171,8 @@ export function useAddWorkOrderComment(
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: ({ text }: AddWorkOrderCommentInput) =>
-      workOrdersApi.createComment(workOrderId, text),
+    mutationFn: ({ text, mentions }: AddWorkOrderCommentInput) =>
+      workOrdersApi.createComment(workOrderId, text, mentions),
     onSuccess: () => {
       invalidateBoardDetail(queryClient, workOrderId);
     },
@@ -217,8 +224,8 @@ export function useUpdateWorkOrderMediaCategory(
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: ({ mediaId, category }: UpdateWorkOrderMediaCategoryInput) =>
-      workOrdersApi.updateMediaCategory(workOrderId, mediaId, category),
+    mutationFn: ({ mediaId, category, workOrderVersion }: UpdateWorkOrderMediaCategoryInput) =>
+      workOrdersApi.updateMediaCategory(workOrderId, mediaId, category, workOrderVersion),
     onSuccess: () => {
       invalidateBoardDetail(queryClient, workOrderId);
       invalidateWorkOrders(queryClient);
@@ -232,11 +239,12 @@ export function useUpdateWorkOrderMediaCategory(
 
 export function useDeleteWorkOrderMedia(
   workOrderId: string | number,
-): UseMutationResult<void, Error, string | number> {
+): UseMutationResult<void, Error, DeleteWorkOrderMediaInput> {
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: (mediaId: string | number) => workOrdersApi.deleteMedia(workOrderId, mediaId),
+    mutationFn: ({ mediaId, workOrderVersion }: DeleteWorkOrderMediaInput) =>
+      workOrdersApi.deleteMedia(workOrderId, mediaId, workOrderVersion),
     onSuccess: () => {
       invalidateBoardDetail(queryClient, workOrderId);
       invalidateWorkOrders(queryClient);

src/domain/work-orders/utils/comment-mentions.ts

@@ -0,0 +1,188 @@
+/** Encoded mention token stored in comment text: `@[userId:Display Name]`. */
+export const MENTION_TOKEN_PATTERN = /@\[([^:\]]+):([^\]]+)\]/g;
+
+export type CommentBodySegment =
+  { type: "text"; value: string } | { type: "mention"; userId: string; label: string };
+
+export type MentionLookup = {
+  id: string | number;
+  name: string;
+};
+
+export function encodeMentionToken(userId: string | number, userName: string): string {
+  const trimmedName = userName.trim();
+  return `@[${String(userId)}:${trimmedName}]`;
+}
+
+export function extractMentionIds(text: string): string[] {
+  const ids: string[] = [];
+  const pattern = new RegExp(MENTION_TOKEN_PATTERN.source, "g");
+
+  for (const match of text.matchAll(pattern)) {
+    const userId = match[1];
+    if (userId && !ids.includes(userId)) {
+      ids.push(userId);
+    }
+  }
+
+  return ids;
+}
+
+export function toDisplayText(text: string): string {
+  return text.replace(MENTION_TOKEN_PATTERN, (_full, _userId: string, userName: string) => {
+    return `@${userName}`;
+  });
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function pushTextSegment(segments: CommentBodySegment[], value: string): void {
+  if (!value) {
+    return;
+  }
+
+  const last = segments.length > 0 ? segments[segments.length - 1] : undefined;
+  if (last?.type === "text") {
+    last.value += value;
+    return;
+  }
+
+  segments.push({ type: "text", value });
+}
+
+function resolveMentionNames(
+  mentionIds: string[] | undefined,
+  users: MentionLookup[] | undefined,
+): Map<string, string> {
+  const byId = new Map<string, string>();
+  const usersById = new Map((users ?? []).map((user) => [String(user.id), user.name] as const));
+
+  // Only ids that were actually mentioned — never seed the full dispatcher roster.
+  for (const mentionId of mentionIds ?? []) {
+    const id = String(mentionId);
+    byId.set(id, usersById.get(id) ?? id);
+  }
+
+  return byId;
+}
+
+function appendPlainMentionMatches(
+  segments: CommentBodySegment[],
+  plainText: string,
+  mentionNames: string[],
+): void {
+  if (!plainText || mentionNames.length === 0) {
+    pushTextSegment(segments, plainText);
+    return;
+  }
+
+  const sortedNames = [...mentionNames].sort((a, b) => b.length - a.length);
+  const namePattern = sortedNames.map((name) => escapeRegExp(name)).join("|");
+  // Require a non-word boundary after the name so "@Ann" does not match inside "@Annual".
+  const mentionRegex = new RegExp(`@(${namePattern})(?![\\w])`, "g");
+
+  let cursor = 0;
+  for (const match of plainText.matchAll(mentionRegex)) {
+    const index = match.index ?? 0;
+    pushTextSegment(segments, plainText.slice(cursor, index));
+
+    const label = match[1] ?? "";
+    segments.push({ type: "mention", userId: label, label });
+    cursor = index + match[0].length;
+  }
+
+  pushTextSegment(segments, plainText.slice(cursor));
+}
+
+export function buildCommentBodySegments(
+  text: string,
+  mentionIds?: string[],
+  users?: MentionLookup[],
+): CommentBodySegment[] {
+  if (!text) {
+    return [];
+  }
+
+  const segments: CommentBodySegment[] = [];
+  const encodedPattern = new RegExp(MENTION_TOKEN_PATTERN.source, "g");
+  const mentionNameById = resolveMentionNames(mentionIds, users);
+  const encodedLabels: string[] = [];
+  for (const match of text.matchAll(new RegExp(MENTION_TOKEN_PATTERN.source, "g"))) {
+    const label = match[2]?.trim();
+    if (label) encodedLabels.push(label);
+  }
+  const mentionNames = [...new Set([...mentionNameById.values(), ...encodedLabels])].filter(
+    Boolean,
+  );
+  let cursor = 0;
+
+  for (const match of text.matchAll(encodedPattern)) {
+    const index = match.index ?? 0;
+    const plainBetween = text.slice(cursor, index);
+    appendPlainMentionMatches(segments, plainBetween, mentionNames);
+
+    const userId = match[1] ?? "";
+    const label = match[2] ?? userId;
+    segments.push({ type: "mention", userId, label });
+    cursor = index + match[0].length;
+  }
+
+  const trailingPlain = text.slice(cursor);
+  appendPlainMentionMatches(segments, trailingPlain, mentionNames);
+
+  return segments.length > 0 ? segments : [{ type: "text", value: text }];
+}
+
+export type ActiveMentionQuery = {
+  start: number;
+  query: string;
+};
+
+export function findActiveMentionQuery(text: string, cursor: number): ActiveMentionQuery | null {
+  const beforeCursor = text.slice(0, cursor);
+  const atIndex = beforeCursor.lastIndexOf("@");
+
+  if (atIndex < 0) {
+    return null;
+  }
+
+  const prefix = beforeCursor.slice(0, atIndex);
+  const lastPrefixChar = prefix.length > 0 ? prefix[prefix.length - 1] : "";
+  if (prefix.length > 0 && !/\s/.test(lastPrefixChar)) {
+    return null;
+  }
+
+  const query = beforeCursor.slice(atIndex + 1);
+  if (/[\n\r\t[\]]/.test(query)) {
+    return null;
+  }
+
+  return { start: atIndex, query };
+}
+
+export function filterMentionCandidates(
+  candidates: MentionLookup[],
+  query: string,
+): MentionLookup[] {
+  const normalized = query.trim().toLowerCase();
+  const filtered = normalized
+    ? candidates.filter((candidate) => candidate.name.toLowerCase().includes(normalized))
+    : candidates;
+
+  return filtered.slice(0, 8);
+}
+
+export function insertMentionToken(
+  text: string,
+  queryStart: number,
+  cursor: number,
+  user: MentionLookup,
+): { nextText: string; nextCursor: number } {
+  const token = `${encodeMentionToken(user.id, user.name)} `;
+  const nextText = `${text.slice(0, queryStart)}${token}${text.slice(cursor)}`;
+  const nextCursor = queryStart + token.length;
+
+  return { nextText, nextCursor };
+}

src/domain/work-orders/utils/completion-doc-service-gate.ts

@@ -0,0 +1,4 @@
+/** CompDoc is gated on a selected primary service (`pm`). */
+export function hasCompletionDocService(pm: string | null | undefined): boolean {
+  return Boolean(pm?.trim());
+}

src/domain/work-orders/utils/completion-doc-service-title.ts

@@ -17,15 +17,12 @@ const SERVICE_PHRASE: Record<string, string> = {
   "Assess Window Leaks": "Window Leak Assessment",
 };
 
-const FREQ_CYCLE = ["13 Week", "26 Week", "52 Week"];
-
-function hashNum(s: string, mod: number): number {
-  let h = 0;
-  for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) >>> 0;
-  return h % mod;
-}
-
-export function serviceTitle(row: Pick<WorkOrderTableRow, "pm" | "woNumber">): string {
-  const phrase = SERVICE_PHRASE[row.pm] ?? row.pm;
-  return `Amer-Building ${phrase} — ${FREQ_CYCLE[hashNum(row.woNumber, FREQ_CYCLE.length)]}`;
+/**
+ * Title derived only from the selected service (`pm`).
+ * Never fabricates maintenance-cycle metadata from the work-order number.
+ */
+export function serviceTitle(row: Pick<WorkOrderTableRow, "pm">): string {
+  const service = row.pm.trim();
+  const phrase = SERVICE_PHRASE[service] ?? service;
+  return `Amer-Building ${phrase}`;
 }

src/infra/query-key/query-key.ts

@@ -88,6 +88,7 @@ export const queryKeys = {
       [...queryKeys.uplifts.all, "queue", params ?? {}] as const,
     forDispatch: (dispatchId: string | number) =>
       [...queryKeys.uplifts.all, "dispatch", dispatchId] as const,
+    evidence: (id: string | number) => [...queryKeys.uplifts.all, "evidence", id] as const,
   },
   vendorPos: {
     all: ["vendorPos"] as const,

src/test/app/(protected)/workorders/comp-doc-cell-service-gate.test.tsx

@@ -0,0 +1,29 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { CompDocCell } from "@/app/(protected)/workorders/_components/list/table/cells/comp-doc-cell";
+
+describe("CompDocCell service gate", () => {
+  it("shows a disabled placeholder when no service is selected", () => {
+    const onOpen = vi.fn();
+    render(<CompDocCell status="No" woType="PM" pm="" onOpen={onOpen} onOpenMedia={vi.fn()} />);
+
+    expect(screen.getByText("Select service")).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: /draft|view doc|n\/n/i })).not.toBeInTheDocument();
+  });
+
+  it("opens CompDoc when a service is selected", () => {
+    const onOpen = vi.fn();
+    render(
+      <CompDocCell
+        status="No"
+        woType="PM"
+        pm="HVAC Inspection"
+        onOpen={onOpen}
+        onOpenMedia={vi.fn()}
+      />,
+    );
+
+    screen.getByRole("button", { name: /draft/i }).click();
+    expect(onOpen).toHaveBeenCalledTimes(1);
+  });
+});

src/test/app/(protected)/workorders/resolve-technician-key.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { resolveTechnicianKey } from "@/app/(protected)/workorders/_components/list/table/cells/resolve-technician-key";
+import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
+
+const vendors: VendorDropdownItem[] = [
+  {
+    id: 10,
+    companyName: "Gateway Plumbing",
+    contactName: "Jordan Lee",
+    tradeSpecialties: "Plumbing",
+    address: "1 Main St",
+    distanceMiles: 4.2,
+    email: "dispatch@gateway.test",
+  },
+  {
+    id: 11,
+    companyName: "Gateway Plumbing",
+    contactName: "Adam Whyte",
+    tradeSpecialties: "Plumbing",
+    address: "1 Main St",
+    distanceMiles: 4.2,
+    email: "dispatch@gateway.test",
+  },
+];
+
+describe("resolveTechnicianKey", () => {
+  it("prefers a stable vendorId when it exists in the list", () => {
+    expect(resolveTechnicianKey(11, "Jordan Lee", "Gateway Plumbing", vendors)).toBe("11");
+  });
+
+  it("falls back to name+company when vendorId is missing", () => {
+    expect(resolveTechnicianKey("", "Jordan Lee", "Gateway Plumbing", vendors)).toBe("10");
+  });
+
+  it("keeps orphan tech string as key when no vendor matches", () => {
+    expect(resolveTechnicianKey("", "Unknown Tech", "Gateway Plumbing", vendors)).toBe(
+      "Unknown Tech",
+    );
+  });
+
+  it("keeps vendorId when the vendors list is still empty", () => {
+    expect(resolveTechnicianKey(42, "Jordan Lee", "Gateway Plumbing", [])).toBe("42");
+  });
+});

src/test/app/(protected)/workorders/use-comp-doc-dialog-address-seed.test.tsx

@@ -0,0 +1,148 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ReactNode } from "react";
+import { useCompDocDialog } from "@/app/(protected)/workorders/_hooks/use-comp-doc-dialog";
+import type { Location } from "@/domain/locations/types/location";
+import type { WorkOrderTableRow } from "@/domain/work-orders/types/work-order-table-row";
+
+const locationDetailState = vi.hoisted(() => ({
+  data: undefined as Location | undefined,
+}));
+
+vi.mock("@/domain/locations/use-cases/use-location-detail", () => ({
+  useLocationDetail: () => ({ data: locationDetailState.data }),
+}));
+
+function baseRow(overrides: Partial<WorkOrderTableRow> = {}): WorkOrderTableRow {
+  return {
+    id: 42,
+    woNumber: "WO-42",
+    site: "SEA1",
+    type: "PM",
+    dispatcherId: "u1",
+    dispatcherName: "Dispatcher",
+    scheduledOn: "2026-06-01",
+    completedDate: "",
+    targetWeek: "",
+    dayGroup: "",
+    dayLabel: "",
+    location: "Seattle",
+    locationId: "loc-real-1",
+    pm: "HVAC",
+    serviceNotes: "",
+    extraServices: [],
+    vendorId: "",
+    company: "Vendor Co",
+    tech: "Tech One",
+    techPhone: "",
+    apptStart: "",
+    apptEnd: "",
+    apptTime: "",
+    status: "Scheduled",
+    docStatus: "No",
+    pocName: "Amazon Rep",
+    pocPhone: "",
+    pocNotes: "",
+    dueDate: "",
+    rescheduleCount: 0,
+    carriedOver: 0,
+    originalWeek: "",
+    originalDate: "",
+    isPastDue: false,
+    scheduleWeekOnly: false,
+    mediaCount: 0,
+    title: "PM — SEA1",
+    priority: "Sev 3",
+    primaryDispatchId: null,
+    rowVersion: "",
+    dispatchRowVersion: "",
+    flagColor: null,
+    ...overrides,
+  };
+}
+
+function wrapper({ children }: { children: ReactNode }) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
+}
+
+describe("useCompDocDialog address seeding", () => {
+  beforeEach(() => {
+    locationDetailState.data = undefined;
+  });
+
+  it("seeds address from the first authoritative locationDetail without locking on the empty fallback", async () => {
+    const row = baseRow();
+    const { result, rerender } = renderHook(
+      () =>
+        useCompDocDialog({
+          row,
+          open: true,
+          onSave: vi.fn(),
+        }),
+      { wrapper },
+    );
+
+    expect(result.current.editAddress).toBe("");
+
+    locationDetailState.data = {
+      id: "loc-real-1",
+      name: "SEA1",
+      address: "3811 Distribution Dr",
+      city: "Seattle",
+      state: "WA",
+      zipCode: "98101",
+    } as Location;
+
+    rerender();
+
+    await waitFor(() => {
+      expect(result.current.editAddress).toContain("3811 Distribution Dr");
+    });
+  });
+
+  it("does not overwrite address after the dispatcher edits it", async () => {
+    locationDetailState.data = {
+      id: "loc-real-1",
+      name: "SEA1",
+      address: "3811 Distribution Dr",
+      city: "Seattle",
+      state: "WA",
+      zipCode: "98101",
+    } as Location;
+
+    const row = baseRow();
+    const { result, rerender } = renderHook(
+      () =>
+        useCompDocDialog({
+          row,
+          open: true,
+          onSave: vi.fn(),
+        }),
+      { wrapper },
+    );
+
+    await waitFor(() => {
+      expect(result.current.editAddress).toContain("3811 Distribution Dr");
+    });
+
+    act(() => {
+      result.current.setEditAddress("Dispatcher typed address");
+    });
+
+    locationDetailState.data = {
+      id: "loc-real-1",
+      name: "SEA1",
+      address: "999 Other St",
+      city: "Seattle",
+      state: "WA",
+      zipCode: "98101",
+    } as Location;
+    rerender();
+
+    expect(result.current.editAddress).toBe("Dispatcher typed address");
+  });
+});

src/test/app/(protected)/workorders/vendor-dialog-add-technician.test.tsx

@@ -0,0 +1,51 @@
+import { fireEvent, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { VendorDialogAddTechnician } from "@/app/(protected)/workorders/_components/list/table/cells/vendor-dialog-add-technician";
+import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
+import { isDraftVendorId } from "@/domain/vendors/utils/draft-vendor";
+import { renderWithProviders } from "@/test/test-utils";
+
+const companyVendor: VendorDropdownItem = {
+  id: 10,
+  companyName: "Gateway Plumbing",
+  contactName: "Adam Whyte",
+  tradeSpecialties: "Plumbing",
+  address: "1 Main St",
+  distanceMiles: 4.2,
+  email: "dispatch@gateway.test",
+};
+
+describe("VendorDialogAddTechnician", () => {
+  it("stages a draft technician locally without calling the create API", () => {
+    const onCreated = vi.fn();
+
+    renderWithProviders(
+      <VendorDialogAddTechnician
+        companyName="Gateway Plumbing"
+        companyVendor={companyVendor}
+        onCreated={onCreated}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /\+ add technician/i }));
+    fireEvent.change(screen.getByPlaceholderText("Full name"), {
+      target: { value: "Jordan Lee" },
+    });
+    fireEvent.change(screen.getByPlaceholderText("(000) 000-0000"), {
+      target: { value: "3145550199" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /^add$/i }));
+
+    expect(onCreated).toHaveBeenCalledTimes(1);
+    const [draftVendor, phone, payload] = onCreated.mock.calls[0] ?? [];
+    expect(isDraftVendorId(draftVendor.id)).toBe(true);
+    expect(draftVendor.contactName).toBe("Jordan Lee");
+    expect(phone).toBeTruthy();
+    expect(payload).toEqual(
+      expect.objectContaining({
+        companyName: "Gateway Plumbing",
+        contactName: "Jordan Lee",
+      }),
+    );
+  });
+});

src/test/app/(protected)/workorders/vendor-dialog-stable-identity.test.tsx

@@ -0,0 +1,178 @@
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { VendorDialog } from "@/app/(protected)/workorders/_components/list/table/cells/vendor-dialog";
+import type { Vendor } from "@/domain/vendors/types/vendor";
+import type { VendorDropdownItem } from "@/domain/work-orders/types/work-order";
+import { renderWithProviders } from "@/test/test-utils";
+
+const mutateAsync = vi.fn();
+
+vi.mock("@/domain/vendors/use-cases/use-create-vendor", () => ({
+  useCreateVendor: () => ({
+    mutateAsync,
+    isPending: false,
+  }),
+}));
+
+const existingVendor: VendorDropdownItem = {
+  id: 10,
+  companyName: "Gateway Plumbing",
+  contactName: "Jordan Lee",
+  tradeSpecialties: "Plumbing",
+  address: "1 Main St",
+  distanceMiles: 4.2,
+  email: "dispatch@gateway.test",
+};
+
+const createdVendor: Vendor = {
+  id: 99,
+  companyId: 10,
+  companyName: "Gateway Plumbing",
+  contactName: "Jordan Lee",
+  email: "dispatch@gateway.test",
+  phone: "(314) 555-9999",
+  companyPhone: "",
+  googleMapsUrl: "",
+  notes: "",
+  totalJobs: 0,
+  address: "1 Main St",
+  city: "",
+  state: "",
+  zip: "",
+  tradeSpecialties: "Plumbing",
+  isActive: true,
+  preferredContact: "Phone",
+};
+
+describe("VendorDialog stable technician identity", () => {
+  beforeEach(() => {
+    mutateAsync.mockReset();
+    mutateAsync.mockResolvedValue(createdVendor);
+  });
+
+  it("keeps draft identity on same-name collision and posts live phone on save", async () => {
+    const onSave = vi.fn();
+    const onOpenChange = vi.fn();
+
+    renderWithProviders(
+      <VendorDialog
+        open={true}
+        onOpenChange={onOpenChange}
+        vendorId={10}
+        company="Gateway Plumbing"
+        tech="Jordan Lee"
+        techPhone="(314) 555-0100"
+        vendors={[existingVendor]}
+        onSave={onSave}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /\+ add technician/i }));
+    fireEvent.change(screen.getByPlaceholderText("Full name"), {
+      target: { value: "Jordan Lee" },
+    });
+    fireEvent.change(screen.getByPlaceholderText("(000) 000-0000"), {
+      target: { value: "3145550199" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /^add$/i }));
+
+    // Draft stays staged: add form collapses and select still shows the colliding name.
+    expect(screen.getByRole("button", { name: /\+ add technician/i })).toBeTruthy();
+    expect(screen.getByText("Jordan Lee · Gateway Plumbing")).toBeTruthy();
+
+    fireEvent.change(screen.getByDisplayValue("3145550199"), {
+      target: { value: "(314) 555-9999" },
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: /^save$/i }));
+
+    await waitFor(() => {
+      expect(mutateAsync).toHaveBeenCalledTimes(1);
+    });
+
+    expect(mutateAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        contactName: "Jordan Lee",
+        companyName: "Gateway Plumbing",
+        phone: "(314) 555-9999",
+      }),
+    );
+
+    await waitFor(() => {
+      expect(onSave).toHaveBeenCalledWith(
+        expect.objectContaining({
+          vendorId: "99",
+          tech: "Jordan Lee",
+          company: "Gateway Plumbing",
+          techPhone: "(314) 555-9999",
+        }),
+      );
+    });
+
+    // Must not persist the pre-existing colliding vendor id.
+    expect(onSave.mock.calls[0]?.[0].vendorId).not.toBe("10");
+  });
+
+  it("does not clear staged draft when technicianOptions rebuild after add", async () => {
+    const onSave = vi.fn();
+    mutateAsync.mockResolvedValue({
+      ...createdVendor,
+      id: 88,
+      contactName: "Casey New",
+      phone: "3145550188",
+    });
+
+    renderWithProviders(
+      <VendorDialog
+        open={true}
+        onOpenChange={vi.fn()}
+        vendorId={11}
+        company="Gateway Plumbing"
+        tech="Adam Whyte"
+        techPhone=""
+        vendors={[
+          existingVendor,
+          {
+            ...existingVendor,
+            id: 11,
+            contactName: "Adam Whyte",
+          },
+        ]}
+        onSave={onSave}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /\+ add technician/i }));
+    fireEvent.change(screen.getByPlaceholderText("Full name"), {
+      target: { value: "Casey New" },
+    });
+    fireEvent.change(screen.getByPlaceholderText("(000) 000-0000"), {
+      target: { value: "3145550188" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /^add$/i }));
+
+    expect(screen.getByText("Casey New · Gateway Plumbing")).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: /^save$/i }));
+
+    await waitFor(() => {
+      expect(mutateAsync).toHaveBeenCalledTimes(1);
+    });
+
+    expect(mutateAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        contactName: "Casey New",
+        phone: "3145550188",
+      }),
+    );
+
+    await waitFor(() => {
+      expect(onSave).toHaveBeenCalledWith(
+        expect.objectContaining({
+          vendorId: "88",
+          tech: "Casey New",
+        }),
+      );
+    });
+  });
+});

src/test/app/(protected)/workorders/wo-table-unscheduled-highlight.test.tsx

@@ -39,6 +39,7 @@ const unscheduledRow: WorkOrderTableRow = {
   pocPhone: "",
   pocNotes: "",
   dueDate: "2026-07-15",
+  completedDate: "",
   rescheduleCount: 0,
   carriedOver: 0,
   originalWeek: "",

src/test/app/(protected)/workorders/work-orders-board-core-affordances.test.tsx

@@ -244,7 +244,13 @@ describe("CompDocCell slice affordances", () => {
 
   it("shows View Doc when onOpen is provided", () => {
     renderWithProviders(
-      <CompDocCell status="Yes" woType="PM" onOpen={vi.fn()} onOpenMedia={vi.fn()} />,
+      <CompDocCell
+        status="Yes"
+        woType="PM"
+        pm="HVAC Inspection"
+        onOpen={vi.fn()}
+        onOpenMedia={vi.fn()}
+      />,
       { withAuth: false },
     );