@fluentcommerce/ai-skills 0.1.0 → 0.3.0

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

@@ -0,0 +1,64 @@
+---
+alias: "fc.page"
+aliases:
+  - fc.page
+  - shared.components.material.DynamicPage
+category: page
+module: Core
+---
+# fc.page
+
+Top-level page container with header, breadcrumb navigation, and automatic workflow user actions.
+
+## When to Use
+- Every page in a manifest (required as root component)
+- When you need workflow-driven action buttons in the header
+- When you need breadcrumb back-navigation
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `title` | string | Recommended | Header text -- supports template strings `"Order {{ref}}"` |
+| `backButtons` | BreadCrumb[] | No | Breadcrumb navigation links `[{ label, path, menuLabel? }]` |
+| `actions` | PageActionConfig / boolean | No | User actions config -- `true` for auto-discovery, object for custom `{ primary?, secondary?, userActionFilter?, userActionExtensions? }` |
+| `tabs` | TabInfo[] | No | Page-level tab bar (different from `fc.tabs.card`) |
+| `hideRefreshButton` | boolean | No | **DEPRECATED** -- the refresh button has been moved to the global header and is always displayed. This prop is accepted but has no effect |
+
+## Data Binding
+Page-level `data.query` in the route definition provides the data context for all descendants. Variables support template strings: `{ "id": "{{params.id}}", "retailerId": "{{activeRetailer.id}}" }`
+
+## Descendants
+Yes — accepts any component as children. Uses Material-UI Grid internally.
+
+## Composition Patterns
+- `fc.page` > `fc.column` + `fc.column` for multi-column layouts
+- `fc.page` > `fc.tabs.card` for tabbed content
+- `fc.page` > `fc.list` for entity list pages
+
+## Gotchas
+- Actions prop set to `true` auto-discovers workflow actions -- set to `false` or omit for read-only pages
+- Page-level tabs are different from `fc.tabs.card` -- page tabs create URL segments, card tabs are visual only
+- `hideRefreshButton` is deprecated and has no effect -- the refresh button is now in the global header
+- `fullScreen` is NOT a prop on `fc.page` -- it is a route-level property set on the page definition in the manifest (e.g., `{ "path": "/scanner", "fullScreen": true, "component": "fc.page", ... }`). It collapses the sidebar navigation
+
+## Validation Rules
+P15 (title recommended), P16 (component should be fc.page), S09 (every page needs component field)
+
+## Manifest Example
+```json
+{
+  "component": "fc.page",
+  "props": {
+    "title": "Order {{ref}}",
+    "backButtons": [{ "label": "Orders", "path": "/orders" }],
+    "actions": true
+  },
+  "descendants": []
+}
+```
+
+## 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.page.refresh.md

@@ -0,0 +1,48 @@
+---
+alias: "fc.page.refresh"
+aliases:
+  - fc.page.refresh
+category: page
+module: Core
+---
+
+# fc.page.refresh
+
+Auto-refresh timer that reloads the current page data at a configurable interval.
+
+## When to Use
+- Auto-refresh a dashboard or monitoring page on a timer
+- Keep a pick/pack or fulfilment page updated without manual refresh
+- Show a loading spinner with optional label while waiting for the next refresh cycle
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `interval` | number | Yes | Refresh interval in seconds. Minimum enforced is 10 -- values below 10 are clamped to 10. |
+| `displaySpinner` | boolean | No | When `true`, renders a centered loading spinner (and optional label) between refreshes |
+| `label` | string \| TypedDynamicAttribute | No | Text or dynamic attribute shown below the spinner. Strings render directly; objects use `DynamicValue`. |
+| `data` | any | No | Data context for resolving dynamic `label` attributes |
+
+## Gotchas
+- The minimum interval is 10 seconds. Setting `interval` to less than 10 (or omitting it) silently defaults to 10.
+- Calls `refreshPage()` which re-fetches all page-level queries -- use sparingly on pages with heavy data.
+- The timer is set once on mount and does not re-initialize if `interval` changes (empty dependency array in `useEffect`).
+- When `displaySpinner` is `false` or omitted, this component renders nothing visible -- it only triggers the background timer.
+
+## Manifest Example
+```json
+{
+  "component": "fc.page.refresh",
+  "props": {
+    "interval": 30,
+    "displaySpinner": true,
+    "label": "Auto-refreshing every 30 seconds..."
+  }
+}
+```
+
+## 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.page.section.column.md

