@cxtms/cx-schema 1.9.67 → 1.9.241

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

@@ -18,8 +18,9 @@ Core tenant entity. Each organization represents a company/tenant in the system.
 | `faxNumber` | `string?` | |
 | `uniqueId` | `Guid` | Immutable external identifier |
 | `slug` | `string?` | URL-friendly identifier for Public API routes (lowercase, hyphenated) |
+| `organizationType` | `OrganizationType` | `Regular` (0) or platform-managed `SystemAdministration` (1) |
 | `isDeleted` | `bool` | Soft delete |
-| `customValues` | `Dictionary?` | jsonb, merged on update |
+| `customValues` | `Dictionary?` | jsonb, merged on update; incoming keys overwrite existing keys while unrelated keys are preserved |
 | `created` / `lastModified` | `DateTime` | Audit fields (from `AuditableEntity`) |
 | `createdBy` / `lastModifiedBy` | `string` | Audit fields |
 
@@ -37,5 +38,6 @@ Used by `PublicApiOrganizationResolver` to resolve org by slug or GUID in Public
 
 - `ChangeSlug(string?)` — trims and lowercases
 - `ChangeCompanyName(string)`, `ChangeAddressLine(string?)`, etc.
-- `ChangeCustomValues(Dictionary?)` — merges into existing values
+- `ChangeCustomValues(Dictionary?)` — initializes `CustomValues` when needed, merges incoming values into the existing dictionary, and overwrites matching keys without dropping unrelated keys
 - `DeleteOrganization()` — sets `IsDeleted = true`
+- `ChangeOrganizationType(OrganizationType)` — platform-only; ignored by dynamic update mutations

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

@@ -1,15 +1,37 @@
 # Shared Entity Reference
 
 ## Contents
+- EntityField
 - Tag
 - Attachment
 - Division
 - EquipmentType
+- Equipment
+- EquipmentStatus
 - PackageType
 - NoteThread
 - Note
 
-Tag, Attachment, Division, EquipmentType, PackageType, Note/NoteThread.
+EntityField, Tag, Attachment, Division, EquipmentType, Equipment, EquipmentStatus, PackageType, Note/NoteThread.
+
+## EntityField
+
+App-module field metadata used by grids, forms, filters, and entity extensions.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `entityFieldId` | `int` | PK |
+| `organizationId` | `int` | |
+| `entityTypeId` | `int` | FK to EntityType |
+| `name` | `string?` | Field name / path |
+| `fieldDefinition` | `Dictionary` | Original module field definition |
+| `isCustomField` | `bool` | True for custom field definitions |
+| `isInactive` | `bool` | Inactive fields are excluded when resolving fields for an `entityName` |
+| `priority` | `int` | Override precedence; if multiple active module fields have the same entity/name, highest priority wins |
+
+**GraphQL:** `entityFields(organizationId, entityName, filter, search, orderBy)` exposes `priority`. Supplying `entityName` applies inactive filtering and priority-based duplicate resolution.
+
+---
 
 ## Tag
 
@@ -103,6 +125,54 @@ No customValues. Linked to carriers via `CarrierEquipment` join.
 
 ---
 
+## Equipment
+
+Physical equipment units (trailers, containers, trucks) tracked within an organization.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `equipmentId` | `int` | PK |
+| `organizationId` | `int` | |
+| `unitNumber` | `string` | Required; unique per org |
+| `equipmentTypeId` | `int` | FK to EquipmentType |
+| `equipmentStatusId` | `int` | FK to EquipmentStatus |
+| `notes` | `string?` | |
+| `customValues` | `Dictionary` | jsonb |
+
+**Navigation:** `organization`, `equipmentType` (EquipmentType), `equipmentStatus` (EquipmentStatus)
+
+**Constraints:** `(organizationId, unitNumber)` unique index.
+
+---
+
+## EquipmentStatus
+
+User-defined statuses for equipment lifecycle management.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `equipmentStatusId` | `int` | PK |
+| `organizationId` | `int` | |
+| `statusName` | `string` | Required |
+| `statusDescription` | `string?` | |
+| `statusStage` | `EquipmentStatusStage` enum | Required |
+| `priority` | `int` | Required; controls display/sort order |
+
+**Navigation:** `organization`
+
+No customValues.
+
+### EquipmentStatusStage Enum
+
+| Value | Int |
+|-------|-----|
+| `Available` | 1 |
+| `InUse` | 2 |
+| `Maintenance` | 3 |
+| `OutOfService` | 4 |
+
+---
+
 ## PackageType
 
 | Field | Type | Notes |
