@cxtms/cx-schema 1.7.3 → 1.7.5

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-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-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>
 ---
 
@@ -191,7 +191,8 @@ events:                                     # Workflow-level event handlers
 
 ## Variable References (quick summary)
 
-For full reference: `!cat .claude/skills/cx-workflow/ref-expressions.md`
+For template expressions and value directives: see [ref-expressions-template.md](.claude/skills/cx-workflow/ref-expressions-template.md)
+For NCalc conditions and functions: see [ref-expressions-ncalc.md](.claude/skills/cx-workflow/ref-expressions-ncalc.md)
 
 **`{{ path }}`** — in step inputs. Single `{{ }}` returns raw object. Multiple returns string interpolation.
 **`[variable]`** — in conditions and `expression:` directives. NCalc syntax.
@@ -294,7 +295,8 @@ Implicit variable: `iteration` (zero-based).
 
 | Reference | Load |
 |-----------|------|
-| Expressions & Functions | `!cat .claude/skills/cx-workflow/ref-expressions.md` |
+| Template Expressions & Value Directives | `!cat .claude/skills/cx-workflow/ref-expressions-template.md` |
+| NCalc Expressions & Functions | `!cat .claude/skills/cx-workflow/ref-expressions-ncalc.md` |
 | Flow Workflows (state machines) | `!cat .claude/skills/cx-workflow/ref-flow.md` |
 
 ## Dynamic Schema Access (load on demand)
@@ -318,21 +320,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-expressions.md → ref-expressions-ncalc.md}

@@ -1,131 +1,16 @@
-# Variable References & Expressions
+# NCalc Expressions & Functions
 
 ## Contents
-- Template Expressions: `{{ path }}` (in step inputs)
-- NCalc Expressions: `[variable]` (in conditions and expression directives)
-- Property Path Syntax (in collection, mapping, variable paths)
+- NCalc expression syntax `[variable]` (in conditions and expression directives)
+- Operators (comparison, logical, arithmetic, ternary, membership)
+- Iterator variables (`[each.*]` and `[item.*]`)
+- Collection functions (any, all, count, sum, first, last, distinct, groupBy, join, etc.)
+- String functions (isNullOrEmpty, length, lower, upper, replace, format, base64, etc.)
+- Date functions (now, parseDate, addDays, formatDate, dateFromUnix, etc.)
+- Math functions (Abs, Ceiling, Floor, Round, Min, Max, etc.)
+- Domain functions (convertWeight, convertDimension)
 
