diff --git a/docs/work-orders/pending-be-contract.md b/docs/work-orders/pending-be-contract.md
new file mode 100644
index 00000000..a3a92f53
--- /dev/null
+++ b/docs/work-orders/pending-be-contract.md
@@ -0,0 +1,58 @@
+# Pending BE contract (WO design parity gaps)
+
+Local checklist for FE branches off `dev`. Confirm with backend before shipping PR3/PR5 to production. Until confirmed, FE may use typed clients + mocks.
+
+## Board row / PATCH
+
+| Field                                                    | Needed by     | Notes                                                                  |
+| -------------------------------------------------------- | ------------- | ---------------------------------------------------------------------- |
+| `completedDate` on GET `/board` and `/board/search` rows | PR1, PR4      | PATCH `field: "completedDate"` expected; confirm GET includes ISO date |
+| `severity` (`1`–`5` \| `null`) on row, create, PATCH     | PR2, PR5      | Required for Emergency/Reactive; PATCH `field: "severity"`             |
+| `upliftSummary` on row                                   | PR3, PR4, PR5 | `{ hasUplift, pendingCount, primaryStatus? }`                          |
+| `hasPendingUplift` on row/detail                         | PR4           | Prefer server 422 on Completed / completion-doc when pending           |
+| `additionalContacts[]`                                   | PR6           | `{ name, phone, notes? }[]` on create/detail/PATCH                     |
+| `isAddOn`                                                | PR5 (filter)  | Indicator, not a WO type (SH-126)                                      |
+
+## Proposed WO-scoped uplift endpoints (confirm vs NTE `uplifts` queue)
+
+| Method | Path                                        | Body                              |
+| ------ | ------------------------------------------- | --------------------------------- |
+| GET    | `workorders/{id}/uplifts`                   | —                                 |
+| POST   | `workorders/{id}/uplifts`                   | `{ amount, notes, attachments? }` |
+| POST   | `workorders/{id}/uplifts/{upliftId}/cancel` | —                                 |
+| POST   | `workorders/{id}/uplifts/{upliftId}/revoke` | `{ reason? }`                     |
+
+Statuses (design): `pending` \| `approved` \| `auto_approved` \| `rejected` \| `cancelled` \| `revoked`.
+
+## Search query params (`GET workorders/board/search`)
+
+| Param                          | Meaning                   |
+| ------------------------------ | ------------------------- |
+| `severities`                   | multi `1`–`5`             |
+| `rescheduled` / `carriedOver`  | boolean (≥2 counters)     |
+| `addOn`                        | boolean (`isAddOn`)       |
+| `flagColors`                   | multi `#RRGGBB`           |
+| `internalOnly`                 | WO# starts with `SH`      |
+| `avetaOnly`                    | if `avetaRequired` exists |
+| `hasUplift` + `upliftStatuses` | uplift filters            |
+
+Already documented in `board-search-api.md`: datePreset, sites, types, overdue, dispatchers, statuses, pmTypes, vendorIds, docStatuses.
+
+## Comments
+
+| Field                                    | Needed by |
+| ---------------------------------------- | --------- |
+| POST `{ text, mentions?: string[] }`     | PR9       |
+| Response includes mentions for highlight | PR9       |
+
+## Vendor
+
+| Item                                                           | Needed by |
+| -------------------------------------------------------------- | --------- |
+| Create technician under company (confirm existing vendors API) | PR7       |
+
+## Optional
+
+| Item                                | Needed by                        |
+| ----------------------------------- | -------------------------------- |
+| 422 on duplicate WO number (global) | PR8 (FE dialog works without it) |