@pega/sdk 0.0.14 → 0.0.15

package/templates/react-sdk-reference/.ai-common/prompts/replace-design-system.md

@@ -6,7 +6,17 @@ ai-description: Replace design system components — full app, by scope/folder,
 
 Replace the current design system in this application with **{{designSystem}}**.
 
-> **Before doing anything else:** if `{{designSystem}}` is empty or not provided, stop immediately and ask the user: _"Which design system should I migrate to? (e.g. Ant Design, Carbon Design System, Chakra UI)"_ — do not proceed with any migration steps until it is provided.
+> **Before doing anything else:** if `{{designSystem}}` is empty or not provided, stop immediately and ask the user: _"Which style kit should I switch the screens to? (A style kit is a ready-made set of buttons, inputs, and layouts — e.g. Ant Design, Carbon Design System, Chakra UI)"_ — list any UI libraries already in the project's dependency list first, marked as already in the project, and never choose one on the user's behalf. Do not proceed with any migration steps until it is provided.
+
+## Progress milestones
+
+Announce these to the user as you reach them, in plain words and with a counter — "Step 3 of 4 — Updating the components". Inside milestone 3, count the batches as well — "batch 2 of 9".
+
+1. **Working out what to update** — Step 0
+2. **Preparing your design system** — T1 (targeted) or Phase 1 (full)
+3. **Updating the components** — T2 (targeted) or Phase 2 (full)
+4. **Tidying up and checking the app builds** — T3 (targeted) or Phase 3 (full)
+5. **Trying it out** — T3 step 4 (targeted) or 3.6 (full)
 
 ---
 
@@ -33,12 +43,16 @@ Produce a list of SDK component names visible across **all** screenshots, then u
 
 Resolve each name against the manifest's `components` map to get its path and category.
 
+If a name is in everyday words ("date picker", "the buttons at the bottom"), resolve it first through the manifest's `aliases`, then its `behaviorClasses`, and confirm the match with the user. If nothing matches, ask the user which piece they mean.
+
 ---
 
 ### Source C — `scope` param provided
 
 > Applies when: `{{scope}}` is provided
 
