@pega/sdk 0.0.7 → 0.0.9

package/templates/react-sdk-reference/.ai-common/prompts/generate-all-components.md

@@ -1,5 +1,5 @@
 ---
-ai-description: Generate components across multiple types (field, template, widget, designSystemExtension) using any design system
+ai-description: Generate components across multiple types (field, template, widget, designSystemExtension, infra) using any design system
 ---
 
 ## Step 0 — Resolve inputs
@@ -8,30 +8,32 @@ Read the user's message carefully. Extract:
 
 - **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
 - **Base components folder** — the root folder that contains (or will contain) the component type subfolders (e.g. `src/components/`)
-- **Component types in scope** — which types to generate (default: all four if not specified)
+- **Component types in scope** — an optional narrowing filter (default: all five if not specified)
 
 Both **design system** and **base components folder** are required. If either is missing or ambiguous, you MUST stop and ask the user before proceeding. Do not infer any value from the project structure, `{{AI_FILE_EXT}}` files, existing folders, or any other source.
 
-⛔ **STOP** — If the user's message does not explicitly state BOTH the design system AND the base components folder, ask for the missing items now. Do not proceed to Step 1 until you have explicit answers from the user for all required inputs.
+⛔ **STOP** — If the user's message does not explicitly state BOTH the design system AND the base components folder, ask for the missing items now. Do not proceed to Step 0.5 until you have explicit answers from the user for all required inputs.
+
+**Which components get generated is not decided here.** That set comes from the portal, and the landing pages and/or case types the user picks within it, all resolved from the Pega server in Step 0.5. The type scope below is only a filter applied on top of that set — it can narrow it, never widen it.
 
 Example questions (ask only the ones that are actually missing):
 
 1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
-2. What is your base components folder? (e.g. `src/components/`) — subfolders `field/`, `template/`, `widget/`, and `designSystemExtension/` will be used under it.
+2. What is your base components folder? (e.g. `src/components/`) — subfolders `field/`, `template/`, `widget/`, `designSystemExtension/`, and `infra/` will be used under it.
 
 ### Component type scope
 
 Extract which types the user wants from the message:
 
-| User says                                  | Types in scope                                    |
-| ------------------------------------------ | ------------------------------------------------- |
-| "generate all components"                  | field + template + widget + designSystemExtension |
-| "generate field and widget components"     | field + widget                                    |
-| "generate widget, template components"     | widget + template                                 |
-| "generate all components except templates" | field + widget + designSystemExtension            |
-| "replace everything"                       | field + template + widget + designSystemExtension |
+| User says                                  | Types in scope                                            |
+| ------------------------------------------ | --------------------------------------------------------- |
+| "generate all components"                  | field + template + widget + designSystemExtension + infra |
+| "generate field and widget components"     | field + widget                                            |
+| "generate widget, template components"     | widget + template                                         |
+| "generate all components except templates" | field + widget + designSystemExtension + infra            |
+| "replace everything"                       | field + template + widget + designSystemExtension + infra |
 
-Default to **all four types** if the message does not restrict the scope.
+Default to **all five types** if the message does not restrict the scope. A type in scope does not mean every component of that type is generated — it means components of that type are eligible for the selection made in Step 0.5.
 
 ### Derived output paths
 
@@ -43,14 +45,112 @@ Once the base folder is known, derive the output path for each type in scope:
 | template              | `<base>/template/`              |
 | widget                | `<base>/widget/`                |
 | designSystemExtension | `<base>/designSystemExtension/` |
