@cxtms/cx-schema 1.1.0 → 1.2.1

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

@@ -0,0 +1,147 @@
+# Shared Entity Reference
+
+Tag, Attachment, Division, EquipmentType, PackageType, Note/NoteThread.
+
+## Tag
+
+Tagging system for orders, commodities, inventory items.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `tagId` | `int` | PK |
+| `organizationId` | `int` | |
+| `name` | `string` | |
+| `description` | `string?` | |
+| `entityName` | `string` | Discriminator: which entity type this tag belongs to |
+| `isDeleted` | `bool` | Soft delete |
+| `customValues` | `Dictionary` | jsonb |
+
+**Join entities** (all have own `customValues`):
+- `OrderTag` — `orderId` + `tagId` + `customValues`
+- `CommodityTag` — `commodityId` + `tagId` + `customValues`
+- `InventoryItemTag` — `inventoryItemId` + `tagId` + `customValues`
+
+---
+
+## Attachment
+
+File attachments linked to orders, contacts, jobs, etc.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `attachmentId` | `int` | PK |
+| `attachmentGuid` | `Guid?` | |
+| `fileName` | `string` | |
+| `fileUri` | `string` | Storage path |
+| `fileExtension` | `string` | Computed from fileName |
+| `previewUri` | `string?` | |
+| `thumbnailUri` | `string?` | |
+| `description` | `string?` | |
+| `attachmentType` | `AttachmentType` enum | Picture=1, OtherDocument, Avatar, CustomerDocument |
+| `parentId` | `string?` | Polymorphic FK (entity ID as string) |
+| `parentType` | `AttachmentParentType` enum | None=0, Order=1, Contact=2, AccountingTransaction=3, EquipmentType=4, Job=5, Commodity=6 |
+| `status` | `AttachmentStatus` enum | Active=0, PendingUpload=1, UploadFailed=2 |
+| `category` | `AttachmentCategory` enum | General=0, FieldValue=1 |
+| `organizationId` | `int` | |
+| `customValues` | `Dictionary` | jsonb |
+
+### GraphQL Computed
+
+- `isImage`, `isPdf` — computed from extension
+- `presignedFileUri`, `presignedPreviewUri`, `presignedThumbnailUri` — signed URLs
+- `getPresignedUri(expiresInDays, uriType)` — custom resolver
+- `getParentOrder` — resolve parent Order
+
+---
+
+## Division
+
+Organization divisions/branches.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `divisionId` | `int` | PK |
+| `organizationId` | `int` | |
+| `divisionName` | `string` | |
+| `email` | `string?` | |
+| `phoneNumber` | `string?` | |
+| `faxNumber` | `string?` | |
+| `streetAndNumber` | `string?` | |
+| `city` | `string?` | |
+| `stateCode` | `string?` | FK to State |
+| `countryCode` | `string?` | FK to Country |
+| `zipCode` | `string?` | |
+| `portId` | `string?` | FK to Port |
+| `comments` | `string?` | |
+| `parentDivisionId` | `int?` | Self-referencing FK |
+| `assignDivisionToEntities` | `bool` | |
+| `useDivisionInDocumentHeaders` | `bool` | |
+| `airAmsOriginatorCode` | `string?` | |
+
+**Navigation:** `country`, `state`, `port`, `parentDivision`, `nestedDivisions` (children). No customValues.
+
+---
+
+## EquipmentType
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `equipmentTypeId` | `int` | PK |
+| `organizationId` | `int` | |
+| `name` | `string` | |
+
+No customValues. Linked to carriers via `CarrierEquipment` join.
+
+---
+
+## PackageType
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `packageTypeId` | `int` | PK |
+| `organizationId` | `int` | |
+| `name` | `string` | |
+| `height` | `decimal` | |
+| `length` | `decimal` | |
+| `width` | `decimal` | |
+| `weight` | `decimal` | |
+| `maximumWeight` | `decimal` | |
+| `volume` | `decimal` | |
+| `air` | `bool` | Mode applicability |
+| `ground` | `bool` | |
+| `ocean` | `bool` | |
+| `containerDescriptionCode` | `string?` | FK |
+| `containerTypeCode` | `string?` | FK |
+| `packageCategoryCode` | `string` | FK |
+
+**Navigation:** `packageCategory`, `containerDescription`, `containerType`. No customValues.
+
+---
+
+## NoteThread
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `Guid` | PK |
+| `organizationId` | `int` | |
+| `name` | `string` | |
+| `slug` | `string` | Lowercase identifier |
+| `isDeleted` | `bool` | Soft delete |
+| `metadata` | `Dictionary` | jsonb (non-nullable, defaults to {}) |
+
+**Collections:** `notes` (one-to-many)
+
+## Note
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `Guid` | PK |
+| `threadId` | `Guid` | FK to NoteThread |
+| `threadName` | `string` | Snapshot of thread name |
+| `content` | `Dictionary` | TipTap document format (root type="doc"), max 256KB |
+| `mentions` | `[Dictionary]?` | Mentioned users/entities |
+| `tags` | `[string]` | Max 20 tags, each max 32 chars |
+| `isPinned` | `bool` | |
+| `isDeleted` | `bool` | Soft delete |
+
+**Navigation:** `thread` (NoteThread)

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

