@pega/sdk 0.0.2 → 0.0.3

package/templates/react-sdk-reference/.cursor/rules/pega-sdk.mdrules

@@ -0,0 +1,247 @@
+---
+alwaysApply: true
+---
+
+# Pega SDK — Cursor Rules
+
+You are assisting developers in a React reference application that demonstrates the Pega Infinity SDK. Customers clone this repo and **replace the sample UI components with their own design system** (MUI, Chakra, Radix, Shadcn, Ant Design, or any other).
+
+---
+
+## 1. Repository Purpose
+
+This is a **reference implementation** — not a framework. The UI components (fields, templates, widgets) are intentionally simple MUI-based implementations meant to be swapped out. The SDK wiring (bootstrap, PConnect bridge, component registry) is reusable infrastructure that should NOT be modified.
+
+---
+
+## 2. What Is Replaceable vs. Infrastructure
+
+### Replaceable (customer modifies these)
+
+| Directory                               | Purpose                                                     |
+| --------------------------------------- | ----------------------------------------------------------- |
+| `src/components/field/`                 | Form field components (TextInput, Dropdown, Date, etc.)     |
+| `src/components/template/`              | Layout templates (OneColumn, TwoColumn, Details, etc.)      |
+| `src/components/widget/`                | Data widgets (ToDo, Attachment, CaseHistory, etc.)          |
+| `src/components/designSystemExtension/` | Extended UI (AlertBanner, FieldGroup, RichTextEditor, etc.) |
+
+### Infrastructure (do NOT modify unless you know what you're doing)
+
+| File/Directory                          | Purpose                                                   |
+| --------------------------------------- | --------------------------------------------------------- |
+| `src/MashupApp.tsx`                     | Auth + bootstrap + root rendering                         |
+| `src/components/component-map.ts`       | Registry wiring (only add/remove entries)                 |
+| `src/components/infra/`                 | Infrastructure components (ActionButtons, Stages, NavBar) |
+| `src/components/helpers/event-utils.ts` | PConnect event handler utility                            |
+| `@pega/sdk-react`                       | SDK bridge — never modify                                 |
+
+---
+
+## 3. Component Architecture
+
+### The PConnect Bridge
+
+Every component receives `getPConnect` as a prop. This is the bridge to the Pega platform:
+
+```typescript
+const pConn = getPConnect();
+const actions = pConn.getActionsApi(); // For field updates
+const propName = (pConn.getStateProps() as any).value; // Property path
+```
+
+### Event Handling Pattern
+
+All field components use this pattern for two-way binding:
+
+```typescript
+import handleEvent from '../../helpers/event-utils';
+
+// On change (local state only):
+function handleChange(event) {
+  setInputValue(event.target.value);
+}
+
+// On blur (push to platform):
+function handleBlur() {
+  handleEvent(actions, 'changeNblur', propName, inputValue);
+}
+```
+
+### Display Mode Handling
+
+Field components must handle `displayMode` prop:
+
+- `undefined` → render editable input
+- `'DISPLAY_ONLY'` → render read-only value via `FieldValueList`
+- `'STACKED_LARGE_VAL'` → render stacked read-only via `FieldValueList` with `variant='stacked'`
+
+### Component Registry
+
+Components are registered by name in `src/components/component-map.ts`:
+
+```typescript
+import { sdkComponents } from '@pega/sdk-react';
+
+function getSampleComponentMap() {
+  return {
+    ...sdkComponents, // Infrastructure (View, Region, FlowContainer, etc.)
+    TextInput, // Your field components
+    Dropdown,
+    // ...
+  };
+}
+```
+
+To add a new component: add the import + add to the map object.
+To replace a component: change the import to point to your new implementation.
+
+---
+
+## 4. Props Interfaces
+
+### Field Components (`PConnFieldProps`)
+
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface PConnFieldProps {
+  getPConnect: () => typeof PConnect;
+  label: string;
+  required: boolean;
+  disabled: boolean;
+  value?: string;
+  validatemessage: string;
+  status?: string; // 'error' | 'warning' | undefined
+  onChange: any;
+  onBlur?: any;
+  readOnly: boolean;
+  testId: string;
+  helperText: string;
+  displayMode?: string; // 'DISPLAY_ONLY' | 'STACKED_LARGE_VAL'
+  hideLabel: boolean;
+  placeholder?: string;
+}
+```
+
+### Template/Widget Components (`PConnProps`)
+
+```typescript
+import type { PConnProps } from '@pega/sdk-react';
+
+interface PConnProps {
+  getPConnect: () => typeof PConnect;
+}
+```
+
+---
+
+## 5. Rules for Replacing Components
+
+1. **Keep the same default export name** — the component-map references it.
+2. **Keep `getPConnect` wiring intact** — extract props, call `handleEvent` on blur.
+3. **Handle `displayMode`** — return `FieldValueList` for read-only modes.
+4. **Handle validation** — show `validatemessage` when `status === 'error'`.
+5. **Preserve `data-test-id`** — pass `testId` to the root interactive element.
+6. **Use `getComponentFromRegistry`** to render sub-components (e.g., `FieldValueList`) — don't hardcode imports for components that might also be replaced.
+
+---
+
+## 6. Build & Dev Commands
+
+```bash
+# From monorepo root (if developing locally with source packages):
+npm run build              # Build all packages + samples
+npm run dev:react          # Build + dev server
+
+# From this directory (standalone):
+npm run dev                # Vite dev server (port 3500)
+npm run build              # Production build
+```
+
+---
+
+## 7. Key Imports
+
+```typescript
+// From SDK (never modify these)
+import {
+  PConnectComponent,
+  PegaStoreContext,
+  registerComponentCreator,
+  getComponentFromRegistry,
+  sdkComponents,
+} from '@pega/sdk-react';
+import type { PConnProps, PConnFieldProps } from '@pega/sdk-react';
+
+// Event utility (preserve this)
+import handleEvent from '../../helpers/event-utils';
+```
+
+---
+
+## 8. Do NOT
+
+- Modify `MashupApp.tsx` bootstrap flow when replacing design system components.
+- Import from `@pega/sdk-react/src/...` — use the package entry point only.
+- Hardcode component references — use `getComponentFromRegistry('Name')` for components that may be overridden.
+- Remove the `...sdkComponents` spread from `component-map.ts`.
+- Use `any` without justification — prefer `unknown` and narrow.
+- Add `@ts-ignore` — use `@ts-expect-error` with explanation if truly needed.
+
+---
+
+## 9. Component Generation Workflow — Single Component
+
+When the user asks to generate, create, add, or replace **a single UI component** (e.g., "generate an AutoComplete component", "add a Dropdown using Chakra UI"),
+read the full contents of `.cursor/rules/prompts/add-component.mdrules` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+> For generating **multiple field components** at once, see Section 10.
+
+---
+
+## 10. Batch Field Component Generation
+
+When the user asks to generate, create, or replace **multiple field components** or **all field components** with a design system (e.g., "generate field components with Ant Design", "replace all fields with Chakra UI", "generate all field components using Radix"),
+read the full contents of `.cursor/rules/prompts/generate-field-components.mdrules` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+---
+
+## 11. Batch Template Component Generation
+
+When the user asks to generate, create, or replace **multiple template components** or **all template components** with a design system (e.g., "generate template components with Ant Design", "replace all templates with Chakra UI", "generate layout templates using Radix"),
+read the full contents of `.cursor/rules/prompts/generate-template-components.mdrules` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+---
+
+## 12. Batch Widget Component Generation
+
+When the user asks to generate, create, or replace **multiple widget components** or **all widget components** with a design system (e.g., "generate widget components with Ant Design", "replace all widgets with Chakra UI", "generate widgets using Carbon"),
+read the full contents of `.cursor/rules/prompts/generate-widget-components.mdrules` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+---
+
+## 13. Batch Design System Extension Component Generation
+
+When the user asks to generate, create, or replace **multiple design system extension components** or **all DSE components** with a design system (e.g., "generate DSE components with Ant Design", "replace design system extension components with Chakra UI", "generate designSystemExtension components using Carbon"),
+read the full contents of `.cursor/rules/prompts/generate-dse-components.mdrules` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+---
+
+## 14. Generate All Components (Multi-Type)
+
+When the user asks to generate, create, or replace components across **multiple types** or **all component types** at once (e.g., "generate all components with Ant Design", "replace everything with Chakra UI", "generate field and widget components using Carbon", "regenerate all components"),
+read the full contents of `.cursor/rules/prompts/generate-all-components.mdrules` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+> Use this section when the request spans more than one component type. For a single type, use Sections 10–13.

package/templates/react-sdk-reference/.cursor/rules/prompts/add-component.mdrules

@@ -0,0 +1,149 @@
+---
+description: add-component.prompt
+alwaysApply: false
+---
+
+## Step 0 — Resolve missing information
+
+Read the user's message carefully. Extract:
+
+- **Component name** — the exact name (e.g. `AutoComplete`, `DatePicker`)
+- **Component type** — one of: `field` | `template` | `widget` | `designSystemExtension`
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output path** — the exact or relative path where the component should be generated (e.g. `src/components/field/AutoComplete`)
+
+If any of the four are missing or ambiguous, ask the user all unresolved items in **one numbered list** and wait for their answers before continuing. Do not guess or proceed with assumptions.
+
+Example questions to ask (only ask the ones that are actually missing):
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. What is the exact component name?
+3. What type of component is this? (field / template / widget / designSystemExtension)
+4. What is the exact or relative path where the component should be generated? (e.g. `src/components/field/AutoComplete`)
+
+### Case-insensitive component name matching
+
+The user may enter the component name in any casing (e.g. `autocomplete`, `Autocomplete`, `autoComplete`). It is your responsibility to match it to the correct canonical name by checking the skill files in `.cursor/rules/skills/field-skills/`, `.cursor/rules/skills/template-skills/`, `.cursor/rules/skills/widget-skills/`, and `.cursor/rules/skills/design-system-extension-skills/`. For example, if the user types `autocomplete`, match it to `AutoComplete`.
+
+Once all four are known, continue to Step 1.
+
+---
+
+## Step 1 — Check for existing component (overwrite check)
+
+Before generating, check if a component already exists at the resolved output path:
+
+1. Check if `<outputPath>/<ComponentName>.tsx` (or the directory) already exists.
+2. If it **does exist**, ask the user: _"A component named `<ComponentName>` already exists at `<outputPath>`. Do you want to overwrite it with the new implementation?"_
+   - If the user says **yes**, proceed to overwrite.
+   - If the user says **no**, stop and skip generation.
+3. If it **does not exist**, continue to Step 2.
+
+---
+
+## Step 2 — Check for skill files
+
+Always read the **general type skill** for the component type:
+
+| Component Type | General Skill File |
+|---|---|
+| `field` | `.cursor/rules/skills/field-components.mdrules` |
+| `template` | `.cursor/rules/skills/template-components.mdrules` |
+| `widget` | `.cursor/rules/skills/widget-components.mdrules` |
+| `designSystemExtension` | `.cursor/rules/skills/design-system-extension.mdrules` |
+
+Then look for a **component-specific skill** based on the component type:
+
+| Component Type | Specific Skill Location |
+|---|---|
+| `field` | `.cursor/rules/skills/field-skills/<ComponentName>.mdrules` |
+| `template` | `.cursor/rules/skills/template-skills/<ComponentName>.mdrules` |
+| `widget` | `.cursor/rules/skills/widget-skills/<ComponentName>.mdrules` |
+| `designSystemExtension` | `.cursor/rules/skills/design-system-extension-skills/<ComponentName>.mdrules` |
+
+If the component-specific skill file exists, read it fully. Pay special attention to:
+- **Behavioral Contract** — state management, event handling, option loading, edge cases
+- **Design System Mapping** table — the recommended component for the chosen design system
+
+You must read **both** the general type skill and the component-specific skill (if it exists) before proceeding.
+
+Examples:
+- `AutoComplete` (field) → read `field-components.md` + `field-skills/AutoComplete.md`
+- `AdvancedSearch` (template) → read `template-components.md` + `template-skills/AdvancedSearch.md`
+- `AppAnnouncement` (widget) → read `widget-components.md` + `widget-skills/AppAnnouncement.md`
+- `AlertBanner` (designSystemExtension) → read `design-system-extension.md` + `design-system-extension-skills/AlertBanner.md`
+
+If no component-specific skill file exists, continue using the general pattern from the type skill.
+
+---
+
+## Step 3 — Check and install dependencies
+
+Run:
+```
+cat package.json | grep "<design-system-package>"
+```
+
+If the design system package is **not** listed in `dependencies` or `devDependencies`, install it:
+```
+npm install <design-system-package>
+```
+
+Also install any peer dependencies documented in the package's README. Report what was installed.
+
+---
+
+## Step 4 — Discover the design system's API
+
+Before writing any code, inspect the installed package:
+
+1. `cat node_modules/<designSystem>/README.md` — note the correct import path and usage patterns for the installed version.
+2. `grep "^export" node_modules/<designSystem>/dist/index.d.ts 2>/dev/null || grep -rl "^export" node_modules/<designSystem> --include="index.d.ts" | head -3 | xargs grep "^export"` — lists every component actually exported by the installed version.
+3. For every component you plan to use, read its TypeScript prop interface from the installed `.d.ts`:
+   `find node_modules/<designSystem> -name "ComponentName.d.ts" | head -3`, then `grep -A 40 "interface.*Props"` on the result.
+4. Only use component names and prop names confirmed in those files. Do not rely on training knowledge of the API.
+
+Also check:
+- Whether the design system has a **form layout wrapper** (label + input + helper text) — use it instead of manual margins
+- Whether it has **size/density/variant conventions** — use built-in props rather than custom padding
+- Whether it has a **companion icons package** — read its exports before using any icon name; never guess icon names
+- Whether it has a **tokens or CSS directory** — use design system CSS custom properties for spacing; never hardcode `px` values
+
+---
+
+## Step 5 — Generate the component
+
+Create the component directory at the resolved output path (from Step 0).
+
+Create `<ComponentName>.tsx` using the pattern for the component type:
+
+- **field**: Extend `PConnFieldProps` from `@pega/sdk-react`. Extract `getPConnect`, `label`, `required`, `disabled`, `value`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`. Call `handleEvent(actions, 'changeNblur', propName, value)` on blur. Handle `displayMode === 'DISPLAY_ONLY'` and `'STACKED_LARGE_VAL'` using `getComponentFromRegistry('FieldValueList')`. Show `validatemessage` when `status === 'error'`. Pass `data-test-id={testId}` on the interactive element.
+- **template**: Extend `PConnProps`, render children via the design system's grid/layout primitives
+- **widget**: Extend `PConnProps`, fetch data via `PCore.getDataPageUtils()`
+- **designSystemExtension**: Pure display props or extend `PConnProps`
+
+Create `index.tsx`:
+```typescript
+export { default } from './<ComponentName>';
+```
+
+---
+
+## Step 6 — Register in component-map.ts
+
+Edit `src/components/component-map.ts`:
+
+1. Add the import at the top of the file, in the correct section (Fields / Templates / Widgets / Design System Extension)
+2. Add an entry in `getSampleComponentMap()` under the matching category comment
+
+Do not restructure or reorder any existing entries.
+
+---
+
+## Step 7 — Verify the build
+
+Run:
+```
+npm run build
+```
+
+If build errors occur, fix them before reporting completion. Report what files were created and what was added to `component-map.ts`.