+| infra                 | `<base>/infra/`                 |
+
+Once design system, base folder, and type scope are resolved, continue to Step 0.5.
+
+---
+
+## Step 0.5 — Resolve the portal, its scope, and its components from the server (MANDATORY GATE)
+
+⛔ **This step MUST complete before anything is read, installed, or written.** A portal renders a specific set of components, and generating the full catalogue produces components the portal will never mount. Do NOT use a hardcoded component list, and do NOT infer one from the project's existing folders.
+
+### 0.5.1 — Resolve the portal
+
+Execute the data source **`D_pyAvailablePortals`**, which returns the portals available in the application. Pass the name exactly as written — this data page is part of the Pega platform and does not vary between installations.
+
+Execute it directly. Do not survey the session's capabilities first — the attempt is itself the check, and a better one: a capability survey can come back empty while the capability is present, stopping a flow that would have worked. Resolve the means of executing a Pega data source by what it does, not by what it is called; tool names and the server's label differ between editors and AI tools. Never look for a configuration file, never assume a path or a server name, and never tell the user which file to edit.
+
+If nothing in this session can execute a Pega data source, stop. Tell the user the Pega MCP server is not available to this conversation, and name both common causes: the server is not running, or it was started after this conversation began — in which case its tools are not bound to this session and a new session is needed. Do not guess at its configuration, and do not fall back to generating the full component catalogue.
+
+If the execution runs but fails, report the failure, and if the server's data sources can be listed, list them so the user can see whether the data page is offered at all. Do not substitute a different data page.
+
+The response's `pxResults` array holds one entry per portal. Then:
+
+1. If the user's message did NOT name a portal, present the returned portals as a numbered pick-list and ask which one to generate for.
+2. If the user's message DID name one, confirm it appears in the response. If it does not, show what the server returned and ask the user to choose from that list. Never proceed on an unverified portal name.
+3. Record the confirmed entry's **`pyPortalLayout`** value. This — not the display label shown to the user — is what Steps 0.5.3 and 0.5.4 pass to the server as `PortalName`; carry it forward exactly as the data page returned it.
+
+### 0.5.2 — Ask what to convert
+
+Ask the user which parts of the portal to convert: **Landing pages**, **Cases**, or **Both**. Allow selecting more than one. This is a gate — wait for the answer before continuing.
+
+- If **Landing pages** is selected, run Step 0.5.3.
+- If **Cases** is selected, run Step 0.5.4.
+- If **Both** is selected, run 0.5.3 and 0.5.4 and merge their results in Step 0.5.5.
+
+### 0.5.3 — Landing pages (skip unless selected)
+
+Execute the data source **`D_pyPortalPages`** with `PortalName` set to the `pyPortalLayout` value recorded in Step 0.5.1. It returns the landing pages configured in that portal, in a `pxResults` array whose entries carry `pxObjClass`, `pyRuleName`, and `pyClassName`.
+
+If `pxResults` is empty, tell the user this portal has no landing pages and, if Cases was not already selected, offer to fall back to it. If Cases was also not selected or also comes back empty, stop — there is nothing to generate.
+
+Present the returned pages as a **checkbox list** (label each with its `pyRuleName`, and show its `pxObjClass` alongside so the user can tell a view from a landing page) and let the user select one or more. This is a gate.
+
+For **each selected page**, resolve its components by its `pxObjClass`:
+
+Apply this dispatch as an exact, mutually exclusive decision for every page. Do not choose a data source based on the page label, rule name, or a guessed similarity:
+
+1. If `pxObjClass` is exactly `Rule-UI-View`, execute **only** `D_pyViewDependencies` with `ViewName = pyRuleName` and `ViewClass = pyClassName`. Read component names from `pxDependencies`.
+2. Else if `pxObjClass` is exactly `Rule-UI-View-LandingPage`, execute **only** `D_pyLandingPageComponentsByType` with `RuleName = pyRuleName` and `ClassName = pyClassName`. Read component names from `pxResults`.
+3. Else, do not execute either data source. Report the unsupported `pxObjClass`, preserve the page in the selection summary, and ask how to proceed. Never route an unknown class through the landing-page data source as a default.
+
+The required mapping is:
+
+| Exact `pxObjClass`         | Data source                       | Parameters                                         | Components are in |
+| -------------------------- | --------------------------------- | -------------------------------------------------- | ----------------- |
+| `Rule-UI-View`             | `D_pyViewDependencies`            | `ViewName = pyRuleName`, `ViewClass = pyClassName` | `pxDependencies`  |
+| `Rule-UI-View-LandingPage` | `D_pyLandingPageComponentsByType` | `RuleName = pyRuleName`, `ClassName = pyClassName` | `pxResults`       |
+
+For a page whose `pxObjClass` is `Rule-UI-View`, it is a workflow error to call `D_pyLandingPageComponentsByType`; stop and correct the dispatch before continuing. Likewise, do not call `D_pyViewDependencies` for `Rule-UI-View-LandingPage`.
+
+Do not supply `ApplicationName` or `ApplicationVersion` to `D_pyLandingPageComponentsByType` — ignore those parameters. Make one call per selected page, even when two pages resolve to the same data source. Discard malformed entries (anything that is not a plain component-name identifier) from each response, then union the results across all selected pages and drop duplicates. Keep a note of which page(s) contributed each component — Step 0.5.5 reports it.
+
+### 0.5.4 — Cases (skip unless selected)
+
+Execute the data source **`D_pyPortalCaseTypes`** with `PortalName` set to the `pyPortalLayout` value recorded in Step 0.5.1. It returns the case types configured in that portal, in a `pxResults` array whose entries carry `pyClassName`.
+
+If `pxResults` is empty, tell the user this portal has no case types and, if Landing pages was not already selected, offer to fall back to it. If Landing pages was also not selected or also comes back empty, stop — there is nothing to generate.
+
+Present the returned case types as a **checkbox list** and let the user select one or more. This is a gate.
+
+For **each selected case type**, execute **`D_pyCaseViewComponentsByType`** with `CaseType` set to its `pyClassName`. Make one call per selected case type. Discard malformed entries from each response, then union the results across all selected case types and drop duplicates. Keep a note of which case type(s) contributed each component.
+
+### 0.5.5 — Merge, present, and ask which components to generate
+
+Union whatever Step 0.5.3 and Step 0.5.4 produced (only one ran unless the user chose Both) and drop duplicates across the two.
+
+Read `{{PROMPT_DIR}}/component-manifest.json` and use its `components` and `aliases` entries to group every resulting name under its type — `field`, `template`, `widget`, `designSystemExtension`, or `infra`. List any name that matches nothing in the manifest under **Unrecognized**, carried through exactly as the server returned it, rather than dropping it or guessing a canonical name for it.
+
+Present the grouped list — noting, for any component contributed by more than one page or case type, which ones — and ask which components to generate as a **checkbox list**, offering selecting all of them as an explicit option. Where a returned component is one the SDK provides and this prompt never generates — anything named in Step 8's never-generate list, or a structural wrapper such as `View`, `Region`, or `FlowContainer` — keep it visible in the list but mark it as not generatable and say why, so the user can see it's used without expecting a folder for it.
+
+⛔ **Wait for the user's answer.** This is a gate, not a notification. Nothing is read, installed, or written until the selection is confirmed.
+
+### 0.5.6 — Required additions
+
+Add the following to the confirmed selection whether or not the user picked it, and note the addition in the Step 9 summary:
+
+- **`FieldValueList`** — whenever the selection contains any field component. Every field renders its display-only mode through it, so the selected fields will not render correctly without it.
 
