@cxtms/cx-schema 1.8.1 → 1.9.0

package/{.claude/skills/cx-core → skills/cxtms-developer}/SKILL.md

@@ -1,10 +1,12 @@
 ---
-name: cx-core
-description: Shared CargoXplorer entity field reference — domain entities, field names, enums, and customValues patterns
+name: cxtms-developer
+description: >
+  Shared CargoXplorer domain reference — entity fields, enums, customValues, GraphQL queries, and CLI auth.
+  Use when the user asks about CX entity fields, enums, customValues, entity relationships, or needs domain reference for Orders, Contacts, Commodities, Jobs, Charges, or other CX entities.
 argument-hint: <entity name or question about fields>
 ---
 
-Shared domain reference for CargoXplorer entities. Used by `cx-workflow` and `cx-module` skills for entity field names, types, navigation properties, enums, and customValues extension patterns.
+Shared domain reference for CargoXplorer entities. Used by `cxtms-workflow-builder` and `cxtms-module-builder` skills for entity field names, types, navigation properties, enums, and customValues extension patterns.
 
 ## Feature File Layout
 
@@ -27,32 +29,32 @@ Use `--feature <feature_name>` with `cx-cli create` to automatically place files
 
 ### 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
+!cat skills/cxtms-developer/ref-entity-order.md
+!cat skills/cxtms-developer/ref-entity-contact.md
+!cat skills/cxtms-developer/ref-entity-commodity.md
+!cat skills/cxtms-developer/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
+!cat skills/cxtms-developer/ref-entity-order-sub.md
+!cat skills/cxtms-developer/ref-entity-job.md
 
 ### Pricing & Accounting Lookups
 
-!cat .claude/skills/cx-core/ref-entity-rate.md
+!cat skills/cxtms-developer/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
+!cat skills/cxtms-developer/ref-entity-shared.md
+!cat skills/cxtms-developer/ref-entity-geography.md
 
 ### Warehouse & Inventory
 
-!cat .claude/skills/cx-core/ref-entity-warehouse.md
+!cat skills/cxtms-developer/ref-entity-warehouse.md
 
 ### Notifications
 
-!cat .claude/skills/cx-core/ref-entity-notification.md
+!cat skills/cxtms-developer/ref-entity-notification.md
 
 | Category | Entities | Reference |
 |----------|----------|-----------|

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

@@ -0,0 +1,120 @@
+# 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. **Always pass `--org <id>` on deploy/undeploy/release/execute/logs commands** to avoid the interactive org picker blocking automation.
+
+## 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.
+
+## App Manifest Management
+
+Server-side app manifest operations — install from git, release changes to git, and list installed apps.
+
+```bash
+# Install/refresh app from its git repository into the CX server
+npx cxtms app install
+
+# Force reinstall even if same version is already installed
+npx cxtms app install --force
+
+# Install from a specific branch
+npx cxtms app install --branch develop
+
+# Install but skip modules that have unpublished local changes
+npx cxtms app install --skip-changed
+
+# Release server changes to git (creates a PR) — message is required
+npx cxtms app release -m "Add new shipping module"
+
+# Force release all modules and workflows (not just changed ones)
+npx cxtms app release -m "Full republish" --force
+
+# List installed app manifests on the server
+npx cxtms app list
+```
+
+**`app install`** reads `repository` and `branch` from `app.yaml`, downloads the repo on the server side, and installs/updates all modules and workflows. Use `--force` to reinstall even if the version hasn't changed. Use `--skip-changed` to preserve modules with unpublished changes.
+
+**`app release`** takes the current server state and releases it to git by creating a PR. Requires a `-m` message describing the changes (like a git commit message). The server increments the version, creates a release branch, commits all module/workflow YAML files, and opens a pull request to the target branch.
+
+**`app list`** shows all installed app manifests with their version, status flags (disabled, unpublished changes, update available), and repository info.

package/{.claude/skills/cx-core → skills/cxtms-developer}/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 → skills/cxtms-developer}/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 → skills/cxtms-developer}/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 → skills/cxtms-developer}/ref-entity-geography.md

@@ -1,6 +1,16 @@
 # Geography & Lookup Entity Reference
 
