@cxtms/cx-schema 1.9.67 → 1.9.241

package/schemas/workflows/tasks/workflow-execute.json

@@ -50,6 +50,10 @@
           "description": "Inputs to pass to the child workflow",
           "additionalProperties": true
         },
+        "executionId": {
+          "type": "string",
+          "description": "Optional caller-provided GUID idempotency key for retry-safe workflow execution"
+        },
         "async": {
           "type": "boolean",
           "description": "Execute asynchronously"

package/schemas/workflows/variable.json

@@ -31,14 +31,14 @@
             },
             "key": {
               "type": "string",
-              "description": "Optional key within configuration"
+              "description": "Optional key within configuration. If omitted, the variable receives the whole config object with organizationConfigId injected alongside custom values."
             }
           },
           "required": ["configName"],
           "additionalProperties": true
         }
       ],
-      "description": "Load value from configuration"
+      "description": "Load value from organization configuration. When a full config is loaded without a key, the runtime injects organizationConfigId into the returned object; keyed lookups return only the keyed value."
     }
   },
   "required": ["name"],

package/schemas/workflows/workflow.json

@@ -67,8 +67,8 @@
         },
         "workflowType": {
           "type": "string",
-          "enum": ["Document", "Quote", "Flow", "Webhook", "PublicApi"],
-          "description": "Workflow type: Document (PDF/Excel generation), Quote, Flow (declarative state machine), Webhook (HTTP endpoint), or PublicApi (REST API endpoint). Omit for standard process workflows."
+          "enum": ["Document", "Quote", "Flow", "Webhook", "PublicApi", "McpTool", "McpResource", "McpPrompt"],
+          "description": "Workflow type, including organization-scoped MCP tools, resources, and prompts. Omit for standard process workflows."
         },
         "runAs": {
           "type": "string",
@@ -266,6 +266,19 @@
       "required": ["path", "method"],
       "additionalProperties": true
     },
+    "mcp": {
+      "type": "object",
+      "description": "MCP metadata for McpTool, McpResource, and McpPrompt workflows",
+      "properties": {
+        "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "uri": { "type": "string", "format": "uri" },
+        "mimeType": { "type": "string" },
+        "timeout": { "type": "integer", "minimum": 0, "default": 60 }
+      },
+      "additionalProperties": false
+    },
     "entity": {
       "$ref": "flow/entity.json",
       "description": "Entity configuration for Flow workflows"
@@ -329,6 +342,30 @@
       "then": {
         "required": ["workflow", "activities", "api"]
       }
+    },
+    {
+      "if": {
+        "properties": { "workflow": { "properties": { "workflowType": { "enum": ["McpTool", "McpPrompt"] } }, "required": ["workflowType"] } }
+      },
+      "then": {
+        "required": ["workflow", "activities", "mcp"],
+        "properties": {
+          "mcp": { "required": ["name"] },
+          "workflow": { "properties": { "executionMode": { "const": "Sync" } } }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "workflow": { "properties": { "workflowType": { "const": "McpResource" } }, "required": ["workflowType"] } }
+      },
+      "then": {
+        "required": ["workflow", "activities", "mcp"],
+        "properties": {
+          "mcp": { "required": ["uri"] },
+          "workflow": { "properties": { "executionMode": { "const": "Sync" } } }
+        }
+      }
     }
   ],
   "additionalProperties": true

package/skills/cxtms-developer/SKILL.md

@@ -39,6 +39,7 @@ Use `--feature <feature_name>` with `cx-cli create` to automatically place files
 
 !cat skills/cxtms-developer/ref-entity-order-sub.md
 !cat skills/cxtms-developer/ref-entity-job.md
+!cat skills/cxtms-developer/ref-entity-dispatch-routing.md
 
 ### Pricing & Accounting Lookups
 
@@ -66,8 +67,10 @@ Use `--feature <feature_name>` with `cx-cli create` to automatically place files
 | **Primary** | Order, Contact, Commodity, AccountingTransaction | ref-entity-order/contact/commodity/accounting.md |
 | **Order sub** | OrderEntity, TrackingEvent, EventDefinition, LinkedOrder, OrderDocument | ref-entity-order-sub.md |
 | **Job** | Job, JobOrder, JobStatus | ref-entity-job.md |
+| **Dispatch routing** | DispatchRouteStatus, DispatchRouteTemplate, DispatchRoute, stops | ref-entity-dispatch-routing.md |
+| **Order moves** | OrderMove, OrderMoveLeg, move and leg statuses | ref-entity-dispatch-routing.md |
 | **Pricing** | Rate, Lane, Discount, AccountingItem, AccountingAccount, PaymentTerm | ref-entity-rate.md |
-| **Shared** | Tag, Attachment, Division, EquipmentType, PackageType, Note/NoteThread | ref-entity-shared.md |
+| **Shared** | Tag, Attachment, Division, EquipmentType, Equipment, EquipmentStatus, PackageType, Note/NoteThread | ref-entity-shared.md |
 | **Geography** | Country, State, City, Port, Vessel, CustomCode, ModeOfTransportation | ref-entity-geography.md |
 | **Equipment** | Equipment, EquipmentStatus | ref-entity-equipment.md |
 | **Warehouse** | InventoryItem, WarehouseLocation, CargoMovement (Order variant) | ref-entity-warehouse.md |