-Once design system, base folder, and type scope are resolved, continue to Step 1.
+Layout sub-variants are not part of the selection at all — Step 5.2.1 derives them from whichever layout templates were selected, and the user never has to ask for them.
+
+`ActionButtons`, `Stages`, and `MultiStep` are **not** added automatically. In a portal, that chrome is generated only when the user selects it.
+
+### 0.5.7 — Derive the generation set
+
+Intersect the confirmed selection with the type scope from Step 0, group the result by type, and record it as **the generation set**. It governs the rest of this prompt:
+
+- Steps 1 and 2 read skills and discover design system components for the types present in the generation set.
+- Step 3 checks for existing files only within the generation set.
+- Steps 4–8 each generate only the components of their type that are in the generation set, and are skipped entirely when it holds none of their type.
+
+Generate nothing outside the generation set. Do not add components based on assumptions about what a portal might need.
 
 ---
 
-## Step 1 — Read general skill files (once, for each type in scope)
+## Step 1 — Read general skill files (once, for each type in the generation set)
 
-Read the general skill file for every type in scope. Do this upfront — do not re-read per component.
+Read the general skill file for every type present in the generation set. Do this upfront — do not re-read per component.
 
 | Type                  | Skill file to read                         |
 | --------------------- | ------------------------------------------ |
@@ -58,6 +158,7 @@ Read the general skill file for every type in scope. Do this upfront — do not
 | template              | `{{SKILL_DIR}}/template-components.md`     |
 | widget                | `{{SKILL_DIR}}/widget-components.md`       |
 | designSystemExtension | `{{SKILL_DIR}}/design-system-extension.md` |
+| infra                 | `{{SKILL_DIR}}/infra-components.md`        |
 
 Keep all loaded skill files active throughout the entire session.
 
@@ -69,6 +170,8 @@ Check the project's dependency manifest to determine whether the design system p
 
 **Immediately after installation**, read `node_modules/<designSystem>/README.md` in full. From it, note the correct import paths, usage patterns, version-specific guidance, global CSS/styles import path, provider wrapper component name, and any peer dependency requirements. Store this information in your memory and use it for all subsequent steps — do not re-read the README later. If the README lists peer dependencies that are not already installed in the project, install them now — the design system will not function correctly without them.
 
+**Discovery runs whether or not you had to install anything**, and the package may not sit under the project's own `node_modules/` — in a workspace or monorepo it is commonly hoisted to a parent `node_modules/`. Walk up the directory tree to find it rather than concluding it is missing, and take everything from the type definitions if the package ships no README.
+
 You MUST also thoroughly inspect the installed design system package:
 
 1. **Discover all available components** — browse the installed package's directory tree under `node_modules/<designSystem>/` to find every component it exports. Do not assume a specific folder structure (e.g. `dist/`) — packages vary widely in how they organize source, types, and entry points. Navigate through the package's folders, read its entry-point files and type definitions, and build a complete list of every component the package actually provides. Store all discovered component names and their import paths in your memory for reference during code generation.
@@ -115,7 +218,7 @@ Keep all DS discovery information active throughout the entire session. Referenc
 
 ## Step 3 — Overwrite check (all types, all at once)
 
-For every type in scope, check whether each component's file or directory already exists at the derived output path.
+For every component in the generation set, check whether its file or directory already exists at the derived output path for its type. Components outside the generation set are not checked — they are not being generated.
 
 Collect all existing components across all types and report them in one consolidated list:
 
@@ -127,13 +230,13 @@ Collect all existing components across all types and report them in one consolid
 
 Wait for the user's answer before proceeding. If none exist, continue immediately.
 