-Country, State, City, Port, Vessel, CustomCode, ModeOfTransportation.
+## Contents
+- Country
+- State
+- City
+- PostalCode
+- Port
+- Vessel
+- CustomCode
+- ModeOfTransportation
+
+Country, State, City, PostalCode, Port, Vessel, CustomCode, ModeOfTransportation.
 
 ## Country
 
@@ -50,6 +60,29 @@ Composite key: `organizationId` + `countryCode` + `stateCode`.
 
 ---
 
+## PostalCode
+
+PK: `id` (int, auto). Scoped per organization.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `int` | PK |
+| `organizationId` | `int` | |
+| `code` | `string` | Postal/zip code value |
+| `countryCode` | `string` | FK to Country |
+| `placeName` | `string` | Place/city name |
+| `stateCode` | `string?` | FK to State |
+| `accuracy` | `AccuracyTypes?` | 1=Region, 2=Municipality, 3=Neighborhood, 4=Place, 5=Street, 6=Centroid |
+| `timeZone` | `string?` | IANA timezone ID (e.g., `America/Chicago`) |
+| `customValues` | `Dictionary` | jsonb |
+| `location` | `Point?` | WGS 84 (SRID 4326). X=longitude, Y=latitude |
+
+**Navigation:** `country`, `state`
+
+**Mutations:** `ChangeCode`, `ChangePlaceName`, `ChangeCoordinates(lat, lng, accuracy)`, `ChangeCountry`/`ChangeCountryCode`, `ChangeState`/`ChangeStateCode`, `ChangeTimeZone`, `ChangeCustomValues`, `ChangeLatitude`, `ChangeLongitude`
+
+---
+
 ## Port
 
 String-based PK (e.g., UN/LOCODE).

package/{.claude/skills/cx-core → skills/cxtms-developer}/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
@@ -94,6 +101,12 @@ Template/type definition for tracking events.
 | `triggerConditionFields` | `string?` | |
 | `customValues` | `Dictionary` | jsonb |
 
+### GraphQL Resolvers
+
+| Resolver | Arguments | Returns | Description |
+|----------|-----------|---------|-------------|
+| `getContact` | `customValuesKey: String!` | `Contact` | Looks up a Contact by ID stored in `customValues[key]` |
+
 ---
 
 ## LinkedOrder