-There are **two distinct syntaxes** for referencing variables, used in different contexts.
-
-## Template Expressions: `{{ path }}` (in step inputs)
-
-Used in step `inputs` values. Resolves variable paths from scoped variables.
-
-```yaml
-inputs:
-  orderId: "{{ inputs.orderId }}"                    # Simple reference
-  url: "{{ chopinConfig.baseUrl }}/api/v1"           # String interpolation
-  order: "{{ Data.GetOrder.order }}"                 # Raw object (single {{ }})
-  name: "Order {{ Data.GetOrder.order.orderNumber }}" # String interpolation (multiple)
-```
-
-**Key behavior**: A single `{{ path }}` returns the **raw object** (preserving type). Multiple `{{ }}` in a string returns string interpolation (each resolved value is `.ToString()`).
-
-### Type Converters (prefix in {{ }})
-
-```yaml
-organizationId: "{{ int organizationId }}"
-amount: "{{ decimal totalAmount }}"
-isActive: "{{ bool isActive }}"
-flag: "{{ boolOrFalse someFlag }}"        # null -> false
-flagOn: "{{ boolOrTrue someFlag }}"       # null -> true
-notes: "{{ emptyIfNull notes }}"          # null -> ""
-notes: "{{ nullIfEmpty notes }}"          # "" or whitespace -> null
-config: "{{ fromJson configJsonString }}" # JSON string -> dict/array
-payload: "{{ toJson someObject }}"        # object -> JSON string
-name: "{{ trim value }}"
-search: "{{ luceneString query }}"        # escape & quote for Lucene
-```
-
-| Converter | Returns | Null handling |
-|-----------|---------|---------------|
-| `string` | `string` | null. Reads `Stream` to string if value is Stream |
-| `int` | `int` | Throws on null |
-| `decimal` | `decimal` | Throws on null |
-| `bool` | `bool` | Throws on null |
-| `boolOrFalse` | `bool` | `false` if null |
-| `boolOrTrue` | `bool` | `true` if null |
-| `datetime` | `DateTime` | Throws on null |
-| `emptyIfNull` | same type | `""` if null, `0` for int?, `0m` for decimal? |
-| `nullIfEmpty` | same type | `null` if empty/whitespace string or empty collection |
-| `luceneString` | `string` | null |
-| `transliterate` | `string` | null (Unicode -> ASCII via Unidecode) |
-| `transliterateUa` | `string` | null (Ukrainian-specific rules) |
-| `fromJson` | `dict` or `array` | null. Empty string -> empty dict |
-| `toJson` | `string` | `""` if null |
-| `trim` | `string` | null |
-
-### Value Directives (in YAML input mappings)
-
-**`expression`** -- Evaluate NCalc expression as a value:
-```yaml
-amount:
-  expression: "[price] * [quantity]"
-```
-
-**`coalesce`** -- First non-null value from a list:
-```yaml
-displayName:
-  coalesce:
-    - "{{ customer.name? }}"
-    - "{{ customer.email? }}"
-    - "Unknown"
-```
-
-**`foreach`** (value context) -- Transform collections inline:
-```yaml
-commodities:
-  foreach: "sourceCommodities"
-  item: "item"                             # default: "item"
-  conditions: "[item.isActive] = true"     # optional NCalc filter per item
-  continueOnError: false                   # optional, skip errors
-  mapping:                                 # dict -> List<dict>, string -> List<object>
-    name: "{{ item.name }}"
-    quantity: "{{ item.qty }}"
-```
-
-**`switch`** (value context) -- Value-based switch (case-insensitive match):
-```yaml
-perLb:
-  switch: "{{ contact.commissionTier }}"
-  cases:
-    "tier1": "{{ rate.customValues.commission_per_lb_tier1 }}"
-    "tier2": "{{ rate.customValues.commission_per_lb_tier2 }}"
-  default: "0"
-```
-
-**`extends`** -- Extend/merge an existing object or array:
-```yaml
-orderData:
-  extends: "{{ existingOrder }}"           # base object or array
-  defaultIfNull: {}                        # fallback if extends is null
-  mapping:                                 # dict: merge overrides. array: append items
-    status: "Updated"
-    notes: "{{ newNotes }}"
-```
-
-**`$raw`** -- Prevent template parsing (pass as-is):
-```yaml
-template:
-  $raw: "This {{ won't }} be parsed"
-```
-
-**`$eval`** -- Parse JSON string then evaluate as template:
-```yaml
-dynamicConfig:
-  $eval: "{{ configJsonString }}"
-```
-
-**`decrypt`** / **`encrypt`** -- AES-CBC encryption (optional key/IV, has defaults):
-```yaml
-apiKey:
-  decrypt:
-    encryptedValue: "{{ encryptedApiKey }}"
-    key: "{{ encryptionKey }}"             # optional Base64 AES key
-    initializationVector: "{{ iv }}"       # optional Base64 IV
-```
-
----
+For template expressions `{{ path }}` used in step inputs, see [ref-expressions-template.md](ref-expressions-template.md).
 
 ## NCalc Expressions: `[variable]` (in conditions and expression directives)
 
@@ -224,24 +109,3 @@ Custom: `ceiling([value])` -- same as `Ceiling` but handles type conversion to d
 |----------|-------------|
 | `convertWeight([weight], 'Kg', 'Lb')` | Weight unit conversion. Returns `decimal` rounded to 5 places |
 | `convertDimension([length], 'Cm', 'In')` | Dimension unit conversion. Returns `decimal` rounded to 3 places |