-⚠️ **This decision is final for the entire session.** Do NOT re-check file existence or re-ask this overwrite question during Steps 4–7. When you encounter a component file that already exists during generation, silently apply the decision made here (overwrite it or skip it) without prompting again. This applies even after retries, transport errors, or subagent restarts — the user's answer here governs all subsequent component generation in this conversation.
+⚠️ **This decision is final for the entire session.** Do NOT re-check file existence or re-ask this overwrite question during Steps 4–8. When you encounter a component file that already exists during generation, silently apply the decision made here (overwrite it or skip it) without prompting again. This applies even after retries, transport errors, or subagent restarts — the user's answer here governs all subsequent component generation in this conversation.
 
 ---
 
-## Step 4 — Generate field components (skip if field not in scope)
+## Step 4 — Generate field components (skip if the generation set holds no field component)
 
-If `field` is in scope, generate each of the 27 field components in order:
+Generate each field component in the generation set, in order:
 
 **For each field component:**
 
@@ -182,9 +285,9 @@ After each component: "`<ComponentName>` ✓ — using `<DS component name>`"
 
 ---
 
-## Step 5 — Generate template components (skip if template not in scope)
+## Step 5 — Generate template components (skip if the generation set holds no template component)
 
-If `template` is in scope, generate each of the 32 template components in order:
+Generate each template component in the generation set, in order:
 
 **For each template component:**
 
@@ -229,6 +332,8 @@ After generating **TwoColumn**, **OneColumn**, **NarrowWide**, or **WideNarrow**
 
 Each sub-variant is a one-line passthrough that delegates to the base component via the project's component registry. It retrieves the base component (e.g. `TwoColumn`) from the registry and renders it with all props forwarded. Follow the same file extension and module pattern used by the rest of the project.
 
+Sub-variants are not part of the generation set and never appear in the Step 0.5 selection — they are derived here from whichever of these four layouts was selected. Create them even though the user did not ask for them by name.
+
 ### 5.3 — Register the component
 
 Open the project's component map file and:
@@ -243,9 +348,9 @@ After each component: "`<ComponentName>` ✓ — `<Layout | Form | Page>` templa
 
 ---
 
-## Step 6 — Generate widget components (skip if widget not in scope)
+## Step 6 — Generate widget components (skip if the generation set holds no widget component)
 
-If `widget` is in scope, generate each of the 9 widget components in order:
+Generate each widget component in the generation set, in order:
 
 **For each widget component:**
 
@@ -292,9 +397,9 @@ After each component: "`<ComponentName>` ✓ — using `<DS card/list primitive>
 
 ---
 
-## Step 7 — Generate design system extension components (skip if DSE not in scope)
+## Step 7 — Generate design system extension components (skip if the generation set holds no DSE component)
 
-If `designSystemExtension` is in scope, generate each of the 11 DSE components in order:
+Generate each design system extension component in the generation set, in order:
 
 **For each DSE component:**
 
@@ -337,11 +442,80 @@ After each component: "`<ComponentName>` ✓ — Pattern `<B/A/C>`"
 
 ---
 
