@fluentcommerce/ai-skills 0.2.0 → 0.3.0

package/content/dev/skills/fluent-mystique-builder/SKILL.md

@@ -0,0 +1,1294 @@
+---
+name: fluent-mystique-builder
+description: Build and edit Mystique manifest JSON definitions. Create pages, routes, component trees, data queries, and fragment compositions using the v2.0 schema. Triggers on "build manifest", "create mystique page", "add route", "mystique component", "edit manifest", "build ui", "add page to manifest".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <operation> [manifest-file] [--page <path>] [--section <name>] [--fragment]
+---
+
+# Mystique Manifest Builder
+
+Create, edit, and validate Fluent Commerce Mystique manifest JSON definitions. Mystique is the declarative, manifest-driven UI framework that powers the OMX frontend. Manifests are JSON documents that define the entire application structure: routes, pages, component trees, GraphQL data queries, role-based visibility, template strings, and plugin references. This skill understands the v2.0 manifest schema end-to-end and generates structurally correct JSON that passes `/fluent-mystique-validate`.
+
+## Platform Fundamentals
+
+**OMX vs Mystique naming:** "OMX" (Order Management Experience) is the umbrella framework covering UX + Workflows + Connect. "Mystique" is the internal/historical code name for the UX Framework layer specifically. All import paths and code references use `mystique/` (e.g., `mystique/hooks/useAuth`, `mystique/registry`), while documentation uses "OMX" or "UX Framework" externally. Both refer to the same thing for frontend purposes.
+
+**Three registries:**
+- **ComponentRegistry** — standard display components (`fc.list`, `fc.card.attribute`, custom components)
+- **FieldRegistry** — form input components for user action attributes (auto-selected by type name)
+- **TemplateRegistry** — Handlebars helper functions for template string expressions
+
+**Configuration over code:** Most UI should be built via manifest JSON, not custom components. Only build custom components when: novel visualizations, drag-and-drop, external service integrations, real-time features, or interaction patterns not covered by user action forms. The framework is **versionless with guaranteed backward compatibility** — old configurations never break.
+
+**Multi-tenancy context:** Account → Retailer → Location. Manifests can be scoped at ACCOUNT level. User context (`activeRetailer`, `activeLocation`) is available in template strings for query variables and conditional rendering.
+
+**Workflow-UI integration:** User action buttons and forms appear automatically based on the entity's current workflow state. No manifest changes needed when workflows evolve — the UI adapts. Custom form field components are selected by matching the workflow `eventAttributes[].type` to FieldRegistry entries.
+
+## Planning Gate
+
+### Pre-flight: Plan Verification
+
+Before proceeding, check for an existing approved plan:
+
+1. **Search** `accounts/<PROFILE>/features/*/status.json` for an entry with `plan: "APPROVED"` that covers this UI work, OR check `accounts/<PROFILE>/tasks/` for a task plan with `Status: APPROVED`
+2. **If multi-artifact work** (manifest + SDK component + settings + workflows): STOP. Invoke `/fluent-feature-plan` first — this skill cannot be used for multi-artifact work without a feature plan
+3. **If approved plan found:** Skip to implementation, referencing the plan's UI/manifest sections
+4. **If manifest-only work with no plan:** Continue to the Planning Gate below to write a plan for this skill
+
+**Before creating or modifying any manifest JSON, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Every table row must carry a Source column (NEW/EXISTING/MODIFIED/REUSED/OOTB).
+
+**If this manifest change is part of a larger feature** (rules + workflows + UI), use `/fluent-feature-plan` first. Then reference the approved plan during implementation.
+
+**Manifest-builder specific emphasis — ensure these are covered:**
+
+1. **Wireframe (ASCII/Mermaid)** — layout sketch showing page structure and component hierarchy
+2. **Route table** — all routes with path, component, section, nav label, roles
+3. **Component tree** — hierarchical component layout per page (nested list or tree diagram)
+4. **Data requirements** — GraphQL queries needed per page with entity types and key fields
+5. **Settings dependencies** — fragment references (`settingName`), feature flags, plugin settings
+6. **i18n keys** — translatable strings requiring `i18n:` prefixed keys
+7. **Plugin references** — custom SDK components needed and their bundle URLs
+
+**Write the plan to:** `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-mystique-builder-<slug>.md`. Set `Status: PENDING`.
+
+Present the full plan content to the user and wait for approval before writing any manifest JSON. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
+
+## Post-Build: Manifest Validation
+
+After building or modifying any manifest JSON, **always recommend running `/fluent-mystique-validate`** to check for:
+- Schema compliance (manifestVersion, required fields, route types)
+- Component alias resolution (unknown `fc.*` aliases or custom components)
+- Data query syntax and dataSource path validity
+- Template string syntax (balanced `{{`/`}}`, valid helper names)
+- Cross-reference issues (homePath resolves, fragment settingName conventions)
+- Component prop completeness (fc.list needs attributes, fc.conditional needs value/matches)
+
+If the user skips this step, `/fluent-pre-deploy-check` will enforce it before deployment. But catching issues early avoids broken UI in production.
+
+## Ownership Boundary
+
+This skill owns manifest JSON creation/editing and component tree composition.
+
+| This skill OWNS | Other skills OWN |
+|-----------------|------------------|
+| Manifest JSON creation/editing | Manifest validation -> `/fluent-mystique-validate` |
+| Page and route structure | SDK component code -> `/fluent-mystique-scaffold` |
+| Component tree composition | Deployed manifest analysis -> `/fluent-mystique-analyze` |
+| GraphQL query scaffolding in pages | Live GraphQL execution -> MCP tools |
+| i18n key generation in manifest | Settings management -> `/fluent-settings` |
+| Fragment composition | Workflow actions -> `/fluent-workflow-builder` |
+
+## Pre-flight: Plugin Availability
+
+Before building a manifest that references custom SDK components (non-`fc.*` aliases), verify the plugin bundle is accessible:
+
+1. **Identify custom components** in the plan — any component alias that does NOT start with `fc.`
+2. **For each custom component**, check if an SDK project exists in `accounts/<PROFILE>/SOURCE/*/src/index.tsx` with matching `ComponentRegistry.register` calls
+3. **If ALL custom components found locally:** Ensure the `plugins[]` array references the correct bundle URL (localhost for dev, CDN for production)
+4. **If ANY custom component is MISSING:** **STOP.** Inform the user: *"Custom component `<alias>` is not registered in any local SDK project. Scaffold it first via `/fluent-mystique-scaffold`, then resume manifest building."*
+5. **Exception:** If the manifest is being built as part of a feature plan where scaffolding comes later, note the dependency and proceed — but add a `DEPLOYMENT_ORDER_WARNING` comment
+
+## Frontend Development and Deployment Model
+
+Understanding how manifests and custom components reach users is critical for correct builder output.
+
+### Manifests are JSON Configuration
+
+Manifests are pure JSON — they are NOT compiled or bundled. They are deployed to Fluent UX Apps through one of:
+- **Admin Console** — upload via the UX App configuration UI
+- **Fluent API** — create/update as a Fluent Setting (key convention: `fc.mystique.manifest.<app-name>`)
+- **Fragment references** — deploy manifest fragments as separate Settings, referenced via `type: "reference"` routes
+
+### Custom Components are Externally Hosted Bundles
+
+Custom SDK components (anything not `fc.*`) are React code compiled to a `bundle.js` file. Fluent does NOT host these bundles. The deployment model is:
+
+1. **Development:** `yarn start` serves the bundle on `http://localhost:3001/bundle.[hash].js`
+2. **Production:** `yarn build` produces `dist/bundle.[hash].js` — deploy to a CDN (Vercel, S3, CloudFront, etc.)
+3. **Manifest references the bundle URL** via the `plugins[]` array
+
+### Plugin Configuration
+
+The `plugins[]` array in the manifest tells Mystique where to load external component bundles:
+
+```json
+{
+  "plugins": [
+    {
+      "type": "url",
+      "src": "http://localhost:3001/bundle.46a734bac1cb3a54ba80.js"
+    }
+  ]
+}
+```
+
+For production deployment, replace with the CDN URL:
+
+```json
+{
+  "plugins": [
+    {
+      "type": "url",
+      "src": "https://my-components.vercel.app/bundle.abc123.js"
+    }
+  ]
+}
+```
+
+Plugins can also be loaded from a Fluent Setting:
+
+```json
+{
+  "plugins": [
+    {
+      "type": "setting",
+      "setting": "fc.mystique.plugin.custom-components"
+    }
+  ]
+}
+```
+
+### Fragment Deployment
+
+Manifest fragments are deployed as Fluent Settings with the naming convention:
+
+```
+fc.mystique.manifest.<fragment-name>
+```
+
+The main manifest references them via:
+
+```json
+{
+  "type": "reference",
+  "settingName": "fc.mystique.manifest.inventory-section"
+}
+```
+
+This allows sections to be independently deployed and versioned without editing the main manifest.
+
+### Manifest Deployment via Settings API
+
+Manifests are stored as **Fluent Settings**. To deploy a manifest or fragment, you create or update its corresponding setting.
+
+**Storage model — setting names are app-scoped:**
+
+| App | Root Manifest Setting | Example Fragment Setting |
+|-----|----------------------|------------------------|
+| OMS | `fc.mystique.manifest.oms` | `fc.mystique.manifest.oms.fragment.dashboard` |
+| Store | `fc.mystique.manifest.store` | `fc.mystique.manifest.store.fragment.picking` |
+| Service Point | `fc.mystique.manifest.servicepoint` | `fc.mystique.manifest.servicepoint.fragment.tasks` |
+| Custom App | `fc.mystique.manifest.<app>` | `fc.mystique.manifest.<app>.fragment.<name>` |
+
+All manifest settings use scope `ACCOUNT`, type `JSON`, and the body is stored in `lobValue`.
+
+Each app serves at its own URL path: `/_plugins/<app>/manifests/...`
+
+**CRITICAL: Always use `lobValue`, not `value`.** Manifests exceed the regular `value` field's size limit. Using `value` will **silently truncate** the JSON — this causes data loss with no error.
+
+**Fetch an existing manifest or fragment:**
+
+```graphql
+query Manifest {
+  settings(name: "fc.mystique.manifest.oms") {
+    edges { node { id name lobValue } }
+  }
+}
+```
+
+Use the same query pattern for fragments — just change the `name` parameter:
+```graphql
+settings(name: "fc.mystique.manifest.oms.fragment.dashboard")
+```
+
+If a fragment has no ACCOUNT-level override, the platform loads the **global default** via HTTP:
+```
+https://<host>/_plugins/<app>/manifests/fc.mystique.manifest.<app>.fragment.<name>.json?v=<cachebuster>
+```
+
+**Create a new fragment override** (first-time deployment):
+
+```graphql
+mutation CreateFragment {
+  createSetting(input: {
+    name: "fc.mystique.manifest.oms.fragment.dashboard"
+    context: "ACCOUNT"
+    contextId: 0
+    valueType: "JSON"
+    lobValue: { "manifestVersion": "2.0", "routes": [...] }
+  }) { id }
+}
+```
+
+**Update an existing manifest** (requires setting ID — fetch first if unknown):
+
+```graphql
+mutation UpdateManifest {
+  updateSetting(input: {
+    id: 242
+    lobValue: { "manifestVersion": "2.0", "routes": [...] }
+  }) { id }
+}
+```
+
+`lobValue` must be **raw JSON** (an object), not a stringified JSON string.
+
+**Deployment workflow:**
+1. Fetch current deployed manifest/fragment via `graphql.query` → save locally as `.json`
+2. Make changes to the local copy (user reviews diff)
+3. Upload via `createSetting` (new) or `updateSetting` (existing) — or use MCP `setting.upsert`
+4. Verify in browser — Settings changes are immediate, no cache delay
+
+## When to Use
+
+- Creating a new Mystique app manifest from scratch
+- Adding pages or sections to an existing manifest
+- Composing component trees for entity detail or list pages
+- Building manifest fragments for modular deployment
+- Generating page-level GraphQL data queries for Fluent entities
+- Editing existing manifest JSON (add/remove/update routes, components, props)
+- Wiring custom SDK components into manifests via `plugins[]`
+
+## Progress
+
+Emit this block at each phase transition to show progress:
+
+```
+> /fluent-mystique-builder [1/6]
+  Done Plan verification       -> Collect manifest requirements
+  Todo Build route structure    Todo Compose component trees
+  Todo Generate data queries    Todo Validate output
+```
+
+Update the block as each phase completes — mark completed phases with `Done`, the active phase with `->`, and remaining phases with `Todo`. Replace `[1/6]` with the current phase number.
+
+## Manifest v2.0 Schema
+
+Every Mystique manifest follows this top-level structure:
+
+```json
+{
+  "manifestVersion": "2.0",
+  "name": "admin",
+  "title": "i18n:fc.admin.title",
+  "icon": "settings",
+  "context": {
+    "level": "retailer",
+    "role": "ADMIN"
+  },
+  "plugins": [
+    { "type": "url", "src": "https://cdn.example.com/bundle.js" }
+  ],
+  "homePath": "dashboard",
+  "routes": []
+}
+```
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `manifestVersion` | `"2.0"` | Always `"2.0"` — the only supported schema version |
+| `name` | `string` | App identifier used in logs and user action filtering. No spaces. |
+| `title` | `string` | User-facing app name. Supports `i18n:` prefix for translation |
+| `homePath` | `string` | Landing route path. Must match a defined route's `path` |
+| `routes` | `MystiqueManifestRoute[]` | Array of sections, pages, and fragment references |
+
+### Optional Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `icon` | `string` | none | Material icon name for the app |
+| `context` | `{ level, role? }` | `{ level: "retailer" }` | App context: `account`, `retailer`, or `location`. Optional `role` restricts access |
+| `plugins` | `MystiquePlugin[]` | `[]` | External component bundle URLs or setting references |
+| `orchestrationAlias` | `string` | none | Rename entity types for workflow resolution (e.g., `"store"` -> `"servicepoint"`) |
+
+### Route Types
+
+Routes come in three types:
+
+**Section** — groups pages under a navigation header:
+
+```json
+{
+  "type": "section",
+  "path": "orders",
+  "nav": { "label": "i18n:fc.orders.nav", "icon": "shopping_cart" },
+  "roles": ["ADMIN", "OPERATOR"],
+  "pages": []
+}
+```
+
+**Page** — a routable screen with data and components:
+
+```json
+{
+  "type": "page",
+  "path": "orders",
+  "component": "fc.page",
+  "nav": { "label": "i18n:fc.orders.list.nav", "icon": "list" },
+  "data": {
+    "query": "query { orders(first: 25) { edges { node { id ref status type createdOn } } pageInfo { hasNextPage endCursor } } }"
+  },
+  "props": { "title": "i18n:fc.orders.list.title" },
+  "descendants": [],
+  "roles": ["ADMIN"],
+  "fullScreen": false
+}
+```
+
+**Reference** — includes a manifest fragment stored as a Fluent Setting:
+
+```json
+{
+  "type": "reference",
+  "settingName": "fc.mystique.manifest.custom-inventory"
+}
+```
+
+### Component Instance
+
+The recursive building block used throughout `descendants[]`:
+
+```json
+{
+  "component": "fc.card.attribute",
+  "dataSource": "orderById",
+  "props": {
+    "title": "Order Details",
+    "width": "half",
+    "attributes": [
+      { "label": "Reference", "value": "{{ref}}" },
+      { "label": "Status", "value": "{{status}}" },
+      { "label": "Type", "value": "{{type}}" },
+      { "label": "Created", "value": "{{dateRelative createdOn}}" }
+    ]
+  },
+  "descendants": [],
+  "roles": ["ADMIN"]
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `component` | `string` | yes | Registry alias — `fc.*` for core, `custom.*` for SDK components |
+| `dataSource` | `string` | no | JSONPath scoping the data context for this component and its descendants |
+| `props` | `Record<string, any>` | no | Component-specific configuration (varies by component) |
+| `descendants` | `MystiqueComponentInstance[]` | no | Nested child components |
+| `roles` | `string[]` | no | Role-based visibility — component hidden if user lacks listed roles |
+
+### Page Data Query
+
+The `data` block on a page defines the GraphQL query executed before rendering:
+
+```json
+{
+  "data": {
+    "query": "query($id: ID!) { orderById(id: $id) { id ref status type createdOn totalPrice customer { firstName lastName } items { edges { node { id ref quantity productRef } } } } }",
+    "variables": {
+      "id": "{{id}}"
+    }
+  }
+}
+```
+
+Variables support template strings (`{{id}}` resolves from URL params) and `ConvertableVariable` for non-string types:
+
+```json
+{
+  "variables": {
+    "id": { "value": "{{id}}", "parse": true }
+  }
+}
+```
+
+### Manifest Fragment
+
+Fragments are cut-down manifests for modular deployment:
+
+```json
+{
+  "manifestVersion": "2.0",
+  "routes": [
+    {
+      "type": "section",
+      "nav": { "label": "Custom Section", "icon": "extension" },
+      "pages": [
+        {
+          "type": "page",
+          "path": "custom-page",
+          "component": "fc.page",
+          "nav": { "label": "Custom Page", "icon": "build" },
+          "props": { "title": "Custom Page" },
+          "descendants": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Operations
+
+### Operation 1: Create Manifest
+
+Interactive wizard collecting:
+
+```
+1. App name (slug: "admin", "servicepoint", "store-ops")
+2. Title (user-facing, supports i18n: prefix)
+3. Context level (account / retailer / location)
+4. Role restriction (optional)
+5. Home page path
+6. Initial sections and pages (from wireframe/plan)
+7. Plugin references (if custom components needed)
+```
+
+Generates a complete `manifest.json` with:
+- `manifestVersion: "2.0"` and all required top-level fields
+- Route structure with sections and pages
+- Page-level GraphQL data queries for each entity page
+- Component trees with props wired to data sources
+- Plugin references for custom SDK components
+
+### Operation 2: Add Page
+
+```
+Input: manifest file + page definition
+1. Determine target section (existing or new)
+2. Define page path (validate uniqueness against existing routes)
+3. Select page component (fc.page recommended as top-level)
+4. Define data query (entity type -> auto-generate GraphQL using entity map)
+5. Build component tree:
+   - Start with fc.page as the route component
+   - Add layout components (fc.column, fc.tabs.card)
+   - Add content components (fc.list, fc.card.attribute, fc.provider.graphql)
+   - Wire dataSource paths to connect components to query results
+   - Set component props per component documentation
+6. Add nav config if page should appear in sidebar
+7. Add role restrictions (optional)
+```
+
+### Operation 3: Add Component to Page
+
+```
+Input: manifest file + page path + component spec
+1. Load manifest and locate the target page by path
+2. Find insertion point in descendants tree (by index or parent component)
+3. Generate component instance:
+   - Select component alias from known registry
+   - Set props from component schema (see Component Props Reference below)
+   - Wire dataSource if the component consumes query data
+   - Add descendants recursively for container components
+4. Validate resulting tree structure
+```
+
+### Operation 4: Build Fragment
+
+```
+Input: fragment definition (sections and pages)
+1. Generate MystiqueManifestFragment JSON structure
+2. Define fragment routes (sections + pages with full component trees)
+3. Output as standalone JSON file
+4. Generate Fluent setting key: fc.mystique.manifest.<fragment-name>
+5. Generate setting.upsert command for deployment via /fluent-settings
+```
+
+### Operation 5: Generate Data Query
+
+```
+Input: entity type + required fields + query type (list or detail)
+1. Map entity type to GraphQL root query using Entity Type Query Map
+2. Build query with requested fields plus standard fields
+3. Handle connections/edges/node patterns for nested entities
+4. Add variables for dynamic filtering (pagination, URL params)
+5. Output as a page.data block ready to embed in the manifest
+```
+
+### Operation 6: Edit Existing Manifest
+
+```
+Input: manifest file + edit instructions
+1. Load and parse the manifest JSON
+2. Locate target element (route by path, component by tree position)
+3. Apply modifications (add/remove/update routes, components, props)
+4. Preserve existing structure — minimal diff approach
+5. Validate modified manifest against v2.0 schema
+6. Write back to the same file path
+```
+
+## Component Composition Patterns
+
+### Pattern 1: Entity Detail Page
+
+The standard layout for viewing a single entity with attributes and related data:
+
+```json
+{
+  "type": "page",
+  "path": "orders/:id",
+  "component": "fc.page",
+  "data": {
+    "query": "query($id: ID!) { orderById(id: $id) { id ref status type totalPrice totalTaxPrice createdOn updatedOn customer { id firstName lastName primaryEmail } items { edges { node { id ref productRef quantity paidPrice currency } } } fulfilments { edges { node { id ref status type fromAddress { name } } } } attributes { name value type } } }",
+    "variables": { "id": { "value": "{{id}}", "parse": true } }
+  },
+  "props": {
+    "title": "{{capitalise status}} - Order {{ref}}",
+    "backButtons": [{ "label": "Orders", "path": "/orders" }],
+    "actions": true
+  },
+  "descendants": [
+    {
+      "component": "fc.card.attribute",
+      "props": {
+        "title": "Order Summary",
+        "width": "half",
+        "attributes": [
+          { "label": "Reference", "value": "{{ref}}" },
+          { "label": "Status", "value": "{{status}}", "options": { "styles": [
+            { "matches": "COMPLETE", "icon": { "name": "MdCheckCircle", "colour": "success" } },
+            { "matches": "CANCELLED", "icon": { "name": "MdCancel", "colour": "error" } }
+          ]}},
+          { "label": "Type", "value": "{{type}}" },
+          { "label": "Created", "value": "{{dateRelative createdOn}}" },
+          { "label": "Total", "value": "${{totalPrice}}" }
+        ]
+      }
+    },
+    {
+      "component": "fc.card.attribute",
+      "props": {
+        "title": "Customer",
+        "width": "half",
+        "attributes": [
+          { "label": "Name", "value": "{{customer.firstName}} {{customer.lastName}}" },
+          { "label": "Email", "value": "{{customer.primaryEmail}}" }
+        ]
+      }
+    },
+    {
+      "component": "fc.tabs.card",
+      "props": {
+        "tabs": [
+          { "label": "Items" },
+          { "label": "Fulfilments" },
+          { "label": "Attributes" }
+        ]
+      },
+      "descendants": [
+        {
+          "component": "fc.list",
+          "dataSource": "items",
+          "props": {
+            "defaultPageSize": 25,
+            "attributes": [
+              { "label": "Product", "value": "{{node.productRef}}" },
+              { "label": "Quantity", "value": "{{node.quantity}}" },
+              { "label": "Price", "value": "${{node.paidPrice}}", "align": "right" }
+            ]
+          }
+        },
+        {
+          "component": "fc.list",
+          "dataSource": "fulfilments",
+          "props": {
+            "defaultPageSize": 10,
+            "rowLink": "/fulfilments/{{node.id}}",
+            "attributes": [
+              { "label": "Reference", "value": "{{node.ref}}" },
+              { "label": "Status", "value": "{{node.status}}" },
+              { "label": "Type", "value": "{{node.type}}" }
+            ]
+          }
+        },
+        {
+          "component": "fc.list",
+          "dataSource": "attributes",
+          "props": {
+            "defaultPageSize": 25,
+            "attributes": [
+              { "label": "Name", "value": "{{node.name}}" },
+              { "label": "Value", "value": "{{node.value}}" },
+              { "label": "Type", "value": "{{node.type}}" }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Pattern 2: Entity List Page
+
+The standard paginated list page with filtering:
+
+```json
+{
+  "type": "page",
+  "path": "orders",
+  "component": "fc.page",
+  "nav": { "label": "i18n:fc.orders.list.nav", "icon": "shopping_cart" },
+  "data": {
+    "query": "query($retailerId: [Int!], $orders_first: Int, $status: [String], $type: [String], $createdOn: DateRange) { orders(retailerId: $retailerId, first: $orders_first, status: $status, type: $type, createdOn: $createdOn) { edges { node { id ref status type totalPrice createdOn customer { firstName lastName } } } pageInfo { hasNextPage endCursor } } }",
+    "variables": {
+      "orders_first": 25,
+      "retailerId": "{{activeRetailer.id}}"
+    }
+  },
+  "props": { "title": "i18n:fc.orders.list.title" },
+  "descendants": [
+    {
+      "component": "fc.list",
+      "dataSource": "orders",
+      "props": {
+        "defaultPageSize": 25,
+        "rowLink": "/orders/{{node.id}}",
+        "filter": { "enabled": true },
+        "attributes": [
+          { "label": "Reference", "value": "{{node.ref}}" },
+          { "label": "Customer", "value": "{{node.customer.firstName}} {{node.customer.lastName}}" },
+          { "label": "Status", "value": "{{node.status}}" },
+          { "label": "Type", "value": "{{node.type}}" },
+          { "label": "Total", "value": "${{node.totalPrice}}", "align": "right" },
+          { "label": "Created", "value": "{{dateRelative node.createdOn}}", "hideBelow": "sm" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Pattern 3: Dashboard with Metrics
+
+```json
+{
+  "type": "page",
+  "path": "dashboard",
+  "component": "fc.page",
+  "data": {
+    "query": "query($todayStart: DateTime!, $weekStart: DateTime!) { ordersToday: orders(createdOn: {from: $todayStart}) { edges { node { id } } } ordersWeek: orders(createdOn: {from: $weekStart}) { edges { node { id } } } escalations: fulfilments(status: \"ESCALATED\") { edges { node { id } } } }",
+    "variables": {
+      "todayStart": "{{dateStringFormatter (dateAdd day=-1) 'YYYY-MM-DD[T]HH:mm:ss.SSS[Z]'}}",
+      "weekStart": "{{dateStringFormatter (dateAdd day=-7) 'YYYY-MM-DD[T]HH:mm:ss.SSS[Z]'}}"
+    }
+  },
+  "props": { "title": "Overview Dashboard" },
+  "descendants": [
+    {
+      "component": "fc.dashboard.threshold",
+      "props": {
+        "label": "Orders Today",
+        "value": "{{ordersToday.edges.length}}",
+        "thresholdLow": 100,
+        "thresholdHigh": 500,
+        "link": "#/orders"
+      }
+    },
+    {
+      "component": "fc.dashboard.threshold",
+      "props": {
+        "label": "Orders This Week",
+        "value": "{{ordersWeek.edges.length}}",
+        "thresholdLow": 500,
+        "thresholdHigh": 2000,
+        "link": "#/orders"
+      }
+    },
+    {
+      "component": "fc.dashboard.threshold",
+      "props": {
+        "label": "Escalations",
+        "value": "{{escalations.edges.length}}",
+        "thresholdLow": 5,
+        "thresholdHigh": 20,
+        "link": "#/fulfilments"
+      }
+    }
+  ]
+}
+```
+
+### Pattern 4: Conditional Content
+
+Show different components based on entity data using `fc.conditional`:
+
+```json
+{
+  "component": "fc.conditional",
+  "props": {
+    "value": "{{type}}",
+    "matches": "HD"
+  },
+  "descendants": [
+    {
+      "component": "fc.card.attribute",
+      "props": {
+        "title": "Home Delivery Details",
+        "attributes": [
+          { "label": "Delivery Address", "value": "{{fulfilmentChoice.deliveryAddress.street}}" },
+          { "label": "Postcode", "value": "{{fulfilmentChoice.deliveryAddress.postcode}}" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+Use multiple `fc.conditional` siblings for if/else-if patterns:
+
+```json
+[
+  {
+    "component": "fc.conditional",
+    "props": { "value": "{{type}}", "matches": "HD" },
+    "descendants": [{ "component": "fc.card.attribute", "props": { "title": "Home Delivery" } }]
+  },
+  {
+    "component": "fc.conditional",
+    "props": { "value": "{{type}}", "matches": "CC" },
+    "descendants": [{ "component": "fc.card.attribute", "props": { "title": "Click & Collect" } }]
+  }
+]
+```
+
+### Pattern 5: Data Provider Nesting
+
+Use `fc.provider.graphql` to fetch additional data within a page:
+
+```json
+{
+  "component": "fc.provider.graphql",
+  "props": {
+    "query": "query($ref: [String]) { locations(ref: $ref) { edges { node { id ref name type status primaryAddress { street city state postcode country } } } } }",
+    "variables": { "ref": "{{fromLocation.ref}}" },
+    "path": "locations"
+  },
+  "descendants": [
+    {
+      "component": "fc.card.attribute",
+      "dataSource": "locations",
+      "props": {
+        "title": "Fulfilment Location",
+        "attributes": [
+          { "label": "Name", "value": "{{node.name}}" },
+          { "label": "Address", "value": "{{node.primaryAddress.street}}, {{node.primaryAddress.city}}" },
+          { "label": "Status", "value": "{{node.status}}" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+The `path` prop enables auto-pagination for connections. The `loadingBehavior` prop controls rendering during fetch: `"wait"`, `"wait-with-animation"`, or `"pass-immediately"` (default).
+
+### Pattern 6: Tab Card with Multiple Views
+
+Use `fc.tabs.card` to organize related content into tabs. Descendants are matched to tabs by index:
+
+```json
+{
+  "component": "fc.tabs.card",
+  "props": {
+    "tabs": [
+      { "label": "i18n:fc.order.items.tab" },
+      { "label": "i18n:fc.order.fulfilments.tab" },
+      { "label": "i18n:fc.order.activity.tab" }
+    ],
+    "urlKey": "orderTab"
+  },
+  "descendants": [
+    {
+      "component": "fc.list",
+      "dataSource": "items",
+      "props": {
+        "defaultPageSize": 25,
+        "attributes": [
+          { "label": "Product", "value": "{{node.productRef}}" },
+          { "label": "Qty", "value": "{{node.quantity}}" }
+        ]
+      }
+    },
+    {
+      "component": "fc.list",
+      "dataSource": "fulfilments",
+      "props": {
+        "defaultPageSize": 10,
+        "rowLink": "/fulfilments/{{node.id}}",
+        "attributes": [
+          { "label": "Ref", "value": "{{node.ref}}" },
+          { "label": "Status", "value": "{{node.status}}" }
+        ]
+      }
+    },
+    {
+      "component": "fc.list",
+      "dataSource": "events",
+      "props": {
+        "defaultPageSize": 50,
+        "attributes": [
+          { "label": "Event", "value": "{{node.name}}" },
+          { "label": "Time", "value": "{{dateRelative node.createdOn}}" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Pattern 7: Page Actions (User Actions, Mutations, Navigation)
+
+Configure page-level action buttons via the `actions` prop on `fc.page`:
+
+```json
+{
+  "props": {
+    "title": "Order {{ref}}",
+    "actions": {
+      "primary": [
+        {
+          "type": "userAction",
+          "name": "ConfirmShipment",
+          "condition": "{{eq status 'PICK_PACK'}}"
+        },
+        {
+          "type": "navigate",
+          "label": "View Fulfilments",
+          "link": "/orders/{{id}}/fulfilments"
+        }
+      ],
+      "secondary": [
+        {
+          "type": "mutation",
+          "name": "updateOrder",
+          "label": "Edit Order",
+          "args": { "id": "{{id}}" },
+          "filter": { "type": "include", "names": ["status", "attributes"] },
+          "extensions": {
+            "postSubmit": { "type": "navigate", "link": "/orders/{{id}}" }
+          }
+        },
+        {
+          "type": "component",
+          "component": "custom.order-export-button",
+          "props": { "orderId": "{{id}}" }
+        }
+      ],
+      "userActionFilter": { "type": "exclude", "names": ["CancelOrder"] }
+    }
+  }
+}
+```
+
+Action types:
+- `userAction` — triggers a workflow user action. Auto-appended from workflow but can be reordered or conditionally shown.
+- `mutation` — executes a GraphQL mutation with auto-generated form. Use `overrides` to customize field labels, sources, and components.
+- `navigate` — navigates to another page. `link` supports template strings.
+- `component` — renders a custom SDK component in the action bar.
+
+## Entity Type to GraphQL Query Map
+
+Use this mapping to auto-generate page data queries:
+
+| Entity Type | Root Query (list) | Root Query (detail) | Key Fields |
+|-------------|-------------------|---------------------|------------|
+| ORDER | `orders(first, after, status, type, retailerId, createdOn)` | `orderById(id)` | id, ref, status, type, createdOn, totalPrice, customer, items, fulfilments, fulfilmentChoice, attributes |
+| FULFILMENT | `fulfilments(first, after, status, type, retailerId)` | `fulfilmentById(id)` | id, ref, status, type, createdOn, order, items, fromAddress, toAddress, attributes |
+| ARTICLE | `articles(first, after, status, retailerId)` | `articleById(id)` | id, ref, status, type, items, consignmentArticles, attributes |
+| WAVE | `waves(first, after, status, retailerId)` | `waveById(id)` | id, ref, status, type, fulfilments, retailer, attributes |
+| LOCATION | `locations(first, after, status, type, retailerId)` | `locationById(id)` | id, ref, name, type, status, primaryAddress, networks, openingSchedule, attributes |
+| INVENTORY_POSITION | `inventoryPositions(first, after, productRef, locationRef)` | `inventoryPositionById(id)` | id, ref, productRef, locationRef, onHand, status, type, attributes |
+| PRODUCT_CATALOGUE | `productCatalogues(first, after, retailerId)` | `productCatalogueById(id)` | id, ref, name, type, retailer, attributes |
+| VIRTUAL_CATALOGUE | `virtualCatalogues(first, after, retailerId)` | `virtualCatalogueById(id)` | id, ref, name, type, retailer, attributes |
+| CARRIER | `carriers(first, after, retailerId)` | `carrierById(id)` | id, ref, name, type, status, retailer, attributes |
+| RETURN_ORDER | `returnOrders(first, after, status, retailerId)` | `returnOrderById(id)` | id, ref, status, type, order, returnAuthorisation, items, attributes |
+| NETWORK | `networks(first, after, retailerId)` | `networkById(id)` | id, ref, name, type, status, locations, retailers, attributes |
+| SETTING | `settings(first, after, name, context)` | n/a | id, name, value, lobValue, valueType, context, contextId |
+
+### Connection Pattern for Nested Entities
+
+All list queries return connections with edges/node pattern. Always include `pageInfo` for pagination:
+
+```graphql
+query($first: Int, $after: String) {
+  orders(first: $first, after: $after) {
+    edges {
+      node {
+        id
+        ref
+        status
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}
+```
+
+Nested connections follow the same pattern:
+
+```graphql
+{
+  orderById(id: $id) {
+    items {
+      edges {
+        node { id ref quantity productRef }
+      }
+    }
+  }
+}
+```
+
+## Component Knowledge
+
+Each OOTB component is documented in its own `.md` file under `components/` (same directory as this skill). `COMPONENT_TEMPLATE.md` defines the standard format — used for both OOTB and client custom component documentation.
+
+Use this lookup order for fastest and most reliable component selection:
+1. Start with `components/INDEX.md` for alias/category/module lookup (AI-friendly table).
+2. Open matching `components/<alias>.md` files for detailed props, data binding, and composition guidance.
+3. Use each file's frontmatter (`alias`, `aliases`, `category`, `module`) and `## AI Parse Notes` section for deterministic parsing.
+
+**Before building ANY manifest:**
+1. Grep `components/*.md` for the user's UI need (e.g., "list", "filter", "tabs")
+2. Read matching component files for props, data binding, and composition patterns
+3. Propose a composition plan → get user approval → build manifest JSON
+4. Only if no OOTB combination works → escalate to `/fluent-mystique-scaffold`
+
+### Build vs Configure Decision (use EVERY time)
+
+```
+Step 1: Check Need → Grep components/*.md for matching capability
+├── Found a match? → Configure via manifest using the documented props
+├── Close match? → Step 2: Creative composition of OOTB components
+│   ├── Combine fc.conditional + fc.repeater + fc.provider.graphql?
+│   ├── Nest tabs inside providers? Use multiple data providers?
+│   └── Found a working composition? → Build manifest JSON
+├── Need a custom form field or template? → Step 3: Lightweight SDK extension
+│   └── FieldRegistry.register() or TemplateRegistry.register()
+└── Genuinely no OOTB equivalent? → Step 4: Full custom component
+    └── Scaffold via /fluent-mystique-scaffold → ComponentRegistry.register()
+```
+
+**Most requests resolve at Step 1 or 2.** Only proceed to Step 4 for: novel visualizations, drag-and-drop, external service integrations, real-time features, or interaction patterns not covered by user action forms.
+
+### Quick Alias Reference (86 components in `components/`)
+
+**Page:** `fc.page`, `fc.page.section`, `fc.page.section.column`, `fc.page.section.header`, `fc.page.wizard`, `fc.page.wizard.summary`, `fc.page.refresh`, `fc.page.filter.select`
+
+**Layout:** `fc.conditional`, `fc.repeater`, `fc.provider.graphql`, `fc.workflow.provider`, `fc.tabs`, `fc.tabs.card`, `fc.tab.content`, `fc.accordion`, `fc.filterPanel`
+
+**Content:** `fc.list`, `fc.list.customAction`, `fc.card.attribute`, `fc.card.image`, `fc.card.product`, `fc.card.multi`, `fc.card.attributes.grid`, `fc.card.map.point`, `fc.tile.metric`, `fc.dashboard.threshold`, `fc.stepper`, `fc.progress.circular`, `fc.attribute.json`, `fc.attribute.column`, `fc.mystique.collapsible.text`, `fc.mystique.collapsible.attributes`, `fc.mystique.link`, `fc.json.viewer`, `fc.json.editor`, `fc.quantity.list`, `fc.settingForm`
+
+**Charts:** `fc.chart.line`, `fc.chart.bar`, `fc.chart.area`, `fc.chart.gauge` (+ wrapper variants)
+
+**Actions:** `fc.action.inline`, `fc.mutation.inline`, `fc.button.print` (+ `.pick`, `.inline`, `.download`), `fc.button.bar`, `fc.modal.button`, `fc.modal.button.addItem`, `fc.drawer.button`, `fc.sourcing.strategy.modal.button`, `fc.sourcing.profile.drawer.button`, `fc.sourcing.profile.modal.button`
+
+**Forms/Fields:** `select`, `fc.field.daterange`, `fc.field.intrange`, `fc.field.multistring`, `fc.field.filterComplex`, `fc.scanner.barcode`, `fc.scanner.camera`, `fc.scanner.barcodeFilter`
+
+**OMS:** `fc.events.search`, `fc.activity.entity`, `fc.event.detail`, `fc.order.itemDetails`, `fc.order.shipmentDetails`, `fc.return.rowExpansion`
+
+**Store:** `fc.buttons.add.reject`, `fc.action.field.wavepick`, `fc.action.field.fulfilmentpack`, `fc.action.field.multiparcel`, `fc.action.field.returnitems`
+
+**Analytics:** `fc.analytics.viz` (Looker embed)
+
+**Legacy aliases** (v1 → v2): `shared.components.material.DynamicPage` → `fc.page`, `shared.components.material.DynamicList` → `fc.list`, `shared.components.material.DynamicCard` → `fc.card.attribute`, `shared.components.material.MaterialTabsSet` → `fc.tabs`
+
+## Template String Reference
+
+Mystique uses Handlebars-based template strings throughout manifests. **Only use documented helpers — guessing undocumented helpers produces broken manifests.**
+
+### Field Access
+
+| Expression | Purpose | Example |
+|-----------|---------|---------|
+| `{{fieldName}}` | Direct field access | `{{ref}}`, `{{status}}` |
+| `{{nested.path}}` | Nested field access | `{{customer.firstName}}` |
+| `{{attributes.byName.X}}` | Attribute by name shorthand | `{{order.attributes.byName.vipStatus}}` |
+| `{{node.field}}` | List row data access | `{{node.ref}}` in fc.list attributes |
+| `{{edges.length}}` | Connection count | `{{orders.edges.length}}` |
+
+### Context Variables
+
+| Expression | Purpose |
+|-----------|---------|
+| `{{activeUser.username}}` | Current user's username |
+| `{{activeUser.firstName}}` | Current user's first name |
+| `{{activeUser.timezone}}` | Current user's timezone |
+| `{{activeContext.id}}` | Current context ID (retailer or location) |
+| `{{activeContext.ref}}` | Current context ref |
+| `{{activeRetailer.id}}` | Current retailer ID |
+| `{{activeRetailer.ref}}` | Current retailer ref |
+| `{{activeLocation.id}}` | Current location ID |
+| `{{activeLocation.ref}}` | Current location ref |
+| `{{params.id}}` | Route parameter access |
+| `{{params.filter_status}}` | Query parameter access |
+
+### String Helpers
+
+| Expression | Purpose | Example |
+|-----------|---------|---------|
+| `{{capitalise value}}` | Capitalize string | `{{capitalise status}}` |
+| `{{humanify value}}` | Human-readable (underscore/camel to spaced) | `{{humanify entityType}}` |
+| `{{toLowerCase value}}` | Lowercase | `{{toLowerCase order.type}}` |
+| `{{toUpperCase value}}` | Uppercase | `{{toUpperCase lastName}}` |
+| `{{concat a b separator='X'}}` | Concatenate with separator | `{{concat firstName lastName separator=' '}}` |
+| `{{stringify value}}` | JSON stringify | `{{stringify order.attributes.byName.payload}}` |
+| `{{preserveWhitespace text}}` | Preserve whitespace in rendering | `{{preserveWhitespace notes}}` |
+| `{{partialStringMatch a b}}` | Case-insensitive partial match | `{{partialStringMatch 'item1' 'eM1'}}` returns true |
+| `{{decodeUrlParams value}}` | URL decode | `{{decodeUrlParams 'TEST%3A%3AL%2FXL'}}` returns `TEST::L/XL` |
+| `{{{currentUrlParams}}}` | Inject current URL params (triple-brace, unescaped) | `"#/search?{{{currentUrlParams}}}"` |
+| `{{placeholderText text color='X' defaultValue='X'}}` | Styled fallback text | `{{placeholderText value defaultValue='-'}}` |
+
+### Date Helpers
+
+**CRITICAL: Always use `_locale='en'` for dates in query variables.** Without it, user locale may produce non-ASCII digits (e.g., Arabic numerals) that break backend queries.
+
+| Expression | Purpose | Example |
+|-----------|---------|---------|
+| `{{dateFormat date fmt}}` | Formatted date (display) | `{{dateFormat createdOn 'MMM DD, YYYY'}}` |
+| `{{dateFormat date fmt true _locale='en'}}` | **Backend-safe** formatted date | `{{dateFormat (dateAdd day=-1) 'YYYY-MM-DD[T]HH:mm:ss.SSS[Z]' true _locale='en'}}` |
+| `{{dateRelative date}}` | Relative time ("10 minutes ago") | `{{dateRelative order.expiryTime}}` |
+| `{{dateFormatByLocale date}}` | Locale-aware format (dd/mm or mm/dd) | `{{dateFormatByLocale order.createdOn}}` |
+| `{{dateAdd date day=N}}` | Date arithmetic (add) | `{{dateAdd order.createdOn day=3}}` |
+| `{{dateSubtract date day=N}}` | Date arithmetic (subtract) | `{{dateSubtract order.createdOn day=5}}` |
+| `{{dateStringFormatter (dateAdd day=N) fmt}}` | Date arithmetic + format | `{{dateStringFormatter (dateAdd day=-7) 'YYYY-MM-DD'}}` |
+| `{{placeholderDate date color='X' defaultValue='X'}}` | Date with styled fallback | `{{placeholderDate date defaultValue='[...]'}}` |
+
+### Number and Currency Helpers
+
+| Expression | Purpose | Example |
+|-----------|---------|---------|
+| `{{currency value code}}` | Format as currency | `{{currency totalPrice 'AUD'}}` |
+| `{{currency value code _locale='X' _decimalPlaces=N}}` | Currency with locale control | `{{currency 123.87 'AUD' _locale='en-AU' _decimalPlaces=3}}` |
+| `{{add a b}}` | Addition | `{{add 1 2}}` returns 3 |
+| `{{subtract a b _decimalPlaces=N}}` | Subtraction | `{{subtract 50.32 20.11 _decimalPlaces=2}}` returns 30.21 |
+| `{{multiply a b}}` | Multiplication | `{{multiply 3 4}}` returns 12 |
+| `{{divide a b _decimalPlaces=N}}` | Division | `{{divide 12 4 _decimalPlaces=3}}` returns 3.000 |
+| `{{pow base exp}}` | Exponent | `{{pow 3 2}}` returns 9 |
+
+### Array Helpers
+
+| Expression | Purpose | Example |
+|-----------|---------|---------|
+| `{{len array}}` | Array length | `{{len items.edges}}` |
+| `{{arraySum array 'path'}}` | Sum numeric field across array | `{{arraySum order.items 'node.totalPrice'}}` |
+| `{{placeholderArray arr separator='X' charCutoff=N}}` | Array display with truncation | `{{placeholderArray tags separator=', ' charCutoff=50}}` |
+
+### Logic Helpers
+
+| Expression | Purpose | Example |
+|-----------|---------|---------|
+| `{{eq a b}}` | Equality | `{{eq status 'ACTIVE'}}` |
+| `{{ne a b}}` | Not equal | `{{ne status 'CANCELLED'}}` |
+| `{{gt a b}}` | Greater than | `{{gt totalPrice 0}}` |
+| `{{lt a b}}` | Less than | `{{lt items.count 3}}` |
+| `{{gte a b}}` | Greater or equal | `{{gte items.count 5}}` |
+| `{{lte a b}}` | Less or equal | `{{lte items.count 10}}` |
+| `{{and a b}}` | Logical AND | `{{and (eq status 'BOOKED') (gt items.count 0)}}` |
+| `{{or a b}}` | Logical OR | `{{or order.status order.items.count}}` |
+| `{{in value ...options}}` | Inclusion check | `{{in type 'HD' 'CC' 'MULTI'}}` |
+| `{{switch val k1 v1 k2 v2 default}}` | Switch expression | `{{switch status 'COMPLETE' 'green' 'red'}}` |
+| `{{hasRole 'ROLE'}}` | Role check | `{{hasRole 'admin'}}` |
+| `{{firstDefinedValue a b c}}` | First non-null value | `{{firstDefinedValue null undefined 10}}` returns 10 |
+| `{{anyMatch 'path' 'val' 'op'}}` | Array element match | `{{anyMatch 'node.entity.field' 'delta' 'eq'}}` |
+
+### i18n Helpers
+
+| Expression | Purpose | Example |
+|-----------|---------|---------|
+| `{{i18n 'key'}}` | Translate key | `{{i18n 'fc.om.orders.title'}}` |
+| `{{i18n 'prefix' value _fallback=val}}` | Dynamic key with fallback | `{{i18n 'fc.om.order.type.' node.type _fallback=node.type}}` |
+| `{{i18n 'a' '.' 'b'}}` | Concatenated key | `{{i18n 'fc.om.order' '.' 'status'}}` |
+
+### Special Helpers
+
+| Expression | Purpose | Example |
+|-----------|---------|---------|
+| `{{barcode value format}}` | Generate barcode SVG | `{{barcode '1234 abc' 'CODE128B'}}` |
+| `{{barcode value}}` | Barcode with auto-detected format | `{{barcode fulfilmentById.ref}}` |
+| `{{barcode value format false}}` | Barcode without text below | `{{barcode '1234' 'EAN-13' false}}` |
+
+Supported barcode formats: CODE128, CODE128A, CODE128B, CODE128C, EAN-13, EAN-8, EAN-5, EAN-2, UPC-A, UPC-E, CODE39, ITF, ITF-14, MSI, MSI10, MSI11, MSI1010, MSI1110, Pharmacode, Codabar.
+
+## Dynamic Attribute Types
+
+Dynamic attributes are configurable value displays used in `fc.list` columns, `fc.card.attribute` rows, and similar components. Three types: **standard** (text), **image**, and **component**.
+
+### Standard (Text) with Conditional Styling
+
+```json
+{
+  "label": "i18n:fc.om.orders.column.status",
+  "value": "{{status}}",
+  "link": "#/order/{{id}}",
+  "condition": "{{and id}}",
+  "enableCopyIcon": "displayOnHover",
+  "options": {
+    "styles": [
+      {
+        "value": "{{status}}",
+        "matches": ["BOOKED", "CONFIRMED"],
+        "icon": { "name": "MdCheckCircle", "colour": "primary" },
+        "text": { "colour": "green" }
+      },
+      {
+        "matches": ["CANCELLED"],
+        "icon": { "name": "MdCancel", "colour": "error" },
+        "text": { "colour": "red" }
+      },
+      { "icon": { "name": "MdInfo" } }
+    ]
+  }
+}
+```
+
+Style matching: entries with `matches` checked in order — first match wins. Entry without `matches` is the default. Icon `name` must include library prefix: `Md*` (Material Design) or `Fa*` (Font Awesome).
+
+### Image Attribute
+
+```json
+{ "type": "image", "label": "Product", "value": "{{node.attributes.byName.imageUrl}}", "options": { "width": 50, "height": 50 } }
+```
+
+### Component Attribute
+
+Embed another component inside an attribute slot:
+
+```json
+{ "type": "component", "label": "Actions", "options": { "component": "fc.button.print.download", "props": { "label": "Print", "href": "api/v4/consignment/{{id}}/labelStream", "filename": "label.pdf" } } }
+```
+
+## CardActions Pattern
+
+CardActions configure action buttons on cards and list rows. Primary actions render as buttons; secondary actions group under "More".
+
+```json
+{
+  "cardActions": {
+    "primary": [{ "type": "userAction", "name": "ConfirmShipment", "label": "i18n:fc.action.confirm" }],
+    "secondary": [{ "type": "userAction", "name": "CancelOrder", "condition": "{{ne status 'SHIPPED'}}" }],
+    "showAtLeast": 1
+  }
+}
+```
+
+- `type: "userAction"` triggers a workflow user action. `name` matches the ruleset name.
+- Workflow-defined user actions are **automatically appended** — only add to manifest when reordering or adding conditions.
+- `showAtLeast` — primary actions to keep visible on mobile (rest collapse into "More").
+- `condition` — template string; action hidden when evaluates to `"false"`.
+
+## Settings vs Manifest Decision Matrix
+
+| Use **Settings** when | Use **Manifest** when |
+|---|---|
+| Config varies by retailer/location | Structure is stable across tenants |
+| Values change frequently | Routes, pages, component layout |
+| Non-developers need to update | Developers manage changes |
+| API keys, external URLs, thresholds | Static labels, i18n keys |
+
+## Troubleshooting
+
+Common manifest issues and fixes:
+
+1. **Template not resolving** — Missing `{{ }}` syntax. `"value": "order.ref"` shows literal text. Fix: `"value": "{{order.ref}}"`
+2. **Date query returns localized digits** — User locale produces Arabic/Thai numerals that break backend. Fix: Add `_locale='en'`: `{{dateFormat (dateSubtract day=1) 'YYYY-MM-DD[T]HH:mm:ss.SSS[Z]' true _locale='en'}}`
+3. **Condition not working** — String `"false"` is truthy. Fix: Use a template expression: `"condition": "{{and field1 field2}}"`
+4. **Link not rendering** — The data value is null/undefined. Fix: Add `"condition": "{{and customer.id}}"` alongside the link
+5. **Icon not showing** — Missing library prefix. `"CheckCircle"` is wrong. Fix: `"MdCheckCircle"` (Material Design) or `"FaCheck"` (Font Awesome)
+6. **Debugging tips** — Check browser DevTools Network tab for actual GraphQL response shape. Use React DevTools to inspect component props. Validate JSON syntax with `jq .`
+
+## Output Locations
+
+| Artifact | Path |
+|----------|------|
+| New manifest | `accounts/<PROFILE>/SOURCE/<sdk-project>/manifests/<name>.json` |
+| Fragment | `accounts/<PROFILE>/SOURCE/<sdk-project>/manifests/fragments/<name>.json` |
+| Standalone manifest (no SDK project) | `accounts/<PROFILE>/manifests/<name>.json` |
+| Build plan | `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-mystique-builder-<slug>.md` |
+
+## Handoff Protocol
+
+### Signals emitted by this skill
+
+| Signal | Condition | Example |
+|--------|-----------|---------|
+| `-> READY: <path>` | Manifest JSON created/modified | `-> READY: accounts/SAGIRISH/SOURCE/mystique-plugin/manifests/admin.json` |
+| `-> NEXT: /fluent-<skill>` | Always validate after build | `-> NEXT: /fluent-mystique-validate` |
+| `-> BLOCKED: <reason>` | Prerequisite missing | `-> BLOCKED: PREREQ_MISSING -- Custom component custom.order-tracker not registered. Run /fluent-mystique-scaffold` |
+| `-> SKIP: <reason>` | No manifest changes needed | `-> SKIP: No UI changes in this feature plan` |
+
+### Error codes
+
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| `PLAN_REQUIRED` | Multi-artifact work attempted without approved plan | Run `/fluent-feature-plan` first |
+| `PREREQ_MISSING` | Custom SDK components not scaffolded or plugins missing | Scaffold component via `/fluent-mystique-scaffold` |
+| `VALIDATION_FAILED` | Manifest JSON structure invalid after editing | Fix JSON structure per validation checklist |
+
+## Session Tracking
+
+When invoked, log the following to the session tracking protocol (consumed by `/fluent-session-summary` and `/fluent-session-audit-export`):
+
+**On entry:**
+```json
+{ "skill": "fluent-mystique-builder", "timestamp": "<ISO-8601>", "arguments": { "operation": "<op>", "manifest": "<file>", "page": "<path>" } }
+```
+
+**On exit:**
+```json
+{ "skill": "fluent-mystique-builder", "outcome": "<completed|failed|skipped>", "changesProduced": ["<seq-numbers>"], "toolCallsProduced": ["<seq-numbers>"], "nextRecommended": "/fluent-mystique-validate" }
+```
+
+## Error Reporting
+
+Errors from this skill follow the standard format:
+
+| Field | Description |
+|-------|-------------|
+| `phase` | Skill phase where error occurred (e.g., `pre-flight`, `route-design`, `component-tree`, `query-generation`, `validation`) |
+| `severity` | `CRITICAL` (blocks downstream), `HIGH` (needs fix), `MEDIUM` (advisory), `LOW` (informational) |
+| `message` | Human-readable error description |
+| `resolution` | Suggested fix or downstream skill to invoke |
+
+## Validation Checklist
+
+Run through this before considering any manifest complete:
+
+1. **JSON syntax** — Valid JSON (no trailing commas, correct brackets)
+2. **manifestVersion** — Must be `"2.0"`
+3. **Required fields** — `name`, `title`, `homePath`, `routes` all present
+4. **homePath resolves** — Must match a defined route's `path`
+5. **Route types valid** — Every route is `section`, `page`, or `reference`
+6. **Page paths unique** — No duplicate `path` values across all pages
+7. **Component aliases** — All `fc.*` aliases exist in the known registry; custom aliases have corresponding plugin
+8. **dataSource paths** — JSONPath notation valid; references query result fields
+9. **Template strings** — Balanced `{{`/`}}`, valid helper names
+10. **Plugin URLs** — `src` is a valid URL (http/https for dev, https for production)
+11. **Fragment settingName** — Follows `fc.mystique.manifest.*` convention
+12. **Roles** — Role strings are valid and consistent across the manifest
+13. **i18n keys** — Translatable strings use `i18n:` prefix consistently
+
+## Integration with Other Skills
+
+| Task | Skill |
+|------|-------|
+| Validate manifest structure before deploy | `/fluent-mystique-validate` |
+| Scaffold custom SDK component project | `/fluent-mystique-scaffold` |
+| Analyze existing manifests for patterns | `/fluent-mystique-analyze` |
+| Deploy manifest as Fluent Setting | `/fluent-settings` |
+| Build workflows that power user actions | `/fluent-workflow-builder` |
+| Create feature plan covering UI work | `/fluent-feature-plan` |
+| Run pre-deploy checks including manifest validation | `/fluent-pre-deploy-check` |
+
+## Handoff
+
+| Output Artifact | Consumed By | Path |
+|----------------|-------------|------|
+| Manifest JSON file | `/fluent-mystique-validate` (validation) | `accounts/<PROFILE>/SOURCE/<project>/manifests/<name>.json` |
+| Manifest JSON file | `/fluent-settings` (deploy as setting) | `accounts/<PROFILE>/SOURCE/<project>/manifests/<name>.json` |
+| Fragment JSON file | `/fluent-settings` (deploy as setting) | `accounts/<PROFILE>/SOURCE/<project>/manifests/fragments/<name>.json` |
+| Build plan | User review | `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-mystique-builder-<slug>.md` |