@pega/sdk 0.0.5 → 0.0.6

package/templates/react-sdk-reference/.ai-common/global/ai-agent-instructions.md

@@ -1,12 +1,12 @@
-# Pega SDK — React Reference App
+# Pega SDK — Reference App
 
-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).
+You are assisting developers in a reference application that demonstrates the Pega Infinity SDK. Customers clone this repo and **replace the sample UI components with their own design system** (Ant Design, Chakra UI, Carbon, Radix UI, Shadcn/ui, MUI, 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.
+This is a **reference implementation** — not a framework. The UI components (fields, templates, widgets) are intentionally simple sample implementations meant to be swapped out. The SDK wiring (bootstrap, PConnect bridge, component registry) is reusable infrastructure that should NOT be modified.
 
 ---
 
@@ -14,22 +14,22 @@ This is a **reference implementation** — not a framework. The UI components (f
 
 ### 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.) |
+| Area                          | Purpose                                                     |
+| ----------------------------- | ----------------------------------------------------------- |
+| Field components directory    | Form field components (TextInput, Dropdown, Date, etc.)     |
+| Template components directory | Layout templates (OneColumn, TwoColumn, Details, etc.)      |
+| Widget components directory   | Data widgets (ToDo, Attachment, CaseHistory, etc.)          |
+| DSE components directory      | 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                                 |
+| Area                         | Purpose                                   |
+| ---------------------------- | ----------------------------------------- |
+| Application bootstrap module | Auth + bootstrap + root rendering         |
+| Component map file           | Registry wiring (only add/remove entries) |
+| Infrastructure components    | ActionButtons, Stages, NavBar, etc.       |
+| Event handling helper module | PConnect event handler utility            |
+| SDK bridge package           | SDK bridge — never modify                 |
 
 ---
 
@@ -37,150 +37,99 @@ This is a **reference implementation** — not a framework. The UI components (f
 
 ### 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
-```
+Every component receives `getPConnect` as a prop. This is the bridge to the Pega platform. From it you obtain the PConnect instance, from which you access the actions API (for field updates) and state props (for the current 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);
-}
-```
+- On **change**: update local component state only (do not push to the platform on every keystroke).
+- On **blur**: call the project's event handling helper with the actions API, a `'changeNblur'` action type, the property name, and the current local value. This pushes the value to the Pega platform.
 
 ### Display Mode Handling
 
-Field components must handle `displayMode` prop:
+Field components must handle the `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'`
+- `undefined` → render the editable input
+- `'DISPLAY_ONLY'` → render a read-only label-value pair via the project's field-value display component
+- `'STACKED_LARGE_VAL'` → render the same display component with a `stacked` variant
 
 ### Component Registry
 
-Components are registered by name in `src/components/component-map.ts`:
+Components are registered by name in the project's component map file. The map function returns an object that spreads the SDK's built-in component set (providing infrastructure like View, Region, FlowContainer, etc.) and then adds the project's own components.
 
-```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 add a new component: add the import and add an entry 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;
-}
-```
+### Field Components
+
+Field components extend the SDK's field props interface. The standard props available to every field component are:
+
+- `getPConnect` — function returning the PConnect accessor
+- `label` — field label text
+- `required` — whether the field is required
+- `disabled` — whether the field is disabled
+- `value` — current field value
+- `validatemessage` — validation error message text
+- `status` — `'error'` | `'warning'` | undefined
+- `onChange` — change handler
+- `onBlur` — blur handler
+- `readOnly` — whether the field is read-only
+- `testId` — test identifier to pass to the interactive element
+- `helperText` — helper/hint text
+- `displayMode` — `'DISPLAY_ONLY'` | `'STACKED_LARGE_VAL'` | undefined
+- `hideLabel` — whether to suppress the label
+- `placeholder` — placeholder text
+
+### Template/Widget Components
+
+Template and widget components extend the SDK's base props interface, which provides:
+
+- `getPConnect` — function returning the PConnect accessor
 
 ---
 
 ## 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.
+1. **Keep the same export convention** — the component map references it.
+2. **Keep `getPConnect` wiring intact** — extract props and call the event handling helper on blur.
+3. **Handle `displayMode`** — render the field-value display component 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.
+5. **Preserve the test id attribute** — pass `testId` to the root interactive element.
+6. **Use the component registry** to render sub-components (e.g., the field-value display component) — 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
+## 6. Build & Dev
 
-# From this directory (standalone):
-npm run dev                # Vite dev server (port 3500)
-npm run build              # Production build
-```
+Use the project's build script to compile the application and verify there are no errors. Use the project's dev script to start the development server for local testing. If working within the monorepo, run the build/dev commands from the monorepo root; if working standalone in this directory, run them locally.
 
 ---
 
-## 7. Key Imports
+## 7. Key SDK Utilities
+
+The SDK bridge package provides the following utilities (import from the package entry point only — never from internal paths):
 
-```typescript
-// From SDK (never modify these)
-import {
-  PConnectComponent,
-  PegaStoreContext,
-  registerComponentCreator,
-  getComponentFromRegistry,
-  sdkComponents,
-} from '@pega/sdk-react';
-import type { PConnProps, PConnFieldProps } from '@pega/sdk-react';
+- **PConnect bridge component** — renders a PConnect-managed child component
+- **Store context** — provides the SDK store to the component tree
+- **Component creator registration** — registers custom component factories
+- **Component registry lookup** — retrieves a registered component by its Pega name
+- **Built-in SDK component set** — the infrastructure components that must always be spread into the component map
 
-// Event utility (preserve this)
-import handleEvent from '../../helpers/event-utils';
-```
+The project also provides an **event handling helper module** that wraps PConnect action calls for consistent field event handling (change + blur pattern).
 
 ---
 
 ## 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`.
+- Modify the application bootstrap module when replacing design system components.
+- Import from internal SDK package paths — use the package entry point only.
+- Hardcode component references — use the component registry for components that may be overridden.
+- Remove the SDK's built-in component spread from the component map.
 - Use `any` without justification — prefer `unknown` and narrow.
 - Add `@ts-ignore` — use `@ts-expect-error` with explanation if truly needed.
 

package/templates/react-sdk-reference/.ai-common/instructions/component-map.md

@@ -1,32 +1,20 @@
 ---
-ai-globs: **/component-map.ts
+ai-globs: **/component-map.*
 ---
 
 # Component Map Rules
 
-The component map (`src/components/component-map.ts`) is the registry that maps Pega component names to React implementations.
+The component map is the registry that maps Pega component names to their framework-specific implementations.
 
 ## Structure
 
-```typescript
-import { sdkComponents } from '@pega/sdk-react';
-
-function getSampleComponentMap() {
-  return {
-    ...sdkComponents, // NEVER remove this — provides infrastructure
-    // Your components below:
-    TextInput,
-    Dropdown,
-    // ...
-  };
-}
-```
+The component map file exports a function that returns an object where each key is a Pega component name and each value is the corresponding component implementation. It spreads the SDK's built-in component set first, then adds project-specific components below.
 
 ## Rules
 
-1. **NEVER remove `...sdkComponents`** — it provides View, Region, Reference, RootContainer, FlowContainer, ViewContainer, Assignment, AssignmentCard, ErrorBoundary, MultiStep, CaseSummary, and their aliases.
+1. **NEVER remove the SDK's built-in component spread** — it provides infrastructure components (View, Region, Reference, RootContainer, FlowContainer, ViewContainer, Assignment, AssignmentCard, ErrorBoundary, MultiStep, CaseSummary, and their aliases).
 
-2. **Map keys must match Pega component names exactly** — these are resolved at runtime by the platform. The key is what Pega sends; the value is your React component.
+2. **Map keys must match Pega component names exactly** — these are resolved at runtime by the platform. The key is what Pega sends; the value is your component implementation.
 
 3. **To replace a component**: change its import path to your new implementation. Do NOT rename the key.
 
@@ -37,9 +25,9 @@ function getSampleComponentMap() {
    - `URL: URLComponent` (URL is a global)
    - `Todo: ToDo` (casing difference)
 
-6. **Keep the `registerSampleComponents` function** — it registers all entries into the `ComponentRegistry` instance used by the PConnect bridge.
+6. **Keep the registration function** — it registers all entries into the component registry instance used by the PConnect bridge.
 
-7. **Sub-component registration** — Some template/widget components internally render sub-components via `getComponentFromRegistry()`. These sub-components MUST also be registered in the component map or they will be `undefined` at runtime. Known sub-components:
+7. **Sub-component registration** — Some template/widget components internally render sub-components via the component registry. These sub-components MUST also be registered in the component map or they will be `undefined` at runtime. Known sub-components:
    - `SearchForm` — used by `DataReference` and `AdvancedSearch`
    - `SearchGroups` — used by `AdvancedSearch`
    - `ActionButtonsForFileUtil` — used by `FileUtility`

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

@@ -1,5 +1,5 @@
 ---
-ai-globs: src/components/designSystemExtension/**/*.tsx
+ai-globs: **/designSystemExtension/**/*
 ---
 
 # Design System Extension Component Rules
@@ -8,7 +8,7 @@ When creating or modifying DSE components, follow these rules:
 
 ## What Are DSE Components?
 
-Design System Extension components are display-focused presentational components. They sit between pure UI and data-fetching widgets. Some receive `getPConnect`, others receive only display props.
+Design System Extension components are display-focused presentational components. They sit between pure UI and data-fetching widgets. Some receive a PConnect accessor, others receive only display props.
 
 ## Patterns
 
@@ -16,49 +16,19 @@ Design System Extension components are display-focused presentational components
 
 Used for: FieldValueList, CaseSummaryFields, DetailsFields
 
-```typescript
-import type { PConnProps } from '@pega/sdk-react';
-
-interface FieldValueListProps extends PConnProps {
-  name?: string;
-  value?: string;
-  variant?: 'stacked' | 'inline';
-}
-
-export default function FieldValueList(props: FieldValueListProps) {
-  const { name, value, variant = 'inline' } = props;
-  // Render a label-value pair
-}
-```
+These components extend the base PConnect props interface and receive a PConnect accessor. FieldValueList additionally accepts `name`, `value`, and an optional `variant` (`'stacked'` | `'inline'`) prop that controls its layout — it renders a label-value pair.
 
 ### Pattern B: Without PConnect (pure presentation)
 
 Used for: AlertBanner, Banner, Operator
 
-```typescript
-interface AlertBannerProps {
-  variant: 'urgent' | 'warning' | 'info' | 'success';
-  heading?: string;
-  messages: Array<string | { label?: string; description?: string }>;
-  onClose?: () => void;
-}
+These components receive only plain display props — no PConnect awareness. AlertBanner accepts a `variant` (`'urgent'` | `'warning'` | `'info'` | `'success'`), an optional `heading`, a `messages` array (strings or `{ label, description }` objects), and an optional `onClose` callback.
 
-export default function AlertBanner(props: AlertBannerProps) {
-  // Render an alert/notification banner
-}
-```
-
-### Pattern C: Rich editor (extends PConnFieldProps)
+### Pattern C: Rich editor (extends field props)
 
 Used for: RichTextEditor
 
-```typescript
-import type { PConnFieldProps } from '@pega/sdk-react';
-
-interface RichTextEditorProps extends PConnFieldProps {
-  content?: string;
-}
-```
+This component extends the base field props interface (the same interface used by field components) and adds a `content` prop.
 
 ## Visual Preservation
 
@@ -66,12 +36,12 @@ The replacement must look the same as the original component:
 
 1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
 2. Replicate those styles via inline `style` props, the new design system's props/variants, or by keeping the CSS import — whichever produces the closest match.
-3. Do NOT silently drop `makeStyles` classes — map each one to an equivalent style.
+3. Do NOT silently drop legacy styling utility classes — map each one to an equivalent style.
 
 ## Key Rules
 
-- DSE components are the **most commonly referenced by other components** via `getComponentFromRegistry('FieldValueList')` — every field uses FieldValueList for display modes
-- Keep the same export name (default export) and prop interface shape
+- DSE components are the **most commonly referenced by other components** via the project's component registry — every field uses FieldValueList for display modes
+- Keep the same export convention and prop interface shape used elsewhere in the project
 - If you replace FieldValueList, ensure it accepts `name`, `value`, and optional `variant` props
 - AlertBanner must handle the `messages` array format (both strings and `{label, description}` objects)
-- Do NOT drop visual styles when removing `makeStyles` — always map them to an equivalent
+- Do NOT drop visual styles when removing legacy styling utility classes — always map them to an equivalent

package/templates/react-sdk-reference/.ai-common/instructions/embedded-component.md

@@ -0,0 +1,134 @@
+---
+ai-globs: pega-components/**/*
+---
+
+# Embedded Component Rules
+
+When generating or modifying Pega components in the `pega-components/` folder (components created for embedding into a customer's existing application), follow these rules.
+
+---
+
+## Context
+
+These components are different from the reference app's sample components. They are generated to live **inside a customer's existing project**, using the customer's design system so that they are visually indistinguishable from the rest of their UI. The Design Profile (`.design-profile.md`) in the same folder describes the customer's visual conventions.
+
+---
+
+## Mandatory Behavioral Contract
+
+Every generated component must satisfy the behavioral requirements defined in its type-level and component-specific skill files. These are non-negotiable regardless of the customer's framework or design system.
+
+### All components must:
+
+1. **Accept and use the PConnect accessor** — this is the bridge to the Pega runtime. Every component receives it and must use it to access state, actions, and child descriptors. Two things are exceptions and receive plain display props instead: a pure-presentation design system extension component (Pattern B in the DSE component rules) — see rule 11 — and the `ActionButtons` chrome component — see rule 14.
+
+2. **Support the component registry** — when a component needs to render another Pega component (e.g., a display-mode renderer or a child component), it must resolve that component through the SDK's component registry, never through direct import of another generated component.
+
+3. **Preserve the test identifier** — pass the provided test identifier through to the primary interactive or container element for automation purposes.
+
+### Field components must additionally:
+
+4. **Handle display modes** — at minimum, support an editable mode and a display-only mode. When in display-only mode, render the value using the display-mode renderer resolved from the registry.
+
+5. **Wire value change and commit events** — local edits update internal state; on commit (blur or equivalent), propagate the value to the Pega store via the SDK actions API.
+
+6. **Render validation feedback** — when validation messages are present, display them following the customer's validation display convention (from the Design Profile).
+
+7. **Respect disabled and read-only states** — honor these flags from the input contract.
+
+### Template components must additionally:
+
+8. **Traverse and render children** — obtain child component descriptors from the PConnect accessor and render each via the SDK bridge component.
+
+9. **Propagate inherited properties** — pass display mode, read-only state, and other inherited properties down to children via the PConnect accessor's inheritance mechanism.
+
+### Widget components must additionally:
+
+10. **Consume configuration from PConnect** — widgets receive their display data (headers, descriptions, data sources) as resolved properties from the PConnect accessor.
+
+### Design system extension components must additionally:
+
+11. **Follow their pattern's input contract** — the DSE component rules define three patterns and are the authority on which one each component belongs to. Pattern A in the DSE component rules (data-aware display, e.g. `FieldValueList`, `CaseSummaryFields`, `DetailsFields`) receives the PConnect accessor; Pattern B (pure presentation, e.g. `AlertBanner`, `Banner`, `Operator`) receives plain display props only; Pattern C (rich editor, `RichTextEditor`) extends the field input contract.
+
+12. **Render display content only** — these components do not own field state, so they never wire value change or commit events.
+
+13. **Keep the prop shape other components depend on** — DSE components are resolved through the registry by fields, templates, and widgets rather than imported directly. `FieldValueList` in particular backs every field component's display-only mode and must keep accepting `name`, `value`, and an optional `variant`.
+
+### Infrastructure (chrome) components must additionally:
+
+14. **Reproduce the SDK component's prop contract exactly** — `ActionButtons`, `MultiStep`, and `Stages` override components the SDK already provides, so Pega calls them with a contract that is already fixed. They do not share one shape: `ActionButtons` receives no PConnect accessor, only `arMainButtons`, `arSecondaryButtons`, and an `onButtonPress(action, buttonType)` callback; `Stages` receives the PConnect accessor plus `stages`; `MultiStep` receives the PConnect accessor plus `children`, `itemKey`, `actionButtons`, and `onButtonPress`. Read the component's skill file in `{{SKILL_DIR}}/infra-skills/` before generating.
+
+15. **Localize labels through Pega** — button and step text comes from the Pega locale utilities using the locale category the SDK component uses, never from hardcoded strings. Only markup and styling are yours to change.
+
+---
+
+## Customer Convention Compliance
+
+**The customer owns how it looks. Pega owns how it behaves.** Generated components must be visually indistinguishable from the customer's own UI — their design system, styling mechanism, tokens, and theme are authoritative for appearance. Everything behavioural — state, events, prop contracts, paths, names, registry keys — follows the Pega contract, no matter how the customer does it in their own code.
+
+The Design Profile documents both, but only its visual half is authoritative. Its Component Patterns and File Conventions sections describe how the customer writes _their_ components; they are context, not instructions.
+
+### Styling
+
+- Apply styles using the **same mechanism** the customer uses (utility classes, CSS modules, style objects, scoped styles, etc.)
+- Reference the customer's **design tokens** (colors, spacing, typography) — never hardcode raw values that bypass their token system
+- Handle conditional styling (error states, disabled states, focus states) the same way the customer's components do
+
+### File Structure
+
+- **Paths are fixed by Pega, not inferred from the customer.** Components live at `pega-components/{type}/{ComponentName}/{ComponentName}.{ext}`, where `{type}` is `field`, `template`, `widget`, `designSystemExtension`, or `infra`, and `{ComponentName}` is the component's canonical Pega name, verbatim, for both the folder and the implementation file — `Checkbox/Checkbox.*`, never `checkbox/CheckboxField.*`
+- **Resolve the canonical name, never assume it.** Step 1 of `{{PROMPT_DIR}}/generate-embedded-components{{PROMPT_EXT}}` defines the resolution procedure — normalized name match, then alias lookup, then behaviour class, then ask the user — against `{{PROMPT_DIR}}/component-manifest.json`. It is the authority, and it forbids fuzzy "similar sounding" matching. Follow it when adding a component by hand, not only when running the prompt
+- Use the customer's **file extension** for their framework
+- Use the customer's **export pattern** (default export, named export, barrel file)
+- Co-locate related files (styles, types, tests) according to the customer's convention
+
+### Code Style
+
+Behaviour is Pega's, not the customer's. Do **not** imitate how the customer handles:
+
+- **State** — field values live in local component state and are committed to the Pega store via the SDK actions API. Never route Pega state through the customer's form library or global store, even though that is how they manage their own forms
+- **Events** — change and commit are reported through the SDK actions API, not through the customer's event or form-submission idioms
+- **Prop and type definitions** — the input contract comes from the SDK's types. Extend them where a component needs extra inputs; never restructure them to match the customer's typing style
+
+The customer's platform still imposes constraints the generated code must satisfy in order to build and lint:
+
+- **Module resolution** — import their UI primitives through their path aliases, not hand-built relative paths
+- **Framework requirements** — include whatever their framework needs to run the component (client/server boundary directives, module format, language level)
+- **Lint and format rules** — generated files must pass the customer's linter and formatter unmodified
+
+---
+
+## Prohibitions
+
+1. **Never import from the customer's existing components** — generated Pega components are self-contained. If you need a UI primitive, import it from the customer's UI library package, not from their source components.
+
+2. **Never modify the customer's existing files while generating components** — the `pega-components/` folder is additive, and component generation writes nothing outside it.
+
+   **Exception — integration seams.** Wiring a case flow into the customer's app necessarily edits their code, and that is expected. `{{SKILL_DIR}}/embedded-flow/wire-integration.md` defines the complete set of permitted touch points: the dependency manifest, the HTML and application entry points, the OAuth callback assets, `sdk-config.json`, a new bootstrap module, the control or event that launches the case, the element that hosts the Pega container, the lifecycle event subscriptions, and the verification tooling described in `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration.md` (an additive verification folder, its script entry, and the version-control ignore rule for its session-state directory). Confine edits to those seams — make the smallest change that connects the customer's existing control to the SDK, and never restructure, restyle, or refactor the surrounding code while you are in there.
+
+   Verification does not widen this exception. A failing check is not permission to edit customer code outside these seams to make it pass — see `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration.md` for what may be fixed and what must only be reported.
+
+3. **Never introduce new dependencies** — only use packages already in the customer's dependency manifest plus the Pega SDK packages. If a needed package is missing, flag it to the user.
+
+4. **Never hardcode design token values** — always reference the customer's token system. If a specific value is needed and no token exists, use the closest available token and note the deviation.
+
+5. **Never skip display mode handling in field components** — even if the customer's equivalent doesn't have this concept, the Pega contract requires it.
+
+6. **Never bypass the component registry** — do not directly import other Pega components for rendering. Always resolve through the registry.
+
+7. **Never invent props or APIs** — the component's input interface is defined by the Pega behavioral contract (from skill files). Do not add extra required inputs that the SDK bridge won't provide.
+
+8. **Never omit the validation display** — field components must always render validation feedback when it is present, even if the customer's equivalent handles validation differently.
+
+---
+
+## Registry File Rules
+
+The `component-map.*` file in the `pega-components/` folder:
+
+1. Must export a registration function that accepts a component registry and registers all generated components
+2. Must spread/include the SDK's built-in infrastructure components (NavBar, DeferLoad, VerticalTabs, DashboardFilter and the structural set), which ship with the SDK's own styling
+3. May override three of them — `ActionButtons`, `MultiStep`, and `Stages`. These render inline with the case form, so they are generated in the customer's design system rather than left SDK-styled. `ActionButtons` and `MultiStep` are assignment chrome and belong in an embedded flow; `Stages` is case chrome and only applies to a case-view surface. Because an override replaces the spread entry, it must appear _after_ the spread
+4. Keys must match Pega's canonical component names exactly (case-sensitive)
+5. Must import each generated component and map it to its Pega name
+6. Must never contain a non-canonical key. Aliases and design-system names are resolved away _before_ registration by Step 1 of `{{PROMPT_DIR}}/generate-embedded-components{{PROMPT_EXT}}`, so they never appear here — Pega would never request them at runtime

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

@@ -1,5 +1,5 @@
 ---
-ai-globs: src/components/field/**/*.tsx
+ai-globs: **/field/**/*
 ---
 
 # Field Component Rules
@@ -8,71 +8,43 @@ When creating or modifying field components, follow these rules:
 
 ## Required Structure
 
-1. **Import types from `@pega/sdk-react`**:
+1. **Extend the base field props interface** — the project's standard field props type — when defining the component's prop interface.
 
-   ```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
-   }
-   ```
-
-3. **Export as default function component**:
-   ```typescript
-   export default function MyField(props: MyFieldProps) { ... }
-   ```
+2. **Export the component** using the project's standard export convention (matching other field components in the project).
 
 ## Required Behaviors
 
 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();
-   const propName = (pConn.getStateProps() as any).value;
-   ```
+2. **Get PConnect APIs**: obtain the actions API and the current property name from the PConnect accessor (`getPConnect()` → actions API, state props).
 
 3. **Handle displayMode** (MUST be before the main return):
-
-   ```typescript
-   if (displayMode === 'DISPLAY_ONLY') {
-     return <FieldValueList name={hideLabel ? '' : label} value={value} />;
-   }
-   if (displayMode === 'STACKED_LARGE_VAL') {
-     return <FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />;
-   }
-   ```
+   - When `displayMode` is `DISPLAY_ONLY`, render the value via the project's field-value display component (unlabeled if `hideLabel` is set).
+   - When `displayMode` is `STACKED_LARGE_VAL`, render the same display component with a `stacked` variant.
 
 4. **Use local state + blur pattern**:
    - `onChange` → update local state only
-   - `onBlur` → call `handleEvent(actions, 'changeNblur', propName, localValue)`
+   - `onBlur` → call the event helper with a `changeNblur` action, the property name, and the local value
 
 5. **Show validation**: Display `validatemessage` and apply error styling when `status === 'error'`
 
-6. **Pass test ID**: Set `data-test-id={testId}` on the interactive element
+6. **Pass test ID**: Set the test id attribute on the interactive element using the `testId` prop
 
-7. **Use `getComponentFromRegistry('FieldValueList')`** — never hardcode FieldValueList import
+7. **Use the component registry to look up the field-value display component** — never hardcode its import
 
 ## Visual Preservation
 
 The replacement must look the same as the original component:
 
 1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
-2. Replicate those styles via inline `style` props, {{designSystem}} component props/variants, or by keeping the CSS import — whichever produces the closest match.
-3. Do NOT silently drop `makeStyles` classes — map each one to an equivalent style.
+2. Replicate those styles via inline `style` props, the design system's component props/variants, or by keeping the CSS import — whichever produces the closest match.
+3. Do NOT silently drop legacy styling utility classes — map each one to an equivalent style.
 
 ## Do NOT
 
 - Skip `displayMode` handling — it breaks read-only views
-- Call `handleEvent` on every keystroke — only on blur
+- Call the blur handler on every keystroke — only on blur
 - Hardcode component imports for components that exist in the registry
-- Remove the `handleEvent` import from `../../helpers/event-utils`
-- Drop visual styles when removing `makeStyles` — always map them to an equivalent
-- **Import the same symbol twice from `field-utils`** — if you import `DynamicFieldProps` (or any other export) in one import statement, do NOT add a separate `import type { DynamicFieldProps }` line. This causes `"DynamicFieldProps is already defined"` errors. Use a single import: `import { commitField, DynamicFieldProps, FieldValue, getFieldContext } from '../field-utils';`
+- Remove the import of the event handling helper module
+- Drop visual styles when removing legacy styling utility classes — always map them to an equivalent
+- **Import the same symbol twice from the shared field utilities module** — if you import a type or helper in one import statement, do NOT add a separate import line for the same symbol elsewhere. This causes "already defined" errors. Use a single consolidated import.