@cxtms/cx-schema 1.8.1 → 1.9.0

package/{.claude/skills/cx-workflow → skills/cxtms-workflow-builder}/SKILL.md

@@ -1,27 +1,36 @@
 ---
-name: cx-workflow
-description: Generate schema-valid CargoXplorer workflow YAML files (standard process and Flow state machine workflows)
+name: cxtms-workflow-builder
+description: >
+  Works with CXTMS workflow YAML files — creates, modifies, fixes, validates, and deploys 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>
 ---
 
 You are a CargoXplorer workflow YAML builder. You generate schema-valid YAML for CX workflows — both standard process workflows (activities, steps, triggers) and Flow state machine workflows (entity lifecycle, states, transitions). All output must conform to the JSON schemas in `.cx-schema/`.
 
-**IMPORTANT — use `cx-cli` for all workflow operations:**
-- **Scaffold**: `npx cx-cli create workflow <name> --template <template>` — generates a schema-valid YAML file. ALWAYS run this first, then read the generated file, then customize. Do NOT write YAML from scratch or copy templates manually.
-- **Validate**: `npx cx-cli <file.yaml>` — run after every change
-- **Schema lookup**: `npx cx-cli schema <task>` — e.g., `cx-cli schema graphql`, `cx-cli schema foreach`, `cx-cli schema action-event`. Schema names use kebab-case file names. Case-insensitive: `ActionEvent` resolves to `action-event`.
-- **Examples**: `npx cx-cli example <task>` — show example YAML for a task
-- **List schemas**: `npx cx-cli list --type workflow` — shows all available task schemas in the Tasks section
-- **Feature folder**: `npx cx-cli create workflow <name> --template <template> --feature <feature-name>`
+**IMPORTANT — use `cxtms` for all workflow operations:**
+- **Scaffold**: `npx cxtms create workflow <name> --template <template>` — generates a schema-valid YAML file. ALWAYS run this first, then read the generated file, then customize. Do NOT write YAML from scratch or copy templates manually.
+- **Validate**: `npx cxtms <file.yaml>` — run after every change
+- **Schema lookup**: `npx cxtms schema <task>` — e.g., `cxtms schema graphql`, `cxtms schema foreach`, `cxtms schema action-event`. Schema names use kebab-case file names. Case-insensitive: `ActionEvent` resolves to `action-event`.
+- **Examples**: `npx cxtms example <task>` — show example YAML for a task
+- **List schemas**: `npx cxtms list --type workflow` — shows all available task schemas in the Tasks section
+- **Feature folder**: `npx cxtms create workflow <name> --template <template> --feature <feature-name>`
+- **Deploy to server**: `npx cxtms workflow deploy <file.yaml> --org <id>` — creates or updates workflow on the CX server
+- **Undeploy from server**: `npx cxtms workflow undeploy <workflowId> --org <id>` — removes a workflow by UUID
+- **Execute**: `npx cxtms workflow execute <workflowId|file.yaml> --org <id> [--vars '<json>'] [--file varName=path]` — trigger a workflow execution (--file uploads a local file and passes the URL as a variable)
+- **List logs**: `npx cxtms workflow logs <workflowId|file.yaml> --org <id> [--from YYYY-MM-DD] [--to YYYY-MM-DD]` — list executions with log availability
+- **Download log**: `npx cxtms workflow log <executionId> --org <id> [--json] [--console] [--output <file>]` — download execution log
+- **Publish all**: `npx cxtms publish [--feature <name>] --org <id>` — deploy all modules and workflows to the server
 
 ## Generation Workflow
 
 ### Step 1: Scaffold via CLI — MANDATORY
 
-**You MUST run `cx-cli create workflow` to generate the initial file.** Do not skip this step. Do not write YAML from scratch. Do not read template files and copy them manually. The CLI generates correct UUIDs, file paths, and structure.
+**You MUST run `cxtms create workflow` to generate the initial file.** Do not skip this step. Do not write YAML from scratch. Do not read template files and copy them manually. The CLI generates correct UUIDs, file paths, and structure.
 
 ```bash
-npx cx-cli create workflow <name> --template <template>
+npx cxtms create workflow <name> --template <template>
 ```
 
 | Template | Use Case |
