@pega/sdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,119 @@
+# Pega SDK — Embedded Flow
+
+You are assisting a developer who is embedding a Pega case flow into their existing application. The Pega SDK renders workflow forms (case flows) inside the customer's app using components that match the customer's design system.
+
+---
+
+## 1. Context
+
+This is the customer's own application — **not** a Pega reference app. Pega skill files have been added to help generate components and wire the integration. The customer's existing code, design system, routing, and architecture must not be modified except where explicitly needed for Pega integration.
+
+---
+
+## 2. What the Pega SDK Does
+
+The Pega SDK connects to a Pega Infinity server and renders case workflow forms inside the customer's application. The workflow (which fields to show, what validation to apply, what happens next) is defined on the Pega server — the frontend only renders it.
+
+### Key Concepts
+
+| Concept                | Description                                                                                                                                                                       |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **PConnect**           | The bridge between the Pega runtime and UI components. Every Pega component receives a `getPConnect` accessor to read state and trigger actions.                                  |
+| **Component Registry** | A map of component names to implementations. The Pega runtime asks for a component by name; the registry returns the customer's implementation.                                   |
+| **Bridge Component**   | The SDK's component that recursively resolves and renders Pega components from the registry. It subscribes to PConnect state changes and passes resolved props to each component. |
+| **Display Mode**       | Components can render in editable mode or display-only mode. Field components must handle both.                                                                                   |
+| **Actions API**        | The PConnect accessor provides an actions API for reporting value changes and blur/commit events back to the Pega store.                                                          |
+
+---
+
+## 3. What Exists in This Project
+
+### Pega Skill Files
+
+AI skill files have been added to this project to assist with:
+
+- **Analyzing the codebase** — extracting design system, coding patterns, and conventions into a Design Profile
+- **Generating Pega components** — creating components that satisfy the Pega behavioral contract while matching the customer's design system
+- **Wiring the integration** — bootstrapping the SDK, launching case flows, and handling lifecycle events
+
+### SDK Packages
+
+Pega SDK packages (`.tgz` files) have been added to the project root and referenced in the dependency manifest. These provide:
+
+- The SDK adapter package (bridge component, runtime context, component registry)
+- The auth package (OAuth authentication with the Pega server)
+- The SDK types package (shared type definitions)
+- The ConstellationJS core (Pega runtime engine)
+
+### SDK Configuration
+
+`sdk-config.json` contains connection details for the Pega server. The customer must fill in their server URL, app alias, OAuth client ID, and case type.
+
+---
+
+## 4. Component Architecture
+
+### Field Components (form inputs)
+
+Extend the SDK's field input contract. Must:
+
+- Accept the PConnect accessor
+- Handle display modes (editable and display-only)
+- Wire value changes through the SDK actions API (local state on change, commit on blur)
+- Render validation feedback when present
+- Pass through the test identifier
+
+### Template Components (layouts)
+
+Extend the SDK's base component interface. Must:
+
+- Traverse child component descriptors via PConnect
+- Render children using the SDK bridge component
+- Propagate inherited properties (display mode, read-only state) to children
+
+### Widget Components (display blocks)
+
+Extend the SDK's base component interface. Must:
+
+- Consume configuration properties from PConnect (headers, descriptions, data sources)
+- Render display content — typically no interactive state management
+
+### Design System Extension Components (shared display building blocks)
+
+Presentational components that other Pega components resolve through the registry rather than import. Must:
+
+- Follow the input contract of their pattern — data-aware display components receive the PConnect accessor, pure-presentation components receive plain display props, and rich editors extend the field input contract
+- Render display content only — they do not own field state, so they never wire value changes
+- Preserve the prop shape their consumers rely on
+
+The most important one is `FieldValueList`: every field component renders its display-only mode through it, so it is required whenever the case contains any field.
+
+### Infrastructure Components (case chrome)
+
+Most infrastructure components ship from the SDK and are never generated. Three are overridable because they render inline with the case form, where SDK styling is the most visible mismatch: `ActionButtons` (the Cancel/Save/Submit row), `Stages` (the stage progress indicator), and `MultiStep` (step navigation within an assignment). When generated, these must:
+
+- Reproduce the SDK component's prop contract exactly — it differs per component, and `ActionButtons` receives plain display props rather than the PConnect accessor
+- Localize labels through the Pega locale utilities
+- Change markup and styling only
+
+---
+
+## 5. Rules
+
+1. **Never modify the customer's existing components during analysis or generation** — the `pega-components/` folder is additive. Wiring is the exception: it edits the integration seams listed in the wire-integration skill, plus the verification tooling seams listed in the run-and-verify-integration skill. A failing verification check never widens that set
+2. **Match the customer's conventions** — generated code should look like the customer wrote it
+3. **Satisfy the Pega behavioral contract** — every component must implement what its skill file requires
+4. **Use the customer's design system** — never introduce a new UI library
+5. **Reference design tokens, not raw values** — use the customer's variables/tokens for colors, spacing, etc.
+6. **Resolve sub-components via the registry** — never import other Pega components directly
+
+---
+
+## 6. Workflow Entry Points
+
+| Task                            | How to start                                |
+| ------------------------------- | ------------------------------------------- |
+| Analyze the customer's codebase | Use the analyze-customer-repo skill         |
+| Generate Pega components        | Use the generate-embedded-components prompt |
+| Wire the Pega SDK integration   | Use the wire-integration skill              |
+| Full end-to-end embedded flow   | Use the Embedded Flow Expert agent          |

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