@@ -90,7 +93,7 @@ Most entities have `customValues` — a `Dictionary<string, object?>` stored as
 
 **Sub-entities**: OrderEntity, OrderCommodity, ContactAddress, ContactPaymentMethod, CommodityType, CommodityTag, OrderTag, LinkedOrder, InventoryItemTag
 
-**Lookup entities**: Job, JobStatus, Tag, Attachment, EventDefinition, Rate, Lane, Discount, AccountingItem, Port, Country, State, City, ModeOfTransportation
+**Lookup entities**: Job, JobStatus, DispatchRouteStatus, DispatchRouteTemplate, DispatchRoute, DispatchRouteStop, DispatchRouteTemplateStop, Tag, Attachment, EventDefinition, Rate, Lane, Discount, AccountingItem, Port, Country, State, City, ModeOfTransportation
 
 **Fleet**: Equipment (replace semantics — null clears, non-null full-replaces)
 

package/skills/cxtms-developer/ref-cli-auth.md

@@ -86,6 +86,8 @@ npx cxtms deploy-all --org 42
 
 Validates all YAML files first, then pushes modules and workflows to the server. Skips files with validation errors and reports results.
 
+Deploying a module whose matching server record was soft-deleted restores and updates that record. The server resolves deleted modules by module and organization ID, avoiding a duplicate-key insert during reinstall.
+
 > Note: `deploy-all` pushes local YAML files to the CX server (per-file `updateWorkflow` / `updateAppModule` mutations). It does **not** touch git or create a PR. Use `app release` to open a git PR from the server's pending changes.
 
 ## App Manifest Management

package/skills/cxtms-developer/ref-entity-commodity.md

@@ -116,11 +116,14 @@ Field names as used in workflow expressions: `{{ entity.description }}`, `{{ ent
 | `getChildCommodities(filter)` | `[Commodity]` | Child commodities |
 | `getParentCommodity` | `Commodity` | Parent commodity |
 | `getRelatedOrders(filter)` | `[Order]` | Related orders |
-| `getRelatedOrder(filter)` | `Order` | First related order |
+| `getRelatedOrder(filter)` | `Order` | First non-draft related order, batched across commodity rows; optional order filter; lowest `orderId` wins when multiple orders match |
+| `getRelatedDispatchRoutes(filter?, orderBy?)` | `[DispatchRoute]` | Dispatch routes linked through non-draft orders attached to this commodity or any descendant commodity |
 | `getCommodityTrackingNumber(idPropertyName)` | `TrackingNumber` | Lookup |
 | `getCommodityAttachments(filter)` | `[Attachment]` | |
-| `lastTrackingEvent(eventDefinitionName, orderBy?)` | `TrackingEvent` | Most recent (or earliest) tracking event, resolved via batched DataLoader. `orderBy` is **honoured**: omit or prefix with `-` for DESC (latest event: `COALESCE(EventDate, Created) DESC, TrackingEventId DESC`); no prefix for ASC (earliest event: same columns ASC). Default is DESC. |
+| `getWeightTotal(weightUnit)` | `decimal?` | Total weight converted to requested unit; defaults to commodity `weightUnit` when omitted |
+| `lastTrackingEvent(eventDefinitionName, orderBy?)` | `TrackingEvent` | Most recent (or earliest) tracking event, resolved via batched DataLoader. `eventDefinitionName` may contain pipe-separated names such as `Departed|Delivered`; the resolver selects the winner across all matching definitions. `orderBy` is **honoured**: omit or prefix with `-` for DESC (latest event: `COALESCE(EventDate, Created) DESC, TrackingEventId DESC`); no prefix for ASC (earliest event: same columns ASC). Default is DESC. |
 | `changeHistory(startDate, endDate, maxResults)` | `[ChangeHistory]` | Audit trail |
+| `getContact(idPropertyName)` | `Contact` | Resolves a contact ID stored in `customValues[idPropertyName]` within the same organization; returns null when no valid ID exists |
 
 ## Container/Child Pattern (Self-Referencing)
 
@@ -139,6 +142,7 @@ Container Commodity (parent)
 - Changing warehouse location on parent cascades to children
 - Changing commodity status on parent cascades to children
 - Deleting parent cascades to children
+- `updateCommodity` can optionally cascade `customValues` to direct children (`cascadeToChildren`) or promote markers to the parent once all direct siblings have those keys (`promoteParentWhenAllChildren`)
 
 ## CommodityTrackingNumber Sub-Entity
 
@@ -206,9 +210,37 @@ conditions:
 # Update via Commodity/Update task
 inputs:
   commodityId: "{{ entity.commodityId }}"
-  commodity:
-    CustomValues.lotNumber: "LOT-001"
-    CustomValues.hazmat: true
+  entity:
+    customValues:
+      lotNumber: "LOT-001"
+      hazmat: true
+
+# Pallet/carton scan cascade: parent scan marks direct children
+inputs:
+  commodityId: "{{ pallet.commodityId }}"
+  cascadeToChildren: true
+  entity:
+    customValues:
+      scanned: true
+
+# Carton scan promotion: final marked sibling marks the parent
+inputs:
+  commodityId: "{{ carton.commodityId }}"
+  promoteParentWhenAllChildren: true
+  entity:
+    customValues:
+      scanned: true
+```
+
+Resolve custom-value contact references:
+
+```graphql
+getCommodities(organizationId: 1, take: 1) {
+  items {
+    commodityId
+    getContact(idPropertyName: "shipperContactId") { contactId name }
+  }
+}
 ```
 
 **Entities with own customValues:**
