@cxtms/cx-schema 1.9.258 → 1.9.260

package/schemas/workflows/agent/agent.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "agent/agent.json",
+  "title": "Agent section",
+  "description": "Configuration for workflowType: Agent. An LLM agent that calls other workflows as tools.",
+  "type": "object",
+  "required": ["instructions"],
+  "properties": {
+    "description": { "type": "string", "description": "What this agent does. Shown to callers and to other agents that may invoke it." },
+    "ui": {
+      "type": "object",
+      "description": "How the AI Assistant chat shows this agent. Display-only; no runtime effect.",
+      "properties": {
+        "name": { "type": "string", "description": "Display name. Defaults to the workflow name." },
+        "shortDescription": { "type": "string", "description": "One line under the name, e.g. 'Status, ETAs, exceptions, POD'." },
+        "icon": { "type": "string", "description": "Tabler icon name without the 'tabler-' prefix, e.g. 'map-pin'. Defaults to 'robot'." },
+        "color": { "type": "string", "enum": ["primary", "secondary", "info", "success", "warning", "error"], "description": "Theme palette color for the agent's icon. Defaults to 'primary'." },
+        "prompts": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "description": "Suggested prompts shown on an empty chat. At most 5." }
+      },
+      "additionalProperties": false
+    },
+    "instructions": { "type": "string", "minLength": 1, "description": "System instructions. Handlebars template over workflow variables and inputs." },
+    "model": {
+      "type": "object",
+      "properties": {
+        "fromConfig": { "type": "string", "description": "Organization config name holding provider, model, apiKey, endpoint. Default ai.default." },
+        "name": { "type": "string", "description": "Overrides the config's model name." },
+        "temperature": { "type": "number", "minimum": 0, "maximum": 2 },
+        "contextWindow": { "type": "integer", "minimum": 1, "description": "The model's context window in tokens. Needed when this agent overrides the model name via model.name: the organization config's window describes the config's model, not this one. Defaults to 256000 when neither the agent nor the resolved model configuration declares one." }
+      },
+      "additionalProperties": false
+    },
+    "session": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string", "enum": ["task", "chat"], "default": "task", "description": "task ends when set_result is called; chat is open-ended." },
+        "maxTurns": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 },
+        "timeout": { "type": "integer", "minimum": 1, "default": 300, "description": "Seconds." }
+      },
+      "additionalProperties": false
+    },
+    "result": {
+      "type": "object",
+      "description": "JSON Schema (type: object) for the set_result argument.",
+      "properties": { "type": { "const": "object" } },
+      "required": ["type"]
+    },
+    "skills": { "type": "array", "items": { "type": "string" }, "description": "Installed skill names to enable (runtime in a later release)." },
+    "tools": {
+      "type": "array",
+      "description": "Tools the agent may call: other workflows, or built-in tools. Each entry has exactly one of 'workflow' or 'builtin'.",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": ["workflow"],
+            "properties": {
+              "workflow": { "type": "string", "minLength": 1, "description": "Workflow name or workflowId to expose as a tool." },
+              "instructions": { "type": "string", "description": "When and how the agent should use this tool." },
+              "mode": { "type": "string", "enum": ["auto", "approval", "always"], "default": "auto", "description": "'auto' runs the tool as soon as the model calls it. 'approval' pauses a chat session until a person approves or declines the call, unless the chat is in Auto approval mode, where it runs and is recorded as auto-approved. 'always' pauses a chat session for a person in every approval mode. A task session (no person present) refuses 'approval' and 'always' calls outright and tells the agent it needs human approval." }
+            },
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "required": ["builtin"],
+            "properties": {
+              "builtin": { "type": "string", "enum": ["data.query", "data.schema", "data.type"], "description": "A built-in, read-only data tool. data.query runs a GraphQL query in the agent's organization (tool data_query); data.schema lists query fields and types (data_schema); data.type describes one type (data_type)." },
+              "instructions": { "type": "string", "description": "When and how the agent should use this tool." },
+              "mode": { "type": "string", "enum": ["auto", "approval", "always"], "default": "auto", "description": "Same meaning as for workflow tools." }
+            },
+            "additionalProperties": false
+          }
+        ]
+      }
+    },
+    "mcp": {
+      "type": "array",
+      "items": { "type": "object", "required": ["fromConfig"], "properties": { "fromConfig": { "type": "string" } }, "additionalProperties": false },
+      "description": "Outbound MCP connections (runtime in a later release)."
+    },
+    "agents": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "agent": { "type": "string", "description": "Name of another Agent workflow in this organization." },
+          "url": { "type": "string", "format": "uri", "description": "Remote A2A agent card URL." },
+          "modes": { "type": "array", "items": { "type": "string", "enum": ["task", "chat"] } }
+        },
+        "oneOf": [{ "required": ["agent"] }, { "required": ["url"] }],
+        "additionalProperties": false
+      },
+      "description": "Allow list of agents this agent may invoke (runtime in a later release)."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/workflows/tasks/attachment.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Attachment Tasks",
-  "description": "Attachment entity CRUD operations",
+  "description": "Attachment entity CRUD operations and entity links",
   "type": "object",
   "properties": {
     "task": {
@@ -9,6 +9,8 @@
       "enum": [
         "Attachment/Create@1",
         "Attachment/Update@1",
+        "Attachment/Link@1",
+        "Attachment/Unlink@1",
         "Attachment/Delete@1",
         "Attachment/Get@1",
         "Attachment/Thumbnail",
@@ -48,13 +50,67 @@
           "type": "string",
           "description": "Attachment ID"
         },
+        "attachment": {
+          "type": "object",
+          "description": "Attachment values (Attachment/Create@1, Attachment/Update@1)",
+          "properties": {
+            "fileName": {
+              "type": "string"
+            },
+            "attachmentType": {
+              "type": "string",
+              "description": "Picture, OtherDocument, Avatar, CustomerDocument"
+            },
+            "description": {
+              "type": "string"
+            },
+            "parentType": {
+              "type": "string",
+              "description": "Primary parent type: Order, Contact, AccountingTransaction, EquipmentType, Job, Commodity, Route, TrackingEvent"
+            },
+            "parentId": {
+              "type": "string",
+              "description": "Primary parent ID"
+            },
+            "links": {
+              "type": "array",
+              "description": "Additional entity links on create (Attachment/Create@1)",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "entityType": {
+                    "type": "string",
+                    "description": "Linked entity type: Order, Contact, Job, TrackingEvent"
+                  },
+                  "entityId": {
+                    "type": "string",
+                    "description": "Linked entity ID (int id; uuid for Job)"
+                  }
+                },
+                "required": ["entityType", "entityId"]
+              }
+            }
+          },
+          "additionalProperties": true
+        },
+        "fileData": {
+          "description": "File content: base64 string, byte array or stream (Attachment/Create@1)"
+        },
+        "fileUrl": {
+          "type": "string",
+          "description": "URL to download the file from (Attachment/Create@1)"
+        },
         "entityName": {
           "type": "string",
           "description": "Parent entity name"
         },