@@ -0,0 +1,192 @@
+# Pega SDK — Reference App
+
+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 sample 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)
+
+| 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)
+
+| 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                 |
+
+---
+
+## 3. Component Architecture
+
+### The PConnect Bridge
+
+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:
+
+- 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 the `displayMode` prop:
+
+- `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 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.
+
+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
+
+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 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 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
+
+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 SDK Utilities
+
+The SDK bridge package provides the following utilities (import from the package entry point only — never from internal paths):
+
+- **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
+
+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 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.
+
+---
+
+## 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 `{{PROMPT_DIR}}/add-component{{PROMPT_EXT}}` 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 `{{PROMPT_DIR}}/generate-field-components{{PROMPT_EXT}}` 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 `{{PROMPT_DIR}}/generate-template-components{{PROMPT_EXT}}` 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 `{{PROMPT_DIR}}/generate-widget-components{{PROMPT_EXT}}` 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 `{{PROMPT_DIR}}/generate-dse-components{{PROMPT_EXT}}` 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 `{{PROMPT_DIR}}/generate-all-components{{PROMPT_EXT}}` 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/.ai-common/instructions/component-map.md

@@ -0,0 +1,35 @@
+---
+ai-globs: **/component-map.*
+---
+
+# Component Map Rules
+
+The component map is the registry that maps Pega component names to their framework-specific implementations.
+
+## Structure
+
+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 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 component implementation.
+
+3. **To replace a component**: change its import path to your new implementation. Do NOT rename the key.
+
+4. **To add a new component**: add the import + add a new key-value entry.
+
+5. **Key naming exceptions** (where key differs from variable name):
+   - `Date: DateField` (Date is reserved in JS)
+   - `URL: URLComponent` (URL is a global)
+   - `Todo: ToDo` (casing difference)
+
+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 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`
+
+8. **`Todo` vs `ToDo` key** — The Pega engine sends `Todo` (capital T, lowercase odo). The component variable may be named `ToDo`, but the map key MUST be `Todo: ToDo`.

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

@@ -0,0 +1,47 @@
+---
+ai-globs: **/designSystemExtension/**/*
+---
+
+# Design System Extension Component Rules
+
+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 a PConnect accessor, others receive only display props.
+
+## Patterns
+
+### Pattern A: With PConnect (data-aware display)
+
+Used for: FieldValueList, CaseSummaryFields, DetailsFields
+
+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
+
+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.
+
+### Pattern C: Rich editor (extends field props)
+
+Used for: RichTextEditor
+
+This component extends the base field props interface (the same interface used by field components) and adds a `content` prop.
+
+## 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, the new design system's 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.
+
+## Key Rules
+
+- 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 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

@@ -0,0 +1,50 @@
+---
+ai-globs: **/field/**/*
+---
+
+# Field Component Rules
+
+When creating or modifying field components, follow these rules:
+
+## Required Structure
+
+1. **Extend the base field props interface** — the project's standard field props type — when defining the component's prop interface.
+
+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**: 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):
+   - 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 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 the test id attribute on the interactive element using the `testId` prop
+
+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, 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 the blur handler on every keystroke — only on blur
+- Hardcode component imports for components that exist in the registry
+- 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.

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

@@ -0,0 +1,43 @@
+---
+ai-globs: **/template/**/*
+---
+
+# Template Component Rules
+
+When creating or modifying template/layout components, follow these rules:
+
+## Required Structure
+
+1. **Extend the base template props interface** — the project's standard props type — when defining the component's prop interface.
+
+2. **Export the component** using the project's standard export convention.
+
+## Template Categories
+
+### Layout Templates (TwoColumn, OneColumn, NarrowWide, WideNarrow)
+
+Receive child components directly via the props. Parse the `templateCol` prop (e.g. `"1fr 1fr"`, `"2fr 1fr"`) to compute column ratios, then render each child in its corresponding column.
+
+### Form/View Templates (DefaultForm, Details, CaseView)
+
+Render children by retrieving them from the PConnect accessor (`getPConnect().getChildren()`) and rendering each child through the project's PConnect-bridge component.
+
+### Page Templates (OneColumnPage, TwoColumnPage)
+
+Wrap a layout with page-level chrome (title, actions) — retrieve case/page metadata from the PConnect accessor and render it alongside the layout's children.
+
+## 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, the new design system's layout props, or by keeping the CSS import — whichever produces the closest match.
+3. Do NOT silently drop legacy layout utility classes — map each one to an equivalent style.
+
+## Key Rules
+
+- Use the project's PConnect-bridge component to render PConnect children
+- Grid proportions come from the `templateCol` prop — parse it to calculate column ratios
+- Templates must not call the event handling helper or interact with field state
+- Templates are layout-only — they arrange, not edit
+- Do NOT drop column gap, padding, or alignment styles when removing legacy layout primitives — replicate them in the replacement layout