-## Step 8 — Verify the build
+## Step 8 — Generate infrastructure components (skip if the generation set holds no infra component)
+
+Infrastructure components are the chrome the runtime draws _around_ a case or an assignment. Most of them ship from the SDK adapter package. **Exactly three are overridable, and this list never grows:**
+
+| Component     | Pattern             |
+| ------------- | ------------------- |
+| ActionButtons | Display-only chrome |
+| Stages        | Case-aware chrome   |
+| MultiStep     | Container chrome    |
+
+⛔ **Never generate** `NavBar`, `DeferLoad`, `VerticalTabs`, `DashboardFilter`, or any other infrastructure component. They are structural plumbing tied to the SDK's own internals. This holds even when the portal reports one of them in Step 0.5 and the user selects it — skip it and say why.
+
+Generate each infra component in the generation set that is one of the three overridable components above, in order:
+
+**For each infra component:**
+
+### 8.1 — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `{{SKILL_DIR}}/infra-skills/<ComponentName>.md` using your file reading tool. This step is **required** for every component — do not rely solely on the general `infra-components.md`.
+
+After reading, extract and keep active:
+
+- **Pattern classification** — display-only chrome | case-aware chrome | container chrome
+- **Input contract** — the exact inputs the runtime supplies, and whether the PConnect accessor is among them
+- **Behavioral Contract** — derivation logic, callback signatures, state flags, fallback rules, edge cases
+- **Design System Mapping** table — the recommended DS primitive for this chrome pattern
+
+⚠️ The general skill provides the pattern skeletons. The component-specific skill provides the **exact input names, callback signatures, and derivation rules**. Both are needed.
+
+### 8.2 — Generate the component files
+
+Create the directory `<base>/infra/<ComponentName>/`.
+
+Create the component's main implementation file using the file naming convention and extension appropriate to the project's framework.
+
+Follow the implementation structure described in `infra-components.md` (loaded in Step 1) for the component's pattern classification. Use the DS primitives you identified in Step 2 for the rendered markup.
+
+Generating an infra component produces an **override** of a component the SDK already supplies, so the contract is not yours to design — only the markup and the styling are:
+
+- Do not reshape the input contract. Keep every input name and callback signature exactly as the runtime uses them.
+- `ActionButtons` receives plain display props — do not give it a PConnect accessor.
+- Localize every label through the Pega locale utilities or the localization service. Values arriving in the inputs are keys, not display text. If a skill file documents no locale source for a particular label, follow the skill file — that label arrives already localized.
+- Resolve Pega sub-components through the project's component registry, never by direct import.
+- Derive the display model from the runtime's raw inputs first, then render it.
+- Where a skill file names an SDK styling helper or a derived flag that only exists to feed one — spacing classes, connector lines, last-item detection — and the DS primitive already handles it, drop it and use the primitive. Keep only what still carries meaning (state derivation, filtering, ordering), and report what you dropped.
+
+If the project uses barrel/re-export files, create one in the same directory. Create a CSS file only if the skill file requires one for the implementation path you actually chose.
+
+### 8.3 — Register the component
+
+Open the project's component map file and apply the case that matches what you find there. An infra component is normally **absent from the output folder while still registered** — the SDK supplies every infrastructure component, so check the map before assuming the name is free.
+
+**Case 1 — not registered by name** (no entry at all, or it resolves only through the SDK's built-in component spread):
+
+1. Add an import at the top in the **Infra** section — create that section if it does not exist yet
+2. Add an entry in the component map object under the infra comment
+
+**Case 2 — already registered by name, imported from the SDK adapter package**: do NOT add a second import under the same name — that is a duplicate binding and will not compile. **Rebind the existing entry** instead: remove only this component's name from the SDK import, add an import for your generated implementation, and leave the existing map entry in place.
+
+⛔ **Ordering is load-bearing for this category.** An infra entry MUST be listed **after** the SDK's built-in component spread. Listed before it, the spread replaces it and the override silently does nothing.
+
+### 8.4 — Report progress
+
+After each component: "`<ComponentName>` ✓ — `<display-only | case-aware | container>` chrome"
+
+---
+
+## Step 9 — Verify the build
 
 Run the project's build process to confirm everything compiles without errors. Fix any TypeScript or build errors before reporting completion.
 
-### 8.1 — Validate component map key names
+⚠️ **A passing build is not a passing type-check.** Many bundlers strip types without checking them, so a build can report success while generated components contain real type errors. If the project has a separate type-check step, run it too — and if it has none, invoke the type checker directly. Only errors in the files you created or edited are yours to fix; report any pre-existing errors elsewhere rather than fixing them.
+
+### 9.1 — Validate component map key names
 
 After a clean build, verify these key name exceptions in the component map:
 
@@ -349,10 +523,19 @@ After a clean build, verify these key name exceptions in the component map:
 - [ ] `URL: URLComponent` (not `URLComponent,`)
 - [ ] `Todo: ToDo` (not `ToDo,`)
 
-These are cases where the Pega engine sends a component name that differs from the JavaScript variable name. If any are registered using shorthand (e.g., `ToDo,`), fix them to use explicit key mapping (e.g., `Todo: ToDo,`).
+These are cases where the Pega engine sends a component name that differs from the JavaScript variable name. If any are registered using shorthand (e.g., `ToDo,`), fix them to use explicit key mapping (e.g., `Todo: ToDo,`). Verify only the keys whose components are in the generation set.
+
+### 9.2 — Validate infra registration (skip if the generation set holds no infra component)
+
+- [ ] Only `ActionButtons`, `Stages`, and `MultiStep` were generated — no other infrastructure component has a folder, or a registry entry pointing at generated code
+- [ ] Every infra entry appears **after** the SDK's built-in component spread
+- [ ] The SDK's built-in component spread is still present, and every registration that resolves through it or through the SDK adapter package is untouched
 
 Report a final summary:
 
+- The portal resolved in Step 0.5.1, the scope chosen in Step 0.5.2 (Landing pages / Cases / Both), and which pages and/or case types were selected
+- How many components the server returned in total versus how many were selected to generate
 - Total components generated, grouped by type
+- `FieldValueList`, if it was added automatically under Step 0.5.6
 - All entries added to the component map
-- Any components skipped (if "skip existing" was chosen in Step 3)
+- Any components skipped (if "skip existing" was chosen in Step 3, or because they are SDK-provided infrastructure)

package/templates/react-sdk-reference/.ai-common/prompts/generate-infra-components.md

@@ -0,0 +1,222 @@
+---
+ai-description: Generate all (or a subset of) infrastructure (chrome) components using any design system
+---
+
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output base path** — the folder where infrastructure components should be generated (e.g. `src/components/infra/`)
+- **Component list** — which components to generate (default: all 3 listed below)
+
+Both **design system** and **output base path** are required. If either is missing or ambiguous, you MUST stop and ask the user before proceeding. Do not infer any value from the project structure, `{{AI_FILE_EXT}}` files, existing folders, or any other source.
+
+⛔ **STOP** — If the user's message does not explicitly state BOTH the design system AND the output path, ask for the missing items now. Do not proceed to Step 1 until you have explicit answers from the user for all required inputs.
+
+Example questions (ask only the ones that are actually missing):
+
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. Where should the infrastructure components be generated? (e.g. `src/components/infra/`)
+
+If the user specified a subset (e.g., "just ActionButtons and Stages"), restrict the list accordingly.
+
+### Full component list (default — 3 infra components)
+
+Infrastructure components are the chrome the Pega runtime draws _around_ a case or an assignment. Most of them ship from the SDK adapter package. **Only these three are overridable, and this list never grows:**
+
+| Component     | Role                                                 | Pattern             | DS needed? |
+| ------------- | ---------------------------------------------------- | ------------------- | ---------- |
+| ActionButtons | The Cancel / Save / Submit row beneath an assignment | Display-only chrome | Yes        |
+| Stages        | The case stage progress indicator                    | Case-aware chrome   | Yes        |
+| MultiStep     | Step navigation within a multi-step assignment       | Container chrome    | Yes        |
+
+⛔ **Never generate these** — they are structural plumbing tied to the SDK's own internals and are always sourced from the SDK adapter package:
+
+| Component       | Role                         |
+| --------------- | ---------------------------- |
+| NavBar          | Portal navigation shell      |
+| DeferLoad       | Deferred content loader      |
+| VerticalTabs    | Case view tab rail           |
+| DashboardFilter | Dashboard filtering controls |
+
+If the user names one of them — or any other infrastructure component not in the table of three — skip it, tell them it is SDK-provided and not generated, and continue with the rest of the list. Do not create a skill file, a folder, or a registry entry for it.
+
+Once both inputs are known, continue to Step 1.
+
+---
+
+## Step 1 — Read `infra-components.md` (once, for the entire session)
+
+Read the full contents of `{{SKILL_DIR}}/infra-components.md`.
+
+This gives you:
+
+- The three implementation patterns (display-only chrome, case-aware chrome, container chrome)
+- The input contract for each of the three components — they do **not** share one
+- Localization rules, sub-component resolution rules, and the registration ordering rule
+- The Design System Adaptation section — chrome primitive mapping and DS discovery guidance
+
+Keep this context active throughout the entire generation session. Do not re-read it per component.
+
+> Infrastructure components differ from every other category in one important way: **they already exist**. Generating one produces an override of the SDK's implementation. The runtime keeps calling it with the contract it already uses, so the contract is not yours to design — only the markup and the styling are.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+Check the project's dependency manifest to determine whether the design system package is already installed. If it is **not** listed in the project's dependencies, install it using the project's package manager. Report what was installed, or report that it was already present. If installing is not possible — no network, a locked or offline environment, a package manager that refuses — stop and report exactly that. Do not carry on and generate components against a design system you could not inspect.
+
+**Discovery runs either way.** Whether you just installed the package or found it already listed, you MUST complete the rest of this step before generating anything. An already-installed design system is the normal case for this category, and it is never a reason to skip discovery.
+
+**Locate the installed package on disk.** It is usually under the project's own `node_modules/<designSystem>/`, but in a workspace or monorepo it is commonly hoisted to a parent `node_modules/`. If it is not under the project directory, walk up the directory tree until you find it. Not finding it immediately does **not** mean it is missing — never conclude the package is uninstalled, and never attempt a second install, before you have checked the parent `node_modules` directories.
+
+Read the package's `README.md` in full if it has one. From it, note the correct import paths, usage patterns, version-specific guidance, global CSS/styles import path, provider wrapper component name, and any peer dependency requirements. Store this information in your memory and use it for all subsequent steps — do not re-read the README later. If the README lists peer dependencies that are not already installed in the project, install them now — the design system will not function correctly without them. **Many packages ship no README at all** — if there is none, skip straight to the inspection steps below and take everything from the type definitions instead.
+
+You MUST also thoroughly inspect the installed design system package, focusing on chrome primitives (Button, Button group, Toolbar, Divider, Stepper, Steps, Breadcrumbs, List):
+
+1. **Discover all available chrome primitives** — browse the installed package's directory tree to find every component it exports. Do not assume a specific folder structure (e.g. `dist/`) — packages vary widely in how they organize source, types, and entry points. Navigate through the package's folders, read its entry-point files and type definitions, and build a complete list of every primitive the package actually provides. Store all discovered component names and their import paths in your memory for reference during code generation.
+2. **Map each infra component to the best available DS primitive** — the chrome patterns described in the skill files may not have an exact name match in the installed design system. Using the complete list you just discovered, identify which DS primitive best serves the same purpose (e.g. a stepper or breadcrumb primitive for stage progression). If no single DS component is a close match, compose the requested behavior from multiple available DS primitives. Never fabricate a component import that does not exist in the installed package.
+3. **Read the props interface of every primitive you plan to use** — for each component you intend to use, locate and read its TypeScript type definitions (`.d.ts` files or inline types) to understand the exact prop names, types, required vs. optional status, and any relevant enums or union types. Pay special attention to **emphasis/variant prop names** (primary vs. secondary actions) and to **step state conventions** (completed / active / pending). Store this information in your memory alongside the component names.
+4. **Use ONLY confirmed component names and prop names** — when generating code, you must exclusively use the component names and prop names you discovered from the installed package. Do not rely on training knowledge of the design system's API, as it may be outdated, inaccurate, or refer to components/props that do not exist in the installed version.
+
+Also check:
+
+- Whether the design system has a **companion icon package** — read its exports before using any icon name; never guess icon names. Decorative icons must be hidden from assistive technology.
+- Whether it has **size/emphasis/variant conventions** — use built-in props rather than custom padding
+- Whether it has a **tokens or CSS directory** — use design system CSS custom properties for spacing; never hardcode `px` values
+
+### 2.1 — Install the DS styles package and configure global CSS (MANDATORY)
+
+Design systems require their global stylesheet — without it, components render unstyled.
+
+#### Known DS style requirements (examples — verify against the package you inspected):
+
+| Design System | Styles Package (example) | CSS Import (example)                     | Provider Wrapper (example) |
+| ------------- | ------------------------ | ---------------------------------------- | -------------------------- |
+| Carbon        | `@carbon/styles`         | `import '@carbon/react/css/styles.css';` | `<Theme>`                  |
+| Ant Design    | (included)               | `import 'antd/dist/reset.css';`          | `<ConfigProvider>`         |
+| Radix Themes  | `@radix-ui/themes`       | `import '@radix-ui/themes/styles.css';`  | `<Theme>`                  |
+| Chakra UI     | (included)               | (none — runtime)                         | `<ChakraProvider>`         |
+| Shadcn/ui     | (Tailwind)               | `import './globals.css';`                | None                       |
+| MUI           | (included)               | (none — CSS-in-JS)                       | `<ThemeProvider>`          |
+
+Above mentioned are **examples** based on common versions. Use the import path and provider name you noted while inspecting the package — they take precedence over this table.
+
+If in table and not already configured: install styles package (if separate), add the global CSS import as the **first import** in the application's entry file, and add the Provider wrapper in the application's providers file.
+If not in table: browse the installed design system's folder for a `styles/` or `dist/` directory containing CSS files, and use what you find there.
+
+Before implementing any component, verify whether design-system-specific styles are already configured in the existing codebase — check the application's entry file for a matching CSS import. If the styles are already imported and configured, skip this step and report "already configured".
+
+Report what was installed/configured (or "already configured").
+
+Keep all DS discovery information active throughout the entire session. Reference it whenever generating a component — do NOT re-run discovery per component.
+
+---
+
+## Step 3 — Existing-implementation check (all at once)
+
+For each component in the list, check **both** of the following — an infra component can already be live in the running application without having a single file in the output folder:
+
+1. **The output path** — does `<outputPath>/<ComponentName>/` already exist?
+2. **The component map** — open the project's component map file and check whether the component's Pega name is **already registered**. It usually is: the SDK contributes every infrastructure component, and the project may additionally import it by name from the SDK adapter package and list it explicitly.
+
+> Unlike every other category, an infrastructure component is normally **absent from the output folder** while still rendering at runtime — the SDK supplies it. An empty output folder is expected and is not a reason to stop. It is also **not** evidence that the component is unregistered. Record, per component, whether an existing registration was found and where its import comes from — Step 4c needs this.
+
+If a component already has **files at the output path**, report them all at once and ask:
+
+> "The following N components already exist: [list]. How should I proceed?
+>
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+An existing **registration** alone is not an overwrite — do not ask about it. It is expected, and Step 4c tells you how to rebind it.
+
+---
+
+## Step 4 — Generate each component (loop)
+
+For each component in the resolved list (in the order listed in Step 0):
+
+### 4a — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `{{SKILL_DIR}}/infra-skills/<ComponentName>.md` using your file reading tool. This step is **required** for every component — do not rely solely on the general `infra-components.md`.
+
+After reading, extract and keep active:
+
+- **Pattern classification** — display-only chrome / case-aware chrome / container chrome
+- **Input contract** — the exact inputs the runtime supplies, and whether the PConnect accessor is among them
+- **Behavioral Contract** — derivation logic, callback signatures, state flags, fallback rules, edge cases
+- **Design System Mapping** table — the recommended DS primitive for this component's chrome pattern
+
+⚠️ The general skill file (`infra-components.md`) provides the pattern skeletons. The component-specific skill file provides the **exact input names, callback signatures, and derivation rules**. Both are needed — generating from only the general skill will produce chrome that renders but does not receive or forward what the runtime expects.
+
+A skill file may describe SDK styling helpers or derived flags that only exist to hand-build structure a design system primitive renders for you. Read Step 4b's rule on those **before** you start writing — it decides which of them survive.
+
+### 4b — Generate the component files
+
+Create the directory `<outputPath>/<ComponentName>/`.
+
+Create the component's main implementation file using the file naming convention and extension appropriate to the project's framework (determine this by examining existing components in the project).
+
+Follow the implementation structure described in `infra-components.md` (loaded in Step 1) for the component's pattern classification, as identified in Step 4a. Use the DS primitives you identified in Step 2 for the rendered markup.
+
+Apply the Behavioral Contract from the component skill file exactly. In particular:
+
+- **Do not reshape the input contract.** The runtime decides it. Keep every input name and every callback signature exactly as the SDK component being replaced uses them.
+- **Not every chrome component receives the PConnect accessor.** `ActionButtons` is handed plain display props and must not reach the runtime for its own data. Do not add an accessor to it.
+- **Localize every label.** Values arriving in the inputs are keys, not display text — resolve them through the Pega locale utilities or the localization service, as the component's skill file specifies. Never render a raw input string as a label and never hardcode label text. If a skill file documents no locale source for a particular label, follow the skill file — that label arrives already localized, and running it through a locale lookup a second time will blank it out.
+- **Resolve Pega sub-components through the project's component registry**, never by direct import — a direct import pins the sub-component to the SDK's version and silently discards any override.
+- **Derive before rendering.** Compute the display model from the runtime's raw inputs first, then render it. This is what keeps the component portable across design systems.
+- **Keep repeated elements stable.** Every item in a rendered collection needs a stable identity.
+- Treat every array input as optional and default it to empty.
+
+**When a skill file names an SDK styling helper — or a derived flag that exists only to feed one — that the DS primitive already handles for you**, prefer the DS primitive and drop it. Some of these exist only to hand-build structure the SDK renders itself — spacing classes, connector lines, last-item detection. A DS stepper, breadcrumb or list that owns its own connectors and item states makes them unreachable, and the class names they return refer to SDK stylesheets you are no longer using. Keep only what still carries meaning (state derivation, filtering, ordering), state in your progress report which ones you dropped and why, and never hand-roll raw markup purely to keep one alive — that defeats the point of adopting the design system. This rule overrides the skill file's wording where the two conflict; nothing else in the skill file's Behavioral Contract is negotiable.
+
+If the project uses barrel/re-export files (check existing component directories for the convention), create one in the same directory following the same pattern. Create a CSS file only if the skill file requires one **for the implementation path you actually chose** — skill files commonly document a CSS-only fallback that does not apply once you are rendering with design system primitives.
+
+### 4c — Register the component
+
+Open the project's component map file (the file that maps component names to their implementations) and apply the case that matches what Step 3 recorded for this component.
+
+**Case 1 — the component is not registered by name.** Either the map has no entry for it at all, or it resolves only through the SDK's built-in component spread. Both are the same job:
+
+1. Add an import at the top of the file in the **Infra** section — create that section if it does not exist yet
+2. Add an entry in the component map object under the infra comment
+
+**Case 2 — the component is already registered by name, imported from the SDK adapter package.** Do **not** add a second import under the same name — that is a duplicate binding and will not compile. Instead **rebind the existing entry**:
+
+1. Remove only this component's name from the SDK import — leave every other name in that import untouched
+2. Add a new import for your generated implementation
+3. Leave the existing map entry in place; it now resolves to your implementation
+
+Rebinding an existing entry is the one restructuring this step permits, and only for the components you are generating. Do not reorder or restructure any other existing entries.
+
+⛔ **Ordering is load-bearing for this category.** An infra entry is an override of a component the SDK already contributes, so it MUST be listed **after** the SDK's built-in component spread. Listed before it, the spread replaces it and the override silently does nothing.
+
+Never remove the SDK's built-in component spread — it supplies the infrastructure components that are not overridable, and removing it breaks rendering entirely.
+
+### 4d — Report progress
+
+After each component: "`<ComponentName>` ✓ — `<display-only | case-aware | container>` chrome, using `<DS primitive>`"
+
+---
+
+## Step 5 — Verify the build
+
+Run the project's build process to confirm everything compiles without errors.
+
+⚠️ **A passing build is not a passing type-check.** Many bundlers strip types without checking them, so a build can report success while your components contain real type errors. If the project has a separate type-check step, run it too — and if it has none, invoke the type checker directly. Only errors in the files you created or edited are yours to fix; report any pre-existing errors elsewhere rather than fixing them.
+
+Fix any errors in your own files before reporting completion.
+
+Before reporting success, confirm:
+
+- [ ] Only `ActionButtons`, `Stages`, and `MultiStep` were generated — no other infrastructure component has a folder, or a registry entry pointing at generated code
+- [ ] Every generated infra entry appears **after** the SDK's built-in component spread in the component map
+- [ ] The SDK's built-in component spread is still present, and every registration that resolves through it or through the SDK adapter package is untouched
+
+Report a summary: list of all files created, all entries added to the component map, and any components skipped because they are SDK-provided.

package/templates/react-sdk-reference/package.minimal.json

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@pega/auth": "file:pega-auth-0.2.42.tgz",
+    "@pega/auth": "file:pega-auth-0.2.44.tgz",
     "@pega/constellationjs": "file:pega-constellationjs-0.26.3-local.tgz",
     "@pega/sdk-react": "file:pega-sdk-react-0.1.0.tgz",
     "@pega/sdk-types": "file:pega-sdk-types-0.1.0.tgz",