@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-mystique-builder/components/fc.events.search.md

@@ -0,0 +1,21 @@
+---
+alias: "fc.events.search"
+aliases:
+  - fc.events.search
+category: content
+module: OMS
+---
+# fc.events.search
+
+Advanced event search interface with filters, timeline display, and export. Queries the Event API for system events.
+
+## When to Use
+- Event forensics / debugging pages
+- Admin event search
+- Audit trail viewing
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.field.daterange.md

@@ -0,0 +1,83 @@
+---
+alias: "fc.field.daterange"
+aliases:
+  - fc.field.daterange
+  - daterange
+category: field
+module: Core
+---
+# fc.field.daterange
+
+Date and time range picker with dual calendar view, locale-aware date formatting, and configurable future date restriction.
+
+## When to Use
+- Filter forms requiring a date/time range (e.g., event search, report generation)
+- Workflow user actions needing date range input
+- Any form where start and end date/time selection is required
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `value` | `{ from: string \| null, to: string \| null }` | No | Initial date range in ISO format (e.g., `'2024-04-18T13:50:49.030Z'`) |
+| `label` | string | No | Field label (supports i18n keys) |
+| `disableFuture` | boolean | Yes | When `true`, prevents selection of future dates. Default: `false` |
+| `isError` | boolean | No | Marks input as invalid with red border (custom component only) |
+| `helperText` | string | No | Helper text below the input field (custom component only) |
+| `minDate` | string | No | Minimum selectable date (custom component only) |
+| `maxDate` | string | No | Maximum selectable date (custom component only) |
+
+## Data Binding
+In workflow configuration, use `defaultValue` with `{ from: "", to: "" }` to set initial range. The component returns values in ISO 8601 string format. Properties marked with "custom component only" can only be configured when used as a registered SDK component, not through workflow contracts.
+
+### Workflow Contract Properties
+`name`, `label`, `type`, `source`, `value`, `options`, `defaultValue`, `mandatory`
+
+## Descendants
+No.
+
+## Gotchas
+- Date format adapts to the browser's preferred language: `dd/mm/yyyy` (UK/AU), `mm/dd/yyyy` (US), `yyyy/mm/dd` (CA/FR-CA).
+- Time uses 24-hour format. Default start time: `00:00:00`, default end time: `23:59:59`.
+- Both start and end times are required once the filter is applied.
+- Navigation icons disable at January 1970 (minimum) and the month after the current month (maximum).
+- Clear resets all changes; Cancel restores initial values and closes; Apply confirms and closes.
+
+## Manifest Example
+```json
+{
+  "userActions": [
+    {
+      "eventName": "ApplyDateFilter",
+      "context": [
+        {
+          "label": "Date",
+          "type": "SECONDARY",
+          "modules": ["adminconsole"],
+          "confirm": true
+        }
+      ],
+      "attributes": [
+        {
+          "name": "daterange",
+          "label": "Dates",
+          "type": "daterange",
+          "source": "",
+          "defaultValue": { "to": "", "from": "" },
+          "mandatory": false
+        }
+      ]
+    }
+  ]
+}
+```
+
+When this component is used inside workflow user actions, keep the strict contract:
+- Set explicit `eventName` (do not infer from `label`)
+- Keep `context` and `attributes` to documented user-action fields only
+- Validate module visibility with `workflow.transitions` (`module` vs `module: "all"`)
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.field.filterComplex.md