@@ -0,0 +1,71 @@
+---
+alias: "fc.page.section.column"
+aliases:
+  - fc.page.section.column
+  - fc.column
+category: layout
+module: Core
+---
+# fc.page.section.column
+
+Compatibility alias for `fc.column` used in page-section layout manifests.
+
+## One-line Description
+Defines a column container within page section layouts, using the same behavior as `fc.column`.
+
+## When to Use
+- Legacy manifests that reference `fc.page.section.column`
+- Grid-based page sections where components are arranged by columns
+- Backward-compatible layout migrations to canonical aliases
+
+## Key Props
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| xs | number | No | Width on extra-small breakpoints |
+| sm | number | No | Width on small breakpoints |
+| md | number | No | Width on medium breakpoints |
+| lg | number | No | Width on large breakpoints |
+| xl | number | No | Width on extra-large breakpoints |
+| className | string | No | Additional CSS classes |
+
+## Data Binding
+Primarily structural layout component; binds child components rather than business data fields.
+
+## Descendants
+Yes. Supports nested content components.
+
+## Composition Patterns
+- Commonly nested under `fc.page.section`.
+- Use multiple columns to compose responsive cards, fields, and action clusters.
+- Prefer `fc.column` for newly authored manifests.
+
+## Gotchas
+- Column widths should be coordinated across siblings to avoid overflow.
+- Alias and canonical component are functionally equivalent.
+
+## Validation Rules
+- Breakpoint width props should be valid grid values for the active theme/system.
+
+## Manifest Example
+```json
+{
+  "component": "fc.page.section.column",
+  "props": {
+    "md": 6
+  },
+  "descendants": [
+    {
+      "component": "fc.card.attribute",
+      "props": {
+        "title": "Details"
+      }
+    }
+  ]
+}
+```
+
+## 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.page.section.header.md

@@ -0,0 +1,61 @@
+---
+alias: "fc.page.section.header"
+aliases:
+  - fc.page.section.header
+category: layout
+module: Core
+---
+
+# fc.page.section.header
+
+Section header bar with an optional icon, title text, and right-aligned action buttons rendered from descendants.
+
+## When to Use
+- Display a titled header above a group of components within a page section
+- Add icon + title branding to a section
+- Place action buttons (descendants) aligned to the right of the header row
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `title` | string | Yes | Header text -- supports template strings `"{{status}}"` via TemplateRenderer |
+| `icon` | string | No | Material icon name (e.g. `"MdInfo"`, `"MdLocalShipping"`) rendered left of the title via `getIcon()` |
+| `data` | any | No | Data context passed to `TemplateRenderer.parse()` for resolving template strings in `title` |
+
+## Descendants
+Yes -- descendants are rendered as action buttons in a horizontal `Grid` to the right of the title. Each child is wrapped in a `<Grid item>`.
+
+## Composition Patterns
+- `fc.page.section` > `fc.page.section.header` + content components
+- `fc.page.section.header` > `fc.drawer.button` or `fc.modal.button` as action descendants
+- `fc.column` > `fc.page.section.header` + content components for titled sections
+
+## Gotchas
+- The `title` prop is required; without it (and no icon) the header still renders but shows an empty container.
+- Template strings in `title` are resolved via `TemplateRenderer.parse()` using the `data` prop as context.
+- Descendants render right-aligned in the header bar, not below the title.
+- Different from `fc.page.section` which is an invisible grouping container -- this component has visible chrome.
+- Registered with category `content` in the component registry.
+
+## Manifest Example
+```json
+{
+  "component": "fc.page.section.header",
+  "props": {
+    "title": "Fulfilment Details",
+    "icon": "MdLocalShipping"
+  },
+  "descendants": [
+    {
+      "component": "fc.drawer.button",
+      "props": { "label": "Edit" }
+    }
+  ]
+}
+```
+
+## 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.page.section.md