@@ -66,12 +75,12 @@ npx cx-cli create workflow <name> --template <template>
 
 **All templates** include workflow-level `events` (`onWorkflowStarted`, `onWorkflowExecuted`, `onWorkflowFailed`) and activity-level `events` (`onActivityStarted`, `onActivityCompleted`, `onActivityFailed`) with Log steps. Replace/extend these with notification tasks (Email/Send, HttpRequest, Workflow/Execute) as needed.
 
-**Flow workflows** — scaffold with `basic` then set `workflowType: Flow`, remove `activities`/`triggers`, add `entity`, `states`, `transitions`, `aggregations`. Load Flow reference: `!cat .claude/skills/cx-workflow/ref-flow.md`
+**Flow workflows** — scaffold with `basic` then set `workflowType: Flow`, remove `activities`/`triggers`, add `entity`, `states`, `transitions`, `aggregations`. Load Flow reference: `!cat skills/cxtms-workflow-builder/ref-flow.md`
 
 ### Step 4: Validate
 
 ```bash
-npx cx-cli <generated-file.yaml>
+npx cxtms <generated-file.yaml>
 ```
 
 ### File Placement
@@ -182,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](skills/cxtms-workflow-builder/ref-expressions-template.md)
+For NCalc conditions and functions: see [ref-expressions-ncalc.md](skills/cxtms-workflow-builder/ref-expressions-ncalc.md)
 
 **`{{ path }}`** — in step inputs. Single `{{ }}` returns raw object. Multiple returns string interpolation.
 **`[variable]`** — in conditions and `expression:` directives. NCalc syntax.
@@ -269,24 +279,25 @@ Implicit variable: `iteration` (zero-based).
 
 | Category | Tasks | Load Reference |
 |----------|-------|----------------|
-| Utilities | SetVariable, Log, Error, HttpRequest, Map, Template, Import, Export, CsvParse, UnzipFile | `!cat .claude/skills/cx-workflow/ref-utilities.md` |
-| Query & Workflow | Query/GraphQL, Validation, Workflow/Execute | `!cat .claude/skills/cx-workflow/ref-query.md` |
-| Entity CRUD | Order, Contact, Commodity, Job, Charge, Discount, Inventory, Movement, Transmission | `!cat .claude/skills/cx-workflow/ref-entity.md` |
-| Communication | Email/Send, Document/Render, Attachment, PdfDocument/Merge | `!cat .claude/skills/cx-workflow/ref-communication.md` |
-| File Transfer | Connect, Disconnect, ListFiles, Download, Upload, Move, Delete | `!cat .claude/skills/cx-workflow/ref-filetransfer.md` |
-| Accounting | AccountingTransaction, Payment, Number/Generate, SequenceNumber | `!cat .claude/skills/cx-workflow/ref-accounting.md` |
-| Other | User, Auth, Caching, X12/Parse, EDIFACT, Flow/Transition, Notes, AppModule, ActionEvent | `!cat .claude/skills/cx-workflow/ref-other.md` |
+| Utilities | SetVariable, Log, Error, HttpRequest, Map, Template, Import, Export, CsvParse, UnzipFile | `!cat skills/cxtms-workflow-builder/ref-utilities.md` |
+| Query & Workflow | Query/GraphQL, Validation, Workflow/Execute | `!cat skills/cxtms-workflow-builder/ref-query.md` |
+| Entity CRUD | Order, Contact, Commodity, Job, Charge, Discount, Inventory, Movement, Transmission | `!cat skills/cxtms-workflow-builder/ref-entity.md` |
+| Communication | Email/Send, Document/Render, Attachment, PdfDocument/Merge | `!cat skills/cxtms-workflow-builder/ref-communication.md` |
+| File Transfer | Connect, Disconnect, ListFiles, Download, Upload, Move, Delete | `!cat skills/cxtms-workflow-builder/ref-filetransfer.md` |
+| Accounting | AccountingTransaction, Payment, Number/Generate, SequenceNumber | `!cat skills/cxtms-workflow-builder/ref-accounting.md` |
+| Other | User, Auth, Caching, X12/Parse, EDIFACT, Flow/Transition, Notes, AppModule, ActionEvent | `!cat skills/cxtms-workflow-builder/ref-other.md` |
 
-## Entity Field Reference (cx-core)
+## Entity Field Reference (cxtms-developer)
 
