@cxtms/cx-schema 1.8.1 → 1.8.2

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

@@ -1,30 +1,36 @@
 ---
 name: cx-module
-description: Generate schema-valid CargoXplorer app module YAML files (UI screens, forms, grids, routes)
+description: >
+  Works with CXTMS app module YAML files — creates, modifies, fixes, validates, and deploys UI screens, forms, grids, and 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>
 ---
 
 You are a CargoXplorer module YAML builder. You generate schema-valid YAML for CX app modules — UI screens, forms, data grids, routes, and components. All output must conform to the JSON schemas in `.cx-schema/`.
 
-**IMPORTANT — use `cx-cli` for all module operations:**
-- **Scaffold**: `npx cx-cli create module <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.
-- **Scaffold with fields**: `npx cx-cli create module <name> --template <template> --options '<json>'`
-- **Validate**: `npx cx-cli <file.yaml>` — run after every change
-- **Schema lookup**: `npx cx-cli schema <component>` — e.g., `cx-cli schema form`, `cx-cli schema dataGrid`
-- **Examples**: `npx cx-cli example <component>` — show example YAML
-- **List schemas**: `npx cx-cli list`
-- **Extract**: `npx cx-cli extract <source> <component> --to <target>` — move components between modules
-- **Feature folder**: `npx cx-cli create module <name> --template <template> --feature <feature-name>`
+**IMPORTANT — use `cxtms` for all module operations:**
+- **Scaffold**: `npx cxtms create module <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.
+- **Scaffold with fields**: `npx cxtms create module <name> --template <template> --options '<json>'`
+- **Validate**: `npx cxtms <file.yaml>` — run after every change
+- **Schema lookup**: `npx cxtms schema <component>` — e.g., `cxtms schema form`, `cxtms schema dataGrid`
+- **Examples**: `npx cxtms example <component>` — show example YAML
+- **List schemas**: `npx cxtms list`
+- **Extract**: `npx cxtms extract <source> <component> --to <target>` — move components between modules
+- **Feature folder**: `npx cxtms create module <name> --template <template> --feature <feature-name>`
+- **Deploy to server**: `npx cxtms appmodule deploy <file.yaml> --org <id>` — creates or updates module on the CX server
+- **Undeploy from server**: `npx cxtms appmodule undeploy <appModuleId> --org <id>` — removes a module by UUID
+- **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 module` 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 module` 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 module <name> --template <template>
-npx cx-cli create module <name> --template <template> --options '<json>'
+npx cxtms create module <name> --template <template>
+npx cxtms create module <name> --template <template> --options '<json>'
 ```
 
 | Template | Use Case |
@@ -52,7 +58,7 @@ npx cx-cli create module <name> --template <template> --options '<json>'
 ### Step 4: Validate
 
 ```bash
-npx cx-cli <generated-file.yaml>
+npx cxtms <generated-file.yaml>
 ```
 
 ---
@@ -64,7 +70,7 @@ Customize generated modules at scaffold time with `--options`. Accepts inline JS
 ### Field Array Format (all templates)
 
 ```bash
-npx cx-cli create module "Tariff" --template grid --options '[
+npx cxtms create module "Tariff" --template grid --options '[
   {"name": "code", "type": "text", "label": "Tariff Code", "required": true},
   {"name": "rate", "type": "number", "label": "Rate %"},
   {"name": "effectiveDate", "type": "date"},
@@ -75,7 +81,7 @@ npx cx-cli create module "Tariff" --template grid --options '[
 ### Object Format (with entityName)
 
 ```bash
-npx cx-cli create module "Country" --template select --options '{
+npx cxtms create module "Country" --template select --options '{
   "entityName": "Country",
   "fields": [
     {"name": "countryCode", "type": "text", "label": "Country Code"},
@@ -107,13 +113,18 @@ npx cx-cli create module "Country" --template select --options '{
 
 ## Extract Command
 
-Move a component (and its routes) from one module into another. Useful for splitting large modules into smaller, focused ones.
+Move or copy a component (and its routes) from one module into another. Useful for splitting large modules or sharing components.
 
 ```bash
-cx-cli extract <source-file> <component-name> --to <target-file>
+cxtms extract <source-file> <component-name> --to <target-file>
+cxtms extract <source-file> <component-name> --to <target-file> --copy
 ```
 
-### What Gets Moved
+### Flags
+- `--to <file>` — target module file (required)
+- `--copy` — copy instead of move (source keeps the component, target gets a higher-priority copy)
+
+### What Gets Moved/Copied
 - The component matching the exact `name` field
 - Any routes whose `component` field matches the component name
 - Permissions and entities are **NOT** moved
@@ -121,11 +132,14 @@ cx-cli extract <source-file> <component-name> --to <target-file>
 ### Examples
 
 ```bash