@@ -0,0 +1,106 @@
+---
+alias: "fc.field.filterComplex"
+aliases:
+  - fc.field.filterComplex
+category: field
+module: Core
+---
+# fc.field.filterComplex
+
+Complex multi-condition filter builder that dynamically fetches and filters data via a configurable GraphQL query. Opens a modal dialog with form fields, search results, and chip-based selection.
+
+## When to Use
+- Entity search fields requiring multi-step filtering (e.g., product lookup, location search)
+- Forms where users must select entities from GraphQL query results
+- Advanced filter inputs with custom search result card layouts
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `value` | `string[]` | No | Array of pre-selected values |
+| `label` | string | No | Label for the main input field |
+| `extensions` | Extensions | No | Advanced configuration (query, result layout, selection behavior) |
+
+### Extensions Object
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `query` | string | **Yes** | GraphQL query for filtering data |
+| `filtersSource` | string | No | Data source for filter options |
+| `variables` | `Map<string, any>` | No | GraphQL query variables |
+| `overrides` | ExtendedFormField | No | Field-level customization (label, default value, component) |
+| `searchItemConfig` | MystiqueComponentInstance | **Yes** | Layout for search result items (Product Card or Standard Card) |
+| `chipItemConfig` | `{ label: string, query: string, variables: Map }` | **Yes** | Chip display label path and pre-selection query |
+| `onChangeValues` | OnChangeValues | **Yes** | Maps search item data to filter values |
+| `exclude` | `string[]` | No | Filter fields to hide (e.g., `["createdOn"]`) |
+| `mode` | `"single" \| "multiple"` | No | Selection mode. Default: `"multiple"` |
+| `selectionLimit` | number | No | Max selectable items (only for `"multiple"` mode) |
+| `displayColumns` | number | No | Number of form field columns. Default: `1` |
+| `modalDimension` | `"small" \| "medium"` | No | Modal window size. Default: `"small"` |
+
+### OnChangeValues Object
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `value` | string | No | Path to extract value from search item |
+| `variableName` | string | No | GraphQL variable name for the value |
+| `visibleItemsThreshold` | number | No | Min items shown before collapsing. Default: `2` |
+
+### ExtendedFormField (overrides)
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `component` | string | No | Alternate field component alias |
+| `source` | string | No | Setting name for dropdown/radio options |
+| `label` | string | No | Custom label (supports i18n) |
+| `value` | any | No | Lock field to a fixed value (hides field) |
+| `defaultValue` | any | No | Initial editable value |
+| `helperText` | string | No | Helper text alongside the field |
+| `options` | `Record<string, string>` | No | Value options for select/radio |
+| `sortPrefix` | string | No | Field position in form |
+
+## Data Binding
+The `query` in extensions defines the GraphQL query executed when the modal is opened and as filter fields change. `searchItemConfig` defines how results are displayed (typically via `fc.card.product` or `fc.card.attribute`). `chipItemConfig.query` runs an initial query to resolve labels for pre-selected values.
+
+## Descendants
+No.
+
+## Gotchas
+- Three required extension props: `query`, `searchItemConfig`, and `chipItemConfig` must all be configured.
+- Selected items display as chips at the top of the modal; items remain visible in results after selection.
+- When `mode: "single"`, output is a string; when `mode: "multiple"`, output is an array.
+- `selectionLimit` is ignored when mode is `"single"`.
+- Use `displayColumns: 2` or `3` for wider modals with many filter fields.
+
+## Manifest Example
+```json
+{
+  "component": "fc.field.filterComplex",
+  "props": {
+    "label": "Select Products",
+    "extensions": {
+      "query": "query products($ref: [String]) { variantProducts(ref: $ref) { edges { node { ref name } } } }",
+      "searchItemConfig": {
+        "component": "fc.card.product",
+        "props": { "title": "{{node.name}}" }
+      },
+      "chipItemConfig": {
+        "label": "node.name",
+        "query": "query getProduct($ref: [String]) { variantProducts(ref: $ref) { edges { node { ref name } } } }",
+        "variables": {}
+      },
+      "onChangeValues": {
+        "value": "node.ref",
+        "variableName": "ref"
+      },
+      "mode": "multiple",
+      "selectionLimit": 10,
+      "modalDimension": "medium",
+      "displayColumns": 2
+    }
+  }
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.field.intrange.md

@@ -0,0 +1,82 @@
+---
+alias: "fc.field.intrange"
+aliases:
+  - fc.field.intrange
+  - intrange
+category: field
+module: Core
+---
+# fc.field.intrange
+
+Integer range (min/max) input field with popup for entering minimum and maximum values. Supports partial ranges and negative numbers.
+
+## When to Use
+- Filter forms requiring numeric range input (e.g., quantity range, price range)
+- Workflow user actions needing integer range parameters
+- List/table filters for numeric columns
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `value` | `{ from?: number, to?: number }` | No | Current range values. Supports negative numbers. |
+| `defaultValue` | `{ from?: number, to?: number }` | No | Initial range (workflow configuration). Can be partial. |
+| `name` | string | No | Field name in the form |
+| `label` | string | No | Field label (supports i18n keys) |
+| `mandatory` | boolean | No | Whether the field is required |
+
+## Data Binding
+In workflow configuration, use `defaultValue` to set the initial range. The property supports flexible configuration:
+- Both values: `{ from: 1, to: 100 }`
+- Only minimum: `{ from: 1 }`
+- Only maximum: `{ to: 100 }`
+- No values: `{}` or omit `defaultValue` entirely
+
+### Workflow Contract Properties
+`name`, `label`, `type`, `source`, `value`, `options`, `defaultValue`, `mandatory`
+
+## Descendants
+No.
+
+## Gotchas
+- The input displays the current range as a formatted string. Clicking opens a popup with two input fields.
+- Both `from` and `to` are optional -- partial ranges are valid.
+- Negative values are supported.
+- Clear resets fields to empty; Cancel restores initial values and closes; Apply confirms and closes.
+
+## Manifest Example
+```json
+{
+  "userActions": [
+    {
+      "eventName": "ApplyQuantityFilter",
+      "context": [
+        {
+          "label": "Filter by Quantity",
+          "type": "SECONDARY",
+          "modules": ["adminconsole"]
+        }
+      ],
+      "attributes": [
+        {
+          "name": "quantityRange",
+          "label": "Quantity Range",
+          "type": "intrange",
+          "defaultValue": { "from": 0, "to": 1000 },
+          "mandatory": false
+        }
+      ]
+    }
+  ]
+}
+```
+
+When this component is used inside workflow user actions, keep the strict contract:
+- Set explicit `eventName` (do not infer from `label`)
+- Keep `context` and `attributes` to documented user-action fields only
+- Validate module visibility with `workflow.transitions` (`module` vs `module: "all"`)
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.field.multistring.md

@@ -0,0 +1,50 @@
+---
+alias: "fc.field.multistring"
+aliases:
+  - fc.field.multistring
+category: field
+module: Core
+---
+# fc.field.multistring
+
+Multi-value string input that converts free-text entries into individual chips. Supports context search (partial match) and exact search (strict match) modes, with automatic duplicate removal.
+
+## When to Use
+- Filter forms requiring multiple search terms (e.g., multi-ref search, multi-SKU lookup)
+- Any input where users need to enter several string values as tags/chips
+- Bulk search interfaces for order refs, product refs, or tracking numbers
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `exactSearch` | boolean | No | When `true`, enforces exact case-sensitive matching. Default: `false` (context/partial search). |
+| `visibleItemsThreshold` | number | No | Minimum chips shown before excess collapses into dropdown. Default: `2` |
+
+## Data Binding
+The component outputs an array of string values. Each entered value becomes a chip. Duplicates are automatically removed. Leading/trailing spaces are trimmed. Empty strings are ignored.
+
+## Descendants
+No.
+
+## Gotchas
+- Two search modes: Context Search (default, partial matching) and Exact Search (set `exactSearch: true`, strict case-sensitive matching).
+- Duplicate entries are silently removed -- the component ensures unique values only.
+- Empty strings and whitespace-only entries are rejected.
+- Clear removes all chips; Cancel restores initial values; Apply finalizes selection.
+
+## Manifest Example
+```json
+{
+  "component": "fc.field.multistring",
+  "props": {
+    "exactSearch": false,
+    "visibleItemsThreshold": 3
+  }
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.filterPanel.md

@@ -0,0 +1,53 @@
+---
+alias: "fc.filterPanel"
+aliases:
+  - fc.filterPanel
+category: filter
+module: Core
+---
+# fc.filterPanel
+
+Collapsible filter panel that generates search/filter UI from data source or config. Connects to `fc.list` to filter results.
+
+## When to Use
+- Any list page that needs search/filter functionality
+- Paired with `fc.list` for filtered entity lists
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `filtersSource` | string | No | Prefix for auto-detected filter variables from the page query (e.g., `"orders"` matches `orders_status`, `orders_ref`, etc.) |
+| `query` | string | No | Custom GraphQL query -- filter fields are extracted from the query's variable definitions instead of the page query |
+| `variables` | Record<string, any> | No | Query variables -- supports template strings |
+| `noCard` | boolean | No | Remove card styling |
+| `overrides` | Record<string, ExtendedFormField> | No | Per-field customization keyed by field name. Supports `inputTemplate`, `outputTemplate`, `label`, `component`, `defaultValue`, `multiple`, `sortPrefix` |
+| `exclude` | string[] | No | Hide specific filter fields by name |
+| `additionalFields` | MystiqueComponentInstance[] | No | Extra filter field components to append |
+| `allowReadWriteUrlParams` | boolean | No | Sync filters with URL query parameters for shareable filtered views |
+
+## Descendants
+Yes — typically `fc.list` as a child.
+
+## Gotchas
+- **Filter fields are auto-detected from the GraphQL query's variable definitions** -- the panel introspects the page query AST (or custom `query` prop) and generates form fields for each variable matching the `filtersSource` prefix. Pagination variables (`first`, `last`, `before`, `after`, `workflowRef`, `workflowVersion`) are excluded by default
+- URL param sync lets users share filtered views via URL
+- **`inputTemplate` / `outputTemplate` transform system**: Set via `overrides` per field. `outputTemplate` transforms the field value before sending it as a query variable (e.g., `outputTemplate: '{"ref": "{{value}}"}'` wraps the user input into an object). `inputTemplate` does the reverse when reading from URL params (e.g., `inputTemplate: '{{ref}}'` extracts the ref from a URL param). Templates receive `{{ value }}` (current field value) and `{{ values }}` (all field values)
+- `defaultValue` in overrides supports `{{settings.settingName}}` syntax to load initial values from Fluent settings
+- Filter field labels are auto-generated from variable names using i18n lookup: `fc.gql.<entity>.<field>.label` -> fallback to capitalized field name
+
+## Manifest Example
+```json
+{
+  "component": "fc.filterPanel",
+  "props": { "allowReadWriteUrlParams": true },
+  "descendants": [
+    { "component": "fc.list", "props": { "dataSource": "orders", "attributes": [] } }
+  ]
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.json.editor.md

@@ -0,0 +1,22 @@
+---
+alias: "fc.json.editor"
+aliases:
+  - fc.json.editor
+  - fc.attribute.jsoneditor
+category: content
+module: Core
+---
+# fc.json.editor
+
+Editable JSON field with syntax highlighting and validation.
+
+## When to Use
+- Editing entity attributes as JSON
+- Settings value editing
+- Advanced configuration forms
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.json.viewer.md

@@ -0,0 +1,21 @@
+---
+alias: "fc.json.viewer"
+aliases:
+  - fc.json.viewer
+category: content
+module: Core
+---
+# fc.json.viewer
+
+Read-only formatted JSON display with syntax highlighting.
+
+## When to Use
+- Viewing entity attributes as raw JSON
+- Debug/inspection views
+- API response previews
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.list.customAction.md

@@ -0,0 +1,79 @@
+---
+alias: "fc.list.customAction"
+aliases:
+  - fc.list.customAction
+category: content
+module: Core
+---
+
+# fc.list.customAction
+
+List component with custom action support, enabling row selection and custom action callbacks instead of workflow-driven user actions.
+
+## When to Use
+- Display a data list where a custom action button operates on selected rows
+- Build bulk-action UIs where users select rows and trigger a callback function
+- Replace `fc.list` when you need programmatic action handling instead of workflow user actions
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `defaultPageSize` | number | Yes | Number of rows per page |
+| `attributes` | ListColumn[] | Yes | Column definitions (same as `fc.list`) |
+| `density` | DensityToggle | No | `{ toggle?: boolean, initial?: "compressed" \| "standard" }` -- row density controls |
+| `rowsPerPageOptions` | number[] | No | Available page size options (e.g. `[10, 25, 50]`) |
+| `actions` | boolean | No | Enable/disable the custom action feature |
+| `action` | CustomActionProp | No | `{ fn: (selectedRows) => void, label: string }` -- the custom action callback and button label |
+| `filter` | ListFilterConfig | No | Filter configuration including `memoryFilter` for client-side filtering |
+| `title` | string | No | Card title |
+| `width` | CardWidth | No | Card width on 12-column grid |
+| `highlight` | string | No | Top border highlight color |
+
+### CustomActionProp Structure
+| Field | Type | Description |
+|-------|------|-------------|
+| `fn` | `(selectedRows: RowSelection[]) => void` | Callback invoked with selected rows when the action button is clicked |
+| `label` | string | Button label for the custom action |
+
+## Data Binding
+Same as `fc.list` -- uses `dataSource` to bind to a GraphQL connection. Data is passed via the `data` prop from the parent data context.
+
+## Descendants
+No -- self-contained list component. Column content is configured via `attributes`.
+
+## Composition Patterns
+- `fc.page` > `fc.list.customAction` for bulk-operation list pages
+- `fc.card.multi` > `fc.list.customAction` for embedded action lists
+
+## Gotchas
+- The `action` prop is only shown when `actions` is truthy. If `actions` is falsy, the action button is hidden.
+- Unlike `fc.list`, this component uses `CustomActionProp` (a callback function) rather than workflow `UserAction` lookups.
+- Row selection state can be externally controlled via `selectedRows` and `setSelectedRows` props for parent-managed selection.
+- Shares the same underlying `ListView` rendering as `fc.list` -- visual output is identical.
+
+## Manifest Example
+```json
+{
+  "component": "fc.list.customAction",
+  "dataSource": "fulfilments",
+  "props": {
+    "defaultPageSize": 10,
+    "actions": true,
+    "action": {
+      "label": "Process Selected",
+      "fn": "handleProcessSelected"
+    },
+    "attributes": [
+      { "label": "Ref", "value": "{{node.ref}}" },
+      { "label": "Status", "value": "{{node.status}}" },
+      { "label": "Type", "value": "{{node.type}}" }
+    ]
+  }
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.list.md

@@ -0,0 +1,116 @@
+---
+alias: "fc.list"
+aliases:
+  - fc.list
+  - shared.components.material.DynamicList
+category: content
+module: Core
+---
+# fc.list
+
+Paginated data table with sorting, filtering, row links, bulk actions, and optional row expansion.
+
+## When to Use
+- Any entity list page (orders, fulfilments, locations, inventory)
+- Entity detail tabs showing child items (order items, fulfilment items)
+- Any tabular data display
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `attributes` | ListColumn[] | **Yes** | Column definitions: `[{ label, value, align, hideBelow }]` |
+| `defaultPageSize` | number | Recommended | Rows per page (default: 10) |
+| `title` | string | No | Card title above table |
+| `rowLink` | string | No | **DEPRECATED** -- prefer `row: { link: "..." }`. Template for row click navigation: `"/orders/{{id}}"` |
+| `filter` | ListFilterConfig | No | Enable inline filtering: `{ enabled: boolean, exclude?: string[], source?, entityType?, memoryFilter?, overrides? }` |
+| `actions` | boolean | No | Enable bulk action row selection (header checkbox) |
+| `density` | DensityToggle | No | Row density: `{ toggle?: boolean, initial?: "compressed" \| "standard" }` |
+| `responsiveness` | string | No | `"table"`, `"card"`, `"forcecard"` -- mobile adaptation |
+| `rowsPerPageOptions` | number[] | No | Pagination options: `[10, 25, 50, 100]` |
+| `row` | ListRowConfig | No | Row configuration (see ListRowConfig below) |
+
+### ListRowConfig
+
+| Prop | Type | What it controls |
+|------|------|------------------|
+| `link` | string | Template for row click navigation: `"/orders/{{node.id}}"` (preferred over top-level `rowLink`) |
+| `expansion` | Descendants or `{ descendants, toggle }` | Component(s) to render below each row when expanded. `toggle: true` shows expand/collapse icon |
+| `actions` | CardActions | Action buttons at end of each row (see CardActions below) |
+
+### CardActions (applies to `row.actions` and `cardActions`)
+
+| Prop | Type | What it controls |
+|------|------|------------------|
+| `primary` | CardAction[] | Visible action buttons |
+| `secondary` | CardAction[] | Actions grouped under "More" dropdown |
+| `showAtLeast` | number | Primary actions to keep visible on mobile (default 0 — all collapse) |
+
+CardAction types: `{ "type": "userAction", "name": "<rulesetName>", "label": "i18n:key", "condition": "{{template}}" }`. Workflow-defined user actions are auto-appended — only add when reordering or conditionally hiding.
+| `vAlign` | string | No | Vertical alignment of row content: `"top"`, `"centre"`, `"center"`, `"middle"`, `"bottom"` |
+| `hidePagination` | boolean | No | Hide the pagination controls entirely |
+| `loading` | string | No | Template string evaluated to `"true"`/`"false"` to show loading skeleton |
+| `noRecordKey` | string | No | i18n key for the empty-state message (default: `"fc.mystique.table.noRecords"`) |
+| `rowId` | string | No | JSONPath to a unique row identifier field for DOM `id` attributes |
+| `collapseExpansionPadding` | boolean | No | Remove padding around row expansion content |
+| `collapseAppendPadding` | boolean | No | Remove padding for appended column content |
+| `barcode` | ListBarcodeConfig | No | Barcode scanner integration: `{ enabled: boolean, match: string, action?: Action }` |
+| `highlight` | string | No | Card border highlight color (theme color key or CSS color) |
+| `width` | CardWidth | No | Card width (quarter/third/half/full or 1-12) |
+| `cardActions` | PageActionsProps | No | Action buttons in the card header |
+
+### Column Props (ListColumn)
+| Prop | Type | What it controls |
+|------|------|------------------|
+| `label` | string | Column header text |
+| `value` | string | Template string for cell content |
+| `align` | string | Text alignment: `"left"`, `"centre"`, `"center"`, `"right"` |
+| `hideBelow` | breakpoint | Hide column below breakpoint: `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"` |
+| `hideAbove` | breakpoint | Hide column above breakpoint: `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"` |
+| `enableCopyIcon` | string | Show copy-to-clipboard icon: `"displayAlways"` or `"displayOnHover"` |
+| `append` | boolean | Append this column's content to the previous column in card view |
+| `cardAction` | boolean | Render this column as a card action in responsive card mode |
+
+## Data Binding
+**Requires `dataSource`** — JSONPath to a connection or array. E.g., `"orders"`, `"orderById.items.edges"`. Column values use `{{node.fieldName}}` for row data access.
+
+## Descendants
+Optional — used for row expansion content.
+
+## Composition Patterns
+- `fc.page` > `fc.filterPanel` + `fc.list` for filtered list page
+- `fc.tabs.card` > `fc.list` per tab for detail page
+- `fc.list` with `rowLink` for master-detail navigation
+
+## Gotchas
+- **Must have `dataSource`** -- without it, table renders empty
+- Column `value` uses `{{node.field}}` not `{{field}}` when in a connection
+- Don't nest `fc.provider.graphql` inside `fc.list` -- pagination conflict
+- `hideBelow: "md"` hides column on mobile
+- **`rowLink` is deprecated** -- use `row: { link: "/orders/{{node.id}}" }` instead. `rowLink` still works but will be removed in a future version
+- `loading` is a template string (e.g., `"{{isLoading}}"`) that must evaluate to the string `"true"` to activate, not a boolean
+
+## Validation Rules
+P01 (CRITICAL — attributes required), P02 (defaultPageSize), P03 (attribute labels), P04 (CRITICAL — dataSource required), T04 (rowLink template valid)
+
+## Manifest Example
+```json
+{
+  "component": "fc.list",
+  "props": {
+    "dataSource": "orders",
+    "defaultPageSize": 25,
+    "rowLink": "/orders/{{node.id}}",
+    "attributes": [
+      { "label": "Ref", "value": "{{node.ref}}" },
+      { "label": "Status", "value": "{{node.status}}" },
+      { "label": "Created", "value": "{{dateFormat node.createdOn 'MMM DD, YYYY'}}" }
+    ]
+  }
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.