@@ -0,0 +1,110 @@
+# Warehouse & Inventory Entity Reference
+
+## InventoryItem
+
+SKU-level inventory tracking.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `inventoryItemId` | `int` | PK |
+| `organizationId` | `int` | |
+| `sku` | `string` | Stock keeping unit |
+| `productName` | `string?` | |
+| `modelNumber` | `string?` | |
+| `description` | `string?` | |
+| `availableQuantity` | `int` | |
+| `backOrderQuantity` | `int` | |
+| `height` | `decimal?` | |
+| `length` | `decimal?` | |
+| `width` | `decimal?` | |
+| `weight` | `decimal?` | |
+| `volumePiece` | `decimal?` | |
+| `dimensionsUnit` | `DimensionsUnit` enum | In, Cm, M, Ft |
+| `weightUnit` | `WeightUnit` enum | Lb, Kg |
+| `volumeUnit` | `VolumeUnit` enum | Ft, Vlb, Vkg, M, In, Cm |
+| `useSerialNumbers` | `bool` | |
+| `isInactive` | `bool` | |
+| `customerContactId` | `int?` | FK to Contact |
+| `manufacturerContactId` | `int?` | FK to Contact |
+| `packageTypeId` | `int?` | FK to PackageType |
+| `customValues` | `Dictionary` | jsonb |
+
+### Navigation
+
+| Field | Type |
+|-------|------|
+| `customerContact` | `Contact?` |
+| `manufacturerContact` | `Contact?` |
+| `packageType` | `PackageType?` |
+| `commodities` | `[Commodity]` |
+| `inventoryItemTags` | `[InventoryItemTag]` |
+| `allTags` | `[InventoryItemAllTagsView]` |
+
+### GraphQL Computed
+
+- `getContact(idPropertyName)` — resolve contact from customValues
+
+---
+
+## WarehouseLocation
+
+Physical storage zones/locations in warehouse.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `warehouseLocationId` | `int` | PK |
+| `organizationId` | `int` | |
+| `code` | `string` | Location code |
+| `description` | `string?` | |
+| `locationType` | `LocationType` enum | See below |
+| `height` | `decimal?` | |
+| `length` | `decimal?` | |
+| `width` | `decimal?` | |
+| `maximumWeight` | `decimal?` | |
+| `isInactive` | `bool` | |
+| `customerId` | `int?` | FK to Contact |
+| `parentZoneId` | `int?` | FK to WarehouseZone |
+
+### LocationType Enum
+
+Receiving, Storage, Replenishment, Picking, QualityControl, Shipping, Mobile, Other, Packing, Service, PutAway
+
+### Navigation
+
+`customer` (Contact), `parentWarehouseZone` (WarehouseZone), `commodities` ([Commodity]). No customValues.
+
+---
+
+## CargoMovement
+
+**Not a separate entity** — implemented as `Order` with `orderType = CargoMovement` (value 7).
+
+Movement-specific data stored in Order's `customValues`:
+
+| CustomValues Key | Type | Notes |
+|-----------------|------|-------|
+| `movementStatus` | `string` | e.g., "Created" |
+| `movementType` | `string` | |
+| `destinationLocationId` | `string/int` | Warehouse location ID |
+| `destinationLocationDescription` | `string` | |
+| `transportationMode` | `string` | |
+| `finalMileCarrier` | `string` | |
+
+The Order's `trackingNumber` field serves as the pallet number for cargo movements.
+
+```yaml
+# Example: Query cargo movement in workflow
+- task: "Query/GraphQL@1"
+  name: GetMovement
+  inputs:
+    query: >-
+      query($id: Int!, $orgId: Int!) {
+        order(organizationId: $orgId, orderId: $id) {
+          orderId orderNumber trackingNumber orderType
+          customValues
+        }
+      }
+    variables:
+      id: "{{ int inputs.orderId }}"
+      orgId: "{{ int organizationId }}"
+```

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