-# Extract to a new file (creates module scaffold automatically)
-npx cx-cli extract modules/orders.yaml Orders/CreateItem --to modules/order-create.yaml
+# Move a component to a new file (creates module scaffold automatically)
+npx cxtms extract modules/orders.yaml Orders/CreateItem --to modules/order-create.yaml
+
+# Copy a component (source unchanged, target gets higher priority)
+npx cxtms extract modules/orders.yaml Orders/CreateItem --to modules/order-create.yaml --copy
 
 # Extract to an existing module
-npx cx-cli extract modules/main.yaml Dashboard --to modules/dashboard.yaml
+npx cxtms extract modules/main.yaml Dashboard --to modules/dashboard.yaml
 ```
 
 ### New Target Scaffold
@@ -138,7 +152,7 @@ When the target file doesn't exist, a new module is created with:
 ### Workflow
 1. Run `extract` to move the component
 2. Manually move any related permissions/entities if needed
-3. Validate both files: `npx cx-cli <source>` and `npx cx-cli <target>`
+3. Validate both files: `npx cxtms <source>` and `npx cxtms <target>`
 
 ---
 
@@ -198,7 +212,7 @@ module:
   description:
     en-US: "Module description"
   application: "CargoXplorer"             # Required
-  fileName: "modules/<name>-module.yaml"  # File path in repo
+  filePath: "modules/<name>-module.yaml"  # File path in repo
 
 entities:
   - name: <EntityName>
@@ -224,6 +238,15 @@ permissions:
     displayName: { en-US: "..." }
     roles: ["Admin", "Manager"]
 
+configurations:                              # Optional: org-level config definitions
+  - configName: "apps.myFeature"             # Unique config key
+    displayName: { en-US: "My Feature Settings" }
+    description: { en-US: "Configure my feature" }
+    component: "ModuleName/ConfigComponent"  # Component that renders the config UI
+    defaultValue:                            # Optional default values
+      enabled: true
+      limit: 100
+
 routes:
   - name: "routeName"
     path: "/module-path"                   # Supports :params
@@ -384,9 +407,61 @@ Reusable select components (e.g., `Countries/Select`, `Ports/Select`) follow thi
 
 ---
 
+## Server Module Commands
+
+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 [cx-core/ref-cli-auth.md](.claude/skills/cx-core/ref-cli-auth.md)
+
+### Releasing App to GitHub
+
+Use `app release` to release modified modules and workflows 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
+# Release all unpublished changes to GitHub (creates a PR) — message is required
+npx cxtms app release -m "Add warehouse locations module"
+
+# Release specific modules and/or workflows by YAML file
+npx cxtms app release -m "Fix country module" modules/my-module.yaml
+npx cxtms app release -m "Update billing" modules/a.yaml workflows/b.yaml
+
+# Force release all modules and workflows (not just unpublished ones)
+npx cxtms app release -m "Full republish" --force
+
+# Release with explicit org
+npx cxtms app release -m "Add warehouse locations module" --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 module/workflow YAML files to the branch
+5. Creates a pull request from the publish branch to the target branch
+6. Marks published modules and workflows 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 modules and workflows 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:** Modules and workflows must be deployed to the TMS server before they can be released. Use `cxtms appmodule deploy` or `cxtms workflow 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
+
+---
+
 # Generation Rules
 
-1. **Always scaffold via `cx-cli create module` first** — never write YAML from scratch, never copy templates manually
+1. **Always scaffold via `cxtms create module` first** — never write YAML from scratch, never copy templates manually
 2. **Use localized strings** `{ en-US: "..." }` for all user-visible text
 3. **Follow naming conventions**:
    - Module names: PascalCase (e.g., `WarehouseLocations`)
@@ -394,9 +469,9 @@ Reusable select components (e.g., `Countries/Select`, `Ports/Select`) follow thi
    - Route paths: kebab-case (e.g., `/warehouse-locations`)
    - Permission names: PascalCase with slashes (e.g., `WarehouseLocations/Read`, `System/Contacts/Update`)
 4. **Template expressions** use `{{ expression }}` syntax (double curly braces)
-5. **Include fileName** property pointing to the YAML file location
+5. **Include filePath** property pointing to the YAML file location
 6. **Set proper entityKind** when defining entities (Order, Contact, OrderEntity, AccountingTransaction, Calendar, CalendarEvent, Other)
 7. **DataGrid options** requires ALL properties: query, rootEntityName, entityKeys, navigationType, enableDynamicGrid, enableViews, enableSearch, enablePagination, enableColumns, enableFilter, defaultView, onRowClick
 8. **Form component** requires `validationSchema` in props
-9. **Do not change `appModuleId` or `fileName`** — set correctly by CLI scaffold
-10. **Always validate** the final YAML: `npx cx-cli <file.yaml>`
+9. **Do not change `appModuleId` or `filePath`** — set correctly by CLI scaffold
+10. **Always validate** the final YAML: `npx cxtms <file.yaml>`

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.
@@ -31,7 +44,11 @@ Full-featured data table with views, filtering, sorting, pagination, and row act
 | `defaultView` | `string` | — | Default view name |
 | `defaultPageSize` | `number` | `20` | Rows per page |
 | `enableRefresh` | `boolean` | — | Auto-refresh |