+        "entityType": {
+          "type": "string",
+          "description": "Entity type to link/unlink: Order, Contact, Job, TrackingEvent (Attachment/Link@1, Attachment/Unlink@1)"
+        },
         "entityId": {
           "type": "string",
-          "description": "Parent entity ID"
+          "description": "Entity ID to link/unlink: int id, uuid for Job (Attachment/Link@1, Attachment/Unlink@1)"
         },
         "fileName": {
           "type": "string",

package/schemas/workflows/workflow.json

@@ -67,8 +67,8 @@
         },
         "workflowType": {
           "type": "string",
-          "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."
+          "enum": ["Process", "Document", "Quote", "Flow", "Webhook", "PublicApi", "McpTool", "McpResource", "McpPrompt", "Agent", "EmailTemplate", "RulesTariff"],
+          "description": "Workflow type: Process (standard workflow), Document (PDF/Excel generation), Quote, Flow (declarative state machine), Webhook (HTTP endpoint), PublicApi (REST API endpoint), McpTool, McpResource, McpPrompt (organization-scoped MCP tools, resources and prompts), Agent (LLM agent), EmailTemplate or RulesTariff. Omit for standard process workflows."
         },
         "runAs": {
           "type": "string",
@@ -279,6 +279,7 @@
       },
       "additionalProperties": false
     },