@@ -172,5 +242,11 @@ Encrypted key-value store for sensitive configuration (API keys, tokens, credent
 **Table:** `secrets` (snake_case columns)
 **Provider:** `PostgresSecretManager` (default) or `AzureKeyVault` via `SecretManager:Provider` config.
 
-**GraphQL mutations:** `setSecret(organizationId, secretName, secretValue)`, `deleteSecret(organizationId, secretName)`.
-**Org scoping:** Commands validate user org membership; qualified name `org/{orgId}/{name}` is built by the command handler.
+**GraphQL mutations:** org-scoped secrets use input-wrapper mutations: `setSecret(input: { organizationId, secretName, secretValue }) { setSecretResult { secretName } }` and `deleteSecret(input: { organizationId, secretName }) { boolean }`.
+**Org scoping:** Commands validate user org membership; qualified name `org/{orgId}/{name}` is built by the command handler. Module `secret` fields must pass the current organization ID in the mutation input.
+
+---
+
+## EntityKind enum
+
+Known entity-kind values include `Order`, `Contact`, `OrderEntity`, `AccountingTransaction`, `Calendar`, `CalendarEvent`, `CalendarAvailabilityBlock`, `Other`, and `AuditChangeEntry`. Use `AuditChangeEntry` for audit-history result rows/change-log entries rather than a primary business entity.

package/skills/cxtms-developer/ref-graphql-query.md

@@ -28,7 +28,24 @@ orders(
 Entity-specific extras:
 - `orders` — `includeDraft: Boolean` (default false)
 
-Available root queries: `orders`, `contacts`, `commodities`, `accountingTransactions`, `jobs`, and others.
+Available root queries: `orders`, `contacts`, `commodities`, `accountingTransactions`, `jobs`, `entityFields`, and others.
+
+`entityFields` returns field metadata. When `entityName` is supplied, the API filters out inactive fields and duplicate field names resolve to the active definition with the highest `priority`.
+
+`getEntityFieldsLastModified(organizationId, entityName, filter)` returns the newest matching field timestamp (or `null`) for cheap saved-view reconciliation without fetching every definition. Entity-name matching is case-insensitive.
+
+Order quick search (`orders.search` and `orderGroupBy.search`) matches order number, bill-to, carriers, tracking numbers, order entities, commodity text/tracking numbers, and InventoryItem values linked through order commodities or child/container commodities. Inventory item matches include `sku`, `productName`, `description`, `modelNumber`, and JSON `customValues` such as color or size.
+
+## App Module Metadata Visibility
+
+GraphQL metadata queries hide rows attached to soft-deleted app modules:
+
+- `appComponents` / `appComponent` require the parent `AppModule.IsDeleted != true`
+- `appRoutes` and public route queries require the parent module to be active
+- `appPermissions` require the parent module to be active
+- `entityFields` exclude fields whose `EntityType.AppModule` is deleted
+
+Do not add extra client-side `isDeleted` filters for these metadata screens unless the UI also needs to expose deleted-module diagnostics.
 
 ## Filter Syntax (Lucene Query)
 
@@ -82,11 +99,61 @@ filter: "customValues.fieldName:\"exact match\""
 filter: "customValues.fieldName:NULL"
 ```
 
+### CustomValue join expressions
+
+When a custom value stores a foreign key to a supported entity, use `customValues.key->entity.property` to filter by a property on the joined row. Supported join aliases include `contact`, `order`, `modeOfTransportation`, `country`, `terminal`, `contactAddress`, `port`, and `vessel`. Vessel keys are integer `VesselId` values.
+
+```
+filter: "customValues.carrierId->contact.name:Acme*"
+filter: "customValues.terminalId->terminal.name:Chicago*"
+filter: "customValues.portId->port.name:Los Angeles*"
+filter: "customValues.vesselId->vessel.name:Ever*"
+filter: "customValues.deliveryLocationId->contactAddress.name:Warehouse*"
+filter: "NOT customValues.returnLocationId->contactAddress.contactAddressId:NULL"
+```
+
+For list-valued scalar columns, a negated match includes rows where the list column is null; a positive match requires a non-null list. For example, `NOT tags:Priority` matches null tag lists as well as lists that do not contain `Priority`.
+
 ### Filtered collections (bracket notation)
 ```
 filter: "children[category:CatA].name:test"
+filter: "contactAddresses[addressType:Billing|Shipping].contactAddressId:[1 TO *]"
+filter: "dispatchRouteStopOrders.dispatchRouteStop.dispatchRouteStopStatus.statusStage:Completed"
+```
+
+Inside `[path:value]`, pipe-separated values are OR-combined after trimming and normal type conversion. Use this for exact multi-value bracket filters in both `filter` and `orderBy`, e.g. `children[category:CatA|CatB].name` or `lastTrackingEvent[eventDefinition.eventName:Departed|Delivered].eventDate`.
+
+## Mutations
+
+### `importContacts`
+
+Bulk import contacts from an uploaded CSV, JSON, or XLSX file.
+
+```graphql
+mutation ImportContacts($input: ImportContactsInput!) {
+  importContacts(input: $input) {
+    added
+    updated
+    errors
+  }
+}
 ```
 
+`ImportContactsInput` fields:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `organizationId` | `Int!` | Tenant scope |
+| `fileUploadUrl` | `String!` | Uploaded file URL/path |
+| `contactType` | `ContactType` | Optional default for new rows; row-level `ContactType` wins |
+| `columnMappings` | `MapOfString` | Map internal field paths to inbound column headers |
+
+Behavior notes:
+- Matches existing contacts by `ContactId` first.
+- Ignores primary key fields during patching.
+- Skips nulls and empty strings on updates so blank cells do not clear existing values.
+- Resolves nested `division.divisionName` / `Division.DivisionName` to `DivisionId` when possible.
+
 ## OrderBy Syntax
 
 ```
@@ -97,25 +164,93 @@ orderBy: "customValues.fieldName"     # Custom field sort
 orderBy: "orderNumber~ToInt32"        # Type conversion during sort
 ```
 
-### `lastTrackingEvent` synthetic sort path (Order / Commodity)
+Join expressions are also valid in `orderBy`, including terminal and contact-address custom-value references:
 
-Sort the result list by the winning tracking event of each order or commodity. The "winner" is selected using `COALESCE(EventDate, Created) DESC/ASC, TrackingEventId DESC/ASC` — identical to the DataLoader logic — so SQL-level ordering and per-row resolution are always consistent.
+```
+orderBy: "customValues.terminalId->terminal.name"
+orderBy: "-customValues.returnLocationId->terminal.name"
+orderBy: "customValues.deliveryLocationId->contactAddress.name"
+orderBy: "customValues.portId->port.name"
+orderBy: "customValues.vesselId->vessel.name"
+orderBy: "orderSummary.totalPieces"
+```
+
+### Tracking-event synthetic sort paths (Order / Commodity)
+
+Sort the result list by the winning tracking event of each order or commodity. Use `lastTrackingEvent` for the newest matching event and `firstTrackingEvent` for the oldest matching event. Winners are selected using `COALESCE(EventDate, Created)` plus `TrackingEventId` as a tie-breaker, so SQL-level ordering and per-row resolution stay consistent.
 
 ```
 orderBy: "-lastTrackingEvent.eventDate"   # Latest event first (DESC)
-orderBy: "lastTrackingEvent.eventDate"    # Earliest event first (ASC)
+orderBy: "lastTrackingEvent.eventDate"    # Newest-event winner, sorted ASC
+orderBy: "firstTrackingEvent.eventDate"   # Oldest-event winner, sorted ASC
 ```
 
 Filter to a specific event type using bracket notation before sorting:
 
 ```
 orderBy: "-lastTrackingEvent[eventDefinition.eventName:Departed].eventDate"
+orderBy: "-lastTrackingEvent[eventDefinition.eventName:Departed|Delivered].eventDate"
+orderBy: "firstTrackingEvent[eventDefinition.eventName:Yard Scan|Archive Yard Scan].eventDate"
 ```
 
 - The bracket predicate (`[path:value]`) filters the `TrackingEvents` collection before the winner is picked.
+- Pipe-separated bracket values are OR-combined, so the winner can be selected from several event definitions.
 - Only `.eventDate` is supported as the sub-path. The expression resolves to `COALESCE(winner.EventDate, winner.Created)`, so null `EventDate` values fall back to `Created`.
 - Works on both `orders` and `commodities` top-level queries.
 
+### Commodity `getContact` resolver
+
+Commodities expose `getContact(idPropertyName: String!)` to resolve a contact ID stored in `customValues`. The lookup is scoped to the commodity organization and returns `null` when the custom value is missing or not a valid integer contact ID.
+
+```graphql
+{
+  commodities(organizationId: 1, take: 1) {
+    items {
+      commodityId
+      getContact(idPropertyName: "shipperContactId") {
+        contactId
+        name
+      }
+    }
+  }
+}
+```
+
+### Commodity related dispatch routes
+
+Commodities expose `getRelatedDispatchRoutes(filter, orderBy)` for dispatch routes linked through non-draft orders attached to the commodity or any descendant commodity.
+
+```graphql
+commodities(organizationId: 1, filter: "commodityId:5001") {
+  items {
+    commodityId
+    getRelatedDispatchRoutes(orderBy: "routeDate") {
+      dispatchRouteId
+      name
+      routeDate
+    }
+  }
+}
+```
+
+## Order Custom-Value Resolvers
+
+Orders expose `getContactAddress(idPropertyName: String!)` to resolve a contact-address id stored in `customValues` into a `contactAddress` object. The lookup is organization-scoped and returns null/empty when the custom-value key is missing.
+
+```graphql
+orders(organizationId: 1, take: 1) {
+  items {
+    orderId
+    getContactAddress(idPropertyName: "pickupContactAddressId") {
+      contactAddressId
+      name
+      addressLine
+      cityName
+    }
+  }
+}
+```
+
 ## Pagination
 
 ```graphql
@@ -197,6 +332,21 @@ Arguments: `organizationId: Int!`, `filter: String`, `search: String`, `take: In
 
 Filter fields: `entityName`, `primaryKey`, `userId`, `state`
 
+### Root-level: `auditEntityHistory` grid query filters
+
+The paged audit-history query accepts DataGrid/Lucene filter strings:
+
+- `entityName:"Order*"` — normalized to the entity path segment; quotes, trailing `*`, and trailing `~` are stripped.
+- `primaryKey:"123"` — narrows the S3 path to one entity key.
+- `timestamp:["2026-05-01T00:00:00Z" TO "NOW"]` — filters parsed audit file timestamps. ISO timestamps and date-math bounds (`NOW-7DAYS`, `NOW/DAY+1DAY`) are supported.
+- `user.fullName:"Jane*"` — resolves users by full name, first/last name, username, or email and filters by persisted `userId`.
+
+Sorting supports `timestamp` and `-timestamp`; descending timestamp is the default.
+
+### Entity fields lookup
+
+`entityFields(organizationId, entityName, filter, search, orderBy)` matches `entityName` with case-insensitive SQL `ILIKE`, so exact names and `ILIKE` patterns are both accepted. `search` matches field names by substring.
+
 ### Root-level: `auditChangeSummaries` query
 
 High-level summary of changes (grouped by change event):
@@ -283,6 +433,75 @@ High-level summary of changes (grouped by change event):
 | `userName` | `String` |
 | `email` | `String` |
 
+## Workflow Execution Queries
+
+### `executeWorkflow` idempotency
+
+The `executeWorkflow` mutation accepts an optional `executionId` GUID. Use one stable ID per retryable business operation, especially offline or mobile sync actions. Replays with the same organization, workflow, and `executionId` return the stored result instead of executing the workflow again; using the same ID for another workflow or organization is rejected.
+
+### `workflowExecutions` — paginated execution history
+
+Returns paginated `WorkflowExecutionLog` records. Supports Lucene filter scoping, free-text search, and sorting.
+
+```graphql
+{
+  workflowExecutions(
+    organizationId: 1
+    filter: "workflowId:abc123 AND status:Failed"
+    search: "user@example.com"
+    orderBy: "-executedAt"
+    take: 50
+    skip: 0
+  ) {
+    items {
+      executionId
+      workflowId
+      status
+      executedAt
+      userId
+    }
+    totalCount
+    pageInfo { hasNextPage hasPreviousPage }
+  }
+}
+```
+
+**Arguments:**
+
+| Argument | Type | Notes |
+|----------|------|-------|
+| `organizationId` | `Int!` | Required |
+| `filter` | `String` | Lucene query syntax — scope by any field |
+| `search` | `String` | Free-text: matches `userId`, `executionId`, `workflowId` |
+| `orderBy` | `String` | Default: `-executedAt` (newest first) |
+| `take` / `skip` | `Int` | Pagination |
+
+**`filter` examples:**
+```
+filter: "workflowId:abc123"
+filter: "status:Failed"
+filter: "userId:user@example.com AND status:Completed"
+```
+
+**`search` behavior:** case-insensitive match across `userId`, `executionId` (UUID string), and `workflowId` (UUID string).
+
+### `workflowExecution` — single execution by ID
+
+```graphql
+{
+  workflowExecution(
+    organizationId: 1
+    executionId: "00000000-0000-0000-0000-000000000000"
+  ) {
+    executionId
+    workflowId
+    status
+    executedAt
+    userId
+  }
+}
+```
+
 ## Discovering Fields
 
 **Always discover field names before building a query.** Do not guess field names — use the tools below.
@@ -326,3 +545,26 @@ GraphQL error messages reveal valid field/type names:
 
 - `npx cxtms schema <name>` — shows workflow/module JSON schema fields (not GraphQL)
 - Entity reference files (`ref-entity-*.md`) — document common fields, computed properties, and enums
+
+
+## Contact Nested Address Resolver
+
+Contacts expose `getContactAddresses(filter, orderBy)` for loading only the addresses needed by a selection set. Prefer this resolver over raw `contactAddresses` when the UI/workflow needs server-side filtering or deterministic sorting.
+
+```graphql
+query {
+  contacts(organizationId: 1, filter: "contactId:123") {
+    items {
+      contactId
+      name
+      getContactAddresses(filter: "addressType:Shipping", orderBy: "cityName") {
+        contactAddressId
+        addressType
+        cityName
+        stateCode
+        countryCode
+      }
+    }
+  }
+}
+```

package/skills/cxtms-module-builder/SKILL.md

@@ -172,10 +172,10 @@ Read the relevant category ref file when building specific component types:
 |----------|-----------|------|
 | **Layout & Structure** | `layout`, `row`, `col`, `header`, `tabs`, `toolbar`, `card`, `line`, `slot` | `skills/cxtms-module-builder/ref-components-layout.md` |
 | **Forms & Input** | `form`, `field`, `field-collection`, `barcodeScanner` | `skills/cxtms-module-builder/ref-components-forms.md` |
-| **Data Display** | `dataGrid`, `text`, `markup`, `badge`, `icon`, `image`, `photo`, `summary`, `diff`, `viewer`, `embed` | `skills/cxtms-module-builder/ref-components-display.md` |
+| **Data Display** | `dataGrid`, `text`, `markup`, `badge`, `avatar`, `infoLine`, `progressBar`, `icon`, `image`, `photo`, `summary`, `diff`, `viewer`, `embed` | `skills/cxtms-module-builder/ref-components-display.md` |
 | **Interactive & Nav** | `button`, `dropdown`, `menuButton`, `link`, `redirect`, `navbar`, `navbarItem`, `navbarLink`, `navDropdown` | `skills/cxtms-module-builder/ref-components-interactive.md` |
 | **Data & Collections** | `collection`, `list`, `listItem`, `datasource`, `script` | `skills/cxtms-module-builder/ref-components-data.md` |
-| **Specialized** | `calendar`, `notes`, `dashboard`, `dashboard-widget`, `widget`, `timeline`, `timeline-grid`, `oauth2` | `skills/cxtms-module-builder/ref-components-specialized.md` |
+| **Specialized** | `calendar`, `notes`, `dashboard`, `dashboard-widget`, `widget`, `timeline`, `timeline-grid`, `planner`, `oauth2` | `skills/cxtms-module-builder/ref-components-specialized.md` |
 
 ### Templates
 
@@ -224,9 +224,10 @@ entities:
         fieldType: text | number | date | boolean | ...
         displayName: { en-US: "..." }
         isCustomField: false
+        priority: 0              # Optional override precedence; highest active duplicate field wins
         props:
           allowOrderBy: true
-          allowFilter: true
+          allowFilter: true       # Boolean or template expression, e.g. "{{ canFilterField }}"
           filter:                          # Optional filter selector
             component: "Contacts/Select"
             props:
@@ -276,6 +277,7 @@ onClick:
   - navigateBack: { fallback: "/home" }                    # Go back in history
   - navigateBackOrClose: { fallback: "/home" }             # Go back or close dialog
   - refresh: "componentName"                               # Refresh a component
+  - reload: "formName"                                    # Refetch and replace a form's initial values
   - notification: { message: { en-US: "Saved!" }, type: success }  # success|error|warning|info
   - confirm: { title: { en-US: "Delete?" }, message: { en-US: "Are you sure?" } }
   - mutation:
@@ -290,6 +292,7 @@ onClick:
       onError: [...]
   - setFields: { "fieldName": "{{ value }}" }              # Set form field values
   - setStore: { "key": "{{ value }}" }                     # Set store values
+  - setSessionStorage: { key: "isDevMode", value: "true" } # Set tab-scoped sessionStorage
   - validateForm: {}                                        # Trigger form validation
   - dialog:
       name: "dialogName"
@@ -312,6 +315,8 @@ onClick:
   - consoleLog: { message: "debug info" }
   - openBarcodeScanner: { onScan: [...] }
   - resetDirtyState: {}
+  - sound: success                                         # success|error|warning|scan
+  - vibrate: light                                         # success|error|warning|light|medium|heavy
 ```
 
 ## Common Patterns
@@ -328,6 +333,7 @@ displayName:
 value: "{{ fieldName }}"                    # Simple variable
 value: "{{ format date L }}"               # Format helper
 value: "{{ number quantity }}"             # Type cast
+value: "{{ sessionStorage isDevMode }}"    # Current-tab sessionStorage
 value: "{{ eval items.length > 0 }}"       # JavaScript expression
 isHidden: "{{ eval !canEdit }}"            # Conditional visibility
 ```
@@ -400,7 +406,7 @@ Reusable select components (e.g., `Countries/Select`, `Ports/Select`) follow thi
                 entity(...) { entityId name }
               }
             variables: { entityId: "{{number entityId}}" }
-      onEditClick:                           # Edit action on selected item
+      onEditClick:                           # Edit action on selected item (also supported on text fields)
         - dialog:
             component: { layout: { component: layout, children: [{ component: Entity/UpdateEntity }] } }
 ```
@@ -473,5 +479,26 @@ npx cxtms app release -m "Add warehouse locations module" --org 42
 6. **Set proper entityKind** when defining entities (Order, Contact, OrderEntity, AccountingTransaction, Calendar, CalendarEvent, Other)
 7. **DataGrid options** requires ALL properties: query, rootEntityName, entityKeys, navigationType, enableDynamicGrid, enableViews, enableSearch, enablePagination, enableColumns, enableFilter, defaultView, onRowClick
 8. **Form component** requires `validationSchema` in props
-9. **Do not change `appModuleId` or `filePath`** — set correctly by CLI scaffold
-10. **Always validate** the final YAML: `npx cxtms <file.yaml>`
+9. **Adaptive (mobile/tablet/desktop) design by default** — every form and layout must work on phones (`xs`), tablets (`sm`/`md`), and desktops (`lg+`):
+   - Wrap form fields in a `layout` child with `itemDefaults.size: { xs: 12, md: 6 }` (1 col on phone, 2 col on tablet+)
+   - Long fields (`textarea`, `quill`, `attachment`, multi-line `notes`) → `size: { xs: 12 }` (always full width)
+   - Cap visible columns: max 2 on `sm`, 3 on `md`, 4 on `lg`
+   - Group large forms into `card` sections that reflow with `size: { xs: 12, lg: 6 }`
+   - **Use modern MUI Grid v2 spacing**: `columnSpacing` + `rowSpacing` (both accept responsive maps `{ xs, sm, md, lg, xl }`) per https://mui.com/material-ui/react-grid/#row-and-column-spacing. Use `spacing` only when both axes should match.
+   - For details, see `skills/cxtms-module-builder/ref-components-layout.md` ("Adaptive / Responsive Design") and `skills/cxtms-module-builder/ref-components-forms.md` ("Mobile-Friendly Form Layout")
+10. **Do NOT use these legacy / forbidden layout patterns:**
+    - **No `cols: N`** on `layout` or `form` — non-responsive, ignored on mobile. Use `itemDefaults: { size: { xs: 12, md: <12/N> } }` instead.
+    - **No `row` component** in new code — use `layout` with responsive `columns` and `itemDefaults.size`. Existing `row` usages can stay.
+    - **No CSS class names (`className`) for layout** — neither on `layout`, `row`, nor `col`. Layouts must control sizing and spacing through `size`, `columns`, `spacing`/`rowSpacing`/`columnSpacing`, and `sx` / `containerSx` / `itemDefaults.sx`. Bootstrap-style classes (`col-md-6`, `row`, `container-fluid`) do not affect MUI Grid and have no effect.
+    - **No bare `spacing: <number>` for adaptive layouts** — use a breakpoint map (`spacing: { xs: 1, md: 3 }`) or split into `columnSpacing`/`rowSpacing`.
+11. **Do not change `appModuleId` or `filePath`** — set correctly by CLI scaffold
+12. **Always validate** the final YAML: `npx cxtms <file.yaml>`
+
+
+## Reactive page titles
+
+Route `props.title` and root component `displayName` may be template expressions. App screens parse them against the app module store and update the page header/browser title when store values change. Unauthorized-route labels intentionally use route name/path instead of parsing store-backed title templates.
+
+## Screen route variables
+
+Matched route parameters are raw strings and are available on the component's first render, including when a cached component definition mounts. Query-string values that look numeric are converted to numbers. When names collide, the matched route parameter wins over the query string. Screen variables also include `organizationId`, `locale`, and `currentUser`.

package/skills/cxtms-module-builder/ref-components-data.md

@@ -7,6 +7,91 @@
 - Datasource component
 - Script component
 
+## dataGrid export identity keys
+
+Saved views reconcile automatically with newer entity-field schemas before their first data load. Removed fields and filters are dropped, nested reference columns are resolved, and YAML-declared computed columns are preserved.
+
+`rowStyles.conditions` accepts a semantic `variant` or template-resolved hex `color` for theme-aware row and hover tints. Matching conditions apply in order; the last value wins.
+
+DataGrid table views support `includeEntityKeysInExport` on each view. It defaults to `true` and forces entity key/primary key fields into exports so rows can be matched by ID on re-import. Set it to `false` only when exports must omit internal IDs.
+
+On phone layouts, DataGrid pagination already reduces inline padding and the page-size select width below the MUI `sm` breakpoint. When placing grids in dialogs or cards, avoid adding extra horizontal padding around the grid unless it is required by the surrounding design.
+
+```yaml
+component: dataGrid
+name: contactsGrid
+props:
+  options:
+    query: contacts
+    rootEntityName: Contact
+    entityKeys: [contactId]
+  views:
+    - name: allContacts
+      includeEntityKeysInExport: true
+      columns:
+        - name: name
+        - name: emailAddress
+```
+
+
+## dataGrid static items inherit parent variables
+
+When `options.items` is a template expression, the grid parses it with local variables, store values, and parent component variables. Nested grids can reference parent-scope values such as collection items or datasource results:
+
+```yaml
+component: dataGrid
+name: commodityLines
+props:
+  options:
+    items: "{{ order.commodities }}"
+    entityKeys: [commodityId]
+```
+
+Use `options.items` for already-loaded arrays; use `options.query` for server-side search/sort/pagination.
+
+---
+
+## dataGrid conditional filter columns
+
+DataGrid column `props.allowFilter` accepts either a boolean or a template expression. The filter column picker evaluates the expression with the grid's current variables before deciding whether the column can be added as a filter.
+
+```yaml
+component: dataGrid
+name: ordersGrid
+props:
+  views:
+    - name: operations
+      columns:
+        - name: orderStatusName
+          props:
+            allowFilter: "{{ currentUser.canFilterStatus }}"
+```
+
+Dynamic entity fields use the same rule through `fieldDefinition.props.allowFilter`.
+
+---
+
+## dataGrid sticky column state
+
+DataGrid table headers let users pin columns left or right. The active view stores pinned column names under `stickyColumns.left[]` and `stickyColumns.right[]`; left-pinned columns render first, normal columns render in their original order, and right-pinned columns render last.
+
+```yaml
+component: dataGrid
+name: ordersGrid
+props:
+  views:
+    - name: operations
+      stickyColumns:
+        left: [orderNumber]
+        right: [orderStatusName]
+      columns:
+        - name: orderNumber
+        - name: customerName
+        - name: orderStatusName
+```
+
+---
+
 ## collection
 
 Iterates over data items and renders children as templates. Supports drag-and-drop reordering.