package/templates/react-sdk-reference/.cursor/rules/prompts/component-manifest.json

@@ -0,0 +1,111 @@
+{
+  "folderScopes": {
+    "field": "src/components/field",
+    "template": "src/components/template",
+    "widget": "src/components/widget",
+    "infra": "src/components/infra",
+    "designSystemExtension": "src/components/designSystemExtension"
+  },
+  "namedScopes": {
+    "workflow-form": {
+      "folders": ["field"],
+      "components": [
+        { "name": "Stages", "category": "infra", "path": "src/components/infra/Stages" }
+      ]
+    }
+  },
+  "components": {
+    "field": [
+      { "name": "AutoComplete",    "path": "src/components/field/AutoComplete" },
+      { "name": "CancelAlert",     "path": "src/components/field/CancelAlert" },
+      { "name": "Checkbox",        "path": "src/components/field/Checkbox" },
+      { "name": "Currency",        "path": "src/components/field/Currency" },
+      { "name": "Date",            "path": "src/components/field/Date" },
+      { "name": "DateTime",        "path": "src/components/field/DateTime" },
+      { "name": "Decimal",         "path": "src/components/field/Decimal" },
+      { "name": "Dropdown",        "path": "src/components/field/Dropdown" },
+      { "name": "Email",           "path": "src/components/field/Email" },
+      { "name": "Group",           "path": "src/components/field/Group" },
+      { "name": "Integer",         "path": "src/components/field/Integer" },
+      { "name": "Location",        "path": "src/components/field/Location" },
+      { "name": "Multiselect",     "path": "src/components/field/Multiselect" },
+      { "name": "ObjectReference", "path": "src/components/field/ObjectReference" },
+      { "name": "Percentage",      "path": "src/components/field/Percentage" },
+      { "name": "Phone",           "path": "src/components/field/Phone" },
+      { "name": "RadioButtons",    "path": "src/components/field/RadioButtons" },
+      { "name": "RichText",        "path": "src/components/field/RichText" },
+      { "name": "ScalarList",      "path": "src/components/field/ScalarList" },
+      { "name": "SelectableCard",  "path": "src/components/field/SelectableCard" },
+      { "name": "SemanticLink",    "path": "src/components/field/SemanticLink" },
+      { "name": "TextArea",        "path": "src/components/field/TextArea" },
+      { "name": "TextContent",     "path": "src/components/field/TextContent" },
+      { "name": "TextInput",       "path": "src/components/field/TextInput" },
+      { "name": "Time",            "path": "src/components/field/Time" },
+      { "name": "URL",             "path": "src/components/field/URL" },
+      { "name": "UserReference",   "path": "src/components/field/UserReference" }
+    ],
+    "template": [
+      { "name": "AdvancedSearch",         "path": "src/components/template/AdvancedSearch" },
+      { "name": "AppShell",               "path": "src/components/template/AppShell" },
+      { "name": "BannerPage",             "path": "src/components/template/BannerPage" },
+      { "name": "CaseSummary",            "path": "src/components/template/CaseSummary" },
+      { "name": "CaseView",               "path": "src/components/template/CaseView" },
+      { "name": "CaseViewActionsMenu",    "path": "src/components/template/CaseViewActionsMenu" },
+      { "name": "Confirmation",           "path": "src/components/template/Confirmation" },
+      { "name": "DataReference",          "path": "src/components/template/DataReference" },
+      { "name": "DefaultForm",            "path": "src/components/template/DefaultForm" },
+      { "name": "DefaultPage",            "path": "src/components/template/DefaultPage" },
+      { "name": "Details",                "path": "src/components/template/Details" },
+      { "name": "FieldGroupTemplate",     "path": "src/components/template/FieldGroupTemplate" },
+      { "name": "HierarchicalForm",       "path": "src/components/template/HierarchicalForm" },
+      { "name": "InlineDashboard",        "path": "src/components/template/InlineDashboard" },
+      { "name": "InlineDashboardPage",    "path": "src/components/template/InlineDashboardPage" },
+      { "name": "ListPage",               "path": "src/components/template/ListPage" },
+      { "name": "ListView",               "path": "src/components/template/ListView" },
+      { "name": "MultiReferenceReadOnly", "path": "src/components/template/MultiReferenceReadOnly" },
+      { "name": "NarrowWide",             "path": "src/components/template/NarrowWide" },
+      { "name": "ObjectPage",             "path": "src/components/template/ObjectPage" },
+      { "name": "OneColumn",              "path": "src/components/template/OneColumn" },
+      { "name": "PromotedFilters",        "path": "src/components/template/PromotedFilters" },
+      { "name": "SelfServiceCaseView",    "path": "src/components/template/SelfServiceCaseView" },
+      { "name": "SimpleTable",            "path": "src/components/template/SimpleTable" },
+      { "name": "SingleReferenceReadOnly","path": "src/components/template/SingleReferenceReadOnly" },
+      { "name": "SubTabs",                "path": "src/components/template/SubTabs" },
+      { "name": "TwoColumn",              "path": "src/components/template/TwoColumn" },
+      { "name": "WideNarrow",             "path": "src/components/template/WideNarrow" },
+      { "name": "WssNavBar",              "path": "src/components/template/WssNavBar" }
+    ],
+    "widget": [
+      { "name": "AppAnnouncement", "path": "src/components/widget/AppAnnouncement" },
+      { "name": "Attachment",      "path": "src/components/widget/Attachment" },
+      { "name": "CaseHistory",     "path": "src/components/widget/CaseHistory" },
+      { "name": "FileUtility",     "path": "src/components/widget/FileUtility" },
+      { "name": "Followers",       "path": "src/components/widget/Followers" },
+      { "name": "QuickCreate",     "path": "src/components/widget/QuickCreate" },
+      { "name": "SummaryItem",     "path": "src/components/widget/SummaryItem" },
+      { "name": "SummaryList",     "path": "src/components/widget/SummaryList" },
+      { "name": "ToDo",            "path": "src/components/widget/ToDo" }
+    ],
+    "infra": [
+      { "name": "ActionButtons",   "path": "src/components/infra/ActionButtons" },
+      { "name": "DashboardFilter", "path": "src/components/infra/DashboardFilter" },
+      { "name": "DeferLoad",       "path": "src/components/infra/DeferLoad" },
+      { "name": "NavBar",          "path": "src/components/infra/NavBar" },
+      { "name": "Stages",          "path": "src/components/infra/Stages" },
+      { "name": "VerticalTabs",    "path": "src/components/infra/VerticalTabs" }
+    ],
+    "designSystemExtension": [
+      { "name": "AlertBanner",       "path": "src/components/designSystemExtension/AlertBanner" },
+      { "name": "Banner",            "path": "src/components/designSystemExtension/Banner" },
+      { "name": "CaseSummaryFields", "path": "src/components/designSystemExtension/CaseSummaryFields" },
+      { "name": "DetailsFields",     "path": "src/components/designSystemExtension/DetailsFields" },
+      { "name": "FieldGroup",        "path": "src/components/designSystemExtension/FieldGroup" },
+      { "name": "FieldGroupList",    "path": "src/components/designSystemExtension/FieldGroupList" },
+      { "name": "FieldValueList",    "path": "src/components/designSystemExtension/FieldValueList" },
+      { "name": "Operator",          "path": "src/components/designSystemExtension/Operator" },
+      { "name": "Pulse",             "path": "src/components/designSystemExtension/Pulse" },
+      { "name": "RichTextEditor",    "path": "src/components/designSystemExtension/RichTextEditor" },
+      { "name": "WssQuickCreate",    "path": "src/components/designSystemExtension/WssQuickCreate" }
+    ]
+  }
+}