-!cat .claude/skills/cx-core/SKILL.md
+!cat skills/cxtms-developer/SKILL.md
 
 ## Additional References (load on demand)
 
 | Reference | Load |
 |-----------|------|
-| Expressions & Functions | `!cat .claude/skills/cx-workflow/ref-expressions.md` |
-| Flow Workflows (state machines) | `!cat .claude/skills/cx-workflow/ref-flow.md` |
+| Template Expressions & Value Directives | `!cat skills/cxtms-workflow-builder/ref-expressions-template.md` |
+| NCalc Expressions & Functions | `!cat skills/cxtms-workflow-builder/ref-expressions-ncalc.md` |
+| Flow Workflows (state machines) | `!cat skills/cxtms-workflow-builder/ref-flow.md` |
 
 ## Dynamic Schema Access (load on demand)
 
@@ -307,19 +318,117 @@ Implicit variable: `iteration` (zero-based).
 
 ---
 
-## Debugging Workflow Executions
+## Server Workflow Commands
 
-When TMS MCP returns gzip file URLs for workflow execution logs, decompress with:
+Deploy, undeploy, and release commands are listed in the CLI section at the top of this file. For authentication setup (login, PAT tokens, org management): see [cxtms-developer/ref-cli-auth.md](skills/cxtms-developer/ref-cli-auth.md)
+
+### Releasing App to GitHub
+
+Use `app release` to release modified workflows and modules from the CX server to a GitHub repository. This creates a branch and pull request — it does NOT push directly to the target branch.
 
 ```bash
-node -e "const https=require('https'),zlib=require('zlib'),fs=require('fs');https.get(process.argv[1],r=>r.pipe(zlib.createGunzip()).pipe(fs.createWriteStream(process.argv[2])))" "<url>" "<output-file>"
+# Release all unpublished changes to GitHub (creates a PR) — message is required
+npx cxtms app release -m "Add order notification workflow"
+
+# Release specific workflows and/or modules by YAML file
+npx cxtms app release -m "Fix tracking workflow" workflows/my-workflow.yaml
+npx cxtms app release -m "Update shipping" workflows/a.yaml modules/b.yaml
+
+# Force release all workflows and modules (not just unpublished ones)
+npx cxtms app release -m "Full republish" --force
+
+# Release with explicit org
+npx cxtms app release -m "Add order notification workflow" --org 42
 ```
 