-
----
-
-## Property Path Syntax (in collection, mapping, variable paths)
-
-Used in `collection:` (foreach), `mapping:` (outputs), and variable resolution.
-
-| Pattern | Description | Example |
-|---------|-------------|---------|
-| `a.b.c` | Dot-separated nested path | `order.customer.name` |
-| `prop?` | Optional access (null if missing) | `order.customer?.name?` |
-| `list[0]` | Array index | `items[0]` |
-| `list[^1]` | Index from end (last item) | `items[^1]` |
-| `list[*]` | Flatten/wildcard (all items) | `containers[*].commodities` |
-| `list[**]` | Recursive flatten (all depths) | `containerCommodities[**]` |
-| `list[-1]` | Depth filter (leaves only) | `tree[**][-1]` |
-| `list[condition]` | Filter by condition | `items[status=Active]` |
-| `dict['key']` | Dictionary key access | `customValues['myField']` |
-| `list[*].{f1 f2}` | Field selector (projection) | `items[*].{name description}` |
-| `list[*].{alias:source}` | Field selector with alias | `items[*].{id:commodityId}` |
-| `list[*].{alias:_.parent}` | Field selector referencing parent | `items[*].{parentId:_.orderId}` |

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

@@ -0,0 +1,148 @@
+# Template Expressions & Value Directives
+
+## Contents
+- Template expression syntax `{{ path }}` (in step inputs)
+- Type converters (int, decimal, bool, fromJson, toJson, etc.)
+- Value directives (expression, coalesce, foreach, switch, extends, $raw, $eval, encrypt/decrypt)
+- Property path syntax (dot paths, array indexing, wildcards, filters, projections)
+
+There are **two distinct syntaxes** for referencing variables, used in different contexts. This file covers **template expressions** used in step inputs. For NCalc conditions and functions, see [ref-expressions-ncalc.md](ref-expressions-ncalc.md).
+
+## Template Expressions: `{{ path }}` (in step inputs)
+
+Used in step `inputs` values. Resolves variable paths from scoped variables.
+
+```yaml
+inputs:
+  orderId: "{{ inputs.orderId }}"                    # Simple reference
+  url: "{{ chopinConfig.baseUrl }}/api/v1"           # String interpolation
+  order: "{{ Data.GetOrder.order }}"                 # Raw object (single {{ }})
+  name: "Order {{ Data.GetOrder.order.orderNumber }}" # String interpolation (multiple)
+```
+
+**Key behavior**: A single `{{ path }}` returns the **raw object** (preserving type). Multiple `{{ }}` in a string returns string interpolation (each resolved value is `.ToString()`).
+
+### Type Converters (prefix in {{ }})
+
+```yaml
+organizationId: "{{ int organizationId }}"
+amount: "{{ decimal totalAmount }}"
+isActive: "{{ bool isActive }}"
+flag: "{{ boolOrFalse someFlag }}"        # null -> false
+flagOn: "{{ boolOrTrue someFlag }}"       # null -> true
+notes: "{{ emptyIfNull notes }}"          # null -> ""
+notes: "{{ nullIfEmpty notes }}"          # "" or whitespace -> null
+config: "{{ fromJson configJsonString }}" # JSON string -> dict/array
+payload: "{{ toJson someObject }}"        # object -> JSON string
+name: "{{ trim value }}"
+search: "{{ luceneString query }}"        # escape & quote for Lucene
+```
+
+| Converter | Returns | Null handling |
+|-----------|---------|---------------|
+| `string` | `string` | null. Reads `Stream` to string if value is Stream |
+| `int` | `int` | Throws on null |
+| `decimal` | `decimal` | Throws on null |
+| `bool` | `bool` | Throws on null |
+| `boolOrFalse` | `bool` | `false` if null |
+| `boolOrTrue` | `bool` | `true` if null |
+| `datetime` | `DateTime` | Throws on null |
+| `emptyIfNull` | same type | `""` if null, `0` for int?, `0m` for decimal? |
+| `nullIfEmpty` | same type | `null` if empty/whitespace string or empty collection |
+| `luceneString` | `string` | null |
+| `transliterate` | `string` | null (Unicode -> ASCII via Unidecode) |
+| `transliterateUa` | `string` | null (Ukrainian-specific rules) |
+| `fromJson` | `dict` or `array` | null. Empty string -> empty dict |
+| `toJson` | `string` | `""` if null |
+| `trim` | `string` | null |
+
+### Value Directives (in YAML input mappings)
+
+**`expression`** -- Evaluate NCalc expression as a value:
+```yaml
+amount:
+  expression: "[price] * [quantity]"
+```
+
+**`coalesce`** -- First non-null value from a list:
+```yaml
+displayName:
+  coalesce:
+    - "{{ customer.name? }}"
+    - "{{ customer.email? }}"
+    - "Unknown"
+```
+
+**`foreach`** (value context) -- Transform collections inline:
+```yaml
+commodities:
+  foreach: "sourceCommodities"
+  item: "item"                             # default: "item"
+  conditions: "[item.isActive] = true"     # optional NCalc filter per item
+  continueOnError: false                   # optional, skip errors
+  mapping:                                 # dict -> List<dict>, string -> List<object>
+    name: "{{ item.name }}"
+    quantity: "{{ item.qty }}"
+```
+
+**`switch`** (value context) -- Value-based switch (case-insensitive match):
+```yaml
+perLb:
+  switch: "{{ contact.commissionTier }}"
+  cases:
+    "tier1": "{{ rate.customValues.commission_per_lb_tier1 }}"
+    "tier2": "{{ rate.customValues.commission_per_lb_tier2 }}"
+  default: "0"
+```
+
+**`extends`** -- Extend/merge an existing object or array:
+```yaml
+orderData:
+  extends: "{{ existingOrder }}"           # base object or array
+  defaultIfNull: {}                        # fallback if extends is null
+  mapping:                                 # dict: merge overrides. array: append items
+    status: "Updated"
+    notes: "{{ newNotes }}"
+```
+
+**`$raw`** -- Prevent template parsing (pass as-is):
+```yaml
+template:
+  $raw: "This {{ won't }} be parsed"
+```
+
+**`$eval`** -- Parse JSON string then evaluate as template:
+```yaml
+dynamicConfig:
+  $eval: "{{ configJsonString }}"
+```
+
+**`decrypt`** / **`encrypt`** -- AES-CBC encryption (optional key/IV, has defaults):
+```yaml
+apiKey:
+  decrypt:
+    encryptedValue: "{{ encryptedApiKey }}"
+    key: "{{ encryptionKey }}"             # optional Base64 AES key
+    initializationVector: "{{ iv }}"       # optional Base64 IV
+```
+
+---
+
+## Property Path Syntax (in collection, mapping, variable paths)
+
+Used in `collection:` (foreach), `mapping:` (outputs), and variable resolution.
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `a.b.c` | Dot-separated nested path | `order.customer.name` |
+| `prop?` | Optional access (null if missing) | `order.customer?.name?` |
+| `list[0]` | Array index | `items[0]` |
+| `list[^1]` | Index from end (last item) | `items[^1]` |
+| `list[*]` | Flatten/wildcard (all items) | `containers[*].commodities` |
+| `list[**]` | Recursive flatten (all depths) | `containerCommodities[**]` |
+| `list[-1]` | Depth filter (leaves only) | `tree[**][-1]` |
+| `list[condition]` | Filter by condition | `items[status=Active]` |
+| `dict['key']` | Dictionary key access | `customValues['myField']` |
+| `list[*].{f1 f2}` | Field selector (projection) | `items[*].{name description}` |
+| `list[*].{alias:source}` | Field selector with alias | `items[*].{id:commodityId}` |
+| `list[*].{alias:_.parent}` | Field selector referencing parent | `items[*].{parentId:_.orderId}` |

package/package.json

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