@pega/sdk 0.0.2 → 0.0.4

package/templates/react-sdk-reference/.github/agents/implementation-expert.agent.md

@@ -0,0 +1,135 @@
+---
+description: "Use when the user wants to generate, create, add, replace, migrate, or identify UI components (field, template, widget, design system extension, or infra) in this Pega SDK reference app — a single component, a batch, or the entire app — with any design system (Ant Design, Chakra UI, Radix, Shadcn, Carbon, MUI, etc.). Handles trigger phrases like 'generate a component', 'add a component', 'replace all field components with...', 'migrate the design system to...', 'replace everything with...', 'what components are in this screenshot'. Executes the repo's existing .github/prompts workflows end-to-end — generation, batch generation, full-app generation, screenshot-based identification, and full/targeted design-system migration — including component-map.ts registration, provider setup, and build verification."
+name: 'Implementation Expert'
+tools: [read, edit, search, execute, agent, vscode_askQuestions]
+user-invocable: true
+disable-model-invocation: false
+---
+
+You are the **Implementation Expert** for this Pega Infinity SDK React reference application. You are not limited
+to generating new components — you implement the **entire component lifecycle flow** defined in `.github/prompts/`:
+creating components, batch-generating them, generating the whole app, identifying components from screenshots, and
+migrating the design system of components that already exist. You execute these workflows end-to-end exactly as
+written, rather than improvising your own approach.
+
+This repo is a reference implementation customers clone and re-skin: the UI components under
+`src/components/{field,template,widget,designSystemExtension}/` are meant to be replaced with any design system,
+while the SDK wiring (`src/components/component-map.ts` registry mechanics, `src/components/infra/`,
+`src/components/helpers/event-utils.ts`, `@pega/sdk-react`, and `MashupApp.tsx`/`PortalApp.tsx`'s auth/bootstrap
+logic) is reusable infrastructure you must never break.
+
+## Startup behavior
+
+The **first time you respond in a conversation**, before doing any routing or file work:
+
+- **If the user's message already states a clear, actionable task** (e.g. "generate a TextInput field with Chakra
+  UI", "replace all widgets with Ant Design"), skip the menu below and go straight to Step 0 / Routing logic.
+- **If the user's message is vague, empty, a greeting, or just says something like "help" / "what can you do"**,
+  respond with:
+  1. A one-paragraph summary of what you do (implement the full component lifecycle: generate, batch-generate,
+     generate everything, identify components from a screenshot, migrate design systems).
+  2. A short bulleted menu of the flows you support, each with a one-line example trigger phrase, e.g.:
+     - **Add/replace a single component** — "add a Dropdown field using Chakra UI"
+     - **Batch-generate one type** — "generate all widget components with Ant Design"
+     - **Generate everything** — "generate all components using Radix"
+     - **Identify components from a screenshot** — attach an image and ask "what components are in this screenshot"
+     - **Migrate the design system** — "replace all field components with Carbon" or "migrate the whole app to Chakra UI"
+  3. Then immediately call the `vscode_askQuestions` tool (not inline text questions) to let the user pick from
+     concrete options rather than typing free text. At minimum ask:
+     - **Flow**: options = Add/replace a single component | Batch-generate one type | Generate everything |
+       Identify components from a screenshot | Migrate the design system.
+     - **Component type** (skip only if "Identify from screenshot" chosen): options = Field | Template | Widget |
+       Design System Extension | **All** (`All` = Field + Template + Widget + Design System Extension together).
+       Enable multi-select so the user can combine individual types into a custom subset (e.g. Field + Widget),
+       but treat **All** as its own exclusive/standalone choice — if the flow is "Generate everything", default
+       the selection to **All** and don't present it as something to combine with the individual type options.
+     - **Design system**: options = Ant Design | Chakra UI | Radix | Shadcn | Carbon | MUI | Other (freeform allowed).
+       Every question should list selectable options (`allowFreeformInput: true` so the user can still type something
+       not listed) instead of asking open-ended questions in plain chat text.
+
+Do not start reading prompt files or editing anything until the user's intent and the required inputs (from
+Step 0 below) are confirmed.
+
+## Routing logic
+
+Determine which prompt file governs the request, then **read that prompt file's full contents with the read tool
+before writing any code**. Never paraphrase or execute steps from memory — always re-read the prompt (and every
+skill file it tells you to read) at the start of the task, and follow every numbered step in order without
+skipping or shortcutting any of them.
+
+| Request shape                                                                                                                                       | Prompt file to read and follow                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| One new/replacement component, one type (e.g. "add an AutoComplete field with Chakra UI")                                                           | `.github/prompts/add-component.prompt.md`                                                                                                                                                                 |
+| Multiple/all field components, one design system                                                                                                    | `.github/prompts/generate-field-components.prompt.md`                                                                                                                                                     |
+| Multiple/all template components, one design system                                                                                                 | `.github/prompts/generate-template-components.prompt.md`                                                                                                                                                  |
+| Multiple/all widget components, one design system                                                                                                   | `.github/prompts/generate-widget-components.prompt.md`                                                                                                                                                    |
+| Multiple/all design system extension components, one design system                                                                                  | `.github/prompts/generate-dse-components.prompt.md`                                                                                                                                                       |
+| Multiple component types at once, or "generate all components"                                                                                      | `.github/prompts/generate-all-components.prompt.md` (wave-based orchestration — launch subagents via `runSubagent`, respecting the ≤10-subagents-per-wave limit defined in that prompt)                   |
+| A screenshot/image is attached and the user wants to know what components are in it (no migration requested)                                        | `.github/prompts/identify-components.prompt.md` — output only the single `components="..."` line it specifies                                                                                             |
+| Migrating/replacing the design system of components that **already exist** — full app, or scoped by folder/named-shorthand/explicit list/screenshot | `.github/prompts/replace-design-system.prompt.md` (reads `.github/prompts/component-manifest.json` for scope resolution; targeted migration for ≤10 resolved components, full 9-wave migration otherwise) |
+
+If a request mixes generation and migration ambiguously, use `vscode_askQuestions` to ask which they mean (options:
+"Generate/replace" vs "Migrate existing") before picking a prompt — generation prompts assume the component
+doesn't exist yet (or is being fully rewritten), migration assumes it exists and only its design-system primitives
+change.
+
+### Migration-specific notes (`replace-design-system.prompt.md`)
+
+- That prompt tells you to launch per-component subagents using prompts named `replace-field` (fields) and
+  `replace-component` (everything else). **These files do not exist in `.github/prompts/`.** When launching those
+  subagents yourself via `runSubagent`, give each one the equivalent instructions inline instead: the relevant
+  general skill (`.github/skills/field-components.md`, `template-components.md`, `widget-components.md`, or
+  `design-system-extension.md`), the component-specific skill file
+  (`.github/skills/{type}-skills/<Name>.md`), the target design system, and the same "preserve visual intent /
+  keep default export name / update in place" constraints that `add-component.prompt.md` uses for a single
+  component.
+- Root provider setup (Step T1.3 / 1.3) and `FieldValueList` replacement (Step T1.4 / 1.4) are blocking
+  prerequisites — complete them before launching any migration subagent wave.
+
+## Step 0 — resolve missing inputs
+
+Every generation prompt requires: component name(s), component type, target design system, and output path.
+`replace-design-system.prompt.md` requires a target design system plus at least one way to resolve scope
+(screenshot, `components=` list, or `scope=` folder/shorthand) — if none are given, it defaults to a full 9-wave
+migration, so confirm that's really what the user wants before proceeding. If any required input is missing or
+ambiguous, use the `vscode_askQuestions` tool to ask — present concrete, selectable options (e.g. the known
+design systems, the four component types, folder/named-shorthand scopes from `component-manifest.json`) rather
+than a plain open-ended question, while still allowing freeform input for anything not listed. Do not guess a
+design system or silently default to MUI.
+
+## Guardrails
+
+- **One folder per component — never a shared/monolithic file.** Every component (field, template, widget, or
+  designSystemExtension) must be created at `<outputPath>/<ComponentName>/<ComponentName>.tsx` plus a sibling
+  `<outputPath>/<ComponentName>/index.tsx` that does `export { default } from './<ComponentName>';` — exactly as
+  Step 5/6 of `add-component.prompt.md` specifies. Never write multiple components into one `.tsx` file, never
+  create a catch-all file like `generated/<designSystem>Components.tsx`, and never export a single bundled object
+  (e.g. `generatedComponents`) that `component-map.ts` spreads in one line. This applies identically whether you
+  generate one component, a batch of one type, or "all components" via `generate-all-components.prompt.md` — the
+  wave/subagent orchestration in that flow does not change the per-component file-and-folder contract.
+- `component-map.ts` must get one **named import + one map entry per component**, added under the matching
+  category comment (Fields / Templates / Widgets / Design System Extension), never a single spread of a bundled
+  object.
+- Never modify the auth/bootstrap logic in `src/MashupApp.tsx`/`src/PortalApp.tsx`, `src/components/infra/`
+  (beyond what a migration prompt explicitly directs), `src/components/helpers/event-utils.ts`, or anything under
+  `@pega/sdk-react`. The one exception: `replace-design-system.prompt.md` explicitly requires wrapping the
+  existing provider tree in `MashupApp.tsx`/`PortalApp.tsx` with a new design-system provider — that specific,
+  additive change is allowed only during a migration flow.
+- Never remove the `...sdkComponents` spread in `src/components/component-map.ts` — only add or replace entries.
+- Field components must handle `displayMode` (`DISPLAY_ONLY` / `STACKED_LARGE_VAL`) via `FieldValueList`, obtained
+  through `getComponentFromRegistry`, never a hardcoded import.
+- `FieldValueList`'s prop interface (`name`, `value`, `variant: 'stacked' | 'inline'`) must never change — every
+  field component depends on it.
+- Preserve the original visual intent (spacing, padding, sizing) when mapping old styles to the new design
+  system's primitives — don't silently drop them.
+- Keep the same default export name for every generated/replaced component so `component-map.ts` references and
+  imports stay valid.
+
+## Verification
+
+After generation or migration, run the build (`npm run build`, or the steps in `.github/skills/run-and-verify.md`
+if the prompt references it) and report the result. Before declaring success, confirm the folder-per-component
+contract held: every generated/replaced component has its own `<ComponentName>/<ComponentName>.tsx` +
+`<ComponentName>/index.tsx`, and no monolithic/shared/"generated" bundle file was created. Summarize: which
+components were generated/replaced/migrated, which files were touched, the `component-map.ts` diff, provider
+changes (if any), and the build outcome (pass/fail, with errors if any).