@@ -0,0 +1,59 @@
+---
+alias: "fc.page.section"
+aliases:
+  - fc.page.section
+category: layout
+module: Core
+---
+
+# fc.page.section
+
+Transparent grouping container that renders all descendants without any visual wrapper.
+
+## When to Use
+- Group related components into a logical section within a page
+- Organize page layout without adding visual card boundaries
+- Pair with `fc.page.section.header` for a titled section
+- Wrap multiple descendants into a single logical unit inside tabs or list column components
+
+## Key Props
+
+This component has no props of its own. The source code is `export const Section = () => <Children />;` -- a pure pass-through container.
+
+## Descendants
+Yes -- accepts any component as children. All descendants are rendered directly without wrapping markup.
+
+## Composition Patterns
+- `fc.page` > `fc.page.section` > `fc.page.section.header` + child components
+- `fc.page` > `fc.page.section` > `fc.card.attribute` + `fc.list`
+- `fc.tabs.card` > `fc.page.section` per tab for grouped content
+- `fc.list` column `type: "component"` > `fc.page.section` > multiple child components
+- Use `fc.page.section.column` (alias for `fc.column`) within a section for column layout
+
+## Gotchas
+- This component renders zero DOM of its own -- it delegates entirely to `<Children />`. If you need a visual card boundary use `fc.card.attribute` or `fc.card.multi` instead.
+- Easily confused with `fc.page.section.header` which adds a visible title bar with icon.
+- Registered with category `content` in the component registry despite being a structural grouping element.
+
+## Manifest Example
+```json
+{
+  "component": "fc.page.section",
+  "descendants": [
+    {
+      "component": "fc.page.section.header",
+      "props": { "title": "Details", "icon": "MdInfo" }
+    },
+    {
+      "component": "fc.card.attribute",
+      "props": { "title": "Order Info" }
+    }
+  ]
+}
+```
+
+## 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.page.wizard.md

@@ -0,0 +1,45 @@
+---
+alias: "fc.page.wizard"
+aliases:
+  - fc.page.wizard
+category: page
+module: Core
+---
+# fc.page.wizard
+
+Multi-step wizard page with linear progression and step tracking.
+
+## When to Use
+- Multi-step entity creation (create order, configure sourcing)
+- Complex configuration workflows
+- Guided setup processes
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `steps` | StepConfig[] | **Yes** | Step definitions with labels |
+| `title` | string | No | Wizard page title |
+
+## Data Binding
+Each step can have its own form state. Final step typically submits a mutation.
+
+## Descendants
+Yes — each step's content (matched by index, like `fc.tabs.card`).
+
+## Manifest Example
+```json
+{
+  "component": "fc.page.wizard",
+  "props": {
+    "title": "Create Order",
+    "steps": [{ "label": "Order Details" }, { "label": "Items" }, { "label": "Review" }]
+  },
+  "descendants": []
+}
+```
+
+## 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.page.wizard.summary.md

@@ -0,0 +1,56 @@
+---
+alias: "fc.page.wizard.summary"
+aliases:
+  - fc.page.wizard.summary
+category: page
+module: Core
+---
+
+# fc.page.wizard.summary
+
+Summary panel for `fc.page.wizard` that displays the wizard's summary content as a sidebar or inline card.
+
+## When to Use
+- Show a running summary alongside wizard steps (e.g. order totals, selected items)
+- Create a sticky sidebar that follows the user as they scroll through wizard steps
+- Display wizard summary content outside the step flow
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `width` | CardWidth (`"quarter"` / `"third"` / `"half"` / `"two-thirds"` / `"full"` / number 1-12) | No | Width on 12-column grid. Default `12`. |
+| `noCard` | boolean | No | When `true`, renders summary content without the Material-UI Card wrapper |
+| `sticky` | boolean | No | When `true`, makes the summary panel stick to the top of the viewport as the user scrolls |
+
+## Data Binding
+Reads summary content from `WizardContext` -- the `summary` field is set by the parent `fc.page.wizard` component. This component does not accept its own data query.
+
+## Composition Patterns
+- `fc.page.wizard` > `fc.page.wizard.summary` + wizard step descendants
+- Place the summary as a sibling to wizard steps at the same level within the wizard
+
+## Gotchas
+- Must be a descendant of `fc.page.wizard` -- it reads from `WizardContext` which is only available inside a wizard.
+- The `sticky` prop uses CSS `position: sticky` with a negative top offset. This may not work inside overflow containers.
+- Named widths (e.g. `"third"`) are resolved via the shared `NamedWidths` map. Invalid values default to 12.
+- Registered with category `content` in the component registry.
+
+## Manifest Example
+```json
+{
+  "component": "fc.page.wizard",
+  "props": { "title": "Create Order" },
+  "descendants": [
+    {
+      "component": "fc.page.wizard.summary",
+      "props": { "width": "third", "sticky": true }
+    }
+  ]
+}
+```
+
+## 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.progress.circular.md

@@ -0,0 +1,20 @@
+---
+alias: "fc.progress.circular"
+aliases:
+  - fc.progress.circular
+category: content
+module: Core
+---
+# fc.progress.circular
+
+Circular progress visualization showing completion percentages.
+
+## When to Use
+- Fulfilment pick/pack completion
+- Order processing progress
+
+## 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.provider.graphql.md