package/templates/react-sdk-reference/.cursor/rules/prompts/generate-all-components.mdrules

@@ -0,0 +1,154 @@
+---
+description: generate-all-components.prompt
+alwaysApply: false
+---
+
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Base components folder** — the root folder that contains (or will contain) the component type subfolders (e.g. `src/components/`)
+- **Component types in scope** — which types to generate (default: all four if not specified)
+
+Both **design system** and **base components folder** are required. If either is missing or ambiguous, ask both unresolved items in one numbered list. Do not assume or default the base folder — the client's folder structure may differ.
+
+Example questions (ask only the ones that are actually missing):
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. What is your base components folder? (e.g. `src/components/`) — subfolders `field/`, `template/`, `widget/`, and `designSystemExtension/` will be used under it.
+
+### Component type scope
+
+Extract which types the user wants from the message:
+
+| User says | Types in scope |
+|---|---|
+| "generate all components" | field + template + widget + designSystemExtension |
+| "generate field and widget components" | field + widget |
+| "generate widget, template components" | widget + template |
+| "generate all components except templates" | field + widget + designSystemExtension |
+| "replace everything" | field + template + widget + designSystemExtension |
+
+Default to **all four types** if the message does not restrict the scope.
+
+### Derived output paths
+
+Once the base folder is known, derive the output path for each type in scope:
+
+| Type | Derived path |
+|---|---|
+| field | `<base>/field/` |
+| template | `<base>/template/` |
+| widget | `<base>/widget/` |
+| designSystemExtension | `<base>/designSystemExtension/` |
+
+Once design system, base folder, and type scope are resolved, continue to Step 1.
+
+---
+
+## Step 1 — Read general skill files (once, for each type in scope)
+
+Read the general skill file for every type in scope. Do this upfront — do not re-read per component.
+
+| Type | Skill file to read |
+|---|---|
+| field | `.cursor/rules/skills/field-components.mdrules` |
+| template | `.cursor/rules/skills/template-components.mdrules` |
+| widget | `.cursor/rules/skills/widget-components.mdrules` |
+| designSystemExtension | `.cursor/rules/skills/design-system-extension.mdrules` |
+
+Keep all loaded skill files active throughout the entire session.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+Execute **Step 3** from `.cursor/rules/prompts/add-component.mdrules` exactly as written:
+- Check `package.json` for the DS package
+- Install if missing, including any peer dependencies
+- Report what was installed
+
+Then execute **Step 4** from `.cursor/rules/prompts/add-component.mdrules` exactly as written:
+- Read the DS README from `node_modules`
+- Discover all exported components from `dist/index.d.ts`
+- Read prop interfaces for primitives needed across **all types in scope**:
+  - **field**: form input controls (Input, Select, Checkbox, DatePicker, etc.)
+  - **template**: grid/layout primitives (Grid, Flex, Columns, SimpleGrid, etc.)
+  - **widget**: card/list/table/button/badge primitives
+  - **designSystemExtension**: alert/notification/avatar primitives
+- Note form layout wrappers, size/variant conventions, icon packages, and design tokens
+
+Build a unified **DS API reference map** covering all types in scope. Reuse it throughout — do not repeat discovery commands per component.
+
+---
+
+## Step 3 — Overwrite check (all types, all at once)
+
+For every type in scope, check whether each component's `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+
+Collect all existing components across all types and report them in one consolidated list:
+
+> "The following N components already exist across [types]: [list grouped by type]. How should I proceed?
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate field components (skip if field not in scope)
+
+If `field` is in scope, execute **Step 4** from `.cursor/rules/prompts/generate-field-components.mdrules` in full:
+- Use the derived field output path: `<base>/field/`
+- The general skill (`field-components.md`) is already loaded from Step 1 — do not re-read it
+- The DS API reference map is already built from Step 2 — do not repeat discovery commands
+- For each of the 27 field components: read skill file → generate → register in `component-map.ts`
+- Report progress after each component
+
+---
+
+## Step 5 — Generate template components (skip if template not in scope)
+
+If `template` is in scope, execute **Step 4** from `.cursor/rules/prompts/generate-template-components.mdrules` in full:
+- Use the derived template output path: `<base>/template/`
+- The general skill (`template-components.md`) is already loaded from Step 1 — do not re-read it
+- The DS layout API is already discovered from Step 2 — do not repeat discovery commands
+- For each of the 32 template components: read skill file → generate → register in `component-map.ts`
+- Report progress after each component
+
+---
+
+## Step 6 — Generate widget components (skip if widget not in scope)
+
+If `widget` is in scope, execute **Step 4** from `.cursor/rules/prompts/generate-widget-components.mdrules` in full:
+- Use the derived widget output path: `<base>/widget/`
+- The general skill (`widget-components.md`) is already loaded from Step 1 — do not re-read it
+- The DS UI primitive map is already built from Step 2 — do not repeat discovery commands
+- For each of the 9 widget components: read skill file → generate → register in `component-map.ts`
+- If no skill file exists for a component (e.g., `SummaryList`), use the general pattern from `widget-components.md`
+- Report progress after each component
+
+---
+
+## Step 7 — Generate design system extension components (skip if DSE not in scope)
+
+If `designSystemExtension` is in scope, execute **Step 4** from `.cursor/rules/prompts/generate-dse-components.mdrules` in full:
+- Use the derived DSE output path: `<base>/designSystemExtension/`
+- The general skill (`design-system-extension.md`) is already loaded from Step 1 — do not re-read it
+- The DS display primitive map is already built from Step 2 — do not repeat discovery commands
+- For each of the 11 DSE components: read skill file → generate → register in `component-map.ts`
+- Apply the Pattern B/A/C branching as specified in the skill file and `design-system-extension.md`
+- Report progress after each component
+
+---
+
+## Step 8 — Verify the build
+
+Execute **Step 7** from `.cursor/rules/prompts/add-component.mdrules` exactly as written:
+- Run `npm run build`
+- Fix any TypeScript or build errors before reporting completion
+- Report a final summary:
+  - Total components generated, grouped by type
+  - All entries added to `component-map.ts`
+  - Any components skipped (if "skip existing" was chosen in Step 3)