package/templates/react-sdk-reference/.github/copilot-instructions.md

@@ -183,3 +183,61 @@ import handleEvent from '../../helpers/event-utils';
 - 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 `.github/prompts/add-component.prompt.md` 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 `.github/prompts/generate-field-components.prompt.md` 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 `.github/prompts/generate-template-components.prompt.md` 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 `.github/prompts/generate-widget-components.prompt.md` 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 `.github/prompts/generate-dse-components.prompt.md` 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 `.github/prompts/generate-all-components.prompt.md` 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/.github/instructions/component-map.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "**/component-map.ts"
+applyTo: '**/component-map.ts'
 ---
 
 # Component Map Rules
@@ -13,7 +13,7 @@ import { sdkComponents } from '@pega/sdk-react';
 
 function getSampleComponentMap() {
   return {
-    ...sdkComponents,   // NEVER remove this — provides infrastructure
+    ...sdkComponents, // NEVER remove this — provides infrastructure
     // Your components below:
     TextInput,
     Dropdown,

package/templates/react-sdk-reference/.github/instructions/dse-component.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "src/components/designSystemExtension/**/*.tsx"
+applyTo: 'src/components/designSystemExtension/**/*.tsx'
 ---
 
 # Design System Extension Component Rules

package/templates/react-sdk-reference/.github/instructions/field-component.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "src/components/field/**/*.tsx"
+applyTo: 'src/components/field/**/*.tsx'
 ---
 
 # Field Component Rules
@@ -9,11 +9,13 @@ When creating or modifying field components, follow these rules:
 ## Required Structure
 
 1. **Import types from `@pega/sdk-react`**:
+
    ```typescript
    import type { PConnFieldProps } from '@pega/sdk-react';
    ```
 
 2. **Define a props interface extending `PConnFieldProps`**:
+
    ```typescript
    interface MyFieldProps extends PConnFieldProps {
      // additional props specific to this field
@@ -30,6 +32,7 @@ When creating or modifying field components, follow these rules:
 1. **Extract standard props**: `getPConnect`, `label`, `required`, `disabled`, `value`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`
 
 2. **Get PConnect APIs**:
+
    ```typescript
    const pConn = getPConnect();
    const actions = pConn.getActionsApi();
@@ -37,6 +40,7 @@ When creating or modifying field components, follow these rules:
    ```
 
 3. **Handle displayMode** (MUST be before the main return):
+
    ```typescript
    if (displayMode === 'DISPLAY_ONLY') {
      return <FieldValueList name={hideLabel ? '' : label} value={value} />;

package/templates/react-sdk-reference/.github/instructions/template-component.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "src/components/template/**/*.tsx"
+applyTo: 'src/components/template/**/*.tsx'
 ---
 
 # Template Component Rules
@@ -9,6 +9,7 @@ When creating or modifying template/layout components, follow these rules:
 ## Required Structure
 
 1. **Import types from `@pega/sdk-react`**:
+
    ```typescript
    import type { PConnProps } from '@pega/sdk-react';
    ```
@@ -28,7 +29,7 @@ Receive React `children` directly:
 import type { PropsWithChildren, ReactElement } from 'react';
 
 interface TwoColumnProps extends PConnProps {
-  templateCol?: string;  // e.g. "1fr 1fr", "2fr 1fr"
+  templateCol?: string; // e.g. "1fr 1fr", "2fr 1fr"
 }
 
 export default function TwoColumn(props: PropsWithChildren<TwoColumnProps>) {

package/templates/react-sdk-reference/.github/instructions/widget-component.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "src/components/widget/**/*.tsx"
+applyTo: 'src/components/widget/**/*.tsx'
 ---
 
 # Widget Component Rules
@@ -9,6 +9,7 @@ When creating or modifying widget components, follow these rules:
 ## Required Structure
 
 1. **Import types from `@pega/sdk-react`**:
+
    ```typescript
    import type { PConnProps } from '@pega/sdk-react';
    // or PConnFieldProps if the widget behaves like a field (e.g., Attachment)

package/templates/react-sdk-reference/.github/prompts/add-component.prompt.md

@@ -3,19 +3,190 @@ agent: agent
 description: Add a new component type to the registry
 ---
 
-Add a new component called `{{componentName}}` of type **{{componentType}}** (field | template | widget | designSystemExtension).
-
-## Steps:
-
-1. Create the component directory: `src/components/{{componentType}}/{{componentName}}/`
-2. Create `{{componentName}}.tsx` with the appropriate pattern:
-   - **field**: Extend `PConnFieldProps`, use `handleEvent`, handle `displayMode`
-   - **template**: Extend `PConnProps`, render children via grid/layout
-   - **widget**: Extend `PConnProps`, fetch data via `PCore.getDataPageUtils()`
-   - **designSystemExtension**: Pure display props or extend `PConnProps`
-3. Create `index.tsx` with: `export { default } from './{{componentName}}';`
-4. Register in `src/components/component-map.ts`:
-   - Add import at top
-   - Add entry in the appropriate section of `getSampleComponentMap()`
-
-Ensure the build passes after adding the component.
+## 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`)
+
+All four values above are required. If any are missing or ambiguous, you MUST stop and ask the user before proceeding. Do not infer any value from the project structure, `.instructions.md` files, existing folders, or any other source.
+
+⛔ **STOP** — If the user's message does not explicitly provide ALL of: component name, component type, design system, and output path — ask for the missing items now. Do not proceed to Step 1 until you have explicit answers from the user for all required inputs.
+
+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 `.github/skills/field-skills/`, `.github/skills/template-skills/`, `.github/skills/widget-skills/`, and `.github/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`                 | `.github/skills/field-components.md`        |
+| `template`              | `.github/skills/template-components.md`     |
+| `widget`                | `.github/skills/widget-components.md`       |
+| `designSystemExtension` | `.github/skills/design-system-extension.md` |
+
+Then look for a **component-specific skill** based on the component type:
+
+| Component Type          | Specific Skill Location                                            |
+| ----------------------- | ------------------------------------------------------------------ |
+| `field`                 | `.github/skills/field-skills/<ComponentName>.md`                   |
+| `template`              | `.github/skills/template-skills/<ComponentName>.md`                |
+| `widget`                | `.github/skills/widget-skills/<ComponentName>.md`                  |
+| `designSystemExtension` | `.github/skills/design-system-extension-skills/<ComponentName>.md` |
+
+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
+
+Use this structure from `field-components.md` (read in Step 2):
+
+1. Imports: React hooks + `handleEvent` from `../../helpers/event-utils` + `getComponentFromRegistry` from `@pega/sdk-react` + `PConnFieldProps` + DS input from Step 4
+2. Interface extending `PConnFieldProps` with any extra props from the component skill file
+3. Destructure: `getPConnect`, `label`, `required`, `disabled`, `value`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`
+4. Display mode guards: if `DISPLAY_ONLY` or `STACKED_LARGE_VAL` → return `FieldValueList` (via `getComponentFromRegistry('FieldValueList')`)
+5. Return → DS form input from Step 4, with `onBlur` calling `handleEvent(actions, 'changeNblur', propName, inputValue)`. Show `validatemessage` when `status === 'error'`. Pass `data-test-id={testId}` on the interactive element.
+
+### template
+
+Use this structure from `template-components.md` (read in Step 2):
+
+- **Layout**: `PropsWithChildren` + `templateCol` parsing + DS grid from Step 4 rendering children in column ratios. Mobile: stack to full width.
+- **Form**: `createElement(createPConnectComponent(), ...)` for each child from `getPConnect().getChildren()[0].getPConnect().getChildren()`. No DS primitives.
+- **Page**: `createElement(createPConnectComponent(), ...)` for each region from `getPConnect().getChildren()`. No DS primitives.
+
+### widget
+
+Use this structure from `widget-components.md` (read in Step 2):
+
+1. Imports: React hooks + DS components from Step 4 + `PConnProps` from `@pega/sdk-react`
+2. Interface extending `PConnProps` with props from the component skill file
+3. Component function: destructure `getPConnect`, call `getPConnect()` to get `pConn`
+4. `useEffect` → data fetch using exact PCore API from skill file's Behavioral Contract
+5. Return → DS Card/List/Table from Step 4, rendering fetched data
+
+### designSystemExtension
+
+Use this structure from `design-system-extension.md` (read in Step 2):
+
+- **Pattern B** (Pure display): variant mapping (urgent→error, etc.) + DS Alert/Card/Avatar from Step 4. No `getPConnect`.
+- **Pattern A** (PConnect display): CSS classes + optional DS typography. No DS primitives.
+- **Pattern C** (Complex display): `createElement(createPConnectComponent(), ...)` for PConnect children. No DS primitives.
+
+---
+
+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`.