@@ -0,0 +1,71 @@
+---
+alias: "fc.provider.graphql"
+aliases:
+  - fc.provider.graphql
+category: content
+module: Core
+---
+# fc.provider.graphql
+
+Execute an additional GraphQL query and provide results as data context for descendants.
+
+## When to Use
+- Load related entity data not in the page query
+- Fetch locations, inventory, or reference data
+- Secondary queries that don't fit in the primary page query
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `query` | string (GraphQL) | **Yes** | GraphQL query string |
+| `path` | string | **Yes** | Path to the data root in the query response. If the path points to a connection, auto-paginates. E.g., `"locationById"`, `"orders"` |
+| `variables` | Record<string, any> | No | Query variables -- supports template strings |
+| `max` | number | No | Max records to fetch when auto-paginating (default: 1000, **hardcoded cap: 1000** -- values above 1000 are clamped) |
+| `loadingBehavior` | string | No | `"wait"`, `"wait-with-animation"`, `"pass-immediately"` (default) |
+| `toastMessages` | object | No | Override toast messages: `{ maxResultsReached?: string }` -- custom warning when max record limit is hit |
+
+## Data Binding
+Query results become the data context for descendants. Variables can reference parent data: `{ "id": "{{fulfilment.location.id}}" }`.
+
+**Implicit template variables** available in `variables` templates: `{{activeContext.id}}`, `{{activeLocation.id}}`, `{{activeRetailer.id}}`, `{{activeUser.username}}`, `{{params.id}}` (route params), plus all parent data fields.
+
+## Descendants
+Yes — receive the provider's query results as their data context.
+
+## Composition Patterns
+- `fc.provider.graphql` > `fc.card.attribute` (show location details)
+- `fc.provider.graphql` > `fc.list` (show related entities)
+
+## Gotchas
+- **Do NOT nest inside `fc.list`** -- both compete for pagination, causes conflicts
+- Query is a string, not gql tagged template
+- Variables are rendered as templates before query execution
+- `loadingBehavior: "wait"` blocks rendering until ALL pages are fetched
+- **Implicit `dataProviderState`** is passed to all descendants as part of the data context. Values: `"loading"`, `"ok"`, `"error"`, `"max"`. Use in conditionals: `"{{dataProviderState}}"` matches `"ok"` to show content only after data loads
+- `max` is clamped to 1000 even if you specify a higher value (`Math.min(max, 1000)`)
+- When the max record limit is reached, a toast warning is shown automatically (customizable via `toastMessages.maxResultsReached`)
+
+## Validation Rules
+P09 (CRITICAL — query required), D01 (valid GraphQL), D06 (query must be defined)
+
+## Manifest Example
+```json
+{
+  "component": "fc.provider.graphql",
+  "props": {
+    "query": "query location($id: ID!) { locationById(id: $id) { id ref name } }",
+    "path": "locationById",
+    "variables": { "id": "{{fulfilment.fromLocation.id}}" },
+    "loadingBehavior": "wait"
+  },
+  "descendants": [
+    { "component": "fc.card.attribute", "props": { "title": "Location", "attributes": [{ "label": "Name", "value": "{{locationById.name}}" }] } }
+  ]
+}
+```
+
+## 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.quantity.list.md