+**What `app release` does:**
+1. Reads `app.yaml` for the `id` (appManifestId), repository, and branch
+2. Increments the app version (patch bump)
+3. Creates a `publish/{app-name}-v{version}-{timestamp}` branch on GitHub
+4. Commits `app.yaml` + selected workflow/module YAML files to the branch
+5. Creates a pull request from the publish branch to the target branch
+6. Marks published workflows and modules as `hasUnpublishedChanges: false`
+
+**This is a release-to-git operation** — it commits the current server-side YAML directly to GitHub via the API. No local git repo is involved. The workflows and modules being released are taken from the CX server database, not from local files. The YAML file arguments only identify *which* items to include by their IDs.
+
+**Important:** Workflows and modules must be deployed to the TMS server before they can be released. Use `cxtms workflow deploy` or `cxtms appmodule deploy` first, then `cxtms app release` to commit them to GitHub.
+
+**Do NOT run `app release` automatically.** Only release when the user explicitly requests it. Releasing creates a branch and PR on GitHub, so it should be done once when all changes are ready — not after every deploy.
+
+**Prerequisites:**
+- `app.yaml` must exist with a valid `id` field
+- The app manifest must be installed on the server (`app install` first)
+- The server must have a GitHub token configured for the organization
+- The repository and branch must be set on the app manifest
+
+**Related commands:**
+- `npx cxtms app install` — install/refresh app from GitHub into the server
+- `npx cxtms app install --force` — force reinstall even if same version
+- `npx cxtms app install --branch develop` — install from a specific branch
+- `npx cxtms app install --skip-changed` — skip modules with local changes
+- `npx cxtms app list` — list installed app manifests on the server
+
+### Execute
+
+```bash
+# Execute a workflow by UUID or YAML file
+npx cxtms workflow execute <workflowId>
+npx cxtms workflow execute workflows/my-workflow.yaml
+
+# Pass input variables as JSON
+npx cxtms workflow execute <workflowId> --vars '{"city": "London", "count": 5}'
+
+# Upload a local file and pass its URL as a workflow variable
+npx cxtms workflow execute workflow.yaml --file importFile=/path/to/data.csv
+
+# Combine variables and file uploads
+npx cxtms workflow execute workflow.yaml --vars '{"mode": "preview"}' --file importFile=data.csv --file templateFile=template.xlsx
+```
+
+`--file varName=path` uploads the local file to the server via presigned URL and sets the resulting URL as the named variable. Can be specified multiple times.
+
+Returns execution result including `executionId`, `isAsync`, `outputs` (for Sync workflows).
+
+### Execution Logs
+
+```bash
+# List executions with log availability (sorted desc by date)
+npx cxtms workflow logs <workflowId|file.yaml>
+
+# Filter by date range
+npx cxtms workflow logs <workflowId> --from 2026-01-01 --to 2026-01-31
+
+# Download a specific execution log (saves to temp dir by default)
+npx cxtms workflow log <executionId>
+
+# Save to specific file
+npx cxtms workflow log <executionId> --output mylog.txt
+
+# Print to stdout
+npx cxtms workflow log <executionId> --console
+
+# Download JSON log (richer data: inputs, outputs, timing, metadata)
+npx cxtms workflow log <executionId> --json
+
+# JSON log to stdout
+npx cxtms workflow log <executionId> --json --console
+```
+
+`workflow logs` shows a table with execution status, date, duration, user, and log availability indicators (filled/empty circle). `workflow log` downloads the actual log content from the server (gzip-compressed S3 URLs).
+
+### Debugging Tips
+
+- Use `--json` for detailed structured data (ExecutionId, Inputs, Outputs, Exception, timing)
+- Text logs show step-by-step execution trace with timestamps
+- Sync workflow executions may not appear in `workflow logs` — they return results inline
+- Use `workflow execute --vars` to test workflows with specific inputs
+- Use `workflow execute --file varName=path` to upload local files for workflows that expect file URL inputs
+
 ---
 
 ## Generation Rules
 
-1. **Always scaffold via `cx-cli create workflow` first** — never write YAML from scratch, never copy templates manually
+1. **Always scaffold via `cxtms create workflow` first** — never write YAML from scratch, never copy templates manually
 2. **Naming conventions**: step names PascalCase, variables camelCase, states PascalCase, transitions camelCase
 3. **Template expressions** use `{{ expression }}` — NCalc conditions use `[variable]`
 4. **Do not change `workflowId` or `filePath`** — set correctly by CLI scaffold
@@ -327,4 +436,4 @@ node -e "const https=require('https'),zlib=require('zlib'),fs=require('fs');http
 6. **Flow workflows** require `entity`, `states`, `transitions` (no `activities`)
 7. **Entity triggers** require `entityName` and `eventType`
 8. **Always use null-safe `?`** on variable paths — `Activity?.Step?.output?` — unless referencing guaranteed system variables (see Variable References section)
-9. **Always validate** the final YAML: `npx cx-cli <file.yaml>`
+9. **Always validate** the final YAML: `npx cxtms <file.yaml>`

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

@@ -1,7 +1,50 @@
 # 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`.
 
+## PostalCodes
+
+| Task | Description |
+|------|-------------|
+| `PostalCodes/Import@1` | Import postal codes from file URL, stream, or inline data |
+
+### PostalCodes/Import@1
+
+Imports postal codes (CSV, JSON, Excel). Supports upsert via `matchByFields`.
+
+```yaml
+- task: "PostalCodes/Import@1"
+  name: ImportPostalCodes
+  inputs:
+    organizationId: "{{ int inputs.organizationId }}"
+    fileUrl: "{{ inputs.fileUrl }}"
+    matchByFields: ["code", "countryCode"]
+  outputs:
+    - name: importResult
+      mapping: "result?"
+```
+
+**Inputs:** `organizationId` (int, required), `fileUrl` (string?), `fileType` (FileType?), `stream` (Stream?), `postalCodes` (List?), `matchByFields` (string[]?)
+**Outputs:** `result.success`, `result.added`, `result.updated`, `result.errors`, `result.totalProcessed`, `result.hasErrors`
+Input priority: `stream` > `fileUrl` > `postalCodes`. Task catches exceptions and returns them in `result.errors`.
+
 ## Generic Entity Change
 
 | Task | Description |

