@fluentcommerce/ai-skills 0.2.0 → 0.3.0

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

@@ -0,0 +1,1830 @@
+---
+name: fluent-mystique-scaffold
+description: Scaffold a new Mystique SDK component project with webpack, TypeScript, Storybook, Jest, component registration, and i18n — ready to develop and deploy. Triggers on "scaffold component", "new mystique project", "create sdk component", "mystique sdk setup", "new ui plugin".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <project-name> [--components ComponentA,ComponentB] [--category content|layout|page|filter]
+---
+
+# Mystique SDK Component Scaffolder
+
+Generate a complete, buildable Mystique SDK component project from a project name and optional component list. The output is a directory under `accounts/<PROFILE>/SOURCE/` containing a React/TypeScript/webpack project that produces a `bundle.[contenthash].js` file loadable via the `plugins[]` array in any Mystique manifest.
+
+A Mystique SDK project is a standalone React application that registers custom UI components with the Mystique ComponentRegistry. At runtime, the Fluent OMX host application loads the bundle from a URL, executes it, and the registered components become available for use in manifests alongside built-in `fc.*` components. The host application provides React, ReactDOM, Material-UI, and Mystique globals as webpack externals -- the bundle does NOT include these libraries.
+
+## Pre-Check: New Project or Extend Existing?
+
+**ALWAYS run this decision tree before scaffolding. Do NOT skip.**
+
+```
+User asks: "I need a UI component" / "Create a Mystique plugin" / "Build a custom component"
+|
++-- 1. Discover existing SDK projects in workspace
+|   Search: accounts/<PROFILE>/SOURCE/*/package.json (look for mystique deps)
+|   Search: accounts/<PROFILE>/SOURCE/*/webpack.config.*
+|   Search: accounts/<PROFILE>/SOURCE/*/@types/mystique/
+|   List found projects with their registered components
+|
++-- 2. Check deployed plugins in live manifests
+|   Look for plugins[] array entries in deployed manifests
+|   Cross-reference with local SOURCE/
+|
++-- 3. Evaluate: does the new component fit an existing project?
+|   +-- YES -> Add component to existing project (just generate component files)
+|   +-- NO -> Genuinely new domain, proceed with full scaffolding
+|   +-- UNCLEAR -> Ask user
+```
+
+### Source Code Availability Check
+
+Before extending an existing project, verify the source is accessible:
+
+| Source State | Action |
+|---|---|
+| `accounts/<PROFILE>/SOURCE/<project>/` exists with `package.json` + `@types/mystique/` | Ready -- add component files directly |
+| Plugin deployed but no source in `SOURCE/` | Ask user to clone repo into `SOURCE/` |
+| Source exists but registered components unknown | Read `src/index.tsx` to discover existing registrations |
+
+## 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** (SDK component + manifest + workflows + settings): 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 sections
+4. **If standalone SDK project work with no plan:** Continue to the Planning Gate below to write a plan for this skill
+
+**After the pre-check determines a NEW project is needed, write a plan.** Same pattern as `/fluent-module-scaffold`.
+
+**Mystique-scaffold specific emphasis -- ensure these are covered:**
+
+1. **Component inventory** -- names, aliases, categories, props interface for each component
+2. **Data dependencies** -- what GraphQL entities/queries each component will need
+3. **Styling approach** -- Material-UI theme extension or custom CSS via Emotion
+4. **Integration points** -- which manifest pages will use these components
+5. **Testing strategy** -- unit tests, Storybook stories, Cypress E2E
+6. **Hosting strategy** -- where the production bundle will be deployed (Vercel, S3, CDN)
+
+**Write the plan to:** `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-mystique-scaffold-<slug>.md`. Set `Status: PENDING`.
+
+Present the full plan content to the user and wait for approval before generating any files. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
+
+## Handoff Protocol
+
+### Signals emitted by this skill
+
+| Signal | Condition | Example |
+|--------|-----------|---------|
+| `-> READY: <path>` | Project directory scaffolded | `-> READY: accounts/SAGIRISH/SOURCE/mystique-plugin-curbside/` |
+| `-> NEXT: /fluent-<skill>` | Ready for manifest wiring | `-> NEXT: /fluent-mystique-builder` |
+| `-> BLOCKED: <reason>` | Cannot proceed | `-> BLOCKED: PLAN_REQUIRED -- Write a plan via /fluent-feature-plan` |
+| `-> SKIP: <reason>` | Existing project covers the domain | `-> SKIP: Extend existing project mystique-plugin-hm. Add component files directly` |
+
+### Error codes
+
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| `PLAN_REQUIRED` | Scaffolding attempted without approved plan | Run `/fluent-feature-plan` first |
+| `VALIDATION_FAILED` | Project name conflicts or invalid component names | Fix input parameters |
+
+## When to Use
+
+- Creating a brand-new Mystique SDK component project from scratch
+- Starting a greenfield UI plugin that needs webpack, TypeScript, Storybook, Jest, and component registration
+- Bootstrapping a component project for a new feature requiring custom UI beyond built-in `fc.*` components
+- Generating a project shell to be populated incrementally with new components
+
+## Ownership Boundary
+
+This skill owns:
+
+- Creating the complete SDK project directory structure
+- Generating `package.json` with correct dependencies and scripts
+- Generating `webpack.config.ts` with proper externals (React, ReactDOM, Material-UI, Mystique)
+- Generating `tsconfig.json` with strict TypeScript configuration
+- Generating `jest.config.js` with ts-jest, mocks, and coverage thresholds
+- Generating `.babelrc` with React/TypeScript/Emotion presets
+- Copying `@types/mystique/` type definitions (7 files)
+- Generating `lib/` SDK initialization files (init.js, mystique.js, mystique-export.js, material-ui.js)
+- Generating Storybook configuration (`.storybook/main.ts`, `preview.js`, `helpers.ts`)
+- Generating component files with test and story for each `--components` entry
+- Generating `src/index.tsx` with ComponentRegistry registrations
+- Generating example manifest in `manifests/`
+- Generating `src/index.html` for dev server
+- Generating `.gitignore`, `.eslintrc.js`
+
+This skill does **not** own:
+
+- Creating or editing Mystique manifests --> `/fluent-mystique-builder`
+- Validating manifest JSON --> `/fluent-mystique-validate`
+- Analyzing existing manifests --> `/fluent-mystique-analyze`
+- Deploying manifests as settings --> `/fluent-settings`
+- Building/deploying Java modules --> `/fluent-build`, `/fluent-module-deploy`
+
+## Inputs
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `project-name` | Yes | -- | Project directory name (e.g., `mystique-plugin-curbside`). Used for directory name and package.json name. Lowercase alphanumeric with hyphens. |
+| `--components` | No | -- | Comma-separated PascalCase component names to scaffold (e.g., `OrderTracker,StoreMap`). Each gets a `.tsx`, `.test.tsx`, `.stories.tsx`, and `index.ts`. |
+| `--category` | No | `content` | Default component category for ComponentRegistry registration. Valid: `page`, `layout`, `content`, `filter`. |
+| `--namespace` | No | Auto-detect from project name | Component alias prefix (e.g., `acme` produces aliases like `acme.content.order-tracker`). |
+| `--profile` | No | Active profile | Fluent CLI profile for path resolution |
+
+## Pre-Check: Project Already Exists?
+
+Before creating anything, check if the target directory already exists:
+
+```
+accounts/<PROFILE>/SOURCE/<project-name>/
+```
+
+If it exists, **abort** with message:
+```
+Project directory already exists: accounts/<PROFILE>/SOURCE/<project-name>/
+Use this skill with --components to add components to the existing project, or choose a different name.
+```
+
+## Namespace Detection
+
+The namespace is used in ComponentRegistry aliases following the pattern `<namespace>.<category>.<kebab-name>`. Detection order:
+
+```
+1. If --namespace provided, use it directly
+
+2. Else derive from project-name:
+   mystique-plugin-curbside    -> curbside
+   mystique-plugin-hm-custom   -> hm
+   fluent-component-acme       -> acme
+   Strip "mystique-plugin-" or "fluent-component-" prefix, take first word
+
+3. Fallback: "custom"
+   Warn user: "Could not derive namespace. Components will use 'custom.*' aliases."
+```
+
+## Generated Directory Structure
+
+```
+accounts/<PROFILE>/SOURCE/<project-name>/
++-- package.json                    # Dependencies, scripts, browserslist
++-- tsconfig.json                   # TypeScript config (strict mode, ES6 target)
++-- webpack.config.ts               # Bundle output with content hash, externals
++-- jest.config.js                  # Jest with ts-jest, coverage thresholds
++-- .babelrc                        # Babel presets for React/TypeScript/Emotion
++-- .eslintrc.js                    # ESLint config for TypeScript + React
++-- .gitignore
++-- sdk-version.json                # SDK version tracking
++-- .storybook/
+|   +-- main.ts                     # Storybook webpack config with externals
+|   +-- preview.js                  # Decorators, viewport config
+|   +-- helpers.ts                  # Story template utility
+|   +-- Storyshots.test.ts          # Snapshot testing for stories
++-- @types/
+|   +-- images.d.ts                 # Image import declarations
+|   +-- mystique/                   # Mystique SDK type definitions
+|       +-- index.d.ts              # Common types (QueryResponse, Connection, Edge)
+|       +-- manifest.d.ts           # Full manifest schema types (MystiqueManifest, Route, Page, Section)
+|       +-- components.d.ts         # Component prop interfaces (Card, List, Children, DynamicValue, Loading)
+|       +-- hooks.d.ts              # Hook definitions (useAuth, useQuery, useSettings, useI18n, useData, useRest, useUserActions)
+|       +-- services.d.ts           # Service types (MystiqueThemeColours)
+|       +-- registry.d.ts           # Registry interfaces (ComponentRegistry, FieldRegistry, TemplateRegistry)
+|       +-- frame.d.ts              # Modal/Drawer/Toast utilities (pushModal, pushDrawer, pushToast)
++-- i18n/
+|   +-- locales/
+|       +-- en/
+|           +-- translation.json    # Initial i18n keys
++-- lib/
+|   +-- init.js                     # Global setup: React, ReactDOM, MaterialUI, Emotion on globalThis
+|   +-- material-ui.js              # MaterialUI UMD global (bundled for Storybook/Jest)
+|   +-- mystique.js                 # Mystique global object (bundled for Storybook/Jest)
+|   +-- mystique-export.js          # Named exports from globalThis.Mystique for import resolution
++-- src/
+|   +-- index.tsx                   # Entry point -- ComponentRegistry.register() calls
+|   +-- index.html                  # Dev server HTML with CDN React/ReactDOM
+|   +-- setup-tests.ts              # Jest setup (Emotion matchers)
+|   +-- components/
+|   |   +-- <ComponentName>/
+|   |       +-- <ComponentName>.tsx       # Component implementation
+|   |       +-- <ComponentName>.test.tsx  # Unit test
+|   |       +-- <ComponentName>.stories.tsx  # Storybook story
+|   |       +-- index.ts                  # Re-export
+|   +-- utils/
+|       +-- GqlUtils.ts             # GraphQL document-to-string utility
+|       +-- TestUtils.tsx           # MaterialUI classname fix for test snapshots
++-- manifests/
+|   +-- fc.mystique.manifest.example.ts         # Example full manifest
+|   +-- fc.mystique.manifest.fragment.example.ts # Example fragment manifest
++-- build/
+|   +-- GenerateVersionPlugin.ts    # Webpack plugin: emits version.json with bundle path
+|   +-- GenerateManifestsPlugin.ts  # Webpack plugin: compiles manifest .ts to .json in dist/
++-- cypress/                        # (empty scaffold, ready for E2E tests)
+|   +-- cypress.json
++-- dist/                           # (empty, webpack output directory)
+```
+
+## File Templates
+
+### package.json
+
+```json
+{
+  "name": "${PROJECT_NAME}",
+  "version": "1.0.0",
+  "description": "Mystique SDK Plugin - ${PROJECT_TITLE}",
+  "main": "index.js",
+  "scripts": {
+    "start": "webpack serve --mode development --open --hot --port 3001",
+    "build": "webpack --mode production && jest ./build",
+    "bundle": "webpack",
+    "test": "jest --coverage --testPathIgnorePatterns ./build/**",
+    "test:bail": "jest --bail --testPathIgnorePatterns ./build/**",
+    "test:storybook": "start-storybook --smoke-test",
+    "check-types": "tsc",
+    "storybook": "start-storybook -p 6006 -s ./lib",
+    "storybook:build": "build-storybook -o dist/_storybook && cp ./lib/*.js ./dist/_storybook",
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:fix": "yarn run lint -- --fix"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.13.8",
+    "@babel/plugin-proposal-class-properties": "^7.12.1",
+    "@babel/plugin-proposal-object-rest-spread": "^7.12.1",
+    "@babel/preset-env": "^7.13.9",
+    "@babel/preset-react": "^7.12.10",
+    "@babel/preset-typescript": "^7.12.7",
+    "@emotion/babel-preset-css-prop": "^11.10.0",
+    "@emotion/eslint-plugin": "^11.10.0",
+    "@emotion/jest": "^11.10.0",
+    "@emotion/react": "^11.10.0",
+    "@storybook/addon-actions": "6.5.12",
+    "@storybook/addon-essentials": "6.5.12",
+    "@storybook/addon-links": "6.5.12",
+    "@storybook/addon-storyshots": "6.5.12",
+    "@storybook/builder-webpack5": "6.5.12",
+    "@storybook/core-common": "6.5.12",
+    "@storybook/manager-webpack5": "6.5.12",
+    "@storybook/react": "6.5.12",
+    "@testing-library/dom": "^7.31.2",
+    "@testing-library/jest-dom": "^5.11.9",
+    "@testing-library/react": "^11.2.5",
+    "@testing-library/react-hooks": "^5.1.1",
+    "@testing-library/user-event": "^13.1.9",
+    "@types/jest": "^26.0.20",
+    "@types/lodash": "^4.14.167",
+    "@types/material-ui": "^0.21.8",
+    "@types/node": "^18.7.14",
+    "@types/react": "^17.0.0",
+    "@types/react-dom": "^17.0.0",
+    "@types/testing-library__jest-dom": "^5.14.0",
+    "@types/webpack": "^5.0.0",
+    "@types/webpack-dev-server": "^3.11.3",
+    "@typescript-eslint/eslint-plugin": "^4.28.0",
+    "@typescript-eslint/parser": "^4.28.0",
+    "babel-jest": "^26.6.3",
+    "babel-loader": "^8.2.2",
+    "copy-webpack-plugin": "^9.0.1",
+    "eslint": "^7.29.0",
+    "eslint-plugin-no-only-tests": "^2.6.0",
+    "eslint-plugin-react": "^7.24.0",
+    "eslint-plugin-react-hooks": "^4.2.0",
+    "graphql": "^15.4.0",
+    "graphql-tag": "^2.12.4",
+    "html-webpack-plugin": "^5.3.1",
+    "jest": "^26.6.3",
+    "jest-fetch-mock": "^3.0.3",
+    "jest-html-reporter": "^3.3.0",
+    "lodash": "^4.17.21",
+    "react-test-renderer": "^17.0.2",
+    "ts-jest": "^26.5.2",
+    "typescript": "^4.1.3",
+    "url-loader": "^4.1.1",
+    "webpack": "^5.74.0",
+    "webpack-cli": "^4.10.0",
+    "webpack-dev-server": "^4.10.0"
+  },
+  "dependencies": {
+    "@material-ui/core": "4.12.1",
+    "@material-ui/pickers": "^3.3.10",
+    "qs": "^6.10.1",
+    "react": "^17.0.1",
+    "react-dom": "^17.0.1"
+  },
+  "browserslist": {
+    "production": [">0.2%", "not dead", "not op_mini all"],
+    "development": ["last 1 chrome version", "last 1 firefox version", "last 1 safari version"]
+  }
+}
+```
+
+**Important notes about dependencies:**
+- `react`, `react-dom`, and `@material-ui/core` are listed as `dependencies` but are treated as webpack **externals** -- they are NOT bundled into the output. They exist in `dependencies` for TypeScript type resolution and for Storybook/Jest test execution.
+- The host Fluent OMX application provides React 17, ReactDOM 17, and Material-UI 4.12 at runtime via `window.React`, `window.ReactDOM`, and `window.MaterialUI` globals.
+- Storybook version is pinned to 6.5.12 for compatibility with the Mystique SDK.
+
+### webpack.config.ts
+
+This is the most critical file -- it controls how the bundle is produced and what is externalized.
+
+```typescript
+const path = require('path');
+import { Configuration } from 'webpack';
+import HtmlWebpackPlugin from 'html-webpack-plugin';
+const GenerateVersionPlugin = require('./build/GenerateVersionPlugin');
+const GenerateManifestsPlugin = require('./build/GenerateManifestsPlugin');
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+
+const config: Configuration = {
+
+  // Entry point -- all ComponentRegistry.register() calls happen here
+  entry: './src/index',
+
+  devServer: {
+    allowedHosts: 'all',
+    static: {
+      directory: path.resolve(__dirname, 'dist'),
+      watch: true,
+    },
+    headers: {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
+      'Access-Control-Allow-Headers': 'X-Requested-With, content-type, Authorization',
+    },
+  },
+
+  // Output: bundle.[contenthash].js for cache busting
+  output: {
+    path: path.join(__dirname, '/dist'),
+    clean: true,
+    filename: 'bundle.[contenthash].js',
+  },
+
+  resolve: {
+    extensions: ['.ts', '.tsx', '.js'],
+  },
+
+  module: {
+    rules: [
+      {
+        test: /\.(ts|js)x?$/,
+        exclude: /node_modules/,
+        use: {
+          loader: 'babel-loader',
+        },
+      },
+      {
+        test: /\.(png|jp(e*)g|svg)$/,
+        use: [{
+          loader: 'url-loader',
+          options: {
+            limit: 8000,
+            name: 'images/[hash]-[name].[ext]',
+          },
+        }],
+      },
+    ],
+  },
+  plugins: [
+    new HtmlWebpackPlugin({
+      template: './src/index.html',
+    }),
+    new CopyWebpackPlugin({
+      patterns: [
+        {
+          from: 'i18n/locales',
+          to: path.join(__dirname, 'dist/i18n'),
+        },
+      ],
+    }),
+    new GenerateVersionPlugin(),
+    new GenerateManifestsPlugin(),
+  ],
+
+  // CRITICAL: externals configuration
+  // React, ReactDOM, Emotion, Material-UI, and Mystique are provided by the host app
+  // They must NOT be bundled -- the bundle uses window globals at runtime
+  externals: [{
+    'react': 'React',
+    'react-dom': 'ReactDOM',
+    '@emotion/react': 'emotionReact',
+  },
+  externalMaterialUI,
+  externalMystique,
+  ],
+};
+
+/** Re-route @material-ui/core imports to the global UMD import */
+export function externalMaterialUI (_: any, module: any, callback: any): any {
+  if (module === '@material-ui/core') {
+    return callback(null, `window["MaterialUI"]`);
+  }
+  const isMaterialUIComponent = /^@material-ui\/core\/.+$/;
+  const match = isMaterialUIComponent.exec(module);
+  if (match !== null) {
+    const parts = module.split('/');
+    const component = parts[parts.length - 1];
+    if (component === 'styles') {
+      return callback(null, `window["MaterialUI"]`);
+    }
+    return callback(null, `window["MaterialUI"].${component}`);
+  }
+  callback();
+}
+
+/** Re-route mystique/* imports to the global Mystique object */
+export function externalMystique (_: any, module: any, callback: any): any {
+  const isMystiqueComponent = /^mystique\/.+$/;
+  const match = isMystiqueComponent.exec(module);
+  if (match !== null) {
+    return callback(null, `window["Mystique"]`);
+  }
+  callback();
+}
+
+export default config;
+```
+
+**Key points about the webpack config:**
+- `CORS headers` on devServer are required so the Fluent OMX host app (running on a different port/domain) can load the bundle.
+- `contenthash` in the filename enables cache busting in production.
+- The `GenerateVersionPlugin` emits a `version.json` that maps the hashed bundle filename, enabling the host app to auto-discover the current bundle.
+- The `GenerateManifestsPlugin` compiles `.ts` manifest files under `manifests/` into `.json` in `dist/manifests/`.
+- The three external handlers ensure ZERO framework code ends up in the bundle. The host OMX app provides everything via `window` globals.
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "es6",
+    "outDir": "./dist/",
+    "strictNullChecks": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "noEmit": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "@emotion/react",
+    "baseUrl": "./src",
+    "lib": ["es2015", "dom.iterable", "es2016.array.include", "es2017.object", "dom"],
+    "types": ["node", "jest", "@testing-library/jest-dom"],
+    "typeRoots": ["./node_modules/@types", "./@types/**/*"],
+    "module": "es6",
+    "removeComments": true,
+    "alwaysStrict": true,
+    "allowUnreachableCode": false,
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "importHelpers": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*", "manifests/**/*", "@types/**/*", "./@types"],
+  "exclude": ["node_modules", "./node_modules", "./node_modules/*", "./node_modules/@types/node/index.d.ts"]
+}
+```
+
+**Key: `jsxImportSource: "@emotion/react"`** enables Emotion CSS-in-JS props on JSX elements. The `typeRoots` includes `./@types/**/*` which is where the Mystique type definitions live.
+
+### jest.config.js
+
+```javascript
+const path = require('path');
+
+module.exports = {
+    restoreMocks: true,
+    roots: [
+        "<rootDir>"
+    ],
+    setupFilesAfterSetup: ['./src/setup-tests.ts'],
+    setupFiles: [
+        "./lib/material-ui.js",
+        "./lib/init.js",
+        "./lib/mystique.js",
+    ],
+    testMatch: [
+        "**/?(*.)+(test).+(ts|tsx)"
+    ],
+    coverageThreshold: {
+        global: {
+            statements: 80,
+            branches: 80,
+            functions: 80,
+            lines: 80
+        }
+    },
+    coveragePathIgnorePatterns: [
+        ".storybook/",
+        "src/index.tsx",
+        '.stories.'
+    ],
+    collectCoverageFrom: [
+        "src/**/*.{ts,tsx}"
+    ],
+    preset: 'ts-jest',
+    transform: {
+        '^.+\\.(ts|tsx)?$': 'ts-jest',
+        "^.+\\.(js|jsx)$": "babel-jest",
+    },
+    moduleNameMapper: {
+        "\\.(jpg|ico|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$": "identity-obj-proxy",
+        "\\.(css|less)$": "identity-obj-proxy",
+        "^./react": path.resolve(__dirname, 'node_modules/react'),
+        "^mystique": path.resolve(__dirname, 'lib/mystique-export.js')
+    },
+    reporters: [
+        "default",
+        ["./node_modules/jest-html-reporter", {
+            "pageTitle": "Test Report",
+            "outputPath": "./test-report/test-report.html"
+        }]
+    ],
+};
+```
+
+**Critical: `setupFiles`** loads `lib/material-ui.js`, `lib/init.js`, and `lib/mystique.js` before tests run. These files set up the global objects (`window.React`, `window.MaterialUI`, `window.Mystique`) that the webpack externals resolve to at runtime. The `moduleNameMapper` for `^mystique` redirects Mystique module imports to `lib/mystique-export.js` which provides named exports from the global Mystique object.
+
+### .babelrc
+
+```json
+{
+  "presets": [
+    "@babel/preset-env",
+    "@babel/preset-typescript",
+    [
+      "@babel/preset-react",
+      {
+        "runtime": "automatic"
+      }
+    ],
+    "@emotion/babel-preset-css-prop"
+  ],
+  "plugins": ["@emotion", "@babel/proposal-class-properties", "@babel/proposal-object-rest-spread"]
+}
+```
+
+### lib/init.js
+
+Sets up global objects that the webpack externals resolve to. Required for both Jest tests and the dev server HTML page.
+
+```javascript
+import fetchMock from 'jest-fetch-mock';
+fetchMock.enableMocks();
+
+import React from 'react';
+globalThis.React = React;
+
+import ReactDOM from 'react-dom';
+globalThis.ReactDOM = ReactDOM;
+
+import * as MaterialUI from '@material-ui/core';
+globalThis.MaterialUI = MaterialUI;
+
+import * as Emotion from '@emotion/react';
+globalThis.emotionReact = Emotion;
+```
+
+### lib/mystique-export.js
+
+Provides named exports from the global `Mystique` object. This file is what `moduleNameMapper` in Jest points `mystique/*` imports to, and what makes hook/component imports work in tests.
+
+```javascript
+const m = globalThis.Mystique;
+
+// registry
+export const ComponentRegistry = m.ComponentRegistry;
+export const FieldRegistry = m.FieldRegistry;
+
+// frame
+export const DataModal = m.DataModal;
+export const pushModal = m.pushModal;
+export const pushDrawer = m.pushDrawer;
+export const pushToast = m.pushToast;
+
+// hooks
+export const useAuth = m.useAuth;
+export const useI18n = m.useI18n;
+export const useSettings = m.useSettings;
+export const useQuery = m.useQuery;
+export const useMutation = m.useMutation;
+export const useRest = m.useRest;
+export const getQuery = m.getQuery;
+export const getRest = m.getRest;
+
+// components
+export const Card = m.Card;
+export const CardContent = m.CardContent;
+export const Children = m.Children;
+export const DynamicValue = m.DynamicValue;
+export const Loading = m.Loading;
+export const QuantitySelectorComponent = m.QuantitySelectorComponent;
+export const QuantityList = m.QuantityList;
+
+// utils
+export const decorateQueryResult = m.decorateQueryResult;
+```
+
+### lib/mystique.js and lib/material-ui.js
+
+These are large bundled files from the Fluent Commerce SDK distribution. They set up `globalThis.Mystique` and `globalThis.MaterialUI` respectively. **Do NOT generate these files** -- they must be copied from the reference SDK at `OMX Mystique components/omx-component-sdk/omx-component-sdk/lib/`. If the reference SDK is not available locally, warn the user:
+
+```
+WARNING: lib/mystique.js and lib/material-ui.js are required but cannot be auto-generated.
+These files must be obtained from the Fluent Commerce OMX Component SDK distribution.
+Copy them from: OMX Mystique components/omx-component-sdk/omx-component-sdk/lib/
+Without these files, Jest tests and Storybook will fail (missing global Mystique/MaterialUI objects).
+```
+
+### src/index.tsx (Entry Point)
+
+This is the entry point for the webpack bundle. All component registrations happen here.
+
+```tsx
+import { ComponentRegistry } from 'mystique/registry/ComponentRegistry';
+// Import each component
+import { ${ComponentName} } from './components/${ComponentName}/${ComponentName}';
+
+// Register with Mystique -- aliases are how the manifest references this component
+// Convention: <namespace>.<category>.<kebab-name>
+ComponentRegistry.register(
+  ['${NAMESPACE}.${CATEGORY}.${KEBAB_NAME}'],
+  ${ComponentName},
+  { category: '${CATEGORY}' }
+);
+```
+
+**Alias naming convention:** `<namespace>.<category>.<component-name>` where:
+- `namespace` is the company/project prefix (e.g., `acme`, `hm`, `curbside`)
+- `category` is one of `page`, `layout`, `content`, `filter`
+- `component-name` is kebab-case (e.g., `order-tracker`, `store-map`)
+
+Multiple aliases can be registered for the same component for backward compatibility.
+
+### src/index.html (Dev Server)
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${PROJECT_TITLE} - Mystique Plugin</title>
+    <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/react/17.0.1/umd/react.production.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/react-dom/17.0.1/umd/react-dom.production.min.js"></script>
+    <style>
+        body { display:flex; flex-direction: column; align-items: center; justify-content: center; background-color:#efefef; font-family: 'Lato', sans-serif; }
+        #root { width: 600px; max-width:90%; padding: 4em 2em 2em 2em; }
+    </style>
+</head>
+<body>
+    <div id="root">
+        <p>Welcome to the ${PROJECT_TITLE} Mystique Plugin!</p>
+        <p>Add this plugin to your Fluent OMX app manifest:</p>
+        <pre>
+{
+  "plugins": [
+    { "type": "url", "src": "http://localhost:3001" }
+  ]
+}
+        </pre>
+    </div>
+</body>
+</html>
+```
+
+### src/setup-tests.ts
+
+```typescript
+import { matchers } from '@emotion/jest';
+
+expect.extend(matchers);
+```
+
+### src/utils/TestUtils.tsx
+
+Provides consistent Material-UI classname generation for snapshot tests.
+
+```tsx
+import { FC } from 'react';
+import { StylesProvider, StylesOptions } from '@material-ui/styles';
+
+const generateClassName: StylesOptions['generateClassName'] = (
+  rule,
+  sheet,
+): string => `${sheet!.options.classNamePrefix}-${rule.key}`;
+
+/**
+ * Provides consistent classname generation for MaterialUI components to avoid inconsistent snapshots.
+ */
+export const FixMuiClassnames: FC = ({ children }) => {
+  return (
+    <StylesProvider generateClassName={generateClassName}>
+      {children}
+    </StylesProvider>
+  );
+};
+```
+
+### src/utils/GqlUtils.ts
+
+```typescript
+import { DocumentNode } from 'graphql';
+import { print } from 'graphql/language/printer';
+
+/**
+ * Converts a GraphQL document node back to a query string.
+ * Useful for defining queries with gql`` template literals in manifests
+ * and converting them to strings for the manifest JSON output.
+ */
+export const parse = (doc: DocumentNode) => print(doc);
+```
+
+## Component Template
+
+For each component in `--components`, generate the following files:
+
+### Component File (`src/components/<Name>/<Name>.tsx`)
+
+```tsx
+import React from 'react';
+import { Card } from 'mystique/components/Card';
+import { CardContent } from 'mystique/components/CardContent';
+import { StdProps } from 'mystique/registry/ComponentRegistry';
+
+/**
+ * Props for the ${Name} component.
+ * Extends StdProps to receive injected data from the page query via dataSource.
+ */
+export interface ${Name}Props extends StdProps {
+  /**
+   * Component title displayed in the card header.
+   */
+  title?: string;
+  // TODO: Define component-specific props
+}
+
+/**
+ * ${Name} -- a custom Mystique component.
+ *
+ * Usage in manifest:
+ *   { "component": "${NAMESPACE}.${CATEGORY}.${KEBAB_NAME}", "props": { "title": "My Title" } }
+ */
+export const ${Name}: React.FC<${Name}Props> = ({ data, title = '${Name}', ...props }) => {
+  return (
+    <Card title={title}>
+      <CardContent>
+        <p data-testid="${KEBAB_NAME}-content">
+          {/* TODO: Implement component using data from props.data */}
+          {data ? JSON.stringify(data) : 'No data available'}
+        </p>
+      </CardContent>
+    </Card>
+  );
+};
+```
+
+### Test File (`src/components/<Name>/<Name>.test.tsx`)
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { ${Name} } from './${Name}';
+
+describe('${Name}', () => {
+  it('renders without crashing', () => {
+    render(<${Name} />);
+    expect(screen.getByTestId('${KEBAB_NAME}-content')).toBeInTheDocument();
+  });
+
+  it('displays title prop', () => {
+    const { container } = render(<${Name} title="Custom Title" />);
+    expect(container.textContent).toContain('Custom Title');
+  });
+
+  it('renders data when provided', () => {
+    const mockData = { id: '123', ref: 'TEST-001' };
+    render(<${Name} data={mockData} />);
+    expect(screen.getByTestId('${KEBAB_NAME}-content').textContent).toContain('TEST-001');
+  });
+});
+```
+
+### Story File (`src/components/<Name>/<Name>.stories.tsx`)
+
+```tsx
+import { ComponentMeta } from '@storybook/react';
+import { storyTemplate } from '../../../.storybook/helpers';
+import { ${Name} } from './${Name}';
+
+export default {
+  title: 'Components/${Name}',
+  component: ${Name},
+} as ComponentMeta<typeof ${Name}>;
+
+const template = storyTemplate(${Name});
+
+export const Default = template({
+  title: '${Name} Component',
+});
+
+export const WithData = template({
+  title: '${Name} with Data',
+  data: {
+    id: '1',
+    ref: 'EXAMPLE-001',
+    status: 'ACTIVE',
+  },
+});
+```
+
+### Index File (`src/components/<Name>/index.ts`)
+
+```typescript
+export { ${Name} } from './${Name}';
+export type { ${Name}Props } from './${Name}';
+```
+
+## Storybook Configuration
+
+### .storybook/main.ts
+
+```typescript
+import { StorybookConfig } from '@storybook/core-common';
+import { externalMaterialUI, externalMystique } from '../webpack.config';
+
+const config: StorybookConfig = {
+  webpackFinal: async (config: any) => {
+    config.externals = [{
+      'react': 'React',
+      'react-dom': 'ReactDOM',
+    },
+      externalMaterialUI,
+      externalMystique
+    ];
+    return config;
+  },
+  stories: [
+    '../src/**/*.stories.mdx',
+    '../src/**/*.stories.@(ts|tsx)'
+  ],
+  addons: [
+    '@storybook/addon-links',
+    '@storybook/addon-essentials'
+  ],
+  core: {
+    builder: 'webpack5'
+  }
+};
+
+module.exports = config;
+```
+
+### .storybook/preview.js
+
+```javascript
+import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
+import { FixMuiClassnames } from '../src/utils/TestUtils';
+
+export const parameters = {
+  actions: { argTypesRegex: "^on[A-Z].*" },
+  viewport: {
+    defaultViewport: 'iphone5',
+    viewports: INITIAL_VIEWPORTS
+  },
+};
+
+export const decorators = [
+  (Story) => (
+    <FixMuiClassnames>
+      <Story />
+    </FixMuiClassnames>
+  )
+];
+```
+
+### .storybook/helpers.ts
+
+```typescript
+import { ComponentStory, Story } from '@storybook/react';
+
+export const storyTemplate = <P,>(Component: (props: P) => any) => (
+  props: P
+): Story<P> => {
+  const template: ComponentStory<typeof Component> = (args) => Component(args);
+  const story = template.bind({});
+  story.args = props;
+  return story;
+};
+```
+
+## @types/mystique/ Type Definitions
+
+The `@types/mystique/` directory contains 7 TypeScript declaration files that define the Mystique SDK API surface. These must be copied from the reference SDK or generated from the templates below.
+
+| File | Purpose |
+|------|---------|
+| `index.d.ts` | Common types: `TranslatableString`, `QueryResponse<T>`, `Connection<T>`, `Edge<T>` |
+| `manifest.d.ts` | Full manifest v2.0 schema: `MystiqueManifest`, `MystiqueSection`, `MystiquePage`, `MystiqueComponentInstance`, `MystiquePlugin`, `MystiqueManifestFragment`, `GQLQuery` |
+| `components.d.ts` | Component prop interfaces: `Card`, `CardContent`, `Children`, `DynamicValue`, `Loading`, `List`, `QuantityList`, `QuantitySelectorComponent`, `DatePicker` |
+| `hooks.d.ts` | Hook definitions: `useAuth`, `useEnv`, `useI18n`, `useSettings`, `useQuery`, `getQuery`, `useRest`, `getRest`, `useData`, `useUserActions`, `useUserActionForm`, `getApiDownload`, `getSettings` |
+| `services.d.ts` | Service types: `MystiqueThemeColours` (color palette interface for theming) |
+| `registry.d.ts` | Registry interfaces: `ComponentRegistry` (register/get components), `FieldRegistry` (register/get form fields), `TemplateRegistry` (register/render Handlebars helpers) |
+| `frame.d.ts` | Frame utilities: `pushModal`, `pushDrawer`, `pushToast`, `DataModal`, `clearModals`, `clearDrawers` |
+
+**These type definitions are the contract between your component code and the Mystique host application.** They provide full IntelliSense in the IDE for all Mystique hooks, components, and registries. The actual implementations are provided at runtime by the host app via `window.Mystique`.
+
+## React Hooks Usage Patterns
+
+The Mystique SDK provides hooks via `import { useAuth, useQuery, ... } from 'mystique/hooks'`. All hooks are provided by the host app at runtime.
+
+### useAuth — Authentication and Context
+
+```typescript
+import { useAuth } from 'mystique/hooks';
+
+const MyComponent = () => {
+  const auth = useAuth();
+  // auth.username: string — current user's login name
+  // auth.firstName, auth.lastName: string
+  // auth.timezone: string — user's timezone (e.g., 'Australia/Sydney')
+  // auth.language: string — user's locale (e.g., 'en')
+  // auth.roles: Array<{ name: string }> — assigned roles
+  // auth.contextId: number — current retailer/location context ID
+  // auth.contextType: string — 'RETAILER' | 'LOCATION'
+  // auth.switchContext(contextId, contextType) — switch retailer/location
+  // auth.logout() — end session
+
+  const isAdmin = auth.roles.some(r => r.name === 'ADMIN');
+  return isAdmin ? <AdminPanel /> : <StandardView />;
+};
+```
+
+### useQuery — GraphQL Data Fetching
+
+```typescript
+import { useQuery } from 'mystique/hooks';
+
+const OrderDetail = ({ orderId }: { orderId: string }) => {
+  const [result, { loading, error, refetch }] = useQuery(
+    `query OrderById($id: ID!) { orderById(id: $id) { id ref status type createdOn } }`,
+    { id: orderId }
+  );
+
+  if (loading) return <Loading />;
+  if (error) return <div>Error: {error.message}</div>;
+
+  const order = result?.orderById;
+  // Connection/pagination pattern:
+  // result.orders.edges[].node — array of entities
+  // result.orders.pageInfo.hasNextPage — boolean
+  // result.orders.pageInfo.endCursor — cursor for next page
+  return <div>{order.ref} — {order.status}</div>;
+};
+```
+
+### useSettings — Hierarchical Settings Access
+
+```typescript
+import { useSettings } from 'mystique/hooks';
+
+const ConfiguredComponent = () => {
+  const settings = useSettings(['fc.myFeature.enabled', 'fc.myFeature.maxItems']);
+  // Settings cascade: Location > Retailer > Account > Global (most specific wins)
+  // Each key returns: { status: 'loading' | 'error' | 'success', result?: { value: string } }
+
+  const featureEnabled = settings['fc.myFeature.enabled'];
+  if (featureEnabled.status === 'loading') return <Loading />;
+  const enabled = featureEnabled.result?.value === 'true';
+  return enabled ? <FeatureUI /> : null;
+};
+```
+
+### useI18n — Internationalization
+
+```typescript
+import { useI18n } from 'mystique/hooks';
+
+const TranslatedComponent = () => {
+  const { translate, translateOr } = useI18n();
+
+  // translate(key) — single key lookup, returns key if not found
+  const title = translate('fc.om.orders.title');
+
+  // translateOr([key1, key2, ..., fallback]) — try keys in order, last is fallback
+  const label = translateOr(['fc.custom.order.label', 'fc.om.orders.label', 'Orders']);
+
+  return <h1>{title}</h1>;
+};
+```
+
+### useData — Page Query Data Access
+
+```typescript
+import { useData } from 'mystique/hooks';
+
+const PageComponent = () => {
+  const data = useData();
+  // data — contains the response from the page-level GraphQL query
+  // In a list page: data.orders.edges, data.orders.pageInfo
+  // In a detail page: data.orderById.ref, data.orderById.status
+  // Variables and filters are managed by the host app
+  return <span>{data?.orderById?.ref}</span>;
+};
+```
+
+### useEnv — Environment Details
+
+```typescript
+import { useEnv } from 'mystique/hooks';
+
+const DebugInfo = () => {
+  const env = useEnv();
+  // env.accountName: string — Fluent account name
+  // env.appName: string — 'oms', 'store', 'servicepoint'
+  // env.apiEndpoint: string — API base URL
+  return <span>Connected to {env.accountName}</span>;
+};
+```
+
+## Component Composition Primitives
+
+Three essential patterns for building reusable, manifest-configurable custom components.
+
+### DynamicValue — Manifest-Configurable Content
+
+`DynamicValue` renders a single dynamic attribute (text, image, or component) from manifest config. Lets manifest configurers control what your component displays without code changes.
+
+```typescript
+import { DynamicValue } from 'mystique/components';
+
+const OrderCard = ({ data, props }) => {
+  // props.attributes comes from the manifest's attributes[] array
+  return (
+    <div>
+      {props.attributes?.map((attr, i) => (
+        <div key={i}>
+          <label>{attr.label}</label>
+          <DynamicValue attribute={attr} context={data} defaultValue={<span>-</span>} />
+        </div>
+      ))}
+    </div>
+  );
+};
+```
+
+### Children — Manifest-Driven Composition
+
+`Children` renders descendant components configured in the manifest. Lets configurers place OOTB or custom components inside your component via `descendants`.
+
+```typescript
+import { Children } from 'mystique/components';
+
+const Panel = ({ data, children }) => {
+  return (
+    <div className="custom-panel">
+      <Children />  {/* renders all descendants from manifest */}
+    </div>
+  );
+};
+
+// Wrapper variant: transform data for all descendants
+const FilteredPanel = ({ data }) => {
+  const filteredData = data.items.filter(i => i.status === 'ACTIVE');
+  return (
+    <div>
+      <Children dataOverride={filteredData} />
+    </div>
+  );
+};
+```
+
+### TemplateRegistry.render — Resolve Templates in Code
+
+Use `TemplateRegistry.render()` to resolve Handlebars template strings inside component code.
+
+```typescript
+import { TemplateRegistry } from 'mystique/registry';
+
+const CustomDisplay = ({ data, props }) => {
+  // props.titleTemplate might be "Order {{ref}} — {{status}}" from manifest
+  const resolvedTitle = TemplateRegistry.render(props.titleTemplate, data);
+  return <h2>{resolvedTitle}</h2>;
+};
+```
+
+### FieldRegistry.get — Reuse OOTB Form Fields
+
+Compose existing OOTB field components inside custom composite fields:
+
+```typescript
+import { FieldRegistry } from 'mystique/registry';
+
+const CompositeField = ({ onChange, value }) => {
+  const NumberField = FieldRegistry.get('number');
+  return (
+    <div>
+      <NumberField value={value.min} onChange={(v) => onChange({ ...value, min: v })} />
+      <span> to </span>
+      <NumberField value={value.max} onChange={(v) => onChange({ ...value, max: v })} />
+    </div>
+  );
+};
+```
+
+### Form Field onChange — Avoid Infinite Loop
+
+**CRITICAL:** When building form field components, `onChange` triggers a re-render. Never call `onChange` in the render body — wrap in `useEffect`:
+
+```typescript
+// WRONG — infinite re-render loop
+const BadField = ({ onChange, value }) => {
+  onChange(value || 'default'); // called every render!
+  return <input value={value} />;
+};
+
+// CORRECT — useEffect prevents the loop
+const GoodField = ({ onChange, value }) => {
+  useEffect(() => {
+    if (!value) onChange('default');
+  }, [value]); // only runs when value changes
+
+  return <input value={value} onChange={(e) => onChange(e.target.value)} />;
+};
+```
+
+### User Action Attribute to Field Mapping
+
+Workflow user actions define `eventAttributes` with a `type` property. The Mystique form engine maps each type to a FieldRegistry entry:
+
+| Workflow `eventAttributes[].type` | FieldRegistry Entry | Input Type |
+|---|---|---|
+| `TEXT` / `STRING` | text | Single-line text input |
+| `TEXTAREA` | textarea | Multi-line text area |
+| `NUMBER` / `INTEGER` | number | Numeric input |
+| `BOOLEAN` | boolean | Toggle switch |
+| `DATE` | date | Date picker |
+| `DROPDOWN` | dropdown | Select from options |
+| Custom type name | Custom field (if registered) | Your custom component |
+
+Register custom fields with `FieldRegistry.register('myCustomType', MyFieldComponent)`. The form engine auto-selects them when a user action has `type: "myCustomType"`.
+
+## Build & Development Lifecycle
+
+### Development Cycle
+
+```
+1. Scaffold project
+   /fluent-mystique-scaffold my-plugin --components OrderTracker,StoreMap
+
+2. Install dependencies
+   cd accounts/<PROFILE>/SOURCE/my-plugin/
+   yarn install
+
+3. Start dev server
+   yarn start
+   -> Serves on http://localhost:3001
+   -> Outputs bundle.[hash].js with CORS headers
+
+4. Point manifest plugins[] to localhost
+   In the Fluent OMX app manifest (via Settings or /fluent-mystique-builder):
+   {
+     "plugins": [
+       { "type": "url", "src": "http://localhost:3001/" }
+     ]
+   }
+
+5. Test in Fluent OMX App
+   -> Load the OMX app in browser
+   -> The host app fetches version.json from localhost:3001
+   -> Loads the hashed bundle
+   -> Your components are now available in the manifest
+
+6. Write tests
+   yarn test              # Run Jest with coverage
+   yarn storybook         # Visual component testing on port 6006
+
+7. Iterate
+   -> Webpack HMR reloads on save
+   -> Refresh the OMX app to pick up changes
+```
+
+### Production Deployment
+
+```
+1. Build the bundle
+   yarn build
+   -> Produces dist/bundle.[contenthash].js
+   -> Produces dist/version.json (maps bundle filename)
+   -> Produces dist/manifests/*.json (compiled manifest examples)
+   -> Runs build tests to verify output
+
+2. Deploy to hosting
+   Fluent Commerce does NOT host custom component bundles.
+   The bundle must be self-hosted. Options:
+
+   a) Vercel (recommended for simplicity):
+      vercel deploy
+      -> Returns URL like https://my-plugin.vercel.app/
+
+   b) AWS S3 + CloudFront:
+      aws s3 sync dist/ s3://my-bucket/my-plugin/ --cache-control max-age=31536000
+
+   c) Any static hosting / CDN:
+      Upload dist/ contents to your hosting provider
+
+3. Update manifest plugins[] with production URL
+   {
+     "plugins": [
+       {
+         "type": "url",
+         "src": "https://my-plugin.vercel.app/",
+         "name": "my-plugin"
+       }
+     ]
+   }
+
+   NOTE: The trailing "/" in the src URL enables version.json auto-discovery.
+   The host app fetches <src>/version.json, reads the bundle filename,
+   then loads <src>/<bundle-filename>.
+
+4. Deploy manifest to Fluent environment
+   Use /fluent-mystique-builder to update the manifest, then
+   /fluent-settings to upload it as a Fluent Setting.
+```
+
+### Key Deployment Facts
+
+- **Fluent Commerce does NOT host custom component bundles.** The bundle must be self-hosted on Vercel, S3, CDN, or any static file server.
+- **The manifest `plugins[]` array loads bundles by URL at runtime.** The OMX host app fetches each plugin URL, executes the JavaScript, and the `ComponentRegistry.register()` calls make components available.
+- **Webpack externals ensure React, ReactDOM, and Material-UI are NOT bundled.** These are provided by the host app. Including them would cause version conflicts and dramatically increase bundle size.
+- **Bundle output uses `[contenthash]` for cache busting.** The `version.json` file maps the current hash, allowing the host app to discover the latest bundle without hardcoding the hash in the manifest.
+- **For local development, webpack dev server serves on port 3001** with CORS headers enabled so the host app on a different domain can load the bundle.
+
+### Vercel Deployment (Optional Convenience)
+
+If using Vercel, generate a `vercel.json` in the project root:
+
+```json
+{
+  "version": 2,
+  "builds": [
+    {
+      "src": "dist/**",
+      "use": "@vercel/static"
+    }
+  ],
+  "routes": [
+    {
+      "src": "/(.*)",
+      "dest": "/dist/$1"
+    }
+  ]
+}
+```
+
+Deploy with:
+```bash
+yarn build
+vercel deploy --prod
+```
+
+The production URL is stable and can be used directly in the manifest `plugins[]` array.
+
+## Build Plugins
+
+### build/GenerateVersionPlugin.ts
+
+Emits `version.json` alongside the bundle, mapping the hashed filename:
+
+```typescript
+import { Compiler, sources } from 'webpack';
+
+class GenerateVersionPlugin {
+  apply(compiler: Compiler) {
+    compiler.hooks.afterCompile.tap('GenerateVersionPlugin', (compilation) => {
+      Object.entries(compilation.assets).forEach(([pathname]) => {
+        if (pathname.match(/bundle\.[a-z0-9]+\.js$/))
+          compilation.assets['version.json'] =
+              new sources.RawSource(JSON.stringify({
+                bundle: pathname,
+                version: process.env.GIT_TAG || Date.now().toString()
+              }));
+      });
+    });
+  }
+}
+
+module.exports = GenerateVersionPlugin;
+```
+
+### build/GenerateManifestsPlugin.ts
+
+Compiles TypeScript manifest files in `manifests/` to JSON in `dist/manifests/`:
+
+```typescript
+import webpack from 'webpack';
+const fs = require('fs-extra');
+
+class GenerateManifestsPlugin {
+  apply(compiler: webpack.Compiler) {
+    compiler.hooks.afterEmit.tap('GenerateManifestsPlugin', () => {
+      fs.readdir('./manifests', (err: string, files: string[]) => {
+        if (err) {
+          console.log(err);
+        } else {
+          files.forEach((file: string) => {
+            if (file.includes('fc.mystique.manifest') && !file.includes('.test.')) {
+              const filenameNoExt = file.slice(0, -3);
+              import(`../manifests/${filenameNoExt}`).then(manifest => {
+                fs.outputFile(
+                  `dist/manifests/${filenameNoExt}.json`,
+                  JSON.stringify(manifest.manifest, null, 4)
+                );
+              });
+            }
+          });
+        }
+      });
+    });
+  }
+}
+
+module.exports = GenerateManifestsPlugin;
+```
+
+## .gitignore
+
+```gitignore
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Test output
+test-report/
+coverage/
+
+# IDE files
+.idea/
+*.iml
+.vscode/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+yarn-debug.log*
+yarn-error.log*
+
+# Environment
+.env
+.env.local
+.env.production
+
+# Storybook
+storybook-static/
+```
+
+## Execution Flow
+
+```
+1. VALIDATE inputs
+   a. project-name: must match /^[a-z][a-z0-9-]*$/ (lowercase, hyphens allowed)
+   b. component names (if --components): must match /^[A-Z][a-zA-Z0-9]*$/ (PascalCase)
+   c. category (if --category): must be page|layout|content|filter
+
+2. PRE-CHECK: Project already exists?
+   a. Check accounts/<PROFILE>/SOURCE/<project-name>/ exists
+   b. If exists -> ABORT with guidance (or add components if --components specified)
+
+3. DETECT namespace
+   a. If --namespace provided -> use it
+   b. Else derive from project-name
+   c. Fallback: "custom" with warning
+
+4. COMPUTE derived values
+   a. PROJECT_TITLE = title-case of project-name with hyphens as spaces
+   b. KEBAB_NAME = kebab-case of each component name
+   c. CATEGORY = from --category or default "content"
+   d. Alias = <namespace>.<category>.<kebab-name>
+
+5. CREATE directory structure
+   a. Create all directories listed in the structure section
+   b. Ensure all parent directories exist before writing files
+
+6. COPY @types/mystique/ from reference SDK
+   a. Search for reference SDK: OMX Mystique components/omx-component-sdk/omx-component-sdk/@types/mystique/
+   b. Copy all 7 .d.ts files
+   c. Also copy @types/images.d.ts
+
+7. COPY lib/ files from reference SDK
+   a. Copy mystique.js and material-ui.js (large bundled files, cannot be generated)
+   b. Generate init.js, mystique-export.js from templates
+
+8. GENERATE project config files
+   a. package.json with substituted project name and description
+   b. webpack.config.ts
+   c. tsconfig.json
+   d. jest.config.js
+   e. .babelrc
+   f. .gitignore
+   g. sdk-version.json
+   h. .storybook/main.ts, preview.js, helpers.ts
+
+9. GENERATE source files
+   a. src/index.tsx with ComponentRegistry.register() for each component
+   b. src/index.html with project title
+   c. src/setup-tests.ts
+   d. src/utils/GqlUtils.ts, TestUtils.tsx
+   e. manifests/fc.mystique.manifest.example.ts
+   f. manifests/fc.mystique.manifest.fragment.example.ts
+   g. build/GenerateVersionPlugin.ts, GenerateManifestsPlugin.ts
+   h. i18n/locales/en/translation.json (empty object {})
+
+10. FOR EACH component in --components (if specified):
+    a. Create src/components/<Name>/ directory
+    b. Generate <Name>.tsx using component template
+    c. Generate <Name>.test.tsx using test template
+    d. Generate <Name>.stories.tsx using story template
+    e. Generate index.ts re-export
+    f. Add import and ComponentRegistry.register() to src/index.tsx
+
+11. VERIFY structure
+    If yarn is available: yarn install && yarn check-types
+    This confirms TypeScript compiles and dependencies resolve.
+
+12. REPORT generated files
+    List all files created with their full paths.
+    Print next steps:
+    - "Project scaffolded at: accounts/<PROFILE>/SOURCE/<project-name>/"
+    - "Install dependencies: cd accounts/<PROFILE>/SOURCE/<project-name> && yarn install"
+    - "Start dev server: yarn start (serves on http://localhost:3001)"
+    - "Run tests: yarn test"
+    - "Run Storybook: yarn storybook (serves on http://localhost:6006)"
+    - "Build for production: yarn build (outputs to dist/)"
+    - "Next: Wire components into a manifest with /fluent-mystique-builder"
+```
+
+## Integration with Other Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `/fluent-mystique-builder` | After scaffolding, use this to create or edit manifests that reference the new components via their registered aliases. |
+| `/fluent-mystique-validate` | Validate manifests that reference the new components. Checks that component aliases are known and props are well-formed. |
+| `/fluent-mystique-analyze` | Analyze deployed manifests to understand existing component usage before adding new ones. |
+| `/fluent-settings` | Deploy the compiled manifest JSON as a Fluent Setting for production use. |
+| `/fluent-feature-plan` | Required for multi-artifact work (SDK + manifest + workflows). Produces the comprehensive plan. |
+
+### Post-Scaffold Workflow
+
+```
+/fluent-mystique-scaffold mystique-plugin-curbside --components CurbsideStatus,StoreMap --category content
+    |
+    v
+cd accounts/<PROFILE>/SOURCE/mystique-plugin-curbside/ && yarn install
+    |
+    v
+yarn start   (develop and test locally on port 3001)
+    |
+    v
+/fluent-mystique-builder   (create manifest pages using curbside.content.curbside-status, curbside.content.store-map)
+    |
+    v
+/fluent-mystique-validate   (validate the manifest before deployment)
+    |
+    v
+yarn build   (produce dist/bundle.[hash].js)
+    |
+    v
+vercel deploy --prod   (deploy bundle to hosting)
+    |
+    v
+/fluent-settings   (upload manifest JSON to Fluent environment as a Setting)
+```
+
+## Edge Cases
+
+### No components specified
+
+When `--components` is omitted:
+- `src/index.tsx` contains only a comment: `// Register your components here`
+- No component directories are created
+- The project is still buildable (produces a bundle with no registrations)
+- This is valid as a starting point -- add components incrementally
+
+### Project name conflicts
+
+Check for any directory matching the project name:
+
+```bash
+ls accounts/<PROFILE>/SOURCE/ | grep -i "<project-name>"
+```
+
+If found, abort. Do NOT overwrite an existing project.
+
+### Reference SDK not available
+
+If `OMX Mystique components/omx-component-sdk/` is not found in the workspace:
+- Generate `@types/mystique/` files from the embedded templates (all 7 files documented in the plan)
+- Warn about missing `lib/mystique.js` and `lib/material-ui.js`
+- The project will build but tests and Storybook will fail without these lib files
+
+### Windows path handling
+
+- All webpack paths use forward slashes (Node.js standard)
+- Use `path.join()` and `path.resolve()` in webpack config, not hardcoded separators
+- Build scripts use `yarn` (cross-platform) rather than shell-specific commands
+
+### Duplicate component names
+
+If `--components` contains duplicates, deduplicate silently and warn:
+```
+Warning: Duplicate component name 'OrderTracker' removed from list.
+```
+
+### Component name validation
+
+Reject component names that:
+- Start with a lowercase letter or digit
+- Contain hyphens, underscores, or spaces (must be PascalCase)
+- Are empty or longer than 50 characters
+- Conflict with built-in Mystique components (e.g., `Card`, `List`, `Loading`)
+
+## React Hooks API Reference
+
+The Mystique host app provides 6 hooks via `mystique/hooks/*`. Type declarations are generated in `@types/mystique/hooks.d.ts`. Here is the runtime API for each:
+
+### useAuth — User Session & Context
+
+```typescript
+import { useAuth } from 'mystique/hooks/useAuth';
+
+const auth = useAuth();
+
+// User info
+auth.user.username;          // string
+auth.user.firstName;         // string
+auth.user.timezone;          // string (e.g., "Australia/Sydney")
+auth.user.language;          // string (e.g., "en")
+auth.user.roles;             // { role: { name: string } }[]
+
+// Current context
+auth.context.current.contextId;    // string — retailer or location ID
+auth.context.current.contextType;  // "RETAILER" | "LOCATION"
+auth.context.current.details?.ref; // string — entity ref
+
+// Actions
+auth.switchContext({ contextType: 'RETAILER', contextId });
+auth.logout();
+```
+
+**Use case**: Role-based rendering, context-aware queries, user info display.
+
+### useQuery — GraphQL Data Fetching
+
+```typescript
+import { useQuery } from 'mystique/hooks/useQuery';
+
+const [result, { loading, error, refetch }] = useQuery<ResultType>(
+  queryString,
+  { variables }
+);
+
+// result.data — typed query result (null while loading)
+// loading     — boolean
+// error       — Error object or null
+// refetch     — () => void — re-execute query
+```
+
+Results follow the Relay connection pattern: `edges[].node`, `pageInfo { hasNextPage, endCursor }`.
+
+**Prefer page query data over useQuery** — only use useQuery for follow-up queries not available in the page data context. Page queries are defined in the manifest `data` block and auto-executed.
+
+### useSettings — Dynamic Configuration
+
+```typescript
+import { useSettings } from 'mystique/hooks/useSettings';
+
+const settings = useSettings({ key: 'my.setting.name' });
+
+// Result shape:
+// settings.key.status  — 'loading' | 'error' | (truthy on success)
+// settings.key.result?.value — the setting value (any type)
+```
+
+**Hierarchy**: Location → Retailer → Account → Global (cascades up). A Location-level setting overrides Retailer, which overrides Account.
+
+### useI18n — Internationalization
+
+```typescript
+import { useI18n } from 'mystique/hooks/useI18n';
+
+const { translate, translateOr, languages, currentLanguage } = useI18n();
+
+translate('fc.om.orders.title');                    // single key lookup
+translateOr([                                        // fallback chain
+  'acme.errors.specificError',
+  'acme.errors.genericError',
+  'An error occurred'                                // last item = default
+]);
+currentLanguage.label;                               // e.g., "English"
+languages;                                           // { value, label }[]
+```
+
+Language dictionaries auto-load from the setting matching the user's language preference (e.g., `LANGUAGE_JA-JP`).
+
+### useData — Page Query Access
+
+```typescript
+import { useData } from 'mystique/hooks/useData';
+
+const { data, variables, loading, error } = useData();
+
+data.order;          // page query result, scoped by component's dataSource
+variables.orderId;   // query variables from manifest
+```
+
+**Use case**: Components that interact with page-level data (filters, list controls) without needing their own query.
+
+### useEnv — Environment Details
+
+```typescript
+import { useEnv } from 'mystique/hooks/useEnv';
+
+const env = useEnv();
+
+env.account;  // Account name
+env.app;      // App name: "oms", "store", "servicepoint", or custom
+env.api;      // API endpoint URL
+```
+
+## Advanced Component Patterns
+
+### DynamicValue — User-Configurable Display
+
+`<DynamicValue />` renders manifest-configured attributes as text, image, or embedded component. This is the key to making components reusable across different manifest contexts:
+
+```typescript
+import { DynamicValue } from 'mystique/components/DynamicValue';
+
+// GOOD — configurer controls what is displayed
+export const MyComponent: FC<ComponentProps> = ({ attribute, data }) => {
+  return <DynamicValue attribute={attribute} context={data} defaultValue={<span>-</span>} />;
+};
+
+// AVOID — hardcoded field access, not reusable
+export const MyComponent: FC<ComponentProps> = ({ data }) => {
+  return <div>{data.order.ref}</div>;
+};
+```
+
+### Children — Manifest-Driven Composition
+
+`<Children />` renders whatever descendant components are configured in the manifest. This lets configurers compose UI without touching code:
+
+```typescript
+import { Children } from 'mystique/components/Children';
+
+// Render descendants from manifest
+export const MyAccordion: FC = () => (
+  <CollapsibleDiv>
+    <Children />
+  </CollapsibleDiv>
+);
+
+// Override data context for all descendants
+export const MyDataWrapper: FC = ({ data }) => {
+  const transformed = transformData(data);
+  return (
+    <div>
+      <Children dataOverride={transformed} />
+    </div>
+  );
+};
+```
+
+### TemplateRegistry.render — Resolve Manifest Templates in Code
+
+When your component receives a template string from the manifest (e.g., `"{{order.ref}} - {{order.status}}"`), resolve it at runtime:
+
+```typescript
+import { TemplateRegistry } from 'mystique/registry/TemplateRegistry';
+
+const resolved = TemplateRegistry.render('{{order.ref}} - {{order.status}}', data);
+```
+
+### FieldRegistry.get — Compose Existing Fields
+
+Reuse OOTB field components inside custom composite fields:
+
+```typescript
+import { FieldRegistry } from 'mystique/registry/FieldRegistry';
+
+const QuantityField = FieldRegistry.get('number');
+
+// Use in your component's render:
+<QuantityField name="qty" label="Quantity" value={qty} onChange={setQty} />
+```
+
+### onChange + useEffect — Loop Prevention (CRITICAL)
+
+Form field `onChange` MUST be wrapped in `useEffect`. Calling `onChange` directly in a handler causes infinite re-renders:
+
+```typescript
+// CORRECT — useEffect breaks the render cycle
+const [value, setValue] = useState('');
+useEffect(() => {
+  onChange({ value });
+}, [value]);
+
+// WRONG — causes infinite loop
+const handleChange = (v: string) => {
+  setValue(v);
+  onChange({ value: v }); // triggers parent re-render → this component re-renders → calls onChange again
+};
+```
+
+### User Action Attribute ↔ Field Mapping
+
+Workflow user actions define form attributes with a `type` field. Mystique auto-selects the matching FieldRegistry entry:
+
+| Workflow Attribute Type | FieldRegistry Key | Component |
+|------------------------|-------------------|-----------|
+| `STRING` | `text` | Text input |
+| `INTEGER` | `number` | Number input |
+| `BOOLEAN` | `boolean` | Checkbox |
+| `JSON` | `json` | JSON editor |
+| `<custom>` | `<custom>` | Your registered field |
+
+Register a custom field to handle custom types: `FieldRegistry.register(['stockReservation'], StockReservationField)`.
+
+### Material-UI Version Lock
+
+The host OMX app ships **Material-UI v4.12.4**. This version is locked — do NOT use MUI v5/v6 APIs. Some newer patterns (certain keyframe syntax, `sx` prop, Emotion-based `styled()`) are unsupported.
+
+Theme colors: primary `#00A9E0`, secondary (brand purple), plus `success`, `error`, `warning`, `info` from the theme palette. Access via `makeStyles`:
+
+```typescript
+const useStyles = makeStyles((theme) => ({
+  root: { color: theme.palette.primary.main },    // #00A9E0
+  error: { color: theme.palette.error.main },
+}));
+```
+
+Responsive breakpoints: `theme.breakpoints.down('sm')`, `theme.breakpoints.up('md')`.
+
+## 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-scaffold", "timestamp": "<ISO-8601>", "arguments": { "projectName": "<name>", "components": ["<list>"], "category": "<cat>" } }
+```
+
+**On exit:**
+```json
+{ "skill": "fluent-mystique-scaffold", "outcome": "<completed|failed|skipped>", "changesProduced": ["<seq-numbers>"], "toolCallsProduced": ["<seq-numbers>"], "nextRecommended": "/fluent-mystique-builder" }
+```
+
+## Handoff
+
+| Output Artifact | Consumed By | Path |
+|----------------|-------------|------|
+| SDK project with components | `/fluent-mystique-builder` (creates manifest referencing components) | `accounts/<PROFILE>/SOURCE/<project-name>/` |
+| Built bundle | Manifest `plugins[]` array (loaded at runtime by host app) | `accounts/<PROFILE>/SOURCE/<project-name>/dist/bundle.[hash].js` |
+| Compiled manifests | `/fluent-mystique-validate` (validates before deploy) | `accounts/<PROFILE>/SOURCE/<project-name>/dist/manifests/` |
+
+## Error Reporting
+
+Errors from this skill follow the standard format:
+
+| Field | Description |
+|-------|-------------|
+| `phase` | Skill phase where error occurred (e.g., `pre-check`, `validation`, `generation`, `verification`) |
+| `severity` | `CRITICAL` (blocks downstream), `HIGH` (needs fix), `MEDIUM` (advisory), `LOW` (informational) |
+| `message` | Human-readable error description |
+| `resolution` | Suggested fix or downstream skill to invoke |
+
+## Gotchas
+
+- **`lib/mystique.js` is ~5MB** and `lib/material-ui.js` is ~1.2MB. These are bundled Fluent Commerce SDK files that cannot be generated -- they must be copied from the reference SDK distribution. Without them, Jest and Storybook will fail with `Cannot read properties of undefined (reading 'ComponentRegistry')`.
+- **Webpack externals are order-sensitive.** The three externals (`static map`, `externalMaterialUI`, `externalMystique`) must be in an array. If any handler catches a module it should not, the bundle will break at runtime.
+- **`@material-ui/core` subpath imports** (e.g., `@material-ui/core/Button`) are routed to `window.MaterialUI.Button` by the `externalMaterialUI` function. The `styles` subpath is special-cased to return the root `MaterialUI` object.
+- **`mystique/*` imports** (e.g., `mystique/hooks/useQuery`) all resolve to `window.Mystique` at runtime. The TypeScript type declarations in `@types/mystique/` provide compile-time safety, but the actual objects come from the host app global.
+- **React 17 is required.** The host Fluent OMX app provides React 17. Using React 18 APIs will fail at runtime even if they compile successfully.
+- **Content hash in filename** means the URL changes on every build. The `version.json` file is the stable discovery mechanism -- the manifest `plugins[].src` should point to the directory (with trailing `/`), not the specific bundle file.
+- **CORS headers are essential** for local development. Without `Access-Control-Allow-Origin: *` on the dev server, the host app cannot load the bundle from localhost:3001.
+- **Storybook 6.5.x** is the last version compatible with this SDK's webpack 5 setup. Do not upgrade to Storybook 7+ without verifying compatibility.
+- **The `@emotion/react` external** is mapped to `emotionReact` (not `Emotion`). This matches how `lib/init.js` sets `globalThis.emotionReact = Emotion`.
+- **Manifest `plugins[]` type field:** Use `{ "type": "url", "src": "..." }` for URL-based plugins (production bundles) or `{ "type": "setting", "setting": "..." }` for setting-based plugin references. Local development always uses the URL type.