+| `refreshInterval` | `number` | `30000` | Auto-refresh polling interval (ms) |
 | `enableChangeTracking` | `boolean` | `true` | Track data changes |
+| `highlightNew` | `boolean` | `true` | Highlight newly added rows |
+| `highlightUpdated` | `boolean` | `true` | Highlight rows with updated values |
+| `highlightForRefreshes` | `number` | `1` | Per-row TTL — refresh cycles a highlight persists |
 | `onRowClick` | `action[]` | — | Default row click action |
 | `onDataLoad` | `action[]` | — | Action after data loads |
 | `items` | `any` | — | Static data (instead of query) |

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.
@@ -182,7 +188,7 @@ Polymorphic form field — renders different input types based on `type` prop.
 | `onFocus` | Fires on focus |
 | `onKeyPress` | Fires on keypress (data: `key`, `keyCode`) |
 | `onSelectValue` | Fires on select-async value selection |
-| `onEditClick` | Fires when edit icon clicked (select-async, permission-gated) |
+| `onEditClick` | Fires when edit icon clicked. Supported on text and select-async fields. Passes current form values (with optional `valueFieldName`) to the action context |
 
 ```yaml
 # Text field

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.
@@ -331,7 +341,9 @@ CSS Grid-based timeline with swim lanes, drill-down, and virtual scrolling.
 | `view` | `day \| week \| month \| year` | `week` | Time view |
 | `startDate` / `endDate` | `string` | — | Date range |
 | `eventSources` | `EventSource[]` | — | Event data sources |
+| `eventSources[].query.name` | `string` | `query1`, `query2`... | Source name, used as key in `summaryComponent` `dataSources` |
 | `eventTemplate` | `ComponentProps` | — | Custom event template |
+| `summaryComponent` | `ComponentProps` | — | Custom component rendered per column in the summary row. Replaces numeric totals when set. |
 | `options.height` | `string \| number` | `600` | Container height |
 | `options.cellHeight` | `number` | `60/100` | Cell height (px) |
 | `options.groupBy` | `string` | — | Field for swim lane grouping |
@@ -342,6 +354,14 @@ CSS Grid-based timeline with swim lanes, drill-down, and virtual scrolling.
 | `options.showWeekends` | `boolean` | `true` | Show weekends |
 | `options.showTotalCount` | `boolean` | `false` | Show event totals |
 
+**Summary component variables** (available when `summaryComponent` is set):
+| Variable | Type | Description |
+|----------|------|-------------|
+| `dataSources` | `Record<string, TimelineEvent[]>` | Per-source events filtered to the column, keyed by `query.name` |
+| `column` | `ColumnDefinition` | Column metadata (`id`, `label`, `date`, `startDate`, `endDate`) |
+| `columnIndex` | `number` | Zero-based column index |
+| `totalCount` | `number` | Total event count for the column across all sources |
+
 **Events:**
 | Event | Data | Description |
 |-------|------|-------------|
@@ -387,6 +407,36 @@ props:
           props: { date: "{{ date }}", assignee: "{{ row }}" }
 ```
 
+**Summary component example** (per-source breakdown per column):
+```yaml
+component: timeline-grid
+props:
+  view: week
+  options: { height: 600, enableNavigation: true }
+  eventSources:
+    - query:
+        name: ups
+        command: "query($s:String!,$e:String!){ upsShipments(start:$s,end:$e){ id date title } }"
+        variables: { s: "{{ startDate }}", e: "{{ endDate }}" }
+        path: upsShipments
+    - query:
+        name: fedex
+        command: "query($s:String!,$e:String!){ fedexShipments(start:$s,end:$e){ id date title } }"
+        variables: { s: "{{ startDate }}", e: "{{ endDate }}" }
+        path: fedexShipments
+  summaryComponent:
+    component: layout
+    props:
+      direction: column
+    children:
+      - component: text
+        props: { value: "UPS: {{ dataSources.ups.length }}" }
+      - component: text
+        props: { value: "FedEx: {{ dataSources.fedex.length }}" }
+      - component: text
+        props: { value: "Total: {{ totalCount }}" }
+```
+
 ---
 
 ## oauth2

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

@@ -1,27 +1,36 @@
 ---
 name: cx-workflow
-description: Generate schema-valid CargoXplorer workflow YAML files (standard process and Flow state machine workflows)
+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 |
@@ -71,7 +80,7 @@ npx cx-cli create workflow <name> --template <template>
 ### 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](.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.
@@ -285,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)
@@ -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 [cx-core/ref-cli-auth.md](.claude/skills/cx-core/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/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.