package/skills/cxtms-workflow-builder/ref-expressions-ncalc.md

@@ -0,0 +1,128 @@
+# NCalc Expressions & Functions
+
+## Contents
+- 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)
+
+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)
+
+Used in `conditions[].expression`, `switch` case `when`, and `expression:` value directives. Variables use **square bracket** `[name]` syntax.
+
+```yaml
+conditions:
+  - expression: "[status] = 'Active' AND [amount] > 100"
+  - expression: "isNullOrEmpty([Data.GetOrder.order?]) = false"
+  - expression: "any([changes], [each.key] = 'Status') = true"
+```
+
+**Parameter resolution rules**:
+- Empty strings are converted to `null` (so `""` is treated as no value)
+- Numeric strings are auto-converted to `decimal` when needed (e.g., `[price] > 100` works even if price is the string `"150"`)
+- Dot paths resolve deep: `[Activity.Step.output.nested.field]`
+- Optional suffix `?` prevents errors: `[order.customer?.name?]`
+
+### Operators
+
+| Type | Operators |
+|------|-----------|
+| Comparison | `=`, `!=`, `<>`, `<`, `>`, `<=`, `>=` |
+| Logical | `AND`, `OR`, `NOT` (also `&&`, `\|\|`, `!`) |
+| Arithmetic | `+`, `-`, `*`, `/`, `%` |
+| Ternary | `if(condition, trueVal, falseVal)` |
+| Membership | `in(value, val1, val2, ...)` |
+
+### Iterator Variables
+
+Functions use two iterator variable names:
+- **`[each.*]`** -- used by: `any`, `all`, `sum`, `join` (3-arg)
+- **`[item.*]`** -- used by: `first`, `last`, `groupBy`
+
+### Collection Functions
+
+| Function | Description |
+|----------|-------------|
+| `any([items], [each.prop] = 'val')` | True if any item matches expression. Without expression: checks if collection contains the value |
+| `all([items], [each.prop] > 0)` | True if all items match. Returns `false` for null/empty collections |
+| `count([items])` | Count items in list or JToken. Returns `0` for non-collections |
+| `sum([items], [each.amount])` | Sum values as `decimal`. Optional `[each.*]` accessor. Skips nulls |
+| `first([items])` or `first([items], [item.name])` | First item or evaluate expression on first item. Returns `""` if empty |
+| `last([items])` or `last([items], [item.name])` | Last item or evaluate expression on last item. Returns `""` if empty |
+| `distinct([items])` | Remove duplicates. Uses deep comparison for dictionaries |
+| `reverse([items])` | Reverse collection or string |
+| `contains([source], 'needle')` | String contains, JArray contains, list contains, or dict key/value contains |
+| `removeEmpty([items])` | Remove null and whitespace-only items |
+| `concat([list1], [list2], ...)` | Concatenate multiple collections into flat list. Variadic args. Skips nulls |
+| `groupBy([items], [item.cat])` | Group by one or more key expressions. Returns `[{key, items}]`. Multi-key: keys joined with `\|` |
+| `join([items], [each.name], ',')` | Join collection with `[each.*]` accessor and separator (3-arg) |
+| `join([items], ',')` | Join collection directly with separator (2-arg) |
+| `split([str], ' ')` | Split string by first character of separator. Returns `List<string>` |
+| `elementAt([items], 0)` | Get element at index (zero-based) from list |
+
+### String Functions
+
+| Function | Description |
+|----------|-------------|
+| `isNullOrEmpty([var])` | True if null, empty string, or empty list |
+| `length([var])` | String length or collection count. `0` for null strings and non-collections |
+| `lower([name])` / `upper([code])` | Case conversion. Handles string, JToken, any `.ToString()` |
+| `left([code], 3)` / `right([code], 3)` | Left/right N characters. Returns full string if shorter than N |
+| `substring([str], 0, 5)` | Extract substring starting at position for given length |
+| `replace([str], 'old', 'new')` | String replacement. Returns null if any arg is null |
+| `trim([value])` | Trim whitespace. Returns `""` for null |
+| `format('{0}-{1}', [prefix], [id])` | String.Format style. Variadic args. Returns null if format is null |
+| `base64([value])` / `fromBase64([encoded])` | Base64 encode/decode. Handles string, byte[], JToken |
+| `bool([value])` | Convert to boolean: null->`false`, empty string->`false`, "true"/"false"->parsed, non-zero number->`true`, any object->`true` |
+| `transliterate([value])` | Unicode to ASCII (Unidecode). Returns `""` for null |
+| `transliterateUa([value])` | Ukrainian-specific transliteration. Returns `""` for null |
+| `parseAddress([address])` | Parse address -> `{StreetNumber, StreetName}`. Handles US and EU formats |
+
+### Date Functions
+
+| Function | Description |
+|----------|-------------|
+| `parseDate([str])` | Parse date string to DateTime. Supports common formats (ISO, US, etc.) |
+| `now()` | Current UTC `DateTime` |
+| `now('yyyy-MM-dd', 'en-US')` | Formatted current time as string |
+| `addDays([date], 30)` | Add days (decimal, can be negative). Accepts DateTime, DateTimeOffset, string |
+| `addHours([date], 2)` | Add hours (decimal, can be negative). Same type handling |
+| `formatDate([date], 'dd/MM/yyyy', 'en-US')` | Format date with culture. Accepts DateTime or string |
+| `dateFromUnix([unixTime])` | Unix timestamp (seconds) -> `DateTimeOffset`. Accepts int, long, decimal, string |
+| `dateToUtc([date])` or `dateToUtc([date], 'en-US')` | Convert to UTC. Optional culture for string parsing |
+| `toLocalTime([date], 'America/Chicago')` | Convert UTC datetime to local time in IANA timezone. Returns `null` if date or timezone is invalid |
+
+### Business Date Math (in Lucene filter expressions)
+
+The filter engine (`FilterBy`) supports business-aware date math units in Lucene date expressions:
+
+| Unit | Aliases | Description |
+|------|---------|-------------|
+| `BHOUR` | `BHOURS` | Add/subtract business hours (respects weekly schedule + holidays) |
+| `BDAY` | `BDAYS` | Add/subtract business days (skips non-working days) |
+
+**Usage**: These units are used in **Lucene filter strings** (not NCalc expressions). They require an `IBusinessDateMathResolver` and are resolved via the organization's business calendar.
+
+```
+dueDate: [NOW TO NOW+3BDAYS]
+pickupDate: [* TO NOW-8BHOURS]
+```
+
+### Math Functions (NCalc built-in)
+
+`Abs(x)`, `Ceiling(x)`, `Floor(x)`, `Round(x, decimals)`, `Min(x, y)`, `Max(x, y)`, `Pow(x, y)`, `Sqrt(x)`, `Truncate(x)`
+
+Custom: `ceiling([value])` -- same as `Ceiling` but handles type conversion to double.
+
+### Domain Functions
+
+| Function | Description |
+|----------|-------------|
+| `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 |

package/skills/cxtms-workflow-builder/ref-expressions-template.md

@@ -0,0 +1,159 @@
+# 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 |
+| `toLocalTime` | `DateTime` or `string` | null. Syntax: `{{ toLocalTime path 'TimezoneId' 'format?' }}` |
+
+### 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 }}"
+```
+
+**`resolve`** -- Entity ID lookup by querying a GraphQL collection:
+```yaml
+customerId:
+  resolve:
+    entity: "Contact"                        # Entity type (auto-pluralized for query)
+    filter: "name:{{ customerName }}"         # Lucene filter (template-parsed)
+    field: "contactId"                       # Field to return (default: <entity>Id)
+```
+Results are batched and cached per unique `entity|filter|field` combination by `ResolvePreProcessor` before step execution. Cache misses return `null`. Useful inside `foreach` mappings where many items reference the same entity — only one query per unique filter value.
+
+**`$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/{.claude/skills/cx-workflow → skills/cxtms-workflow-builder}/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
@@ -86,7 +93,7 @@ states:
 
 ### State Rules
 - **name**: Required, must be unique across all states
-- **isInitial**: At most one state can be initial
+- **isInitial**: At most one state can be initial. When an entity has null status, the engine resolves it to the initial state automatically.
 - **isFinal**: Final states cannot be transition sources
 - **parent**: References another state; parent cannot be initial or final; children inherit parent transitions
 

package/{.claude/skills/cx-workflow → skills/cxtms-workflow-builder}/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 |