@@ -0,0 +1,402 @@
+---
+name: cx-module
+description: Generate schema-valid CargoXplorer app module YAML files (UI screens, forms, grids, routes)
+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>`
+
+## 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.
+
+```bash
+npx cx-cli create module <name> --template <template>
+npx cx-cli create module <name> --template <template> --options '<json>'
+```
+
+| Template | Use Case |
+|----------|----------|
+| `default` | Generic module with form |
+| `form` | Entity create/edit form |
+| `configuration` | Settings/config screen |
+| `grid` | List/table view |
+| `select` | Reusable async select |
+
+### Step 2: Read the generated file
+
+### Step 3: Customize for the use case
+
+**All templates** — update module name, component names, entity fields, permissions, GraphQL queries/mutations.
+
+**`form`** — update form fields, validationSchema, query/mutation field lists. Add tabs for grouped fields. Customize toolbar buttons. Update dirtyGuard messages.
+
+**`configuration`** — update form fields, initialValues.append defaults, validationSchema rules, query/mutation field lists. Add tabs for grouped settings.
+
+**`grid`** — update view columns, filters, entity fields. Add/remove views. Customize dotsMenu actions. Configure toolbar with export/import actions.
+
+**`select`** — update `valueFieldName`, `itemLabelTemplate`, `itemValueTemplate`. Customize GraphQL query fields and variables. Set `navigateActionPermission`. Configure `dropDownToolbar` create button dialog.
+
+### Step 4: Validate
+
+```bash
+npx cx-cli <generated-file.yaml>
+```
+
+---
+
+## --options Flag
+
+Customize generated modules at scaffold time with `--options`. Accepts inline JSON or a file path.
+
+### Field Array Format (all templates)
+
+```bash
+npx cx-cli 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"},
+  {"name": "isActive", "type": "checkbox", "label": "Active"}
+]'
+```
+
+### Object Format (with entityName)
+
+```bash
+npx cx-cli create module "Country" --template select --options '{
+  "entityName": "Country",
+  "fields": [
+    {"name": "countryCode", "type": "text", "label": "Country Code"},
+    {"name": "countryName", "type": "text", "label": "Country Name"}
+  ]
+}'
+```
+
+### Field Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | string | **Required.** Field name (camelCase) |
+| `type` | string | **Required.** text, number, checkbox, date, select, select-async, textarea, email |
+| `label` | string | Display label (auto-generated from name if omitted) |
+| `required` | boolean | Add to validationSchema as required |
+| `default` | any | Default value (form/configuration template: added to initialValues.append) |
+
+### What --options Customizes Per Template
+
+| Template | Fields | Entity | Queries |
+|----------|--------|--------|---------|
+| `form` | Form children, validationSchema, initialValues.append | Entity field definitions | GraphQL query field lists (preserves `id`) |
+| `configuration` | Form children, validationSchema, initialValues.append | Entity field definitions | GraphQL query field lists |
+| `grid` | View columns (with showAs by type), entity fields | Entity name + rootEntityName | — |
+| `select` | Entity fields, itemLabelTemplate | Entity name | GraphQL query field lists |
+
+---
+
+## Extract Command
+
+Move a component (and its routes) from one module into another. Useful for splitting large modules into smaller, focused ones.
+
+```bash
+cx-cli extract <source-file> <component-name> --to <target-file>
+```
+
+### What Gets Moved
+- The component matching the exact `name` field
+- Any routes whose `component` field matches the component name
+- Permissions and entities are **NOT** moved
+
+### 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
+
+# Extract to an existing module
+npx cx-cli extract modules/main.yaml Dashboard --to modules/dashboard.yaml
+```
+
+### New Target Scaffold
+When the target file doesn't exist, a new module is created with:
+- `module` name derived from filename (PascalCase)
+- Fresh `appModuleId` (UUID)
+- `application` copied from source
+- Empty `entities` and `permissions` arrays
+
+### 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>`
+
+---
+
+## On-Demand References
+
+**Read these files only when needed for the current task.** Do not load all references upfront.
+
+### Entity Field Reference (cx-core)
+
+!cat .claude/skills/cx-core/SKILL.md
+
+### Component Directory
+
+Read the relevant category ref file when building specific component types:
+
+| Category | Components | File |
+|----------|-----------|------|
+| **Layout & Structure** | `layout`, `row`, `col`, `header`, `tabs`, `toolbar`, `card`, `line` | `.claude/skills/cx-module/ref-components-layout.md` |
+| **Forms & Input** | `form`, `field`, `field-collection`, `barcodeScanner` | `.claude/skills/cx-module/ref-components-forms.md` |
+| **Data Display** | `dataGrid`, `text`, `markup`, `badge`, `icon`, `image`, `photo`, `summary`, `diff`, `viewer`, `embed` | `.claude/skills/cx-module/ref-components-display.md` |
+| **Interactive & Nav** | `button`, `dropdown`, `menuButton`, `link`, `redirect`, `navbar`, `navbarItem`, `navbarLink`, `navDropdown` | `.claude/skills/cx-module/ref-components-interactive.md` |
+| **Data & Collections** | `collection`, `list`, `listItem`, `datasource`, `script` | `.claude/skills/cx-module/ref-components-data.md` |
+| **Specialized** | `calendar`, `notes`, `dashboard`, `dashboard-widget`, `widget`, `timeline`, `timeline-grid`, `oauth2` | `.claude/skills/cx-module/ref-components-specialized.md` |
+
+### Templates
+
+Read the relevant template after scaffolding to understand the generated structure:
+
+| Template | File |
+|----------|------|
+| default | `templates/module.yaml` |
+| form | `templates/module-form.yaml` |
+| configuration | `templates/module-configuration.yaml` |
+| grid | `templates/module-grid.yaml` |
+| select | `templates/module-select.yaml` |
+
+### JSON Schemas
+
+Read schema files from `.cx-schema/` only when debugging validation errors:
+- `schemas.json` — main schema definitions
+- `components/<type>.json` — component schemas (layout, form, dataGrid, field, button, tabs, card, calendar, collection, appComponent, module)
+- `fields/<type>.json` — field schemas (text, select, select-async)
+- `actions/<type>.json` — action schemas (navigate, mutation, dialog, all)
+
+---
+
+# Module YAML Reference
+
+## Top-Level Structure
+
+```yaml
+module:
+  name: "<ModuleName>"                    # PascalCase identifier
+  appModuleId: "<uuid>"                   # Generate a new UUID v4
+  displayName:
+    en-US: "Human Readable Name"
+  description:
+    en-US: "Module description"
+  application: "CargoXplorer"             # Required
+  fileName: "modules/<name>-module.yaml"  # File path in repo
+
+entities:
+  - name: <EntityName>
+    entityKind: Order | Contact | OrderEntity | AccountingTransaction | Calendar | CalendarEvent | Other
+    extension: false                       # true if extending existing entity
+    displayName: { en-US: "..." }
+    fields:
+      - name: fieldName
+        fieldType: text | number | date | boolean | ...
+        displayName: { en-US: "..." }
+        isCustomField: false
+        props:
+          allowOrderBy: true
+          allowFilter: true
+          filter:                          # Optional filter selector
+            component: "Contacts/Select"
+            props:
+              filter: "contactType: Customer"
+              options: { baseName: "contactId" }
+
+permissions:
+  - name: "ModuleName/Read"                   # PascalCase with slashes
+    displayName: { en-US: "..." }
+    roles: ["Admin", "Manager"]
+
+routes:
+  - name: "routeName"
+    path: "/module-path"                   # Supports :params
+    component: ComponentName               # References component name
+    platforms: [web, mobile]               # Optional, defaults to both
+    props:
+      title: { en-US: "..." }
+      icon: "icon-name"
+      permission: "permission-name"
+
+components:
+  - name: "ModuleName/ComponentName"       # Pattern: Module/Component
+    displayName: { en-US: "..." }
+    permissions: "permission-name"         # String or array
+    layout:
+      component: layout                    # Root must be a component
+      # ... component tree
+```
+
+## Action Types
+
+Actions are used in event handlers (onClick, onSubmit, etc.) as arrays:
+
+```yaml
+onClick:
+  - navigate: "~/path/{{ id }}"                           # Navigate to route
+  - navigateBack: { fallback: "/home" }                    # Go back in history
+  - navigateBackOrClose: { fallback: "/home" }             # Go back or close dialog
+  - refresh: "componentName"                               # Refresh a component
+  - notification: { message: { en-US: "Saved!" }, type: success }  # success|error|warning|info
+  - confirm: { title: { en-US: "Delete?" }, message: { en-US: "Are you sure?" } }
+  - mutation:
+      command: "mutation M($input: MInput!) { m(input: $input) { result } }"
+      variables: { input: "{{ form }}" }
+      onSuccess: [...]
+      onError: [...]
+  - query:
+      command: "query Q($id: ID!) { entity(id: $id) { id name } }"
+      variables: { id: "{{ entityId }}" }
+      onSuccess: [...]
+      onError: [...]
+  - setFields: { "fieldName": "{{ value }}" }              # Set form field values
+  - setStore: { "key": "{{ value }}" }                     # Set store values
+  - validateForm: {}                                        # Trigger form validation
+  - dialog:
+      name: "dialogName"
+      props: { title: { en-US: "Title" } }
+      component: { component: "Module/Component" }
+      onClose: [...]
+  - workflow:
+      workflowId: "<uuid>"
+      inputs: { key: "value" }
+      onSuccess: [...]
+      onError: [...]
+  - fileDownload: { url: "...", fileName: "..." }
+  - forEach:
+      items: "{{ selectedItems }}"
+      item: "currentItem"
+      actions: [...]
+  - if: "{{ condition }}"
+    then: [...]
+    else: [...]
+  - consoleLog: { message: "debug info" }
+  - openBarcodeScanner: { onScan: [...] }
+  - resetDirtyState: {}
+```
+
+## Common Patterns
+
+### Localized strings
+```yaml
+displayName:
+  en-US: "English text"
+  es-ES: "Spanish text"
+```
+
+### Template expressions
+```yaml
+value: "{{ fieldName }}"                    # Simple variable
+value: "{{ format date L }}"               # Format helper
+value: "{{ number quantity }}"             # Type cast
+value: "{{ eval items.length > 0 }}"       # JavaScript expression
+isHidden: "{{ eval !canEdit }}"            # Conditional visibility
+```
+
+### Permissions
+```yaml
+permission: "ModuleName/Read"                # Single string (PascalCase/Action)
+permissions:                                # Array
+  - "ModuleName/Read"
+  - "ModuleName/Update"
+```
+
+### Async Select Component Pattern
+
+Reusable select components (e.g., `Countries/Select`, `Ports/Select`) follow this structure:
+
+```yaml
+- name: Entity/Select
+  displayName: { en-US: "Select Entity" }
+  platforms: [web, mobile]
+  layout:
+    component: field
+    name: entityId                           # Value binding field name
+    props:
+      type: select-async
+      label: { en-US: "Entity" }
+      options:
+        valueFieldName: "entityId"           # Which result field holds the value
+        itemLabelTemplate: "{{name}}"        # Handlebars template for labels
+        itemValueTemplate: "{{entityId}}"    # Handlebars template for values
+        navigateActionPermission: "Entity/Update"
+        searchQuery:                         # References list query below
+          name: getEntities
+          path: entities.items
+          params:
+            search: "{{ string search }}"
+            take: "{{ number pageSize }}"
+            skip: "{{ number skip }}"
+            filter: "{{ string filter }}"
+        valueQuery:                          # References single-item query below
+          name: getEntity
+          path: entity
+          params:
+            entityId: "{{entityId}}"
+        allowSearch: true
+        allowClear: true
+      dropDownToolbar:                       # Create button in dropdown
+        - component: button
+          name: createBtn
+          props:
+            label: { en-US: "Create Entity" }
+            icon: plus
+            onClick:
+              - dialog:
+                  component: Entity/CreateEntity
+                  onClose:
+                    - selectValue: "{{ result.entityId }}"
+      queries:
+        - name: getEntities                  # Paginated search query
+          query:
+            command: >-
+              query($organizationId: Int!, $filter: String!, $search: String!, $take: Int!, $skip: Int!) {
+                entities(...) { items { entityId name } totalCount }
+              }
+            variables: { organizationId: "{{number organizationId}}", ... }
+        - name: getEntity                    # Single-value lookup query
+          query:
+            command: >-
+              query($organizationId: Int!, $entityId: Int!) {
+                entity(...) { entityId name }
+              }
+            variables: { entityId: "{{number entityId}}" }
+      onEditClick:                           # Edit action on selected item
+        - dialog:
+            component: { layout: { component: layout, children: [{ component: Entity/UpdateEntity }] } }
+```
+
+---
+
+# Generation Rules
+
+1. **Always scaffold via `cx-cli 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`)
+   - Component names: Module/Component pattern (e.g., `WarehouseLocations/List`)
+   - 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
+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>`