+    "agent": { "$ref": "agent/agent.json" },
     "entity": {
       "$ref": "flow/entity.json",
       "description": "Entity configuration for Flow workflows"
@@ -308,24 +309,18 @@
   "required": ["workflow"],
   "allOf": [
     {
-      "if": {
-        "properties": {
-          "workflow": {
-            "properties": {
-              "workflowType": { "const": "Flow" }
-            },
-            "required": ["workflowType"]
-          }
-        }
-      },
-      "then": {
-        "required": ["workflow", "entity"],
-        "properties": {
-          "activities": false
-        }
-      },
+      "if": { "properties": { "workflow": { "properties": { "workflowType": { "const": "Flow" } }, "required": ["workflowType"] } } },
+      "then": { "required": ["workflow", "entity"], "properties": { "activities": false } },
       "else": {
-        "required": ["workflow", "activities"]
+        "if": { "properties": { "workflow": { "properties": { "workflowType": { "const": "Agent" } }, "required": ["workflowType"] } } },
+        "then": {
+          "required": ["workflow", "agent"],
+          "properties": {
+            "activities": false,
+            "workflow": { "properties": { "executionMode": { "const": "Sync" } }, "required": ["executionMode"] }
+          }
+        },
+        "else": { "required": ["workflow", "activities"] }
       }
     },
     {

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

@@ -13,8 +13,8 @@ Real-time notification system. Notifications are org-scoped with per-user read t
 | `type` | `NotificationType` | System=0, OrderUpdate=1, TaskAssignment=2, Alert=3, Info=4 |
 | `priority` | `NotificationPriority` | Low=0, Normal=1, High=2, Urgent=3 |
 | `targetUserId` | `string?` | If set, targets one user; if null, broadcasts to all active org users |
-| `entityType` | `string?` | Linked entity type (e.g. "Order", "Job") |
-| `entityId` | `int?` | Linked entity PK |
+| `entityType` | `string?` | Linked entity type (e.g. "Order", "Job", "AgentSession") |
+| `entityId` | `string?` | Linked entity id (varchar(64)). Most entity types still store an integer PK as text; `entityType: "AgentSession"` carries the session's GUID (`AgentSessionId.ToString()`) instead. |
 | `expiresAt` | `DateTime?` | Optional expiration |
 | `created` / `lastModified` | `DateTime` | Audit fields (from `AuditableEntity`) |
 | `createdBy` / `lastModifiedBy` | `string` | Audit fields |

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

@@ -77,7 +77,7 @@ Tagging system for orders, commodities, inventory items.
 
 ## Attachment
 
-File attachments linked to orders, contacts, jobs, etc.
+File attachments. `parentType`/`parentId` is the primary parent; an attachment can also be linked to more Orders, Contacts, Jobs and TrackingEvents (link tables).
 
 | Field | Type | Notes |
 |-------|------|-------|
@@ -91,7 +91,7 @@ File attachments linked to orders, contacts, jobs, etc.
 | `description` | `string?` | |
 | `attachmentType` | `AttachmentType` enum | Picture=1, OtherDocument, Avatar, CustomerDocument |
 | `parentId` | `string?` | Polymorphic FK (entity ID as string) |
-| `parentType` | `AttachmentParentType` enum | None=0, Order=1, Contact=2, AccountingTransaction=3, EquipmentType=4, Job=5, Commodity=6 |
+| `parentType` | `AttachmentParentType` enum | None=0, Order=1, Contact=2, AccountingTransaction=3, EquipmentType=4, Job=5, Commodity=6, Route=7, TrackingEvent=8 |
 | `status` | `AttachmentStatus` enum | Active=0, PendingUpload=1, UploadFailed=2 |
 | `category` | `AttachmentCategory` enum | General=0, FieldValue=1 |
 | `organizationId` | `int` | |
@@ -103,6 +103,10 @@ File attachments linked to orders, contacts, jobs, etc.
 - `presignedFileUri`, `presignedPreviewUri`, `presignedThumbnailUri` — signed URLs
 - `getPresignedUri(expiresInDays, uriType)` — custom resolver
 - `getParentOrder` — resolve parent Order
+- `links { entityType entityId }` — all links, including the primary one
+- Filter by link: `attachments(filter: "orderLinks.orderId:123")` — also `contactLinks.contactId`, `jobLinks.jobId`, `trackingEventLinks.trackingEventId`
+- `job { getJobAttachments }`, `trackingEvent { getTrackingEventAttachments }` — attachments linked to the entity
+- Mutations: `linkAttachment` / `unlinkAttachment` (`attachmentId`, `entityType`, `entityId`); `createAttachment` `values.links: [{ entityType, entityId }]`. Workflows: `Attachment/Link@1`, `Attachment/Unlink@1`
 
 ---
 

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

@@ -315,8 +315,9 @@ onClick:
   - consoleLog: { message: "debug info" }
   - openBarcodeScanner: { onScan: [...] }
   - resetDirtyState: {}
-  - sound: success                                         # success|error|warning|scan
-  - vibrate: light                                         # success|error|warning|light|medium|heavy
+  - sound: success                    # audible cue: success|error|warning|scan (or { type, volume: 0-1 })
+  - vibrate: success                  # haptic: success|error|warning|light|medium|heavy
+  - vibrate: { pattern: [100, 50, 100] }   # custom ms pattern (web Vibration API convention) or { duration: 200 }
 ```
 
 ## Common Patterns
@@ -334,10 +335,87 @@ 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
+isHidden: "{{ !canEdit }}"                 # Negation — no eval needed
+value: "{{ eval items.map(x => x.id) }}"   # JavaScript eval — last resort
 ```
 
+**Prefer built-in template functions over `eval`.** The engine ships named functions for
+the common cases — use them first. Reach for `eval` only when nothing below fits
+(array `.map()`/`.filter()`, arithmetic, template literals, object building, ternaries).
+
+| Function | Example | Notes |
+|----------|---------|-------|
+| `number` / `number!` | `{{ number quantity }}` | Cast to number; `number!` returns `0` for null |
+| `string` / `boolean` | `{{ boolean isActive }}` | Cast; `boolean` treats string `'true'` as true |
+| `nullIfEmpty` | `{{ nullIfEmpty notes }}` | `''`, `0`, undefined → null |
+| `luceneString` | `{{ luceneString search }}` | Escape for Lucene filter strings |
+| `isEqual` | `{{ isEqual status 'Pending' }}` | Deep equality; numeric strings coerced |
+| `isTrue` | `{{ isTrue customValues.flag }}` | `true`, `'true'`, or truthy |
+| `isNullOrEmpty` | `{{ isNullOrEmpty orderNumber }}` | null, undefined, `''`, or empty array |
+| `any` | `{{ any selectedItems }}` | Array/string has at least one element |
+| `moreThan` / `lessThan` | `{{ moreThan totalAmount 100 }}` | Numbers by value; arrays/strings by length |
+| `startsWith` / `endsWith` | `{{ startsWith trackingNumber 'TRK' }}` | String prefix/suffix check |
+| `includes` / `contains` | `{{ includes description 'rush' }}` | Substring check (aliases) |
+| `trim` | `{{ trim name }}` | Trim whitespace |
+| `round` | `{{ round totalAmount 2 }}` | `toFixed(n)` returned as number |
+| `encodeURIComponent` | `{{ encodeURIComponent returnUrl }}` | URL-encode |
+| `format` | `{{ format createdDate L }}` | moment format (`L`, `MM/DD/YYYY`, `fromNow`, …) |
+| `formatTz` | `{{ formatTz pickupDate 'MM/DD h:mm A' 'America/New_York' }}` | Format UTC value in a timezone |
+| `dateDiff` | `{{ dateDiff dueDate startDate }}` | Whole days, first minus second |
+| `daysBetween` | `{{ daysBetween pickupDate deliveryDate }}` | Absolute day difference |
+| `daysUntil` / `daysAgo` | `{{ daysUntil dueDate }}` | Days between now and the date |
+| `isDateBefore` / `isDateAfter` | `{{ isDateBefore pickupDate deliveryDate }}` | Date comparison |
+| `hasPermission` | `{{ hasPermission Orders/Update }}` | Current user permission check |
+| `fromConfig` | `{{ fromConfig apps.myFeature key }}` | Organization config lookup |
+| `localStorage` / `sessionStorage` | `{{ localStorage recentSearch }}` | Browser storage read |
+| `parse` | `{{ parse configs.labelTemplate }}` | Re-parse a template stored in a variable |
+
+Combinators — also no `eval` needed:
+- `!` / `!!` prefix negates / booleanizes any path or function: `{{ !isEqual status 'Pending' }}`, `{{ !!order.notes }}`
+- `||` / `&&` combine paths and comparisons: `{{ orderId || quoteId }}`, `{{ !pickupForm.contactAddressId || !pickupForm.pickupDate }}`
+- `?.` optional chaining inside paths: `{{ order?.customer?.name }}`
+- Quoted arguments are string literals; parenthesized arguments evaluate as nested expressions
+
+```yaml
+# ❌ eval where a built-in exists
+disabled: "{{ eval status !== 'Pending' }}"
+isHidden: "{{ eval selectedItems.length === 0 }}"
+# ✅ built-in equivalents
+disabled: "{{ !isEqual status 'Pending' }}"
+isHidden: "{{ !any selectedItems }}"
+```
+
+**When `eval` is genuinely needed, keep it human-readable.** Inline form is only for
+trivial expressions. Anything longer (ternaries, method chains, or ~60+ characters)
+MUST be written as a multiline YAML block scalar:
+
+```yaml
+# Multiline eval — block scalar, one clause per line
+color: >-
+  {{ eval
+    item.status === 'delayed' ? '#e53e3e'
+    : item.priority === 'high' ? '#ffa726'
+    : '#4ecdc4'
+  }}
+label: >-
+  {{ eval
+    attachments.items
+      .map(x => x.fileName)
+      .join(', ')
+  }}
+```
+
+Multiline eval rules:
+- **Always use `>-` (folded, strip)** — never `>`, `|`, or `|+`. Those keep a trailing
+  newline, so the value no longer ends with `}}` and the engine silently falls back to
+  string interpolation instead of evaluating the expression.
+- The block must contain exactly one `{{ eval ... }}` and nothing else — surrounding text
+  or a second `{{ }}` also switches the engine to string interpolation.
+- Block scalars need no YAML quoting or escaping — use natural JavaScript quotes
+  (`'` or `"`) inside the expression.
+- Put `{{ eval` on the first line, one clause per indented line, and `}}` on its own
+  closing line.
+
 ### Permissions
 ```yaml
 permission: "ModuleName/Read"                # Single string (PascalCase/Action)
@@ -474,7 +552,7 @@ npx cxtms app release -m "Add warehouse locations module" --org 42
    - Component names: Module/Component pattern (e.g., `WarehouseLocations/List`)
    - Route paths: kebab-case (e.g., `/warehouse-locations`)
    - Permission names: PascalCase with slashes (e.g., `WarehouseLocations/Read`, `System/Contacts/Update`)
-4. **Template expressions** use `{{ expression }}` syntax (double curly braces)
+4. **Template expressions** use `{{ expression }}` syntax (double curly braces); prefer built-in functions (`isEqual`, `any`, `isNullOrEmpty`, `format`, …) over `eval`, and write non-trivial `eval` expressions as multiline block scalars (`>-`) — see Template expressions
 5. **Include filePath** property pointing to the YAML file location
 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

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

@@ -314,7 +314,7 @@ props:
           - navigate: "orders/{{ item.id }}"
       - label: "Delete"
         icon: trash
-        disabled: "{{ eval item.status === 'Completed' }}"
+        disabled: "{{ isEqual item.status 'Completed' }}"
         onClick:
           - confirm: { title: { en-US: "Delete?" } }
   onClick:

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

@@ -477,21 +477,6 @@ props:
 
 Compact theme-aware badge. Prefer semantic variants for new modules; the dot is opt-in.
 
-## avatar, infoLine, and progressBar
-
-Use these template-aware display components for compact entity cards and planner headers.
-
-```yaml
-- component: avatar
-  props: { name: '{{ row.record.name }}', colorSeed: '{{ row.record.id }}', size: 40 }
-- component: infoLine
-  props: { icon: tabler-phone, value: '{{ row.record.phone }}', href: 'tel:{{ row.record.phone }}' }
-- component: progressBar
-  props: { items: '{{ row.items }}', completedPath: status, completedValue: Completed }
-```
-
-`avatar` derives initials from names/email and uses `src` as an optional image. `infoLine` renders nothing for an empty value and only links allowlisted URL schemes. `progressBar` accepts direct `value`/`max` or derives counts from `items`; choose `count`/`percent` and `linear`/`circular`/`segmented` display modes. On mobile, `activeColor` and `trackColor` customize segmented progress; `tooltip` is exposed to assistive technology rather than hover UI.
-
 **Props:**
 | Prop | Type | Description |
 |------|------|-------------|
@@ -534,6 +519,104 @@ props:
 
 ---
 
+## avatar
+
+Template-aware display component for compact entity cards and planner headers. Circular avatar with automatic two-letter initials. Sources tried in priority order: `src` image → `firstName` + `lastName` → `name` → `email` → placeholder user icon. Color is picked deterministically from the theme palette by hashing `colorSeed`.
+
+**Props (all template-parsed):**
+| Prop | Type | Description |
+|------|------|-------------|
+| `src` | `string` | Image URL; falls back to initials when empty or broken |
+| `name` | `string` | Full name: `Andre Kovac` → AK, `Kovac, Andre` → AK, `Madonna` → MA |
+| `firstName` / `lastName` | `string` | Explicit name parts (organization user form); take priority over `name` |
+| `email` | `string` | Last text fallback: local part, digits dropped (`andre.kovac@…` → AK) |
+| `colorSeed` | `string\|number` | Stable color seed — use an id (`contactId`, user id), not the name |
+| `color` | `string` | Pin a theme color: `primary` \| `secondary` \| `error` \| `warning` \| `info` \| `success` |
+| `bgcolor` / `textColor` | `string` | Explicit CSS color overrides |
+| `size` | `number` | Diameter in px, default 40 |
+| `variant` | `string` | `circular` (default) \| `rounded` \| `square` |
+| `skin` | `string` | `light` (default, tinted bg) \| `filled` \| `light-static` |
+| `tooltip` | `string\|localized` | Tooltip on hover |
+| `onClick` | `Action[]` | Actions on click; when present the avatar is clickable |
+
+```yaml
+component: avatar
+name: driverLaneAvatar
+props:
+  name: '{{ row.record.name }}'
+  colorSeed: '{{ row.record.contactId }}'
+  size: 40
+```
+
+---
+
+## infoLine
+
+Compact "icon + value" line for entity cards (phone, email, truck, container…). Abstract: YAML assembles the value string, the component only renders it. **An empty value renders nothing**, so optional lines can be declared unconditionally.
+
+**Props (all template-parsed):**
+| Prop | Type | Description |
+|------|------|-------------|
+| `icon` | `string` | Icon class: `tabler-phone`, `tabler-mail`, `tabler-truck`, `tabler-container`, FA names |
+| `iconColor` | `string` | Theme path or CSS color, default `text.secondary` |
+| `value` | `string` | The text; assemble separators in YAML: `'{{ n }} • {{ size }}'`. Empty → not rendered |
+| `href` | `string` | Renders the value as a link: `tel:{{ … }}`, `mailto:{{ … }}`, or a URL; only allowlisted URL schemes are linked |
+| `onClick` | `Action[]` | Actions on click (alternative to href) |
+| `truncate` | `boolean` | Ellipsis on overflow; tooltip defaults to the full value |
+| `tooltip` | `string\|localized` | Explicit tooltip, overrides the truncate default |
+| `variant` | `string` | `default` \| `chip` — bordered rounded container |
+
+```yaml
+- component: infoLine
+  name: driverPhone
+  props:
+    icon: tabler-phone
+    value: '{{ row.record.phoneNumber }}'
+    href: 'tel:{{ row.record.phoneNumber }}'
+- component: infoLine
+  name: containerChip
+  props:
+    icon: tabler-container
+    value: '{{ container.number }} • {{ container.size }}'
+    variant: chip
+    truncate: true
+```
+
+---
+
+## progressBar
+
+Abstract progress bar. Feed it `value`/`max` directly, or an `items` array with a declarative completed predicate — what the numbers mean (moves, stops, hours…) is the module's business. **max 0 or missing → nothing renders**, so it can be declared unconditionally.
+
+**Props (all template-parsed):**
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `number\|string` | Completed amount; overrides the derived count |
+| `max` | `number\|string` | Total; defaults to `items.length` when `items` is set |
+| `items` | `string` | Single-chunk template → array, e.g. `'{{ row.items }}'` |
+| `completedPath` | `string` | Dot path inside each item, e.g. `orderMove.orderMoveStatus.statusStage` |
+| `completedValue` | `string` | Match at the path counts as completed; omitted → any truthy value |
+| `label` | `string\|localized` | Caption on the left, e.g. `Moves` |
+| `showValue` | `boolean` | Value caption (`2/5`), default true |
+| `valueFormat` | `string` | `count` (default) \| `percent` |
+| `variant` | `string` | `linear` (default) \| `circular` \| `segmented` |
+| `height` / `size` | `number` | Linear thickness (6) / circular diameter (40) |
+| `color` | `string` | Theme name or CSS color; default primary → success at 100% |
+| `activeColor` / `trackColor` | `string` | Mobile: completed-segment color / track or incomplete-segment color for the segmented variant |
+| `tooltip` | `string\|localized` | Tooltip on hover (on mobile it is exposed to assistive technology rather than hover UI) |
+
+```yaml
+- component: progressBar
+  name: laneMovesProgress
+  props:
+    label: Moves
+    items: '{{ row.items }}'
+    completedPath: orderMove.orderMoveStatus.statusStage
+    completedValue: Completed
+```
+
+---
+
 ## icon
 
 Icon renderer. Supports FontAwesome, Tabler, and Feather icons.

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

@@ -448,6 +448,32 @@ still control the displayed label and stored value.
           fields: ["name", "address_components", "formatted_address", "geometry", "place_id"]
 ```
 
+**Attachment options (under `options`):**
+| Prop | Type | Description |
+|------|------|-------------|
+| `parentId` / `parentType` | `string` | Primary parent of the uploaded attachment (`parentType` defaults to `Order`) |
+| `links` | `{entityType, entityId}[]` or template | More entities to link the same upload to: `Order`, `Contact`, `Job`, `TrackingEvent`. Entries whose `entityType` or `entityId` resolves empty are skipped |
+| `category` | `string` | Attachment category (web) |
+| `allowMultiple` / `allowCamera` / `clearAfterUpload` | `boolean` | Upload behavior |
+| `maxSize` / `allowedExtensions` | `number` / `string[]` | File limits |
+| `onUploaded` | actions | Runs after each upload; `attachment` is in scope |
+
+```yaml
+# One upload linked to the order (parent) and a tracking event
+- component: field
+  name: eventPhoto
+  props:
+    type: attachment
+    options:
+      parentType: Order
+      parentId: "{{ orderId }}"
+      links:
+        - entityType: TrackingEvent
+          entityId: "{{ trackingEventId }}"
+```
+
+`Attachments/ListAttachments` (cx-app-core) takes the same `links` prop next to `parentId`/`parentType` and passes it to its upload field; its grid still lists by `parentId`/`parentType`.
+
 **Events:**
 | Event | Description |
 |-------|-------------|
@@ -567,7 +593,7 @@ still control the displayed label and stored value.
     type: textarea
     label: { en-US: "Notes" }
     rows: 4
-    disabled: "{{ eval !canEdit }}"
+    disabled: "{{ !canEdit }}"
 ```
 
 ---

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

@@ -83,7 +83,7 @@ MUI Button with icon, label, loading state, and action dispatch.
     icon: check-circle
     options:
       variant: success
-      disabled: "{{ eval status !== 'Pending' }}"
+      disabled: "{{ !isEqual status 'Pending' }}"
     onClick:
       - mutation:
           command: "mutation($id: Int!) { approveOrder(id: $id) { success } }"
@@ -131,7 +131,7 @@ props:
         - dialog:
             component: Module/ImportDialog
     - label: { en-US: "Archive All" }
-      disabled: "{{ eval selectedItems.length === 0 }}"
+      disabled: "{{ !any selectedItems }}"
       onClick:
         - confirm: { title: { en-US: "Archive?" }, message: { en-US: "Archive selected items?" } }
 ```
@@ -216,7 +216,7 @@ Programmatic navigation — renders nothing (or spinner with delay).
 component: redirect
 name: createRedirect
 props:
-  condition: "{{ eval !id }}"
+  condition: "{{ !id }}"
   path: "/orders/create"
 
 # External redirect with delay

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

@@ -468,7 +468,7 @@ children:
   - name: advanced
     props:
       label: { en-US: "Advanced" }
-      isHidden: "{{ eval !isAdmin }}"
+      isHidden: "{{ !isAdmin }}"
     children:
       - component: field
         name: config

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

@@ -347,6 +347,7 @@ MUI Lab Timeline for chronological events or milestone-based tracking progress.
 | `startDate` / `endDate` | `string` | current week | Initial date range for normal mode |
 | `eventSources` | `EventSource[]` | — | GraphQL/static event sources |
 | `eventTemplate` | `ComponentProps` | — | Custom event template for normal mode |
+| `itemGroups` | `{key, accent?, background?, headerTemplate?}` | — | Mobile normal-mode grouping for consecutive events with the same non-empty key |
 | `milestones` | `Milestone[]` | `[]` | Tracking milestones |
 | `options.height` | `string \| number` | `400`/`auto` | Component height |
 | `options.showTodayMarker` | `boolean` | `true` | Today marker in normal mode |
@@ -364,6 +365,8 @@ MUI Lab Timeline for chronological events or milestone-based tracking progress.
 
 **Events:** `onEventClick` (data: `event`)
 
+On mobile vertical timelines, `itemGroups` frames adjacent runs of two or more events whose templated `key` resolves equally. Runs are order-sensitive; isolated or empty keys remain ungrouped. `headerTemplate`, `accent`, and `background` resolve with `group = { key, items, size, startIndex, endIndex }` and `collection`. Grouped event templates also receive `groupPosition` and `groupOffset`. Tracking mode ignores grouping.
+
 ```yaml
 component: timeline
 name: orderTimeline