@@ -238,3 +270,7 @@ aggregations:
     parameter: "eventCode"
     expression: "any([Commodity.CommodityEvents], [each.TrackingEvent.EventDefinition.EventCode] = [eventCode])"
 ```
+
+### Last tracking event business days
+
+`lastTrackingEventBusinessDays(path, contactId?, contactIdPropertyName?, eventDefinitionName?, orderBy?)` returns an `int?` business-day count for the commodity's last tracking event. Use `contactIdPropertyName: "carrierId"` when each grid row stores its carrier in `Commodity.CustomValues.carrierId`; the resolver reads the row value server-side and filters business calendar availability blocks to org-wide plus that contact.

package/skills/cxtms-developer/ref-entity-contact.md

@@ -45,6 +45,18 @@ Field names as used in workflow expressions: `{{ entity.name }}`, `{{ entity.cus
 | `lastModified` | `DateTime` | |
 | `lastModifiedBy` | `string` | User ID |
 
+When an organization user's profile first/last name changes, linked contact profile names can be regenerated from trimmed `contactFirstName` + `contactLastName` so `name` remains in sync with the person display name.
+
+### Import behavior
+
+Contact CSV/import handling protects division scoping:
+
+- `DivisionId` values are accepted only when they belong to the target organization. Foreign, stale, or unparsable division IDs are removed from the import row.
+- For existing contacts, an invalid `DivisionId` is ignored so the current division is not overwritten.
+- For new contacts, if no valid division remains, the contact is created in the importing user's division when available.
+- Nested `division.divisionName` input is resolved to an organization division and converted to `DivisionId`; the nested `division` object is not persisted.
+- Empty strings are stripped from add/update fields so blank CSV cells do not clear existing values or break enum/numeric conversions.
+
 ## Navigation Properties
 
 | Field | Type | Notes |
@@ -78,6 +90,7 @@ Field names as used in workflow expressions: `{{ entity.name }}`, `{{ entity.cus
 | `getContactAddressByType(addressType)` | `[ContactAddress]` | Filter by "Billing", "Shipping", "Other" |
 | `getFirstContactAddressByType(addressType)` | `ContactAddress` | First match |
 | `getContactAttachments(filter, orderBy)` | `[Attachment]` | |
+| `getContactAddresses(filter, orderBy)` | `[ContactAddress]` | Contact-scoped address resolver with server-side Lucene filtering and sorting |
 | `getCustomValuesAttachment(filter)` | `Attachment` | From customValues `attachmentId` key |
 | `availableCredit` | `[AvailableCreditByCurrency]` | Carrier/Customer only |
 | `changeHistory(startDate, endDate, maxResults)` | `[ChangeHistory]` | Audit trail |
@@ -101,6 +114,7 @@ Field names as used in workflow expressions: `{{ entity.name }}`, `{{ entity.cus
 | `Store` | 13 | |
 | `ContactUser` | 14 | User associated with contact |
 | `USPPI` | 15 | US Principal Party in Interest |
+| `Port` | 16 | Port contact/location reference |
 
 ## ContactAddress Sub-Entity
 
@@ -115,6 +129,7 @@ Field names as used in workflow expressions: `{{ entity.name }}`, `{{ entity.cus
 | `stateCode` | `string?` | FK to State |
 | `postalCode` | `string?` | |
 | `isInactive` | `bool?` | |
+| `name` | `string?` | Optional label for the address/location (max 200 chars) |
 | `latitude` | `double?` | From Location.Y (GraphQL resolved) |
 | `longitude` | `double?` | From Location.X (GraphQL resolved) |
 | `customValues` | `Dictionary` | Own customValues (separate from Contact) |
@@ -123,6 +138,10 @@ Field names as used in workflow expressions: `{{ entity.name }}`, `{{ entity.cus
 
 GraphQL resolver: `formattedAddress(outputFormat, addressFormat, lang, multiline)` — formatted string.
 
+**ContactAddress import notes:** `ContactAddress/Import@1` can update by `ContactAddressId` or `contactAddressId` first, then falls back to business-key matching. Rows are bound as dictionaries, so exported primary-key columns survive re-import even when the casing is camelCase. Export grids should include `contactAddressId`/entity keys when data is intended for re-import. Import aliases `City` to `cityName`, resolves `StateName` to `stateCode`, and accepts `Longitude`/`Latitude` for `location`.
+
+Module default-data imports support `entity: "contact"` with `keys` for natural-key matching and `overwrite` for update-vs-skip behavior. Use `ContactType: Port` for port/location contacts when appropriate.
+
 ## Other Related Enums
 
 | Enum | Values |
@@ -134,6 +153,33 @@ GraphQL resolver: `formattedAddress(outputFormat, addressFormat, lang, multiline
 | `ContactStatusStage` | Active=0, Inactive=1 |
 | `PaymentType` | Card=1, AccountCredit=2, Cash=3, Check=4, BankTransfer=5, Other=7 |
 
+## Contact Import
+
+GraphQL `importContacts` accepts CSV, JSON, or XLSX uploads and imports rows as dynamic contact field dictionaries.
+
+Important rules:
+- Existing contacts match by `ContactId`; otherwise a new contact is created.
+- `ContactId` and `OrganizationId` are primary key fields and are filtered out before create/update field application.
+- Empty strings and nulls are skipped on updates; blank spreadsheet cells do not erase existing values.
+- New contacts require `Name`; rows without a non-empty name are skipped.
+- `ContactType` can come from the row, from the mutation-level `contactType` default, or finally defaults to `Contact`.
+- Nested division objects can set the primary division by name: `division.divisionName` resolves to `divisionId` within the same organization.
+
+Example mutation input:
+
+```json
+{
+  "organizationId": 1,
+  "fileUploadUrl": "uploads/imports/contacts.xlsx",
+  "contactType": "Customer",
+  "columnMappings": {
+    "Name": "Company Name",
+    "EmailAddress": "Email",
+    "Division.DivisionName": "Division"
+  }
+}
+```
+
 ## CustomValues
 
 `Dictionary<string, object?>` stored as PostgreSQL `jsonb`. Access in workflows:

package/skills/cxtms-developer/ref-entity-dispatch-routing.md

@@ -0,0 +1,195 @@
+# Dispatch Routing Entity Field Reference
+
+Dispatch routing covers reusable weekly route templates, daily dispatch routes, route statuses, stop statuses, and stops.
+
+> **Proposed API:** The Order Move entities and fields in the section below come from the backend
+> design specification and are not deployed yet. Do not generate production queries or mutations
+> against them until implementation is confirmed.
+
+## DispatchRouteType Enum
+
+| Value | Notes |
+|-------|-------|
+| `Delivery` | Delivery route or stop |
+| `Pickup` | Pickup route or stop |
+| `PickupDelivery` | Combined pickup-and-delivery route or stop |
+
+## DispatchRouteStatus
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `dispatchRouteStatusId` | `int` | PK |
+| `organizationId` | `int` | Tenant scope |
+| `statusName` | `string` | Display name |
+| `statusDescription` | `string?` | Optional description |
+| `statusStage` | `StatusStage` | `Pending`, `InProgress`, `Completed` |
+| `routeType` | `DispatchRouteType?` | Null applies to any route type |
+| `priority` | `int` | Display sort order |
+| `color` | `string?` | Hex/display color |
+| `customValues` | `Dictionary` | jsonb |
+
+## DispatchRouteStopStatus
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `dispatchRouteStopStatusId` | `int` | PK |
+| `organizationId` | `int` | Tenant scope |
+| `statusName` | `string` | Display name; unique per organization for active statuses |
+| `statusDescription` | `string?` | Optional description |
+| `statusStage` | `StatusStage` | `Pending`, `InProgress`, `Completed` |
+| `stopType` | `DispatchRouteType?` | Null applies to any stop type |
+| `priority` | `int` | Display sort order |
+| `color` | `string?` | Hex/display color |
+| `customValues` | `Dictionary` | jsonb |
+| `isDeleted` | `bool` | Soft-delete flag |
+
+## DispatchRouteTemplate
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `dispatchRouteTemplateId` | `int` | PK |
+| `organizationId` | `int` | Tenant scope |
+| `name` | `string` | Template name |
+| `routeType` | `DispatchRouteType` | `Delivery`, `Pickup`, or `PickupDelivery` |
+| `daysOfWeek` | `DayOfWeek[]` | Matching generation days |
+| `divisionId` | `int?` | FK to Division |
+| `equipmentTypeId` | `int?` | Planned equipment type |
+| `enabled` | `bool` | Generation skips disabled templates |
+| `stops` | `[DispatchRouteTemplateStop]` | Ordered by `sequence` |
+| `customValues` | `Dictionary` | jsonb |
+
+## DispatchRouteTemplateStop
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `dispatchRouteTemplateStopId` | `int` | PK |
+| `dispatchRouteTemplateId` | `int` | Parent template |
+| `stopContactId` | `int?` | Store/location contact (nullable; use with or without `contactAddressId`) |
+| `contactAddressId` | `int?` | Optional stop address |
+| `stopType` | `DispatchRouteType` | Defaults to template route type when omitted |
+| `sequence` | `int` | 1-based order |
+| `estimatedServiceMinutes` | `int?` | Planned service time |
+| `customValues` | `Dictionary` | jsonb (use for ad-hoc address when not using a contact) |
+
+## DispatchRoute
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `dispatchRouteId` | `int` | PK |
+| `organizationId` | `int` | Tenant scope |
+| `name` | `string` | Route name |
+| `routeType` | `DispatchRouteType` | `Delivery`, `Pickup`, or `PickupDelivery` |
+| `routeDate` | `Date` | `yyyy-MM-dd` |
+| `dispatchRouteStatusId` | `int` | FK to DispatchRouteStatus |
+| `dispatchRouteTemplateId` | `int?` | Source template when generated |
+| `divisionId` | `int?` | FK to Division |
+| `driverContactId` | `int?` | Driver contact assignment |
+| `equipmentId` | `int?` | Equipment assignment |
+| `isDraft` | `bool` | Generated/new routes start as draft |
+| `isInactive` | `bool` | Soft-delete flag |
+| `collapsedIntoDispatchRouteId` | `int?` | Route merge target |
+| `stops` | `[DispatchRouteStop]` | Ordered by `plannedSequence` |
+| `trackingEvents` | `[TrackingEvent]` | Tracking events linked directly to the route |
+| `customValues` | `Dictionary` | jsonb |
+
+## DispatchRouteStop
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `dispatchRouteStopId` | `int` | PK |
+| `dispatchRouteId` | `int` | Parent route |
+| `stopContactId` | `int?` | Store/location contact (nullable; use with or without `contactAddressId`) |
+| `contactAddressId` | `int?` | Optional stop address |
+| `stopType` | `DispatchRouteType` | Defaults to route route type when omitted |
+| `plannedSequence` | `int` | Planned 1-based order |
+| `actualSequence` | `int?` | Actual execution order |
+| `estimatedServiceMinutes` | `int?` | Planned service time |
+| `dispatchRouteStopStatusId` | `int?` | FK to DispatchRouteStopStatus |
+| `dispatchRouteStopStatus` | `DispatchRouteStopStatus?` | Optional expanded stop status |
+| `actualArrivalTime` | `DateTime?` | Actual arrival timestamp |
+| `actualCompletionTime` | `DateTime?` | Actual completion timestamp |
+| `orderMoveId` | `int?` | Optional move this trip stop executes |
+| `orderMove` | `OrderMove?` | Expandable move navigation |
+| `orderIds` | `int[]` | Attached order IDs; always projected |
+| `orders` | `[DispatchRouteStopOrder]` | Attached order links; expand `order` when needed |
+| `trackingEvents` | `[TrackingEvent]` | Tracking events linked directly to this stop |
+| `customValues` | `Dictionary` | jsonb (use for ad-hoc address when not using a contact) |
+
+## DispatchRouteStopOrder
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `dispatchRouteStopOrderId` | `int` | PK |
+| `dispatchRouteStopId` | `int` | Parent stop |
+| `orderId` | `int` | Attached order |
+| `order` | `Order?` | Optional expanded order |
+| `dispatchRouteStop` | `DispatchRouteStop?` | Optional expanded stop when reached from `order.dispatchRouteStopOrders` |
+| `customValues` | `Dictionary` | jsonb on the stop/order link |
+
+## Order Moves
+
+An order owns ordered `OrderMove` records, and each move owns ordered `OrderMoveLeg` records.
+Vertical-specific routing details belong in `customValues`.
+
+### OrderMove
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `orderMoveId` | `int` | PK |
+| `organizationId` | `int` | Tenant scope |
+| `orderId` | `int` | Parent order |
+| `sequence` | `int` | 1-based order within the order |
+| `name` | `string?` | Optional label |
+| `assignedDriverContactId` | `int?` | FK to Contact |
+| `orderMoveStatusId` | `int?` | FK to OrderMoveStatus |
+| `startDate` | `DateTime?` | UTC start |
+| `endDate` | `DateTime?` | UTC end |
+| `customValues` | `Dictionary` | Vertical-specific jsonb data |
+| `orderMoveLegs` | `[OrderMoveLeg]` | Ordered by `sequence` |
+| `dispatchRouteStops` | `[DispatchRouteStop]` | Stops executing this move, ordered by route then planned sequence; may span routes |
+| `trackingEvents` | `[TrackingEvent]` | Move-level milestones |
+
+### OrderMoveLeg
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `orderMoveLegId` | `int` | PK |
+| `orderMoveId` | `int` | Parent move |
+| `sequence` | `int` | 1-based order within the move |
+| `name` | `string?` | Optional label |
+| `orderMoveLegStatusId` | `int?` | FK to OrderMoveLegStatus |
+| `startDate` | `DateTime?` | UTC start |
+| `endDate` | `DateTime?` | UTC end |
+| `customValues` | `Dictionary` | Location, event, appointment, and metric data |
+| `trackingEvents` | `[TrackingEvent]` | Leg-level milestones |
+
+`OrderMoveStatus` and `OrderMoveLegStatus` are organization-scoped status dictionaries with
+`statusName`, `statusDescription`, `statusStage`, `priority`, `color`, and `customValues`.
+Moves support `OrderMove/Create@1`, `OrderMove/Update@1`, and `OrderMove/Delete@1` workflow tasks.
+
+Order creation may include `orderMoves`; the new order supplies their `orderId`, moves default
+to array-position sequence, and nested legs receive 1-based array-order sequences.
+`Order/Import@1` also accepts moves and nested legs. Existing records match by ID, then by
+`ImportOrderOptions.OrderMoveMatchByFields` / `OrderMoveLegMatchByFields` (dotted
+`customValues` paths are supported), and finally by sequence or array position. New records
+are appended and omitted existing records are not deleted.
+
+## GraphQL Notes
+
+- Queries: `dispatchRouteStatus`, `dispatchRouteStatuses`, `dispatchRouteStopStatus`, `dispatchRouteStopStatuses`, `dispatchRouteTemplate`, `dispatchRouteTemplates`, `dispatchRoute`, `dispatchRoutes`.
+- Order move queries: `orderMove`, `orderMoves`, `orderMoveStatus`, `orderMoveStatuses`, `orderMoveLegStatus`, and `orderMoveLegStatuses`.
+- Nested order resolvers: `getOrderMoves(filter, orderBy)` returns pending or statusless moves (defaulted to sequence order), while `getOrderMove(filter, orderBy)` returns the first matching pending or statusless move. Moves whose status stage is no longer `Pending` are excluded.
+- Order move mutations create, sparse-update, and soft-delete moves; create/update accepts nested `orderMoveLegs`, reconciled by ID and array order. Omitted or `isDeleted: true` legs are soft-deleted, new already-deleted legs are ignored, and only active legs consume sequence positions.
+- A dynamic order update can supply `orderMoves` to reconcile the full collection with the same rules. New moves inherit `organizationId` and `orderId` from the aggregate; omitted or explicitly deleted moves are soft-deleted; active moves and nested legs are resequenced from 1.
+- Mutations use `input: { organizationId, values }` and return payload fields named `dispatchRouteStatus`, `dispatchRouteStopStatus`, `dispatchRouteTemplate`, `dispatchRoute`, or `generateDispatchRoutesResult`.
+- Stop status mutations: `createDispatchRouteStopStatus`, `updateDispatchRouteStopStatus`, `deleteDispatchRouteStopStatus`.
+- Route stops can be anchored by location (`stopContactId`, `contactAddressId`, ad-hoc `customValues`) or by attached `orderIds`.
+- Route stops optionally expand `orderMove`; the inverse `orderMove.dispatchRouteStops` collection supports filtering and may span multiple dispatch routes.
+- Create accepts nested route stops with `dispatchRouteStopStatusId`, `orderMoveId`, and `orderIds`. `orderMoveId` links the new stop to the move it executes. Dynamic route updates and stop add/update mutations also accept `dispatchRouteStopStatusId` and `orderIds`; statuses are organization-scoped and validated against stop type, and when `orderIds` is present, the attached orders are reconciled to exactly those IDs after organization validation.
+- `updateDispatchRouteStop` uses a dynamic `values` map. It sparse-updates only supplied keys, treats an explicit `null` as clearing a nullable field, and rejects unknown keys. Use `actualArrivalTime` and `actualCompletionTime` to stamp or clear actual stop times without echoing unrelated fields.
+- Dynamic route/template updates can replace the full `stops` array: existing stops with IDs are sparse-updated, new stops are inserted, omitted existing stops are soft-deleted, and sequence/plannedSequence is reassigned from array order. Dedicated stop add/update/remove/reorder mutations remain available for targeted edits.
+- Orders expose `relatedDispatchRoutes(filter, orderBy)` for routes linked through stop order attachments; draft orders return no related routes.
+- Orders expose raw stop membership links through `dispatchRouteStopOrders`; use nested paths such as `dispatchRouteStopOrders.dispatchRouteStop.dispatchRouteStopStatus.statusStage` when filtering orders by route-stop assignment or completion state.
+- Tracking events can be attached directly to dispatch routes and dispatch route stops. Use route-level events for whole-route milestones and stop-level events for arrival, completion, exception, or proof-of-service milestones tied to one stop.
+- Workflow tasks support these links: `TrackingEvent/Create@1` accepts `dispatchRouteId` or `dispatchRouteStopId`; `TrackingEvent/Import@1` requires exactly one target among `orderId`, `dispatchRouteId`, and `dispatchRouteStopId`.
+- Route generation is idempotent per template/date and creates draft routes.

package/skills/cxtms-developer/ref-entity-geography.md

@@ -6,11 +6,12 @@
 - City
 - PostalCode
 - Port
+- Terminal
 - Vessel
 - CustomCode
 - ModeOfTransportation
 
-Country, State, City, PostalCode, Port, Vessel, CustomCode, ModeOfTransportation.
+Country, State, City, PostalCode, Port, Terminal, Vessel, CustomCode, ModeOfTransportation.
 
 ## Country
 
@@ -110,6 +111,30 @@ String-based PK (e.g., UN/LOCODE).
 
 ---
 
+## Terminal
+
+Organization-scoped terminal / operating location (facility record). Optional Port linkage. Soft deleted; codes are unique only among active terminals in the same organization.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `terminalId` | `int` | PK |
+| `organizationId` | `int` | Required; tenant scope |
+| `name` | `string` | Required display name |
+| `code` | `string?` | Optional; unique per organization when not null and `isDeleted=false` |
+| `portId` | `string?` | Optional FK to Port (`organizationId` + `portId`) |
+| `customValues` | `Dictionary` | jsonb; searchable |
+| `isDeleted` | `bool` | Soft delete flag; default false; default queries filter deleted rows |
+| `created` / `createdBy` | `DateTime` / `string` | Audit fields |
+| `lastModified` / `lastModifiedBy` | `DateTime` / `string` | Audit fields |
+
+**Navigation:** `organization`, `port`, `createdUser`, `updatedUser`
+
+**GraphQL:** `terminal(organizationId, terminalId)`, `terminals(organizationId, filter, search, orderBy)`, `createTerminal`, `updateTerminal`, `deleteTerminal`.
+
+**Search:** `name`, `code`, and `customValues`.
+
+---
+
 ## Vessel
 
 | Field | Type | Notes |

package/skills/cxtms-developer/ref-entity-job.md

@@ -36,9 +36,13 @@ Job groups related orders and accounting transactions.
 | `accountingTransactions` | `[AccountingTransaction]` | Via JobAccountingTransaction join |
 | `commodities` | `[Commodity]` | Direct FK |
 
-### GraphQL Computed
+### GraphQL Child Resolvers
 
-- `getJobOrders(filter)` — orders via JobOrder join
+| Field | Type | Notes |
+|-------|------|-------|
+| `getJobOrders(filter)` | `[Order]` | Orders via JobOrder join |
+| `getJobOrder(filter)` | `Order?` | Single order via JobOrder join (UseFirstOrDefault + projection) |
+| `getJobCommodity(filter)` | `Commodity?` | Single commodity linked to job (by JobId) |
 
 ---
 

package/skills/cxtms-developer/ref-entity-order-sub.md

@@ -81,7 +81,7 @@ Milestone/tracking event on an order or commodity.
 
 | Field | Returns | Notes |
 |-------|---------|-------|
-| `businessDays(path: String!)` | `int?` | Business days from the date at `path` to today, using the org's business calendar. `path` is a dot-separated property path on the tracking event (e.g. `"eventDate"`, `"customValues.scheduledAt"`). Returns `null` if path doesn't resolve or value isn't a parseable date. |
+| `businessDays(path: String!, contactId?: Int)` | `int?` | Business days from the date at `path` to today, using the org business calendar. Optional `contactId` scopes availability blocks to org-wide plus matching contact blocks. Instant values are converted to the org timezone before taking the date; date-only values are not timezone-shifted. Returns `null` if path does not resolve or value is not parseable. |
 
 ---
 

package/skills/cxtms-developer/ref-entity-order.md

@@ -40,6 +40,7 @@ Field names as used in workflow expressions: `{{ entity.orderId }}`, `{{ entity.
 | Field | Type | Notes |
 |-------|------|-------|
 | `orderStatus` | `OrderStatus` | `.statusName`, `.statusStage` |
+| `orderSummary` | `OrderSummaryView` | One-to-one summary view; supports nested sort paths like `orderSummary.totalPieces` |
 | `division` | `Division` | `.name` |
 | `equipmentType` | `EquipmentType` | |
 | `billToContact` | `Contact` | Full contact object |
@@ -50,6 +51,14 @@ Field names as used in workflow expressions: `{{ entity.orderId }}`, `{{ entity.
 | `createdUser` | `User` | `.firstName`, `.lastName`, `.email` |
 | `updatedUser` | `User` | |
 
+## Workflow Trigger Payload Notes
+
+Order entity triggers include scalar status fields (`orderStatusId`, `orderStatusName`) in the lightweight workflow payload. `orderStatusName` is loaded before mapping when needed, so modified-order workflows and Flow auto-transition expressions can rely on it even if the EF event did not preload the `orderStatus` navigation.
+
+## Search Behavior
+
+Order GraphQL quick search (`orders(search:)` and `orderGroupBy(search:)`) matches core order fields plus related commodity and inventory item fields. InventoryItem data linked from an order commodity, including child/container commodities, is searchable by `sku`, `productName`, `description`, `modelNumber`, and JSON `customValues`. Use this for warehouse-backed order lookup by SKU, item name, model number, color, size, or similar item attributes.
+
 ## Collection Properties
 
 | Field | Type | Notes |
@@ -63,8 +72,10 @@ Field names as used in workflow expressions: `{{ entity.orderId }}`, `{{ entity.
 | `jobOrders` | `[JobOrder]` | |
 | `orderTags` | `[OrderTag]` | |
 | `orderCarriers` | `[OrderCarrier]` | |
+| `dispatchRouteStopOrders` | `[DispatchRouteStopOrder]` | Stop membership links for this order; expand `dispatchRouteStop` to inspect route, stop status, or stop tracking events |
 | `allTags` | `[OrderAllTagsView]` | View: all tags including from commodities |
 | `allRelatedOrders` | `[OrderRelatedOrdersView]` | Orders sharing commodities |
+| `relatedDispatchRoutes` | `[DispatchRoute]` | Routes linked through dispatch route stop order attachments; supports `filter` and `orderBy`; draft orders return an empty list |
 | `attachmentsSummary` | `OrderAttachmentSummaryView?` | DB view: `.totalCount`, `.hasAny` (active attachments) |
 | `notesSummary` | `OrderNoteSummaryView?` | DB view: `.totalCount`, `.hasAny` (non-deleted notes) |
 | `outgoingLinks` | `[LinkedOrder]` | |
@@ -98,18 +109,21 @@ These are virtual fields that filter `orderEntities` by type:
 | `commoditySummary` | `CommoditySummary` | `.totalWeight`, `.totalPieces`, `.totalQuantity`, `.totalVolume` |
 | `accountingSummary` | `AccountingSummary` | |
 | `getContact(idPropertyName)` | `Contact` | Resolve contact from `customValues[idPropertyName]` |
+| `getTerminal(idPropertyName)` | `Terminal` | Resolve terminal from int `customValues[idPropertyName]` |
 | `getPort(idPropertyName)` | `Port` | Resolve port from `customValues[idPropertyName]` |
+| `getTerminal(idPropertyName)` | `Terminal` | Resolve terminal from `customValues[idPropertyName]` |
 | `getVessel(idPropertyName)` | `Vessel` | Resolve vessel from `customValues[idPropertyName]` |
 | `getCountry(idPropertyName)` | `Country` | Resolve country from `customValues[idPropertyName]` |
 | `getRoute(idPropertyName)` | `Route` | Resolve route from `customValues[idPropertyName]` |
 | `getModeOfTransportation(idPropertyName)` | `ModeOfTransportation` | |
 | `getCustomCode(idPropertyName)` | `CustomCode` | |
 | `getRelatedOrderByProperty(idPropertyName)` | `Order` | Resolve related order from `customValues[idPropertyName]` |
+| `relatedDispatchRoutes(filter, orderBy)` | `[DispatchRoute]` | Routes linked through dispatch route stop order attachments; draft orders return an empty list |
 | `getCharge(chargeDescription)` | `Charge` | Single charge by description |
 | `getChargesByChargeType(chargeType)` | `[Charge]` | Charges filtered by type |
 | `getOrderSummary(weightUnit, volumeUnit, dimensionsUnit)` | `OrderSummary` | |
-| `lastTrackingEvent(eventDefinitionName, orderBy?)` | `TrackingEvent` | Most recent (or earliest) tracking event, resolved via batched DataLoader. `orderBy` is **honoured**: omit or prefix with `-` for DESC (latest event: `COALESCE(EventDate, Created) DESC, TrackingEventId DESC`); no prefix for ASC (earliest event: same columns ASC). Default is DESC. |
-| `businessDays(path: String!)` | `int?` | Business days from the date at `path` to today, using the org's business calendar. `path` is a dot-separated property path on the order (e.g. `"customValues.leg.pickup.scheduledAt"`). Returns `null` if path doesn't resolve or value isn't a parseable date. |
+| `lastTrackingEvent(eventDefinitionName, orderBy?)` | `TrackingEvent` | Most recent (or earliest) tracking event, resolved via batched DataLoader. `eventDefinitionName` may contain pipe-separated names such as `Departed|Delivered`; the resolver selects the winner across all matching definitions. `orderBy` is **honoured**: omit or prefix with `-` for DESC (latest event: `COALESCE(EventDate, Created) DESC, TrackingEventId DESC`); no prefix for ASC (earliest event: same columns ASC). Default is DESC. |
+| `businessDays(path: String!, contactId?: Int)` | `int?` | Business days from the date at `path` to today, using the org business calendar. Optional `contactId` scopes availability blocks to org-wide plus matching contact blocks. Instant values are converted to the org timezone before taking the date; date-only values are not timezone-shifted. Returns `null` if path does not resolve or value is not parseable. |
 | `attachmentsSummary` | `OrderAttachmentSummaryGqlDto` | `.totalCount` (int), `.hasAny` (bool) — batched DataLoader, backed by DB view |
 | `notesSummary` | `OrderNoteSummaryGqlDto` | `.totalCount` (int), `.hasAny` (bool) — batched DataLoader, backed by DB view |
 | `notesCount(threadFilter)` | `int` | |
@@ -179,6 +193,25 @@ inputs:
 
 **Known system customValues keys:**
 - `modeOfTransportationId` / `modeOfTransportationIdDescription` — transport mode
+- `terminalId` — terminal reference; sortable/filterable with `customValues.terminalId->terminal.name`
+- `deliveryLocationId` — contact-address reference; sortable/filterable with `customValues.deliveryLocationId->contactAddress.name`
+- `returnLocationId` — terminal or contact-address return-location reference; sortable/filterable with `customValues.returnLocationId->terminal.name` or `customValues.returnLocationId->contactAddress.name`
+
+**Join expression pattern** — Order queries can sort and filter by properties of entities referenced from `customValues` using `customValues.key->entity.property`. Supported aliases include `contact`, `order`, `modeOfTransportation`, `country`, `terminal`, `contactAddress`, `port`, and `vessel`. The `vessel` alias joins an integer custom value to `Vessel.VesselId`.
+
+```graphql
+orders(
+  organizationId: 1
+  orderBy: "customValues.deliveryLocationId->contactAddress.name"
+  filter: "customValues.returnLocationId->contactAddress.name:Chicago*"
+) { items { orderId orderNumber } }
+
+orders(
+  organizationId: 1
+  orderBy: "customValues.portId->port.name"
+  orderBy: "customValues.vesselId->vessel.name"
+) { items { orderId orderNumber } }
+```
 
 **Resolver pattern** — Many GraphQL fields resolve entities from customValues IDs:
-`getContact(idPropertyName)` reads `customValues[idPropertyName]` as a contact ID and returns the full Contact object. Same pattern for ports, vessels, countries, routes, etc.
+`getContact(idPropertyName)` reads `customValues[idPropertyName]` as a contact ID and returns the full Contact object. `getTerminal(idPropertyName)` uses the same pattern for terminal IDs. Same pattern for ports, vessels, countries, routes, etc.