+**If `{{scope}}` is a plain phrase** (e.g. "the form fields", "only the forms", "the whole app"): look it up case-insensitively in `manifest.scopeAliases` (ignore a leading "only" or "the") and use the value it maps to as the scope below. If it maps to `all`, the user wants every component — treat this source as empty and, when no other source applies, run the [Full Migration (9 waves)](#full-migration). If the phrase is not listed, work out the group from what it describes — things people type into or pick from → `field`; how a page or form is laid out → `template`; boxes that show lists, files, or history → `widget`; messages, titles, and read-only values → `designSystemExtension`; the buttons and step progress around a form → `infra` — and confirm it in plain words ("By 'the bits people type into', I think you mean the form fields — right?"). If it could mean more than one group, or none, ask the user in plain words which group they mean, offering the plain group names from `scopeAliases`.
+
 **If `{{scope}}` is a folder name** (one of `field`, `template`, `widget`, `infra`, `designSystemExtension`):
 Read every entry under `manifest.components["{{scope}}"]` — that is the full component list for this source.
 
@@ -148,6 +162,7 @@ Use the tables below to map what you see in an attached image to SDK component n
 | What you see                                                 | SDK component name  | Category              |
 | ------------------------------------------------------------ | ------------------- | --------------------- |
 | Coloured banner alert bar (info / warning / error / success) | `AlertBanner`       | designSystemExtension |
+| Step title text directly above an assignment's form fields   | `AssignmentHeader`  | designSystemExtension |
 | Hero-style banner with title + CTA button                    | `Banner`            | designSystemExtension |
 | Read-only field+value pairs in a case summary                | `CaseSummaryFields` | designSystemExtension |
 | Read-only label+value pairs in a details view                | `DetailsFields`     | designSystemExtension |
@@ -156,6 +171,7 @@ Use the tables below to map what you see in an attached image to SDK component n
 | User operator info popover (name + contact)                  | `Operator`          | designSystemExtension |
 | Comment/pulse card with avatar + timestamp                   | `Pulse`             | designSystemExtension |
 | Rich text editor with theme-aware toolbar                    | `RichTextEditor`    | designSystemExtension |
+| Short dark message at the screen edge with a close (×) icon  | `Toast`             | designSystemExtension |
 | Quick-create shortcut links list (WSS sidebar)               | `WssQuickCreate`    | designSystemExtension |
 
 ### Recognition rules
@@ -197,7 +213,8 @@ Most design systems require a root provider/context wrapper for any component in
 
 Check whether `{{designSystem}}` requires one. If yes:
 
-- Add it to **both** `src/MashupApp.tsx` **and** `src/PortalApp.tsx` — wrapping the existing provider tree
+- Add it to `src/AppProviders.tsx`, the shared root provider that both `src/MashupApp.tsx` and `src/PortalApp.tsx` wrap around the Pega root — wrapping the existing provider tree
+- The runtime provider's loading, error and logged-out states render **outside** `AppProviders`, so do not build them from {{designSystem}} primitives that need its provider
 - Do this **before** launching any subagents, regardless of how few components are being migrated
 - Do **not** remove any existing providers (MUI providers may still be needed by unmigrated components)
 
@@ -215,7 +232,7 @@ interface FieldValueListProps {
 ```
 
 **T1.5 — Update providers for full-app scopes (if `template` or `infra` components are in the list)**
-If `CaseView`, `AppShell`, `MashupApp`, or `PortalApp` are in the list, replace the old design system's `ThemeProvider` in `src/MashupApp.tsx` and `src/PortalApp.tsx` with {{designSystem}}'s provider.
+If `CaseView`, `AppShell`, `MashupApp`, or `PortalApp` are in the list, replace the old design system's `ThemeProvider` in `src/AppProviders.tsx` with {{designSystem}}'s provider.
 
 ### T2 — Migrate components (parallel subagents, ≤10 at a time)
 
@@ -226,6 +243,7 @@ For each component in the resolved list, launch a subagent:
 
 If the list has ≤10 components, launch all at once.
 If the list has >10 components, batch into waves of ≤10 and wait for each wave before starting the next.
+If your AI tool cannot run sub-agents, migrate the same components yourself, one at a time, in the same order and with the same instructions.
 
 ### T3 — Cleanup
 
@@ -234,14 +252,15 @@ After all subagents complete:
 1. Search for any remaining imports of the old design system in the migrated files — fix stragglers
 2. Run `npm run build` — fix ALL TypeScript errors until clean
 3. If providers were updated, run `npm run dev` and verify the app loads
+4. Read and execute `{{SKILL_DIR}}/portal-flow/run-and-verify-portal{{SKILL_EXT}}`, handing it the migrated components, and report its verification summary
 
 ---
 
 ## Full Migration
 
-> Used by Rule 4 only. Migrates all 81 components across 9 waves.
+> Used by Rule 4 only. Migrates all 83 components across 9 waves.
 
-> **Why 9 waves of 10?** Launching more than ~10 subagents simultaneously triggers rate-limit errors. Waves of 10 stay safely within the limit while still being ~10× faster than fully sequential execution. **Never launch the next wave until every subagent in the current wave has finished.**
+> **Why 9 waves of 10?** Launching more than ~10 subagents simultaneously triggers rate-limit errors. Waves of 10 stay safely within the limit while still being ~10× faster than fully sequential execution. **Never launch the next wave until every subagent in the current wave has finished.** If your AI tool cannot run sub-agents, migrate each wave's components yourself, one at a time, in the same wave order.
 
 ### Phase 1: Setup (sequential — blocks everything else)
 
@@ -272,7 +291,7 @@ Most design systems require a root provider/context wrapper for any component in
 
 Check whether `{{designSystem}}` requires one. If yes:
 
-- Add it to **both** `src/MashupApp.tsx` **and** `src/PortalApp.tsx` — wrapping the existing provider tree
+- Add it to `src/AppProviders.tsx`, the shared root provider that both `src/MashupApp.tsx` and `src/PortalApp.tsx` wrap around the Pega root — wrapping the existing provider tree
 - Do **not** remove any existing providers (MUI providers are still needed by unmigrated components)
 
 ### 1.4 Replace FieldValueList (blocking dependency for all fields)
@@ -291,7 +310,7 @@ interface FieldValueListProps {
 
 ### 1.5 Update provider files for full migration
 
-Replace MUI's `ThemeProvider` / `LegacyThemeProvider` in `src/MashupApp.tsx` and `src/PortalApp.tsx` with {{designSystem}}'s provider. Remove `LocalizationProvider` from `@mui/x-date-pickers` only if {{designSystem}} provides its own date picker.
+Replace MUI's `ThemeProvider` / `LegacyThemeProvider` in `src/AppProviders.tsx` with {{designSystem}}'s provider. Remove `LocalizationProvider` from `@mui/x-date-pickers` only if {{designSystem}} provides its own date picker.
 
 ---
 
@@ -454,18 +473,22 @@ Each uses prompt: **`replace-component`** with `componentCategory` = `widget`, `
 
 ---
 
-### Wave 9 — Infra (6 subagents)
+### Wave 9 — Infra + DSE batch 3 (8 subagents)
+
+Infra use prompt: **`replace-component`** with `componentCategory` = `infra` | DSE use prompt: **`replace-component`** with `componentCategory` = `designSystemExtension`, `designSystem` = **{{designSystem}}**
 
-Each uses prompt: **`replace-component`** with `componentCategory` = `infra`, `designSystem` = **{{designSystem}}**
+| #   | `componentName`  | `componentPath`                           | MUI to replace                                  |
+| --- | ---------------- | ----------------------------------------- | ----------------------------------------------- |
+| 76  | ActionButtons    | `infra/ActionButtons/`                    | `Button`, `Stack`, `Divider`                    |
+| 77  | DashboardFilter  | `infra/DashboardFilter/`                  | `Select`, `MenuItem`, `Box`                     |
+| 78  | DeferLoad        | `infra/DeferLoad/`                        | `CircularProgress`, `Box`                       |
+| 79  | NavBar           | `infra/NavBar/`                           | `AppBar`, `Toolbar`, `Button`, `Menu`, `Avatar` |
+| 80  | Stages           | `infra/Stages/`                           | `Stepper`, `Step`, `StepLabel`, `makeStyles`    |
+| 81  | VerticalTabs     | `infra/VerticalTabs/`                     | `Tabs`, `Tab`, `Box`                            |
+| 82  | AssignmentHeader | `designSystemExtension/AssignmentHeader/` | `Typography`                                    |
+| 83  | Toast            | `designSystemExtension/Toast/`            | `Snackbar`, `IconButton`, `CloseIcon`           |
 
-| #   | `componentName` | `componentPath`          | MUI to replace                                  |
-| --- | --------------- | ------------------------ | ----------------------------------------------- |
-| 76  | ActionButtons   | `infra/ActionButtons/`   | `Button`, `Stack`, `Divider`                    |
-| 77  | DashboardFilter | `infra/DashboardFilter/` | `Select`, `MenuItem`, `Box`                     |
-| 78  | DeferLoad       | `infra/DeferLoad/`       | `CircularProgress`, `Box`                       |
-| 79  | NavBar          | `infra/NavBar/`          | `AppBar`, `Toolbar`, `Button`, `Menu`, `Avatar` |
-| 80  | Stages          | `infra/Stages/`          | `Stepper`, `Step`, `StepLabel`, `makeStyles`    |
-| 81  | VerticalTabs    | `infra/VerticalTabs/`    | `Tabs`, `Tab`, `Box`                            |
+> Note: #82 and #83 use `componentCategory` = `designSystemExtension`
 
 ---
 
@@ -507,6 +530,10 @@ Run `npm run dev` and exercise:
 
 If any `ReferenceError: X is not defined` appears in the console, a component was removed from imports but its JSX usage was not updated. Fix and re-verify.
 
+### 3.6 Try the portal
+
+Read and execute `{{SKILL_DIR}}/portal-flow/run-and-verify-portal{{SKILL_EXT}}`, handing it the migrated components, and report its verification summary.
+
 ---
 
 ## Critical Rules — NEVER violate these

package/templates/react-sdk-reference/.ai-common/skills/connect-pega-server.md

@@ -64,6 +64,19 @@ Equivalent values across sources are not conflicts; consolidate them without ask
 
 After reading all sources, make the first user interaction complete. Show a status table for every applicable field, using only **configured**, **missing**, or **conflicting**. For the client secret, show presence only.
 
+Label the fields in that table in plain words — Pega server address, application alias, MCP rule name, MCP rule key, client ID (the public identifier for your app's sign-in), and MCP client secret. Keep the exact configuration keys for item 2 below, where the user needs them to edit files.
+
+For each missing value, add one plain sentence saying what it is and who usually has it, so a user who does not know the term can still find it:
+
+- **Pega server address** (server URL) — the web address you open to sign in to Pega, up to and including `/prweb`.
+- **Application alias** — the short ID of your Pega application in its web address: the part after `/app/`, for example `citizen-experience` in `…/prweb/app/citizen-experience/`. It is not the application's display name. You can see it in the browser address after you sign in.
+- **MCP rule name** (MCP rule) — the ID of the Service MCP rule your Pega team set up so this assistant can read your application, shown at the top of that rule, for example `AgenticSDKMCP`.
+- **MCP rule key** (MCP rule instance key) — the last part of that Service MCP rule's **Service endpoint URL**, after `/mcp/`, for example `citizen-experience`. Ask your Pega administrator if you cannot open the rule.
+- **Client ID** — the public ID of the sign-in registration for your app. Your Pega administrator can find it in the app's OAuth 2.0 client registration.
+- **MCP client secret** — a private password for that connection. Ask your Pega administrator, and put it only in a private environment file, never in chat.
+
+If the user does not know a value, suggest they ask their Pega administrator for it, and keep every other answer they have already given.
+
 In that same response:
 
 1. Ask for every missing or conflict-resolved **non-secret** value as one batch. The user may provide these values directly in chat.
@@ -102,6 +115,6 @@ After writing, re-read both active files and repeat the inventory check. Continu
 
 ## 6. Continue or reconnect
 
-- If the MCP config changed, tell the user it must be reloaded or reconnected before a Pega data source can run, then stop. Ask them to retry the original request; the invoking workflow must rerun this gate first. If MCP tools were started or attached after the conversation began and are not bound to this session, tell the user to start a new chat session.
+- If the MCP config changed, tell the user it must be reloaded or reconnected before a Pega data source can run, then stop. Ask them to retry the original request; the invoking workflow must rerun this gate first. If MCP tools were started or attached after the conversation began and are not bound to this session, tell the user to start a new chat session. Say it in plain words — for example: "Your Pega connection details are saved. Restart the Pega connection in your editor (or open a new chat), then ask me again."
 - If only `sdk-config.json` changed and the MCP connection is already available to the conversation, continue the invoking workflow without requiring an unnecessary MCP reconnect.
 - If neither file needed changes, continue immediately.

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension-skills/AssignmentHeader.md

@@ -0,0 +1,79 @@
+# Skill: AssignmentHeader
+
+Heading that shows the name of the current assignment step above the case form.
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, input contracts, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders the title of the step the user is working on — for example "Collect customer details" — directly above the form fields. The SDK's flow container works out the title from the assignment and localizes it, then asks the registry for `AssignmentHeader` to draw it. This component only draws the text; it never decides whether a title exists or what it says.
+
+## Pega Metadata
+
+- **Registration key:** `AssignmentHeader` (in the project's component map)
+- **SDK lookup, not a Pega view component** — Pega never sends this name in view metadata. The SDK's flow container resolves it from the registry, and falls back to its own built-in heading when nothing is registered.
+- **Does NOT use `getPConnect`** — receives all data as direct inputs
+
+## Component Inputs
+
+The component accepts the following inputs. Define the input contract using the project's framework conventions for your target stack.
+
+| Name    | Type     | Required | Description                                   |
+| ------- | -------- | -------- | --------------------------------------------- |
+| `title` | `string` | Yes      | The assignment step's name, already localized |
+
+## Implementation Structure
+
+### Module Setup
+
+The component does NOT import any Pega SDK modules — the title arrives as a direct input. It needs only the design system's typography or heading primitive.
+
+The component is named `AssignmentHeader` and accepts the input listed in the table above. Define the input contract and export the component following the project's framework conventions.
+
+### Component Logic
+
+1. Render `title` as a section heading, using the design system's heading or title typography at the level the project uses for a form or card title.
+2. Give the root element the DOM id `assignment-header`, so tests and automation can find it.
+3. Leave space below the heading before the form begins, using the project's spacing scale.
+
+## Behavioral Contract
+
+1. **Display only** — render `title` exactly as received. Do not localize it again, change its case, or truncate it.
+2. **No visibility logic** — the SDK renders this component only when a title exists. Do not add a separate check that hides an empty title, and do not render a placeholder.
+3. **Heading only** — render the heading and nothing else. The form, its messages, and its buttons are rendered by the SDK around this component and are never wrapped by it.
+4. **Root id** — the root element carries the id `assignment-header`.
+
+## Visual Specifications
+
+Derived from the SDK's built-in heading:
+
+| Property      | Value                                            |
+| ------------- | ------------------------------------------------ |
+| Font size     | 1.2rem (or the design system's form-title size)  |
+| Font weight   | 600 (or the design system's title weight)        |
+| Margin bottom | 1rem (or the design system's equivalent spacing) |
+| Font family   | Inherited — never set a font family of its own   |
+| Color         | Inherited primary text color                     |
+
+**CSS-only implementation notes:**
+
+- Use a native heading element with the project's heading class, or a `<div>` styled as above.
+- Long titles wrap onto further lines; they never truncate or overflow their container.
+
+## Edge Cases & Special Logic
+
+- Long titles wrap rather than truncate.
+- The title may contain characters from any language — do not transform it.
+
+## Dependencies
+
+- No Pega SDK imports required (no `getPConnect`)
+- No helper utilities required
+
+## Design System Mapping
+
+**UI control type:** Heading / title text.
+
+When implementing in a specific design system, use the DS's typography or heading component at the level the project uses for a form or card title — for example a level-6 heading style. If the DS has no typography component, use a native heading element styled with the project's typography tokens.

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension-skills/Toast.md

@@ -0,0 +1,96 @@
+# Skill: Toast
+
+Short notification shown after an assignment action fails — for example "Save failed" or "Cancel failed!". It closes itself after a few seconds, or when the user closes it.
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, input contracts, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a transient message near the edge of the screen. The SDK's assignment component decides when to show it and what it says, then asks the registry for `Toast` to draw it. This component draws the message, a close button, and handles the automatic close — it never decides when to appear or what to say.
+
+## Pega Metadata
+
+- **Registration key:** `Toast` (in the project's component map)
+- **SDK lookup, not a Pega view component** — Pega never sends this name in view metadata. The SDK's assignment component resolves it from the registry, and falls back to its own built-in notification when nothing is registered.
+- **Does NOT use `getPConnect`** — receives all data as direct inputs
+
+## Component Inputs
+
+The component accepts the following inputs. Define the input contract using the project's framework conventions for your target stack.
+
+| Name               | Type       | Required | Description                                                        |
+| ------------------ | ---------- | -------- | ------------------------------------------------------------------ |
+| `open`             | `boolean`  | Yes      | Whether the notification is visible                                |
+| `message`          | `string`   | Yes      | The text to show, already localized                                |
+| `onClose`          | `function` | Yes      | Called with no arguments when the notification should close        |
+| `autoHideDuration` | `number`   | No       | Milliseconds before the notification closes itself. Default `3000` |
+
+## Implementation Structure
+
+### Module Setup
+
+The component does NOT import any Pega SDK modules — all data arrives via direct inputs. It needs the design system's notification primitive (snackbar, toast, or equivalent) and an icon button for closing.
+
+The component is named `Toast` and accepts the inputs listed in the table above. Define the input contract and export the component following the project's framework conventions.
+
+### Component Logic
+
+1. Render the design system's notification primitive, visible only while `open` is true, showing `message` as its content.
+2. Add a close button inside the notification: an icon-only button with a close (×) icon, the accessible label `close`, and the notification's text color. Activating it calls `onClose`.
+3. **Automatic close** — while `open` is true, call `onClose` once `autoHideDuration` milliseconds have passed. Restart that countdown whenever `message` changes. When the design system's primitive offers a built-in auto-hide duration, use it rather than a separate timer.
+4. **Outside clicks** — clicking or tapping elsewhere on the page must not close the notification. If the design system's primitive closes on outside clicks by default, ignore that close reason and keep it open.
+
+## Behavioral Contract
+
+1. **Visibility is owned by the SDK** — show the notification only when `open` is true. Never open it by itself, and never keep it open after `open` becomes false.
+2. **Close paths** — exactly two: the close button, and the automatic close after `autoHideDuration`. Both call `onClose`; neither changes `open` directly.
+3. **Outside clicks are ignored.**
+4. **Message is displayed as received** — do not localize, prefix, or truncate it.
+5. **Accessibility** — the notification is announced to assistive technology as an alert, and the close button carries the accessible label `close`.
+
+## Visual Specifications
+
+Derived from the SDK's built-in notification:
+
+| Property      | Value                                                         |
+| ------------- | ------------------------------------------------------------- |
+| Position      | Fixed, bottom centre of the viewport, above all other content |
+| Background    | Dark neutral (`#333`), or the design system's inverse surface |
+| Text color    | White, or the design system's on-inverse text color           |
+| Padding       | `0.75rem 1.5rem`                                              |
+| Border radius | `0.375rem`, or the design system's notification radius        |
+| Font size     | `0.875rem`                                                    |
+| Layout        | Message and close button in a row, with a small gap           |
+
+**CSS-only implementation notes:**
+
+- Root: `position: fixed; bottom: 1rem; left: 50%; transform: translateX(-50%); display: flex; align-items: center; gap: 0.75rem; z-index` above dialogs.
+- Close button: no border or background, inherits the text color, pointer cursor.
+- When the project already shows notifications in a different position or style, follow the project's convention instead.
+
+## Edge Cases & Special Logic
+
+- A second message while one is showing replaces the text and restarts the countdown.
+- Long messages wrap inside the notification; they never overflow the screen.
+
+## Dependencies
+
+- No Pega SDK imports required (no `getPConnect`)
+- No helper utilities required
+
+## Design System Mapping
+
+**UI control type:** Snackbar / toast notification.
+
+When implementing in a specific design system, map the following:
+
+- `open` → the DS notification's open / visible input
+- Position → bottom centre of the viewport. Many notification primitives default to bottom-left or top-right, so set the anchor or placement input explicitly
+- `message` → the DS notification's message or content
+- `autoHideDuration` → the DS notification's auto-hide or duration input
+- `onClose` → the DS notification's close handler, filtered so an outside-click close reason is ignored
+- Close button → the DS notification's action slot, holding a small icon button with a close icon
+
+If the DS has no notification component, use a `<div role="alert">` positioned as described above, with a timer for the automatic close.

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension.md

@@ -1,6 +1,6 @@
 # Skill: Design System Extension (DSE) Components
 
-Create or replace Design System Extension components in the project. DSE components are display-focused presentational components that render structured data without direct PConnect binding. Some receive `getPConnect`, others receive only display inputs.
+Create or replace Design System Extension components in the project. DSE components are display-focused presentational components that render structured data without direct PConnect binding. None of them calls `getPConnect()` itself — they receive display inputs, ready-rendered children, or (DetailsFields only) field entries that carry their own accessor.
 
 ---
 
@@ -19,19 +19,28 @@ Each DSE component lives in its own folder under the project's design-system-ext
 
 ## Input Contract
 
-DSE components have varying input patterns:
+DSE components have varying input patterns. The component-specific skill file is the authority on each component's exact inputs.
 
-### Pattern A: With PConnect (data-aware display)
+### Pattern A: Data display (no accessor of its own)
 
-The component's input contract extends the project's base component interface, which provides `getPConnect()` — a function returning the PConnect API object — in addition to its own custom inputs. Example: a field-value display component extending the base interface with additional fields like `name`, `value`, and `variant`.
+Used for: FieldValueList, CaseSummaryFields, DetailsFields
+
+The component's input contract is standalone — it does NOT extend the base component interface, and the component never calls `getPConnect()`. It receives the data to show as direct inputs: FieldValueList takes `name`, `value`, and `variant`; CaseSummaryFields takes pre-processed field descriptors. DetailsFields is the one variation: each entry in its `fields` input carries its own `getPConnect()`, which it uses only to render that entry through the project's PConnect bridge utility.
 
 ### Pattern B: Without PConnect (pure presentation)
 
-The component's input contract is standalone — it does NOT extend the base component interface. All rendering data arrives via direct inputs. Example: an alert-banner component with fields like `variant`, `heading`, `messages`, and `onClose`.
+Used for: AlertBanner, AssignmentHeader, Banner, Operator, Toast, WssQuickCreate
+
+The component's input contract is standalone — it does NOT extend the base component interface. All rendering data arrives via direct inputs. Example: an alert-banner component with fields like `variant`, `messages`, and an optional `onDismiss`. Operator's type may extend the base interface for typing, but it never calls `getPConnect()`.
 
-### Pattern C: Extended field input contract (display-only fields)
+### Pattern C: Complex display (no accessor of its own)
 
-The component's input contract extends the project's field input contract, which provides standard field-level inputs (`label`, `value`, `displayMode`, `required`, `disabled`, `readOnly`, `status`, `validatemessage`, `helperText`, `hideLabel`, `placeholder`, `testId`) plus `getPConnect()`. The component adds its own domain-specific inputs on top. Example: a rich-text-editor component extending the field input contract with an additional `content` field.
+Used for: FieldGroup, FieldGroupList, Pulse, RichTextEditor
+
+The component's input contract is standalone and never calls `getPConnect()` or `getChildren()`.
+
+- **FieldGroup, FieldGroupList, Pulse** receive children their caller has already rendered: the calling template or field resolves the Pega children, renders them through the PConnect bridge, and passes the result in — FieldGroup and Pulse as their children, FieldGroupList as `items[].children`.
+- **RichTextEditor** declares field-like inputs directly — `label`, `defaultValue`, `placeholder`, `disabled`, `required`, `readOnly`, `error`, `testId`, `onChange`, `onBlur`, and similar — without extending the base component or field interface. The field component that uses it owns the value and the commit.
 
 ---
 
@@ -39,14 +48,14 @@ The component's input contract extends the project's field input contract, which
 
 ### Pure Display Component (no PConnect)
 
-Used for: AlertBanner, Banner, Operator
+Used for: AlertBanner, Banner, Operator. `AssignmentHeader` and `Toast` are also pure display, but follow their own skill files — they render a heading and a notification rather than an alert.
 
 This pattern is design-system agnostic. The variant-mapping logic and message normalisation are always the same — only the final rendered output changes based on the chosen design system (see "Design System Adaptation" below).
 
 **Structure:**
 
 1. **Use** the design system's alert/notification primitive as the visual foundation.
-2. **Define the input contract** (Pattern B — no PConnect). Include the Pega-facing inputs: `variant`, `heading`/`messages`, and an optional close/dismiss handler.
+2. **Define the input contract** (Pattern B — no PConnect). Include the Pega-facing inputs the component's skill file lists — for AlertBanner: `variant`, `messages`, and an optional dismiss handler.
 3. **Define a variant map** at module level — a plain lookup mapping Pega variant strings (`urgent`, `warning`, `info`, `success`) to the design system's equivalent severity/type value. Unknown variants fall back to `info`.
 4. **Define a message normaliser** — a helper function that accepts either a plain string or an object (`{ label?, description? }`) and returns formatted content. Pega may send either format.
 5. **Render** using the design system's alert primitive. Pass the mapped severity as the type/severity/status input. Wire the dismiss handler to the design system's close input only if provided. Render message content inside the alert body.
@@ -57,22 +66,20 @@ Used for: FieldValueList, CaseSummaryFields, DetailsFields
 
 **Structure:**
 
-1. **Define the input contract** (Pattern A — extends the project's base component interface) with fields for `name` (optional string), `value` (any), and `variant` (optional — `'stacked'` or `'inline'`, defaulting to `'inline'`).
+1. **Define the input contract** (Pattern A — standalone, no `getPConnect`) with fields for `name` (optional string), `value` (any), and `variant` (optional — `'stacked'` or `'inline'`, defaulting to `'inline'`). Every field component renders its display-only mode through this component with exactly these inputs, so never make it require an accessor.
 2. **Stacked variant** — when `variant` is `'stacked'`, render the label on its own line above the value. The value should use a larger/emphasized typography style.
 3. **Inline variant** (default) — render the label and value side by side. The label occupies roughly 1/3 width, value occupies 2/3. If `name` is not provided, render only the value at full width.
 4. **Empty value handling** — if `value` is undefined or an empty string, display a placeholder (`'---'`).
 
-### Complex Display Component (with PConnect for data)
+### Complex Display Component (children from the caller)
 
 Used for: FieldGroup, FieldGroupList, Pulse
 
 **Structure:**
 
-1. **Define the input contract** (Pattern A — extends the project's base component interface) with component-specific fields (e.g., `label`, `showLabel`).
-2. **Obtain the PConnect instance** by calling `getPConnect()` from the component's inputs.
-3. **Retrieve children** via `pConn.getChildren()` — this returns an array of child component configurations from the Pega engine.
-4. **Render children dynamically** — iterate over the children array and render each child configuration using the project's PConnect bridge utility, keyed uniquely. This bridges the Pega component tree into the chosen framework's rendering model.
-5. **Wrap in semantic HTML** — use appropriate semantic elements (e.g., `<fieldset>` with `<legend>` for grouped fields). Conditionally show labels based on the `showLabel` input.
+1. **Define the input contract** (Pattern C — standalone, no `getPConnect`) with the inputs the component's skill file lists — for example FieldGroup's `name`, `collapsible`, and `instructions`, or FieldGroupList's `items`, `onAdd`, and `onDelete`.
+2. **Render the children you are given** — the caller has already resolved the Pega children and rendered them through the PConnect bridge. Never call `getPConnect()` or `getChildren()` here.
+3. **Wrap in semantic HTML** — use appropriate semantic elements (e.g., `<fieldset>` with `<legend>` for grouped fields), showing the group name as the legend when one is given.
 
 ---
 
@@ -105,15 +112,15 @@ If the chosen design system provides built-in spacing, typography, or layout inp
 
 DSE components fall into three patterns with different DS dependencies:
 
-| Pattern                                   | Examples                                         | DS needed?                                         |
-| ----------------------------------------- | ------------------------------------------------ | -------------------------------------------------- |
-| **B — Pure display** (no PConnect)        | AlertBanner, Banner, Operator, WssQuickCreate    | Yes — DS provides alert/card/avatar primitives     |
-| **A — PConnect display**                  | CaseSummaryFields, DetailsFields, FieldValueList | Minimal — CSS-based layout; DS typography optional |
-| **C — Complex display** (PConnect bridge) | FieldGroup, FieldGroupList, Pulse                | No — PConnect bridge is DS-agnostic; semantic HTML |
+| Pattern                                          | Examples                                                               | DS needed?                                                                                  |
+| ------------------------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| **B — Pure display** (no PConnect)               | AlertBanner, AssignmentHeader, Banner, Operator, Toast, WssQuickCreate | Yes — DS provides alert/card/avatar/heading/notification primitives                         |
+| **A — Data display** (no accessor of its own)    | CaseSummaryFields, DetailsFields, FieldValueList                       | Minimal — CSS-based layout; DS typography optional                                          |
+| **C — Complex display** (no accessor of its own) | FieldGroup, FieldGroupList, Pulse, RichTextEditor                      | No — semantic HTML around the children it is given; RichTextEditor wraps its editor library |
 
 The component-specific skill file specifies which pattern applies.
 
-**1. Check the component-specific skill file** — `{{SKILL_DIR}}/design-system-extension-skills/<ComponentName>.md` contains a **Design System Mapping** table where available.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/design-system-extension-skills/<ComponentName>{{SKILL_EXT}}` contains a **Design System Mapping** table where available.
 
 **2. If the chosen design system is not listed** — use the component purpose and pattern category above to pick the closest DS primitive.
 
@@ -130,6 +137,18 @@ The component-specific skill file specifies which pattern applies.
 
 ---
 
+## Visual Preservation
+
+When replacing an existing implementation, the replacement must look the same as the original:
+
+1. **Read the component's companion style file first** (for example a `.css` file in its folder). Note every class's visual intent — spacing, sizing, colours, and layout.
+2. Reproduce that intent through the new design system's inputs or variants, inline styles, or by keeping the style import — whichever gives the closest match.
+3. Never silently drop legacy styling utility classes — map each one to an equivalent style.
+
+In the embedded flow there is no original to preserve: the customer's look, recorded in the Design Profile, decides instead.
+
+---
+
 ## Registration
 
 Register DSE components in the project's component map:
@@ -141,19 +160,21 @@ Register DSE components in the project's component map:
 
 ## Existing DSE Components
 
-| Component         | PConnect? | Description                             |
-| ----------------- | --------- | --------------------------------------- |
-| AlertBanner       | No        | Alert/notification banner with variants |
-| Banner            | No        | Promotional/informational banner        |
-| CaseSummaryFields | Yes       | Summary fields for case header          |
-| DetailsFields     | Yes       | Key-value fields in a details region    |
-| FieldGroup        | Yes       | Grouped fields with label/legend        |
-| FieldGroupList    | Yes       | List of field groups (repeating)        |
-| FieldValueList    | Yes       | Single field-value pair display         |
-| Operator          | No        | Operator avatar + name display          |
-| Pulse             | Yes       | Activity feed/comments stream           |
-| RichTextEditor    | Yes       | Rich text editor (TinyMCE-based)        |
-| WssQuickCreate    | No        | WSS quick case creation component       |
+| Component         | PConnect?                     | Description                             |
+| ----------------- | ----------------------------- | --------------------------------------- |
+| AlertBanner       | No                            | Alert/notification banner with variants |
+| AssignmentHeader  | No                            | Title of the current assignment step    |
+| Banner            | No                            | Promotional/informational banner        |
+| CaseSummaryFields | No                            | Summary fields for case header          |
+| DetailsFields     | Only via its `fields` entries | Key-value fields in a details region    |
+| FieldGroup        | No (children from the caller) | Grouped fields with label/legend        |
+| FieldGroupList    | No (children from the caller) | List of field groups (repeating)        |
+| FieldValueList    | No                            | Single field-value pair display         |
+| Operator          | No                            | Operator avatar + name display          |
+| Pulse             | No (children from the caller) | Activity feed/comments stream           |
+| RichTextEditor    | No (field-like inputs)        | Rich text editor (TinyMCE-based)        |
+| Toast             | No                            | Short notification after an action      |
+| WssQuickCreate    | No                            | WSS quick case creation component       |
 
 ---
 

package/templates/react-sdk-reference/.ai-common/skills/embedded-flow/analyze-customer-repo.md

@@ -23,6 +23,8 @@ When Pega case flows are embedded into a customer's existing application, the ge
 | **Form & state management**      | Identify form-handling libraries or patterns in dependencies and source                  | Library or pattern name + how values, validation, and submission are handled                                                                                         |
 | **Import & module conventions**  | Analyze import statements across multiple files                                          | Path aliasing, barrel imports, relative vs absolute, grouping order                                                                                                  |
 | **Validation & error display**   | Observe how existing components show validation feedback                                 | Pattern: inline message, tooltip, border color change, icon, combination                                                                                             |
+| **Global appearance**            | Trace where fonts are loaded and which wrapper sets the base text and theme              | Font loading, base text settings, reset, theme scope, theme switching, overlay placement                                                                             |
+| **Form layout**                  | Read one or two multi-field forms                                                        | Field and column gaps, label position, field width, section spacing, stacking width, who owns the spacing                                                            |
 
 ---
 
@@ -32,10 +34,11 @@ When Pega case flows are embedded into a customer's existing application, the ge
 
 Every downstream skill and prompt writes generated components to one location: `{output_path}`. Resolve it once, here, before anything else runs. This is separate from the Design Profile document itself, which always lives at the fixed `docs/design-profile.md` and never moves with `{output_path}`.
 
-1. **Check for an existing profile first.** Look for `docs/design-profile.md` at the project root — this is its one fixed location, independent of `{output_path}`. If it exists, read its **Output Path** field (Section 1) and reuse that value as `{output_path}` — skip the rest of this step entirely. Do not ask the user again.
+1. **Check for an existing profile first.** Look for `docs/design-profile.md` at the project root — this is its one fixed location, independent of `{output_path}`. If it exists, read its **Output Path** field (Section 1) and reuse that value as `{output_path}` — skip points 2 to 4 and go straight to point 5. Do not ask the user again.
 2. **Otherwise, ask.** Ask the user where in their own project the generated Pega components should live. Suggest `pega-components/` at the project root as the default/recommended answer, but accept any path they type instead.
 3. **Validate the answer stays inside the project.** Reject an absolute path outside the project, any `..` traversal segment, or anything else that would resolve outside the project root — re-ask when this happens rather than writing outside the repo.
 4. **Record the confirmed path** as `{output_path}`. It is written into the Design Profile in Step 6 below, and every other embedded-flow skill/prompt reads it from there instead of asking again or assuming a fixed name.
+5. **Point the embedded component rules at that folder.** The rules file `{{INSTRUCTIONS_DIR}}/embedded-component{{AI_FILE_EXT}}` attaches itself to `pega-components/` by default, through the file-matching line at the top of the file. If `{output_path}` is a different folder, replace `pega-components` in that one line with `{output_path}` (relative to the project root, without a leading `./` or trailing `/`) and change nothing else. Do this every time this step runs, even when the path came from an existing profile — setting the project up again can restore the default. If the file has no file-matching line, there is nothing to update.
 
 ### Step 1 — Identify project fundamentals
 
@@ -64,6 +67,15 @@ Read the discovered files and extract:
 - **Shadows** — elevation levels used
 - **Breakpoints** — responsive design boundaries (if defined)
 
+Then record how that look is applied across the whole application — the **global appearance**. Tokens alone do not say this, and an embedded form that only references tokens can still render in the browser's default font:
+
+- **Font loading** — where the web font is loaded (a stylesheet, a font-loading mechanism of the framework, or a self-hosted font face) and the font family names it provides
+- **Base text** — which element or wrapper sets the base font family, size, line height, text colour, and page background
+- **Reset or baseline** — any global reset, normalizer, or baseline styles the application applies, and where
+- **Theme scope** — the design system's root theme or provider wrapper (if any), where it is mounted, and which part of the page it covers
+- **Theme switching** — whether the application supports light/dark or other themes, and how the active theme is selected
+- **Overlay placement** — whether dialogs, drawers, and popovers render inside the application's root element or are attached elsewhere in the page, outside the theme scope
+
 ### Step 3 — Analyze representative components
 
 Find 3–5 components that handle user input (text fields, selects/dropdowns, checkboxes, date pickers, buttons). Prioritize components that:
@@ -81,6 +93,20 @@ For each component, note:
 5. **Styling mechanism** — how it applies visual styles (class names, style objects, utility classes, scoped selectors)
 6. **Accessibility** — labels, ARIA attributes, focus management
 
+### Step 3.1 — Analyze form layout
+
+Find one or two forms in the application that collect several fields — ideally one with more than one column. Read how they arrange their fields and record:
+
+- **Field spacing** — the vertical gap between consecutive fields, and the horizontal gap between columns, as spacing tokens
+- **Label position** — above the input, beside it, or floating inside it
+- **Field width** — whether inputs fill their column or have a fixed or maximum width
+- **Sections** — how groups of fields are separated (heading, divider, card, extra space) and the spacing around them
+- **Columns** — how multi-column forms are built (the grid or layout primitive used) and at what width they stack into one column
+- **Actions** — the space between the last field and the form's buttons, and how the buttons are aligned
+- **Who owns the spacing** — whether the gaps come from the form's layout container or from margins on each field
+
+Note the file paths of the forms you used, so generation can re-read them.
+
 ### Step 4 — Determine file and folder conventions
 
 List the project's component directory and observe:
@@ -116,9 +142,9 @@ Produce a structured markdown document with the following sections. Use heading
 
 **Section 1: Project Fundamentals** — start with the **Output Path** resolved in Step 0, then list the framework name and version, language and configuration, UI library name and version (or "Custom"), styling approach, form handling library or pattern, and module system.
 
-**Section 2: Design Tokens** — organize by sub-sections: Colors (primary, secondary, accent, error, warning, success, background, text, border with their semantic names and values), Spacing (scale), Typography (font families, sizes, weights), Borders and Radii (values), Shadows (elevation values), Breakpoints (if defined).
+**Section 2: Design Tokens** — organize by sub-sections: Colors (primary, secondary, accent, error, warning, success, background, text, border with their semantic names and values), Spacing (scale), Typography (font families, sizes, weights), Borders and Radii (values), Shadows (elevation values), Breakpoints (if defined), and Global Appearance (font loading, base text, reset or baseline, theme scope, theme switching, overlay placement — from Step 2).
 
-**Section 3: Component Patterns** — describe each convention as a sub-section: Input Interface Convention (how components define what they accept), State Management Convention (how local state is handled), Event Handling Convention (how value changes are reported — immediate, on blur, debounced), Validation Display Convention (where errors appear, how error styling is applied), Styling Convention (how styles are applied to elements, how conditional styles work).
+**Section 3: Component Patterns** — describe each convention as a sub-section: Input Interface Convention (how components define what they accept), State Management Convention (how local state is handled), Event Handling Convention (how value changes are reported — immediate, on blur, debounced), Validation Display Convention (where errors appear, how error styling is applied), Styling Convention (how styles are applied to elements, how conditional styles work), Form Layout Convention (everything recorded in Step 3.1, with the file paths of the forms it came from).
 
 **Section 4: File Conventions** — list the folder structure type, naming convention (casing), re-export/barrel pattern, test file location, and style file location.