package/{.claude/skills/cx-core → skills/cxtms-developer}/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
@@ -55,6 +65,8 @@ Field names as used in workflow expressions: `{{ entity.orderId }}`, `{{ entity.
 | `orderCarriers` | `[OrderCarrier]` | |
 | `allTags` | `[OrderAllTagsView]` | View: all tags including from commodities |
 | `allRelatedOrders` | `[OrderRelatedOrdersView]` | Orders sharing commodities |
+| `attachmentsSummary` | `OrderAttachmentSummaryView?` | DB view: `.totalCount`, `.hasAny` (active attachments) |
+| `notesSummary` | `OrderNoteSummaryView?` | DB view: `.totalCount`, `.hasAny` (non-deleted notes) |
 | `outgoingLinks` | `[LinkedOrder]` | |
 | `incomingLinks` | `[LinkedOrder]` | |
 
@@ -97,6 +109,8 @@ These are virtual fields that filter `orderEntities` by type:
 | `getChargesByChargeType(chargeType)` | `[Charge]` | Charges filtered by type |
 | `getOrderSummary(weightUnit, volumeUnit, dimensionsUnit)` | `OrderSummary` | |
 | `lastTrackingEvent(eventDefinitionName)` | `TrackingEvent` | Most recent |
+| `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` | |
 | `changeHistory(startDate, endDate, maxResults)` | `[ChangeHistory]` | Audit trail |
 | `getCommoditiesWithRelatedOrder(orderType!, filter?)` | `[Commodity]` | Leaf commodities linked to related orders of specified type. Traverses commodity hierarchy, excludes wrappers. |

package/{.claude/skills/cx-core → skills/cxtms-developer}/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 → skills/cxtms-developer}/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 → skills/cxtms-developer}/ref-entity-warehouse.md

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

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

@@ -0,0 +1,320 @@
+# GraphQL Query Reference
+
+## CLI Query Command
+
+```bash
+npx cxtms query '<graphql-query>'              # Inline query
+npx cxtms query my-query.graphql               # From file
+npx cxtms query '<query>' --vars '{"key":"v"}' # With variables
+```
+
+Requires active login (`npx cxtms login`). Uses the active organization.
+
+## Query Arguments
+
+All root entity queries follow this pattern:
+
+```graphql
+orders(
+  organizationId: Int!    # Required — active org ID
+  filter: String          # Lucene query syntax (see below)
+  search: String          # Full-text search across key fields
+  orderBy: String         # Comma-separated sort fields
+  take: Int               # Page size (alias: limit)
+  skip: Int               # Offset (alias: offset)
+)
+```
+
+Entity-specific extras:
+- `orders` — `includeDraft: Boolean` (default false)
+
+Available root queries: `orders`, `contacts`, `commodities`, `accountingTransactions`, `jobs`, and others.
+
+## Filter Syntax (Lucene Query)
+
+Filters use **Lucene Query syntax** (not OData, not NCalc).
+
+### Basic field matching
+```
+filter: "orderId:196596"
+filter: "orderType:ParcelShipment"
+filter: "status:Active"
+```
+
+### Wildcards
+```
+filter: "name:*pending*"        # Contains
+filter: "code:ABC*"             # Starts with
+filter: "status:*Active"        # Ends with
+```
+
+### Logical operators
+```
+filter: "countryCode:US AND name:Test"
+filter: "status:Active OR status:Pending"
+filter: "NOT customValues.po:123"
+filter: "orderType:ParcelShipment AND (status:Active OR status:Pending)"
+```
+
+### Nested paths (dot notation)
+```
+filter: "orderEntities.entityType:Consignee"
+filter: "orderEntities.contactId:7128"
+filter: "jobs.orders.orderNumber:16*"
+```
+
+### Range queries
+```
+filter: "lastModified:[\"2026-01-01\" TO \"2026-03-15\"]"
+filter: "lastModified:[\"2026-01-01\" TO *]"    # >= date
+filter: "amount:[100 TO 500]"
+```
+
+### NULL checks
+```
+filter: "customValues.po:NULL"
+```
+
+### CustomValues (JSONB fields)
+```
+filter: "customValues.fieldName:value"
+filter: "customValues.fieldName:\"exact match\""
+filter: "customValues.fieldName:NULL"
+```
+
+### Filtered collections (bracket notation)
+```
+filter: "children[category:CatA].name:test"
+```
+
+## OrderBy Syntax
+
+```
+orderBy: "orderNumber"                # Ascending
+orderBy: "-orderNumber"               # Descending
+orderBy: "-created,orderNumber"       # Multi-field
+orderBy: "customValues.fieldName"     # Custom field sort
+orderBy: "orderNumber~ToInt32"        # Type conversion during sort
+```
+
+## Pagination
+
+```graphql
+{
+  orders(organizationId: 1, take: 50, skip: 0) {
+    items { orderId orderNumber }
+    totalCount
+    pageInfo { hasNextPage hasPreviousPage }
+  }
+}
+```
+
+## Audit Change History
+
+### Entity-level: `changeHistory` computed field
+
+Available on: **Order**, **Contact**, **Commodity**, **AccountingTransaction**
+
+```graphql
+{
+  orders(organizationId: 1, filter: "orderId:196596", take: 1) {
+    items {
+      orderId
+      changeHistory(maxResults: 20) {
+        entityName
+        hasMoreRecords
+        continuationToken
+        changes {
+          state         # "Added" | "Modified" | "Deleted"
+          userId
+          timestamp
+          user {
+            fullName
+            email
+          }
+          changedFields {
+            fieldName
+            originalValue
+            currentValue
+            fieldType
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Arguments: `startDate: DateTime`, `endDate: DateTime`, `maxResults: Int` (default 10)
+
+### Root-level: `auditChanges` query
+
+Query audit changes directly without fetching the entity first:
+
+```graphql
+{
+  auditChanges(
+    organizationId: 1
+    filter: "entityName:Order AND primaryKey:196596"
+    take: 20
+  ) {
+    items {
+      state
+      userId
+      timestamp
+      user { fullName email }
+      changedFields {
+        fieldName
+        originalValue
+        currentValue
+        fieldType
+      }
+    }
+  }
+}
+```
+
+Arguments: `organizationId: Int!`, `filter: String`, `search: String`, `take: Int`, `skip: Int`, `orderBy: String`
+
+Filter fields: `entityName`, `primaryKey`, `userId`, `state`
+
+### Root-level: `auditChangeSummaries` query
+
+High-level summary of changes (grouped by change event):
+
+```graphql
+{
+  auditChangeSummaries(
+    organizationId: 1
+    startDate: "2026-03-01T00:00:00Z"
+    endDate: "2026-03-15T23:59:59Z"
+    maxResults: 50
+  ) {
+    items {
+      changeId
+      userId
+      timestamp
+      changePaths
+      organizationId
+    }
+    continuationToken
+    hasMoreRecords
+  }
+}
+```
+
+### Root-level: `auditChange` — single change detail
+
+```graphql
+{
+  auditChange(filePath: "<s3-file-path>") {
+    entityName
+    state
+    primaryKey
+    userId
+    timestamp
+    originalValues
+    currentValues
+    fields {
+      fieldName
+      originalValue
+      currentValue
+      fieldType
+    }
+  }
+}
+```
+
+## GraphQL Type Reference
+
+### EntityAuditHistoryLightResult
+| Field | Type |
+|-------|------|
+| `entityName` | `String` |
+| `primaryKey` | `String` |
+| `organizationId` | `Int` |
+| `changes` | `[AuditChangeEntry!]!` |
+| `continuationToken` | `String` |
+| `hasMoreRecords` | `Boolean!` |
+
+### AuditChangeEntry
+| Field | Type | Notes |
+|-------|------|-------|
+| `state` | `String` | "Added", "Modified", "Deleted" |
+| `userId` | `String` | |
+| `timestamp` | `DateTime!` | |
+| `user` | `AuditUser` | Lazy-loaded resolver |
+| `changedFields` | `[AuditChangeField!]!` | Lazy-loaded resolver |
+
+### AuditChangeField
+| Field | Type |
+|-------|------|
+| `fieldName` | `String!` |
+| `originalValue` | `Any` |
+| `currentValue` | `Any` |
+| `fieldType` | `String!` |
+
+### AuditUser
+| Field | Type |
+|-------|------|
+| `id` | `String` |
+| `firstName` | `String` |
+| `lastName` | `String` |
+| `fullName` | `String` |
+| `userName` | `String` |
+| `email` | `String` |
+
+## Discovering Fields
+
+**Always discover field names before building a query.** Do not guess field names — use the tools below.
+
+### CLI: `cxtms gql` — schema exploration commands
+
+```bash
+# List all query root fields (what you can query)
+npx cxtms gql queries
+npx cxtms gql queries --filter order
+
+# List all mutation root fields
+npx cxtms gql mutations
+npx cxtms gql mutations --filter order
+
+# List all types (filter by name)
+npx cxtms gql types --filter audit
+npx cxtms gql types --filter order
+
+# Inspect a specific type — shows fields, arguments, input fields, enum values
+npx cxtms gql type OrderGqlDto
+npx cxtms gql type AuditChangeEntry
+npx cxtms gql type EntityAuditHistoryLightResult
+npx cxtms gql type CreateOrderInput
+```
+
+### TMS MCP: `graphql_schema` / `graphql_type` — equivalent MCP tools
+
+When TMS MCP is available, the same discovery is available via MCP tools:
+
+```
+graphql_schema(section: "queries", filter: "order")
+graphql_schema(section: "types", filter: "audit")
+graphql_type(typeName: "OrderGqlDto")
+graphql_execute(query: "{ orders(organizationId: 1, take: 1) { items { orderId } } }")
+```
+
+### Workflow: discover → query
+
+1. **Find the type** — `cxtms gql types --filter order` to find type names
+2. **Inspect the type** — `cxtms gql type OrderGqlDto` to see all fields and their types
+3. **Check query args** — `cxtms gql queries --filter order` to see arguments
+4. **Build and run** — `cxtms query '<graphql-query>'`
+
+### Fallback: error-driven discovery
+
+GraphQL error messages reveal valid field/type names:
+- "The field `foo` does not exist on the type `BarType`" — tells you the type name
+- "The argument `bar` does not exist" — tells you valid argument patterns
+
+### Other sources
+
+- `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