@@ -0,0 +1,87 @@
+---
+alias: "fc.quantity.list"
+aliases:
+  - fc.quantity.list
+category: content
+module: Core
+---
+
+# fc.quantity.list
+
+Specialized list component that combines a standard data list with an integrated quantity selector column and optional barcode scanner/filter.
+
+## When to Use
+- Pick/pack workflows where items need quantity input per row
+- Any list where each row requires a quantity adjustment control
+- Store module wave picking, fulfilment packing, or inventory count UIs
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `attributes` | TranslatableAttribute[] | Yes | Column definitions (same as `fc.list` but with translatable labels) |
+| `defaultPageSize` | number | Yes | Number of rows per page (inherited from StandardListProps) |
+| `quantitySelectorProps` | Partial\<QuantitySelectorComponentProps\> | No | Configuration for the quantity selector rendered in each row |
+| `quantitySelectorAttribute` | Partial\<TranslatableAttribute\> | No | Override the label, alignment, or other column props for the quantity selector column |
+| `scannerProps` | ScannerContract | No | Props passed to the `fc.scanner.barcodeFilter` component rendered above the list |
+| `rowsPerPageOptions` | number[] | No | Available page size options |
+| `title` | string | No | Card title |
+| `width` | CardWidth | No | Card width on 12-column grid |
+| `highlight` | string | No | Top border highlight color |
+| `filter` | ListFilterConfig | No | List filter configuration |
+
+## Data Binding
+Same as `fc.list` -- uses `dataSource` to bind to a GraphQL connection. The quantity selector column is automatically appended to the `attributes` array.
+
+## Descendants
+No -- self-contained list component. Column content is configured via `attributes`.
+
+## Composition Patterns
+- `fc.page` > `fc.quantity.list` for pick/pack item lists
+- `fc.page.wizard` step > `fc.quantity.list` for wizard-driven quantity input
+- Often used with `scannerProps` to enable barcode filtering above the list
+
+## Gotchas
+- The quantity selector column is automatically appended as the last column with `type: "component"` pointing to `fc.util.quantitySelector`. You do not need to include it in `attributes`.
+- The quantity selector column defaults to label `"Quantity"` (i18n key `fc.mystique.list.column.quantity.label`) and `align: "center"`. Override via `quantitySelectorAttribute`.
+- When `scannerProps` is provided, the `fc.scanner.barcodeFilter` component is rendered above the list. If not provided, no scanner appears.
+- When the scanner is active, the "no records" message uses i18n key `fc.barcodeFilter.list.noRecords` instead of the default.
+- All attribute labels are passed through `prefixedTranslate` for i18n resolution, and string values in attributes are recursively translated.
+- Registered with category `content` in the component registry.
+
+## Manifest Example
+```json
+{
+  "component": "fc.quantity.list",
+  "dataSource": "waveItems",
+  "props": {
+    "defaultPageSize": 50,
+    "attributes": [
+      {
+        "label": "i18n:fc.mystique.product.name",
+        "value": "{{node.product.name}}"
+      },
+      {
+        "label": "i18n:fc.mystique.product.ref",
+        "value": "{{node.product.ref}}"
+      },
+      {
+        "label": "i18n:fc.mystique.product.barcode",
+        "value": "{{node.product.gtin}}"
+      }
+    ],
+    "quantitySelectorProps": {
+      "max": "{{node.quantity}}",
+      "min": 0
+    },
+    "scannerProps": {
+      "placeholderText": ["fc.barcodeFilter.placeholder", "Scan barcode..."]
+    }
+  }
+}
+```
+
+## 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.repeater.md

@@ -0,0 +1,56 @@
+---
+alias: "fc.repeater"
+aliases:
+  - fc.repeater
+category: layout
+module: Core
+---
+# fc.repeater
+
+Iterate over array data, rendering descendants once per item with per-item data context.
+
+## When to Use
+- Fulfilment choices in a MULTI order (each with its own card)
+- Order items with complex per-item detail views
+- Any array where each item needs a rich component tree (not just a table row)
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `dataSource` | string (JSONPath) | **Yes** | Path to array or connection, e.g., `"order.fulfilmentChoices.edges"` |
+
+## Data Binding
+Each iteration's data context is set to the current array item. **Auto-detects Relay connection format**: if the resolved data is an object with an `edges` array (`{ edges: [{ node: {...} }] }`), it automatically unwraps and iterates over `edges`. This means you can point `dataSource` at either a plain array OR a Relay connection object and it works the same way.
+
+## Descendants
+Yes (required) — rendered once per item.
+
+## Composition Patterns
+- `fc.repeater` > `fc.card.attribute` per item
+- `fc.repeater` > `fc.conditional` > type-specific content per item
+
+## Gotchas
+- Must have at least one descendant -- empty repeater is an error
+- For simple tabular data, use `fc.list` instead (better performance, pagination)
+- **Supports both plain arrays and Relay connection objects** -- if data has `{ edges: [...] }`, it iterates over `edges` automatically. You do NOT need to append `.edges` to the dataSource path if the data is a connection
+- When iterating a connection, each iteration's context is the edge object (typically `{ node: {...}, cursor: "..." }`) -- use `{{node.field}}` in descendant templates
+
+## Validation Rules
+P07 (CRITICAL — dataSource required), P08 (CRITICAL — needs descendants)
+
+## Manifest Example
+```json
+{
+  "component": "fc.repeater",
+  "props": { "dataSource": "orderById.fulfilmentChoices.edges" },
+  "descendants": [
+    { "component": "fc.card.attribute", "props": { "title": "FC: {{node.ref}}", "attributes": [{ "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.