@cxtms/cx-schema 1.7.2 → 1.7.4

package/.claude/skills/cx-core/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: cx-core
 description: >
-  Shared CargoXplorer entity field reference — domain entities, field names, enums, and customValues patterns.
-  TRIGGER when: user asks about CX entity fields, enums, customValues, entity relationships, or needs domain reference for Orders, Contacts, Commodities, Jobs, etc.
+  Provides shared CargoXplorer entity field reference — domain entities, field names, enums, and customValues patterns.
+  Use when the user asks about CX entity fields, enums, customValues, entity relationships, or needs domain reference for Orders, Contacts, Commodities, Jobs, etc.
 argument-hint: <entity name or question about fields>
 ---
 
@@ -10,88 +10,7 @@ Shared domain reference for CargoXplorer entities. Used by `cx-workflow` and `cx
 
 ## CX Server Authentication & Management
 
-The CLI can authenticate against CX environments and manage server resources. Auth is required for push, delete, execute, logs, publish, and org commands.
-
-### Authentication
-
-```bash
-# Login to a CX environment (OAuth2 + PKCE — opens browser)
-npx cxtms login https://tms-v3-dev.usatrt.com
-
-# Logout from current session
-npx cxtms logout
-```
-
-The session is stored at `~/.cxtms/<project-dir>/.session.json`, scoped by project directory name. Each project gets its own server session. The CLI auto-refreshes expired tokens.
-
-### PAT Tokens (alternative to OAuth)
-
-For CI/CD or headless environments, use Personal Access Tokens instead of interactive OAuth:
-
-```bash
-# Check PAT status and setup instructions
-npx cxtms pat setup
-
-# Create a new PAT token (requires OAuth login first)
-npx cxtms pat create "my-ci-token"
-
-# List active PAT tokens
-npx cxtms pat list
-
-# Revoke a PAT token
-npx cxtms pat revoke <tokenId>
-```
-
-After creating a PAT, add to `.env` in your project root:
-```
-CXTMS_AUTH=pat_xxxxx...
-CXTMS_SERVER=https://tms-v3-dev.usatrt.com
-```
-
-When `CXTMS_AUTH` is set, the CLI skips OAuth and uses the PAT token directly. `CXTMS_SERVER` provides the server URL (or set `server` in `app.yaml`).
-
-### Organization Management
-
-```bash
-# List organizations on the server
-npx cxtms orgs list
-
-# Select an organization interactively
-npx cxtms orgs select
-
-# Set active organization by ID
-npx cxtms orgs use <orgId>
-
-# Show current context (server, org, app)
-npx cxtms orgs use
-```
-
-The active org is cached in the session file and used by all server commands. Override with `--org <id>`.
-
-### Session Resolution
-
-Server commands resolve the target session in this order:
-1. `CXTMS_AUTH` env var → PAT token auth (with `CXTMS_SERVER` or `app.yaml` server field)
-2. `~/.cxtms/<project-dir>/.session.json` → project-scoped OAuth session
-3. Not logged in → error
-
-### Publish
-
-```bash
-# Publish all modules and workflows from current project
-npx cxtms publish
-
-# Publish only a specific feature directory
-npx cxtms publish --feature billing
-npx cxtms publish billing
-
-# Publish with explicit org ID
-npx cxtms publish --org 42
-```
-
-Validates all YAML files first, then pushes modules and workflows to the server. Skips files with validation errors and reports results.
-
----
+For CLI authentication, PAT tokens, org management, and publishing: see [ref-cli-auth.md](ref-cli-auth.md)
 
 ## Feature File Layout
 
@@ -112,40 +31,17 @@ Use `--feature <feature_name>` with `cxtms create` to automatically place files
 
 ## Entity Field Reference
 
-### Primary Entities
-
-!cat .claude/skills/cx-core/ref-entity-order.md
-!cat .claude/skills/cx-core/ref-entity-contact.md
-!cat .claude/skills/cx-core/ref-entity-commodity.md
-!cat .claude/skills/cx-core/ref-entity-accounting.md
-
-### Order Sub-Entities & Related
-
-!cat .claude/skills/cx-core/ref-entity-order-sub.md
-!cat .claude/skills/cx-core/ref-entity-job.md
-
-### Pricing & Accounting Lookups
-
-!cat .claude/skills/cx-core/ref-entity-rate.md
-
-### Shared & Lookup Entities
-
-!cat .claude/skills/cx-core/ref-entity-shared.md
-!cat .claude/skills/cx-core/ref-entity-geography.md
-
-### Warehouse & Inventory
-
-!cat .claude/skills/cx-core/ref-entity-warehouse.md
+Read the relevant entity reference file when needed for the current task. Do not load all files upfront.
 
 | Category | Entities | Reference |
 |----------|----------|-----------|
-| **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 |
-| **Pricing** | Rate, Lane, Discount, AccountingItem, AccountingAccount, PaymentTerm | ref-entity-rate.md |
-| **Shared** | Tag, Attachment, Division, EquipmentType, PackageType, Note/NoteThread | ref-entity-shared.md |
-| **Geography** | Country, State, City, Port, Vessel, CustomCode, ModeOfTransportation | ref-entity-geography.md |
-| **Warehouse** | InventoryItem, WarehouseLocation, CargoMovement (Order variant) | ref-entity-warehouse.md |
+| **Primary** | Order, Contact, Commodity, AccountingTransaction | [ref-entity-order.md](ref-entity-order.md), [ref-entity-contact.md](ref-entity-contact.md), [ref-entity-commodity.md](ref-entity-commodity.md), [ref-entity-accounting.md](ref-entity-accounting.md) |
+| **Order sub** | OrderEntity, TrackingEvent, EventDefinition, LinkedOrder, OrderDocument | [ref-entity-order-sub.md](ref-entity-order-sub.md) |
+| **Job** | Job, JobOrder, JobStatus | [ref-entity-job.md](ref-entity-job.md) |
+| **Pricing** | Rate, Lane, Discount, AccountingItem, AccountingAccount, PaymentTerm | [ref-entity-rate.md](ref-entity-rate.md) |
+| **Shared** | Tag, Attachment, Division, EquipmentType, PackageType, Note/NoteThread | [ref-entity-shared.md](ref-entity-shared.md) |
+| **Geography** | Country, State, City, Port, Vessel, CustomCode, ModeOfTransportation | [ref-entity-geography.md](ref-entity-geography.md) |
+| **Warehouse** | InventoryItem, WarehouseLocation, CargoMovement (Order variant) | [ref-entity-warehouse.md](ref-entity-warehouse.md) |
 
 ## CustomValues Pattern
 

package/.claude/skills/cx-core/ref-cli-auth.md

@@ -0,0 +1,87 @@
+# CX Server Authentication & Management
+
+## Contents
+- Authentication (OAuth2 login/logout)
+- PAT Tokens (CI/CD alternative to OAuth)
+- Organization Management
+- Session Resolution
+- Publish (push modules and workflows to server)
+
+## Authentication
+
+```bash
+# Login to a CX environment (OAuth2 + PKCE — opens browser)
+npx cxtms login https://tms-v3-dev.usatrt.com
+
+# Logout from current session
+npx cxtms logout
+```
+
+The session is stored at `~/.cxtms/<project-dir>/.session.json`, scoped by project directory name. Each project gets its own server session. The CLI auto-refreshes expired tokens.
+
+## PAT Tokens (alternative to OAuth)
+
+For CI/CD or headless environments, use Personal Access Tokens instead of interactive OAuth:
+
+```bash
+# Check PAT status and setup instructions
+npx cxtms pat setup
+
+# Create a new PAT token (requires OAuth login first)
+npx cxtms pat create "my-ci-token"
+
+# List active PAT tokens
+npx cxtms pat list
+
+# Revoke a PAT token
+npx cxtms pat revoke <tokenId>
+```
+
+After creating a PAT, add to `.env` in your project root:
+```
+CXTMS_AUTH=pat_xxxxx...
+CXTMS_SERVER=https://tms-v3-dev.usatrt.com
+```
+
+When `CXTMS_AUTH` is set, the CLI skips OAuth and uses the PAT token directly. `CXTMS_SERVER` provides the server URL (or set `server` in `app.yaml`).
+
+## Organization Management
+
+```bash
+# List organizations on the server
+npx cxtms orgs list
+
+# Select an organization interactively
+npx cxtms orgs select
+
+# Set active organization by ID
+npx cxtms orgs use <orgId>
+
+# Show current context (server, org, app)
+npx cxtms orgs use
+```
+
+The active org is cached in the session file and used by all server commands. Override with `--org <id>`.
+
+## Session Resolution
+
+Server commands resolve the target session in this order:
+1. `CXTMS_AUTH` env var → PAT token auth (with `CXTMS_SERVER` or `app.yaml` server field)
+2. `~/.cxtms/<project-dir>/.session.json` → project-scoped OAuth session
+3. Not logged in → error
+
+## Publish
+
+```bash
+# Publish all modules and workflows from current project
+npx cxtms publish
+
+# Publish only a specific feature directory
+npx cxtms publish --feature billing
+npx cxtms publish billing
+
+# Publish with explicit org ID
+npx cxtms publish --org 42
+```
+
+Validates all YAML files first, then pushes modules and workflows to the server. Skips files with validation errors and reports results.

package/.claude/skills/cx-core/ref-entity-accounting.md

@@ -1,5 +1,12 @@
 # Accounting Transaction Entity Field Reference
 
+## Contents
+- AccountingTransaction Fields
+- Charge Entity
+- Payment Entity
+- Accounting Enums
+- Accounting CustomValues
+
 Field names as used in workflow expressions: `{{ entity.transactionNumber }}`, `{{ entity.customValues.myField }}`.
 
 ## AccountingTransaction Fields

package/.claude/skills/cx-core/ref-entity-commodity.md

@@ -1,5 +1,17 @@
 # Commodity Entity Field Reference
 
+## Contents
+- Commodity Scalar Fields
+- Commodity Navigation Properties
+- Commodity Collection Properties
+- Commodity Computed/Resolved GraphQL Fields
+- Commodity Container/Child Pattern (Self-Referencing)
+- CommodityTrackingNumber Sub-Entity
+- OrderCommodity Join Entity
+- Commodity Enums
+- Commodity CustomValues
+- CommodityEvent (Bridge Entity)
+
 Field names as used in workflow expressions: `{{ entity.description }}`, `{{ entity.customValues.myField }}`.
 
 ## Scalar Fields

package/.claude/skills/cx-core/ref-entity-contact.md

@@ -1,5 +1,15 @@
 # Contact Entity Field Reference
 
+## Contents
+- Contact Scalar Fields
+- Contact Navigation Properties
+- Contact Collection Properties
+- Contact Computed/Resolved GraphQL Fields
+- ContactType Enum
+- ContactAddress Sub-Entity
+- Contact Other Related Enums
+- Contact CustomValues
+
 Field names as used in workflow expressions: `{{ entity.name }}`, `{{ entity.customValues.myField }}`.
 
 ## Scalar Fields

package/.claude/skills/cx-core/ref-entity-geography.md

@@ -1,5 +1,14 @@
 # Geography & Lookup Entity Reference
 
+## Contents
+- Country
+- State
+- City
+- Port
+- Vessel
+- CustomCode
+- ModeOfTransportation
+
 Country, State, City, Port, Vessel, CustomCode, ModeOfTransportation.
 
 ## Country

package/.claude/skills/cx-core/ref-entity-order-sub.md

@@ -1,5 +1,12 @@
 # Order Sub-Entity Field Reference
 
+## Contents
+- OrderEntity
+- TrackingEvent
+- EventDefinition
+- LinkedOrder
+- OrderDocument
+
 Entities associated with orders: OrderEntity (parties), TrackingEvent, LinkedOrder, OrderDocument.
 
 ## OrderEntity

package/.claude/skills/cx-core/ref-entity-order.md

@@ -1,5 +1,15 @@
 # Order Entity Field Reference
 
+## Contents
+- Order Scalar Fields
+- Order Navigation Properties
+- Order Collection Properties
+- Pre-filtered OrderEntity Collections (GraphQL)
+- Order Computed/Resolved GraphQL Fields
+- OrderTypes Enum
+- EntityTypes Enum (for OrderEntity)
+- Order CustomValues
+
 Field names as used in workflow expressions: `{{ entity.orderId }}`, `{{ entity.customValues.myField }}`.
 
 ## Scalar Fields

package/.claude/skills/cx-core/ref-entity-rate.md

@@ -1,5 +1,13 @@
 # Rate, Pricing & Accounting Lookup Reference
 
+## Contents
+- Rate
+- Lane
+- Discount
+- AccountingItem
+- AccountingAccount
+- PaymentTerm
+
 ## Rate
 
 Carrier/vendor rates with tariff rules.

package/.claude/skills/cx-core/ref-entity-shared.md

@@ -1,5 +1,14 @@
 # Shared Entity Reference
 
+## Contents
+- Tag
+- Attachment
+- Division
+- EquipmentType
+- PackageType
+- NoteThread
+- Note
+
 Tag, Attachment, Division, EquipmentType, PackageType, Note/NoteThread.
 
 ## Tag

package/.claude/skills/cx-core/ref-entity-warehouse.md

@@ -1,5 +1,10 @@
 # Warehouse & Inventory Entity Reference
 
+## Contents
+- InventoryItem
+- WarehouseLocation
+- CargoMovement
+
 ## InventoryItem
 
 SKU-level inventory tracking.

package/.claude/skills/cx-module/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: cx-module
 description: >
-  Generate schema-valid CargoXplorer app module YAML files (UI screens, forms, grids, routes).
-  TRIGGER when: user asks to create, modify, or fix a module YAML file, or references *-module.yaml files, or asks about UI components/forms/grids/routes in a CX project.
-  DO NOT TRIGGER when: working with workflow YAML files, general TypeScript/code changes, or non-YAML tasks.
+  Generates schema-valid CargoXplorer app module YAML files (UI screens, forms, grids, routes).
+  Use when the user asks to create, modify, or fix a module YAML file, references *-module.yaml files, or asks about UI components/forms/grids/routes in a CX project.
+  Not for workflow YAML files, TypeScript code, or non-YAML tasks.
 argument-hint: <description of what to build>
 ---
 
@@ -400,24 +400,7 @@ Reusable select components (e.g., `Countries/Select`, `Ports/Select`) follow thi
 
 ## Server Module Commands
 
-### Deploy / Undeploy
-
-```bash
-# Deploy a module YAML to the server (creates or updates)
-npx cxtms appmodule deploy modules/my-module.yaml
-
-# Deploy with explicit org ID
-npx cxtms appmodule deploy modules/my-module.yaml --org 42
-
-# Undeploy an app module by UUID
-npx cxtms appmodule undeploy <appModuleId>
-
-# Publish all modules and workflows (validates first)
-npx cxtms publish
-npx cxtms publish --feature billing
-```
-
-Deploy reads `module.appModuleId` from the YAML, queries the server, and creates or updates accordingly. Requires an active session (`cxtms login` or PAT token — see cx-core skill).
+Deploy, undeploy, and publish commands are listed in the CLI section at the top of this file. For authentication setup (login, PAT tokens, org management): see [cx-core/ref-cli-auth.md](.claude/skills/cx-core/ref-cli-auth.md)
 
 ---
 

package/.claude/skills/cx-module/ref-components-data.md

@@ -1,5 +1,12 @@
 # Data & Collection Components
 
+## Contents
+- Collection component
+- List component
+- ListItem component
+- Datasource component
+- Script component
+
 ## collection
 
 Iterates over data items and renders children as templates. Supports drag-and-drop reordering.

package/.claude/skills/cx-module/ref-components-display.md

@@ -1,5 +1,18 @@
 # Data Display Components
 
+## Contents
+- DataGrid component
+- Text component
+- Markup component
+- Badge component
+- Icon component
+- Image component
+- Photo component
+- Summary component
+- Diff component
+- Viewer component
+- Embed component
+
 ## dataGrid
 
 Full-featured data table with views, filtering, sorting, pagination, and row actions.

package/.claude/skills/cx-module/ref-components-forms.md

@@ -1,5 +1,11 @@
 # Form & Input Components
 
+## Contents
+- Form component
+- Field component
+- FieldCollection component
+- BarcodeScanner component
+
 ## form
 
 Data entry form with validation, queries, and submission. Wraps React Hook Form's FormProvider.

package/.claude/skills/cx-module/ref-components-interactive.md

@@ -1,5 +1,16 @@
 # Interactive & Navigation Components
 
+## Contents
+- Button component
+- Dropdown component
+- MenuButton component
+- Link component
+- Redirect component
+- Navbar component
+- NavbarItem component
+- NavbarLink component
+- NavDropdown component
+
 ## button
 
 MUI Button with icon, label, loading state, and action dispatch.

package/.claude/skills/cx-module/ref-components-layout.md

@@ -1,5 +1,16 @@
 # Layout & Structure Components
 
+## Contents
+- Layout component
+- Row component
+- Col component
+- Header component
+- Tabs component
+- Toolbar component
+- Card component
+- Line component
+- Slot component
+
 ## layout
 
 General-purpose container. Renders MUI Grid or Box with flexbox.

package/.claude/skills/cx-module/ref-components-specialized.md

@@ -1,5 +1,15 @@
 # Specialized Components
 
+## Contents
+- Calendar component
+- Notes component
+- Dashboard component
+- DashboardWidget component
+- Widget component
+- Timeline component
+- TimelineGrid component
+- OAuth2 component
+
 ## calendar
 
 FullCalendar integration with GraphQL event sources, timezone support, and programmatic control.

package/.claude/skills/cx-workflow/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: cx-workflow
 description: >
-  Generate schema-valid CargoXplorer workflow YAML files (standard process and Flow state machine workflows).
-  TRIGGER when: user asks to create, modify, or fix a workflow YAML file, or references workflow/*.yaml files, or asks about workflow tasks/triggers/activities in a CX project.
-  DO NOT TRIGGER when: working with module YAML files, general TypeScript/code changes, or non-YAML tasks.
+  Generates schema-valid CargoXplorer workflow YAML files (standard process and Flow state machine workflows).
+  Use when the user asks to create, modify, or fix a workflow YAML file, references workflow/*.yaml files, or asks about workflow tasks/triggers/activities in a CX project.
+  Not for module YAML files, TypeScript code, or non-YAML tasks.
 argument-hint: <description of what to build>
 ---
 
@@ -318,21 +318,7 @@ Implicit variable: `iteration` (zero-based).
 
 ## Server Workflow Commands
 
-### Deploy / Undeploy
-
-```bash
-# Push a workflow YAML to the server (creates or updates)
-npx cxtms workflow deploy workflows/my-workflow.yaml
-
-# Delete a workflow by UUID
-npx cxtms workflow undeploy <workflowId>
-
-# Publish all modules and workflows (validates first)
-npx cxtms publish
-npx cxtms publish --feature billing
-```
-
-Deploy reads `workflow.workflowId` from the YAML, queries the server, and creates or updates accordingly. Requires an active session (`cxtms login` or PAT token — see cx-core skill).
+Deploy, undeploy, and publish commands are listed in the CLI section at the top of this file. For authentication setup (login, PAT tokens, org management): see [cx-core/ref-cli-auth.md](.claude/skills/cx-core/ref-cli-auth.md)
 
 ### Execute
 

package/.claude/skills/cx-workflow/ref-communication.md

@@ -1,5 +1,13 @@
 # Communication & Document Tasks Reference
 
+## Contents
+- Email/Send task (send emails with templates and attachments)
+- Email/VerifyCode task (send and verify email verification codes)
+- Document/Render task (render PDF or Excel from HTML templates)
+- Document/Send task (send a previously rendered document)
+- Attachment tasks (Create, Update, Thumbnail, PdfThumbnail, RegenerateThumbnails)
+- PdfDocument/Merge task (merge multiple PDFs into one)
+
 ## Email/Send
 
 Sends emails with optional templates and attachments.

package/.claude/skills/cx-workflow/ref-entity.md

@@ -1,5 +1,22 @@
 # Entity CRUD Tasks Reference
 
+## Contents
+- Entity/Change task (generic entity modification in Before triggers)
+- Order tasks (Create, Update, Delete, Get, Copy, Split, Import, etc.)
+- Contact tasks (Create, Update, Delete)
+- ContactAddress tasks (Create, Update, Delete, Import)
+- ContactPaymentMethod tasks (Create, Update, SendChargedAmount, VerifyChargedAmount)
+- Commodity tasks (Create, Update, Split, Repack, Unpack)
+- CommodityTrackingNumber tasks (Create, Update, Delete)
+- Job tasks (Create, Update, Delete, Assign, Unassign)
+- Charge tasks (Create, Update, Delete, DynamicUpdate, Calculate)
+- Discount task (Update)
+- Order sub-entity tasks (OrderCommodity, OrderCharge, OrderDocument, OrderTrackingEvent, OrderEntity)
+- Inventory tasks (InventoryItem Create, Update, Delete)
+- Other entity tasks (Movement, Country, Cities, Rate, TrackingEvent/Import)
+- Note tasks (Create, Update, Delete, Import, Export, RenameThread)
+- AccountingTransaction/ApplyCredit task
+
 All entity tasks follow the `Namespace/Operation@Version` pattern. Outputs are stored as `ActivityName.StepName.outputKey`.
 
 ## Generic Entity Change

package/.claude/skills/cx-workflow/ref-expressions.md

@@ -1,5 +1,10 @@
 # Variable References & Expressions
 
+## Contents
+- Template Expressions: `{{ path }}` (in step inputs)
+- NCalc Expressions: `[variable]` (in conditions and expression directives)
+- Property Path Syntax (in collection, mapping, variable paths)
+
 There are **two distinct syntaxes** for referencing variables, used in different contexts.
 
 ## Template Expressions: `{{ path }}` (in step inputs)

package/.claude/skills/cx-workflow/ref-flow.md

@@ -1,5 +1,12 @@
 # Flow Workflow YAML Reference
 
+## Contents
+- Flow top-level structure (workflowType, entity, states, transitions, aggregations)
+- Flow entity section (entity name, type, includes, query)
+- Flow states section (initial, final, parent hierarchy, onEnter/onExit steps)
+- Flow transitions section (manual, auto, event triggers; from/to states; conditions)
+- Flow aggregations section (reusable collection expressions: all, any, sum, count)
+
 Flow workflows are declarative state machines for entity lifecycle management. Use `workflowType: Flow` in the workflow section.
 
 ## Top-Level Structure

package/.claude/skills/cx-workflow/ref-other.md

@@ -1,5 +1,14 @@
 # Other Tasks Reference
 
+## Contents
+- User & Auth tasks (User CRUD, verification codes, OAuth2 authentication)
+- Caching tasks (SetCache and GetCache for in-memory key-value storage)
+- EDI & Structured File Parsing tasks (EDI/Parse for X12/EDIFACT, StructuredFile/Parse)
+- Flow/Transition task (trigger state machine transitions programmatically)
+- Note tasks (Create, Update, Delete, NoteThread/Rename, bulk Import/Export)
+- AppModule tasks (Create, Update, Delete app modules)
+- ActionEvent/Create task (trigger UI notifications or webhooks)
+
 ## User & Auth
 
 | Task | Description |

package/.claude/skills/cx-workflow/ref-utilities.md

@@ -1,5 +1,17 @@
 # Utilities Tasks Reference
 
+## Contents
+- Available utility tasks (summary table of all Utilities/* tasks)
+- SetVariable task (set variables in activity and global scope)
+- Log task (log variables and messages to workflow logger)
+- Error task (throw workflow error to halt execution)
+- HttpRequest task (HTTP calls to external APIs with action events)
+- Map task (extract and reshape data into new variables)
+- Template task (Handlebars template rendering)
+- CsvParse task (parse CSV content into structured data)
+- Export task (export data to file format)
+- Import task (import data from file content)
+
 ## Available Tasks
 
 | Task | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxtms/cx-schema",
-  "version": "1.7.2",
+  "version": "1.7.4",
   "description": "Schema validation package for CargoXplorer YAML modules",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",